@sdd-method/verify-cli 0.1.0

package/dist/lib/catalogue/impact-run.js

@@ -0,0 +1,228 @@
+/**
+ * Transitive impact analysis — `sdd-cli catalogue impact` (M-ADR 0206 §4.6).
+ *
+ * Impact traverses the graph-projection edge set BY DECLARED SEMANTICS: every
+ * relationship carries an impact-flow token in the rubric-coverage-map
+ * (M-ADR 0206 §4.1) naming which endpoint RECEIVES impact — `toward-source`
+ * (dependency shape: a change at the target propagates to the source),
+ * `toward-target` (membership shape: a part's change reaches its whole),
+ * `both` (realisation), `none` (xref, lineage records, attributes). One
+ * relationship (`service_event`) resolves its flow per row from a named
+ * column (§4.2). The closure is the set of nodes impact can reach from the
+ * seed along declared propagation directions, computed by recursive SQL
+ * (`WITH RECURSIVE`) on the Phase A engine.
+ *
+ * THE CO-DIRECTIONALITY INVARIANT (§4.4, a condition of 0206's acceptance):
+ * the Phase C mirror-dedup heuristic is retired because under the declared
+ * tokens every true-mirror pair propagates the SAME direction. That premise
+ * is exercised, not assumed: buildImpactPropagation asserts that no node
+ * pair receives propagation in BOTH directions from two DIFFERENT
+ * single-direction relationship types, and fails loudly naming the pair and
+ * types. A single relationship declaring `both` is deliberate bidirectional
+ * coupling and is exempt; a self-referential type contributing both
+ * directions from different rows (a hierarchy cycle) is likewise exempt.
+ * A future token edit that would silently bring the undirected flood back
+ * trips this assertion instead.
+ *
+ * Cycle discipline: the recursion carries NO depth column — recursive UNION
+ * deduplicates whole rows, and a depth column makes every lap of a cycle a
+ * "new" row: the query that looks more informative is the query that never
+ * terminates. As a bare id-set the closure saturates and stops.
+ */
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { readCatalogueCsv } from "./csv-reader.js";
+import { loadCanonicalSchema } from "./schema-loader.js";
+import { loadCatalogueKinds, loadRelationshipSemantics, } from "./relationship-semantics.js";
+import { projectGraph } from "./graph-projection.js";
+function resolveFlow(edge, semantics) {
+    const decl = edge.type.includes(".")
+        ? semantics.entityFks.get(edge.type)
+        : semantics.edges.get(edge.type);
+    if (decl === undefined) {
+        throw new Error(`impact: relationship ${edge.type} has no declaration in the ` +
+            `rubric-coverage-map (M-ADR 0206) — sync the vendored map.`);
+    }
+    if (decl.impactFlow !== undefined)
+        return decl.impactFlow;
+    const by = decl.impactFlowBy;
+    const value = (edge.properties?.[by.column] ?? "").trim();
+    const flow = by.values[value];
+    if (flow === undefined) {
+        throw new Error(`impact: ${edge.type} resolves flow by column '${by.column}' but row ` +
+            `value '${value}' is not in the declared map — extend the ` +
+            `declaration or fix the row.`);
+    }
+    return flow;
+}
+/**
+ * Resolve every declared edge into propagation steps per its flow, and
+ * exercise the §4.4 co-directionality invariant.
+ */
+export function buildImpactPropagation(edges, semantics) {
+    const out = [];
+    const byFlow = new Map();
+    let flowNone = 0;
+    const pairs = new Map();
+    const notePair = (from, to, type) => {
+        const [a, b] = from < to ? [from, to] : [to, from];
+        const key = `${a}␟${b}`;
+        let rec = pairs.get(key);
+        if (rec === undefined) {
+            rec = { ab: new Set(), ba: new Set() };
+            pairs.set(key, rec);
+        }
+        (from === a ? rec.ab : rec.ba).add(type);
+    };
+    for (const e of edges) {
+        const flow = resolveFlow(e, semantics);
+        byFlow.set(flow, (byFlow.get(flow) ?? 0) + 1);
+        if (flow === "none") {
+            flowNone += 1;
+            continue;
+        }
+        if (flow === "toward-source" || flow === "both") {
+            out.push({ from: e.target, to: e.source, type: e.type });
+            notePair(e.target, e.source, e.type);
+        }
+        if (flow === "toward-target" || flow === "both") {
+            out.push({ from: e.source, to: e.target, type: e.type });
+            notePair(e.source, e.target, e.type);
+        }
+    }
+    // §4.4 invariant, refined on measured data (2026-08-06): a pair fails only
+    // when one type contributes EXCLUSIVELY a→b against another contributing
+    // EXCLUSIVELY b→a. A type that itself spans both directions on the pair —
+    // opposing role-rows of a role-conditional relationship (a service that
+    // publishes AND consumes the same event: five real pairs on the reverse
+    // estate, one service, all session-broadcast shaped), a self-referential
+    // hierarchy cycle, or a declared `both` flow — has DECLARED that pair
+    // bidirectional, so other types aligning with either direction are
+    // consistent with declarations, not drift. The flipped-token flood shape
+    // (two single-direction declarations opposing) still fails, loudly.
+    for (const [key, rec] of pairs) {
+        const abOnly = [...rec.ab].filter((t) => !rec.ba.has(t));
+        const baOnly = [...rec.ba].filter((t) => !rec.ab.has(t));
+        if (abOnly.length > 0 && baOnly.length > 0) {
+            const [a, b] = key.split("␟");
+            throw new Error(`impact: counter-directional reciprocal pair (M-ADR 0206 §4.4): ` +
+                `${abOnly[0]} propagates ${a} -> ${b} while ${baOnly[0]} propagates ` +
+                `${b} -> ${a}, and neither declares the pair bidirectional. The ` +
+                `declared tokens have re-created an undirected pair; fix the ` +
+                `classification before trusting any closure.`);
+        }
+    }
+    return { edges: out, flowNone, byFlow };
+}
+function sqlStringLiteral(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+/**
+ * Closure of `seed` over resolved propagation edges, on the engine.
+ * Exported for the fixture controls; the verb goes through runCatalogueImpact.
+ */
+export async function computeImpactClosure(propagation, seed) {
+    const { DuckDBInstance } = await import("@duckdb/node-api");
+    const instance = await DuckDBInstance.create(":memory:");
+    const conn = await instance.connect();
+    try {
+        await conn.run(`CREATE TABLE prop (f VARCHAR, t VARCHAR);`);
+        const CHUNK = 500;
+        for (let i = 0; i < propagation.length; i += CHUNK) {
+            const tuples = propagation
+                .slice(i, i + CHUNK)
+                .map((e) => `(${sqlStringLiteral(e.from)}, ${sqlStringLiteral(e.to)})`)
+                .join(",\n");
+            await conn.run(`INSERT INTO prop VALUES\n${tuples};`);
+        }
+        const seedLit = sqlStringLiteral(seed);
+        // CYCLE GUARD: the recursion carries NO depth column, deliberately.
+        // Recursive UNION deduplicates whole rows; a depth column makes every
+        // lap around a cycle a "new" row (same id, bigger depth), so the query
+        // that looks more informative is the query that never terminates — the
+        // catalogue graph is not a DAG. As a bare id-set the closure saturates
+        // and stops.
+        const reader = await conn.runAndReadAll(`WITH RECURSIVE reach(id) AS (\n` +
+            `  SELECT t FROM prop WHERE f = ${seedLit}\n` +
+            `  UNION\n` +
+            `  SELECT p.t FROM prop p JOIN reach r ON p.f = r.id\n` +
+            `)\n` +
+            `SELECT DISTINCT id FROM reach WHERE id <> ${seedLit} ORDER BY id;`);
+        return reader.getRows().map((row) => String(row[0]));
+    }
+    finally {
+        conn.disconnectSync();
+    }
+}
+export async function runCatalogueImpact(inputs, write) {
+    const sddRoot = resolve(inputs.sddPath ?? process.cwd());
+    const dir = resolve(sddRoot, inputs.cataloguesDir ?? "catalogues");
+    const tier = inputs.tier ?? "member";
+    if (!existsSync(dir)) {
+        write(`catalogues directory not found at ${dir}\n` +
+            `  Run \`sdd-cli catalogue build\` (or aggregate) first.\n`);
+        return { exitCode: 2 };
+    }
+    const schema = await loadCanonicalSchema();
+    const kinds = await loadCatalogueKinds();
+    const semantics = await loadRelationshipSemantics();
+    const rowsByCatalogue = new Map();
+    for (const cat of schema.catalogues) {
+        const filePath = join(dir, `${cat.name}.csv`);
+        if (!existsSync(filePath))
+            continue;
+        rowsByCatalogue.set(cat.name, (await readCatalogueCsv(filePath)).rows);
+    }
+    const projection = projectGraph(schema, kinds, rowsByCatalogue, tier);
+    const lines = projection.text.trimEnd().split("\n");
+    const nodeIds = new Set();
+    const edges = [];
+    for (const line of lines) {
+        const o = JSON.parse(line);
+        if (o.t === "node")
+            nodeIds.add(o.id);
+        else if (o.t === "edge")
+            edges.push({
+                source: o.source,
+                target: o.target,
+                type: o.type,
+                ...(o.properties !== undefined ? { properties: o.properties } : {}),
+            });
+    }
+    if (!nodeIds.has(inputs.of)) {
+        write(`node not found in the projection: ${inputs.of}\n` +
+            `  Node ids have the form "<catalogue>/<id>", e.g. contracts/orders-api.\n`);
+        return { exitCode: 2 };
+    }
+    const prop = buildImpactPropagation(edges, semantics);
+    const closure = await computeImpactClosure(prop.edges, inputs.of);
+    const byCatalogue = new Map();
+    for (const id of closure) {
+        const cat = id.slice(0, id.indexOf("/"));
+        byCatalogue.set(cat, (byCatalogue.get(cat) ?? 0) + 1);
+    }
+    write(`impact closure of ${inputs.of} (${tier} tier, schema ${schema.schemaVersion})\n`);
+    // Required stated lines (M-ADR 0206 §4.6): what the number means, and what
+    // was traversed under each declared flow — visible per run, not
+    // discoverable from the code.
+    write(`  semantics: change impact over classified relationships (M-ADR 0206) —\n` +
+        `    each relationship traversed per its declared impact-flow; the\n` +
+        `    co-directionality invariant is asserted on every run\n`);
+    const flowCounts = [...prop.byFlow.entries()]
+        .sort()
+        .map(([f, n]) => `${f}=${n}`)
+        .join("  ");
+    write(`  declared edges by resolved flow: ${flowCounts}\n`);
+    write(`  reachable nodes: ${closure.length}\n`);
+    for (const [cat, n] of [...byCatalogue.entries()].sort()) {
+        write(`    ${cat}: ${n}\n`);
+    }
+    for (const id of closure) {
+        write(`  ${id}\n`);
+    }
+    return {
+        exitCode: 0,
+        result: { seed: inputs.of, closure, byCatalogue },
+    };
+}
+//# sourceMappingURL=impact-run.js.map

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

@@ -0,0 +1,422 @@
+/**
+ * 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(),
+    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(),
+    // 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.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.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