; SPDX-FileCopyrightText: © 2026 Jonathan D.A. Jewell (hyperpolymath) ; SPDX-License-Identifier: MPL-2.0 ; SPDX-License-Identifier: CC-BY-SA-4.0 ; ; DEED grammar, v2.0.0 ; Normative for parsing. Prose and rationale: ../DEED-GRAMMAR-SPEC.adoc ; ; NOTICE (standards#837): OWNER RULING 2026-09-19 — the grammar files have ; come together: THIS is the sole normative grammar (v1.0.0), now under its ; correct extension. The v0.1.0 DRAFT archive lives at ; archive/deed.abnf_v0.1.0-draft under its true version. Its only extra rule ; (version-field) is superseded: v1.0.0 folds :schema-version into `field` ; with the "exactly once" side condition. ; Requires RFC 7405 (%s"..." case-sensitive string literals). ; ; NOTE: there is no "key = value" production and no "[section]" production. ; The only bracket is "(". A file using "=" as a field separator is not a deed. ; ("=" MAY appear INSIDE a symbol, e.g., a comparison operator.) ; ; CHANGELOG (v1.5.0 → v2.0.0, A7 rulings S1 and J24, 2026-11-14; SysArch R-01): ; - Removed the doc-head anchor-deed and the file name ANCHOR.deed. The ; anchor is the (anchor …) clause of the chora deed (A7 Q11, restored by ; S1), grammared by clauses/anchor.abnf. ANCHOR.deed now dispatches to ; nothing. NOT additive, so a major version: a v1.5.0 deed headed ; anchor-deed, or named ANCHOR.deed, is not a v2.0.0 deed. Every other ; v1.5.0 deed is a v2.0.0 deed. Estate files still named ANCHOR.deed are ; folded into their repo's chora deed in that repo's own PR (A7 J25). ; ; CHANGELOG (v1.4.0 → v1.5.0, A7 ruling J17, 2026-11-13; SysArch R-03): ; - A field may end in the bang token "!", after a separator: ; field = keyword token-sep value [token-sep bang]. It marks a blocking ; rule (A7 8.4). SEMANTIC (validator-enforced): it is allowed only on ; the :id field of a (rule …) clause at the top level of a ; contractile-deed; anywhere else it is an error. "!" could start no ; field, clause or value before, so no v1.4.0 deed changes verdict: ; every v1.4.0 deed is a v1.5.0 deed. ; ; CHANGELOG (v1.3.0 → v1.4.0, A7 ruling J14, 2026-11-13): ; - Added three doc-heads, each chosen by an exact, case-sensitive file ; name: contractile-deed (file.deed for the six verbs), ; descriptile-deed (the thirteen ALL-CAPS descriptile names, CLADE.deed ; among them) and anchor-deed (ANCHOR.deed). A file in capitals says how ; it is; a Capitalised file says how it must be (A7 YL4). mustfile.deed, ; MUSTFILE.deed, Meta.deed and anchor.deed dispatch to nothing. ; Additive: every v1.3.0 deed is a v1.4.0 deed. No clause syntax changes; ; the forms these heads carry are grammared by their clause modules. ; ; CHANGELOG (v1.2.1 → v1.3.0, owner rulings U4 and I4, 2026-11-12): ; - Added uuid (#uuid"<8-4-4-4-12 lowercase hex>"), an opaque UUID literal. ; It carries an id minted elsewhere (the registry) as a value, not a ; preimage to hash, so a repo move or rename never changes the deed. Only ; versions 5 and 8 and variant 10 are legal: v4 (random) stays excluded. ; - A line is at most 998 octets, line-end excluded, so the 8bit encoding ; label of the deed media type is exact (RFC 2045 §2.8). Validator- ; enforced; see the SEMANTIC note on `deed` below. ; Additive for every deed with lines of 998 octets or fewer: every such ; v1.2.1 deed is a v1.3.0 deed. ; Errata, 2026-11-12 (review of #1473): uuid-variant writes "a" and "b" ; as %s"a" / %s"b". A quoted ABNF string is case-insensitive, so the ; first text admitted "A" and "B" there, which uuid-hex and the gate ; refuse. No lowercase deed changes verdict. ; ; CHANGELOG (v1.2.0 → v1.2.1, owner ruling 2026-10-27): ; - list: a token-sep MAY come before the first value. deed_lint and the ; estate template's deed (rsr-template-repo_chora.deed) already wrote ; multi-line lists that way. Additive: every v1.2.0 deed is a v1.2.1 deed. ; - The gate now enforces the rest of this grammar as written: no DEL or ; C0 control character in a string, comment or header line, a line-end ; after every comment, and nothing between "'" and what it quotes. ; ; CHANGELOG (v1.1.0 → v1.2.0, 2026-10-16): ; - Added exact filename 0-AI-MANIFEST.deed -> repo-deed for the canonical ; machine front door. Existing filename dispatch and clause syntax remain. ; ; CHANGELOG (v1.0.0 → v1.1.0, owner rulings D305/D320, 2026-10-07): ; - Added uuid8 (#u8"domain:name"), the ADR-008 profile C literal. Additive: ; uuid5 stays legal until its own cutover, so every v1.0.0 deed is a v1.1.0 deed. ; ; CHANGELOG (v0.1.0 → v1.0.0): ; - Added %s prefix for all case-sensitive literals (RFC 7405) ; - Added _ to symbol continuation set ; - Changed token-sep from WSP to SP (tabs INVALID, consistent with K9) ; - Made version-field order-free (moved into field/clause repetition) ; - Added EOF enforcement note ; - Added semantic constraint notes for filename↔doc-head matching ; - Added UUID v4 exclusion note ; - Clarified boolean case sensitivity deed = header [token-sep] form [token-sep] ; IMPLEMENTATION NOTE: A conforming parser MUST verify ; that the entire input is consumed by this production. ; Trailing non-whitespace content after the closing ")" ; is a parse error. ; SEMANTIC (validator-enforced, v1.3.0): no line is longer ; than 998 octets, counted in UTF-8 bytes before its ; line-end (CRLF or LF). The last line counts the same way. header = 1*spdx-line spdx-line = ";;" SP %s"SPDX-" 1*text-char line-end form = "(" doc-head 1*(token-sep (field / clause)) [token-sep] ")" ; SEMANTIC: Exactly one field MUST have the keyword ; ":schema-version" with a string value. A conforming ; validator MUST reject forms lacking this field. ; Order of fields and clauses is otherwise not semantic. doc-head = %s"estate-deed" / %s"repo-deed" / %s"estate-atlas-deed" / %s"praxis-deed" / %s"contractile-deed" / %s"descriptile-deed" ; SEMANTIC CONSTRAINT: The doc-head MUST match the ; filename dispatch (see deed-filename below). ; estate_chora.deed → estate-deed ; ATLAS.deed → estate-atlas-deed ; 0-AI-MANIFEST.deed → repo-deed ; *_praxis.deed → praxis-deed ; *_chora.deed → repo-deed ; file.deed → contractile-deed (J14) ; .deed → descriptile-deed (J14) ; A mismatch is a validation error. ; --- Filename dispatch ------------------------------------------------- ; The document form is selected by the filename STEM before parsing begins. ; This production grammars the NAME, not the contents. ; ; IMPLEMENTATION NOTE: The stem is everything before the final suffix ; ("_chora.deed", "_praxis.deed", etc.). Do NOT split on "." — the ; stem may contain dots (e.g., "my.project_chora.deed" → stem "my.project"). deed-filename = estate-file / atlas-file / manifest-file / contractile-file / descriptile-file / praxis-file / repo-file estate-file = %s"estate_chora.deed" ; -> estate-deed atlas-file = %s"ATLAS.deed" ; -> estate-atlas-deed manifest-file = %s"0-AI-MANIFEST.deed" ; -> repo-deed contractile-file = verb-cap %s"file.deed" ; -> contractile-deed (J14) verb-cap = %s"Intent" / %s"Must" / %s"Trust" / %s"Adjust" / %s"Dust" / %s"Bust" descriptile-file = descriptile-name %s".deed" ; -> descriptile-deed (J14) descriptile-name = %s"META" / %s"STATE" / %s"ECOSYSTEM" / %s"AGENTIC" / %s"NEUROSYM" / %s"PLAYBOOK" / %s"CLADE" / %s"INTENT" / %s"MUST" / %s"TRUST" / %s"ADJUST" / %s"DUST" / %s"BUST" ; Exact and case-sensitive: the case is the rule (A7 YL4). ; The six verb names are the verb descriptiles; CLADE is the ; repo's own content organisation (A7 W10), never identity. praxis-file = stem %s"_praxis.deed" ; -> praxis-deed repo-file = stem %s"_chora.deed" ; -> repo-deed stem = 1*( ALPHA / DIGIT / "-" / "." / "_" ) ; SIDE CONDITION (normative, NOT expressible in ABNF): ; In repo-file, MUST NOT be the exact string "estate". ; The literal "estate_chora.deed" also matches repo-file, so a conforming ; implementation MUST test estate-file BEFORE repo-file and MUST NOT parse ; estate_chora.deed as a repo-deed. Dispatch is exact-stem-first. ; See ../DEED-GRAMMAR-SPEC.adoc#chora-dispatch-exclusion. ; RULED 2026-09-08 by the owner on standards#752. field = keyword token-sep value [token-sep bang] bang = "!" ; v1.5.0 (A7 J17). SEMANTIC (validator-enforced, not ; expressible here): only on the :id field of a (rule …) ; clause at the top level of a contractile-deed, where it ; marks a blocking rule (A7 8.4). Since "!" may continue a ; symbol, "sym!" is one symbol; the bang is "!" standing ; alone after a separator. clause = "(" symbol *(token-sep (field / clause)) [token-sep] ")" keyword = ":" symbol value = string / symbol / integer / boolean / uuid5 / uuid8 / uuid / quoted / list list = "(" [token-sep] [value *(token-sep value)] [token-sep] ")" ; A separator MAY open the list, so a multi-line list can ; start on the line after "(", as the estate template writes. quoted = "'" ( symbol / list ) ; NOTE: Only symbols and lists may be quoted. ; Quoting integers, strings, or booleans is a parse error. ; Nothing comes between "'" and what it quotes: "' sym" is ; a parse error. symbol = ALPHA *( ALPHA / DIGIT / "." / "*" / "/" / "<" / ">" / "=" / "!" / "?" / "+" / "-" / "_" ) ; "." is STRUCTURAL: Type.Software.Library is ONE symbol ; whose dotted segments are meaningful to the type resolver. ; "=" may appear INSIDE a symbol (e.g., a comparison operator); ; it is never a field separator. ; "_" is permitted for compatibility with common identifier ; conventions, though hyphens are preferred in DEED keywords. string = DQUOTE *( str-char / escape ) DQUOTE str-char = %x20-21 / %x23-5B / %x5D-7E / UTF8-2 / UTF8-3 / UTF8-4 ; any char except " and \ escape = "\" ( DQUOTE / "\" / %s"n" / %s"t" ) ; Exactly four escapes: \" \\ \n \t ; \r, \uXXXX, and other escapes are INVALID. ; Embed non-ASCII characters directly as UTF-8. UTF8-2 = %xC2-DF UTF8-tail UTF8-3 = %xE0 %xA0-BF UTF8-tail / %xE1-EC 2UTF8-tail / %xED %x80-9F UTF8-tail / %xEE-EF 2UTF8-tail UTF8-4 = %xF0 %x90-BF 2UTF8-tail / %xF1-F3 3UTF8-tail / %xF4 %x80-8F 2UTF8-tail UTF8-tail = %x80-BF ; Comments and SPDX payloads are UTF-8, NOT ASCII. The lexical section of the ; spec says "a deed is a sequence of UTF-8 bytes", and the header the spec ; MANDATES carries "©" (%xC2 %xA9) — which VCHAR (%x21-7E) rejects. Before ; this rule, the normative grammar rejected the specification's own example. text-char = VCHAR / SP / UTF8-2 / UTF8-3 / UTF8-4 integer = [ "-" ] 1*DIGIT ; NOTE: Leading zeros are permitted (e.g., 007). ; Implementations MUST NOT interpret leading zeros as octal. boolean = %s"#t" / %s"#f" ; Strict lowercase only. #T and #F are INVALID. ; Never "true", "false", "yes", "no", "1", "0". uuid5 = %s"#u5" string ; Body is the NAME input to RFC 4122 §4.3 under the ; estate namespace. ; NOTE: Only name-based, deterministic identifiers are supported: ; uuid5 here and uuid8 (profile C) below. ; UUID v4 (random) is intentionally excluded — all DEED ; identifiers MUST be reproducible from their inputs. uuid8 = %s"#u8" string ; ESTATE-UUID-V8 profile C (ADR-008; D305, D320). The body is ; the PREIMAGE domain ":" name. The identifier is bytes 0..15 ; of SHA-256(body) with version 8 and variant 10, so it is ; reproducible from the deed alone, as uuid5 is. ; SEMANTIC (validator-enforced): the body contains ":", and the ; domain before the FIRST ":" is non-empty printable ASCII ; (%x21-7E) — ADR-008 forbids ":" in a domain, so the first ; ":" always ends it. The name after it is unconstrained. ; Example: #u8"gv-clade-index:github.com/hyperpolymath/standards" uuid = %s"#uuid" DQUOTE uuid-hex DQUOTE ; OPAQUE UUID (v1.3.0, owner ruling U4). The body IS the ; identifier, in RFC 9562 form, lowercase. Nothing is hashed: ; a reader cannot recompute it, and the deed does not record ; what it was derived from. An id minted once by the registry ; is written this way, so a move or rename of the repo never ; changes the deed. ; Example: #uuid"b32d6be4-73ba-873e-9d61-e57f43c75cd1" uuid-hex = 8hex-lc "-" 4hex-lc "-" uuid-version 3hex-lc "-" uuid-variant 3hex-lc "-" 12hex-lc uuid-version = "5" / "8" ; Name-based only, as for uuid5 and uuid8: v4 (random) and ; every other version are a parse error. uuid-variant = "8" / "9" / %s"a" / %s"b" ; RFC 9562 variant 10. %s: a quoted ABNF string is ; case-insensitive (RFC 5234 2.3), and "A" or "B" is an error. hex-lc = DIGIT / %x61-66 ; Lowercase only: "A" to "F" are a parse error. token-sep = 1*(SP / line-end / comment) ; Tabs (HTAB) are INVALID separators (consistent with K9). ; Use SP (0x20) for horizontal whitespace. line-end = CRLF / LF comment = ";" *text-char line-end ; Single ";" starts a comment (including ";;" — the second ; ";" is part of the comment text). Comment runs to line-end. ; Order of fields and clauses is not semantic. A canonical ordering is a ; lint convention for diffability, never a parse rule. Where precedence ; matters (rules in a praxis deed) it is carried by an explicit :priority ; INTEGER field, never by file position. ; ; The sole exception is :schema-version, which MUST be present exactly once ; in every form (enforced by the validator, not by grammar position).