@sdd-method/maintain-cli 0.13.1 → 0.15.0

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,13 +347,13 @@ 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)`);
         }
     }
-    // M-ADR 0229 §4.4 (Proposed): journey_requirement re-derived over the merged rows. A journey is often catalogued
+    // M-ADR 0229 §4.4: journey_requirement re-derived over the merged rows. A journey is often catalogued
     // in an application SDD and the requirements its steps cite in the platform's behaviour store, so neither member
     // holds both join inputs; each reports the tag as external. Each contributor's tagged end-to-end files (its own
     // manifest's journeys.test_paths) and its journey features' living specs are read again here against the MERGED
@@ -397,10 +406,10 @@ 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, Proposed; ${contributors.length} contributor(s) read)`);
+            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)`);
         }
         for (const u of unresolved)
             findings.add("orphan", `journey_requirement: unresolved against the merged catalogue: ${u}`);
@@ -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) {
@@ -2106,12 +2143,12 @@ export function rekeyLegacyContractRefs(schema, rowsByCatalogue, findings) {
         rowsByCatalogue.set(cat.name, kept);
         for (const [oldId, count] of [...perOldId.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
             findings.add("inferred", `${cat.name}: ${count} cross-SDD reference(s) to "${oldId}" re-keyed to "${legacyMap.get(oldId)[0]}" — ` +
-                `2.x kindless contract id migrated per the 3.0.0 map (regenerable, not drift; M-ADR 0203 §4.4)`);
+                `an earlier-form contract id (2.x kindless, or a pre-7.0.0 unsplit stem) migrated per the contract-id map (regenerable, not drift; M-ADR 0203 §4.4)`);
         }
         for (const [oldId, targets] of [...ambiguousOld.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
             ambiguous++;
-            findings.add("convention", `${cat.name}: references to "${oldId}" map to ${targets.length} contracts at 3.0.0 [${targets.join(", ")}] — ` +
-                `a 2.x cross-family collision; the referencing SDD must qualify with the kind-suffixed id; left dangling (M-ADR 0203 §4.4)`);
+            findings.add("convention", `${cat.name}: references to "${oldId}" map to ${targets.length} current contracts [${targets.join(", ")}] — ` +
+                `a cross-family collision under the earlier form; the referencing SDD must qualify with the current id; left dangling (M-ADR 0203 §4.4)`);
         }
     }
     return { rekeyed, deduped, ambiguous };

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,9 +44,11 @@ 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";
+import { loadAliasMap } from "./builders/service-entity-tables.js";
 import { buildIntegrationComponents } from "./builders/integration-components.js";
 import { loadReverseProductQuality } from "./reverse-product-quality.js";
 import { loadTraceabilityManifests } from "./traceability-loader.js";
@@ -77,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.
@@ -139,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
@@ -171,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`);
     }
@@ -895,8 +925,8 @@ async function collectRows(schema, manifest, findings, sddPath, snapshotStore) {
         findings,
         knownServiceIds,
         aliases: serviceContractAliases,
-        // M-ADR 0203 §4.4 cut window: alias targets authored as 2.x kindless
-        // contract ids re-key against this build's kind-suffixed rows.
+        // M-ADR 0203 §4.4 cut window: alias targets authored as 2.x kindless contract ids, or with a pre-7.0.0
+        // unsplit stem, re-key against this build's rows.
         legacyContractIdMap: buildLegacyContractIdMap(out.get("contracts") ?? []),
     });
     out.set("service_contract", [...exposesRows, ...consumesRows]);
@@ -1192,11 +1222,17 @@ 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 0229 §4.4 (Proposed): the requirements each journey cites, from its tagged end-to-end files or its
+        // 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({
             sddPath,
@@ -1229,6 +1265,8 @@ async function collectRows(schema, manifest, findings, sddPath, snapshotStore) {
         findings,
         knownSystemIds,
         knownServiceIds,
+        // A malformed alias file is reported by the service_entity walker; not twice.
+        serviceIdByDisplayLower: (await loadAliasMap(sddPath, new FindingsLog())).byDisplayLower,
         knownDomainIds,
         containerIdByEntryIdOut: containerIdByEntryId,
         containerNameByEntryIdOut: containerNameByEntryId,
@@ -1343,12 +1381,14 @@ async function collectRows(schema, manifest, findings, sddPath, snapshotStore) {
     //     c4_containers.service_id.
     //   - c4-system-entity: aggregation roll-up over c4_container_entity ⋈
     //     c4_containers.system_id with container_count.
+    const platformWideEntityIds = new Set();
     const entitiesFromManifest = await buildEntitiesFromManifest({
         sddPath,
         findings,
         profile: manifest.profile,
         knownDomainIds,
         knownGlossaryIds,
+        platformWideIdsOut: platformWideEntityIds,
     });
     const entitiesFromMermaid = await buildEntitiesFromMermaid({
         sddPath,
@@ -1361,13 +1401,8 @@ async function collectRows(schema, manifest, findings, sddPath, snapshotStore) {
         knownGlossaryIds,
     });
     // Forward wins on attribute conflicts (matches per-adopter authoring intent
-    // per M-ADR 0159 §4.4). Reverse rows seed the map; forward overwrites.
-    const entitiesById = new Map();
-    for (const r of entitiesFromMermaid)
-        entitiesById.set(String(r["id"]), r);
-    for (const r of entitiesFromManifest)
-        entitiesById.set(String(r["id"]), r);
-    const entityRows = [...entitiesById.values()];
+    // per M-ADR 0159 §4.4), field by field; a platform-wide entry naming one domain entity is that entity.
+    const entityRows = mergeEntities(entitiesFromMermaid, entitiesFromManifest, findings, platformWideEntityIds);
     out.set("entities", entityRows);
     // Per M-ADR 0159 §4.9: now that entities.csv exists, append entity_glossary
     // rows for the reverse-method side. The forward-method emission via
@@ -1391,7 +1426,9 @@ async function collectRows(schema, manifest, findings, sddPath, snapshotStore) {
             domain_id: domainId,
             entity_name: name,
             glossary_item_id: glossaryId,
-            status: "matched_direct",
+            // A manifest entry folded into this entity keeps the alignment it was authored with; a data-model slug match
+            // is direct.
+            status: /(?:^|;)status=aligned(?:;|$)/.test(String(e["notes"] ?? "")) ? "aligned" : "matched_direct",
             source_sdd_id: "",
         });
     }
@@ -1423,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/c4-containers.js

@@ -11,7 +11,8 @@
 //   - domain_id (nullable, denormalised) derived from the L2 file path:
 //     docs/domains/<slug>/... → <slug>; platform-wide L2 → empty.
 //   - service_id (optional) — opportunistic match on the C4 entry's id
-//     or a slug of its display name to a known service id.
+//     or a slug of its display name to a known service id, then on its
+//     display name through service-name-aliases.yaml.
 //
 // We only consider entries inside System_Boundary or Container_Boundary
 // blocks — mirrors the python reference and excludes Person/System_Ext
@@ -90,11 +91,14 @@ export async function buildC4Containers(inputs) {
                 continue;
             }
             seen.add(id);
+            const aliased = inputs.serviceIdByDisplayLower?.get(entry.name.toLowerCase()) ?? "";
             const serviceId = inputs.knownServiceIds.has(entry.entryId)
                 ? entry.entryId
                 : inputs.knownServiceIds.has(slug)
                     ? slug
-                    : "";
+                    : inputs.knownServiceIds.has(aliased)
+                        ? aliased
+                        : "";
             const domainId = file.domainId !== "" && inputs.knownDomainIds.has(file.domainId)
                 ? file.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/contracts.js

@@ -18,7 +18,7 @@
 import { readdir, readFile } from "node:fs/promises";
 import { extname, join, relative, sep } from "node:path";
 import { parse as parseYaml } from "yaml";
-import { contractIdWithKind } from "../contract-id.js";
+import { contractIdWithKind, contractKindlessSlug } from "../contract-id.js";
 const CONTRACTS_DIR_REL = "contracts";
 const DOCS_DOMAINS_DIR_REL = join("docs", "domains");
 const KIND_SPECS = [
@@ -117,8 +117,8 @@ export async function buildContracts(inputs) {
         // this format exists to end. A remaining collision is same-kind and
         // still reported.
         const kindless = entry.domain !== ""
-            ? slugify(`${entry.domain}-${stem}`)
-            : slugify(stem);
+            ? contractKindlessSlug(entry.domain, stem)
+            : contractKindlessSlug("", stem);
         const slug = contractIdWithKind(kindless, entry.kind);
         if (seen.has(slug)) {
             inputs.findings.add("divergence", `${entry.relPath}: contract id "${slug}" already emitted by an earlier file`);
@@ -311,13 +311,6 @@ function domainSegmentCanonical(relPath) {
         return "";
     return parts[2] ?? "";
 }
-function slugify(s) {
-    return s
-        .toLowerCase()
-        .replace(/^_+/, "") // turn _common into common
-        .replace(/[^a-z0-9]+/g, "-")
-        .replace(/^-+|-+$/g, "");
-}
 const DECLARED_KINDS = {
     openapi: "rest",
     proto: "rpc",
@@ -366,7 +359,7 @@ export function buildDeclaredExternalContracts(inputs) {
                 if (inputs.discoveredIdByPath.has(declared) || localBasenames.has(base))
                     continue;
                 const stem = stemOf(base);
-                const kindless = m.domain !== "" ? slugify(`${m.domain}-${stem}`) : slugify(stem);
+                const kindless = contractKindlessSlug(m.domain, stem);
                 const slug = contractIdWithKind(kindless, kind);
                 if (seenDeclaredPaths.has(declared)) {
                     // Same path, same contract: legitimate cross-capability sharing.

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/entities-manifest.js

@@ -24,8 +24,8 @@
 // - For each entities[] item with non-empty name, emit a row.
 // - Within-model dedup by id; if attributes diverge, fire [finding] divergence
 //   on first re-encounter.
-// - `status: superseded` entries carry extra `superseded_by` + `note` keys.
-//   Ingested as ordinary rows; superseded_by preserved in notes for future
+// - `status: superseded` entries emit no entity: a superseded term is history, and glossary_xref carries
+//   its supersedes edge (schema 7.0.0). Formerly ingested as ordinary rows; superseded_by preserved in notes for future
 //   Phase 5 promotion to an entity_supersedes edge.
 // - `glossary_term` resolved best-effort against glossary_items (exact term
 //   then entitySlug equality); leave empty and fire orphan on miss.
@@ -34,8 +34,8 @@ import { join } from "node:path";
 import { parse as parseYaml } from "yaml";
 import { entitySlug } from "./entity-slug.js";
 const MANIFEST_REL_PATH = join("docs", "platform", "reference", "glossary-alignment-manifest.yaml");
-const NON_CANONICAL_DOMAINS = new Set(["platform-wide", "", "platform_wide"]);
-const PLATFORM_WIDE_PK_PREFIX = "_platform-wide";
+export const NON_CANONICAL_DOMAINS = new Set(["platform-wide", "", "platform_wide"]);
+export const PLATFORM_WIDE_PK_PREFIX = "_platform-wide";
 export async function buildEntitiesFromManifest(inputs) {
     // Profile gate per M-ADR 0159 §4.2 amendment: only platform-profile SDDs
     // read the manifest. Sibling profiles (application-product, integration-
@@ -93,6 +93,10 @@ export async function buildEntitiesFromManifest(inputs) {
                 inputs.findings.add("convention", `${MANIFEST_REL_PATH}: model ${model.path ?? "(unknown)"} has an entities[] entry with empty name — skipped`);
                 continue;
             }
+            // A superseded entry is history, not an element: the glossary keeps its supersedes edge (glossary_xref), and
+            // the entity it names is its successor's.
+            if (String(entity.status ?? "").trim() === "superseded")
+                continue; // as glossary_xref reads it
             const slug = entitySlug(name);
             const id = domainId
                 ? `${domainId}-${slug}`
@@ -128,6 +132,8 @@ export async function buildEntitiesFromManifest(inputs) {
             }
             byId.set(id, row);
             rows.push(row);
+            if (NON_CANONICAL_DOMAINS.has(rawDomain))
+                inputs.platformWideIdsOut?.add(id);
         }
     }
     return rows;