@sdd-method/author-cli 0.12.1 → 0.14.0

package/README.md

@@ -2,6 +2,6 @@
 
 `sdd-author` is for the people and agents who own one SDD's content. It re-authors that content and **cannot move the baseline or rebuild the model** (M-ADR 0220).
 
-Verbs: everything in `@sdd-method/verify-cli`, plus `scaffold domain`, `plan`, `contracts attest`, `conformance`, `api-surface`, the `snapshot` verbs, `render screen`, `generate-briefing`, `context pull` and `catalogue check`.
+Verbs: everything in `@sdd-method/verify-cli`, plus `scaffold domain`, `plan`, `contracts attest`, `conformance`, `api-surface`, the `snapshot` verbs, `render screen`, `generate-briefing`, `context pull`, `catalogue check`, and the structural model's `migrate structure` and `change archive`.
 
 `catalogue check` reports whether the committed catalogues are what the committed specifications build to, and writes nothing. Rebuilding them (`catalogue build`), `sync` and `pack build` are in `@sdd-method/maintain-cli`; `init` and the administrator's verbs are in `@sdd-method/sdd-cli`. They are not present in this package, and invoking one fails with exit 1.

package/dist/author-program.js

@@ -5,8 +5,8 @@
 // (0220 §4.1): both carry the whole verify surface, and the author adds what 0220 §4.2 gives it —
 // new artefacts and plans (`scaffold`, `plan`), the evidence and findings it triages (`contracts`,
 // `conformance`, `api-surface`, the `snapshot` verbs), the projections maintain also holds
-// (`render screen`, `generate-briefing`, `context pull`), and `catalogue check`, which reports a
-// stale model and writes nothing.
+// (`render screen`, `generate-briefing`, `context pull`), `catalogue check`, which reports a
+// stale model and writes nothing, and the structural model it authors (`migrate structure`, `change archive`).
 //
 // Not here, by design: `sync`, `catalogue build | aggregate | graph | diff` and `pack build`
 // (maintain's), and `init`, `metamodel roundtrip` and `catalogue migration-map` (sdd-cli's,
@@ -18,11 +18,13 @@ import { getPackageVersion } from "./lib/package-version.js";
 import { registerVerifySurface, rejectOutsideSurface, VERIFY_SURFACE } from "./verify-program.js";
 import { registerApiSurface } from "./verbs/api-surface.js";
 import { registerCatalogueCheck } from "./verbs/catalogue-check.js";
+import { registerChange } from "./verbs/change.js";
 import { registerConformance } from "./verbs/conformance.js";
 import { registerContext } from "./verbs/context.js";
 import { registerContracts } from "./verbs/contracts.js";
 import { registerGenerateBriefing } from "./verbs/generate-briefing.js";
 import { registerMigrate } from "./verbs/migrate.js";
+import { registerMigrateStructure } from "./verbs/migrate-structure.js";
 import { registerPlan } from "./verbs/plan.js";
 import { registerRender } from "./verbs/render.js";
 import { registerScaffold } from "./verbs/scaffold.js";
@@ -48,6 +50,8 @@ export const AUTHOR_ONLY_SURFACE = [
     "catalogue check",
     "migrate vocabulary",
     "migrate intents",
+    "migrate structure",
+    "change archive",
 ];
 /** The full surface: verify's, plus the author's own. */
 export const AUTHOR_SURFACE = [...VERIFY_SURFACE, ...AUTHOR_ONLY_SURFACE];
@@ -88,6 +92,7 @@ export function buildAuthorProgram() {
     registerVerifySurface(program);
     registerScaffold(program);
     registerMigrate(program);
+    registerMigrateStructure(program);
     registerPlan(program);
     registerContracts(program);
     registerConformance(program);
@@ -96,6 +101,9 @@ export function buildAuthorProgram() {
     registerRender(program);
     registerGenerateBriefing(program);
     registerContext(program);
+    // The structural model is authored content: its first extraction, and a judged change's archive into it (M-ADR 0230
+    // §4.6, §6).
+    registerChange(program);
     const catalogue = program.commands.find((c) => c.name() === "catalogue");
     catalogue.description("Validate and query per-SDD catalogues (M-ADR 0134), and check them for staleness — never rebuilds");
     registerCatalogueCheck(catalogue);

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;

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