@ybotok/loam 0.2.0-alpha.1 → 0.2.0-alpha.13

package/dist/core/diff/victims.js

@@ -1,247 +0,0 @@
-/**
- * Who, in the CURRENT fleet, still depends on a thing the diff says was
- * removed or deprecated — the joins that turn "an operation left the
- * contract" into "and these named consumers break".
- *
- * THREE SOURCES answer that, and only the first two are copies of anything.
- *
- * The first two are deliberately a SECOND copy of the consumer join the
- * coherence gate asks, built on the same shared primitives, and both copies
- * say so:
- *
- *  - the operation half mirrors `core/coherence/lookups.ts`'s
- *    `edgeConsumers`/`requirementConsumers` (landscape edges with
- *    `metadata { op }` resolved through `serviceResolver` WITH the enumerated
- *    fleet — the container lesson recorded there — plus other services'
- *    living `Operations:` lines, spec.md only, exactly as that module scans);
- *  - the message half mirrors `core/coherence/events/lookups.ts`'s
- *    `messageConsumers` (every `consumes` edge naming the message except one
- *    INTO the provider, plus other services' `Consumes:` lines over BOTH spec
- *    axes — the outbox requirement lives in arch.spec.md as often as in
- *    spec.md, that module's lesson).
- *
- * The copies cannot be one module today: coherence's lookups are closures
- * over a feature's `DeltaScope` and its lazy caches; this one is an index
- * over an already-read fleet. Rule 13 (docs/DESIGN.md) governs — a THIRD
- * copy of this join forces the shared extraction, and whoever changes the
- * victim strings or the scan rules in either module owes the other the same
- * change. The victim string spellings are kept byte-compatible with the
- * coherence findings on purpose, so a reader meets one vocabulary.
- *
- * The THIRD source is not a copy and does not fall under that rule: the fleet's
- * USE CASES, joined in `core/usecases/operations.ts`. A hop of a
- * capability-tagged `dynamic view` that the model attributes to the operation
- * being removed is a business flow that stops working, and saying so — "step 4
- * of Checkout breaks" — is the only one of the three that names a consequence a
- * human weighs rather than a document they then have to open. It has its own
- * module because it asks a different question of a different reader (an
- * attribution over the whole `architecture/` PROJECT, not a scan of one
- * landscape file), and because the attributed/contested distinction it turns on
- * belongs beside `attributeStep`, not beside a requirement scan. Coherence has
- * no equivalent to keep in step with, so nothing here owes it a mirror.
- */
-import { existsSync } from "node:fs";
-import {} from "../c4/likec4.js";
-import { serviceResolver } from "../c4/resolve/service.js";
-import { landscapePath } from "../repo/paths.js";
-import { readUseCases } from "../usecases/fleet.js";
-import { hopsConsuming, hopsExercising } from "../usecases/operations.js";
-/** The requirements one current service contributes to a scan, per axis rule. */
-function reqsOf(state, axes) {
-    return axes.flatMap((axis) => {
-        const a = state[axis];
-        return a.kind === "read" ? a.value : [];
-    });
-}
-const EDGE = (resolve, r) => `edge ${resolve(r.source)} → ${resolve(r.target)}${r.title === undefined ? "" : ` ("${r.title}")`}`;
-/** Entry comparator by map key — deterministic suspension order. */
-const byFirst = (a, b) => (a[0] < b[0] ? -1 : 1);
-export function victimIndex(snap) {
-    // Lazy on purpose, the coherence lookups' own discipline: the landscape is
-    // a full LikeC4 workspace spin-up, and a diff that removes nothing must not
-    // pay for it. An absent landscape proves nothing; an unreadable one proves
-    // nothing either way — `landscape.invalid` is validate's finding to make,
-    // and inventing victims out of a parse error would point the reader at the
-    // wrong file (core/coherence/lookups.ts's doctrine, verbatim).
-    let drawn;
-    const landscape = () => (drawn ??= (async () => {
-        const path = landscapePath(snap.docsDir);
-        const doc = existsSync(path) ? await snap.context.loadLikeC4(path) : null;
-        const usable = doc !== null && doc.errors.length === 0 ? doc : null;
-        // The enumerated fleet rides into the resolver so a landscape that
-        // models CONTAINERS stays visible: without `known`, an edge into
-        // `payment.api` resolves to a service called "api" that has never
-        // existed and the join finds nobody — the exact defect DESIGN's
-        // serviceResolver-known row records.
-        return {
-            usable,
-            resolve: usable === null ? null : serviceResolver(usable.elements, new Set(snap.current.keys())),
-        };
-    })());
-    // Sorted, so victim order never depends on the enumeration's walk order.
-    const ids = [...snap.current.keys()].sort();
-    /**
-     * The use-case half, lazy for the same reason and one step further.
-     *
-     * `readUseCases` carries its own cheap gate — a byte scan for the reserved
-     * tag prefix — so a fleet that declares no use case never starts LikeC4 here
-     * at all, and a fleet that does pays for the `architecture/` project exactly
-     * once per `loam diff`, at the first removal that asks. The fleet set is the
-     * same one the landscape resolver above is built from, so the two halves
-     * cannot disagree about which service an element stands for.
-     */
-    let flows;
-    const useCases = () => (flows ??= readUseCases({ docsDir: snap.docsDir, known: new Set(snap.current.keys()) }));
-    /**
-     * The requirement half of one scan, `tupleVisible`'s own discipline applied
-     * to victims: an unreadable consumer axis contributes a SUSPENSION, never a
-     * silent nothing — "consuming nothing" and "loam refused to read the file"
-     * are opposite facts, and collapsing them is how a breaking removal used to
-     * grade down to a confident warning.
-     */
-    const scanRequirements = (unit) => {
-        const out = { victims: [], suspended: [] };
-        for (const other of ids.filter((id) => id !== unit.provider)) {
-            const state = snap.current.get(other);
-            for (const axis of unit.axes) {
-                const a = state[axis];
-                if (a.kind === "unreadable") {
-                    out.suspended.push(`${other} — ${a.path} could not be read, so its requirements could not be scanned`);
-                    continue;
-                }
-                if (a.kind !== "read")
-                    continue;
-                for (const r of a.value)
-                    if (unit.hit(r))
-                        out.victims.push(`${other}'s living requirement '${r.name}'`);
-            }
-        }
-        for (const [id, dirs] of [...snap.ambiguous].sort(byFirst)) {
-            if (id !== unit.provider)
-                out.suspended.push(`${id} — claimed by ${dirs.join(" and ")}, so its documents could not be scanned`);
-        }
-        return out;
-    };
-    const opConsumers = async (provider, op) => {
-        const { usable, resolve } = await landscape();
-        const scan = scanRequirements({ provider, axes: ["spec"], hit: (r) => r.operations.includes(op) });
-        const edges = [];
-        if (usable !== null && resolve !== null) {
-            for (const r of usable.relationships) {
-                if (r.op === op && resolve(r.target) === provider)
-                    edges.push(EDGE(resolve, r));
-            }
-        }
-        // Flows last in each list, deliberately: the edge and the requirement say
-        // WHICH document to open, and the flow says what the reader is about to
-        // break — so a `details[]` scanned top-down ends on the consequence.
-        const hops = hopsExercising(await useCases(), { provider, op });
-        return {
-            victims: [...edges, ...scan.victims, ...hops.breaks],
-            suspended: [...scan.suspended, ...hops.unsure],
-        };
-    };
-    const messageConsumers = async (provider, name) => {
-        const { usable, resolve } = await landscape();
-        const scan = scanRequirements({ provider, axes: ["spec", "archSpec"], hit: (r) => r.consumes.includes(name) });
-        const edges = [];
-        if (usable !== null && resolve !== null) {
-            for (const r of usable.relationships) {
-                // The message join is fleet-global, so every edge naming it counts —
-                // except one into the provider itself, whose consumption leaves with
-                // the same change (events/lookups.ts's exclusion, verbatim).
-                if (r.consumes === name && resolve(r.target) !== provider)
-                    edges.push(EDGE(resolve, r));
-            }
-        }
-        const hops = hopsConsuming(await useCases(), { provider, name });
-        return { victims: [...edges, ...scan.victims, ...hops], suspended: scan.suspended };
-    };
-    const declarers = (name) => ids.filter((id) => {
-        const axis = snap.current.get(id).asyncapi;
-        return axis.kind === "read" && axis.value.some((m) => m.name === name);
-    });
-    return { opConsumers, messageConsumers, declarers };
-}
-/** The map key a tuple is joined on between the two states. */
-function tupleKey(t) {
-    return `${t.kind}\0${t.consumer}\0${t.provider}\0${t.token}`;
-}
-/**
- * Every cross-service join one state holds, keyed for the base/current join.
- * Axis rules mirror the two consumer scans above: `Operations:` from spec.md
- * only, `Consumes:` from both spec axes. Unreadable axes simply contribute
- * nothing here — `semantic.ts` guards the GRADING so a join is never called
- * added or removed off a side nobody could read.
- */
-export function consumerTuples(states) {
-    const providersOf = (pick) => {
-        const map = new Map();
-        for (const id of [...states.keys()].sort()) {
-            for (const token of pick(states.get(id)))
-                map.set(token, [...(map.get(token) ?? []), id]);
-        }
-        return map;
-    };
-    const opProviders = providersOf((s) => (s.openapi.kind === "read" ? s.openapi.value.map((op) => op.id) : []));
-    const msgProviders = providersOf((s) => (s.asyncapi.kind === "read" ? s.asyncapi.value.map((m) => m.name) : []));
-    const out = new Map();
-    const add = (t) => {
-        out.set(tupleKey(t), t);
-    };
-    for (const consumer of [...states.keys()].sort()) {
-        const state = states.get(consumer);
-        for (const r of reqsOf(state, ["spec"])) {
-            for (const op of r.operations) {
-                for (const p of opProviders.get(op) ?? [])
-                    if (p !== consumer)
-                        add({ kind: "op", consumer, provider: p, token: op });
-            }
-        }
-        for (const r of reqsOf(state, ["spec", "archSpec"])) {
-            for (const name of r.consumes) {
-                for (const p of msgProviders.get(name) ?? [])
-                    if (p !== consumer)
-                        add({ kind: "message", consumer, provider: p, token: name });
-            }
-        }
-    }
-    return out;
-}
-/** May a tuple be graded off this side? Absence answers; unreadable does not; an ambiguous base identity answers nothing. */
-function tupleVisible(states, ambiguous, t) {
-    if (ambiguous.has(t.consumer) || ambiguous.has(t.provider))
-        return false;
-    const readable = (id, axes) => {
-        const state = states.get(id);
-        return state === undefined || axes.every((axis) => state[axis].kind !== "unreadable");
-    };
-    return (readable(t.consumer, t.kind === "op" ? ["spec"] : ["spec", "archSpec"]) &&
-        readable(t.provider, [t.kind === "op" ? "openapi" : "asyncapi"]));
-}
-/**
- * The joins that appeared or went away between base and current, sorted for
- * deterministic output (provider, kind, token, consumer). The visibility
- * guard is the containment rule: a join is never called "added" off a base
- * side nobody could read, nor "removed" off an unreadable working file — the
- * suspended axis already carries that fact.
- */
-export function consumerJoinChanges(input) {
-    const baseTuples = consumerTuples(input.base);
-    const currentTuples = consumerTuples(input.current);
-    const graded = [];
-    for (const [key, t] of currentTuples) {
-        if (!baseTuples.has(key) && tupleVisible(input.base, input.baseAmbiguous, t))
-            graded.push({ t, change: "added" });
-    }
-    for (const [key, t] of baseTuples) {
-        if (!currentTuples.has(key) && tupleVisible(input.current, input.currentAmbiguous, t))
-            graded.push({ t, change: "removed" });
-    }
-    return graded.sort((a, b) => {
-        const ka = `${a.t.provider}\0${a.t.kind}\0${a.t.token}\0${a.t.consumer}\0${a.change}`;
-        const kb = `${b.t.provider}\0${b.t.kind}\0${b.t.token}\0${b.t.consumer}\0${b.change}`;
-        return ka < kb ? -1 : 1;
-    });
-}
-//# sourceMappingURL=victims.js.map

package/dist/core/diff/victims.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"victims.js","sourceRoot":"","sources":["../../../src/core/diff/victims.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Who, in the CURRENT fleet, still depends on a thing the diff says was\n * removed or deprecated — the joins that turn \"an operation left the\n * contract\" into \"and these named consumers break\".\n *\n * THREE SOURCES answer that, and only the first two are copies of anything.\n *\n * The first two are deliberately a SECOND copy of the consumer join the\n * coherence gate asks, built on the same shared primitives, and both copies\n * say so:\n *\n *  - the operation half mirrors `core/coherence/lookups.ts`'s\n *    `edgeConsumers`/`requirementConsumers` (landscape edges with\n *    `metadata { op }` resolved through `serviceResolver` WITH the enumerated\n *    fleet — the container lesson recorded there — plus other services'\n *    living `Operations:` lines, spec.md only, exactly as that module scans);\n *  - the message half mirrors `core/coherence/events/lookups.ts`'s\n *    `messageConsumers` (every `consumes` edge naming the message except one\n *    INTO the provider, plus other services' `Consumes:` lines over BOTH spec\n *    axes — the outbox requirement lives in arch.spec.md as often as in\n *    spec.md, that module's lesson).\n *\n * The copies cannot be one module today: coherence's lookups are closures\n * over a feature's `DeltaScope` and its lazy caches; this one is an index\n * over an already-read fleet. Rule 13 (docs/DESIGN.md) governs — a THIRD\n * copy of this join forces the shared extraction, and whoever changes the\n * victim strings or the scan rules in either module owes the other the same\n * change. The victim string spellings are kept byte-compatible with the\n * coherence findings on purpose, so a reader meets one vocabulary.\n *\n * The THIRD source is not a copy and does not fall under that rule: the fleet's\n * USE CASES, joined in `core/usecases/operations.ts`. A hop of a\n * capability-tagged `dynamic view` that the model attributes to the operation\n * being removed is a business flow that stops working, and saying so — \"step 4\n * of Checkout breaks\" — is the only one of the three that names a consequence a\n * human weighs rather than a document they then have to open. It has its own\n * module because it asks a different question of a different reader (an\n * attribution over the whole `architecture/` PROJECT, not a scan of one\n * landscape file), and because the attributed/contested distinction it turns on\n * belongs beside `attributeStep`, not beside a requirement scan. Coherence has\n * no equivalent to keep in step with, so nothing here owes it a mirror.\n */\nimport { existsSync } from \"node:fs\";\nimport { type LoadedDoc, type Rel } from \"../c4/likec4.js\";\nimport { serviceResolver } from \"../c4/resolve/service.js\";\nimport { landscapePath } from \"../repo/paths.js\";\nimport { readUseCases, type UseCaseScan } from \"../usecases/fleet.js\";\nimport { hopsConsuming, hopsExercising } from \"../usecases/operations.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport type { Requirement } from \"../document/spec.js\";\nimport type { ServiceState } from \"./base-state.js\";\n\n/**\n * One consumer scan's answer, honest about its own coverage. `victims` is\n * positive evidence; `suspended` names the consumers whose relevant document\n * could not be read (or whose identity is ambiguous), because a scan that\n * skipped a file loam REFUSED to read must never let the caller assert\n * \"nobody names it\" — the fail-open shape this type exists to forbid.\n */\nexport interface ConsumerScan {\n  victims: string[];\n  suspended: string[];\n}\n\n/** The current-state consumer questions `semantic.ts` asks per removal. */\nexport interface VictimIndex {\n  /** Current consumers of `provider`'s operation `op`: landscape edges into the provider, then other services' living requirements, then the use-case hops the model attributes to it (contested hops ride as suspensions). */\n  opConsumers(provider: string, op: string): Promise<ConsumerScan>;\n  /** Current consumers of message `name` a `provider` is dropping: consumes-edges (not into the provider), then other services' `Consumes:` lines over both spec axes, then the use-case hops backed by such an edge. */\n  messageConsumers(provider: string, name: string): Promise<ConsumerScan>;\n  /** Current services whose asyncapi declares `name` — positive evidence only; a message still declared elsewhere is not orphaned by one producer dropping it. */\n  declarers(name: string): string[];\n}\n\n/** The requirements one current service contributes to a scan, per axis rule. */\nfunction reqsOf(state: ServiceState, axes: readonly (\"spec\" | \"archSpec\")[]): Requirement[] {\n  return axes.flatMap((axis) => {\n    const a = state[axis];\n    return a.kind === \"read\" ? a.value : [];\n  });\n}\n\nconst EDGE = (resolve: (id: string) => string, r: Rel): string =>\n  `edge ${resolve(r.source)} → ${resolve(r.target)}${r.title === undefined ? \"\" : ` (\"${r.title}\")`}`;\n\n/** Entry comparator by map key — deterministic suspension order. */\nconst byFirst = <T>(a: [string, T], b: [string, T]): number => (a[0] < b[0] ? -1 : 1);\n\n/** The landscape half of the index, loaded at most once and only when a removal actually asks. */\ninterface Drawn {\n  usable: LoadedDoc | null;\n  resolve: ((id: string) => string) | null;\n}\n\nexport function victimIndex(snap: {\n  docsDir: DocsDir;\n  context: FleetContext;\n  current: ReadonlyMap<string, ServiceState>;\n  /** Ids the working tree claims twice (current-state.ts) — their documents cannot be scanned, so they ride as suspended consumers. */\n  ambiguous: ReadonlyMap<string, string[]>;\n}): VictimIndex {\n  // Lazy on purpose, the coherence lookups' own discipline: the landscape is\n  // a full LikeC4 workspace spin-up, and a diff that removes nothing must not\n  // pay for it. An absent landscape proves nothing; an unreadable one proves\n  // nothing either way — `landscape.invalid` is validate's finding to make,\n  // and inventing victims out of a parse error would point the reader at the\n  // wrong file (core/coherence/lookups.ts's doctrine, verbatim).\n  let drawn: Promise<Drawn> | undefined;\n  const landscape = (): Promise<Drawn> =>\n    (drawn ??= (async (): Promise<Drawn> => {\n      const path = landscapePath(snap.docsDir);\n      const doc: LoadedDoc | null = existsSync(path) ? await snap.context.loadLikeC4(path) : null;\n      const usable = doc !== null && doc.errors.length === 0 ? doc : null;\n      // The enumerated fleet rides into the resolver so a landscape that\n      // models CONTAINERS stays visible: without `known`, an edge into\n      // `payment.api` resolves to a service called \"api\" that has never\n      // existed and the join finds nobody — the exact defect DESIGN's\n      // serviceResolver-known row records.\n      return {\n        usable,\n        resolve: usable === null ? null : serviceResolver(usable.elements, new Set(snap.current.keys())),\n      };\n    })());\n\n  // Sorted, so victim order never depends on the enumeration's walk order.\n  const ids = [...snap.current.keys()].sort();\n\n  /**\n   * The use-case half, lazy for the same reason and one step further.\n   *\n   * `readUseCases` carries its own cheap gate — a byte scan for the reserved\n   * tag prefix — so a fleet that declares no use case never starts LikeC4 here\n   * at all, and a fleet that does pays for the `architecture/` project exactly\n   * once per `loam diff`, at the first removal that asks. The fleet set is the\n   * same one the landscape resolver above is built from, so the two halves\n   * cannot disagree about which service an element stands for.\n   */\n  let flows: Promise<UseCaseScan> | undefined;\n  const useCases = (): Promise<UseCaseScan> =>\n    (flows ??= readUseCases({ docsDir: snap.docsDir, known: new Set(snap.current.keys()) }));\n\n  /**\n   * The requirement half of one scan, `tupleVisible`'s own discipline applied\n   * to victims: an unreadable consumer axis contributes a SUSPENSION, never a\n   * silent nothing — \"consuming nothing\" and \"loam refused to read the file\"\n   * are opposite facts, and collapsing them is how a breaking removal used to\n   * grade down to a confident warning.\n   */\n  const scanRequirements = (unit: { provider: string; axes: readonly (\"spec\" | \"archSpec\")[]; hit: (r: Requirement) => boolean }): ConsumerScan => {\n    const out: ConsumerScan = { victims: [], suspended: [] };\n    for (const other of ids.filter((id) => id !== unit.provider)) {\n      const state = snap.current.get(other)!;\n      for (const axis of unit.axes) {\n        const a = state[axis];\n        if (a.kind === \"unreadable\") {\n          out.suspended.push(`${other} — ${a.path} could not be read, so its requirements could not be scanned`);\n          continue;\n        }\n        if (a.kind !== \"read\") continue;\n        for (const r of a.value) if (unit.hit(r)) out.victims.push(`${other}'s living requirement '${r.name}'`);\n      }\n    }\n    for (const [id, dirs] of [...snap.ambiguous].sort(byFirst)) {\n      if (id !== unit.provider) out.suspended.push(`${id} — claimed by ${dirs.join(\" and \")}, so its documents could not be scanned`);\n    }\n    return out;\n  };\n\n  const opConsumers = async (provider: string, op: string): Promise<ConsumerScan> => {\n    const { usable, resolve } = await landscape();\n    const scan = scanRequirements({ provider, axes: [\"spec\"], hit: (r) => r.operations.includes(op) });\n    const edges: string[] = [];\n    if (usable !== null && resolve !== null) {\n      for (const r of usable.relationships) {\n        if (r.op === op && resolve(r.target) === provider) edges.push(EDGE(resolve, r));\n      }\n    }\n    // Flows last in each list, deliberately: the edge and the requirement say\n    // WHICH document to open, and the flow says what the reader is about to\n    // break — so a `details[]` scanned top-down ends on the consequence.\n    const hops = hopsExercising(await useCases(), { provider, op });\n    return {\n      victims: [...edges, ...scan.victims, ...hops.breaks],\n      suspended: [...scan.suspended, ...hops.unsure],\n    };\n  };\n\n  const messageConsumers = async (provider: string, name: string): Promise<ConsumerScan> => {\n    const { usable, resolve } = await landscape();\n    const scan = scanRequirements({ provider, axes: [\"spec\", \"archSpec\"], hit: (r) => r.consumes.includes(name) });\n    const edges: string[] = [];\n    if (usable !== null && resolve !== null) {\n      for (const r of usable.relationships) {\n        // The message join is fleet-global, so every edge naming it counts —\n        // except one into the provider itself, whose consumption leaves with\n        // the same change (events/lookups.ts's exclusion, verbatim).\n        if (r.consumes === name && resolve(r.target) !== provider) edges.push(EDGE(resolve, r));\n      }\n    }\n    const hops = hopsConsuming(await useCases(), { provider, name });\n    return { victims: [...edges, ...scan.victims, ...hops], suspended: scan.suspended };\n  };\n\n  const declarers = (name: string): string[] =>\n    ids.filter((id) => {\n      const axis = snap.current.get(id)!.asyncapi;\n      return axis.kind === \"read\" && axis.value.some((m) => m.name === name);\n    });\n\n  return { opConsumers, messageConsumers, declarers };\n}\n\n/**\n * One cross-service join: `consumer`'s living requirements name a `token` that\n * `provider`'s contract defines. The same \"who depends on what\" question the\n * index above answers per removal, asked here of a WHOLE state — base or\n * current — so `semantic.ts` can report joins that appeared or went away.\n */\nexport interface ConsumerTuple {\n  kind: \"op\" | \"message\";\n  consumer: string;\n  provider: string;\n  token: string;\n}\n\n/** The map key a tuple is joined on between the two states. */\nfunction tupleKey(t: ConsumerTuple): string {\n  return `${t.kind}\\0${t.consumer}\\0${t.provider}\\0${t.token}`;\n}\n\n/**\n * Every cross-service join one state holds, keyed for the base/current join.\n * Axis rules mirror the two consumer scans above: `Operations:` from spec.md\n * only, `Consumes:` from both spec axes. Unreadable axes simply contribute\n * nothing here — `semantic.ts` guards the GRADING so a join is never called\n * added or removed off a side nobody could read.\n */\nexport function consumerTuples(states: ReadonlyMap<string, ServiceState>): Map<string, ConsumerTuple> {\n  const providersOf = (pick: (s: ServiceState) => string[]): Map<string, string[]> => {\n    const map = new Map<string, string[]>();\n    for (const id of [...states.keys()].sort()) {\n      for (const token of pick(states.get(id)!)) map.set(token, [...(map.get(token) ?? []), id]);\n    }\n    return map;\n  };\n  const opProviders = providersOf((s) => (s.openapi.kind === \"read\" ? s.openapi.value.map((op) => op.id) : []));\n  const msgProviders = providersOf((s) => (s.asyncapi.kind === \"read\" ? s.asyncapi.value.map((m) => m.name) : []));\n  const out = new Map<string, ConsumerTuple>();\n  const add = (t: ConsumerTuple): void => {\n    out.set(tupleKey(t), t);\n  };\n  for (const consumer of [...states.keys()].sort()) {\n    const state = states.get(consumer)!;\n    for (const r of reqsOf(state, [\"spec\"])) {\n      for (const op of r.operations) {\n        for (const p of opProviders.get(op) ?? []) if (p !== consumer) add({ kind: \"op\", consumer, provider: p, token: op });\n      }\n    }\n    for (const r of reqsOf(state, [\"spec\", \"archSpec\"])) {\n      for (const name of r.consumes) {\n        for (const p of msgProviders.get(name) ?? []) if (p !== consumer) add({ kind: \"message\", consumer, provider: p, token: name });\n      }\n    }\n  }\n  return out;\n}\n\n/** May a tuple be graded off this side? Absence answers; unreadable does not; an ambiguous base identity answers nothing. */\nfunction tupleVisible(states: ReadonlyMap<string, ServiceState>, ambiguous: ReadonlySet<string>, t: ConsumerTuple): boolean {\n  if (ambiguous.has(t.consumer) || ambiguous.has(t.provider)) return false;\n  const readable = (id: string, axes: (\"spec\" | \"archSpec\" | \"openapi\" | \"asyncapi\")[]): boolean => {\n    const state = states.get(id);\n    return state === undefined || axes.every((axis) => state[axis].kind !== \"unreadable\");\n  };\n  return (\n    readable(t.consumer, t.kind === \"op\" ? [\"spec\"] : [\"spec\", \"archSpec\"]) &&\n    readable(t.provider, [t.kind === \"op\" ? \"openapi\" : \"asyncapi\"])\n  );\n}\n\n/** One graded cross-service join change between the two states. */\nexport interface ConsumerChange {\n  t: ConsumerTuple;\n  change: \"added\" | \"removed\";\n}\n\n/**\n * The joins that appeared or went away between base and current, sorted for\n * deterministic output (provider, kind, token, consumer). The visibility\n * guard is the containment rule: a join is never called \"added\" off a base\n * side nobody could read, nor \"removed\" off an unreadable working file — the\n * suspended axis already carries that fact.\n */\nexport function consumerJoinChanges(input: {\n  base: ReadonlyMap<string, ServiceState>;\n  baseAmbiguous: ReadonlySet<string>;\n  current: ReadonlyMap<string, ServiceState>;\n  currentAmbiguous: ReadonlySet<string>;\n}): ConsumerChange[] {\n  const baseTuples = consumerTuples(input.base);\n  const currentTuples = consumerTuples(input.current);\n  const graded: ConsumerChange[] = [];\n  for (const [key, t] of currentTuples) {\n    if (!baseTuples.has(key) && tupleVisible(input.base, input.baseAmbiguous, t)) graded.push({ t, change: \"added\" });\n  }\n  for (const [key, t] of baseTuples) {\n    if (!currentTuples.has(key) && tupleVisible(input.current, input.currentAmbiguous, t)) graded.push({ t, change: \"removed\" });\n  }\n  return graded.sort((a, b) => {\n    const ka = `${a.t.provider}\\0${a.t.kind}\\0${a.t.token}\\0${a.t.consumer}\\0${a.change}`;\n    const kb = `${b.t.provider}\\0${b.t.kind}\\0${b.t.token}\\0${b.t.consumer}\\0${b.change}`;\n    return ka < kb ? -1 : 1;\n  });\n}\n"]}

package/dist/core/repo/tree/views.js

@@ -1,172 +0,0 @@
-/**
- * The generated views file: `architecture/subsystems.likec4`, one LikeC4 view
- * per subsystem enumerating the services beneath it. GENERATED, never
- * authored — authored bytes stay authored (archive's verbatim-splice promise),
- * so the tree is mirrored into a file of its own that `loam subsystem sync`
- * owns outright, and staleness against the tree is a byte compare
- * (`subsystem.views-stale` in `validate --all`), never a parse: a spike
- * confirmed a views-only document does NOT parse standalone (its `include`
- * lines reference elements the landscape defines), so nothing in loam ever
- * loads this file (and rule 26 does not change that: this file is GENERATED and
- * holds STATIC views, whose contents loam may not read in any document) — only
- * the LikeC4 renderer, which merges the whole `architecture/` project per
- * likec4.config.json, resolves it.
- *
- * The output is deterministic and line-oriented, and both halves are the
- * contract: subsystems sorted by path, members sorted by id, ONE `include`
- * per line — so two concurrent moves into different groups touch different
- * lines and git merges the file without intervention, exactly as the
- * service-grouped landscape splice already achieves. Byte-reproducible on any
- * machine: no timestamps, no absolute paths, no readdir-order dependence (the
- * walk sorts, and every list is re-sorted here). Plain lexicographic sorts on
- * purpose — the ids' own grammar is ASCII, an INVALID name is still ordered
- * deterministically, and `compareIds`' numeric tokenizing lives in `repo/`,
- * which this package must not import (`walk.ts` says why the edge only points
- * the other way).
- *
- * Membership is TRANSITIVE: a subsystem's view includes every service beneath
- * it at any depth, so a parent's view is the whole group's map rather than an
- * empty frame around its children. An empty view body is legal LikeC4 (same
- * spike), so an empty subsystem renders as one — `subsystem new` must be
- * usable before anything moves in.
- *
- * Include lines name the landscape ELEMENT id, resolved through the same
- * element→service join `validate` uses (`serviceResolver`: explicit
- * `metadata { service }` binding first, then a title naming a real service) —
- * because element ids in real landscapes are not service ids, and a view of
- * raw service ids would silently render empty for every such fleet. A member
- * with no landscape element is omitted from the includes: the omission is
- * already an error (`landscape.service-unmodelled`), and rendering only what
- * the committed landscape resolves keeps the output a function of committed
- * bytes alone.
- */
-import {} from "../../c4/likec4.js";
-import { serviceResolver } from "../../c4/resolve/service.js";
-import { servicesUnder } from "./find.js";
-/**
- * The header every generated file opens with — stable bytes, part of the
- * byte-compare contract, naming the regenerator so a reader who found the
- * file first knows what owns it.
- */
-const HEADER = "// generated by loam — the subsystem tree under services/, one view per subsystem.\n" +
-    "// Do not edit: `loam subsystem sync` regenerates this file from the directories,\n" +
-    "// and `loam validate --all` reports `subsystem.views-stale` when it drifts.\n";
-/**
- * Render the views file for a walked tree, or null when the tree has no
- * subsystems — the file must then be ABSENT, so a flat fleet never carries a
- * generated artifact that says nothing.
- */
-export function renderSubsystemViews(tree, elements) {
-    if (tree.subsystems.length === 0)
-        return null;
-    const elementOf = elementByService(tree, elements);
-    const lines = [HEADER, "views {"];
-    const subsystems = [...tree.subsystems].sort((a, b) => (pathKey(a) < pathKey(b) ? -1 : 1));
-    for (const [i, sub] of subsystems.entries()) {
-        if (i > 0)
-            lines.push("");
-        lines.push(`  // services/${pathKey(sub)}`);
-        lines.push(`  view ${subsystemViewId(sub)} {`);
-        for (const member of membersOf(tree, sub)) {
-            const element = elementOf.get(member.id);
-            if (element !== undefined)
-                lines.push(`    include ${element}`);
-        }
-        lines.push("  }");
-    }
-    lines.push("}");
-    return lines.join("\n") + "\n";
-}
-/**
- * The landscape element standing for each service id: for every element,
- * resolve it through the shared join, and let the SHALLOWEST element win
- * (document order breaking ties). Shallowest, because `serviceResolver`
- * resolves a service's own containers to the service too, and a view should
- * include the service-level box, not whichever nested container happened to
- * be declared first.
- */
-function elementByService(tree, elements) {
-    const known = new Set(tree.services.map((s) => s.id));
-    const resolve = serviceResolver(elements, known);
-    const depth = (id) => id.split(".").length;
-    const out = new Map();
-    for (const e of elements) {
-        const service = resolve(e.id);
-        if (!known.has(service))
-            continue;
-        const held = out.get(service);
-        if (held === undefined || depth(e.id) < depth(held))
-            out.set(service, e.id);
-    }
-    return out;
-}
-/** Services beneath this subsystem at any depth, ordered by id — the transitive membership. */
-function membersOf(tree, sub) {
-    return [...servicesUnder(tree, sub)].sort((a, b) => (a.id < b.id ? -1 : 1));
-}
-/** The sort key and the comment spelling: the subsystem's path from services/, joined. */
-function pathKey(sub) {
-    return sub.path.join("/");
-}
-/**
- * A LikeC4 identifier for the view, derived from the subsystem's path so
- * nesting reads in the name — and INJECTIVE over every path the name grammar
- * admits, because the renderer refuses the whole `architecture/` project over
- * a duplicate view id. The naive folding (every non-identifier byte and the
- * join separator alike becoming `_`) collided three DISTINCT healthy names
- * onto one identifier — `a_b`, and `b` under `a`, both rendered
- * `subsystem_a_b` — so `validate --all` was green while the renderer refused
- * the fleet map; `subsystem.name-collision` never fires because the flat
- * namespace really is intact. Hence the encoding: an identifier byte
- * (`[A-Za-z0-9]`) passes through, any other byte becomes `_` + two lowercase
- * hex digits (`.` → `_2e`, `-` → `_2d`, `_` itself → `_5f` — the underscore
- * must be escaped precisely because it is BOTH legal in a name and the
- * separator), and segments join on `__`. Underscore runs then decode
- * uniquely — one is an escape, two a separator, three a separator followed
- * by an escape — so no two distinct legal paths share an identifier. A name
- * `subsystem.name-invalid` already flagged may hold a code point above 0xff
- * whose longer hex could in principle re-collide; it is deterministic still,
- * and that directory is already an error finding by name.
- *
- * EXPORTED, with its prefix, because `subsystem.view-id-collision` has to ask
- * the generator what it mints rather than re-deriving it. A check carrying its
- * own copy of the escaping above would go quiet the day the encoding changed,
- * and going quiet is the failure this whole family exists to prevent.
- */
-export const SUBSYSTEM_VIEW_PREFIX = "subsystem_";
-export function subsystemViewId(sub) {
-    const segment = (name) => [...name].map((ch) => (/[A-Za-z0-9]/.test(ch) ? ch : `_${ch.codePointAt(0).toString(16).padStart(2, "0")}`)).join("");
-    return `subsystem_${sub.path.map(segment).join("__")}`;
-}
-/**
- * Does the file on disk already SAY what `renderSubsystemViews` renders?
- *
- * The generator above only ever emits LF. `core.autocrlf=true` is Git for
- * Windows' installer default and a docs repo ships no `.gitattributes`, so an
- * ordinary Windows clone hands the file back with CRLF and not one fact
- * changed. Four call sites asked this question with a byte equality and all
- * four answered "stale" on such a clone: `loam validate` reported an error,
- * `loam subsystem sync` reported `updated` and rewrote with LF, git then showed
- * the file permanently modified, and the next checkout restored the CRLF. That
- * is a loop rather than a diagnosis, which is why the comparison lives here
- * now — the module that mints the bytes is the one that owes an answer about
- * them, and three near-copies of this rule would go stale one at a time.
- *
- * Still never a parse: a views-only document does not parse standalone, and no
- * check anywhere reads this file's content. The narrowing is from BYTES to
- * CONTENT, which is what `subsystem.views-stale`'s own message ("does not match
- * the tree") already claims. The symmetric cost is accepted and is the one
- * `core/verify/pins/pin.ts` documents for `pinnedDigest`: a pure line-ending
- * change is invisible, correctly, because it is not a change to what the file
- * says.
- *
- * `null` is carried through as itself rather than collapsing into `""`: absent,
- * must-be-absent and present-but-different are three distinct states with three
- * distinct messages, and a fleet whose views file does not exist is not a fleet
- * whose views file is blank.
- */
-export function viewsAgree(actual, expected) {
-    const lf = (text) => (text === null ? null : text.replace(/\r\n|\r/g, "\n"));
-    return lf(actual) === lf(expected);
-}
-//# sourceMappingURL=views.js.map

package/dist/core/repo/tree/views.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"views.js","sourceRoot":"","sources":["../../../../src/core/repo/tree/views.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The generated views file: `architecture/subsystems.likec4`, one LikeC4 view\n * per subsystem enumerating the services beneath it. GENERATED, never\n * authored — authored bytes stay authored (archive's verbatim-splice promise),\n * so the tree is mirrored into a file of its own that `loam subsystem sync`\n * owns outright, and staleness against the tree is a byte compare\n * (`subsystem.views-stale` in `validate --all`), never a parse: a spike\n * confirmed a views-only document does NOT parse standalone (its `include`\n * lines reference elements the landscape defines), so nothing in loam ever\n * loads this file (and rule 26 does not change that: this file is GENERATED and\n * holds STATIC views, whose contents loam may not read in any document) — only\n * the LikeC4 renderer, which merges the whole `architecture/` project per\n * likec4.config.json, resolves it.\n *\n * The output is deterministic and line-oriented, and both halves are the\n * contract: subsystems sorted by path, members sorted by id, ONE `include`\n * per line — so two concurrent moves into different groups touch different\n * lines and git merges the file without intervention, exactly as the\n * service-grouped landscape splice already achieves. Byte-reproducible on any\n * machine: no timestamps, no absolute paths, no readdir-order dependence (the\n * walk sorts, and every list is re-sorted here). Plain lexicographic sorts on\n * purpose — the ids' own grammar is ASCII, an INVALID name is still ordered\n * deterministically, and `compareIds`' numeric tokenizing lives in `repo/`,\n * which this package must not import (`walk.ts` says why the edge only points\n * the other way).\n *\n * Membership is TRANSITIVE: a subsystem's view includes every service beneath\n * it at any depth, so a parent's view is the whole group's map rather than an\n * empty frame around its children. An empty view body is legal LikeC4 (same\n * spike), so an empty subsystem renders as one — `subsystem new` must be\n * usable before anything moves in.\n *\n * Include lines name the landscape ELEMENT id, resolved through the same\n * element→service join `validate` uses (`serviceResolver`: explicit\n * `metadata { service }` binding first, then a title naming a real service) —\n * because element ids in real landscapes are not service ids, and a view of\n * raw service ids would silently render empty for every such fleet. A member\n * with no landscape element is omitted from the includes: the omission is\n * already an error (`landscape.service-unmodelled`), and rendering only what\n * the committed landscape resolves keeps the output a function of committed\n * bytes alone.\n */\nimport { type Elem } from \"../../c4/likec4.js\";\nimport { serviceResolver } from \"../../c4/resolve/service.js\";\nimport { servicesUnder } from \"./find.js\";\nimport type { FleetTree, SubsystemEntry, WalkedService } from \"./walk.js\";\n\n/**\n * The header every generated file opens with — stable bytes, part of the\n * byte-compare contract, naming the regenerator so a reader who found the\n * file first knows what owns it.\n */\nconst HEADER =\n  \"// generated by loam — the subsystem tree under services/, one view per subsystem.\\n\" +\n  \"// Do not edit: `loam subsystem sync` regenerates this file from the directories,\\n\" +\n  \"// and `loam validate --all` reports `subsystem.views-stale` when it drifts.\\n\";\n\n/**\n * Render the views file for a walked tree, or null when the tree has no\n * subsystems — the file must then be ABSENT, so a flat fleet never carries a\n * generated artifact that says nothing.\n */\nexport function renderSubsystemViews(tree: FleetTree, elements: Elem[]): string | null {\n  if (tree.subsystems.length === 0) return null;\n  const elementOf = elementByService(tree, elements);\n  const lines: string[] = [HEADER, \"views {\"];\n  const subsystems = [...tree.subsystems].sort((a, b) => (pathKey(a) < pathKey(b) ? -1 : 1));\n  for (const [i, sub] of subsystems.entries()) {\n    if (i > 0) lines.push(\"\");\n    lines.push(`  // services/${pathKey(sub)}`);\n    lines.push(`  view ${subsystemViewId(sub)} {`);\n    for (const member of membersOf(tree, sub)) {\n      const element = elementOf.get(member.id);\n      if (element !== undefined) lines.push(`    include ${element}`);\n    }\n    lines.push(\"  }\");\n  }\n  lines.push(\"}\");\n  return lines.join(\"\\n\") + \"\\n\";\n}\n\n/**\n * The landscape element standing for each service id: for every element,\n * resolve it through the shared join, and let the SHALLOWEST element win\n * (document order breaking ties). Shallowest, because `serviceResolver`\n * resolves a service's own containers to the service too, and a view should\n * include the service-level box, not whichever nested container happened to\n * be declared first.\n */\nfunction elementByService(tree: FleetTree, elements: Elem[]): Map<string, string> {\n  const known: ReadonlySet<string> = new Set(tree.services.map((s) => s.id));\n  const resolve = serviceResolver(elements, known);\n  const depth = (id: string): number => id.split(\".\").length;\n  const out = new Map<string, string>();\n  for (const e of elements) {\n    const service = resolve(e.id);\n    if (!known.has(service)) continue;\n    const held = out.get(service);\n    if (held === undefined || depth(e.id) < depth(held)) out.set(service, e.id);\n  }\n  return out;\n}\n\n/** Services beneath this subsystem at any depth, ordered by id — the transitive membership. */\nfunction membersOf(tree: FleetTree, sub: SubsystemEntry): WalkedService[] {\n  return [...servicesUnder(tree, sub)].sort((a, b) => (a.id < b.id ? -1 : 1));\n}\n\n/** The sort key and the comment spelling: the subsystem's path from services/, joined. */\nfunction pathKey(sub: SubsystemEntry): string {\n  return sub.path.join(\"/\");\n}\n\n/**\n * A LikeC4 identifier for the view, derived from the subsystem's path so\n * nesting reads in the name — and INJECTIVE over every path the name grammar\n * admits, because the renderer refuses the whole `architecture/` project over\n * a duplicate view id. The naive folding (every non-identifier byte and the\n * join separator alike becoming `_`) collided three DISTINCT healthy names\n * onto one identifier — `a_b`, and `b` under `a`, both rendered\n * `subsystem_a_b` — so `validate --all` was green while the renderer refused\n * the fleet map; `subsystem.name-collision` never fires because the flat\n * namespace really is intact. Hence the encoding: an identifier byte\n * (`[A-Za-z0-9]`) passes through, any other byte becomes `_` + two lowercase\n * hex digits (`.` → `_2e`, `-` → `_2d`, `_` itself → `_5f` — the underscore\n * must be escaped precisely because it is BOTH legal in a name and the\n * separator), and segments join on `__`. Underscore runs then decode\n * uniquely — one is an escape, two a separator, three a separator followed\n * by an escape — so no two distinct legal paths share an identifier. A name\n * `subsystem.name-invalid` already flagged may hold a code point above 0xff\n * whose longer hex could in principle re-collide; it is deterministic still,\n * and that directory is already an error finding by name.\n *\n * EXPORTED, with its prefix, because `subsystem.view-id-collision` has to ask\n * the generator what it mints rather than re-deriving it. A check carrying its\n * own copy of the escaping above would go quiet the day the encoding changed,\n * and going quiet is the failure this whole family exists to prevent.\n */\nexport const SUBSYSTEM_VIEW_PREFIX = \"subsystem_\";\n\nexport function subsystemViewId(sub: SubsystemEntry): string {\n  const segment = (name: string): string =>\n    [...name].map((ch) => (/[A-Za-z0-9]/.test(ch) ? ch : `_${ch.codePointAt(0)!.toString(16).padStart(2, \"0\")}`)).join(\"\");\n  return `subsystem_${sub.path.map(segment).join(\"__\")}`;\n}\n\n/**\n * Does the file on disk already SAY what `renderSubsystemViews` renders?\n *\n * The generator above only ever emits LF. `core.autocrlf=true` is Git for\n * Windows' installer default and a docs repo ships no `.gitattributes`, so an\n * ordinary Windows clone hands the file back with CRLF and not one fact\n * changed. Four call sites asked this question with a byte equality and all\n * four answered \"stale\" on such a clone: `loam validate` reported an error,\n * `loam subsystem sync` reported `updated` and rewrote with LF, git then showed\n * the file permanently modified, and the next checkout restored the CRLF. That\n * is a loop rather than a diagnosis, which is why the comparison lives here\n * now — the module that mints the bytes is the one that owes an answer about\n * them, and three near-copies of this rule would go stale one at a time.\n *\n * Still never a parse: a views-only document does not parse standalone, and no\n * check anywhere reads this file's content. The narrowing is from BYTES to\n * CONTENT, which is what `subsystem.views-stale`'s own message (\"does not match\n * the tree\") already claims. The symmetric cost is accepted and is the one\n * `core/verify/pins/pin.ts` documents for `pinnedDigest`: a pure line-ending\n * change is invisible, correctly, because it is not a change to what the file\n * says.\n *\n * `null` is carried through as itself rather than collapsing into `\"\"`: absent,\n * must-be-absent and present-but-different are three distinct states with three\n * distinct messages, and a fleet whose views file does not exist is not a fleet\n * whose views file is blank.\n */\nexport function viewsAgree(actual: string | null, expected: string | null): boolean {\n  const lf = (text: string | null): string | null => (text === null ? null : text.replace(/\\r\\n|\\r/g, \"\\n\"));\n  return lf(actual) === lf(expected);\n}\n"]}

package/dist/core/staging/snapshot.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../../src/core/staging/snapshot.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The undo snapshot: the bytes `archive` is about to overwrite, parked inside\n * the feature directory so they travel with it into `features/archive/`.\n *\n * Separate from the commit because the merge is not invertible — a MODIFIED\n * requirement's previous text appears nowhere in the delta, and a landscape\n * rewritten by hand since cannot be un-rewritten by re-reading one. `unarchive`\n * puts bytes back; it does not recompute them. Nothing on the commit path reads\n * this module: only `archive` writes a snapshot and only `unarchive` honours one.\n */\nimport { existsSync } from \"node:fs\";\nimport { mkdir, readFile, writeFile } from \"node:fs/promises\";\nimport { dirname, join } from \"node:path\";\nimport { repoPath } from \"../envelope/json.js\";\nimport { resolvePortableFileInsideLexically, UnsafePathError } from \"../kernel/path-safety.js\";\n// Every `isRecord` below guards a record loam itself wrote and is reading back\n// — the lock, the snapshot manifest — whose fields are asked for on the very\n// next line, inside a REFUSAL path. `JSON.parse` answers with any JSON value,\n// not with an object, and that is where a thrown `TypeError` costs the most: it\n// does not make the command fail safely, it replaces a designed refusal with\n// `internal`.\nimport { isRecord } from \"../kernel/records.js\";\nimport { isDigest, sha256, type StagedWrite } from \"./writes.js\";\nimport { message, quietRm } from \"./commit.js\";\n\n/** Where archive parks the pre-images, inside the feature directory so they travel with it — the module doc above says why. */\nexport const SNAPSHOT_DIR = \".loam-before\";\nexport const SNAPSHOT_MANIFEST = \"manifest.json\";\n/**\n * Bumped only when the layout changes in a way `unarchive` must refuse to guess\n * at. 2 added `before`: a version-1 snapshot says nothing about the bytes it\n * would RESTORE, so an edited pre-image read back as an intact one. 3 re-keys\n * `services/` entries by `(service, artifact)`: a literal path pins the service\n * directory where it stood on the day of the archive, and once the subsystem\n * tree lets it move — re-cutting is expected to be routine — an undo addressed\n * by path restores into a location that is gone. The service id never moves.\n */\nexport const SNAPSHOT_VERSION = 3;\n/**\n * Version 2 is still READ, forever: version-2 snapshots already sit inside\n * archived features, which carry them across loam upgrades, and each must keep\n * restoring — and keep being graded for staleness by a retried archive — under\n * its own literal-path rules. Only version 1 is refused (no restore digests).\n */\nexport const SNAPSHOT_COMPAT_VERSION = 2;\n\nexport interface SnapshotEntry {\n  /**\n   * Docs-repo-relative path, forward slashes, AS ARCHIVED. Load-bearing even\n   * beside the key below: it names the pre-image under `.loam-before/files/`,\n   * and it is the literal fallback when the id stops being enumerated.\n   */\n  path: string;\n  /**\n   * For a `services/` entry: the service id (the leaf directory name — the one\n   * thing a re-cut never changes) and the artifact's path inside its directory,\n   * resolved through the CURRENT enumeration at restore time. Absent on\n   * landscape and `features/` entries, which do not move.\n   */\n  service?: string;\n  artifact?: string;\n  /** False when archive CREATED the file: restoring it means deleting it again. */\n  existed: boolean;\n  /** sha256 of what archive wrote, so unarchive can tell its own merge from later edits. */\n  after: string;\n  /**\n   * sha256 of the pre-image beside this manifest — the bytes `unarchive` will\n   * RESTORE. Null when archive created the file (there is no pre-image).\n   * `after` only describes what archive wrote; while nothing described the\n   * restore source, a pre-image edited in the archived feature directory — a\n   * bad merge, a rebase, a stray editor — was written back verbatim and every\n   * loam surface certified the result.\n   */\n  before: string | null;\n}\n\n/** A snapshot directory that must not be replaced, because it is the only copy of the true pre-images. */\nexport class SnapshotClobberError extends Error {\n  override readonly name = \"SnapshotClobberError\";\n\n  constructor(readonly dir: string, detail: string) {\n    super(\n      `${dir} already holds an undo snapshot that does NOT match the living docs (${detail}) — a previous archive of ` +\n        `this feature wrote to the living docs and never took them back, and these are the only copies of what they ` +\n        `said before. Overwriting them would make that merge permanent and unreportable. Run \\`loam archive\\` again ` +\n        `after restoring the living docs from version control, or delete ${SNAPSHOT_DIR}/ if you know the merge never landed.`,\n    );\n  }\n}\n\nexport interface SnapshotManifest {\n  version: number;\n  feature: string;\n  dirName: string;\n  archivedAt: string;\n  files: SnapshotEntry[];\n}\n\nexport function snapshotDir(featureDir: string): string {\n  return join(featureDir, SNAPSHOT_DIR);\n}\n\n/** The (service, artifact) key a `services/` path decomposes into. */\nexport interface ServiceKey {\n  service: string;\n  artifact: string;\n}\n\n/**\n * Everything `writeSnapshot` needs, as one object. The resolvers are INJECTED\n * by the caller — `archive` builds them from its view of the tree — because\n * how a path decomposes into a service identity is repo-layout knowledge, and\n * this module's subject is parking and checking bytes.\n */\nexport interface SnapshotRequest {\n  featureDir: string;\n  docsDir: string;\n  feature: { featureId: string; dirName: string };\n  staged: StagedWrite[];\n  /** Docs-relative path → the service it belongs to; null for landscape/features paths. */\n  serviceKeyOf: (rel: string) => ServiceKey | null;\n  /** Service id → its CURRENT docs-relative directory; null when not enumerated. */\n  serviceDirOf: (service: string) => string | null;\n}\n\nexport async function writeSnapshot(request: SnapshotRequest): Promise<void> {\n  const { featureDir, docsDir, staged } = request;\n  const { featureId, dirName } = request.feature;\n  const dir = snapshotDir(featureDir);\n  await assertSnapshotReplaceable(dir, docsDir, request.serviceDirOf);\n  // A leftover from a rolled-back run would describe a merge that never happened.\n  await quietRm(dir);\n\n  const files: SnapshotEntry[] = [];\n  for (const s of staged) {\n    const rel = repoPath(docsDir, s.write.path);\n    // services/ entries are re-keyed by (service, artifact) so they survive the\n    // service directory moving between archive and unarchive; the literal path\n    // is still recorded — it keys the pre-image below, and it is the fallback.\n    const key = request.serviceKeyOf(rel);\n    files.push({\n      path: rel,\n      ...key,\n      existed: s.before !== null,\n      after: sha256(s.content ?? Buffer.alloc(0)),\n      before: s.before === null ? null : sha256(s.before),\n    });\n    if (s.before !== null) {\n      const dest = join(dir, \"files\", rel);\n      await mkdir(dirname(dest), { recursive: true });\n      await writeFile(dest, s.before);\n    }\n  }\n\n  const manifest: SnapshotManifest = {\n    version: SNAPSHOT_VERSION,\n    feature: featureId,\n    dirName,\n    archivedAt: new Date().toISOString(),\n    files,\n  };\n  // Manifest last: its presence is what says the pre-images beside it are complete.\n  await mkdir(dir, { recursive: true });\n  await writeFile(join(dir, SNAPSHOT_MANIFEST), JSON.stringify(manifest, null, 2) + \"\\n\", \"utf8\");\n}\n\n/**\n * Refuse to replace a snapshot whose pre-images are still the only record of\n * what the living docs said.\n *\n * A snapshot in an ACTIVE feature directory means a previous archive of this\n * same feature wrote it — and since a clean rollback deletes it, finding one\n * means that run either died mid-commit or reported `rollback-incomplete`. If\n * its pre-images still match the living docs, nothing of that run landed and\n * the snapshot is stale bookkeeping. If they do not, the living docs carry\n * that run's writes, these files are the only way back, and the unconditional\n * clear turned a repairable half-merge into a permanent one — after which\n * `unarchive` restored the half-merged text and said the docs were back.\n *\n * Version 2 manifests are graded by the same staleness question over their\n * literal paths — refusing them as \"a different loam\" would turn every leftover\n * version-2 snapshot into a permanent archive refusal on upgrade.\n */\nasync function assertSnapshotReplaceable(\n  dir: string,\n  docsDir: string,\n  serviceDirOf: (service: string) => string | null,\n): Promise<void> {\n  const manifestPath = join(dir, SNAPSHOT_MANIFEST);\n  // The manifest is written LAST, so a `files/` tree without one is a snapshot\n  // whose run died before it could swap anything: it describes no merge.\n  if (!existsSync(manifestPath)) return;\n  let manifest: unknown;\n  try {\n    manifest = JSON.parse(await readFile(manifestPath, \"utf8\"));\n  } catch {\n    throw new SnapshotClobberError(dir, `${SNAPSHOT_MANIFEST} cannot be read, so nothing can say whether it is stale`);\n  }\n  // The cast that used to stand here asserted the shape rather than checking\n  // it: well-formed JSON that is not an object answered `undefined` to every\n  // field below and slipped through as \"a different loam\", and a bare `null`\n  // threw a TypeError out of the refusal itself. Both left this directory —\n  // which may hold the only copies of what the living docs said — one step from\n  // being replaced, without the staleness question ever having been asked.\n  if (!isRecord(manifest)) {\n    throw new SnapshotClobberError(dir, `${SNAPSHOT_MANIFEST} cannot be read, so nothing can say whether it is stale`);\n  }\n  if (\n    (manifest.version !== SNAPSHOT_VERSION && manifest.version !== SNAPSHOT_COMPAT_VERSION) ||\n    !Array.isArray(manifest.files)\n  ) {\n    throw new SnapshotClobberError(dir, `it was written by a different loam and cannot be checked against the living docs`);\n  }\n  // `Array.isArray` narrows to `any[]`; naming the element type here is what\n  // keeps that `any` from spreading past the one row being read.\n  const rows: unknown[] = manifest.files;\n  const landed: string[] = [];\n  for (const row of rows) {\n    const entry = readSnapshotClaim(row);\n    if (entry === null) {\n      throw new SnapshotClobberError(dir, `${SNAPSHOT_MANIFEST} is malformed, so nothing can say whether it is stale`);\n    }\n    let target: string;\n    try {\n      // These paths are data, and they are the ones this function goes and\n      // reads. They name living documents, so containment is lexical: a docs\n      // repo may legitimately mount a service directory through a symlink, and\n      // `unarchive` resolves the same field the same way before it writes back.\n      target = resolvePortableFileInsideLexically(docsDir, entry.path, `snapshot path '${entry.path}'`);\n      // A re-keyed entry's CURRENT location is wherever the enumeration says\n      // its service lives today — grading staleness at the old address would\n      // call a merely-moved file a landed merge. The literal path was still\n      // resolved above on purpose: its containment is part of what \"loam wrote\n      // this manifest\" means, and it stays the pre-image's key. An id the\n      // enumeration no longer answers falls back to that literal path.\n      if (entry.service !== undefined && entry.artifact !== undefined) {\n        const current = serviceDirOf(entry.service);\n        if (current !== null) {\n          target = resolvePortableFileInsideLexically(\n            docsDir,\n            `${current}/${entry.artifact}`,\n            `snapshot path '${entry.path}'`,\n          );\n        }\n      }\n    } catch (err) {\n      if (!(err instanceof UnsafePathError)) throw err;\n      throw new SnapshotClobberError(dir, `${message(err)}, so nothing can say whether it is stale`);\n    }\n    const now = existsSync(target) ? sha256(await readFile(target)) : null;\n    // `existed: false` means archive created the file, so \"nothing landed\"\n    // means it is still absent.\n    const untouched = entry.existed ? now === entry.before : now === null;\n    if (!untouched) landed.push(entry.path);\n  }\n  if (landed.length > 0) throw new SnapshotClobberError(dir, `${landed.length} file(s) already carry that merge: ${landed.join(\", \")}`);\n}\n\n/**\n * One manifest row read back as the record `writeSnapshot` wrote, or null when\n * the file does not actually say.\n *\n * Every field the staleness question consumes is checked, because an unchecked\n * field does not read as missing here — it reads as an ANSWER. An `existed`\n * that is not a boolean is falsy, and a `false` claim is graded by asking\n * whether the file is ABSENT: a manifest recording a pre-image for a deleted\n * file therefore graded as stale bookkeeping and was cleared, taking the only\n * copy of that pre-image with it. A `before` of the wrong type equals no digest\n * at all, so the opposite row accused an untouched file of carrying a merge.\n *\n * `unarchive` asks a stricter version of the same question of the same file\n * (`after`, `archivedAt`, the feature name, no duplicates) because it is about\n * to write THROUGH it; that check stays where it is, with its own refusals.\n *\n * `service`/`artifact` are read when present (a version-3 `services/` row) and\n * must arrive as a pair: half a key is a manifest that does not say where the\n * file lives, and grading through the literal path anyway would be a guess.\n */\ninterface SnapshotClaim {\n  path: string;\n  existed: boolean;\n  before: string | null;\n  service?: string;\n  artifact?: string;\n}\n\nfunction readSnapshotClaim(value: unknown): SnapshotClaim | null {\n  if (!isRecord(value)) return null;\n  const { path, existed, before, service, artifact } = value;\n  if (typeof path !== \"string\" || typeof existed !== \"boolean\") return null;\n  let key: { service: string; artifact: string } | Record<string, never>;\n  if (service === undefined && artifact === undefined) key = {};\n  else if (typeof service === \"string\" && typeof artifact === \"string\") key = { service, artifact };\n  else return null;\n  if (existed) return isDigest(before) ? { path, existed, before, ...key } : null;\n  return before === null ? { path, existed, before, ...key } : null;\n}\n\n"]}

package/dist/core/verify/file.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"file.js","sourceRoot":"","sources":["../../../src/core/verify/file.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `verification.yaml` read back, and refused when it cannot be trusted.\n *\n * Reading is deliberately not the inverse of rendering. A record loam wrote is\n * re-graded on the way in — unreadable YAML, a shape that is not a\n * verification, a `summary` that disagrees with the claims below it — because\n * the file is data meant to survive without loam, and anything may have edited\n * it since. The render lives with the writer it feeds (`store/render.ts`\n * produces exactly the bytes `store/commit.ts` swaps into place; races and\n * kills mid-write live there too), and the lock that serialises writers is\n * taken by `commands/verify/verify.ts` before this module's authoritative\n * read. Nothing here touches the filesystem except to read.\n */\nimport { lstat, readFile } from \"node:fs/promises\";\nimport { parse } from \"yaml\";\nimport { isRecord } from \"../kernel/records.js\";\nimport { VERDICTS } from \"./answers.js\";\nimport { isEvidencePinList } from \"./pins/pin.js\";\nimport { tallyAnswers, verificationPath, type Verification } from \"./record.js\";\n\n/**\n * What is on disk beside a feature: nothing, something unreadable, or a record.\n *\n * The three are kept apart because they call for opposite handling. \"Absent\" is\n * a feature nobody has verified — verify starts a fresh record over it without\n * a second thought. \"Unreadable\" is a file that IS somebody's record: it parses\n * as garbage, or its shape is not a record's, and every answer and attestation\n * it holds is unaccounted for. Collapsing the two (which this function used to\n * do, returning null for both) meant a hand-edited or half-written\n * verification.yaml read as \"not verified\" and the next `--record` overwrote a\n * whole fleet's attestations without a word.\n */\nexport type VerificationRead =\n  | { state: \"absent\" }\n  /**\n   * `reason` names the YAML line when the parser gave one — the file is the\n   * thing to fix. `code` is set for the one unreadable that parses perfectly: a\n   * record whose `summary` contradicts its own `claims[]`. That lives here\n   * rather than in a state of its own so every reader which already refuses an\n   * unreadable record refuses this one too, without a line of new code.\n   */\n  | { state: \"unreadable\"; reason: string; code?: \"verify.record-miscounted\" }\n  /**\n   * `raw` is the exact bytes `verification` was parsed from. A writer merges\n   * over the PARSE, but commits over the BYTES: `commitVerification` compares\n   * these against the file immediately before its swap, so an edit that landed\n   * between this read and that write — an editor, a writer that ignored the\n   * docs lock — is refused and preserved instead of silently buried.\n   */\n  | { state: \"ok\"; verification: Verification; raw: Buffer };\n\nexport async function readVerificationState(featureDir: string): Promise<VerificationRead> {\n  const path = verificationPath(featureDir);\n  let raw: Buffer;\n  try {\n    raw = await readFile(path);\n  } catch (err) {\n    if ((err as NodeJS.ErrnoException).code === \"ENOENT\") {\n      // ENOENT is \"absent\" — except from a symlink whose target is gone, which\n      // `existsSync` used to fold into the same answer. That mislabel was a\n      // trap: the read said \"no record\" while the commit's exclusive link(2)\n      // saw the link itself and refused EEXIST, so every `--record` answered\n      // `record-raced` with advice (re-run) that could never work. The lstat\n      // must CONFIRM the link before the message asserts one: a real file can\n      // also appear between the two calls, and telling its owner to \"remove\n      // the link\" would delete a valid record.\n      let entry;\n      try {\n        entry = await lstat(path);\n      } catch {\n        return { state: \"absent\" };\n      }\n      if (entry.isSymbolicLink()) {\n        return {\n          state: \"unreadable\",\n          reason: \"it is a symlink whose target does not exist — replace the link with a real record, or remove it\",\n        };\n      }\n      return {\n        state: \"unreadable\",\n        reason: \"it appeared while being read — another writer is landing; re-run\",\n      };\n    }\n    return { state: \"unreadable\", reason: err instanceof Error ? err.message : String(err) };\n  }\n  let doc: unknown;\n  try {\n    doc = parse(raw.toString(\"utf8\"));\n  } catch (err) {\n    return { state: \"unreadable\", reason: yamlReason(err) };\n  }\n  const verification = asVerification(doc);\n  if (verification === null) {\n    return {\n      state: \"unreadable\",\n      reason:\n        \"it parses as YAML but does not have a verification record's shape (feature, recorded, checklist, summary and claims)\",\n    };\n  }\n  const miscount = summaryDisagreement(verification);\n  if (miscount === null) return { state: \"ok\", verification, raw };\n  return {\n    state: \"unreadable\",\n    // Spelled twice on purpose: the field is what a caller branches on, the\n    // prose is what a terminal prints and what somebody greps for.\n    code: \"verify.record-miscounted\",\n    reason: `verify.record-miscounted: ${miscount}`,\n  };\n}\n\n/**\n * Does the record's `summary` add up from its own `claims[]`?\n *\n * The summary is what wrote the file; the claims are what it answered. Nothing\n * ever compared them, so every reader that took the shortcut — verify's frozen\n * verdict for a shipped feature, list's column, status's block — reported a\n * record full of unconfirmed claims as fully confirmed. Believing either side\n * over the other would be a guess about which half was tampered with, so a\n * record that contradicts itself is refused like any other file loam cannot\n * use. The code is in the reason: it travels wherever the reason is printed.\n */\nfunction summaryDisagreement(v: Verification): string | null {\n  const t = tallyAnswers(v.claims);\n  const unanswered = v.summary.unanswered ?? 0;\n  const says: string[] = [];\n  // Before the arithmetic, because a negative count defeats it: `unanswered:\n  // -2` is never something loam wrote, and it is the one value that lets a\n  // hand-edited summary balance its own books — every comparison below then\n  // agrees, and a record contradicting its claims reported `verified`.\n  for (const [field, value] of Object.entries(v.summary)) {\n    if (typeof value === \"number\" && value < 0) says.push(`carries a negative count (${field}: ${value})`);\n  }\n  if (v.summary.confirmed !== t.confirmed) {\n    says.push(`says ${v.summary.confirmed} confirmed where claims[] holds ${t.confirmed}`);\n  }\n  if (v.summary.unconfirmed !== t.unconfirmed) {\n    says.push(`says ${v.summary.unconfirmed} unconfirmed where claims[] holds ${t.unconfirmed}`);\n  }\n  if (v.summary.claims !== v.claims.length + unanswered) {\n    says.push(\n      `says ${v.summary.claims} claim(s)${unanswered === 0 ? \"\" : ` including ${unanswered} unanswered`} where claims[] holds ${v.claims.length}`,\n    );\n  }\n  return says.length === 0\n    ? null\n    : `its summary ${says.join(\", \")} — the record contradicts itself, so neither half can be believed`;\n}\n\n/** A YAML failure with its line, when the parser located one: that line is the fix. */\nfunction yamlReason(err: unknown): string {\n  const message = err instanceof Error ? err.message.split(\"\\n\")[0]!.trim() : String(err);\n  const pos = (err as { linePos?: Array<{ line: number; col: number }> } | null)?.linePos;\n  const line = Array.isArray(pos) ? pos[0]?.line : undefined;\n  return line === undefined ? `YAML error: ${message}` : `YAML error at line ${line}: ${message}`;\n}\n\n/**\n * The record beside a feature, or null when there is none loam can use. Kept\n * for readers that have nothing to say about the difference (`loam list`'s\n * verification column shows one glyph either way); anything that WRITES must\n * use {@link readVerificationState} instead, or it overwrites what it could not\n * read.\n *\n * A record whose summary contradicts its own claims is one of the nulls now, so\n * no reader can print its counts as fact. Reading it as ABSENT is the safe half\n * of the truth and not the whole of it: a reader that can say why should take\n * {@link readVerificationState} and its `code`.\n */\nexport async function readVerification(featureDir: string): Promise<Verification | null> {\n  const read = await readVerificationState(featureDir);\n  return read.state === \"ok\" ? read.verification : null;\n}\n\n/**\n * The shape check `readVerification` stands behind: everything its readers\n * dereference (verify's report/frozen views, list's verification column) must\n * be present and typed, or the cast would manufacture a Verification that\n * crashes them. Deliberately no tighter than the readers need: extra keys pass\n * (a human may annotate), `answered_by` stays optional (absent in records that\n * predate `--results`) and is any string, like `kind` — the readers only ever\n * compare them, and a record written by a newer loam must not read as absent.\n */\nfunction asVerification(doc: unknown): Verification | null {\n  if (!isRecord(doc)) return null;\n  const summary = doc[\"summary\"];\n  if (\n    typeof doc[\"feature\"] !== \"string\" ||\n    typeof doc[\"recorded\"] !== \"string\" ||\n    typeof doc[\"checklist\"] !== \"string\" ||\n    !isRecord(summary) ||\n    !isCount(summary[\"claims\"]) ||\n    !isCount(summary[\"confirmed\"]) ||\n    !isCount(summary[\"unconfirmed\"]) ||\n    (summary[\"unanswered\"] !== undefined && !isCount(summary[\"unanswered\"])) ||\n    !Array.isArray(doc[\"claims\"])\n  ) {\n    return null;\n  }\n  for (const c of doc[\"claims\"]) {\n    if (!isRecord(c)) return null;\n    if (typeof c[\"id\"] !== \"string\" || typeof c[\"kind\"] !== \"string\" || typeof c[\"claim\"] !== \"string\") return null;\n    if (c[\"subject\"] !== undefined && typeof c[\"subject\"] !== \"string\") return null;\n    if (typeof c[\"verdict\"] !== \"string\" || !(VERDICTS as readonly string[]).includes(c[\"verdict\"])) return null;\n    // The frozen view iterates evidence per claim — a scalar here would crash it.\n    if (!Array.isArray(c[\"evidence\"]) || c[\"evidence\"].some((e) => typeof e !== \"string\")) return null;\n    if (c[\"note\"] !== undefined && typeof c[\"note\"] !== \"string\") return null;\n    if (c[\"answered_by\"] !== undefined && typeof c[\"answered_by\"] !== \"string\") return null;\n    // Absent fine, present whole — the isConsumedContractReport precedent, and\n    // the guard body lives with the pin shape it vouches for (pins/pin.ts). A\n    // broken pins block makes the whole record unreadable and therefore never\n    // overwritten: skipping it instead would read a hand-damaged record as\n    // drift-free.\n    if (!isEvidencePinList(c[\"evidence_pins\"])) return null;\n  }\n  if (doc[\"schema\"] !== undefined && doc[\"schema\"] !== 2) return null;\n  if (!isConsumedReport(doc[\"report\"])) return null;\n  if (!isConsumedContractReport(doc[\"contractReport\"])) return null;\n  if (doc[\"attestations\"] !== undefined) {\n    if (!Array.isArray(doc[\"attestations\"])) return null;\n    for (const a of doc[\"attestations\"]) {\n      if (!isRecord(a)) return null;\n      if (typeof a[\"service\"] !== \"string\" || typeof a[\"commit\"] !== \"string\" || typeof a[\"recorded\"] !== \"string\") return null;\n      if (!/^[0-9a-f]{40,64}$/i.test(a[\"commit\"])) return null;\n      if (!Array.isArray(a[\"claims\"]) || a[\"claims\"].some((id) => typeof id !== \"string\")) return null;\n      if (!isConsumedReport(a[\"report\"])) return null;\n      if (!isConsumedContractReport(a[\"contractReport\"])) return null;\n    }\n  }\n  return doc as unknown as Verification;\n}\n\n/** Absent is fine — most records answer nothing from a report. Present must be whole: it is printed. */\nfunction isConsumedReport(v: unknown): boolean {\n  if (v === undefined) return true;\n  return (\n    isRecord(v) &&\n    typeof v[\"path\"] === \"string\" &&\n    typeof v[\"digest\"] === \"string\" &&\n    typeof v[\"mtime\"] === \"string\" &&\n    isCount(v[\"scenarios\"])\n  );\n}\n\n/**\n * The contract report's pin, exactly as loose as {@link isConsumedReport}:\n * absent fine, present whole — for the fields the readers dereference.\n * `format` is OPTIONAL here even though loam always writes it: nothing in the\n * readers dereferences it (it is provenance for a person, echoed only inside\n * whole-object payloads), and the generated AGENTS.md teaches the pin as\n * path/sha256/mtime/operation-count — so a hand-written block faithful to that\n * teaching must not make the WHOLE record unreadable over a field no reader\n * uses. When present it must be a string, and any string: a record written by\n * a newer loam that learned a second report format must not read as\n * unreadable here.\n */\nfunction isConsumedContractReport(v: unknown): boolean {\n  if (v === undefined) return true;\n  return (\n    isRecord(v) &&\n    typeof v[\"path\"] === \"string\" &&\n    typeof v[\"digest\"] === \"string\" &&\n    typeof v[\"mtime\"] === \"string\" &&\n    isCount(v[\"operations\"]) &&\n    (v[\"format\"] === undefined || typeof v[\"format\"] === \"string\")\n  );\n}\n\n/**\n * A summary count: an integer. YAML hands back strings for anything quoted.\n * Negativity is deliberately NOT checked here: a negative count is a summary\n * that disagrees with the claims below it, and `summaryDisagreement` owns that\n * refusal — failing the SHAPE check instead made the message list five keys\n * that were all present, while the miscount branch one call away holds the\n * advice the case actually needs.\n */\nfunction isCount(v: unknown): v is number {\n  return typeof v === \"number\" && Number.isInteger(v);\n}\n\n"]}