diff --git a/k9-ecosystem/.machine_readable/anchors/ANCHOR.a2ml b/k9-ecosystem/.machine_readable/anchors/ANCHOR.a2ml new file mode 100644 index 000000000..0ed53a13f --- /dev/null +++ b/k9-ecosystem/.machine_readable/anchors/ANCHOR.a2ml @@ -0,0 +1,63 @@ +# SPDX-License-Identifier: MPL-2.0 +# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) +# ANCHOR.a2ml — authoritative anchor for the k9-ecosystem hub. + +[metadata] +version = "1.0.0" +last-updated = "2026-06-20" + +[anchor] +schema = "hyperpolymath.anchor/1" +repo = "hyperpolymath/k9-ecosystem" +authority = "upstream-canonical" +purpose = [ + "Own the canonical K9 format specification and conformance suite.", + "Define what K9 implementations (satellites) may extend but not redefine.", + "Publish the spec version that every satellite must pin.", +] + +[identity] +project = "k9-ecosystem" +kind = "specification-hub" +one-sentence = "Canonical home of the K9 self-validating configuration format: owns the spec and conformance suite, aggregates the implementations and tooling." +domain = "software-component-declaration" + +[semantic-authority] +policy = "canonical" +owns = [ + "K9 format specification (spec/SPEC.adoc)", + "Conformance suite and reference behavior (conformance/fixtures/)", + "K9 invariant definitions and the SecurityLevel / Leash model", +] + +[semantic-authority-files] +language-spec = "spec/SPEC.adoc" +conformance = "conformance/fixtures/" + +[spec-version] +# The version satellites pin. Bump on ratified spec changes. +current = "0.1.0-draft" + +[governance-authority] +# The hub is itself a satellite of the estate standards for governance: +# the anchor schema, contractile model, and ECOSYSTEM.a2ml meta-layer are owned upstream. +upstream = "hyperpolymath/developer-ecosystem" +pins-schema = "hyperpolymath.anchor/1" + +[satellite-policy] +# Obligations the hub places on every K9 member (implementation / tooling / ci / examples): +must-pin-upstream = true +must-declare-authority = true +must-have-anchor = true +must-run-conformance = true + +[implementation-policy] +allowed = ["AsciiDoc", "Markdown", "Nickel", "Just", "Shell", "TOML"] +forbidden = ["Node.js", "npm"] + +[golden-path] +smoke-test-command = ["just check-spec"] +success-criteria = [ + "spec/SPEC.adoc present and versioned", + "conformance/fixtures present", +] diff --git a/k9-ecosystem/.machine_readable/anchors/README.adoc b/k9-ecosystem/.machine_readable/anchors/README.adoc new file mode 100644 index 000000000..da0ad00e8 --- /dev/null +++ b/k9-ecosystem/.machine_readable/anchors/README.adoc @@ -0,0 +1,40 @@ +// SPDX-License-Identifier: MPL-2.0 +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) += K9 Anchors — single source of truth, enforced + +The K9 format has *one writer and many pinned readers*. This directory holds the +mechanism that keeps them from drifting silently. + +== Roles + +* `ANCHOR.a2ml` — the *hub* anchor. Declares `authority = upstream-canonical` + and `semantic-authority.owns` the K9 spec (`spec/SPEC.adoc`) and conformance + suite. Publishes `[spec-version].current` — the version every member pins. The + hub is itself a *satellite of `developer-ecosystem`* for governance. +* `SATELLITE-ANCHOR.template.a2ml` — copied into each member repo as + `.machine_readable/anchors/ANCHOR.a2ml`, with `authority = satellite` and an + `[upstream]` block pinning `spec-version`. + +== The contract (pin + verify, not hardlink) + +[cols="1,2,2", options="header"] +|=== +| Artifact | Pin | Drift check +| Spec prose | satellite cites `spec-version` | anchor-drift job: pinned version must exist upstream +| Conformance fixtures | submodule / published artifact | conformance run: impl output != `expected.json` -> red +| Derived grammars (tree-sitter, TextMate, JSON schema) | generated from the spec | regenerate-&-diff job: stale -> red +| Vendored governance | stamped via `{{OWNER}}` templating + content hash | `a2ml-validate-action` re-stamp, fail on hash diff +|=== + +The enforcer is `hyperpolymath/k9-validate-action`: an *anchor-drift* job asserts +every satellite pins an existing upstream `spec-version` and (where vendored) that +governance hashes match. A drifted satellite cannot merge — the CI check is the +hardlink: versioned and loud. + +== Propagation status + +* [x] Hub anchor (this PR) +* [ ] `k9-rs` flipped `upstream-canonical -> satellite` (reference behaviour, not spec authority) +* [ ] Satellite anchors stamped across the remaining members +* [ ] anchor-drift job added to `k9-validate-action` +* [ ] generate-from-spec + regen-diff wired for `tree-sitter-k9` / `vscode-k9` diff --git a/k9-ecosystem/.machine_readable/anchors/SATELLITE-ANCHOR.template.a2ml b/k9-ecosystem/.machine_readable/anchors/SATELLITE-ANCHOR.template.a2ml new file mode 100644 index 000000000..91615e84c --- /dev/null +++ b/k9-ecosystem/.machine_readable/anchors/SATELLITE-ANCHOR.template.a2ml @@ -0,0 +1,36 @@ +# SPDX-License-Identifier: MPL-2.0 +# SPDX-FileCopyrightText: 2026 {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> +# ANCHOR.a2ml — satellite anchor template. Copy into a K9 member repo at +# .machine_readable/anchors/ANCHOR.a2ml and fill the {{...}} fields. + +[metadata] +version = "1.0.0" +last-updated = "{{CURRENT_DATE}}" + +[anchor] +schema = "hyperpolymath.anchor/1" +repo = "{{OWNER}}/{{REPO}}" +authority = "satellite" + +[identity] +project = "{{PROJECT_NAME}}" +kind = "{{PROJECT_KIND}}" # implementation | tooling | ci | examples +one-sentence = "{{PROJECT_PURPOSE}}" + +[upstream] +# Canonical owner of the K9 format. This satellite may extend but not redefine it. +canonical = "hyperpolymath/k9-ecosystem" +spec-version = "0.1.0-draft" # MUST equal an existing k9-ecosystem [spec-version].current +conformance = "hyperpolymath/k9-ecosystem//conformance/fixtures" + +[satellite-policy] +must-pin-upstream = true +must-run-conformance = true # reproduce conformance fixtures' expected.json +redefines-spec = false + +[golden-path] +smoke-test-command = ["just test"] +success-criteria = [ + "Conformance fixtures reproduced", + "Pinned spec-version exists upstream", +]