@sdd-method/author-cli 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,119 @@
+// Domain discoverer — emits `domains.csv` rows from `docs/domains/<slug>/`.
+//
+// Per ADR 0134 and catalogue-builder-specification.md:
+//   - Domains are method-defined: each subdirectory under docs/domains/
+//     is one domain, named by its slug.
+//   - method_profile reflects the SDD's profile (the domain belongs to
+//     this SDD's method profile).
+//   - repo_count is computed by the build orchestrator after repositories
+//     are discovered, since this builder runs first.
+//
+// Per ADR 0136 ("App and Integration Products Do Not Belong to a Primary
+// Domain"), only platform-profile SDDs own domains. Application-product
+// and integration-product SDDs may have a `docs/domains/<umbrella>/`
+// subdirectory as a structural-organisation convention (where their
+// feature-trees and per-app evidence live), but those subdirectories
+// don't represent domain ownership — they're just where the SDD's
+// artefacts are organised. Emitting a domain row from a non-platform
+// profile creates a duplicate-PK collision at aggregation time when the
+// platform-profile SDD also emits a row for the same umbrella id (e.g.
+// `applications`, `integrations`).
+//
+// The platform-profile SDD is the canonical owner; member SDDs reference
+// their umbrella implicitly via profile + their own identity, not via
+// a redundant domain row. This builder therefore returns an empty list
+// for non-platform-profile SDDs.
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+const DOMAINS_DIR_REL = join("docs", "domains");
+export async function buildDomains(inputs) {
+    // Per ADR 0136: only platform-profile SDDs own domains. Non-platform
+    // SDDs return an empty list to avoid duplicate-PK collisions at
+    // aggregation against the canonical platform-profile contribution.
+    if (inputs.manifest.profile !== "platform-profile") {
+        return [];
+    }
+    const domainsDir = join(inputs.sddPath, DOMAINS_DIR_REL);
+    let entries;
+    try {
+        entries = (await readdir(domainsDir, { withFileTypes: true }))
+            .filter((e) => e.isDirectory())
+            .map((e) => ({ name: e.name }));
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            inputs.findings.add("coverage", `${DOMAINS_DIR_REL}/ not found - emitting empty domains.csv`);
+            return [];
+        }
+        throw err;
+    }
+    const rows = [];
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        const slug = entry.name;
+        const description = await readDomainDescription(join(domainsDir, slug), inputs.findings, slug);
+        rows.push({
+            id: slug,
+            name: titleCase(slug),
+            description,
+            method_profile: inputs.manifest.profile,
+            reference_architecture_equivalent: "",
+            // "active" is correct vocabulary here (active | deferred | absent):
+            // a domain directory that exists on disk is active by definition.
+            // deferred/absent rows have no authoring source yet — they would come
+            // from roadmap/archetype declarations, not directory discovery.
+            status: "active",
+            repo_count: 0, // populated by orchestrator after repositories build
+            source_sdd_id: "",
+        });
+    }
+    return rows;
+}
+/**
+ * Look for a one-line description in a domain README. Falls back to
+ * empty when no README or no usable first paragraph is present.
+ */
+async function readDomainDescription(domainDir, findings, slug) {
+    const candidates = ["README.md", "README.markdown"];
+    for (const name of candidates) {
+        const path = join(domainDir, name);
+        try {
+            const s = await stat(path);
+            if (!s.isFile())
+                continue;
+            const text = await readFile(path, "utf-8");
+            const firstPara = extractFirstParagraph(text);
+            if (firstPara)
+                return firstPara.slice(0, 500);
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== "ENOENT")
+                throw err;
+        }
+    }
+    findings.add("coverage", `domain ${slug} has no README.md — description left empty`);
+    return "";
+}
+function extractFirstParagraph(markdown) {
+    // Strip an optional H1, then return the first non-empty paragraph
+    // (text up to the first blank line).
+    const lines = markdown.split(/\r?\n/);
+    let i = 0;
+    while (i < lines.length && (lines[i] === undefined || lines[i].trim() === "" || lines[i].startsWith("#"))) {
+        i++;
+    }
+    const para = [];
+    while (i < lines.length && lines[i].trim() !== "") {
+        para.push(lines[i].trim());
+        i++;
+    }
+    return para.join(" ").trim();
+}
+function titleCase(slug) {
+    return slug
+        .split("-")
+        .map((p) => (p.length === 0 ? p : p[0].toUpperCase() + p.slice(1)))
+        .join(" ");
+}
+//# sourceMappingURL=domains.js.map

package/dist/lib/catalogue/builders/edge-label-merge.js

@@ -0,0 +1,19 @@
+// F25 — one edge per node pair is the metamodel's rule (schema-stated since
+// 2.30.0) and it stands. The defect was the SILENCE: distinct parallel
+// labels merged first-seen-wins at member and aggregate tier, discarding
+// authored facts without a word (measured: 20 labels already lost before
+// the mechanism that exposed it existed). The merge now concatenates every
+// distinct label — nothing dropped — and says so.
+export function mergeEdgeLabel(row, label, catalogue, findings) {
+    if (label === "")
+        return;
+    const existing = String(row["interaction"] ?? "");
+    const parts = existing === "" ? [] : existing.split("; ");
+    if (parts.includes(label))
+        return;
+    row["interaction"] =
+        existing === "" ? label : `${existing}; ${label}`;
+    findings.add("convention", `${catalogue}: edge "${String(row["id"])}" is declared with multiple distinct labels — ` +
+        `one edge per node pair (schema rule); labels concatenated, nothing dropped (F25)`);
+}
+//# sourceMappingURL=edge-label-merge.js.map

package/dist/lib/catalogue/builders/entities-manifest.js

@@ -0,0 +1,160 @@
+// Forward-method walker for the entities catalogue per ADR 0159 §4.2.
+// Reads `models[].entities[]` from `docs/platform/reference/glossary-alignment-manifest.yaml`.
+//
+// Same input file ADR 0158's entity_glossary walker reads — this walker
+// promotes the entity entries to first-class entity rows; entity_glossary
+// continues to emit a separate edge per (domain, entity, glossary_term).
+//
+// **Profile-gated to platform-profile only (per ADR 0159 §4.2 amendment,
+// schema 2.13.0 patch).** The manifest is platform-owned ecosystem-wide
+// content; adopters who syndicate it to sibling application-product /
+// integration-product SDDs would otherwise see siblings re-emit the entire
+// entity registry locally with unresolved-domain PKs, then collide en masse
+// at aggregation. Profile-gating mirrors the precedent set by
+// domain-models.ts per ADR 0142 (same scope, same syndication shape).
+//
+// Behaviour (Phase Pre Step E acceptance):
+// - For each models[] entry, derive domain_id from its `domain` field.
+//   `platform-wide` and other non-canonical hints map to empty domain_id
+//   and the entity PK uses the `_platform-wide-{slug}` sentinel prefix
+//   (per ADR 0159 §4.2 amendment, schema 2.13.0 patch). The underscore
+//   prefix is unreachable via entitySlug (slugify strips underscores), so
+//   the sentinel can't collide with any real domain id including
+//   ecosystem-named domains. A [finding] convention surfaces the choice.
+// - 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
+//   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.
+import { readFile } from "node:fs/promises";
+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 async function buildEntitiesFromManifest(inputs) {
+    // Profile gate per ADR 0159 §4.2 amendment: only platform-profile SDDs
+    // read the manifest. Sibling profiles (application-product, integration-
+    // product, support-repo, organisation) emit 0 rows even when the file is
+    // present via syndication.
+    if (inputs.profile !== "platform-profile")
+        return [];
+    const path = join(inputs.sddPath, MANIFEST_REL_PATH);
+    let text;
+    try {
+        text = await readFile(path, "utf-8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+    let raw;
+    try {
+        raw = parseYaml(text);
+    }
+    catch (err) {
+        inputs.findings.add("convention", `${MANIFEST_REL_PATH}: failed to parse YAML — ${err.message}`);
+        return [];
+    }
+    if (!raw || typeof raw !== "object")
+        return [];
+    const obj = raw;
+    const modelsRaw = obj["models"];
+    if (!Array.isArray(modelsRaw))
+        return [];
+    const rows = [];
+    const byId = new Map();
+    for (const m of modelsRaw) {
+        if (!m || typeof m !== "object")
+            continue;
+        const model = m;
+        const rawDomain = String(model.domain ?? "").trim();
+        let domainId = rawDomain;
+        if (NON_CANONICAL_DOMAINS.has(rawDomain)) {
+            domainId = "";
+            inputs.findings.add("convention", `${MANIFEST_REL_PATH}: model ${model.path ?? "(unknown path)"} has non-canonical domain "${rawDomain}" — entity domain_id left empty`);
+        }
+        else if (rawDomain && !inputs.knownDomainIds.has(rawDomain)) {
+            inputs.findings.add("orphan", `${MANIFEST_REL_PATH}: model ${model.path ?? "(unknown path)"} declares unknown domain "${rawDomain}" — entity domain_id left empty`);
+            domainId = "";
+        }
+        const entities = (model.entities ?? []);
+        for (const e of entities) {
+            if (!e || typeof e !== "object")
+                continue;
+            const entity = e;
+            const name = String(entity.name ?? "").trim();
+            if (!name) {
+                inputs.findings.add("convention", `${MANIFEST_REL_PATH}: model ${model.path ?? "(unknown)"} has an entities[] entry with empty name — skipped`);
+                continue;
+            }
+            const slug = entitySlug(name);
+            const id = domainId
+                ? `${domainId}-${slug}`
+                : `${PLATFORM_WIDE_PK_PREFIX}-${slug}`;
+            const glossaryTerm = resolveGlossaryTerm(entity.glossary_term, inputs);
+            const noteParts = [];
+            if (entity.status)
+                noteParts.push(`status=${entity.status}`);
+            if (entity.superseded_by)
+                noteParts.push(`superseded_by=${entity.superseded_by}`);
+            if (entity.note)
+                noteParts.push(`note=${entity.note}`);
+            const row = {
+                id,
+                name,
+                domain_id: domainId,
+                source_domain_model_id: "",
+                persistence_kind: "",
+                glossary_term: glossaryTerm,
+                notes: noteParts.join(";"),
+                // The glossary-alignment manifest's entities[] shape has no evidence
+                // slot — manifest-sourced rows stay empty (ADR 0175; schema 2.20.0).
+                evidence_class: "",
+                source_sdd_id: "",
+            };
+            const existing = byId.get(id);
+            if (existing) {
+                const existingGt = String(existing["glossary_term"] ?? "");
+                if (existingGt !== glossaryTerm && glossaryTerm) {
+                    inputs.findings.add("divergence", `${MANIFEST_REL_PATH}: entity ${id} declared in multiple models[] with conflicting glossary_term — keeping first ("${existingGt}"), discarded "${glossaryTerm}"`);
+                }
+                continue;
+            }
+            byId.set(id, row);
+            rows.push(row);
+        }
+    }
+    return rows;
+}
+function resolveGlossaryTerm(raw, inputs) {
+    const term = String(raw ?? "").trim();
+    if (!term)
+        return "";
+    // Try the term-name index plumbed by the glossary builder.
+    const lookups = inputs.idsByTermName?.get(term.toLowerCase());
+    if (lookups && lookups.length > 0) {
+        // Prefer the first; cross-domain collisions are rare and the entity row
+        // carries only one term FK.
+        const id = lookups[0]?.id;
+        if (id && inputs.knownGlossaryIds.has(id))
+            return id;
+    }
+    // Fall back to entity-slug equality scan: produces "vehicle-registration"
+    // type matches for terms authored as "Vehicle Registration".
+    const slug = entitySlug(term);
+    for (const id of inputs.knownGlossaryIds) {
+        // Glossary item ids follow {owning_domain_id}-{term_slug} style; suffix
+        // match avoids cross-domain false positives in most cases.
+        if (id.endsWith(`-${slug}`) || id === slug)
+            return id;
+    }
+    inputs.findings.add("orphan", `${MANIFEST_REL_PATH}: entity glossary_term "${term}" doesn't resolve to a known glossary item`);
+    return "";
+}
+//# sourceMappingURL=entities-manifest.js.map

package/dist/lib/catalogue/builders/entities-mermaid.js

@@ -0,0 +1,189 @@
+// Reverse-method walker for the entities catalogue per ADR 0159 §4.3.
+// Parses `erDiagram` blocks in `docs/domains/{domain}/architecture/data-model.mermaid.md`
+// (or whatever file domain_models.csv references for that domain).
+//
+// Prototype findings (per ADR 0159 — mermaid authoring quirks):
+// - Multi-erDiagram-per-file is the norm (asset has 7 blocks; identity has 4).
+//   Walker merges entities across all `erDiagram` fences in the file.
+// - Naming style varies within a single file: UPPER_SNAKE_CASE, PascalCase,
+//   ALLCAPS-no-underscores, lowercase / camelCase. Regex accepts [A-Za-z_]
+//   as first char with explicit Mermaid-keyword exclusion.
+// - Relationship lines (`A ||--o{ B : "label"`) start with an identifier but
+//   are not entity declarations; detected via arrow-token pattern + skipped.
+// - Mermaid comments (`%% ...`) are tolerated inside entity blocks.
+// - Files may mix `erDiagram` with other Mermaid diagram types (flowchart,
+//   sequenceDiagram). Each fenced block is independently checked for the
+//   erDiagram opener; non-ER blocks are skipped.
+import { readFile } from "node:fs/promises";
+import { entitySlug } from "./entity-slug.js";
+import { extractFileEvidenceClass } from "./evidence-class.js";
+const RE_MERMAID_OPEN = /^```\s*mermaid\s*$/i;
+const RE_FENCE_CLOSE = /^```\s*$/;
+const RE_COMMENT = /^\s*%%/;
+const RE_ENTITY_OPEN = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*\{\s*$/;
+const RE_REL_LINE = /^\s*[A-Za-z_][A-Za-z0-9_]*\s+\|?\|?[o|\-]+\{?\s+[A-Za-z]/;
+const MERMAID_KEYWORDS = new Set(["erdiagram", "subgraph", "classdef", "style", "class"]);
+export async function buildEntitiesFromMermaid(inputs) {
+    const rows = [];
+    const seenAcrossFiles = new Map(); // id → originating doc_path
+    for (const dm of inputs.domainModels) {
+        if (!dm.doc_path.endsWith(".mermaid.md"))
+            continue;
+        const docPath = dm.doc_path.startsWith("/")
+            ? dm.doc_path
+            : `${inputs.sddPath}/${dm.doc_path}`;
+        let text;
+        try {
+            text = await readFile(docPath, "utf-8");
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                continue;
+            throw err;
+        }
+        const parsed = parseFile(text, dm, inputs.findings);
+        // File-level evidence class (leading ```yaml fence's `evidence-class:`,
+        // per the documentation-reverse anchor convention / ADR 0175). Every
+        // entity extracted from this file inherits it; absence → "".
+        const fileEvidenceClass = extractFileEvidenceClass(text);
+        // Within-file dedup by id is enforced inside parseFile via seen-set;
+        // cross-file dedup is enforced here (shouldn't fire in current Adopter A,
+        // defensive against future authoring that splits a domain across files).
+        for (const p of parsed) {
+            const id = `${p.domainId}-${entitySlug(p.name)}`;
+            const existing = seenAcrossFiles.get(id);
+            if (existing) {
+                inputs.findings.add("divergence", `entities: cross-file id collision on "${id}" — declared in ${existing} and ${dm.doc_path}; keeping first`);
+                continue;
+            }
+            seenAcrossFiles.set(id, dm.doc_path);
+            const glossaryTerm = resolveGlossaryTermBySlug(p.name, p.domainId, inputs.knownGlossaryIds);
+            rows.push({
+                id,
+                name: p.name,
+                domain_id: p.domainId,
+                source_domain_model_id: p.sourceDomainModelId,
+                persistence_kind: "",
+                glossary_term: glossaryTerm,
+                notes: `columns=${p.columnCount}`,
+                evidence_class: fileEvidenceClass,
+                source_sdd_id: "",
+            });
+        }
+    }
+    return rows;
+}
+function parseFile(text, dm, findings) {
+    const lines = text.split(/\r?\n/);
+    const out = [];
+    const seenInFile = new Set();
+    let inMermaid = false;
+    let isEr = false;
+    let firstKeywordSeen = false;
+    let inEntity = false;
+    let entityName = null;
+    let entityColumns = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const raw = lines[i] ?? "";
+        if (!inMermaid) {
+            if (RE_MERMAID_OPEN.test(raw)) {
+                inMermaid = true;
+                isEr = false;
+                firstKeywordSeen = false;
+            }
+            continue;
+        }
+        // in_mermaid == true
+        if (RE_FENCE_CLOSE.test(raw)) {
+            inMermaid = false;
+            isEr = false;
+            firstKeywordSeen = false;
+            // If we exit mid-entity, drop it silently — malformed block.
+            inEntity = false;
+            entityName = null;
+            continue;
+        }
+        const stripped = raw.trim();
+        if (!firstKeywordSeen && stripped !== "" && !RE_COMMENT.test(raw)) {
+            firstKeywordSeen = true;
+            isEr = stripped.toLowerCase().startsWith("erdiagram");
+        }
+        if (!isEr)
+            continue;
+        if (inEntity) {
+            if (stripped.startsWith("}")) {
+                if (entityName !== null) {
+                    const slug = entitySlug(entityName);
+                    if (!seenInFile.has(slug)) {
+                        seenInFile.add(slug);
+                        out.push({
+                            name: entityName,
+                            domainId: dm.domain_id,
+                            sourceDomainModelId: dm.id,
+                            columnCount: entityColumns,
+                        });
+                    }
+                }
+                inEntity = false;
+                entityName = null;
+                entityColumns = 0;
+                continue;
+            }
+            if (RE_COMMENT.test(raw))
+                continue;
+            if (stripped)
+                entityColumns++;
+            continue;
+        }
+        // Not in an entity block — look for an opener.
+        if (RE_COMMENT.test(raw))
+            continue;
+        if (RE_REL_LINE.test(raw))
+            continue;
+        const m = RE_ENTITY_OPEN.exec(raw);
+        if (m) {
+            const ident = m[1] ?? "";
+            if (MERMAID_KEYWORDS.has(ident.toLowerCase()))
+                continue;
+            entityName = ident;
+            inEntity = true;
+            entityColumns = 0;
+        }
+    }
+    // Defensive: if a block ended without closing an entity, log it once.
+    if (inEntity && entityName !== null) {
+        findings.add("convention", `entities-mermaid: ${dm.doc_path}: unclosed entity block for "${entityName}" — discarded`);
+    }
+    return out;
+}
+function resolveGlossaryTermBySlug(entityName, domainId, knownGlossaryIds) {
+    const slug = entitySlug(entityName);
+    if (!slug)
+        return "";
+    // Glossary ids follow {owning_domain_id}-{term_slug} or {slug} shape.
+    // Suffix-match keeps cross-domain ids resolvable while avoiding random
+    // substring collisions. Resolves single-word terms (slug has no internal
+    // hyphen, so it equals the glossary term-slug).
+    for (const id of knownGlossaryIds) {
+        if (id === slug || id.endsWith(`-${slug}`))
+            return id;
+    }
+    // ADR 0165 follow-on: the glossary builder collapses multi-word term slugs
+    // (CONTAINER_MESSAGING → "...-containermessaging"), while entitySlug
+    // hyphenates ("container-messaging"), so multi-word terms miss the suffix
+    // match above. Reconcile boundary-insensitively (compare hyphen-stripped
+    // forms), scoped to the entity's OWN domain to avoid cross-domain
+    // false positives.
+    if (domainId !== "") {
+        const prefix = `${domainId}-`;
+        const collapsed = slug.replace(/-/g, "");
+        for (const id of knownGlossaryIds) {
+            if (!id.startsWith(prefix))
+                continue;
+            if (id.slice(prefix.length).replace(/-/g, "") === collapsed)
+                return id;
+        }
+    }
+    return ""; // Most data-model entities have no glossary term; no orphan finding.
+}
+//# sourceMappingURL=entities-mermaid.js.map

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

@@ -0,0 +1,102 @@
+// ADR 0164: backfill `entities.persistence_kind` from the reverse-method
+// `## Data Store Mapping` table's `Store` column.
+//
+// persistence_kind is a reverse-only column (the services parity arc, ADR
+// 0163): the reverse adopter's Data Store Mapping carries a `Store` engine
+// per entity; forward-method adopters author a store-less table, so their
+// rows correctly stay empty (no Store column → no fill, no finding).
+//
+// The Store engine is mapped to the canonical persistence_kind
+// classification (relational-table / document-collection / event-payload /
+// other) via data-store-mapping.derivePersistenceKind — a derived token,
+// not the verbatim engine (the schema's recommended set is a classification;
+// the raw engine is preserved in `notes`). erDiagram-only entities (not in
+// any Data Store Mapping row) stay empty — legitimate partial coverage.
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { derivePersistenceKind, detectColumn, entitySlug, findDataStoreTable, normaliseEntity, } from "./data-store-mapping.js";
+/**
+ * Returns the entity rows with `persistence_kind` filled (fill-if-empty)
+ * from the Data Store Mapping `Store` column, and the raw store recorded in
+ * `notes`. When no Store column exists anywhere (forward adopters) the rows
+ * are returned unchanged and no finding is emitted.
+ */
+export async function enrichEntityPersistenceKind(inputs) {
+    const kindByEntityId = new Map();
+    const unmappedStores = new Set();
+    for (const dm of inputs.domainModels) {
+        if (!dm.doc_path.endsWith(".mermaid.md"))
+            continue;
+        const fullPath = dm.doc_path.startsWith("/")
+            ? dm.doc_path
+            : join(inputs.sddPath, dm.doc_path);
+        let text;
+        try {
+            text = await readFile(fullPath, "utf-8");
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                continue;
+            throw err;
+        }
+        const table = findDataStoreTable(text);
+        if (table === null)
+            continue;
+        const entityColIdx = detectColumn(table.headers, (h) => h === "entity" || h.startsWith("entity"));
+        const storeColIdx = detectColumn(table.headers, (h) => h === "store");
+        // No Store column → forward-method store-less table; skip silently.
+        if (entityColIdx === -1 || storeColIdx === -1)
+            continue;
+        for (const cells of table.dataRows) {
+            if (cells.length <= Math.max(entityColIdx, storeColIdx))
+                continue;
+            const entityText = cells[entityColIdx].trim();
+            const store = cells[storeColIdx].trim();
+            if (!entityText || !store)
+                continue;
+            const { kind, recognised } = derivePersistenceKind(store);
+            if (kind === "")
+                continue; // null store cell (N/A, -, …)
+            if (!recognised)
+                unmappedStores.add(store);
+            const entSlug = entitySlug(normaliseEntity(entityText));
+            const entityId = inputs.entityIdByDomainSlug.get(`${dm.domain_id}|${entSlug}`) ??
+                inputs.entityIdBySlug.get(entSlug);
+            // Data-store-only row with no matching entity node — skip (partial
+            // coverage); the service-entity walker emits its own orphan finding.
+            if (entityId === undefined)
+                continue;
+            // First mapping wins (deterministic by domain-model order).
+            if (!kindByEntityId.has(entityId)) {
+                kindByEntityId.set(entityId, { kind, store });
+            }
+        }
+    }
+    if (kindByEntityId.size === 0)
+        return [...inputs.entityRows];
+    let filled = 0;
+    const out = inputs.entityRows.map((row) => {
+        if (String(row["persistence_kind"] ?? "") !== "")
+            return row; // fill-if-empty
+        const hit = kindByEntityId.get(String(row["id"]));
+        if (hit === undefined)
+            return row;
+        filled++;
+        const notes = String(row["notes"] ?? "");
+        const storeNote = `store=${hit.store}`;
+        return {
+            ...row,
+            persistence_kind: hit.kind,
+            notes: notes ? `${notes};${storeNote}` : storeNote,
+        };
+    });
+    if (filled > 0) {
+        const unmapped = unmappedStores.size > 0
+            ? ` (${unmappedStores.size} store value(s) matched no rule → other: ${[...unmappedStores].slice(0, 8).join(", ")})`
+            : "";
+        inputs.findings.add("coverage", `entities: persistence_kind backfilled on ${filled} ` +
+            `entit${filled === 1 ? "y" : "ies"} from Data Store Mapping Store column${unmapped}`);
+    }
+    return out;
+}
+//# sourceMappingURL=entity-persistence.js.map

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

@@ -0,0 +1,47 @@
+// Entity-aware slug helper used by the data-model-entity walkers
+// (entities-manifest, entities-mermaid, service-entity-tables) per ADR 0159 §4.6.
+//
+// Differs from the base `slugify` in events / capabilities / contracts: adds
+// an ALLCAPS-then-Pascal split rule so naming-style variation across
+// UPPER_SNAKE_CASE Mermaid authoring and PascalCase data-store-table
+// authoring resolves to a single canonical slug.
+//
+// Examples:
+//   entitySlug("OBUConfigurationTemplate")   → "obu-configuration-template"
+//   entitySlug("OBU_CONFIGURATION_TEMPLATE") → "obu-configuration-template"
+//   entitySlug("Vehicle")                    → "vehicle"
+//   entitySlug("APIKeyRotationRecord")       → "api-key-rotation-record"
+//   entitySlug("customer")                   → "customer" (lowercase Mermaid)
+//   entitySlug("accountFeatures")            → "account-features"
+//
+// Phase Pre finding (research/adr-0159-prototypes/PHASE-PRE-SYNTHESIS.md):
+// without the ALLCAPS-then-Pascal rule, the Data Store Mapping table form
+// (`OBUConfigurationTemplate`) never resolves to the Mermaid form
+// (`OBU_CONFIGURATION_TEMPLATE`), breaking ~50% of expected service_entity
+// edges in Adopter A.
+//
+// Acronym-run rule (ADR 0164 wave-2 follow-on): the first replace requires the
+// leading uppercase run to be >=2 chars (`[A-Z]{2,}`). A *single* leading
+// capital before a capitalised word is NOT split off, so a PascalCase form
+// reconciles with its boundary-free UPPER_SNAKE form:
+//   entitySlug("OAuthClient")  -> "oauth-client"  (O is part of "OAuth")
+//   entitySlug("OAUTH_CLIENT") -> "oauth-client"  (matches)
+// Before the >=2 rule these produced "o-auth-client" vs "oauth-client".
+// Verified zero PK churn across both reference adopters (263 + 414 entities).
+// This cannot reconcile names whose PascalCase and UPPER_SNAKE forms genuinely
+// disagree on word boundaries — e.g. "SigLink" (two words) vs "SIGLINK" (one)
+// -> "sig-link" vs "siglink". That is adopter authoring drift, resolved by
+// aligning the spellings (author `SIG_LINK`), not by this normaliser.
+//
+// Kept local to the entity walkers to avoid affecting events / contracts /
+// capability id generation. Promote to a shared module only if a fourth
+// walker needs it (per ADR 0159 §4.6 deferred decision).
+export function entitySlug(s) {
+    return s
+        .replace(/([A-Z]{2,})([A-Z][a-z])/g, "$1-$2")
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+//# sourceMappingURL=entity-slug.js.map