[siracozmen01]

Problem

maul-locale#334 (and its comments on #376 and the bound messages) asks how far a library checks state that a caller holds. The conventions say how a stale id is refused, but nothing for three other kinds of state:

• opaque state the library alone writes;
• a value struct with documented fields that a caller can copy;
• caller memory a call keeps "as checked".

The issue has waited for that ruling since 2026-10-31.

Change

maul/files/docs/internals/maul-conventions.md: one rule beside the root-object rule, covering each kind.

• Opaque state: checked by its cookie, and its ABI version where it records one, and by every index, slot and length being in bounds, so that no bit pattern makes a call read outside it. A forged one is outside the contract, and its internal consistency is not checked again.
• A value struct with documented fields that a call takes back from the caller: carries no raw pointer and size into the library's data. It names the object or data it came from plus an index, checked on each call, so that a copied field cannot reach memory outside what it names. A struct the library only fills in for the caller (a label it points at) may point into its data, and pointers to the caller's own memory, such as a text span, are not affected.
• Kept caller memory: stays unchanged as documented, and whatever it becomes, a later call reads only within the extents it recorded.

Verification

• This is documentation only. maul-locale applies the rule to #334, #376 and the bound messages, each in its own pull request with a test that fails on main.
• Each library meets the rule when it syncs to the tag. A value struct of another library that breaks it is a bug for that library, found in its next audit.

[siracozmen01]

Review at b90128f: changes needed (2). Both are wording; the three-part rule itself is sound.

1. The value-struct clause forbids outputs it should not. As written, "A value struct with documented fields, which a caller may copy and assign, carries no raw pointer and size into the library's data" covers every value struct, including ones the library only writes out and never reads back. maul-locale#334's own survey lists such outputs as fine: "Outputs pointing into validated data, which the library never reads back: mlocIndexBucket.label, mlocMessagePartInfo.name and mlocMessageParameter's name and value". The danger the clause guards against exists only when a call takes the struct back and reads through its fields, as with mlocTimeZone.zones. Each session audits against this rule, so the literal text would make every such getter's view into library data a bug to file. Please scope it, for example: "A value struct with documented fields that a call takes back from the caller carries no raw pointer and size into the library's data: ..." Optionally add: "a struct the library only writes out may point into its data, valid for as long as its documentation says."

2. "Stamp" already means something else in this file. The ABI rule (line 86) uses "stamp" for PP_ABI_VERSION in a root def: "each one carries the stamp", and "A library without a root def has no stamp". The new rule checks opaque state "by its stamp", so a library with no root def, or opaque state that is not a def, reads as having nothing to check by. Please name what is checked, in the file's existing terms: its cookie, and its ABI version where the state records one (a state format records its writer's PP_ABI_VERSION, line 142). Or define "stamp" here as the opaque state's own check word.

No contradiction with the root and id rules. The id rule covers objects a root owns; the new rule covers state the caller holds outside them. "Names the object or data it came from" is satisfied by a typed id for a root-owned object, which is still refused when stale, or by an opaque, checked object such as mlocData. The rule could say so ("by a typed id or by an opaque object checked as above") to close the loop, but this is optional. The opaque clause is also consistent with itself: bounds make every bit pattern memory-safe within the extents the state records, and a forged one gets no semantic checks, which matches "a forged one is outside the contract".

Structs that would break it (not blocking). Known: maul-locale's mlocTimeZone (zones, zonesSize), and through it mlocMessageOperand.zone and mlocMessageOptions.timeZone, per #334. I could not search the other libraries' headers from this session, so the rest is not verified. The test for each session's audit: a public struct with documented fields that a call takes back and reads through, holding a pointer into memory the library allocated or validated. Defs that point at the caller's own memory (shader bytes, mesh positions, text spans) are not affected.

Read, not run.

[siracozmen01]

Re-review at eaf35b1: ready. Both points are resolved in the rule.

1. The value-struct clause now applies to "a value struct with documented fields that a call takes back from the caller", and the new sentence "A struct the library only fills in for the caller, such as a label it points at, may point into its data" keeps the output views maul-locale#334 lists as fine (mlocIndexBucket.label, mlocMessagePartInfo.name, mlocMessageParameter).
2. Opaque state is now checked "by its cookie, and its ABI version where it records one", which uses the file's own terms and no longer collides with the root def's stamp (line 86) or reads as nothing to check in a library without a root def.

One leftover, not blocking: the body's Opaque state bullet still says "checked by its stamp". The body becomes the squash commit message, so you may want it to say "its cookie, and its ABI version where it records one" too. It does not affect the file.

Read, not run.