@sdd-method/author-cli 0.14.0 → 0.15.0

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/structure/intended.js

@@ -8,6 +8,8 @@
 //   a source-built row with a change_id    that change
 //   a contract row                         the change whose record agrees its file as new
 //   a row naming such a contract           that change
+//   a row built from the change's files    that change (its spec_path lies in openspec/changes/<change>/, as a
+//                                          requirement the change ADDS does)
 // Pure but for reading agreement records.
 import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
@@ -125,7 +127,7 @@ export class Additions {
                     out.add(k.slice(CONTRACTS.length + 1));
         return out;
     }
-    /** The open changes a source-built row belongs to: its change_id, or a new contract it is or names. */
+    /** The open changes a source-built row belongs to: its change_id, the change whose files it is built from, or a new contract it is or names. */
     ownersOf(schema, catalogue, row, sddId) {
         const out = new Set();
         const changeId = cell(row["change_id"]);
@@ -134,6 +136,9 @@ export class Additions {
             if (this.open.has(name))
                 out.add(name);
         }
+        const from = /^openspec\/changes\/([^/]+)\//.exec(cell(row["spec_path"]))?.[1];
+        if (from !== undefined && this.open.has(from))
+            out.add(from);
         const contractOwner = (id) => {
             const by = this.adder.get(elementKey(CONTRACTS, id));
             if (by !== undefined)

package/dist/maintain-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "0.15.0",
-  "built_against_sdd_cli": "5.1.0"
+  "version": "0.16.0",
+  "built_against_sdd_cli": "5.2.0"
 }

package/dist/verify-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "5.1.0",
-  "built_against_sdd_cli": "5.1.0"
+  "version": "5.2.0",
+  "built_against_sdd_cli": "5.2.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sdd-method/author-cli",
-  "version": "0.14.0",
-  "sddCliVersion": "5.1.0",
+  "version": "0.15.0",
+  "sddCliVersion": "5.2.0",
   "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",