Skip to content

grammar artifacts: .k9 has no grammar or contract at all, and deed.abnf states both “sole normative” and “pending owner ruling” #1058

Description

@arena-ai-coding-agent

Two grammar-artifact findings, from auditing what actually exists after #856.


Finding 1 — K9 has no grammar artifact, and may not need the one A2ML has

Every A2ML family ships an ABNF:

1-formats/a2ml/agentic/spec/agentic.abnf
1-formats/a2ml/anchor/abnf/anchor.abnf
1-formats/a2ml/ecosystem/spec/ecosystem.abnf
1-formats/a2ml/ecosystem/spec/family/scm-core.abnf
1-formats/a2ml/meta/spec/abnf/meta.abnf
1-formats/a2ml/meta/spec/shared/s-expression.abnf
1-formats/a2ml/state/spec/abnf/state.abnf

K9 ships none. 1-formats/k9/ carries prose only — SPEC.adoc, GUIDE.adoc,
IANA-MEDIA-TYPE-APPLICATION.adoc, TESTING.adoc, K9-ADOPTION-EXPANSION.adoc — and there is no
spec/abnf/ anywhere in it.

The reason this is not simply "write the missing ABNF"

A2ML has its own syntax (s-expressions, ; comments, the =-is-not-a-deed rule), so a grammar
file is the right artifact for it. K9 does not have its own syntax. A K9 file is a
*.k9.ncl — a Nickel file — distinguished only by a magic first line:

K9!
# SPDX-License-Identifier: MPL-2.0
{ pedigree = { schema_version = "1.0.0", security = { leash = 'Hunt, ... }, ... } }

SPEC.adoc states this directly: the format "operates via the must-just-nickel triad:
environment detection (must), task orchestration (Just), and typed validation (Nickel)"
.

So an ABNF that covers the whole file would be re-specifying Nickel. The grammar that is
actually missing is only the envelope, and the validation that is actually missing is a
normative contract, not a grammar:

Artifact Exists? Should exist?
Nickel's own grammar upstream, in Rust not ours to write
K9! magic envelope (K9! = \x4B\x39\x21) + SPDX header + top-level shape prose in SPEC §Status yes — small, ABNF-able
normative Nickel contract for pedigree (schema_version, component_type, security, metadata, warnings, side_effects) no — only prose and the template-*.k9.ncl examples yes — this is the real gap
normative leash taxonomy prose (Hunt / Yard / Kennel, with `template-hunt kennel
media type drafted (IANA-MEDIA-TYPE-APPLICATION.adoc, application/vnd.k9) in progress

Recommendation: rule on which of these K9 needs, rather than assuming the A2ML shape
transfers. My read is: envelope ABNF (small) + a normative Nickel contract (the load-bearing
one) + the leash set as a closed enum. Validation today appears to run through
.githooks/validate-k9.sh, .github/workflows/k9-contractile.yml and the estate's
k9_typecheck tests — worth confirming whether those check a specified contract or each
consumer's local assumption, because that difference is the whole point of a spec.

Naming hazard to carry into any K9 spec work

SPEC.adoc warns, in its own IMPORTANT block:

"K9's execution triad is must / just / nickel. It is not the contractiles family
must / trust / dust / intend, which is a separate estate concept. The word must appears in
both and means different things; never conflate them."

Any K9 contract should namespace or otherwise disambiguate must, since DEED conversion is
simultaneously pulling the contractiles family (which owns the other must) into the same tree.


Finding 2 — deed.abnf v1.0.0 contains a self-contradicting ruling note

1-formats/deed/spec/abnf/deed.abnf is now the sole normative grammar (#856 landed this; hazards
1–2 of #837 are cleared — thank you). Its header comment still reads, in sequence:

; NOTICE (standards#837): OWNER RULING 2026-09-19 — the grammar files have
; come together: THIS is the sole normative grammar (v1.0.0), ...
; 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.
; pending owner ruling. Grammar below is unchanged.

"OWNER RULING 2026-09-19 … THIS is the sole normative grammar" and "pending owner ruling" are
in the same block. A reader parsing this file as a normative artifact cannot tell whether the
ruling landed. The trailing fragment looks like a leftover from the pre-ruling revision.

Ask: delete or complete the pending owner ruling fragment so the normative grammar states
its own status unambiguously. Anyone writing a validator from this file will otherwise hand-encode
whichever reading they happened to land on — which is precisely hazard 4 of #837
("the filename-dispatch ordering side condition must be hand-encoded in every validator").

While there: the archive entry is named deed.abnf_v0.1.0-draft but R1 in the #837 ruling
register proposed deed.abnf_v0.1. Confirm the intended canonical name, since the register and
the tree currently disagree.


Acceptance

Refs: standards#837, #856, #752; 1-formats/k9/SPEC.adoc; 1-formats/deed/spec/abnf/deed.abnf.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions