@sdd-method/maintain-cli 0.11.0 → 0.13.0

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

@@ -0,0 +1,316 @@
+// A domain model's content, parsed whole (M-ADR 0230 §4.3, §4.11 proof 7, Proposed; 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.
+//
+// Mermaid ER (`data-model.mermaid.md`, every ```mermaid fence opening with erDiagram):
+//   ENTITY {                      an entity block; ENTITY { type a; type b } on one line is one too
+//     type name [PK|FK|UK|PK_FK[, ...]] ["comment"]
+//   }
+//   A <end>--<end> B : label      a relationship; each end marker || |o o| }| |{ }o o{ is one of four cardinalities;
+//                                 `..` (non-identifying) is read as `--`, and reported
+// TypeQL, in the documented subset (M-ADR 0210 §4.2, `data-model.tql`), through the fail-closed parseTypes:
+//   an entity's owned attributes (@key, @card), and each binary relation as a relationship between its two roles'
+//   players, roles kept. The subset admits no participation cardinality, so both ends are zero-or-more, and a role's
+//   own @card is a cardinality invariant on the relationship.
+// The keys become invariants: a primary key (PK, @key) is one unique invariant over its attributes, which are not
+// nullable; a UK is a unique invariant over its attribute. What a parser reads and cannot hold is an `extraction`
+// finding, never a silent skip.
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { ParseError, parseTypes } from "../../metamodel/tql-subset-parser.js";
+import { entitySlug } from "./entity-slug.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_ENTITY_INLINE = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*\{(.*)\}\s*$/;
+const RE_ATTRIBUTE = /^\s*([A-Za-z_][\w[\]~(),.<>-]*)\s+([A-Za-z_*][\w.-]*)\s*((?:PK_FK|PK|FK|UK)(?:\s*,\s*(?:PK_FK|PK|FK|UK))*)?\s*(?:"([^"]*)")?\s*$/;
+const RE_RELATIONSHIP = /^\s*([A-Za-z_][\w-]*)\s+(\|\||\|o|o\||\}\||\}o)(--|\.\.)(\|\||o\||\|o|\|\{|o\{)\s+([A-Za-z_][\w-]*)\s*:\s*(.+?)\s*$/;
+const RE_BARE_ENTITY = /^\s*[A-Za-z_][\w-]*\s*$/;
+const MERMAID_KEYWORDS = new Set(["erdiagram", "subgraph", "classdef", "style", "class"]);
+const END = {
+    "||": "exactly-one",
+    "|o": "zero-or-one",
+    "o|": "zero-or-one",
+    "}|": "one-or-more",
+    "|{": "one-or-more",
+    "}o": "zero-or-more",
+    "o{": "zero-or-more",
+};
+function mermaidAttribute(text) {
+    const m = RE_ATTRIBUTE.exec(text);
+    if (!m)
+        return null;
+    const keys = new Set((m[3] ?? "").split(",").map((k) => k.trim()).flatMap((k) => (k === "PK_FK" ? ["PK", "FK"] : k === "" ? [] : [k])));
+    const description = m[4] ?? "";
+    const primaryKey = keys.has("PK");
+    const nullable = primaryKey ? false : /^nullable\b/i.test(description.trim()) ? true : undefined;
+    return { name: m[2].replace(/^\*/, ""), type: m[1], primaryKey, unique: keys.has("UK"), foreignKey: keys.has("FK"), nullable, description };
+}
+/** Parse every erDiagram fence of a Mermaid data-model file. `where` locates what is reported. */
+export function parseMermaidDataModel(text, where) {
+    const lines = text.split(/\r?\n/);
+    const entities = [];
+    const relationships = [];
+    const unread = [];
+    const seen = new Set();
+    let inMermaid = false;
+    let isEr = false;
+    let firstKeywordSeen = false;
+    let open = null;
+    const close = (e) => {
+        const slug = entitySlug(e.name);
+        if (seen.has(slug))
+            return; // a later block naming the entity again: the first declaration stands
+        seen.add(slug);
+        entities.push(e);
+    };
+    for (let i = 0; i < lines.length; i++) {
+        const raw = lines[i] ?? "";
+        const at = `${where}:${i + 1}`;
+        if (!inMermaid) {
+            if (RE_MERMAID_OPEN.test(raw)) {
+                inMermaid = true;
+                isEr = false;
+                firstKeywordSeen = false;
+            }
+            continue;
+        }
+        if (RE_FENCE_CLOSE.test(raw)) {
+            inMermaid = false;
+            open = null; // a block the fence cut off is dropped, as the entities builder always has
+            continue;
+        }
+        const stripped = raw.trim();
+        if (!firstKeywordSeen && stripped !== "" && !RE_COMMENT.test(raw)) {
+            firstKeywordSeen = true;
+            isEr = stripped.toLowerCase().startsWith("erdiagram");
+            continue;
+        }
+        if (!isEr || stripped === "" || RE_COMMENT.test(raw))
+            continue;
+        if (open) {
+            if (stripped.startsWith("}")) {
+                close(open);
+                open = null;
+                continue;
+            }
+            open.columnCount++;
+            const a = mermaidAttribute(raw);
+            if (a)
+                open.attributes.push(a);
+            else
+                unread.push(`${at}: an attribute line of ${open.name} not understood: ${JSON.stringify(stripped)}`);
+            continue;
+        }
+        const rel = RE_RELATIONSHIP.exec(raw);
+        if (rel) {
+            if (rel[3] === "..")
+                unread.push(`${at}: a non-identifying relationship (..), read as identifying: ${JSON.stringify(stripped)}`);
+            relationships.push({
+                from: rel[1],
+                to: rel[5],
+                name: rel[6].replace(/^"(.*)"$/, "$1").trim(),
+                fromCardinality: END[rel[2]],
+                toCardinality: END[rel[4]],
+                fromRole: "",
+                toRole: "",
+                roleCards: [],
+            });
+            continue;
+        }
+        const inline = RE_ENTITY_INLINE.exec(raw);
+        if (inline && !MERMAID_KEYWORDS.has(inline[1].toLowerCase())) {
+            const parts = inline[2].split(";").map((p) => p.trim()).filter((p) => p !== "");
+            const attributes = [];
+            for (const p of parts) {
+                const a = mermaidAttribute(p);
+                if (a)
+                    attributes.push(a);
+                else
+                    unread.push(`${at}: an attribute of ${inline[1]} not understood: ${JSON.stringify(p)}`);
+            }
+            close({ name: inline[1], attributes, columnCount: parts.length });
+            continue;
+        }
+        const m = RE_ENTITY_OPEN.exec(raw);
+        if (m && !MERMAID_KEYWORDS.has(m[1].toLowerCase())) {
+            open = { name: m[1], attributes: [], columnCount: 0 };
+            continue;
+        }
+        if (RE_BARE_ENTITY.test(raw) && !MERMAID_KEYWORDS.has(stripped.toLowerCase())) {
+            unread.push(`${at}: an entity named without a block (${stripped}); it is catalogued only where a block declares it`);
+            continue;
+        }
+        unread.push(`${at}: a line not understood: ${JSON.stringify(stripped)}`);
+    }
+    return { entities, relationships, unread, unclosed: open?.name ?? null };
+}
+/** Parse a TypeQL data model in the documented subset. A file outside the subset is refused whole, located. */
+export function parseTypeqlDataModel(text, where) {
+    let t;
+    try {
+        t = parseTypes(text, where, { singlePlayer: false });
+    }
+    catch (e) {
+        if (e instanceof ParseError)
+            return { refused: e.message };
+        throw e;
+    }
+    const unread = [];
+    const entities = [];
+    for (const [label, d] of t.entities) {
+        const attributes = [];
+        for (const [attr, ann] of d.owns) {
+            if (ann.multi)
+                unread.push(`${where}: ${label} owns ${attr} @card(0..), a multi-valued attribute; the model holds one value per attribute`);
+            attributes.push({
+                name: attr,
+                type: t.attrs.get(attr) ?? "",
+                primaryKey: ann.key,
+                unique: false,
+                foreignKey: false,
+                // TypeDB's default for an ownership is @card(0..1)
+                nullable: ann.key || ann.required ? false : true,
+                description: "",
+            });
+        }
+        entities.push({ name: label, attributes, columnCount: attributes.length });
+    }
+    const relationships = [];
+    for (const [label, d] of t.relations) {
+        const roles = [...d.relates.keys()];
+        if (d.owns.size > 0)
+            unread.push(`${where}: relation ${label} owns attributes (${[...d.owns.keys()].join(", ")}); the model holds no attributes on a relationship`);
+        if (roles.length !== 2) {
+            unread.push(`${where}: relation ${label} relates ${roles.length} role(s); the model holds binary relationships only`);
+            continue;
+        }
+        const [a, b] = roles;
+        const playersOf = (role) => (t.playersAll.get(`${label}:${role}`) ?? []).filter((p) => {
+            if (t.entities.has(p))
+                return true;
+            unread.push(`${where}: relation ${p} plays ${label}:${role}; the model relates entities only`);
+            return false;
+        });
+        const cards = [...d.relates].flatMap(([role, ann]) => ann.required ? [`each ${label} relates exactly one ${role}`] : ann.optional ? [`each ${label} relates at most one ${role}`] : []);
+        for (const from of playersOf(a)) {
+            for (const to of playersOf(b)) {
+                relationships.push({ from, to, name: label, fromCardinality: "zero-or-more", toCardinality: "zero-or-more", fromRole: a, toRole: b, roleCards: cards });
+            }
+        }
+    }
+    return { entities, relationships, unread, unclosed: null };
+}
+/**
+ * Read and parse each domain model a domain_models row names. A missing file contributes nothing (the domain-models
+ * builder reports it); a TypeQL file outside the subset contributes nothing (the entities builder reports it).
+ */
+export async function readDataModelSources(sddPath, models) {
+    const out = [];
+    for (const m of models) {
+        const tql = m.docPath.endsWith(".tql");
+        if (!tql && !m.docPath.endsWith(".mermaid.md"))
+            continue;
+        const text = await readFile(m.docPath.startsWith("/") ? m.docPath : join(sddPath, m.docPath), "utf8").catch(() => null);
+        if (text === null)
+            continue;
+        const parsed = tql ? parseTypeqlDataModel(text, m.docPath) : parseMermaidDataModel(text, m.docPath);
+        if ("refused" in parsed)
+            continue; // the entities builder reports the refusal
+        out.push({ ...m, parsed });
+    }
+    return out;
+}
+/**
+ * The attribute, relationship and invariant rows of every parsed model, against the entities catalogue as built. An
+ * entity this build did not catalogue contributes nothing; a relationship names an entity of its own domain, else the
+ * one entity of that name in another, else it is reported.
+ */
+export function buildDataModelElements(sources, entities, findings) {
+    const attributes = [];
+    const relationships = [];
+    const invariants = [];
+    const entityIds = new Set(entities.map((e) => String(e["id"])));
+    const bySlug = new Map();
+    for (const e of entities) {
+        const id = String(e["id"]);
+        const domain = String(e["domain_id"] ?? "");
+        if (domain === "" || !id.startsWith(`${domain}-`))
+            continue;
+        const slug = id.slice(domain.length + 1);
+        bySlug.set(slug, [...(bySlug.get(slug) ?? []), id]);
+    }
+    const resolve = (domainId, name) => {
+        const own = `${domainId}-${entitySlug(name)}`;
+        if (entityIds.has(own))
+            return own;
+        const elsewhere = bySlug.get(entitySlug(name)) ?? [];
+        return elsewhere.length === 1 ? elsewhere[0] : null;
+    };
+    const seenAttr = new Set();
+    const seenRel = new Set();
+    for (const s of sources) {
+        for (const u of s.parsed.unread)
+            findings.add("extraction", u, "warn", s.docPath);
+        for (const e of s.parsed.entities) {
+            const entityId = `${s.domainId}-${entitySlug(e.name)}`;
+            if (!entityIds.has(entityId))
+                continue;
+            const pk = [];
+            for (const a of e.attributes) {
+                const id = `${entityId}__${entitySlug(a.name) || a.name.toLowerCase()}`;
+                if (seenAttr.has(id)) {
+                    findings.add("extraction", `${s.docPath}: ${e.name}.${a.name} is stated twice; the first stands`, "warn", s.docPath);
+                    continue;
+                }
+                seenAttr.add(id);
+                attributes.push({
+                    id,
+                    entity_id: entityId,
+                    name: a.name,
+                    type: a.type,
+                    nullable: a.nullable,
+                    foreign_key: a.foreignKey ? true : undefined,
+                    description: a.description,
+                });
+                if (a.primaryKey)
+                    pk.push(id);
+                if (a.unique)
+                    invariants.push({ id: `${id}__unique`, entity_id: entityId, kind: "unique", attribute_ids: id, statement: `${a.name} is unique among ${e.name} (UK)` });
+            }
+            if (pk.length > 0) {
+                const names = e.attributes.filter((a) => a.primaryKey).map((a) => a.name);
+                invariants.push({ id: `${entityId}__primary-key`, entity_id: entityId, kind: "unique", attribute_ids: pk.join(";"), statement: `${names.join(" and ")} identif${names.length === 1 ? "ies" : "y"} each ${e.name} (primary key)` });
+            }
+        }
+        for (const r of s.parsed.relationships) {
+            const from = resolve(s.domainId, r.from);
+            const to = resolve(s.domainId, r.to);
+            if (from === null || to === null) {
+                const missing = [from === null ? r.from : null, to === null ? r.to : null].filter((x) => x !== null).join(" and ");
+                findings.add("extraction", `${s.docPath}: the relationship ${r.from} ${r.name} ${r.to} names ${missing}, which no catalogued entity matches (in its domain, or once elsewhere); not catalogued`, "warn", s.docPath);
+                continue;
+            }
+            const id = `${from}__${entitySlug(r.name) || "related"}__${to}`;
+            if (seenRel.has(id)) {
+                findings.add("extraction", `${s.docPath}: the relationship ${r.from} ${r.name} ${r.to} is stated twice; the first stands`, "warn", s.docPath);
+                continue;
+            }
+            seenRel.add(id);
+            relationships.push({
+                id,
+                from_entity_id: from,
+                to_entity_id: to,
+                name: r.name,
+                from_cardinality: r.fromCardinality,
+                to_cardinality: r.toCardinality,
+                from_role: r.fromRole,
+                to_role: r.toRole,
+            });
+            r.roleCards.forEach((statement, i) => invariants.push({ id: `${id}__cardinality-${i + 1}`, entity_id: from, kind: "cardinality", relationship_id: id, statement }));
+        }
+    }
+    return { entityAttributes: attributes, entityRelationships: relationships, domainInvariants: invariants };
+}
+//# sourceMappingURL=data-model.js.map

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

@@ -14,20 +14,19 @@
 // - 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.
+// The file is read by the data-model parser (data-model.ts, schema 6.0.0), the
+// one parser every reader of a domain model shares; an entity on one line
+// (`NAME { type a; type b }`) is an entity too, and a `data-model.tql` in the
+// documented TypeQL subset gives its entities the same way.
 import { readFile } from "node:fs/promises";
+import { parseMermaidDataModel, parseTypeqlDataModel } from "./data-model.js";
 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"))
+        if (!dm.doc_path.endsWith(".mermaid.md") && !dm.doc_path.endsWith(".tql"))
             continue;
         const docPath = dm.doc_path.startsWith("/")
             ? dm.doc_path
@@ -74,87 +73,21 @@ export async function buildEntitiesFromMermaid(inputs) {
     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;
-        }
+    const parsed = dm.doc_path.endsWith(".tql") ? parseTypeqlDataModel(text, dm.doc_path) : parseMermaidDataModel(text, dm.doc_path);
+    if ("refused" in parsed) {
+        findings.add("extraction", `entities: ${dm.doc_path} is outside the documented TypeQL subset, so none of its entities is catalogued: ${parsed.refused}`, "warn", dm.doc_path);
+        return [];
     }
     // 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`);
+    if (parsed.unclosed !== null) {
+        findings.add("convention", `entities-mermaid: ${dm.doc_path}: unclosed entity block for "${parsed.unclosed}" — discarded`);
     }
-    return out;
+    return parsed.entities.map((e) => ({
+        name: e.name,
+        domainId: dm.domain_id,
+        sourceDomainModelId: dm.id,
+        columnCount: e.columnCount,
+    }));
 }
 function resolveGlossaryTermBySlug(entityName, domainId, knownGlossaryIds) {
     const slug = entitySlug(entityName);

package/dist/lib/catalogue/builders/feature-grounding.js

@@ -153,6 +153,7 @@ export async function buildFeatureGrounding(inputs) {
                     status: "active",
                     source: "feature-grounding",
                     runway: "",
+                    kind: "feature",
                     source_sdd_id: "",
                 });
                 const cfId = `${capabilityId}__${featureId}`;

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

@@ -89,9 +89,10 @@ export async function buildFeatures(inputs) {
             parent_feature_id: "",
             description,
             maturity: "",
-            status: "active",
+            status: featureStatus(text),
             source: "feature-spec",
             runway: "",
+            kind: featureKind(text),
             source_sdd_id: "",
         });
         idByPath.set(relPath, id);
@@ -123,9 +124,10 @@ export async function buildFeatures(inputs) {
                 parent_feature_id: "",
                 description,
                 maturity: "",
-                status: "active",
+                status: featureStatus(text),
                 source: "feature-spec",
                 runway: "",
+                kind: featureKind(text),
                 source_sdd_id: "",
             });
             idByPath.set(relPath, id);
@@ -145,6 +147,24 @@ export async function buildFeatures(inputs) {
     }
     return { rows, idByPath, idBySlug };
 }
+/**
+ * A feature spec's catalogue status: `retired` when the spec says `**Status:** retired` (its behaviour retired by
+ * an archived change, the feature kept in the catalogue so its retired requirements still resolve), else
+ * `active`. A retired feature stays where it is; it does not have to move to withdrawn/ first.
+ */
+export function featureStatus(text) {
+    const m = /^\*\*Status:\*\*\s*([A-Za-z-]+)/m.exec(text) ?? /^>.*\bStatus:\s*([A-Za-z-]+)/m.exec(text);
+    return m?.[1]?.toLowerCase() === "retired" ? "retired" : "active";
+}
+/**
+ * A feature spec's kind (schema 4.4.0): the value of its `**Kind:**` line, lower-cased, else `feature`. An
+ * obligation (M-ADR 0226, Proposed) and a journey feature (M-ADR 0229 §4.2, Proposed) say so; any other value is written as given, so
+ * the catalogue's vocabulary gate names the spec rather than a default hiding the mistake.
+ */
+export function featureKind(text) {
+    const m = /^\*\*Kind:\*\*\s*([A-Za-z-]+)/m.exec(text);
+    return m?.[1]?.toLowerCase() ?? "feature";
+}
 async function emitBulletRows(ctx) {
     const featureTreePath = await findFeatureTreeFile(ctx.sddPath);
     if (!featureTreePath)
@@ -188,6 +208,7 @@ async function emitBulletRows(ctx) {
             status: "active",
             source: "feature-tree",
             runway: ev.runway,
+            kind: "feature",
             source_sdd_id: "",
         });
         if (!ctx.idBySlug.has(ev.slug))

package/dist/lib/catalogue/builders/integration-components.js

@@ -176,9 +176,8 @@ export async function buildIntegrationComponents(inputs) {
     }
     // SECOND HOME (§9.1): a full `integration-manifest.yaml` per component repo under
     // `repos/<component>/`. Read after the array form so `seen` already holds the
-    // array-form ids and a collision across the two homes is caught rather than
-    // silently duplicated — measured disjoint today, but the two forms are authored
-    // independently and nothing stops them meeting.
+    // array-form ids: a component in both homes that agrees on every tier field is
+    // one declaration stated twice, and one that disagrees is a divergence (below).
     rows.push(...(await readComponentManifests({
         sddPath: inputs.sddPath,
         findings: inputs.findings,
@@ -186,6 +185,7 @@ export async function buildIntegrationComponents(inputs) {
         knownRepoIds: inputs.knownRepoIds,
         knownServiceIds: inputs.knownServiceIds,
         seen,
+        arrayRows: new Map(rows.map((r) => [String(r["id"]), r])),
     })));
     checkAggregate({
         findings: inputs.findings,
@@ -196,6 +196,43 @@ export async function buildIntegrationComponents(inputs) {
     });
     return rows;
 }
+/** The fields the component tier reads, compared when a component is declared in both homes. */
+const TIER_FIELDS = [
+    "component_type",
+    "direction",
+    "frequency",
+    "transport",
+    "format",
+    "auth",
+    "ingestion_pattern",
+    "invocation_pattern",
+    "pattern_qualifier",
+    "primary_entities",
+];
+function tierValue(m, f) {
+    switch (f) {
+        case "component_type":
+            return (m.componentType ?? "").trim();
+        case "direction":
+            return (m.dataFlow?.direction ?? "").trim();
+        case "frequency":
+            return (m.dataFlow?.frequency ?? "").trim();
+        case "transport":
+            return (m.protocol?.transport ?? "").trim();
+        case "format":
+            return (m.protocol?.format ?? "").trim();
+        case "auth":
+            return (m.protocol?.auth ?? "").trim();
+        case "ingestion_pattern":
+            return (m.ingestionPattern ?? "").trim();
+        case "invocation_pattern":
+            return (m.invocationPattern ?? "").trim();
+        case "pattern_qualifier":
+            return (m.patternQualifier ?? "").trim();
+        case "primary_entities":
+            return (m.dataFlow?.primaryEntities ?? []).join(";");
+    }
+}
 /** `repos/` — where the per-component manifests live (M-ADR 0171 §9.1, second home). */
 const REPOS_DIR = "repos";
 /**
@@ -261,8 +298,15 @@ async function readComponentManifests(args) {
         const componentId = (parsed.data.integrationId ?? "").trim() || dir;
         const id = `${args.integrationId}__${componentId}`;
         if (args.seen.has(id)) {
-            args.findings.add("divergence", `integration_component: component id="${id}" declared in BOTH §9.1 homes (components array and ${rel}) — ` +
-                `one component cannot be declared twice; the per-component manifest is dropped. Remove whichever declaration is stale.`);
+            // The reverse template has the array mirror the per-component manifests, so a component in both homes is
+            // expected. A mirror that agrees on every field the tier reads is one declaration stated twice, and is not a
+            // finding; one that disagrees is, and the array's declaration is kept.
+            const mirrored = args.arrayRows.get(id);
+            const differs = mirrored === undefined ? ["(not an array row)"] : TIER_FIELDS.filter((f) => String(mirrored[f] ?? "") !== tierValue(parsed.data, f));
+            if (differs.length > 0) {
+                args.findings.add("divergence", `integration_component: component id="${id}" is declared in both §9.1 homes (components array and ${rel}) and they disagree on ${differs.join(", ")}; ` +
+                    `the components array's declaration is kept. Correct whichever is stale.`);
+            }
             continue;
         }
         args.seen.add(id);