= DEED Grammar Specification :version: 0.3.1 :status: DRAFT :media-type: application/vnd.metadatastician.deed :toc: :toclevels: 3 [IMPORTANT] ==== *Status:* DRAFT, not ratified. Nothing in this document is deployed. v0.2.0 is a grammar-alignment revision (lexical rules, identity field table, normative-vs-informative grammar). It does not ratify the typing chapter. v0.2.8 applies owner ruling Q2 (2026-11-14): a `#u5` literal in an identity field is an error in every mode, and a `#u8` literal there is accepted (identity table, UUID5 row). v0.3.1 records owner ruling 2026-11-18: K-CUT-LOSS is proved upstream in a stated fragment, and the caution against resting the estate/repo projection relation on it is lifted (typing chapter, Choreographic). No grammar change. ==== Prepared 2026-09-08. Alignment revision: 0.2.0. This is the specification the owner asked for as top priority. It is deliberately scoped to the surface and its identity rule, because that is what unblocks the `.a2ml` → `.deed` conversion (#837) and the downstream consumers. The typing chapter (<>) is marked PROPOSED throughout and is *not* part of the v0.1 conformance surface. *Normative grammar:* link:./abnf/deed.abnf[abnf/deed.abnf] is normative for parsing. The EBNF in <> is informative. + NOTE (standards#837): owner ruling 2026-09-19 brought the grammar files together — `deed.abnf` (now v2.0.0) is the sole normative grammar. The v0.1.0 DRAFT archive lives at `archive/deed.abnf_v0.1.0-draft` under its true version (it was previously misnamed `deed.abnf_v1.0`). Compatible with: * link:./abnf/archive/deed.abnf_v0.1.0-draft[DEED ABNF v0.1.0 DRAFT (archived under its true version)] (as amended by the alignment errata) * link:../../../2-protocols/k9-coordination/spec/COORDINATION-K9-SPEC.adoc[K9 Coordination Spec] (separate surface; DEED does not parse `.k9`) == Changelog [cols="1,1,3"] |=== | Version | Date | Changes | 0.3.0 | 2026-11-14 | Aligned to `deed.abnf` v2.0.0 (A7 rulings S1 and J24; SysArch R-01): the `anchor-deed` head and the `ANCHOR.deed` file name are removed. The anchor is the `(anchor …)` clause of the chora deed (`clauses/anchor.abnf`). Not additive: a deed headed `anchor-deed` or named `ANCHOR.deed` no longer conforms. Every other v1.5.0 deed is a v2.0.0 deed. | 0.2.8 | 2026-11-14 | Owner ruling Q2 (A1 v0.4.5, standards#1553): a `#u5` literal in an identity field is an error in every mode, and a `#u8` literal there is accepted (identity table, UUID5 row). No grammar change. | 0.2.7 | 2026-11-13 | Aligned to `deed.abnf` v1.5.0 (A7 ruling J17; SysArch R-03): a field may end in the bang token `!`, after a separator, as in `(rule :id "adj-alt-text" !`. It marks a blocking rule (A7 8.4). A validator allows it only on the `:id` of a `(rule …)` clause at the top level of a `contractile-deed` and refuses it anywhere else. `!` could start nothing before, so every v1.4.0 deed is a v1.5.0 deed. | 0.2.6 | 2026-11-13 | Aligned to `deed.abnf` v1.4.0 (A7 ruling J14): three new heads, each chosen by an exact, case-sensitive file name. `file.deed` for the six verbs is a `contractile-deed`; the thirteen ALL-CAPS descriptile names, `CLADE.deed` among them, are `descriptile-deed`; `ANCHOR.deed` is an `anchor-deed`. Additive: every v1.3.0 deed is a v1.4.0 deed. | 0.2.5 | 2026-11-12 | Aligned to `deed.abnf` v1.3.0 (owner rulings U4 and I4): added the opaque `#uuid"…"` literal, which carries an id minted elsewhere instead of a preimage to hash (versions 5 and 8 only, variant 10, lowercase). A line is at most 998 octets, line-end excluded, so the 8bit encoding label of the deed media type is exact. Additive for every deed whose lines fit. | 0.2.4 | 2026-10-27 | Aligned to `deed.abnf` v1.2.1 (owner ruling 2026-10-27): a separator may open a list, so a multi-line list can start on the line after `(`, as the estate template writes them. The gate now enforces the rest of the grammar as written: no DEL or C0 control character in a string, comment or SPDX line, a line-end after every comment, and nothing between `'` and what it quotes. | 0.2.3 | 2026-10-16 | Aligned to `deed.abnf` v1.2.0: the exact canonical machine front door `0-AI-MANIFEST.deed` dispatches to `repo-deed`. Other filename rules and clause syntax are unchanged. | 0.2.2 | 2026-10-07 | Aligned to `deed.abnf` v1.1.0 (owner rulings D305/D320): added the `#u8"domain:name"` literal, ESTATE-UUID-V8 profile C. Additive — `#u5` stays legal until its own cutover. `:repo-uuid` takes UUID8 in the `gv-clade-index` domain. | 0.2.1 | 2026-10-06 | Aligned to `deed.abnf` v1.0.0 (owner ruling D308, ABNF wins): tabs INVALID, `_` legal in symbols, `:schema-version` exactly once in any position. Recorded the D305 `#u5` → UUIDv8 profile C transition as pending its own increment. | 0.2.0 | DRAFT | Declared ABNF normative / EBNF informative. Clarified `:schema-version` is a structural first field. Unified identity-field table (pending owner confirm). Documented case sensitivity, EOF, BOM, `(foo)` disambiguation, `*` in symbols, tabs-as-WS. Dropped undefined validator keywords or marked them. No typing-chapter changes. | 0.1.0 | 2026-09-08 | First draft. |=== == Why this document exists Three measured facts, 2026-09-08, motivate every decision below. *Fact 1 — the only runnable gate cannot read a deed.* `validate-a2ml.sh` recognises four identity forms and no more: ---- if [[ "$line" =~ ^[[:space:]]*(agent[-_]id|name|project|spec_id)[[:space:]]*= ]] \ || [[ "$line" =~ ^[[:space:]]*name[[:space:]]*: ]] \ || [[ "$line" =~ ^\[(metadata|scorecard)\] ]] \ || [[ "$line" =~ ^@abstract ]]; then has_identity=true ---- TOML `key =`, YAML `name:`, INI `[metadata]`, markup `@abstract`. A file written in the owner’s own deed form fails on both the leading parenthesis and the absent `=`. Measured under `INPUT_STRICT=true`: ---- ::error:: No identity found (agent-id/name/project/spec_id field, [metadata] or [scorecard] section, or @abstract directive) ::error:: Missing version or schema_version field rc=1 ---- *Fact 2 — `.deed` is invisible.* `grep -ci deed validate-a2ml.sh` returns 0 against 20 occurrences of `a2ml`. No tool in the estate scans a `.deed` file today. *Fact 3 — the identity primitive already exists, compiles, and is decidable.* `BaseVocab.idr` — which lives in the a2ml repository, not in this one — builds clean (11/11 modules, `%default total`) and its own header states its purpose: _"the anti-desync primitive: one neutral shape for a thing that can be identified, located, attributed, and integrity-checked. It names no downstream consumer."_ The gap is therefore not a missing grammar. It is that a typed, total, surface-neutral identity core exists in Idris2, and a weaker, rival identity rule exists in shell regex, and neither knows about `.deed`. This document closes that by defining the deed surface in terms of the typed core, and by specifying the single change the validator needs. == Scope and non-goals *In scope:* lexical structure, concrete syntax, the document forms, the identity rule, the conformance modes, and the validator obligation. *Not in scope for v0.1:* the `action-parsing-rules` / `on-encounter` sub-language of praxis deeds (owner has flagged the existing draft syntax as a strawman); the vocabulary content of any particular chora; the conversion campaign itself. == Lexical structure A deed is a sequence of UTF-8 bytes with *no leading BOM* (U+FEFF is INVALID). Parsers MUST be deterministic given identical input bytes. *Line length.* No line of a deed is longer than 998 octets, not counting the CR and LF that end it. A document with a longer line is not a conforming deed. The bound is the one RFC 5322 Section 2.1.1 sets, and it makes the `8bit` encoding label of the media type registration exact (link:../docs/iana/application-vnd.metadatastician.deed-registration.txt[registration draft]; owner ruling I4, 2026-11-12). `deed.abnf` v1.3.0 states the same constraint beside its `deed-file` rule (metadatastician/standards#1473). Keywords, document heads, booleans, UUID prefixes, filename dispatch literals, and string-escape letters are *case-sensitive*. `repo-deed` is valid; `REPO-DEED` is not. `#t` is valid; `#T` is not. This matches RFC 7405 `%s"..."` literals in link:./abnf/deed.abnf[deed.abnf]. [cols="1,3"] |=== | Token | Rule | COMMENT | `;` to end of line. `;;` is the convention for a whole-line comment and `;` for a trailing one. A comment *is* a token separator (see `Sep`). Comments are UTF-8, not ASCII — the mandated SPDX header carries `©`. | WS | space (0x20), LF, CRLF. Insignificant except as a token separator. Bare CR is not a separator. Tab (0x09) is INVALID anywhere in a deed, as in K9 (`deed.abnf` `token-sep`; D308). | SYMBOL | `[A-Za-z][A-Za-z0-9.*/<>=!?+_-]*` — first character a letter; continuation may include `*` and `_`. Dots are structural: `Type.Software.Library` is *one* symbol whose dotted segments are meaningful to the type resolver. Underscore is lexically valid (`deed.abnf` `symbol`; D308). Hyphen is the estate convention for vocabulary names; that is a lint matter, not a parse rule. | KEYWORD | `:` followed by a SYMBOL. Example: `:schema-version`. `:schema_version` parses, but it is a different keyword and does not satisfy the `:schema-version` requirement. | STRING | `"…"`, body is printable ASCII except `"` and `\` plus UTF-8 multibyte sequences. Exactly four escapes, case-sensitive: `\\`, `\"`, `\n`, `\t`. Empty string `""` is valid. `\r`, `\uXXXX`, and all other escapes are INVALID. Embed non-ASCII directly as UTF-8. | INTEGER | `-?[0-9]+`. Leading zeros are permitted (`007`) and MUST NOT be interpreted as octal. | BOOLEAN | `#t` or `#f` only, lowercase. Not `true`, not `yes`, not `#T`, not `#F`. Note: `true` and `yes` still match SYMBOL. A linter SHOULD warn if they appear in a position whose vocabulary expects a boolean. | UUID5 | `#u5` immediately followed by a STRING, with *no* intervening space: `#u5"estate/chora"`. The body is the name input to RFC 4122 §4.3 under the estate namespace. See <>. UUID v4 is intentionally excluded. *Transition:* owner ruling D305 folds `#u5` into ESTATE-UUID-V8 profile C (ADR-008, Q2). `deed.abnf` v1.1.0 adds UUID8 beside it; retiring `#u5` changes every existing deed identifier, so it is a separate cutover and `#u5` stays legal until then. In an identity field (CHORA-SPEC 7.1) the cutover has happened: owner ruling Q2 (2026-11-14) makes `#u5` there an error in every mode. See <>. | UUID8 | `#u8` immediately followed by a STRING, with *no* intervening space: `#u8"gv-clade-index:github.com/hyperpolymath/standards"`. The body is the ADR-008 profile C *preimage* `domain:name`; the identifier is bytes 0..15 of SHA-256(body) with version 8 and variant `10`. The domain (before the first `:`) MUST be non-empty printable ASCII; the name is unconstrained. `#u7` and every other `#`-form is a parse error (D305). | UUID | `#uuid` immediately followed by a STRING whose body is the identifier itself: `#uuid"b32d6be4-73ba-873e-9d61-e57f43c75cd1"`. The body is 8-4-4-4-12 *lowercase* hex, the version nibble is `5` or `8` and the variant nibble is `8`, `9`, `a` or `b` (variant `10`); anything else is a parse error, so UUID v4 stays excluded. Nothing is hashed. See <>. Added in `deed.abnf` v1.3.0 (owner ruling U4). | QUOTED | `'` followed directly by a SYMBOL or a list. Suppresses evaluation. Quoting an integer, string, or boolean is a parse error. | `( )` | The only bracket. No `[` or `{` forms exist in this grammar. |=== [NOTE] ==== The estate’s earlier markup dialect used square brackets. Those are not part of the deed grammar. A `[section]` header in a `.deed` file is a speciation artefact, not a deed. ==== == Concrete syntax The productions below are *informative EBNF*. If they disagree with link:./abnf/deed.abnf[abnf/deed.abnf], the ABNF wins. ---- Deed ::= Header Sep? Form Sep? EOF Header ::= SpdxLine+ ; see Required header Sep ::= ( WS | COMMENT )+ ; a COMMENT *is* a separator Form ::= "(" DocHead ( Sep ( Field | Clause ) )+ Sep? ")" ; exactly one ":schema-version" STRING field, any position DocHead ::= "estate-deed" | "repo-deed" | "estate-atlas-deed" | "praxis-deed" | "contractile-deed" | "descriptile-deed" ; exact, case-sensitive Field ::= KEYWORD Sep Value Value ::= STRING | SYMBOL | INTEGER | BOOLEAN | UUID5 | UUID8 | UUID | QUOTED | List List ::= "(" Sep? ( Value ( Sep Value )* )? Sep? ")" Clause ::= "(" SYMBOL ( Sep ( Field | Clause ) )* Sep? ")" ---- A Field is a keyword/value pair. A Clause is a named sub-form that may itself carry fields and nested clauses. This is the whole *syntax*; everything else in a deed is vocabulary, not syntax. *Exactly one* top-level `Form`. Trailing non-separator content after the closing `)` is a parse error. `EOF` is an implementation obligation (ABNF cannot name it); a conforming parser MUST consume the entire input. === List vs clause `(foo)` matches both `List` (one symbol) and `Clause` (head `foo`, no children). Disambiguate by *position*: * in a Value position → `List` * in a Field/Clause repetition (including the body of `Form`) → `Clause` `(foo bar)` is only a `List` (`bar` is neither Field nor Clause). `(foo :bar 1)` is only a `Clause` (`:bar` is a KEYWORD, and KEYWORD is not a Value). === Required header Every deed MUST begin with SPDX lines as `;;` comments, before the opening parenthesis: ---- ;; SPDX-FileCopyrightText: © 2026 Jonathan D.A. Jewell (hyperpolymath) ;; SPDX-License-Identifier: CC-BY-SA-4.0 ---- Each header line MUST match `;; SP "SPDX-" …`. At least one such line is required. `SPDX-License-Identifier` MUST appear in that header. The existing validator already requires `SPDX-License-Identifier` within the first 10 lines; that check carries over unchanged. Non-SPDX `;;` comments and blank lines MAY appear *after* the header and *before* the opening `(` (they are `Sep`). === Order is not semantic `:schema-version` MUST appear exactly once at the top level of the form, with a STRING value. Its position is free: `deed.abnf` folds it into `field`, and the validator counts it. Writing it first is the canonical style, not a parse rule. All fields and clauses are order-free and may interleave. The repetition is `( Sep ( Field | Clause ) )`, deliberately not `Field* Clause*`. A canonical ordering is a lint convention for diffability, never a parse rule. Where precedence genuinely matters — the rules inside a praxis deed — it is carried by an explicit `:priority` INTEGER, never by file position. Rationale, and this is the estate’s signature failure mode: with first-match-wins, a broad rule inserted above a narrow one silently shadows it. No error is raised; the narrow rule simply stops firing. With `:priority`, shadowing shows up in a diff as a number changing, and the file stays sortable, formattable and merge-safe. Lint obligations that follow: * `:priority` values MUST be unique within a single `rules` block. * A rule whose guard is implied by a lower-priority rule’s guard SHOULD warn. RULED 2026-09-08 by the owner on standards#752 — match the ABNF to this EBNF (`:schema-version` first; remaining members order-free). SUPERSEDED 2026-10-06 by owner ruling D308: `deed.abnf` v1.0.0 is authoritative, and it requires `:schema-version` exactly once in any position. == The document forms One extension, `.deed`. The form is selected by the filename stem, *before* parsing begins, not by a second extension. Dispatch literals are case-sensitive. [cols="1,1,2"] |=== | Filename | Head form | Meaning | `estate_chora.deed` (exact) | `estate-deed` | Noun. The estate’s vocabulary. One per estate. | `*_chora.deed` excluding `estate_chora.deed` | `repo-deed` | Noun. What a repo IS. A record. | `0-AI-MANIFEST.deed` (exact) | `repo-deed` | The canonical machine front door, recording repository routing and invariants. | `ATLAS.deed` (exact) | `estate-atlas-deed` | Noun. The registry of all deeds. | `*_praxis.deed` | `praxis-deed` | Verb. What a tool DOES. Rules. | `file.deed`, `` one of `Intent`, `Must`, `Trust`, `Adjust`, `Dust`, `Bust` (exact) | `contractile-deed` | How the repo must be: the verb's edicts (A7 J14). | `META.deed`, `STATE.deed`, `ECOSYSTEM.deed`, `AGENTIC.deed`, `NEUROSYM.deed`, `PLAYBOOK.deed`, `CLADE.deed`, and `INTENT.deed`, `MUST.deed`, `TRUST.deed`, `ADJUST.deed`, `DUST.deed`, `BUST.deed` (exact) | `descriptile-deed` | How the repo is: audited facts, and `CLADE.deed` its own content organisation, never identity (A7 J14, W10). |=== The stem is everything before the final suffix (`_chora.deed`, `_praxis.deed`, …). Do *not* split on `.` — stems may contain dots (`my.project_chora.deed` → stem `my.project`). Dispatch is exact-stem-first, and `*_chora.deed` *excludes* `estate_chora.deed`. The two patterns overlap: the literal string `estate_chora.deed` also matches the glob `*_chora.deed`, so a naive glob dispatches the estate vocabulary as a repo record. A conforming implementation MUST test the exact name `estate_chora.deed` BEFORE the `*_chora.deed` pattern, and MUST NOT parse `estate_chora.deed` as a `repo-deed`. Equivalently, the repo form is `_chora.deed` where `` is any non-empty stem other than the exact string `estate`. The exact `0-AI-MANIFEST.deed` name also selects `repo-deed`, and the J14 names select their heads. They are case-sensitive: the case is the rule (A7 YL4), so `mustfile.deed`, `MUSTFILE.deed`, `Meta.deed` and `anchor.deed` are invalid, as are other plain `.deed` names. [NOTE] ==== ABNF cannot express negation, so this exclusion is a side condition in both this document and `abnf/deed.abnf`. The side condition is normative: the grammar alone is not sufficient to dispatch a filename. ==== *Semantic constraint:* the `DocHead` inside the file MUST match the filename dispatch. `ATLAS.deed` containing `(repo-deed …)` is a validation error even if it parses. RULED 2026-09-08 by the owner on standards#752 — "yes, let’s adopt this, good idea, the chora replaces the clade of course." RULED 2026-09-08 by the owner: `praxis-deed` is a genuine fourth head, not a facet of `repo-deed`. A tool carries obligations a repo does not — what it invokes, what it emits, what it may refuse — and those are a distinct document form, so they get a distinct production rather than being smuggled in as optional fields on a record. [NOTE] ==== This is not the earlier `tool-praxis-deed`, which was another session’s coinage and was removed from this spec because it appeared in no owner text. The owner’s own three heads were `estate-deed`, `repo-deed` and `estate-atlas-deed`; `praxis-deed` is a deliberate addition ruled on 2026-09-08, and the name is two words, not three. ==== === `:schema-version` is required on every head RULED 2026-09-08 by the owner. The owner’s original text was not uniform: `estate-deed` carried `:schema-version`, `estate-atlas-deed` carried `:registry-version`, and `repo-deed` carried neither. The grammar normalises this: * `:schema-version` STRING is REQUIRED exactly once on every head (any position; first by convention). It versions the *format*, so a consumer can refuse a file it cannot parse. * `:registry-version` STRING remains available on `estate-atlas-deed` as an optional additional field. It versions the registry’s *contents*. ---- (estate-atlas-deed :schema-version "1.0.0" ; REQUIRED — the format, first field :registry-version "3" ; optional — the contents ...) ---- This is the field the current validator cannot see. Its regex is: ---- ^[[:space:]]*(version|schema_version)[[:space:]]*[=:] ---- That matches the underscore spelling with no leading colon, so `:schema-version "1.0.0"` FAILS and `schema_version = "1.0"` PASSES — directly tested. See <>. Rationale for a single extension: the grammar is identical and only the structure differs. An extension should track what parses a file, not what it means — `.rs` covers both a library and a binary. `find -name '*_chora.deed'` costs exactly what `find -name '*.chora'` costs, so a second extension buys nothing a stem glob does not already give, while doubling every discovery pattern across the estate during an in-flight `.a2ml` → `.deed` sweep. Two interleaved estate-wide sweeps is how this goes wrong. The existing validator already dispatches on basename, so stem dispatch is proven in current tooling. === The praxis-deed form A praxis deed states what a tool does. Three fields are required, and they follow from rules already established elsewhere in this document rather than from taste: ---- ;; SPDX-FileCopyrightText: © 2026 Jonathan D.A. Jewell (hyperpolymath) ;; SPDX-License-Identifier: CC-BY-SA-4.0 (praxis-deed :schema-version "1.0.0" ; REQUIRED — first field :canonical-name "cadastre" ; REQUIRED — identity :beholding-chora #uuid"" ; REQUIRED — one declaration site (rules (rule :priority 10 :when … :then …) (rule :priority 20 :when … :then …))) ---- `:beholding-chora` is required because of <>: a tool may not declare its own vocabulary, so it must name the chora it reads. A UUID, never a bare filename — a bare filename resolves against nothing. `:priority` is required on each rule because of order-independence: rule precedence is carried by an explicit integer, never by file position. [WARNING] ==== *Provisional for v0.1.* The owner ruled on 2026-09-08 that `praxis-deed` is a genuine fourth head. The owner did not rule on which fields beyond these three a praxis deed must carry — candidates such as `:invokes`, `:emits` and `:may-refuse` are not specified here, because inventing them is precisely the failure this document exists to stop. A tool deed conforms in v0.1 on the three fields above; anything further is a v0.2 question. ==== `estate-atlas-deed` is not folded into this form. The atlas is a registry — a noun, a record of what exists — and keeps its own head. A praxis deed is a verb. === One declaration site Vocabulary — types, tropes, lattices — is declared in `estate_chora.deed` and nowhere else. Every other deed references it. This is the owner’s ruling of 2026-09-04, verbatim: "it should be referrring to the chora". Both praxis deeds and repo choras name that vocabulary via `:beholding-chora `. The value is the estate chora's v8 id, written `#uuid"…"` or `#u8"domain:name"`, never a bare filename and never `#u5` (owner ruling Q2, 2026-11-14). This rule exists because the first draft declared its own parallel type universe in a tool deed, and the dependency then ran backwards: a lattice was declared in the tool and consumed by the chora, while every repo beheld the chora. Two universes with no precedence between them is not a layering problem, it is an ambiguity. [WARNING] ==== v0.1 draft used `:beholding-estate` for repos and `:beholding-chora` for praxis. Those cannot both stand without a written distinction. This revision uses `:beholding-chora` for *every* non-estate deed, because there is one declaration site and it is the chora. Owner: confirm or restore the split with definitions. ==== === The chora is not a layer ---- estate_chora.deed THE VOCABULARY (noun, estate-wide) types · tropes · lattice · universal invariants | | every layer below resolves its names here | +-------------+---------------------------------------+ | | v v TOOL PRAXIS DEEDS REPO CHORAS _praxis.deed *_chora.deed rules: guard -> action local facts, history, names | ^ | the cadastre reads every repo chora -->| | derives · validates · maps v EMISSIONS topoindex · veracity-ledger · attenuation-census | v OPERATIONAL TOOLS — read the MAPS; they do not re-parse repo choras ---- === UUID semantics — state the claim honestly `#u5"…"` is a UUIDv5: SHA-1 over a public namespace and a public name. `#u8"…"` is the same construction under ADR-008 profile C (SHA-256 over a public domain and name). Either way any cloner can recompute it correctly. It therefore cannot establish that a document is unfalsified, and no rule may claim that it does. What it does establish is real and worth checking: a clone that copied a deed verbatim without re-running repo initialisation will carry the parent’s UUID, which will not match its own name. That is lazy copy-paste, and this catches it. The check is named `enforce-uuid-provenance` for that reason and MUST NOT be named or described as an unfalsifiability guarantee. `#uuid"…"` is different in kind. It carries an identifier minted elsewhere, once, and does not record what it was derived from: a reader cannot recompute it from the deed. Owner ruling U4 (2026-11-12) puts repository identity in this form. A repository's id is minted once by the registry and never changes when the repository moves or is renamed, so a deed that wrote the path to hash would have to change on every move; the opaque literal does not. The birth path stays in the registry archive, which no route serves. `enforce-uuid-provenance` cannot apply to an opaque literal; the registry check that the id belongs to the repository takes its place. == Semantics: identity, and the self-assertion rule === Identity maps onto BaseRecord A deed’s identity is not a new invention. It is the already-typed `BaseVocab.BaseRecord`, whose required fields are `id`, `sourceSpan`, `hash` (`sha256:` + 64 lowercase hex), `provenance` (author, tool as `name@version`, kind ∈ `{human,ai,mechanical}`, optional agent), `timestamp` (RFC 3339 UTC) and `artefactRef`. `canonicalNode`, `agent` and `profileDecl` are optional and do not affect base validity. The *surface* keywords that carry that identity are the following. This table is the conformance list for v0.1 validators. (Mapping each column onto a `BaseRecord` field is the typed-core bridge, not a parse rule.) [cols="1,2,2"] |=== | Head | Required identity | Required reference | `estate-deed` | `:canonical-name` STRING, `:estate-uuid` UUID: the opaque `#uuid` v8 id (CHORA-SPEC 7.1, U4), or a `#u8` literal | `:beholding-chora` UUID, the same form | `repo-deed` | `:canonical-name` STRING, `:repo-uuid` UUID: the registry's `uuid_v8`, written opaque (owner ruling U4), or a `#u8` literal (domain `gv-clade-index` for ids minted before V9) | `:beholding-chora` UUID, the same form | `praxis-deed` | `:canonical-name` STRING | `:beholding-chora` UUID, the same form | `estate-atlas-deed` | `:canonical-name` STRING | `:beholding-chora` UUID, the same form; `:registry-version` STRING optional |=== Every UUID field in this table is an identity field (CHORA-SPEC 7.1 lists them, with the clause fields). Under owner ruling Q2 (2026-11-14) a `#u5` literal in an identity field is an error in every mode, `lax` included, and so is a version 5 inside `#uuid`. A `#u8` literal there is accepted, because it computes to a v8 id. `#u5` stays legal elsewhere. The legacy beholding value `#u5"estate/chora"` is therefore an error. `scripts/check-uuid-v8.sh` enforces this. Plus, on every head: `:schema-version` STRING, exactly once (any position). The head symbol itself is identifying: a file whose first form is one of the four declared heads is a deed of that kind, and a validator MAY treat the head as satisfying the *structural* half of identity. It does not excuse a missing `:canonical-name`. [WARNING] ==== Confirm this table. v0.1 §6.1 said `:estate-uuid / :repo-uuid` “on chora forms” without defining atlas/praxis. v0.1 §8.2 matched `:estate-authority` and `:agent-id`, which are *not* in this table and MUST NOT be accepted as identity until they are defined here. ==== === A self-declaration is an input, never a conclusion This is the load-bearing semantic rule of the whole format, and it generalises a specific defect found in the first draft. That draft had a repo declare `:p-falsifying #f :p-misbinding #f :p-conflating #f`, and had the enforcing rule read those same fields back to decide whether the repo was deceptive. A liar declares `#f`. The rule was vacuous — it could only ever confirm what it was told. The general rule: [NOTE] ==== A deed’s self-assertions are INPUTS to an audit. They are never its conclusions. Any derived judgement about a repo MUST be computed by an external observer from observed state, MUST be recorded in a distinct `:derived-state` position, and MUST carry a witness naming the deriving tool. A rule that reads a self-assertion and emits a judgement of the same proposition is ill-formed and MUST be rejected by the linter. ==== Consequently a repo states a *warrant* (see <> — the owner’s own term, replacing the coinage `veracity-claim`); it does not state a veracity state. The cadastre derives the state and emits a witness. A bare symbol that a repo writes about itself is not a witness. == Typechecking — PROPOSED, pending the typed core [IMPORTANT] ==== Everything in this section is PROPOSED. It is recorded so the design is not lost, not because it is settled. `TypedCore.idr` currently types the prose document model (sections, refs, figures) and has no record/deed node. Bridging it is real work, not a rename. *No new ABNF production is required by anything below.* ==== === What already exists and is total `BaseVocab` provides `baseValidB : BaseRecord → Bool`, the proposition `BaseValid r = baseValidB r = True`, a decision procedure `baseValidDec : (r : BaseRecord) → Dec (BaseValid r)`, and structured diagnostics `baseRecordIssues` enumerating errors first and the `AiMissingAgent` advisory last. This is the model to follow for every deed check: a decidable Boolean, a proposition, a decision procedure, and a structured issue list rather than a string. === Four type systems, measured against what the estate already proves The owner asked whether tropical, choreographic, echo or epistemic typing can be incorporated usefully into `.deed`, and if necessary into k9. These are not textbook theories to be imported: all four are mechanised in the owner’s own `_TYPES _SET/` repos. Each verdict below says which layer it touches — grammar, semantics, or k9 — because most of them touch no grammar at all. The honest summary: one changes a name, one is a k9 proposal, two are naming for shapes this spec already has. None requires a new production. ==== Epistemic — adopt the vocabulary, change nothing else `_TYPES _SET/epistemic-types` (Agda, MPL-2.0) builds a modality spectrum in which `FactiveModality` carries `reflect : E κ A → A` (knowledge implies truth) and `BeliefModality` intentionally omits `reflect`. That omission is <> stated formally: a repo’s declaration inhabits a non-factive modality, so no rule can extract truth from it. The distinction is proved structural, not asserted by a linter. It also already has the word this draft coined. The repo defines `Warrant κ A` as "the type of evidence tokens for A", explicitly recording "the type of evidence for a claim without assuming the evidence is valid", and separates "I have a receipt for A" from "A is true" — with `SoundWarrant` as a separate interface adding `evidence → A`, not assumed by default. *Ruling proposed:* withdraw the coinage `veracity-claim` from the open rulings and use *warrant* for a repo’s non-authoritative self-assertion, and *receipt* for a claim transported across a repo boundary. The owner already has the terms, mechanised, with the exact semantics this format needs. Coining a rival word would repeat the `tool-praxis-deed` error in vocabulary rather than syntax. *Layer:* semantics and naming. No grammar change. No new field. ==== Tropical — the only one that belongs in k9, and it has a consumer `_TYPES _SET/tropical-types` formalises the max-plus semiring over ℕ ∪ {-∞} in `Tropical.thy` (Isabelle 2025-1, `comm_semiring_1` proved through a seven-step typeclass chain, dioid proved separately), and `TropicalSessionTypes.lean` proves that a static tropical grade equals the dynamic wall-clock span, with a QTT refinement showing the tropical grade bounds sequential billing. The discriminator for "useful" is whether anything declares a budget today. Measured across both canonical trees: `timeout_seconds | Number | default = 300` occurs in 133 Nickel files across 63 repos — but those files carry only three basenames (`_base.ncl` ×68, `trust.ncl` ×60, `echidnabot.ncl` ×5), so this is one shared contractile-runner template stamped estate-wide, not 133 independent decisions. `_base.ncl` is the base imported by every verb runner and the field sits in its `run_defaults`. Alongside it, `timeout_honouring = 'strict` occurs in 48 files, and `'timeout` is one of nine declared failure classes (175 occurrences). That the template is shared is what makes this tractable: a per-step bound is already declared in one place for the whole estate. What does not exist anywhere is a rule for composing those bounds. A pipeline of six steps each bounded at 300s has no declared total, so a runner cannot say in advance whether the pipeline can finish inside its own bound. That composition rule is exactly the tropical semiring: sequential composition is ⊗ (addition of grades), a parallel or alternative fan-out is ⊕ (max of grades, giving the span). The Lean result is the soundness story — the statically computed grade is the wall-clock span. Note the direction of the claim when it is applied here: `timeout_seconds` declares a *bound*, not a measured duration, so the composed value bounds the pipeline’s span rather than equalling it. That is still enough for a runner to refuse a pipeline whose composed bound exceeds its own. *Ruling proposed:* this belongs in the Nickel runner layer, never in `.deed`. Be precise about where that is: of the 147 `.ncl` files declaring `timeout_seconds`, 141 sit in the contractile-runner layer — 133 of those under just three basenames (`_base.ncl`, `trust.ncl`, `echidnabot.ncl`), the other 8 miscellaneous — and 6 are k9 configs (`fleet-config.k9.ncl`, `mcp-server-config-schema.k9.ncl`). No `.k9` file declares it at all — 250 exist and none carry the field — so "k9 already has timeouts" is true of `*.k9.ncl` Nickel configs, not of the `.k9` surface (and not of `coordination.k9`). Propose a composed bound in the runner base alongside the existing per-step field, so a pipeline’s declared total is checkable against its parts. This is task #76 (the must/intend/trust/adjust/bust/dust runners), not a grammar task. Do *not* add a `:budget` field to `.deed`. Nothing reads it. A field no tool consumes is how the TOML speciation started. *Layer:* the Nickel runner layer only (task #76). No grammar change, no new `.deed` field. ==== Echo — the name for what ANCHOR is `_TYPES _SET/echo-types` (Agda, `--safe --without-K`, no postulates) proves the fiber laws for `Echo f` and the total-space equivalence `A ≃ Σ B (Echo f)`. Read against this format: a deed is a projection of a repo’s actual state; the fiber over a declaration is everything the projection lost. The equivalence then says the declaration plus its fiber recovers the repo — which is the precise statement of what ANCHOR is for (task #22, ruled 2026-09-08 to be both descriptile and contractile, the is/ought join). Declared state is the projection; observed drift is the fiber; ANCHOR is the point where the two are forced back together. Two caveats carried verbatim from the repo, because they bound the claim. The equivalence "is not novel" — it is the standard HoTT total-space-of-fibers result — and "the repo’s contribution is the emphasis", treating it as the foundation for a structured-loss account. And the factorization is domain-replacement, not image factorization; the repo admits `EchoImageFactorization` is a misnomer and gives a weak factorization system, with orthogonality (unique diagonal fills) not yet proved. *Ruling proposed:* adopt *echo* as the vocabulary for the ANCHOR spec — projection, fiber, structured loss — and cite it as naming a shape, not as machinery that computes anything. Nothing here validates a file. *Layer:* semantics, and the ANCHOR spec (#22). No grammar change. ==== Choreographic — already the estate/repo split, and its keystone is proved in a fragment `_TYPES _SET/choreographic-types` is not a fourth independent system: it fuses the previous two. A global choreographic type `G` is read as a partial causal order and projected to local types by endpoint projection, with each edge graded by an echo loss-grade and an epistemic standpoint-warrant. A cut is a consistent frontier (antichain) across that order. That is the topology this spec already describes. `estate_chora.deed` is the global type; `repo_chora.deed` is its endpoint projection; the one-declaration-site rule is the projection discipline — vocabulary is declared once globally and projected, never re-declared locally. Naming it as endpoint projection turns "an operational tool does not read a source it is not a party to" from a prose invariant into a statable property. The keystone is the repo’s central result, K-CUT: grading and transport commute with projection across a consistent frontier. Earlier revisions of this spec recorded it as an open conjecture. Its loss component is now proved. Upstream states the following in `PROOF-STATUS.adoc` of `hyperpolymath/choreographic-types` at commit `a7c45138ee9ad59d278d26140ae22a96009593f3`: * *K-1, K-CUT-LOSS.* For every party `p`, global type `G` and cut `c` with `Consistent p c`, `grade↾ p (G ↾ c) ≡ lgrade (proj p G ↾ₗ cutproj p c)`, parametric in the resource algebra. PROVEN (`Choreographic.KCut.kcut-loss`). * *K-4.* That proof uses exactly two laws, `𝟙 ⊗ x ≡ x` and `x ⊕ x ≡ x`. TESTED (`scripts/minimal-laws.sh`). * *K-5.* `Consistent p c` alone makes the cut prefix projectable. PROVEN (`KCut.cut-projectable`). * *K-7.* Both side conditions are needed: without either, the equality fails. TESTED (two refusal fixtures). * *Y-2, asynchronous K-CUT-LOSS.* The same equality for every causal cut consistent for `p`, with messages in flight, using the same two laws. PROVEN (`Async.akcut-loss`). Upstream's gate checks these with `agda --safe --without-K --cubical-compatible --no-libraries --ignore-interfaces --double-check -W error` on Agda 2.6.4.3 (Debian `agda-bin=2.6.4.3-1+b2`), with its sibling libraries pinned by commit. The limits travel with the claim: * *Fragment.* Finite global types with messages and binary choice, plain merge, synchronous; Y-2 adds asynchrony over the same fragment. Not covered: recursion, full merge, delegation, queues as data. * *Loss only.* What is cited here is the equality (loss) component. The warrant and transport component has its own rows upstream and nothing here relies on it. * *No grade claimed.* Upstream records every theorem as `ungraded`: there is no per-theorem PWG-3 receipt and no Rocq or Lean recheck leg (`3-practice/PROOF-POLICY.adoc` §8). This spec cites the theorem by pin, as it cites echo-types. It does not re-prove it and asserts no grade. * *Port.* `hyperpolymath/typed-wasm` `src/abi/TypedWasm/ABI/KCut.idr` is an Idris2 port and re-proof, taken from upstream commit `edb784a7`. Its correspondence to the Agda is `ASSUMED`, it does not re-check K-4, and it is not a Rocq or Lean recheck leg. *Owner ruling, 2026-11-18:* the caution is lifted. The estate/repo projection relation may rest on K-CUT-LOSS, within the fragment and limits above. A rule derived from it is proposed in link:../../../docs/decisions/ADR-011-deed-projection-rests-on-k-cut-loss.adoc[ADR-011]. The owner ruled its design points the same day: echo loss as the grade, `G` derived from deeds, the asynchronous form (Y-2), and both rules adopted as advisory. It is not enforced. *Ruling proposed:* adopt choreography/endpoint-projection as the description of the estate/repo relation in the document forms. *Layer:* semantics and terminology. No grammar change. == Conformance and the validator obligation === Modes [cols="1,3"] |=== | Mode | Meaning | `lax` | Structure only. Identity and version absent are warnings. | `strict` | Identity and version absent are ERRORS. Unknown clauses are errors. | `attested` | `strict`, plus every derived judgement must carry a witness. |=== For `.deed` files, `strict` is the DEFAULT and `lax` MUST be opt-in. This inverts current behaviour and is deliberate. Today, identity and version are `report_issue "warning"`, so a file with no identity at all scores `rc=0` and prints "validation passed" unless `INPUT_STRICT=true` is set. Any CI job citing the validator without that variable is a formality, not a gate. That default is how the speciation regenerated unnoticed, and it must not carry over to `.deed`. A `.deed` file in `strict` mode MUST: . Parse completely against `abnf/deed.abnf` (full input consumed). . Have a filename that dispatches to a head matching `DocHead`. . Carry the required identity fields in the table in <>. . Not use `_` in any symbol, `#T`/`#F` as booleans, or unknown escapes. === The single change the validator needs Add a fifth identity form — the s-expression head — and accept hyphenated keyword versions. Match only keywords defined in <>: ---- # identity: accept a deed document head || [[ "$line" =~ ^[[:space:]]*\((estate-deed|repo-deed|estate-atlas-deed|praxis-deed|contractile-deed|descriptile-deed)([[:space:]]|$) ]] # identity: accept keyword-style identity fields (hyphenated, leading colon) || [[ "$line" =~ ^[[:space:]]*:(canonical-name|estate-uuid|repo-uuid|beholding-chora)[[:space:]] ]] # version: accept hyphenated keyword form alongside version/schema_version || [[ "$line" =~ ^[[:space:]]*:schema-version[[:space:]] ]] || [[ "$line" =~ ^[[:space:]]*:registry-version[[:space:]] ]] ---- A SECOND, separate gap was measured in the same script. Version detection reads: ---- if [[ "$line" =~ ^[[:space:]]*(version|schema_version)[[:space:]]*[=:] ]]; then has_version=true ---- That pattern requires the field name at the start of the line with no leading colon, and spells it with an underscore. The deed surface writes `:schema-version` — leading colon, hyphen. Verified by direct test: the line `:schema-version "1.0.0"` does NOT match, while `schema_version = "1.0"` does. So a conforming deed fails BOTH the identity check and the version check, for two independent reasons. Both must be patched together or the fix is half a fix. The patterns are anchored to optional leading whitespace only, so an indented field still matches. This matters: the owner’s own `estate_chora.deed` indents its fields, and a form anchored to column zero would reject it. The *head* itself has no separator between `(` and the symbol, so `(estate-deed` is always column-adjacent. Do *not* match `:estate-authority` or `:agent-id` until they are in the identity table. === Exemptions carry over unchanged The existing identity exemptions remain: basenames containing `AI-MANIFEST`; `AI.a2ml` (and its successor `AI.deed`); any basename containing `template`; any file with unfilled placeholders; and any path under a configured design tree. These exist because a template legitimately has no identity of its own. == Rulings settled, and rulings still open === Settled by the owner, 2026-09-08 *The record dialect — SUPERSEDED.* `RECORD-DIALECT-SPEC.adoc` (v1.0.0, Draft, in `hyperpolymath/a2ml`) specified `[section]` + `key = value`. That is the TOML-family surface the owner’s own instruction targets ("many AIs have speciated the a2ml/k9s into json type and toml type … I did not ask for it"), and measurement over all 35,884 `.a2ml` files found the grammar has no `=` form. Ruled: keep the file as history, stamped SUPERSEDED with a superseded-by pointer to this document. It is no longer live guidance. *A praxis deed gets its own head — `praxis-deed`.* Four heads, not three. `estate-atlas-deed` remains the head for the registry specifically; `praxis-deed` is the general tool form. *Version field — `:schema-version`, required everywhere,* structurally first. `:registry-version` survives as an optional additional field on the atlas only. === Still open *Identity field table* — v0.2 proposed `:beholding-chora` for every non-estate deed, `:estate-uuid` / `:repo-uuid` for own identity, and dropped `:estate-authority` / `:agent-id` / `:beholding-estate` until defined. Ratify or restore the split. *Echo typing — ANSWERED, ratification needed.* The four-type-systems section gives a reading grounded in `_TYPES _SET/echo-types`: a deed is a projection, the fiber over it is the drift, and `A ≃ Σ B (Echo f)` is why ANCHOR (#22) is the point that rejoins them. Ratify or reject that reading — and note the repo itself calls the equivalence non-novel and has not proved orthogonality. *The warrant/receipt swap — proposed, unratified.* Withdraw the coinage `veracity-claim` in favour of *warrant* (evidence recorded without assuming soundness) and *receipt* (a claim transported across a boundary), both already mechanised in `_TYPES _SET/epistemic-types`. Confirm the swap. *Where pillar-specific vocabulary lives.* One-declaration-site removes the duplicate universe; it does not decide where genuinely tool-specific types belong. Two options: put them in the universal chora (bloats it with vocabulary only one tool matches on), or add an explicit `(extends-vocabulary :base …)` form in the praxis deed — subordinate by construction, so it cannot recreate the two-universe defect. *Slot/assembly vocabulary has no declaration site at all.* A downstream consumer wanting to express a multi-slot assembly as a deed cannot do so today, and under one-declaration-site it may not invent the vocabulary locally. Either the estate chora gains it, or `extends-vocabulary` lands. (Task #75.) == References * link:./abnf/deed.abnf[DEED ABNF (v2.0.0, normative)] · link:./abnf/archive/deed.abnf_v0.1.0-draft[v0.1.0 DRAFT archive] * Clause profiles, each narrowing `clause` for one consumer without changing this grammar: link:./abnf/clauses/egress.abnf[`(egress …)`] v1.0.0 (link:./EGRESS-CLAUSE-SPEC.adoc[prose], ADR-009) and link:./abnf/clauses/rsr-scorecard.abnf[`(rsr-scorecard …)`] v0.2.0 (link:../mappings/scorecard-corpus-decision.adoc[prose] §6; the clause of a `praxis-deed` of `:profile rsr-scorecard`; ratified by the owner on 2026-11-14 with `:assessor` and an RFC 3339 UTC `:assessed-at`) * Shared rules for the clause modules (A7 M3), borrowed rather than restated: link:./abnf/clauses/common.abnf[`common.abnf`] v1.0.0, DRAFT (dates, string lists, the v8 chora id, the affirmation members) * link:https://www.rfc-editor.org/rfc/rfc7405[RFC 7405] (case-sensitive ABNF strings) * link:https://www.rfc-editor.org/rfc/rfc4122[RFC 4122] §4.3 (UUID v5) * link:../../../2-protocols/k9-coordination/spec/COORDINATION-K9-SPEC.adoc[K9 Coordination File Specification] (operational surface; not this grammar) == License This specification is licensed under CC-BY-SA-4.0. Implementations may use any OSI-approved license.