From 7e8219f63a8df184568a078baeb40756be5775ef Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Thu, 17 Sep 2026 22:01:46 +0000 Subject: [PATCH] =?UTF-8?q?docs(deed):=20mapping=20spec=20family=202=20?= =?UTF-8?q?=E2=80=94=20META+ECOSYSTEM=20=E2=86=92=20repo-deed=20clauses?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Refs #837 --- .../mappings/meta-ecosystem-to-repo-deed.adoc | 173 ++++++++++++++++++ 1 file changed, 173 insertions(+) create mode 100644 1-formats/deed/mappings/meta-ecosystem-to-repo-deed.adoc diff --git a/1-formats/deed/mappings/meta-ecosystem-to-repo-deed.adoc b/1-formats/deed/mappings/meta-ecosystem-to-repo-deed.adoc new file mode 100644 index 000000000..bd9a0be52 --- /dev/null +++ b/1-formats/deed/mappings/meta-ecosystem-to-repo-deed.adoc @@ -0,0 +1,173 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 += Mapping spec — `META.a2ml` + `ECOSYSTEM.a2ml` → `repo-deed` (family 2) +Campaign: standards#837 · Frame: link:README.adoc[mappings/README] · +Status: PROPOSAL pending owner review (as is the whole campaign) + +Family 2 per the frame README. These two files are handled together because +they interlock: META describes the repo as an artefact; ECOSYSTEM places it +on the coordination graph — the graph the §5 acceptance criteria live on. + +== 1. Source surface + +Estate instances at `/.machine_readable/descriptiles/{META,ECOSYSTEM}.a2ml` +(descriptile-dir spelling) or `/.machine_readable/*.a2ml` (older). No +`.in` mint templates for these two in rsr-template main (a3c90a1) — the +canon shape lives in the rsr instance files themselves. **Fail-closed note:** +the translator refuses any field not in §3's tables (frame rule "anything +not in the table does not translate"); un-recon'd corner shapes fail, get +reviewed, and extend the table — they never translate ad-hoc. + +== 2. Target form + +Both translate into clauses of the SAME `_chora.deed` +(`repo-deed` head) that family 1 created — this family ADDS clauses; it +does not get its own file. (One deed per repo is the doc-head's semantics.) + +== 3. Field tables + +=== META.a2ml (clause `(meta …)` unless noted) + +[cols="2,3,4"] +|=== +| a2ml surface | deed path | transform / type + +| `[metadata] version` | `(meta :version "0.1.0")` | verbatim STRING — versions of the *content*, not the format (the format's version is `:schema-version` on the head, set by the translator, never copied from a field) +| `[metadata] last-updated` | `(meta :last-updated "…")` | verbatim STRING +| `[project-info] type` | `(meta :type library)` | enum → SYMBOL; closed set `library binary service website monorepo` (inline comment geography; other values fail closed) +| `[project-info] languages` | `(meta :languages (rust zig))` | list of SYMBOLs (identifiers, not prose) +| `[project-info] license` | `(meta :license MPL-2.0)` | SPDX id → SYMBOL (machine-checked against the estate licence corpus) +| `[project-info] author` | `(meta :author "Jonathan D.A. Jewell (hyperpolymath)")` | verbatim STRING +| `[development-practices] build-tool` | `(meta :build-tool just)` | SYMBOL +| `… container-runtime` | `(meta :container-runtime podman)` | SYMBOL +| `… ci-platform` | `(meta :ci-platform github-actions)` | SYMBOL +| `… package-manager` | `(meta :package-manager guix)` | enum → SYMBOL; seen set `guix cargo mix` +| `[maintenance-axes] scoping-first` | `(meta :scoping-first #t)` | BOOLEAN → `#t`/`#f` +| `… execution-order`,`axis-1`,`axis-2`,`axis-3` | `(meta :execution-order "…" …)` | verbatim STRINGs (contain spaces → can never be symbols) +| `[scoping] sources` / `marker-scan` / `idris-unsound-scan` | `(meta :scoping (sources "…") …)` | verbatim STRINGs +| `[axis-2-maintenance-rules] *-first/second/third` | `(meta :corrective-first #t …)` | BOOLEAN → `#t`/`#f` +| `… adaptive-focus`, `perfective-source` | `(meta :adaptive-focus "…" …)` | verbatim STRINGs +| `[architecture-decisions]`, `[axis-3-audit-rules]`, `[design-rationale]` | **fail-closed if populated** — seen empty in recon; free-form content needs a table row first | — +|=== + +=== ECOSYSTEM.a2ml (clause `(ecosystem …)`) + +[cols="2,3,4"] +|=== +| a2ml surface | deed path | transform / type + +| `[metadata] project` | `(ecosystem :project "rsr-template-repo")` | verbatim STRING — MUST equal the deed's `:canonical-name` (validator cross-check) +| `[metadata] ecosystem` | `(ecosystem :ecosystem "hyperpolymath")` | verbatim STRING +| `[position] type` | `(ecosystem :position-type "repository-template")` | verbatim STRING (free-form role label) +| `[position] purpose` | `(ecosystem :purpose "…")` | verbatim STRING +| `[position] what-this-is-not` | `(ecosystem :not ("a project in its own right" "Scaffoldia …"))` | list of STRINGs +| `[pipeline] position` | `(ecosystem :pipeline-position "foundation")` | verbatim STRING +| `[pipeline] chain` | `(ecosystem :chain "standards → rsr-template-repo → (every estate repo)")` | verbatim STRING (arrow prose stays prose) +| `[pipeline] notes` | `(ecosystem :pipeline-notes "…")` | verbatim STRING +| `[pipeline] coordination` | `(ecosystem :coordination standards)` | **the #726 hub-pointer, carried VERBATIM** — hub repo name → SYMBOL; empty string (standalone) stays `:coordination ""` +| `[related-projects] projects[]` | repeated clauses: `(related :name "standards" :relationship standard-source :notes "…")` | name → STRING, relationship → SYMBOL (`standard-source build-tooling validation-tooling signing-tooling verification-tooling` seen set), notes → STRING; one `(related …)` per array element, order-free (deed order is not semantic) +|=== + +== 4. Drop doctrine + +* The inline copy-editing comments (`# TODO: update type …`) annotate the + source's own to-do list: a to-do is journal content (STATE family's + decision territory), not deed state — it rides the source until retire + day, then dies there. +* Empty sections (`[architecture-decisions]` etc.) are NOT even kept as + empty slots here: deed clauses exist when they carry content; the slot + doctrine from family 1 applies to *registry* fields (CLADE/STATUS), not + to prose sections. + +== 5. Provenance & validation (extends family 1's P-1..P-5) + +* **P-2a (table-closed):** any field not in §3 fails translation loudly — + no best-effort passthrough. +* **P-6 (cross-check):** `:ecosystem :project` MUST equal head + `:canonical-name`; mismatch fails closed (catches a deed written into the + wrong repo). +* **P-7 (coordination grep guard):** emission asserts the verbatim + preservation grep `':coordination '` resolves for every hub/satellite + pair known from #726 — if the symbol table drifted, the lane red; the + corpus does not go green on a re-spelling. +* **P-8:** the two files merge into one deed conflict-free by construction + (clause names `meta`/`ecosystem` disjoint from family 1's + `identity/clade/forges/lineage/status`); a collision is a bug in the + table above, not in the repo. + +== 6. Worked translation (real instance: `rsr-template-repo`, abridged) + +[source] +---- +;; SPDX-License-Identifier: CC-BY-SA-4.0 +(repo-deed + :schema-version "1.0.0" + :canonical-name "rsr-template-repo" + :repo-uuid #u5"github.com/hyperpolymath/rsr-template-repo" + :beholding-chora #u5"" + + ; … family-1 clauses (identity clade forges lineage status) … + + (meta :version "0.1.0" + :last-updated "2026-04-11" + :type library + :languages () + :license MPL-2.0 + :author "Jonathan D.A. Jewell (hyperpolymath)" + :build-tool just + :container-runtime podman + :ci-platform github-actions + :package-manager guix + :scoping-first #t + :execution-order "axis-1 > axis-2 > axis-3" + :axis-1 "must > intend > like" + :axis-2 "corrective > adaptive > perfective" + :axis-3 "systems > compliance > effects" + (scoping + :sources "README, roadmap, status docs, maintenance checklist, CI/security docs" + :marker-scan "TODO/FIXME/XXX/HACK/STUB/PARTIAL" + :idris-unsound-scan "believe_me/assert_total") + :corrective-first #t + :adaptive-second #t + :adaptive-focus "scope-change reconciliation, stale-reference removal, obsolete-work culling" + :perfective-third #t + :perfective-source "axis-1 honest state after corrective/adaptive updates") + + (ecosystem :project "rsr-template-repo" + :ecosystem "hyperpolymath" + :position-type "repository-template" + :purpose "Canonical RSR-compliant repository template: scaffolding (CI/CD, AI manifests, ABI/FFI standards, container ecosystem, governance) that new hyperpolymath projects are instantiated from." + :not ("a project in its own right" + "Scaffoldia (the full-featured repo designer)" + "standards (the canon source this template operationalises)") + :pipeline-position "foundation" + :chain "standards → rsr-template-repo → (every estate repo)" + :pipeline-notes "rsr-template-repo turns the RSR standard into runnable scaffolding." + :coordination standards + (related :name "standards" :relationship standard-source :notes "Defines the RSR standard, contractile canon, and policies that this template operationalises.") + (related :name "stapeln" :relationship build-tooling :notes "Layer-based container build system; the template ships stapeln.toml scaffolding.") + (related :name "k9-svc" :relationship validation-tooling :notes "Runs the self-validating k9.ncl checks (.machine_readable/self-validating/).") + (related :name "cerro-torre" :relationship signing-tooling :notes "Container/image signing provider referenced by the container scaffolding.") + (related :name "svalinn" :relationship verification-tooling :notes "Supply-chain verification referenced by the container scaffolding.") + (related :name "vordr" :relationship verification-tooling :notes "Build/artifact verification referenced by the container scaffolding."))) +---- + +== 7. Acceptance greps (family 2 is preserved iff) + +* Every former META/ECOSYSTEM repo's `_chora.deed` carries + `(meta …)` and `(ecosystem …)` clauses parsing against the normative + grammar. +* The #726 coordination graph is ENUMERABLY intact: + `grep -rn ':coordination ' --include='*_chora.deed'` reproduces exactly + the pre-campaign hub→satellite edge set (export compared, byte-for-meaning). +* `(related …)` clause count per repo == source array length per repo. +* No `(meta …)` clause contains the literal `true`/`false` (only `#t`/`#f`). + +== 8. Open questions for the owner + +. Whether the maintenance-axes triple stays in META or moves to the + maintenance-methodology canon (it duplicates `.machine_readable/agent_ + instructions/methodology.a2ml` content in spirit — dedupe is a ruling, + not a mapping choice). +. Whether `license` as a SYMBOL in `(meta …)` is the single machine-checked + licence surface post-campaign (there are other licence carriers — + SPDX headers, LICENSE files; a dedupe ruling would make greps one-stop).