@sdd-method/maintain-cli 0.14.0 → 0.15.1

package/README.md

@@ -2,6 +2,6 @@
 
 `sdd-maintain` brings an SDD repository current and rebuilds its derived model, and **cannot author specification content** (M-ADR 0218).
 
-Verbs: everything in `@sdd-method/verify-cli`, plus `sync`, `generate-briefing`, `context pull`, `catalogue build`, `catalogue aggregate`, `catalogue graph`, `catalogue diff`, `pack build`, `render screen`.
+Verbs: everything in `@sdd-method/verify-cli`, plus `sync`, `generate-briefing`, `context pull`, `catalogue build`, `catalogue aggregate`, `catalogue graph`, `catalogue diff`, `pack build`, `render screen`, `structure show`, `structure render`.
 
 Each writes only derived or method-managed content, and two runs on the same commit write the same bytes. Authoring verbs — `init`, `scaffold`, `plan`, `conformance` and the rest — are not present in it, and are in `@sdd-method/sdd-cli`. Invoking one fails with exit 1.

package/dist/lib/catalogue/aggregate.js

@@ -32,6 +32,7 @@ import { buildLegacyContractIdMap } from "./contract-id.js";
 import { validatedPopulation, validateWithEngineToLog } from "./engine-validator.js";
 import { PLATFORM_STAMP_COLUMN, isPlatformScopedFk } from "./fk-validator.js";
 import { FindingsLog } from "./findings.js";
+import { STRUCTURE_DIR } from "../structure/model.js";
 import { readLockFile } from "../lock-file.js";
 import { mergeEdgeLabel } from "./builders/edge-label-merge.js";
 import { isAsyncContractType } from "./builders/product-platform-dependencies.js";
@@ -189,6 +190,14 @@ export async function runCatalogueAggregate(inputs, write) {
     // `sdd-loyalty-platform`). Kept separate from sddRootsById on purpose: the
     // try-every-root pass must iterate each root ONCE, or a root reachable under two
     // names would count as two hits and report a false ambiguity.
+    // M-ADR 0230: the SDDs here that hold a structural model. A structure-sourced row is that model's
+    // to state, so re-derivation never adds one the model leaves out (see rederiveAppend).
+    const modelSdds = new Set();
+    for (const [id, root] of sddRootsById) {
+        if (await stat(join(root, STRUCTURE_DIR)).then(() => true, () => false))
+            modelSdds.add(id);
+    }
+    const modelled = { schema, rowsByCatalogue, modelSdds, findings };
     const sddRootAliases = new Map(sddRootsById);
     for (const root of sddRootsById.values()) {
         sddRootAliases.set(basename(root), root);
@@ -338,7 +347,7 @@ export async function runCatalogueAggregate(inputs, write) {
             }
         }
         const before = (rowsByCatalogue.get("feature_repo") ?? []).length;
-        rederiveAppend(rowsByCatalogue, "feature_repo", rederivedFeatureRepo);
+        rederiveAppend(rowsByCatalogue, "feature_repo", rederivedFeatureRepo, modelled);
         const added = (rowsByCatalogue.get("feature_repo") ?? []).length - before;
         if (added > 0) {
             findings.add("coverage", `feature_repo: ${added} row(s) re-derived at aggregate tier for features that had NO anchor at member tier — evidence tokens naming a repo registered by another contributor resolve only against the merged repositories; already-anchored features are not widened (M-ADR 0198 §4.1 as amended; ${contributors.length} contributor doc trees scanned)`);
@@ -397,7 +406,7 @@ export async function runCatalogueAggregate(inputs, write) {
             }
         }
         const before = (rowsByCatalogue.get("journey_requirement") ?? []).length;
-        rederiveAppend(rowsByCatalogue, "journey_requirement", rederived);
+        rederiveAppend(rowsByCatalogue, "journey_requirement", rederived, modelled);
         const added = (rowsByCatalogue.get("journey_requirement") ?? []).length - before;
         if (added > 0) {
             findings.add("coverage", `journey_requirement: ${added} row(s) derived at aggregate tier, where a journey and the requirements it cites are catalogued in different SDDs (M-ADR 0229 §4.4; ${contributors.length} contributor(s) read)`);
@@ -416,8 +425,8 @@ export async function runCatalogueAggregate(inputs, write) {
         capabilityFeatureRows: rowsByCatalogue.get("capability_feature") ?? [],
         featureRepoRows: rowsByCatalogue.get("feature_repo") ?? [],
     });
-    rederiveAppend(rowsByCatalogue, "repo_capability", repoEdges.repoCapability);
-    rederiveAppend(rowsByCatalogue, "repo_contract", repoEdges.repoContract);
+    rederiveAppend(rowsByCatalogue, "repo_capability", repoEdges.repoCapability, modelled);
+    rederiveAppend(rowsByCatalogue, "repo_contract", repoEdges.repoContract, modelled);
     const featureContractRows = buildFeatureContract({
         findings,
         capabilityFeatureRows: rowsByCatalogue.get("capability_feature") ?? [],
@@ -425,7 +434,7 @@ export async function runCatalogueAggregate(inputs, write) {
         featureServiceRows: rowsByCatalogue.get("feature_service") ?? [],
         serviceContractRows: rowsByCatalogue.get("service_contract") ?? [],
     });
-    rederiveAppend(rowsByCatalogue, "feature_contract", featureContractRows);
+    rederiveAppend(rowsByCatalogue, "feature_contract", featureContractRows, modelled);
     const capabilityEventRows = buildCapabilityEvent({
         findings,
         manifests: [],
@@ -434,7 +443,7 @@ export async function runCatalogueAggregate(inputs, write) {
         capabilityServiceRows: rowsByCatalogue.get("capability_service") ?? [],
         serviceEventRows: rowsByCatalogue.get("service_event") ?? [],
     });
-    rederiveAppend(rowsByCatalogue, "capability_event", capabilityEventRows);
+    rederiveAppend(rowsByCatalogue, "capability_event", capabilityEventRows, modelled);
     // 5a-iii. Archetype data-plane expectations overlay (M-ADR 0191 §4.3) — the
     // deviation-visible WARN + conformance surface, run at AGGREGATION tier where
     // the reference-architecture bundle's `expected_bindings` resolve (the
@@ -687,14 +696,42 @@ function dedupExternalExemptions(rowsByCatalogue, findings) {
     }
     rowsByCatalogue.set("external_system_exemption", [...byId.values()].sort((a, b) => String(a["id"]).localeCompare(String(b["id"]))));
 }
+// M-ADR 0230: in a structure-sourced catalogue, the column naming the row's subject, and the
+// node catalogue it names. The subject's SDD is the one whose model states the row.
+const STRUCTURE_SUBJECT = {
+    capability_event: { column: "capability_id", catalogue: "capabilities" },
+};
 // M-ADR 0198 §4.2/§4.3: append a re-derived catalogue's rows to whatever concatenation
 // already produced for it, keeping the concatenated row on any primary-key collision. One
 // shared mechanism for every re-derived catalogue, so adding a fifth is a call to this
 // function with that catalogue's builder output, not new merge logic.
-function rederiveAppend(rowsByCatalogue, catalogueName, rederivedRows) {
+// M-ADR 0230: a structure-sourced catalogue is stated by the structural model where its
+// subject's SDD holds one, and that SDD's own build already put the model's rows here; a
+// re-derived row the model leaves out is reported, never added. A row whose subject's SDD this
+// aggregation cannot see (an organisation sibling's member) is added as before.
+function rederiveAppend(rowsByCatalogue, catalogueName, rederivedRows, modelled) {
     const concatenated = rowsByCatalogue.get(catalogueName) ?? [];
     const existingIds = new Set(concatenated.map((r) => String(r["id"])));
-    const added = rederivedRows.filter((r) => !existingIds.has(String(r["id"])));
+    let added = rederivedRows.filter((r) => !existingIds.has(String(r["id"])));
+    const def = modelled.schema.catalogues.find((c) => c.name === catalogueName);
+    if (def?.sourceOfTruth === "structure") {
+        const subject = STRUCTURE_SUBJECT[catalogueName];
+        if (subject === undefined)
+            throw new Error(`rederiveAppend: ${catalogueName} is structure-sourced and names no subject column`);
+        const sddOf = new Map((modelled.rowsByCatalogue.get(subject.catalogue) ?? []).map((r) => [String(r["id"]), String(r["source_sdd_id"] ?? "")]));
+        const left = [];
+        added = added.filter((r) => {
+            const sdd = sddOf.get(String(r[subject.column] ?? "")) ?? "";
+            if (!modelled.modelSdds.has(sdd))
+                return true;
+            left.push(`${String(r["id"])} (${sdd})`);
+            return false;
+        });
+        if (left.length > 0) {
+            left.sort();
+            modelled.findings.add("divergence", `${catalogueName}: ${left.length} row(s) derived at aggregate tier left out: the ${subject.column.replace(/_id$/, "")}'s SDD holds a structural model, which states them (M-ADR 0230): ${left.slice(0, 5).join(", ")}${left.length > 5 ? `, and ${left.length - 5} more` : ""}`);
+        }
+    }
     rowsByCatalogue.set(catalogueName, [...concatenated, ...added]);
 }
 export function dedupExternalSystems(rowsByCatalogue, findings) {

package/dist/lib/catalogue/build.js

@@ -17,7 +17,10 @@
  * smoke test that the infrastructure works end-to-end on any SDD repo.
  */
 import { overlayModel } from "../structure/catalogue.js";
+import { agreedOrder } from "../structure/compose.js";
+import { Additions, intendedWrites, loadOpenChanges, splitDangling } from "../structure/intended.js";
 import { buildDataModelElements, readDataModelSources } from "./builders/data-model.js";
+import { enrichEntityArchetype } from "./builders/entity-archetype.js";
 import { removeRetiredCatalogues } from "./retired-catalogues.js";
 import { loadModel } from "../structure/model.js";
 import { viewOf } from "../structure/view.js";
@@ -41,7 +44,7 @@ import { buildEvidenceTargetRepos } from "./builders/evidence-target-repo.js";
 import { buildRepoDependencies } from "./builders/repo-dependency.js";
 import { buildRequirements } from "./builders/requirements.js";
 import { deriveAdrGoverns } from "./builders/adr-governs.js";
-import { buildContractRevisions } from "./builders/contract-revisions.js";
+import { contractRevisionsAndDeprecations } from "./builders/contract-revisions.js";
 import { buildJourneyRequirement } from "./builders/journey-requirement.js";
 import { buildDomains, buildProducts, buildApplicationDataPlaneBindings, buildApplicationDataPlaneDeviations, buildApplicationConformanceCoverage, buildImplementations, buildRepositories, buildServices, buildCapabilities, buildCapabilityService, buildCapabilityAdr, buildCapabilityFeature, buildCapabilityContract, buildAdrs, buildAdrSupersedes, buildFeatures, buildFeatureGroups, buildFeatureGrounding, buildCapabilitySpec, buildContracts, buildDeclaredExternalContracts, buildRepoEdges, deriveFeatureRepoFromServices, buildRepoCapabilityExemption, buildServiceCapabilityExemption, buildEvents, buildServiceEvent, buildCapabilityEvent, buildFeatureEvent, buildServiceContract, buildServiceContractConsumes, buildFeatureContract, buildDomainModels, buildCapabilityDomainModel, buildFeatureDomainModel, buildFeatureSubscriptionChannels, buildProductPlatformDependencies, buildGlossaryItems, backfillGlossaryRelations, buildGlossaryXref, buildC4Systems, buildC4Containers, buildC4Components, buildC4ExternalSystems, buildExternalSystemExemption, buildContainerDependency, reportEntryIdReferentCollisions, buildSystemExternalDependency, buildPersonaC4System, buildPersonaContainer, buildPersonas, buildQualityScores, buildScaffolds, buildScreens, buildUserJourneys, buildPersonaJourney, buildPersonaFeature, buildJourneyFeature, buildProductEdges, buildIntegrations, entitySlug, buildEntitiesFromManifest, buildEntitiesFromMermaid, buildServiceEntityFromTables, enrichEntityPersistenceKind, buildC4ContainerEntity, buildC4SystemEntity, } from "./builders/index.js";
 import { mergeEntities } from "./builders/entity-merge.js";
@@ -79,12 +82,17 @@ export async function runCatalogueBuild(inputs, write) {
     }
     const collected = await collectRows(schema, manifest, findings, sddPath, inputs.snapshotStore);
     // 3 (then). Where the SDD has a structural model, it is the record of structure: every structure catalogue is built from
-    // its current view, and what the sources say otherwise is reported (M-ADR 0230 §4.3, Proposed).
+    // its current view, and what the sources say otherwise is reported (M-ADR 0230 §4.3).
+    // An agreed open change's elements, stated by the sources ahead of its archive, are intended, not divergent (§4.7).
     const modelProblems = [];
     const modelFiles = await loadModel(sddPath, modelProblems);
-    const rowsByCatalogue = modelFiles === null ? collected : overlayModel(schema, viewOf(modelFiles, modelProblems), collected, findings);
+    const { open, newContracts } = await loadOpenChanges(sddPath, []);
+    const intendedRows = [];
+    const rowsByCatalogue = modelFiles === null
+        ? collected
+        : overlayModel(schema, viewOf(modelFiles, modelProblems), collected, findings, intendedWrites(open, agreedOrder(open)), intendedRows);
     for (const p of modelProblems)
-        findings.add("convention", `${p} (M-ADR 0230, Proposed)`);
+        findings.add("convention", `${p} (M-ADR 0230)`);
     // 3a. Normalise every keyed catalogue to PK-unique rows. Multi-source edge
     // tables (feature_service, feature_repo) can have the same fact asserted by
     // more than one walker; each walker's own seen-set only dedupes intra-walker.
@@ -141,7 +149,13 @@ export async function runCatalogueBuild(inputs, write) {
     // SDD profile so profile-external FKs (schema 2.23.0, e.g. an app/integration
     // capability's platform-resident domain_id per M-ADR 0136) resolve at
     // aggregation instead of failing this local build.
-    const { fk, enums } = await validateWithEngineToLog(schema, rowsByCatalogue, findings, { profile: manifest.profile });
+    const { fk: engineFk, enums } = await validateWithEngineToLog(schema, rowsByCatalogue, findings, { profile: manifest.profile });
+    // 5a. A row an open change owns (its change_id, or a contract its record agrees as new) resolves against what that
+    // change adds; any other row naming an addition is a current reference to an intended element, and still dangles
+    // (M-ADR 0230 §4.7, §4.11 proof 3).
+    const additions = new Additions(open, newContracts, rowsByCatalogue.get("contracts") ?? []);
+    const split = splitDangling(schema, rowsByCatalogue, engineFk.internalFailures, additions, manifest.sddId);
+    const fk = { ...engineFk, internalPass: split.dangling.length === 0, internalFailures: split.dangling.map((d) => d.failure) };
     // 5b. Bound-enum validation (M-ADR 0203 §4.1): every column_enums-bound
     // column hard-fails on an out-of-set value, like a dangling internal FK.
     // The canonical builder cannot emit a non-canonical c4_containers.type
@@ -173,10 +187,24 @@ export async function runCatalogueBuild(inputs, write) {
     }
     else {
         write(`\nFK validation (internal): FAIL (${fk.internalFailures.length} dangling)\n`);
-        for (const f of fk.internalFailures) {
-            write(`  ${f.catalogue}.${f.column}: row pk=${f.referencingRow} → ${f.target}=${f.value || "<empty>"}\n`);
+        for (const { failure: f, addedBy } of split.dangling) {
+            write(`  ${f.catalogue}.${f.column}: row pk=${f.referencingRow} → ${f.target}=${f.value || "<empty>"}` +
+                (addedBy === undefined
+                    ? ""
+                    : ` (open change ${addedBy} adds it, and nothing ties this row to that change: a current reference to an intended element)`) +
+                `\n`);
         }
     }
+    if (split.intended.length > 0) {
+        write(`Intended references: ${split.intended.length}, each made by an open change's own row to what that change adds\n`);
+        for (const { failure: f, change } of split.intended) {
+            write(`  ${f.catalogue}.${f.column}: row pk=${f.referencingRow} → ${f.target}=${f.value} (${change})\n`);
+        }
+    }
+    if (intendedRows.length > 0) {
+        write(`Intended elements: ${intendedRows.length} source row(s) state what an agreed open change adds or modifies, ` +
+            `catalogued once it archives: ${[...intendedRows].sort().join(", ")}\n`);
+    }
     if (enums.pass) {
         write(`Enum validation (column_enums): PASS (${validatedPopulation(rowsByCatalogue)})\n`);
     }
@@ -1194,10 +1222,16 @@ async function collectRows(schema, manifest, findings, sddPath, snapshotStore) {
         out.set("changes", r.changes);
         out.set("change_work_order", r.workOrders);
         out.set("change_work_item", r.workItems);
-        // M-ADR 0230 §4.2 (Proposed): which view each decision governs, now the store's changes are known.
+        // M-ADR 0230 §4.2: which view each decision governs, now the store's changes are known.
         out.set("adrs", deriveAdrGoverns(out.get("adrs") ?? [], out.get("adr_supersedes") ?? [], r.changes, findings));
-        // M-ADR 0230 §4.2 (Proposed): each contract's revisions by digest, active beside agreed.
-        out.set("contract_revisions", await buildContractRevisions({ sddPath, findings, contracts: out.get("contracts") ?? [], changes: r.changes }));
+        // M-ADR 0230 §4.2: each contract's revisions by digest, active beside agreed.
+        const revisions = await contractRevisionsAndDeprecations({ sddPath, findings, contracts: out.get("contracts") ?? [], changes: r.changes });
+        out.set("contract_revisions", revisions.rows);
+        // A version an archived change deprecated (agreement record 1.3.0) is deprecated in contracts too, whether or
+        // not its file is in this SDD.
+        const deprecated = revisions.deprecated;
+        if (deprecated.size > 0)
+            out.set("contracts", (out.get("contracts") ?? []).map((c) => (deprecated.has(String(c["id"])) ? { ...c, status: "deprecated" } : c)));
         // M-ADR 0229 §4.4: the requirements each journey cites, from its tagged end-to-end files or its
         // journey feature's living spec.
         out.set("journey_requirement", await buildJourneyRequirement({
@@ -1426,8 +1460,20 @@ async function collectRows(schema, manifest, findings, sddPath, snapshotStore) {
         entityIdBySlug,
         entityRows,
     });
-    out.set("entities", enrichedEntityRows);
-    // 17a. The domain models' own content (M-ADR 0230 §4.3, §4.11 proof 7, Proposed; schema 6.0.0): each entity's
+    // Schema 7.1.0: the PPT archetype, from the capability specs' Entity Classification tables, in an SDD without a
+    // structural model; with one, the model holds it (M-ADR 0230 §4.3).
+    const hasModel = await stat(join(sddPath, "openspec", "structure")).then(() => true, () => false);
+    out.set("entities", hasModel
+        ? enrichedEntityRows
+        : await enrichEntityArchetype({
+            sddPath,
+            findings,
+            capabilities: (out.get("capabilities") ?? []).map((r) => ({ spec_path: String(r["spec_path"] ?? ""), domain_id: String(r["domain_id"] ?? "") })),
+            entityIdByDomainSlug,
+            entityIdBySlug,
+            entityRows: enrichedEntityRows,
+        }));
+    // 17a. The domain models' own content (M-ADR 0230 §4.3, §4.11 proof 7; schema 6.0.0): each entity's
     // attributes, the relationships with both ends' cardinality and roles, and the keys as invariants, from the same
     // parse the entities came from.
     const dataModel = buildDataModelElements(await readDataModelSources(sddPath, domainModels.map((r) => ({ id: String(r["id"]), domainId: String(r["domain_id"]), docPath: String(r["doc_path"]) }))), enrichedEntityRows, findings);

package/dist/lib/catalogue/builders/adr-governs.js

@@ -18,7 +18,7 @@ export function deriveAdrGoverns(adrs, supersedes, changes, findings) {
         }
         const state = changeState(change);
         if (state === "absent")
-            findings.add("convention", `${String(a["doc_path"])}: effective on archive of ${change}, which is no change in this store; the decision governs nothing until it is (M-ADR 0230 §4.2, Proposed)`);
+            findings.add("convention", `${String(a["doc_path"])}: effective on archive of ${change}, which is no change in this store; the decision governs nothing until it is (M-ADR 0230 §4.2)`);
         accepted.set(String(a["id"]), state === "archived" ? "current" : state === "open" ? "intended" : "none");
     }
     const successors = new Map();

package/dist/lib/catalogue/builders/adrs.js

@@ -19,7 +19,7 @@
 //   - **Date:** YYYY-MM-DD
 //   - **Supersedes:** raw text (captured into supersedes_raw for the
 //     adr_supersedes builder to parse)
-//   - **Effective:** `on acceptance` (the default) or `on archive of <change>` (M-ADR 0230 §4.2, Proposed):
+//   - **Effective:** `on acceptance` (the default) or `on archive of <change>` (M-ADR 0230 §4.2):
 //     effective_change holds the change; governs is derived once the store's changes are known (adr-governs.ts)
 //
 // ID canonicalisation: filename stem `ADR XXXX[: Title]` → `ADR-{0-padded}`.
@@ -85,7 +85,7 @@ export async function buildAdrs(inputs) {
         const effectiveRaw = (extractField(text, "Effective") || "").trim();
         const onArchive = /^on archive of\s+`?([A-Za-z0-9][A-Za-z0-9._-]*)`?\s*\.?$/i.exec(effectiveRaw);
         if (effectiveRaw !== "" && !onArchive && !/^on acceptance\.?$/i.test(effectiveRaw)) {
-            inputs.findings.add("convention", `${relPath}: **Effective:** is "${effectiveRaw}", neither "on acceptance" nor "on archive of <change>"; read as on acceptance (M-ADR 0230 §4.2, Proposed)`);
+            inputs.findings.add("convention", `${relPath}: **Effective:** is "${effectiveRaw}", neither "on acceptance" nor "on archive of <change>"; read as on acceptance (M-ADR 0230 §4.2)`);
         }
         const effectiveChange = onArchive?.[1] ?? "";
         if (scope === "domain" && !inputs.knownDomainIds.has(domainId)) {

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

@@ -1,9 +1,12 @@
-// contract_revisions: a contract version's content revisions, by digest (M-ADR 0230 §4.2, Proposed; schema 6.0.0).
+// contract_revisions: a contract version's content revisions, by digest (M-ADR 0230 §4.2; schema 6.0.0).
 //   active      the contract file's current content (deprecated where the contract is)
 //   agreed      a revision an agreed open change agrees (agreement record 1.2.0, contracts[].agrees)
 //   retired     a revision an archived change agreed that the file no longer holds
+//   deprecated  the active revision, where an archived change's record deprecates the version (record 1.3.0,
+//               contracts[].deprecates: {sunset}), with that sunset and that change; the latest archive wins
 // An archived change that agreed the current content is the active revision's change. A compatible amendment is a
-// new revision at the same path, so an agreed revision and the active one coexist.
+// new revision at the same path, so an agreed revision and the active one coexist. A deprecation an open change
+// states is intended, not current, and moves no row until the change archives.
 //
 // A record names a contract by the file in its own repository (`file:`, or a `files:` list), which the catalogue holds
 // under the SDD's mount of that repository; so a record's file matches the contract whose spec_path ends with it, and
@@ -16,11 +19,12 @@ import { join } from "node:path";
 import { parse as parseYaml } from "yaml";
 const AGREEMENTS = join("docs", "agreements");
 const DIGEST = /^sha256:[0-9a-f]{64}$/;
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
 export function contentDigest(bytes) {
     return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
 }
 const revisionId = (contract, digest) => `${contract}@${digest.slice("sha256:".length, "sha256:".length + 12)}`;
-/** Each (file, relies_on, agrees) a record's contracts list pins. */
+/** Each (file, relies_on, agrees, deprecates) a record's contracts list pins. */
 function pins(record, where, findings) {
     const r = record?.agreement_record;
     if (!Array.isArray(r?.contracts))
@@ -44,16 +48,32 @@ function pins(record, where, findings) {
             }
             return d;
         };
+        // `deprecates: {sunset}` deprecates the version at each of the entry's files.
+        let deprecates;
+        if (c["deprecates"] !== undefined) {
+            const sunset = c["deprecates"]?.sunset;
+            if (typeof sunset === "string" && DATE.test(sunset))
+                deprecates = sunset;
+            else
+                findings.add("convention", `${where}: contracts[${i}].deprecates is {sunset: YYYY-MM-DD}; it deprecates nothing as written`);
+        }
         for (const file of files) {
             const reliesOn = digestFor("relies_on", file);
             const agrees = digestFor("agrees", file);
-            if (reliesOn || agrees)
-                out.push({ file, ...(reliesOn ? { reliesOn } : {}), ...(agrees ? { agrees } : {}) });
+            if (reliesOn || agrees || deprecates)
+                out.push({ file, ...(reliesOn ? { reliesOn } : {}), ...(agrees ? { agrees } : {}), ...(deprecates ? { deprecates } : {}) });
         }
     }
     return out;
 }
 export async function buildContractRevisions(inputs) {
+    return (await contractRevisionsAndDeprecations(inputs)).rows;
+}
+/**
+ * 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.
+ */
+export async function contractRevisionsAndDeprecations(inputs) {
     const { sddPath, findings } = inputs;
     const rows = new Map();
     const current = new Map(); // contract id -> current digest
@@ -78,6 +98,8 @@ export async function buildContractRevisions(inputs) {
     catch {
         names = [];
     }
+    // contract id -> the latest archived deprecation of its version
+    const deprecations = new Map();
     for (const name of names) {
         const change = name.slice(0, -".yaml".length);
         const where = join(AGREEMENTS, name);
@@ -103,8 +125,14 @@ export async function buildContractRevisions(inputs) {
             }
             const contract = matches[0];
             const now = current.get(contract);
+            if (p.deprecates && archived) {
+                const archivedOn = String(archived["archived_on"] ?? "");
+                const prior = deprecations.get(contract);
+                if (!prior || `${archivedOn}\u0000${changeId}` > `${prior.archivedOn}\u0000${prior.changeId}`)
+                    deprecations.set(contract, { sunset: p.deprecates, changeId, archivedOn });
+            }
             if (state === "agreed" && p.reliesOn && now && p.reliesOn !== now) {
-                findings.add("divergence", `${where}: relies on revision ${p.reliesOn.slice(0, 19)}… of ${contract}, which has moved to ${now.slice(0, 19)}…; the change relies on a revision no longer published, so it is re-agreed (M-ADR 0230 §4.2, Proposed)`);
+                findings.add("divergence", `${where}: relies on revision ${p.reliesOn.slice(0, 19)}… of ${contract}, which has moved to ${now.slice(0, 19)}…; the change relies on a revision no longer published, so it is re-agreed (M-ADR 0230 §4.2)`);
             }
             if (!p.agrees)
                 continue;
@@ -121,6 +149,16 @@ export async function buildContractRevisions(inputs) {
                 rows.set(rid, { id: rid, contract_id: contract, digest: p.agrees, state: "retired", sunset_date: "", change_id: changeId, source_sdd_id: "", platform_sdd_id: "" });
         }
     }
-    return [...rows.values()].sort((a, b) => String(a["id"]).localeCompare(String(b["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.
+        const now = current.get(contract);
+        const rid = now ? revisionId(contract, now) : undefined;
+        const row = rid ? rows.get(rid) : undefined;
+        if (rid && row)
+            rows.set(rid, { ...row, state: "deprecated", sunset_date: d.sunset, change_id: d.changeId });
+    }
+    return { rows: [...rows.values()].sort((a, b) => String(a["id"]).localeCompare(String(b["id"]))), deprecated };
 }
 //# sourceMappingURL=contract-revisions.js.map

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

@@ -1,4 +1,4 @@
-// A domain model's content, parsed whole (M-ADR 0230 §4.3, §4.11 proof 7, Proposed; schema 6.0.0). One parser per
+// A domain model's content, parsed whole (M-ADR 0230 §4.3, §4.11 proof 7; schema 6.0.0). One parser per
 // notation, shared by every reader of the file: the entities builder takes its entities from here, and this module
 // builds entity_attributes, entity_relationships and domain_invariants from the same parse.
 //

package/dist/lib/catalogue/builders/entity-archetype.js

@@ -0,0 +1,121 @@
+// Catalogue schema 7.1.0: backfill `entities.ppt_archetype` from the capability specs' `## Entity Classification`
+// tables (M-ADR 0230 §4.3, at its acceptance).
+//
+// The archetype is a structure fact. Where the SDD has a structural model the model holds it, and the capability spec
+// template drops its table, so this reads the tables only in an SDD without a model: that build is what `migrate
+// structure` carries into a first model.
+//
+// Authored cells vary: "Party (Green)", "**Thing — audit record**", "Blue/Description", "Moment", "PartyRole". A cell's
+// archetype is the first one it names, colour labels and qualifiers aside. Moment alone is moment-interval, and
+// PartyRole is a role. A cell naming more than two is a list of options, not a classification, and names none.
+// What cannot be classified is reported, once per build, never guessed.
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { collectTableLines, detectColumn, entitySlug, splitRow } from "./data-store-mapping.js";
+export const PPT_ARCHETYPES = ["party", "place", "thing", "role", "moment-interval", "description"];
+const RE_HEADING = /^## Entity Classification\b/;
+const RE_TOKEN = /\b(?:moment[\s-]*interval|moment|party[\s-]*role|party|place|thing|role|description)/g;
+const EXAMPLES = 5;
+/** The archetypes a cell names, in order, each once. */
+export function archetypesNamed(cell) {
+    const out = [];
+    for (const m of cell.toLowerCase().matchAll(RE_TOKEN)) {
+        const t = m[0].replace(/[\s-]+/g, "");
+        const a = t.startsWith("moment") ? "moment-interval" : t === "partyrole" ? "role" : t;
+        if (!out.includes(a))
+            out.push(a);
+    }
+    return out;
+}
+/** A cell's archetype: the first it names, or null when it names none or more than two. */
+export function archetypeOf(cell) {
+    const named = archetypesNamed(cell);
+    return named.length === 0 || named.length > 2 ? null : named[0];
+}
+/** The entity a row's first cell names: markup and a trailing qualifier stripped. */
+function entityName(cell) {
+    return cell
+        .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")
+        .replace(/[*`_]/g, "")
+        .split(/\s+[—–-]\s+/)[0]
+        .replace(/\s*\([^)]*\)\s*$/, "")
+        .trim();
+}
+function sample(xs) {
+    return xs.slice(0, EXAMPLES).join(", ") + (xs.length > EXAMPLES ? `, and ${xs.length - EXAMPLES} more` : "");
+}
+export async function enrichEntityArchetype(inputs) {
+    // A spec in the entity's own domain outranks one that reaches it by the cross-domain fallback; otherwise the first wins.
+    const chosen = new Map();
+    const several = [];
+    const none = [];
+    const unresolved = [];
+    const disagree = new Set();
+    const specs = [...new Map(inputs.capabilities.filter((c) => c.spec_path !== "").map((c) => [c.spec_path, c])).values()].sort((a, b) => a.spec_path.localeCompare(b.spec_path));
+    for (const cap of specs) {
+        let text;
+        try {
+            text = await readFile(join(inputs.sddPath, cap.spec_path), "utf8");
+        }
+        catch {
+            continue;
+        }
+        const lines = text.split(/\r?\n/);
+        const at = lines.findIndex((l) => RE_HEADING.test(l));
+        if (at === -1)
+            continue;
+        const table = collectTableLines(lines, at + 1);
+        if (table === null || table.length < 3)
+            continue;
+        const headers = splitRow(table[0]);
+        const col = detectColumn(headers, (h) => h.includes("archetype") || h.includes("ppt"));
+        if (col === -1)
+            continue;
+        const entityCol = Math.max(0, detectColumn(headers, (h) => h.includes("entity") || h.includes("aggregate")));
+        for (const line of table.slice(2)) {
+            const cells = splitRow(line);
+            const name = entityName(cells[entityCol] ?? "");
+            // a separator, the template's placeholder row, or a header repeated inside the table
+            if (name === "" || /^[-:]+$/.test(name) || name.startsWith("{") || name.toLowerCase() === (headers[entityCol] ?? "").toLowerCase())
+                continue;
+            const where = `${cap.spec_path}: ${name}`;
+            const cell = cells[col] ?? "";
+            const named = archetypesNamed(cell);
+            const archetype = archetypeOf(cell);
+            if (archetype === null) {
+                none.push(`${where} (${JSON.stringify(cell)})`);
+                continue;
+            }
+            if (named.length > 1)
+                several.push(`${where} (${JSON.stringify(cell)} read as ${archetype})`);
+            const slug = entitySlug(name);
+            const localId = inputs.entityIdByDomainSlug.get(`${cap.domain_id}|${slug}`);
+            const id = localId ?? inputs.entityIdBySlug.get(slug);
+            if (id === undefined) {
+                unresolved.push(where);
+                continue;
+            }
+            const mine = { archetype, spec: cap.spec_path, local: localId !== undefined };
+            const prior = chosen.get(id);
+            if (prior !== undefined && prior.archetype !== archetype) {
+                const [kept, other] = mine.local && !prior.local ? [mine, prior] : [prior, mine];
+                disagree.add(`${id} (${kept.archetype} in ${kept.spec}, catalogued; ${other.archetype} in ${other.spec})`);
+            }
+            if (prior === undefined || (mine.local && !prior.local))
+                chosen.set(id, mine);
+        }
+    }
+    const report = (n, what, items) => {
+        if (n > 0)
+            inputs.findings.add("coverage", `entities.ppt_archetype: ${n} ${what}: ${sample([...items].sort())}`);
+    };
+    report(none.length, "Entity Classification row(s) name no archetype, so none is catalogued", none);
+    report(several.length, "Entity Classification row(s) name two archetypes; the first is catalogued", several);
+    report(unresolved.length, "Entity Classification row(s) name no entity of this SDD", unresolved);
+    report(disagree.size, "entities classified differently by two specs; the entity's own domain's spec, else the first, is catalogued", disagree);
+    return inputs.entityRows.map((r) => {
+        const c = chosen.get(String(r["id"]));
+        return c === undefined || String(r["ppt_archetype"] ?? "") !== "" ? r : { ...r, ppt_archetype: c.archetype };
+    });
+}
+//# sourceMappingURL=entity-archetype.js.map

package/dist/lib/catalogue/builders/quality-scores.js

@@ -119,7 +119,7 @@ const num = (v) => {
     return null;
 };
 /**
- * The review's other assessed inputs (M-ADR 0230 §4.9, Proposed): `inputs:` as a list of paths, or of `{path}`
+ * The review's other assessed inputs (M-ADR 0230 §4.9): `inputs:` as a list of paths, or of `{path}`
  * entries, each read at the review's corpus_ref. ';'-joined; null when the review names none.
  */
 function inputPaths(v) {

package/dist/lib/catalogue/builders/requirements.js

@@ -18,7 +18,7 @@
 //   change_work_order   per (change, repository): the record's work order, agreed or completed.
 //   change_work_item    per (change, work item): the ids its proposal's `## Work Items` section lists, keyed by
 //                       the undated name so the row survives archive.
-//   requirement_revisions  one row per distinct text of a requirement (schema 6.0.0, M-ADR 0230 §4.7, Proposed): the
+//   requirement_revisions  one row per distinct text of a requirement (schema 6.0.0, M-ADR 0230 §4.7): the
 //                       living spec's is current, an agreed open change's ADDED or MODIFIED block intended, an
 //                       archived change's block the living spec no longer holds history. Identified by its digest.
 //   requirement_assertions per (revision, repository): observed from a baseline's `**Observed in:**` line;