# 14 — Agentic consumption

Recorded after the initial design survey. This document adds design pressures that
arise when **agents are the primary producers and consumers** of unimsg content. It
does not change the project's scope.

> **Scope note.** An earlier draft of this document reframed unimsg as "a substrate for
> a catalogue of rulesets" and proposed narrowing v0 accordingly. That was wrong.
> Universality is the aim; rules-as-data is a *consequence* of it. The corrected
> framing is below.

## The motivating observation

> Across many projects, the engine is largely the same — fairly generic at its core.
> What changes are the rules. And the rules end up in code, when they should be stored
> externally and merely referenced by code.

This generalises further than it first appears. A pluralisation engine, a tax
calculator, a routing planner, a validation layer, a scheduler: each is a small generic
evaluator wrapped around a large body of domain rules transcribed by hand into a
programming language — where it is unqueryable, unversionable, untestable in isolation,
and unusable by anyone else. The transcription then dies with the project.

**This is evidence for the universality requirement, not a redefinition of it.** Rules
about systems are one of the things "anything" must include. That they are currently
*not* capturable anywhere is a concrete demonstration that the gap
[00-motivation](00-motivation.md) describes is real, and that
[intensional representation](08-intensional-data.md) is one of the capabilities that
closes it.

Arabic pluralisation is an *instance*, not a target. It earns its place in these
documents as a demanding test case — it stresses precision-critical text, partial
knowledge, competing analyses, and generator-plus-residual structure simultaneously —
not because the format is being built for it.

## What exists, and why it is not enough

The narrow successes are worth knowing, because they show the idea works and where it
stops:

| System | Domain | Limit |
|---|---|---|
| **tzdata** | timezone rules | The canonical success — but single-domain, bespoke format |
| **CLDR / ICU** | locale data, plural *categories* | Gives `one`/`few`/`many`, nowhere near enough to *generate* forms |
| **Unicode UCD** | character properties | Machine-readable, versioned, authoritative, single-purpose |
| **UniMorph** | morphological paradigms | Extensional only — lists forms, not the rules generating them |
| **Grammatical Framework** | grammars | Rules genuinely as data, with an evaluator; siloed |
| **Wikidata, OSM** | facts, geography | Collaborative catalogues scale; weak on rules |

Each is siloed, format-incompatible, mostly extensional, not self-describing, and
assumes a human implementer reads documentation and writes a parser. Nothing composes.

## The consumer shift

> Most of the putting of information into this format will be done by AI agents, and
> most of the usage will be the same.

This is the substantive change in this document, and it applies to **all** unimsg
content, not to rulesets specifically.

### A1 — Discoverability

An agent must determine what a document covers, what it requires, and how complete it
is, without a human explaining. Elevates the
[self-describing header](03-data-model.md#self-description) and adds a requirement for
declared coverage and completeness.

### A2 — Self-tests

Documents that describe a system should carry worked examples: input → expected output.
An agent verifies it has understood by running them; a maintainer catches regressions;
a reviewer sees intent. Cheap, and probably the highest-value single addition.

### A3 — Machine-readable errors

Validation failures must be structured data, not prose, so an agent can act on them and
iterate. [H5](02-requirements.md) said a format is as friendly as its worst error
message; for agents the error must also be *typed*.

### A4 — Descriptors as generation grammars

Because descriptors are machine-readable structure, they can compile into a grammar
that constrains model decoding — so an agent *cannot* emit invalid unimsg. Free upside
from a decision already taken for other reasons.

### A5 — Partial consumption

Context windows are finite. An agent must load a *slice* of a large document rather
than the whole thing. Promotes the
[container and footer index](03-data-model.md#container-layer) from "deferred, low cost"
to genuinely important.

### A6 — Token economy

Verbosity costs money and context. Since agents consume the *text* form — models read
text, not CBOR — its token efficiency becomes a real design criterion that did not
exist when humans were the only readers.

### A7 — Provenance is representable, and that is all the format owes it

> **Scope correction.** An earlier draft of this section elevated provenance to "among
> the most important properties in the project" and treated verification depth,
> rubber-stamping, and sampling methodology as design drivers. That was overreach.
> Those are **academic integrity concerns for people using the format**, not concerns
> for people designing it. They should not shape the design.

What the format owes provenance is exactly what it owes rules, or geography, or
timestamps: the ability to represent it. Provenance is data. It is carried by ordinary
[annotations](03-data-model.md#annotations) over ordinary
[descriptors](03-data-model.md#tags-as-derivations-not-registrations), with no special
mechanism, no privileged position, and no policy encoded anywhere.

The one structural capability worth noting — **attestation over subtrees rather than
whole documents** — is already implied by content addressing plus a Merkle structure
([03](03-data-model.md#references-and-graphs)). It needs no new work and no new
requirement.

Whether a given community demands signed attestations, samples its data, or accepts
unverified model output is that community's policy. A format that tried to enforce it
would be both ineffective and bloated.

The material below is retained as an illustration of what a *user* of the format might
model, not as a specification requirement.

#### Illustrative: provenance as a chain of custody

**Agents are pathways, not authors.** The realistic picture is a human operator
directing agents as instruments:

> An Arabic grammarian knows the pluralisation system and documents it. He does not
> pull every reference himself — he uses an agent to aggregate sources, another to
> gather lexicons, another to fit them into a schema. He is overseeing and directing
> throughout; he is simply using the tools available.

This corrects an earlier framing here that treated agents as autonomous authors and
concluded "there is no ground truth." There *is* ground truth: it attaches to the
**operator**, not the instrument. Provenance is therefore not a human-or-model flag but
a chain of custody with distinct roles:

| Role | Question it answers |
|---|---|
| **Authority** | Who takes responsibility for this claim? (the grammarian) |
| **Instrument** | What did the mechanical work? (which agent, which model, when) |
| **Source** | What was aggregated or cited? |
| **Verification** | What checked it, by what method, covering how much? |

This is ordinary scholarly and archival practice. An academic paper's author is
responsible for its claims even though a research assistant gathered the references.
C2PA content credentials encode the same idea for media.

**The risk does not disappear — it changes shape.** The failure mode is no longer "no
human was involved" but "a human was involved *nominally*": the grammarian who accepts
15,000 aggregated entries without examining them. Rubber-stamping is the real hazard,
and it is invisible under a binary verified/unverified flag.

**So verification needs scope and method, not a boolean.** Distinguish:

- verified this specific claim,
- verified the *process* that produced a class of claims,
- sampled — "200 of 15,000 entries checked, sampling method X, error rate Y",
- merely initiated the work.

Sampled verification stated honestly is far more useful than a blanket flag, and it is
the only form that scales to agent-produced volume.

**Attestation must attach to subtrees, not whole documents.** An operator approves a
section, not a file. The content-addressed Merkle structure already in
[03](03-data-model.md#references-and-graphs) supports this directly: sign a subtree
hash, and the attestation stays valid as unrelated parts of the document change.

**This makes the human syntax a verification tool, not merely an authoring
convenience.** Review happens in the text form. Legibility is what makes oversight
possible at all — which reinforces [05](05-human-syntax.md) rather than competing with
it.

#### Illustrative: selection signals

Same status as A7 — a consumer concern, recorded because it shows the mechanisms are
sufficient, not because it imposes a requirement.

The consumption side has the mirror problem:

> Someone writing a pluralisation tool uses an agent to build it, and that agent selects
> a unimsg model containing the ruleset.

An agent choosing between competing documents needs more than "what does this cover".
It needs grounds for preferring one over another: declared coverage and completeness,
the authority chain from A7, verification depth, freshness, licence, and self-test
results (A2).

Note that none of this requires a central registry. Content-addressed documents carrying
signed attestations from named authorities give **decentralised** trust signals, which
is consistent with [D7](12-inherited-decisions.md#d7--tag-identifier-space-closes-rest-of-q9)
deferring governance rather than depending on it.

Whether that is sufficient in practice is unresolved, and belongs with the
[governance question](10-open-questions.md#the-largest-unexamined-risk).

## What does not change

**Human readability was never the wrong investment, and is now doubly justified.** For
LLM consumers a good human syntax *is* the best machine syntax — models are trained on
human-written text, so regularity, guessability and low ambiguity help both audiences
identically. The [recall test](05-human-syntax.md#testing-method) has a direct machine
analogue: can a model emit valid unimsg after one exposure? Same property, same fix.

**Determinism and content addressing** were right, and matter more: agents need stable,
verifiable references.

**The safety constraints** were right, and matter much more. "Never execute as a
consequence of reading" is a different proposition when most content is
model-generated.

**Scope is unchanged.** The format captures anything; rules are a subset of anything.

## Consequences

| Area | Change |
|---|---|
| Provenance | **No change.** Representable via existing annotations; policy is the user's (A7) |
| Attestation over subtrees | Already implied by content addressing + Merkle structure; no new work |
| Selection signals | **No change.** A consumer concern; existing mechanisms suffice |
| Self-tests | New element for documents describing systems (A2) |
| [Container layer](03-data-model.md#container-layer) | Promoted — partial consumption (A5) |
| Errors | Must be typed, not prose (A3) |
| Descriptor → grammar | New capability, free (A4) |
| [Human syntax](05-human-syntax.md) | Direction unchanged; add token efficiency (A6) |
| [Intensional data](08-intensional-data.md) | Argument strengthened, position unchanged — one important capability among several |
| Governance | Even more critical; the [largest unexamined risk](10-open-questions.md#the-largest-unexamined-risk) grows |

## Validating a universality claim

The corpus tests the substrate against serialisation edge cases. That proves unimsg is
a competent CBOR profile; it says little about whether it can carry *anything*.

A universality claim is validated by exercising **diverse and demanding** instances, not
by narrowing to one. A small set of worked examples, each stressing a different
requirement axis, would test the claim properly:

| Example | Stresses |
|---|---|
| Arabic broken plurals | precision-critical text, partial knowledge, competing analyses, generators + residuals |
| A financial ledger | exact decimals, signing over canonical bytes, immutability |
| A sensor stream | scale, streaming, partial consumption, indexing |
| A build derivation | behaviour as inert data, effects declaration, content addressing |

Four such examples cover most of [02-requirements](02-requirements.md) between them, and
none of them narrows the project's scope — which is precisely the point.