@sdd-method/author-cli 0.14.1 → 0.15.1

package/dist/lib/catalogue/build.js

@@ -90,7 +90,7 @@ export async function runCatalogueBuild(inputs, write) {
     const intendedRows = [];
     const rowsByCatalogue = modelFiles === null
         ? collected
-        : overlayModel(schema, viewOf(modelFiles, modelProblems), collected, findings, intendedWrites(open, agreedOrder(open)), intendedRows);
+        : withC4Rollups(overlayModel(schema, viewOf(modelFiles, modelProblems), collected, findings, intendedWrites(open, agreedOrder(open)), intendedRows));
     for (const p of modelProblems)
         findings.add("convention", `${p} (M-ADR 0230)`);
     // 3a. Normalise every keyed catalogue to PK-unique rows. Multi-source edge
@@ -1517,6 +1517,18 @@ async function collectRows(schema, manifest, findings, sddPath, snapshotStore) {
     });
     return out;
 }
+/**
+ * The C4 roll-ups joined again over the catalogues the structural model settles (M-ADR 0159 §4.8, M-ADR 0230 §4.3).
+ * collectRows joins them over the sources, which can state an element an agreed open change adds; the overlay holds
+ * that element back until the change archives, and a roll-up row reaching it would be a current row referencing it.
+ */
+function withC4Rollups(rows) {
+    const c4Containers = rows.get("c4_containers") ?? [];
+    const containerEntityRows = buildC4ContainerEntity({ serviceEntityRows: rows.get("service_entity") ?? [], c4Containers });
+    rows.set("c4_container_entity", containerEntityRows);
+    rows.set("c4_system_entity", buildC4SystemEntity({ containerEntityRows, c4Containers }));
+    return rows;
+}
 const CONTEXT_CROSS_CUTTING = "cross-cutting";
 /**
  * Convention check (schema 2.21.0): where a screen carries `context` and the

package/dist/lib/catalogue/builders/contract-revisions.js

@@ -13,10 +13,17 @@
 // a file matching no contract, or several, is a finding and produces no row. `relies_on` and `agrees` are a digest
 // beside `file:`, or a map from each file to its digest beside `files:`. A `relies_on` that no longer matches the
 // file's content is reported: the change relies on a revision that has moved, and is re-agreed.
+//
+// A contract declared outside the SDD has no file here. Its current content is what .sdd/contract-availability.yaml
+// attests (M-ADR 0202): the entry whose path is the contract's spec_path as the declaration writes it, so a fresh clone
+// with no sibling checkout builds the same rows. A contract neither here nor attested has no current revision, and an
+// archived change's revision of it is not classified: retired is a comparison with the current content, never the
+// absence of one.
 import { createHash } from "node:crypto";
 import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { parse as parseYaml } from "yaml";
+import { readAvailability } from "../../contracts-availability/index.js";
 const AGREEMENTS = join("docs", "agreements");
 const DIGEST = /^sha256:[0-9a-f]{64}$/;
 const DATE = /^\d{4}-\d{2}-\d{2}$/;
@@ -71,21 +78,29 @@ export async function buildContractRevisions(inputs) {
 }
 /**
  * The revision rows, and every contract an archived change deprecated. The second is kept apart because a contract
- * declared outside this SDD has no file here and so no revision row, yet its version is still deprecated.
+ * declared outside this SDD and not attested has no revision row, yet its version is still deprecated.
  */
 export async function contractRevisionsAndDeprecations(inputs) {
     const { sddPath, findings } = inputs;
     const rows = new Map();
     const current = new Map(); // contract id -> current digest
+    const attested = new Map(); // spec_path -> each digest attested for it
+    for (const e of await readAvailability(sddPath)) {
+        if (!/^[0-9a-f]{64}$/.test(e.sha256))
+            continue;
+        attested.set(e.path, (attested.get(e.path) ?? new Set()).add(`sha256:${e.sha256}`));
+    }
     for (const c of inputs.contracts) {
         const path = String(c["spec_path"] ?? "");
         if (path === "")
             continue;
         const bytes = await readFile(join(sddPath, path)).catch(() => null);
-        if (bytes === null)
+        const claims = attested.get(path);
+        // Two entries attesting different content for one path say nothing about which is current.
+        const digest = bytes !== null ? contentDigest(bytes) : claims?.size === 1 ? [...claims][0] : undefined;
+        if (digest === undefined)
             continue;
         const id = String(c["id"]);
-        const digest = contentDigest(bytes);
         current.set(id, digest);
         const rid = revisionId(id, digest);
         rows.set(rid, { id: rid, contract_id: id, digest, state: c["status"] === "deprecated" ? "deprecated" : "active", sunset_date: "", change_id: "", source_sdd_id: "", platform_sdd_id: "" });
@@ -145,14 +160,14 @@ export async function contractRevisionsAndDeprecations(inputs) {
             }
             if (state === "agreed")
                 rows.set(rid, { id: rid, contract_id: contract, digest: p.agrees, state: "agreed", sunset_date: "", change_id: changeId, source_sdd_id: "", platform_sdd_id: "" });
-            else if (!existing)
+            else if (!existing && now)
                 rows.set(rid, { id: rid, contract_id: contract, digest: p.agrees, state: "retired", sunset_date: "", change_id: changeId, source_sdd_id: "", platform_sdd_id: "" });
         }
     }
     const deprecated = new Map();
     for (const [contract, d] of deprecations) {
         deprecated.set(contract, { sunset: d.sunset, changeId: d.changeId });
-        // A contract whose file is outside this SDD has no revision row to mark.
+        // A contract outside this SDD with no attestation has no revision row to mark.
         const now = current.get(contract);
         const rid = now ? revisionId(contract, now) : undefined;
         const row = rid ? rows.get(rid) : undefined;

package/dist/lib/catalogue/builders/data-model.js

@@ -10,8 +10,9 @@
 //                                 `..` (non-identifying) is read as `--`, and reported
 // TypeQL, in the documented subset (M-ADR 0210 §4.2, `data-model.tql`), through the fail-closed parseTypes:
 //   an entity's owned attributes (@key, @card), and each binary relation as a relationship between its two roles'
-//   players, roles kept. The subset admits no participation cardinality, so both ends are zero-or-more, and a role's
-//   own @card is a cardinality invariant on the relationship.
+//   players, roles kept. An end's cardinality is the other player's participation: B plays R:b @card(1..1) puts
+//   exactly-one at A's end (each B has exactly one A), and an unannotated plays is zero-or-more (TypeDB's default).
+//   A role's own @card is a cardinality invariant on the relationship.
 // The keys become invariants: a primary key (PK, @key) is one unique invariant over its attributes, which are not
 // nullable; a UK is a unique invariant over its attribute. What a parser reads and cannot hold is an `extraction`
 // finding, never a silent skip.
@@ -194,9 +195,13 @@ export function parseTypeqlDataModel(text, where) {
             return false;
         });
         const cards = [...d.relates].flatMap(([role, ann]) => ann.required ? [`each ${label} relates exactly one ${role}`] : ann.optional ? [`each ${label} relates at most one ${role}`] : []);
+        const participation = (player, role) => {
+            const ann = t.entities.get(player)?.plays.get(`${label}:${role}`);
+            return ann?.required ? "exactly-one" : ann?.optional ? "zero-or-one" : "zero-or-more";
+        };
         for (const from of playersOf(a)) {
             for (const to of playersOf(b)) {
-                relationships.push({ from, to, name: label, fromCardinality: "zero-or-more", toCardinality: "zero-or-more", fromRole: a, toRole: b, roleCards: cards });
+                relationships.push({ from, to, name: label, fromCardinality: participation(to, b), toCardinality: participation(from, a), fromRole: a, toRole: b, roleCards: cards });
             }
         }
     }

package/dist/lib/catalogue/canonical-schema.yaml

@@ -721,7 +721,7 @@ enums:
     - value: zero-or-one
     - value: one-or-more
     - value: zero-or-more
-    description: "How many entities one end of a relationship holds for one entity at the other end (M-ADR 0230 §4.3): a Mermaid ER end marker (|| exactly one, |o or o| zero or one, }| or |{ one or more, }o or o{ zero or more). A TypeQL relationship is zero-or-more at both ends, because the subset admits no participation cardinality; a role's @card is a cardinality invariant (domain_invariants). Replaced entity_relationship_cardinality in schema 6.0.0."
+    description: "How many entities one end of a relationship holds for one entity at the other end (M-ADR 0230 §4.3): a Mermaid ER end marker (|| exactly one, |o or o| zero or one, }| or |{ one or more, }o or o{ zero or more). A TypeQL relationship's end is the other player's participation: B plays R:b @card(1..1) makes A's end exactly-one, @card(0..1) zero-or-one, and an unannotated plays zero-or-more; a role's @card is a cardinality invariant (domain_invariants). Replaced entity_relationship_cardinality in schema 6.0.0."
   domain_invariant_kind:
     values:
     - value: unique

package/dist/lib/contracts-availability/index.js

@@ -203,6 +203,10 @@ export function inferKind(ref) {
         return "cli";
     return undefined;
 }
+/** The SDD's attested external artefacts (`.sdd/contract-availability.yaml`); none when it has no manifest. */
+export async function readAvailability(repo) {
+    return readManifest(join(repo, AVAILABILITY_MANIFEST_REL_PATH));
+}
 async function readManifest(abs) {
     if (!existsSync(abs))
         return [];

package/dist/lib/metamodel/tql-subset-parser.js

@@ -175,11 +175,10 @@ export function parseTypes(text, fileLabel = "catalogue-schema.tql", options = {
                 if (decl.plays.has(w[1]))
                     throw new ParseError(`${where}: ${lab} plays ${w[1]} twice`);
                 const ann = parseAnnotations(w.slice(2), where);
-                // A plays clause's cardinality constrains participation, which the relational projection has no place for:
-                // refused, so a constraint the model gained can never be dropped by the projection with the gate green.
-                if (ann.key || ann.required || ann.multi || ann.optional) {
-                    throw new ParseError(`${where}: ${lab} plays ${w[1]} with a cardinality annotation; participation cardinality cannot be projected onto the catalogue schema, so it is not admitted`);
-                }
+                // A plays clause's cardinality constrains participation, and is kept: a reader that can hold it does, and a
+                // projection that cannot refuses it there (schema-projection), never here, so no reader drops it silently.
+                if (ann.key)
+                    throw new ParseError(`${where}: ${lab} plays ${w[1]} @key; a role is not a key`);
                 decl.plays.set(w[1], ann);
             }
             else if (head === "relates") {

package/dist/lib/validate/behaviour-store.js

@@ -86,6 +86,8 @@ const COMMIT_RE = /^[0-9a-f]{7,40}$/;
 // OpenSpec counts a task done when its box holds only `x`, either case, any spacing.
 const TASK_DONE_RE = /^\s*-\s*\[\s*[xX]\s*\]/m;
 const TARGET_HEADING_RE = /^##\s+(MODIFIED|REMOVED|RENAMED)\s+Requirements\b/m;
+// A tasks.md group headed by one word, `## <n>. <word>`, is that repository's work order (taskGroups).
+const GROUP_REPO = (repo) => `tasks.md has a work order for ${repo} and the record's work_orders do not; its evidence cannot be checked (a group heading of one word, \`## <n>. ${repo}\`, names the group's repository)`;
 async function exists(p) {
     try {
         await access(p);
@@ -516,6 +518,14 @@ export async function checkBehaviourStore(repo, options = {}) {
                 }
             }
         }
+        // The archive check reads a task group's repository from its heading; once the record declares work orders, a
+        // heading it would read as a repository the record lacks fails here, while the change can still be amended.
+        if (versionAtLeast(record?.schemaVersion, "1.1.0") && record?.status === "agreed" && record.workOrders.length > 0 && tasks !== null) {
+            const recorded = new Set(record.workOrders.map((w) => w.repo));
+            for (const g of taskGroups(tasks))
+                if (!recorded.has(g.repo))
+                    failures.push(`${record.file}: ${GROUP_REPO(g.repo)}`);
+        }
         // A test plan's kinds (M-ADR 0223 §4.4 as amended): changed and repaired scenarios go red then green, carried ones stay green.
         if (versionAtLeast(record?.schemaVersion, "1.1.0") && record?.status === "agreed") {
             const plan = await readText(join(repo, dir, "test-plan.md"));
@@ -717,7 +727,7 @@ export async function checkBehaviourStore(repo, options = {}) {
         const recorded = new Set(record.workOrders.map((w) => w.repo));
         for (const g of groups)
             if (!recorded.has(g.repo))
-                failures.push(`${record.file}: tasks.md has a work order for ${g.repo} and the record's work_orders do not; its evidence cannot be checked`);
+                failures.push(`${record.file}: ${GROUP_REPO(g.repo)}`);
         // Requirement names are unique within a feature, not across a change: a work order names `<feature>::<name>`,
         // or a bare name only one feature in the change has (schema 5.0.0). An ambiguous bare name implements nothing.
         const built = [];

package/dist/maintain-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "0.15.1",
-  "built_against_sdd_cli": "5.1.1"
+  "version": "0.16.1",
+  "built_against_sdd_cli": "5.2.1"
 }

package/dist/verify-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "5.1.1",
-  "built_against_sdd_cli": "5.1.1"
+  "version": "5.2.1",
+  "built_against_sdd_cli": "5.2.1"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sdd-method/author-cli",
-  "version": "0.14.1",
-  "sddCliVersion": "5.1.1",
+  "version": "0.15.1",
+  "sddCliVersion": "5.2.1",
   "description": "Re-author one SDD's content — scaffold, plan, contracts, conformance, api-surface, snapshots, briefings, catalogue check — plus every read-only verify verb. Ships only the code those verbs reach; it cannot sync the baseline or rebuild the catalogues. Maintenance is in @sdd-method/maintain-cli, administration in @sdd-method/sdd-cli.",
   "license": "UNLICENSED",
   "type": "module",