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

package/dist/lib/catalogue/manifest-loader.js

@@ -0,0 +1,435 @@
+/**
+ * Loader for the per-SDD `.sdd/sdd-manifest.yaml` per the schema at
+ * docs/method/methods/sdd-manifest-schema.yaml in sdd-method.
+ *
+ * Validates schema_version against SCHEMA_COMPAT and the
+ * profile↔category invariant from product-category-taxonomy.md.
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { z } from "zod";
+import { SCHEMA_COMPAT, formatSchemaVersionMismatch } from "./schema-compat.js";
+export const MANIFEST_REL_PATH = ".sdd/sdd-manifest.yaml";
+export const PROFILES = [
+    "platform-profile",
+    "application-product",
+    "integration-product",
+    "support-repo",
+    "organisation-profile",
+];
+export const CATEGORIES = [
+    "platform-root",
+    "platform-subsystem",
+    "application-product",
+    "integration-provider",
+    "integration-umbrella",
+    "support-repo",
+    "organisation-root",
+];
+const PROFILE_CATEGORY_INVARIANT = {
+    "platform-profile": ["platform-root", "platform-subsystem"],
+    "application-product": ["application-product"],
+    "integration-product": ["integration-provider", "integration-umbrella"],
+    "support-repo": ["support-repo"],
+    "organisation-profile": ["organisation-root"],
+};
+// M-ADR 0193 — the data-plane axis. `pattern` and `locality` are CLOSED
+// method-tier enums; `transport`/`target`/`runtime`/`notes` are free
+// (adopter-tier). Malformed bindings FAIL at load, consistent with every other
+// fixed manifest enum.
+export const DATA_PLANE_PATTERNS = [
+    // Inbound (data-sourcing) sub-set.
+    "retrieve",
+    "own-store",
+    "stream-ingest",
+    "project",
+    // Output-side sub-set (M-ADR 0193 §4.7): how the service produces or exposes
+    // data. `generate` produces a scheduled/periodic artefact (compute-bearing,
+    // carries a runtime); `publish` exposes an outward contract/API (not
+    // compute-bearing).
+    "generate",
+    "publish",
+];
+// Inbound data-sourcing patterns MUST name where the other end sits. `own-store`
+// is a self-binding (no other end); the output-side patterns (`generate`/
+// `publish`) MAY carry a locality but do not require one (M-ADR 0193 §4.7).
+const LOCALITY_REQUIRED_PATTERNS = new Set([
+    "retrieve",
+    "stream-ingest",
+    "project",
+]);
+export const DATA_PLANE_LOCALITIES = [
+    "internal-platform",
+    "internal-domain",
+    "external-vendor",
+];
+// The OUTPUT-SIDE sub-set (M-ADR 0193 §4.7). This is the single method-tier
+// direction mapping: every consumer that needs to branch on direction reads it
+// from here rather than re-deriving the pattern split, so the sub-set the ADR
+// declares has exactly one definition in the codebase.
+const OUTPUT_SIDE_PATTERNS = new Set(["generate", "publish"]);
+/**
+ * Direction of a data-plane pattern. DERIVED, never authored — `direction` is not
+ * a manifest field, so it cannot disagree with `pattern`. Three §4.7 rules branch
+ * on it: platform-dep reconciliation is inbound-only, the archetype-default WARN
+ * compares like with like, and the M-ADR 0187 convergence reasoning differs by
+ * direction.
+ */
+export function dataPlaneDirection(pattern) {
+    return OUTPUT_SIDE_PATTERNS.has(pattern) ? "output" : "inbound";
+}
+/** True for the output-side sub-set (`generate`/`publish`). */
+export function isOutputSidePattern(pattern) {
+    return OUTPUT_SIDE_PATTERNS.has(pattern);
+}
+// Patterns that carry a backend-compute role and therefore a runtime choice
+// (M-ADR 0193 §4.1, extended by §4.7). `stream-ingest`/`project` (inbound
+// compute) and `generate` (scheduled-generation) carry a runtime; `retrieve`
+// (BFF/client), `own-store` (private-api), and `publish` (an exposed contract,
+// not compute in the sourcing sense) do not, so a `runtime` on them is malformed.
+const COMPUTE_BEARING_PATTERNS = new Set([
+    "stream-ingest",
+    "project",
+    "generate",
+]);
+const DataPlaneBindingSchema = z
+    .object({
+    pattern: z.enum(DATA_PLANE_PATTERNS),
+    locality: z.enum(DATA_PLANE_LOCALITIES).optional(),
+    transport: z.string().optional(),
+    runtime: z.string().optional(),
+    target: z.string().optional(),
+    notes: z.string().optional(),
+})
+    .refine((b) => !LOCALITY_REQUIRED_PATTERNS.has(b.pattern) || b.locality !== undefined, {
+    message: "locality is required for a data-sourcing binding (retrieve/stream-ingest/project); own-store and the output-side patterns (generate/publish) may omit it",
+    path: ["locality"],
+})
+    .refine((b) => b.runtime === undefined || COMPUTE_BEARING_PATTERNS.has(b.pattern), {
+    message: "runtime is only valid on a compute-bearing binding (stream-ingest/project/generate); retrieve/own-store/publish carry no runtime choice",
+    path: ["runtime"],
+});
+// A declared departure from the archetype's default composition (M-ADR 0191
+// §4.3 overlay). `expectation` names the archetype-default pattern the product
+// knowingly diverges from; the rationale makes it sanctioned variance.
+const DataPlaneDeviationSchema = z.object({
+    expectation: z.string(),
+    rationale: z.string().min(1, {
+        message: "a data_plane deviation must carry a non-empty rationale",
+    }),
+});
+const DataPlaneSchema = z.object({
+    bindings: z.array(DataPlaneBindingSchema),
+    deviations: z.array(DataPlaneDeviationSchema).optional(),
+});
+// Conformance coverage (M-ADR 0191 §4.3, second overlay element — WS4). An
+// application-product asserts which of its archetype's conformance expectations
+// its own conformance suite exercises (`coverage`), and declares a rationale for
+// any expected tag it deliberately does not cover (`deviations`). The method
+// gates the DECLARATION — it does not run the adopter's conformance tests.
+const ConformanceSchema = z.object({
+    coverage: z.array(z.string()).optional(),
+    deviations: z
+        .array(z.object({
+        tag: z.string(),
+        rationale: z.string().min(1, {
+            message: "a conformance deviation must carry a non-empty rationale",
+        }),
+    }))
+        .optional(),
+});
+/**
+ * Owner-declared product lifecycle. Exported as a runtime array, not just a type,
+ * so the canonical-conformance test can compare the CANONICAL vocabulary against
+ * the IMPLEMENTATION rather than against a list duplicated in the test — a
+ * hardcoded expectation cannot detect the implementation drifting.
+ *
+ * `planned` = real and intended but does not exist yet (sdd-manifest-schema
+ * 1.9.0). Absent still reads as `active`.
+ */
+export const LIFECYCLES = ["planned", "active", "deprecated"];
+const ManifestSchema = z.object({
+    schema_version: z.string(),
+    sdd_id: z.string().regex(/^[a-z][a-z0-9-]*$/, {
+        message: "sdd_id must match /^[a-z][a-z0-9-]*$/",
+    }),
+    profile: z.enum(PROFILES),
+    category: z.enum(CATEGORIES),
+    domain_id: z
+        .string()
+        .regex(/^[a-z][a-z0-9-]*$/)
+        .optional(),
+    ecosystem_root: z.string().optional(),
+    // M-ADR 0208 §4.3: the platform this member is contained by. Canonical name;
+    // `ecosystem_root` above is its deprecated alias (schema 1.10.0, removed at 2.0.0).
+    platform_sdd_id: z.string().optional(),
+    // M-ADR 0056 (amended 2026-09-29, manifest schema 1.11.0): the SDD whose
+    // feature-tree.md holds this SDD's runway classifications, when it has none.
+    feature_tree_anchor: z
+        .string()
+        .regex(/^[a-z][a-z0-9-]*$/)
+        .optional(),
+    aggregation_manifest_path: z.string().optional(),
+    description: z.string().optional(),
+    // Optional canonical C4 system id. Defaults to `{sdd_id}-system`. Set this
+    // when the system was already catalogued under an established id elsewhere
+    // (e.g. a reverse-extracted system pulled into its own SDD) so the id stays
+    // stable across SDDs and aggregation.
+    c4_system_id: z
+        .string()
+        .regex(/^[a-z][a-z0-9-]*$/, {
+        message: "c4_system_id must match /^[a-z][a-z0-9-]*$/",
+    })
+        .optional(),
+    // Owner-declared product lifecycle (sdd-manifest-schema 1.1.0). Absent
+    // means "active". Unknown values are a hard load failure, consistent with
+    // every other manifest enum — a typo'd lifecycle silently defaulting to
+    // active would recreate the exact false-active bug the field exists to fix.
+    // `planned` (sdd-manifest-schema 1.9.0): the product is real and intended but
+    // does not exist yet — the normal OPENING state of a forward-authored product,
+    // where the SDD is written before the code. The absent-means-"active" default
+    // was the one state a pre-realisation estate cannot be in, so it silently
+    // asserted that every unbuilt product was running. A fact about the PRODUCT,
+    // deliberately not about the document (that is `status`).
+    lifecycle: z.enum(LIFECYCLES).optional(),
+    // Application-product surface trait (M-ADR 0167, sdd-manifest-schema 1.2.0).
+    // Fixed enum: ui (human-facing, default) | api (headless). Unknown values
+    // are a hard load failure like every other fixed manifest enum. Ignored off
+    // application-product (cleared with a convention finding in the products
+    // builder). Absent reads as "ui".
+    surface: z.enum(["ui", "api"]).optional(),
+    // Application-product packaging trait (M-ADR 0175, sdd-manifest-schema
+    // 1.7.0). Fixed enum, deliberately narrow: `vendor-saas` marks a
+    // packaged-SaaS product (vendor-operated runtime, vendor-versioned base);
+    // absent reads as self-operated, the unmarked norm. Unknown values are a hard
+    // load failure like every other fixed manifest enum. Ignored off
+    // application-product (cleared with a convention finding in the products
+    // builder). Per M-ADR 0175 §4 no builder may branch on this beyond
+    // evidence/deployment handling.
+    packaging: z.enum(["vendor-saas"]).optional(),
+    // Reference-exemplar trait (sdd-manifest-schema 1.8.0). PROFILE-AGNOSTIC,
+    // unlike the three traits it sits between — a demonstration
+    // application-product is as conceivable as the integration-products the first
+    // cohort came from — so the products builder must NOT clear it off
+    // application-product. Absent reads as a real SDD, the unmarked norm, with no
+    // finding. Only `true` is meaningful; `false` is redundant but accepted.
+    exemplar: z.boolean().optional(),
+    // Shared-library trait (sdd-manifest-schema 1.12.0, M-ADR 0217 §4.4). Profile-agnostic,
+    // like `exemplar`; absent is the unmarked norm, no finding.
+    shared_library: z.boolean().optional(),
+    // Application-product archetype trait (M-ADR 0191, sdd-manifest-schema
+    // 1.2.0). RESOLVED enum, not fixed: the loader validates only the slug
+    // shape here. Whether the value resolves against the active vocabulary
+    // (method ∪ RA-bundle ∪ adopter) is checked in the build step, which has
+    // the bundle cache. Absent reads as "unclassified" (with a finding). Named
+    // application_archetype to stay distinct from the ADR 0173 domain archetype
+    // and the ADR 0169 openui archetype.
+    application_archetype: z
+        .string()
+        .regex(/^[a-z][a-z0-9-]*$/, {
+        message: "application_archetype must match /^[a-z][a-z0-9-]*$/",
+    })
+        .optional(),
+    deprecated_date: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/, {
+        message: "deprecated_date must be a YYYY-MM-DD date",
+    })
+        .optional(),
+    successor_sdd_id: z
+        .string()
+        .regex(/^[a-z][a-z0-9-]*$/, {
+        message: "successor_sdd_id must match /^[a-z][a-z0-9-]*$/ (sdd_id vocabulary)",
+    })
+        .optional(),
+    // Application-product data-plane axis (M-ADR 0193, sdd-manifest-schema 1.3.0);
+    // `data_plane.deviations` added in 1.4.0 (M-ADR 0191 §4.3 overlay). A
+    // composition of typed bindings (malformed bindings FAIL at load) plus
+    // optional declared deviations from the archetype default, each carrying a
+    // rationale so the mismatch is sanctioned variance, not silent drift.
+    data_plane: DataPlaneSchema.optional(),
+    // Conformance coverage declaration (M-ADR 0191 §4.3 WS4, sdd-manifest-schema
+    // 1.5.0). Which archetype conformance expectations the product's suite
+    // exercises, plus rationales for any it deliberately does not.
+    conformance: ConformanceSchema.optional(),
+});
+/** What `products.packaging` carries when the manifest declares nothing. */
+export const PACKAGING_DEFAULT = "self-operated";
+/**
+ * Read and validate the `.sdd/sdd-manifest.yaml` at the given SDD repo root.
+ *
+ * Throws on:
+ *   - file missing
+ *   - YAML parse error
+ *   - shape violation (missing fields, bad enum value, bad slug pattern)
+ *   - profile↔category invariant violation
+ *   - schema_version outside SCHEMA_COMPAT.sdd_manifest range
+ */
+/**
+ * Top-level keys this build understands. Derived from the zod shape so it cannot
+ * drift from what is actually parsed — a hand-maintained list would go stale and
+ * start reporting known fields as unknown, which is worse than saying nothing.
+ */
+const KNOWN_MANIFEST_KEYS = new Set(Object.keys(ManifestSchema.shape));
+/**
+ * Top-level keys present in the file that this build does not know.
+ *
+ * Deliberately TOP-LEVEL only. Nested blocks (`data_plane`, `conformance`) are
+ * validated by their own object schemas and strip their own unknowns; walking
+ * them would need a per-schema recursion this does not yet warrant. Stated so the
+ * limit is known rather than assumed — an unknown key nested inside `data_plane`
+ * is still silently dropped today.
+ */
+function findUnknownTopLevelKeys(raw) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        return [];
+    return Object.keys(raw)
+        .filter((k) => !KNOWN_MANIFEST_KEYS.has(k))
+        .sort();
+}
+export async function loadSddManifest(sddPath, options) {
+    const sourcePath = join(sddPath, MANIFEST_REL_PATH);
+    let text;
+    try {
+        text = await readFile(sourcePath, "utf-8");
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            throw new Error(`SDD manifest not found at ${sourcePath}\n\n` +
+                `Every SDD repo MUST declare an .sdd/sdd-manifest.yaml per ADR 0134 §4.6.\n` +
+                `Schema: docs/method/methods/sdd-manifest-schema.yaml in sdd-method.\n` +
+                `Bootstrap: \`sdd-cli init\` (when migrated to support manifest authoring).`);
+        }
+        throw err;
+    }
+    let raw;
+    try {
+        raw = parseYaml(text);
+    }
+    catch (err) {
+        throw new Error(`failed to parse YAML at ${sourcePath}: ${err.message}`);
+    }
+    // Unknown top-level keys are REPORTED, not silently dropped and not fatal.
+    //
+    // zod's default is `strip`, so a key this build does not know vanished without a
+    // trace: an adopter following a schema that documents a field their sdd-cli
+    // predates got a clean validation and a silent no-op. Not hypothetical —
+    // M-ADR 0175's own version history records exactly this happening to
+    // `packaging`, where the ADR instructed adopters to declare a field the CLI had
+    // never implemented.
+    //
+    // `.strict()` is the WRONG fix: it turns the same situation into a hard failure,
+    // so an older CLI could not build an SDD whose manifest declares anything newer
+    // than itself. Newer baselines ship newer schemas by design, so that inverts the
+    // problem instead of solving it. Reporting keeps the declaration visible while
+    // leaving the build working.
+    const unknownKeys = findUnknownTopLevelKeys(raw);
+    const parsed = ManifestSchema.safeParse(raw);
+    if (!parsed.success) {
+        const issues = parsed.error.issues
+            .map((i) => `  - ${i.path.join(".") || "<root>"}: ${i.message}`)
+            .join("\n");
+        throw new Error(`invalid SDD manifest at ${sourcePath}:\n${issues}`);
+    }
+    // Compat range check.
+    if (!isInRange(parsed.data.schema_version, SCHEMA_COMPAT.sdd_manifest)) {
+        throw new Error(formatSchemaVersionMismatch({
+            schema: "sdd_manifest",
+            readVersion: parsed.data.schema_version,
+            cliVersion: options.cliVersion,
+            sourcePath,
+        }));
+    }
+    // Profile ↔ category invariant.
+    const permitted = PROFILE_CATEGORY_INVARIANT[parsed.data.profile];
+    if (!permitted.includes(parsed.data.category)) {
+        throw new Error(`invalid profile/category combination at ${sourcePath}:\n` +
+            `  profile=${parsed.data.profile}, category=${parsed.data.category}\n` +
+            `  permitted categories under profile=${parsed.data.profile}: ${permitted.join(", ")}\n` +
+            `  per docs/method/methods/product-category-taxonomy.md`);
+    }
+    return {
+        schemaVersion: parsed.data.schema_version,
+        sddId: parsed.data.sdd_id,
+        profile: parsed.data.profile,
+        category: parsed.data.category,
+        ...(parsed.data.domain_id !== undefined ? { domainId: parsed.data.domain_id } : {}),
+        ...(parsed.data.c4_system_id !== undefined ? { c4SystemId: parsed.data.c4_system_id } : {}),
+        ...(parsed.data.ecosystem_root !== undefined
+            ? { ecosystemRoot: parsed.data.ecosystem_root }
+            : {}),
+        ...((parsed.data.platform_sdd_id ?? parsed.data.ecosystem_root) !== undefined
+            ? {
+                platformSddId: (parsed.data.platform_sdd_id ?? parsed.data.ecosystem_root),
+                platformFieldDeprecated: parsed.data.platform_sdd_id === undefined && parsed.data.ecosystem_root !== undefined,
+            }
+            : {}),
+        ...(parsed.data.aggregation_manifest_path !== undefined
+            ? { aggregationManifestPath: parsed.data.aggregation_manifest_path }
+            : {}),
+        ...(parsed.data.feature_tree_anchor !== undefined
+            ? { featureTreeAnchor: parsed.data.feature_tree_anchor }
+            : {}),
+        ...(parsed.data.description !== undefined ? { description: parsed.data.description } : {}),
+        ...(parsed.data.lifecycle !== undefined ? { lifecycle: parsed.data.lifecycle } : {}),
+        ...(parsed.data.surface !== undefined ? { surface: parsed.data.surface } : {}),
+        ...(parsed.data.packaging !== undefined ? { packaging: parsed.data.packaging } : {}),
+        ...(parsed.data.exemplar !== undefined ? { exemplar: parsed.data.exemplar } : {}),
+        ...(parsed.data.shared_library !== undefined ? { sharedLibrary: parsed.data.shared_library } : {}),
+        ...(parsed.data.application_archetype !== undefined
+            ? { applicationArchetype: parsed.data.application_archetype }
+            : {}),
+        ...(parsed.data.deprecated_date !== undefined
+            ? { deprecatedDate: parsed.data.deprecated_date }
+            : {}),
+        ...(parsed.data.successor_sdd_id !== undefined
+            ? { successorSddId: parsed.data.successor_sdd_id }
+            : {}),
+        ...(parsed.data.data_plane !== undefined ? { dataPlane: parsed.data.data_plane } : {}),
+        ...(parsed.data.conformance !== undefined ? { conformance: parsed.data.conformance } : {}),
+        ...(unknownKeys.length > 0 ? { unknownKeys } : {}),
+        sourcePath,
+    };
+}
+/**
+ * Caret-prefixed semver range check. Accepts X in `^1.2.3` if X.major === 1
+ * and X >= 1.2.3.
+ *
+ * Restricted to the `^X.Y.Z` shape — that's the only form SCHEMA_COMPAT uses.
+ */
+export function isInRange(version, range) {
+    if (!range.startsWith("^")) {
+        throw new Error(`unsupported range syntax: ${range}`);
+    }
+    const v = parseSemver(version);
+    const r = parseSemver(range.slice(1));
+    if (v === null || r === null)
+        return false;
+    if (v.major !== r.major)
+        return false;
+    if (v.major === 0) {
+        // Per semver, 0.x is unstable; ^0.x.y matches only 0.x.y itself.
+        return v.minor === r.minor && v.patch >= r.patch;
+    }
+    if (v.minor < r.minor)
+        return false;
+    if (v.minor === r.minor && v.patch < r.patch)
+        return false;
+    return true;
+}
+function parseSemver(s) {
+    const m = /^(\d+)\.(\d+)\.(\d+)/.exec(s);
+    if (!m)
+        return null;
+    const [, maj, min, pat] = m;
+    if (maj === undefined || min === undefined || pat === undefined)
+        return null;
+    return {
+        major: parseInt(maj, 10),
+        minor: parseInt(min, 10),
+        patch: parseInt(pat, 10),
+    };
+}
+//# sourceMappingURL=manifest-loader.js.map

package/dist/lib/catalogue/platform-scope.js

@@ -0,0 +1,7 @@
+// Catalogues whose key is platform-scoped at organisation tier (M-ADR 0208 §4.4): two
+// platforms may each own a row of one id, so the key is (platform_sdd_id, id). Its own
+// module so a read-only verb (catalogue validate, reached by verify-cli) can use it
+// without importing the aggregator.
+// data_items (M-ADR 0216): each platform owns its vocabulary, as it owns its domains.
+export const PLATFORM_SCOPED_AT_ORGANISATION = ["domains", "data_items"];
+//# sourceMappingURL=platform-scope.js.map

package/dist/lib/catalogue/population-checks.js

@@ -0,0 +1,87 @@
+const norm = (s) => s.toLowerCase().replace(/^ext-/, "").replace(/[^a-z0-9]/g, "");
+const slug = (s) => s.toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+/** Does a services[] id name a declared C4 container — by id, by the system-anchored id, or by the slug of its name? */
+export function matchesContainer(sid, containers) {
+    const target = sid.toLowerCase();
+    return containers.some((c) => {
+        const id = c.id.toLowerCase();
+        if (id === target || slug(c.name) === target)
+            return true;
+        const sys = (c.system_id ?? "").toLowerCase();
+        return sys !== "" && id === `${sys}-${target}`;
+    });
+}
+/**
+ * A near-miss is an external-system id that the unresolved id contains or is contained by after
+ * normalisation (a separator changed, a prefix or suffix added — the three measured shapes), with a
+ * length floor so a short common token does not fire on everything. It is NAMED, never applied.
+ */
+export function nearMiss(id, externalIds) {
+    const n = norm(id);
+    let best;
+    for (const ext of externalIds) {
+        const e = norm(ext);
+        if (ext === id || e === "" || Math.min(n.length, e.length) < 6)
+            continue;
+        if (n === e || n.includes(e) || e.includes(n)) {
+            if (best === undefined || e.length > norm(best).length)
+                best = ext; // prefer the most specific
+        }
+    }
+    return best;
+}
+// @rule population-capability-service
+export function checkCapabilityServicePopulation(inputs) {
+    let declared = 0, unresolved = 0, deduplicated = 0, capabilityUnknown = 0, crossSdd = 0;
+    let externalSystem = 0, declaredContainer = 0, nowhere = 0, expectedRows = 0;
+    const seen = new Set();
+    for (const m of inputs.manifests) {
+        const capId = m.capability.id;
+        for (const entry of m.traceability.services ?? []) {
+            declared++;
+            if (!inputs.knownCapabilityIds.has(capId)) {
+                capabilityUnknown++;
+                continue;
+            }
+            const sid = entry.id;
+            // Resolution order (M-ADR 0211 §4.3): owner_sdd FIRST — a declared cross-SDD
+            // reference is resolved by declaration, not by the local services catalogue.
+            const resolved = entry.owner_sdd !== undefined || inputs.knownServiceIds.has(sid);
+            if (entry.owner_sdd !== undefined)
+                crossSdd++;
+            if (!resolved) {
+                unresolved++;
+                if (inputs.knownExternalSystemIds.has(sid)) {
+                    externalSystem++;
+                }
+                else if (matchesContainer(sid, inputs.knownContainers)) {
+                    declaredContainer++;
+                    inputs.findings.add("convention", `capability_service: ${capId} services[] id "${sid}" resolves as a DECLARED C4 CONTAINER, not a service — capability_service has no locus for it; the id is correct and there is nothing to fix here (M-ADR 0211 §4.3, class 2: a dependency on a container that is not a service, filed as its own item)`);
+                }
+                else {
+                    nowhere++;
+                    const cand = nearMiss(sid, inputs.knownExternalSystemIds);
+                    if (cand !== undefined) {
+                        inputs.findings.add("convention", `capability_service: ${capId} services[] id "${sid}" resolves nowhere; nearest external-system id is "${cand}" — a CANDIDATE, not applied (M-ADR 0211 §4.3, class 3)`);
+                    }
+                }
+                continue;
+            }
+            const key = `${capId}__${sid}__${(entry.role ?? "") !== "" ? entry.role : "related"}`;
+            if (seen.has(key)) {
+                deduplicated++;
+                continue;
+            }
+            seen.add(key);
+            expectedRows++;
+        }
+    }
+    const rows = inputs.capabilityServiceRows.length;
+    const balances = declared === rows + unresolved + deduplicated + capabilityUnknown;
+    inputs.findings.add("metric", `capability_service: declared=${declared} rows=${rows} unresolved=${unresolved} deduplicated=${deduplicated} capability-unknown=${capabilityUnknown} (cross-SDD via owner_sdd=${crossSdd}); unresolved by class: external-system=${externalSystem} declared-container=${declaredContainer} nowhere=${nowhere}`);
+    if (!balances) {
+        inputs.findings.add("coverage", `capability_service: the population does not balance — declared ${declared} ≠ rows ${rows} + unresolved ${unresolved} + deduplicated ${deduplicated} + capability-unknown ${capabilityUnknown} (expected rows from declarations: ${expectedRows}). Two instruments disagree; adjudicate, do not smooth (M-ADR 0211 §4.3)`);
+    }
+    return { declared, rows, unresolved, deduplicated, capabilityUnknown, crossSdd, externalSystem, declaredContainer, nowhere, balances };
+}
+//# sourceMappingURL=population-checks.js.map

package/dist/lib/catalogue/relationship-semantics.js

@@ -0,0 +1,66 @@
+// Relationship semantics and catalogue kinds, read from the vendored
+// rubric-coverage-map.yaml — READ-ONLY. Split out of `graph-run.ts`, which also
+// holds `runCatalogueGraph`, the verb that writes `<catalogues-dir>-graph.jsonl`
+// by default. `catalogue impact` needs these loaders and nothing that writes,
+// and the verify-only CLI ships `impact` (M-ADR 0212 §4.3b): while they lived in
+// graph-run the writer came along with them, and the package build caught it.
+// `graph-run.ts` re-exports everything here, so existing imports are unchanged.
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+/**
+ * Vendored copy of sdd-method's orchestration/rubric-coverage-map.yaml —
+ * byte-identical to the canonical (rubric-coverage-map-drift.test.ts guards
+ * it, same one-way contract as canonical-schema.yaml). The build copies it
+ * alongside the compiled module via scripts/copy-yaml-assets.mjs.
+ */
+export const VENDORED_COVERAGE_MAP_PATH = join(fileURLToPath(new URL(".", import.meta.url)), "rubric-coverage-map.yaml");
+function toDecl(where, e) {
+    if (e.class === undefined) {
+        throw new Error(`rubric-coverage-map: ${where} has no class declaration (M-ADR 0206)`);
+    }
+    if ((e.impact_flow === undefined) === (e.impact_flow_by === undefined)) {
+        throw new Error(`rubric-coverage-map: ${where} must declare exactly one of impact_flow / impact_flow_by`);
+    }
+    return {
+        class: e.class,
+        ...(e.impact_flow !== undefined
+            ? { impactFlow: e.impact_flow }
+            : {}),
+        ...(e.impact_flow_by !== undefined
+            ? {
+                impactFlowBy: {
+                    column: e.impact_flow_by.column,
+                    values: e.impact_flow_by.values,
+                },
+            }
+            : {}),
+    };
+}
+export async function loadRelationshipSemantics(mapPath = VENDORED_COVERAGE_MAP_PATH) {
+    const raw = parseYaml(await readFile(mapPath, "utf-8"));
+    const kinds = new Map();
+    const edges = new Map();
+    const entityFks = new Map();
+    for (const [name, entry] of Object.entries(raw.coverage)) {
+        kinds.set(name, entry.kind);
+        if (entry.kind === "edge" || entry.kind === "annotation") {
+            // an annotation classifies at top level exactly as an edge does (schema 3.9.0)
+            edges.set(name, toDecl(`edge ${name}`, entry));
+        }
+        for (const [col, decl] of Object.entries(entry.relationships ?? {})) {
+            entityFks.set(`${name}.${col}`, toDecl(`entity FK ${name}.${col}`, decl));
+        }
+    }
+    return { kinds, edges, entityFks };
+}
+export async function loadCatalogueKinds(mapPath = VENDORED_COVERAGE_MAP_PATH) {
+    const raw = parseYaml(await readFile(mapPath, "utf-8"));
+    const kinds = new Map();
+    for (const [name, entry] of Object.entries(raw.coverage)) {
+        kinds.set(name, entry.kind);
+    }
+    return kinds;
+}
+//# sourceMappingURL=relationship-semantics.js.map