@sdd-method/maintain-cli 0.15.1 → 0.16.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

@@ -0,0 +1,277 @@
+/**
+ * Contract availability manifest (M-ADR 0202).
+ *
+ * `.sdd/contract-availability.yaml` — the committed attestation that lets an
+ * instrument distinguish "absent because wrong" from "absent because not
+ * checked out" when an SDD references contract artefacts living in sibling
+ * repositories (the M-ADR 0110 contracts-* pattern).
+ *
+ * Two modes, per the format spec (docs/method/foundations/
+ * contract-availability-manifest.md in the method baseline):
+ *   --refresh  runs where siblings ARE checked out: resolves every collected
+ *              reference, writes/updates entries with content digest and
+ *              repo@commit coordinate. Preserves entries it cannot currently
+ *              see (still referenced, artefact absent here); drops entries no
+ *              longer referenced anywhere, and says so.
+ *   --verify   runs anywhere: present artefacts are digest-compared (drift);
+ *              absent-but-attested is satisfied; referenced-but-unattested-
+ *              and-absent is the failure class.
+ *
+ * References are collected from BOTH observed forms (M-ADR 0200 §4.5 — read
+ * what the estate writes):
+ *   1. traceability.contracts declarations (string and object entries), when
+ *      the declared path does not resolve inside the repo;
+ *   2. markdown links under docs/ whose target escapes the repo root.
+ */
+import { execFile as execFileCb } from "node:child_process";
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { dirname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
+import { promisify } from "node:util";
+import { parse as parseYaml } from "yaml";
+import { loadTraceabilityManifests } from "../catalogue/traceability-loader.js";
+import { FindingsLog } from "../catalogue/findings.js";
+const execFile = promisify(execFileCb);
+export const AVAILABILITY_MANIFEST_REL_PATH = ".sdd/contract-availability.yaml";
+export async function runAttest(opts) {
+    const log = [];
+    const repo = resolve(opts.targetRepo);
+    const codeRoot = resolve(opts.codeRoot ?? join(repo, ".."));
+    const manifestAbs = join(repo, AVAILABILITY_MANIFEST_REL_PATH);
+    const refs = await collectReferences(repo);
+    const existing = await readManifest(manifestAbs);
+    const existingByPath = new Map(existing.map((e) => [e.path, e]));
+    const refSet = new Set(refs.map((r) => r.ref));
+    if (opts.mode === "refresh") {
+        const entries = [];
+        const unresolvable = [];
+        const preserved = [];
+        for (const r of refs) {
+            const abs = resolveRef(r, repo, codeRoot);
+            if (abs !== null) {
+                entries.push(await attestOne(r.ref, abs));
+            }
+            else if (existingByPath.has(r.ref)) {
+                // Still referenced; artefact not visible from this machine. Keep the
+                // prior attestation rather than silently discarding evidence this
+                // run cannot re-establish.
+                entries.push(existingByPath.get(r.ref));
+                preserved.push(r.ref);
+            }
+            else {
+                unresolvable.push(r.ref);
+            }
+        }
+        const dropped = existing.filter((e) => !refSet.has(e.path)).map((e) => e.path);
+        await writeManifest(manifestAbs, entries);
+        log.push(`references collected: ${refs.length}`);
+        log.push(`attested: ${entries.length - preserved.length}`);
+        report(log, "preserved (referenced; artefact not visible here)", preserved);
+        report(log, "unresolvable on this machine (NOT attested)", unresolvable);
+        report(log, "dropped (no longer referenced anywhere)", dropped);
+        return { exitCode: 0, log };
+    }
+    // verify
+    const drift = [];
+    const attestedAbsent = [];
+    const presentClean = [];
+    const stale = [];
+    for (const e of existing) {
+        if (!refSet.has(e.path)) {
+            stale.push(e.path);
+            continue;
+        }
+        const abs = resolveRefPath(e.path, repo, codeRoot);
+        if (abs === null) {
+            attestedAbsent.push(e.path);
+            continue;
+        }
+        const digest = await sha256File(abs);
+        if (digest === e.sha256)
+            presentClean.push(e.path);
+        else
+            drift.push(`${e.path} (manifest ${e.sha256.slice(0, 12)}… vs present ${digest.slice(0, 12)}…)`);
+    }
+    const unattested = refs
+        .filter((r) => !existingByPath.has(r.ref) && resolveRef(r, repo, codeRoot) === null)
+        .map((r) => r.ref);
+    log.push(`entries: ${existing.length}, references: ${refs.length}`);
+    report(log, "present and clean", presentClean);
+    report(log, "attested (absent here, satisfied by manifest)", attestedAbsent);
+    report(log, "DRIFT (present artefact disagrees with attestation)", drift);
+    report(log, "UNATTESTED (referenced, absent, no entry)", unattested);
+    report(log, "stale entries (no longer referenced — remove)", stale);
+    const exitCode = drift.length > 0 || unattested.length > 0 ? 1 : 0;
+    return { exitCode, log };
+}
+async function collectReferences(repo) {
+    const out = new Map();
+    // 1. traceability.contracts declarations that do not resolve in-repo.
+    const manifests = await loadTraceabilityManifests({
+        sddPath: repo,
+        findings: new FindingsLog(),
+    });
+    for (const m of manifests) {
+        const block = m.traceability.contracts;
+        if (!block)
+            continue;
+        for (const list of [block.openapi, block.proto, block.avro, block.spicedb, block.graphql, block.cli]) {
+            if (!Array.isArray(list))
+                continue;
+            for (const entry of list) {
+                const p = typeof entry === "string" ? entry : entry.path;
+                if (typeof p !== "string" || p === "")
+                    continue;
+                if (existsSync(join(repo, p)))
+                    continue;
+                out.set(p, { ref: p });
+            }
+        }
+    }
+    // 2. markdown links under docs/ escaping the repo root.
+    const files = await walkMd(join(repo, "docs"));
+    const LINK = /(?<!!)\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+    for (const f of files) {
+        const txt = await readFile(f, "utf8").catch(() => "");
+        for (const match of txt.matchAll(LINK)) {
+            const raw = decodeURIComponent((match[1] ?? "").split("#")[0] ?? "").trim();
+            if (raw === "" || /^(https?|mailto|tel):/i.test(raw) || raw.startsWith("#"))
+                continue;
+            if (isAbsolute(raw) || raw.includes("{") || raw.includes("<"))
+                continue;
+            const abs = normalize(join(dirname(f), raw));
+            if (!relative(repo, abs).startsWith(".."))
+                continue;
+            out.set(raw, { ref: raw, relTo: dirname(f) });
+        }
+    }
+    return [...out.values()];
+}
+function resolveRef(r, repo, codeRoot) {
+    if (r.relTo !== undefined) {
+        const abs = normalize(join(r.relTo, r.ref));
+        return existsSync(abs) ? abs : null;
+    }
+    return resolveRefPath(r.ref, repo, codeRoot);
+}
+/** Repo-root-relative declaration: in-repo first, then under codeRoot. Doc-relative refs (../…) resolve against repo root's parent chain via normalize. */
+function resolveRefPath(ref, repo, codeRoot) {
+    for (const base of [repo, codeRoot]) {
+        const abs = normalize(join(base, ref));
+        if (existsSync(abs))
+            return abs;
+    }
+    return null;
+}
+async function attestOne(ref, abs) {
+    const sha256 = await sha256File(abs);
+    const source = await sourceCoordinate(abs);
+    const kind = inferKind(ref);
+    return { path: ref, sha256, source, ...(kind ? { kind } : {}) };
+}
+async function sha256File(abs) {
+    const buf = await readFile(abs);
+    return createHash("sha256").update(buf).digest("hex");
+}
+async function sourceCoordinate(abs) {
+    try {
+        const dir = dirname(abs);
+        const { stdout: top } = await execFile("git", ["-C", dir, "rev-parse", "--show-toplevel"]);
+        const { stdout: head } = await execFile("git", ["-C", dir, "rev-parse", "--short", "HEAD"]);
+        const name = top.trim().split(sep).pop() ?? "unknown";
+        return `${name}@${head.trim()}`;
+    }
+    catch {
+        return "unversioned";
+    }
+}
+export function inferKind(ref) {
+    if (ref.endsWith(".avsc"))
+        return "event";
+    if (ref.endsWith(".proto"))
+        return "rpc";
+    if (ref.endsWith(".zed"))
+        return "authz";
+    if (/\.graphqls?$/.test(ref))
+        return "graphql";
+    if (/openapi/.test(ref) && /\.(ya?ml|json)$/.test(ref))
+        return "rest";
+    // A command manifest lives under a `cli/` contracts folder. Tested after rest, so an OpenAPI file in a
+    // repository whose own name ends in -cli stays rest.
+    if (/(^|\/)cli\/.*\.ya?ml$/.test(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 [];
+    const raw = await readFile(abs, "utf8");
+    const doc = parseYaml(raw);
+    if (!doc || !Array.isArray(doc.artefacts))
+        return [];
+    const out = [];
+    for (const a of doc.artefacts) {
+        if (a === null || typeof a !== "object")
+            continue;
+        const o = a;
+        if (typeof o["path"] !== "string" || typeof o["sha256"] !== "string")
+            continue;
+        out.push({
+            path: o["path"],
+            sha256: o["sha256"],
+            source: typeof o["source"] === "string" ? o["source"] : "unversioned",
+            ...(typeof o["kind"] === "string" ? { kind: o["kind"] } : {}),
+        });
+    }
+    return out;
+}
+async function writeManifest(abs, entries) {
+    const sorted = [...entries].sort((a, b) => a.path.localeCompare(b.path));
+    const lines = ['schema_version: "1.0"', "artefacts:"];
+    for (const e of sorted) {
+        lines.push(`  - path: ${JSON.stringify(e.path)}`);
+        lines.push(`    sha256: "${e.sha256}"`);
+        lines.push(`    source: ${JSON.stringify(e.source)}`);
+        if (e.kind)
+            lines.push(`    kind: "${e.kind}"`);
+    }
+    await mkdir(dirname(abs), { recursive: true });
+    await writeFile(abs, lines.join("\n") + "\n", "utf8");
+}
+async function walkMd(root) {
+    const { readdir } = await import("node:fs/promises");
+    const out = [];
+    async function rec(dir) {
+        let names;
+        try {
+            names = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const d of names) {
+            const p = join(dir, d.name);
+            if (d.isDirectory()) {
+                if (d.name === "node_modules" || d.name === ".git")
+                    continue;
+                await rec(p);
+            }
+            else if (d.name.endsWith(".md"))
+                out.push(p);
+        }
+    }
+    await rec(root);
+    return out;
+}
+function report(log, label, items) {
+    // Count AND list, always (M-ADR 0200 §4.3).
+    log.push(`${label}: ${items.length}`);
+    for (const i of items)
+        log.push(`  - ${i}`);
+}
+//# sourceMappingURL=index.js.map

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/maintain-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "0.15.1",
-  "built_against_sdd_cli": "5.1.1"
+  "version": "0.16.0",
+  "built_against_sdd_cli": "5.2.0"
 }

package/dist/verify-version.json

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sdd-method/maintain-cli",
-  "version": "0.15.1",
-  "sddCliVersion": "5.1.1",
+  "version": "0.16.0",
+  "sddCliVersion": "5.2.0",
   "description": "Bring an SDD repository current and rebuild its derived model — sync, briefing, catalogue build and aggregate, pack build, context pull — plus every read-only verify verb. Ships only the code those verbs reach; it cannot author specification content. Authoring is in @sdd-method/sdd-cli.",
   "license": "UNLICENSED",
   "type": "module",