@ybotok/loam 0.2.0-alpha.6 → 0.2.0-alpha.9

package/dist/core/agent/agents-md/spine.js

@@ -1,40 +0,0 @@
-/**
- * Which element in the C4 model IS which service — the binding rule, and the
- * two-way completeness check `loam validate --all` runs over `services/`.
- *
- * This module used to carry the whole ID spine: every join between the
- * artifacts, the `Based-On:` baseline pins, how to draw a shared broker, and
- * how to declare a message produced outside the fleet. Those are now the
- * `loam-spine` reference page (../workflows/reference/spine.ts), printed by
- * `loam instructions loam-spine` — grammars a reader consults while writing one
- * document, in a file that was being truncated by two hosts before it reached
- * them (./command-map.ts's header has the measurement).
- *
- * THIS section stayed, and the line between it and the page it lost is worth
- * saying: an agent cannot read the landscape at all without knowing that a box's
- * title is its service id unless `metadata { service }` says otherwise. It is
- * orientation, not reference — it is needed to form the question, not to answer
- * it.
- *
- * One section of the AGENTS.md template. ../agents-md.ts assembles the
- * document by PLAIN CONCATENATION — no join separator — so every section
- * starts at the first character of its opening line and ends with the newline
- * that closes its last one. Keep that shape when editing, or two sections glue
- * onto one line in every docs repo loam scaffolds from now on.
- */
-export const SPINE = `## Which element IS which service
-
-An element says which service it is with \`metadata { service 'payment-service' }\`.
-Without one, its **title** is used instead — which is what most of this repo relies
-on, and also the trap: rename a box in a diagram and every check joining it to
-\`services/<svc>/\` silently stops matching. Bind an element whenever its title is
-not exactly the directory name, and prefer binding over renaming a directory.
-
-\`services/\` is the list of services — there is no manifest, and none should be
-added. \`loam validate --all\` compares that list to the landscape both ways: a
-directory nothing draws is an error, and an element with no directory is a warning.
-Systems that are not ours — kafka, a payment gateway — carry \`#external\`, which
-says so once and stops the warning for good.
-
-`;
-//# sourceMappingURL=spine.js.map

package/dist/core/agent/agents-md/spine.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"spine.js","sourceRoot":"","sources":["../../../../src/core/agent/agents-md/spine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG;;;;;;;;;;;;;;CAcpB,CAAC","sourcesContent":["/**\n * Which element in the C4 model IS which service — the binding rule, and the\n * two-way completeness check `loam validate --all` runs over `services/`.\n *\n * This module used to carry the whole ID spine: every join between the\n * artifacts, the `Based-On:` baseline pins, how to draw a shared broker, and\n * how to declare a message produced outside the fleet. Those are now the\n * `loam-spine` reference page (../workflows/reference/spine.ts), printed by\n * `loam instructions loam-spine` — grammars a reader consults while writing one\n * document, in a file that was being truncated by two hosts before it reached\n * them (./command-map.ts's header has the measurement).\n *\n * THIS section stayed, and the line between it and the page it lost is worth\n * saying: an agent cannot read the landscape at all without knowing that a box's\n * title is its service id unless `metadata { service }` says otherwise. It is\n * orientation, not reference — it is needed to form the question, not to answer\n * it.\n *\n * One section of the AGENTS.md template. ../agents-md.ts assembles the\n * document by PLAIN CONCATENATION — no join separator — so every section\n * starts at the first character of its opening line and ends with the newline\n * that closes its last one. Keep that shape when editing, or two sections glue\n * onto one line in every docs repo loam scaffolds from now on.\n */\nexport const SPINE = `## Which element IS which service\n\nAn element says which service it is with \\`metadata { service 'payment-service' }\\`.\nWithout one, its **title** is used instead — which is what most of this repo relies\non, and also the trap: rename a box in a diagram and every check joining it to\n\\`services/<svc>/\\` silently stops matching. Bind an element whenever its title is\nnot exactly the directory name, and prefer binding over renaming a directory.\n\n\\`services/\\` is the list of services — there is no manifest, and none should be\nadded. \\`loam validate --all\\` compares that list to the landscape both ways: a\ndirectory nothing draws is an error, and an element with no directory is a warning.\nSystems that are not ours — kafka, a payment gateway — carry \\`#external\\`, which\nsays so once and stops the warning for good.\n\n`;\n"]}

package/dist/core/coherence/events/merged.js

@@ -1,40 +0,0 @@
-/**
- * The contract as the feature would leave it: the REAL merge
- * (core/asyncapi/merge/merge.ts) run over the two texts and read back,
- * nothing written. One simulation feeds two gate questions — the
- * `declares()` join in ./events.ts (a retired or edited-away send must stop
- * answering "the service declares this" BEFORE archive, or a leftover
- * `Publishes:` line passes the gate and breaks the post-archive fleet) and
- * the consumer gate's wire half (a channel or operation removal that stops
- * the service SENDING a message the fleet still consumes).
- *
- * Calling the merge rather than re-deriving its verdicts is the point: a
- * second spelling of quote/edit/removal here would eventually disagree with
- * the merge about what archive actually writes, and the gate would be
- * promising a contract the archive does not produce.
- */
-import { parse } from "yaml";
-import { asyncapiDocOf } from "../../asyncapi/read.js";
-import { AsyncapiMergeError } from "../../asyncapi/merge/error.js";
-import { mergeAsyncapiSlots } from "../../asyncapi/merge/merge.js";
-/**
- * Simulate the archive-time merge, or stand down. Both documents are known
- * readable here (the walk in ./declared.ts checked), so the only refusals
- * left are the merge's own judgement calls — an aliased section, a section
- * spelling one slot key twice. `undefined` on those rather than a throw: the
- * caller falls back to the feature ∪ living union view, which can only be
- * too lenient, and the archive's own plan will surface the refusal by name.
- */
-export function mergedAsyncapiDoc(input) {
-    const { livingText, livingDoc, featureText, service } = input;
-    try {
-        const out = mergeAsyncapiSlots(livingText, featureText, service);
-        return out.text === null ? livingDoc : asyncapiDocOf(parse(out.text));
-    }
-    catch (error) {
-        if (error instanceof AsyncapiMergeError)
-            return undefined;
-        throw error;
-    }
-}
-//# sourceMappingURL=merged.js.map

package/dist/core/coherence/events/merged.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"merged.js","sourceRoot":"","sources":["../../../../src/core/coherence/events/merged.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAEvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAWnE;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAA2B;IAC3D,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC;IAC9D,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,kBAAkB,CAAC,UAAU,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;QACjE,OAAO,GAAG,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;IACxE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,kBAAkB;YAAE,OAAO,SAAS,CAAC;QAC1D,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC","sourcesContent":["/**\n * The contract as the feature would leave it: the REAL merge\n * (core/asyncapi/merge/merge.ts) run over the two texts and read back,\n * nothing written. One simulation feeds two gate questions — the\n * `declares()` join in ./events.ts (a retired or edited-away send must stop\n * answering \"the service declares this\" BEFORE archive, or a leftover\n * `Publishes:` line passes the gate and breaks the post-archive fleet) and\n * the consumer gate's wire half (a channel or operation removal that stops\n * the service SENDING a message the fleet still consumes).\n *\n * Calling the merge rather than re-deriving its verdicts is the point: a\n * second spelling of quote/edit/removal here would eventually disagree with\n * the merge about what archive actually writes, and the gate would be\n * promising a contract the archive does not produce.\n */\nimport { parse } from \"yaml\";\nimport { asyncapiDocOf } from \"../../asyncapi/read.js\";\nimport type { AsyncapiDoc } from \"../../asyncapi/model.js\";\nimport { AsyncapiMergeError } from \"../../asyncapi/merge/error.js\";\nimport { mergeAsyncapiSlots } from \"../../asyncapi/merge/merge.js\";\n\n/** The two texts the simulation merges, plus the living side's existing parse. */\nexport interface MergeSimulationInput {\n  livingText: string;\n  /** `readAsyncapi` of livingText — reused verbatim when the merge writes nothing. */\n  livingDoc: AsyncapiDoc;\n  featureText: string;\n  service: string;\n}\n\n/**\n * Simulate the archive-time merge, or stand down. Both documents are known\n * readable here (the walk in ./declared.ts checked), so the only refusals\n * left are the merge's own judgement calls — an aliased section, a section\n * spelling one slot key twice. `undefined` on those rather than a throw: the\n * caller falls back to the feature ∪ living union view, which can only be\n * too lenient, and the archive's own plan will surface the refusal by name.\n */\nexport function mergedAsyncapiDoc(input: MergeSimulationInput): AsyncapiDoc | undefined {\n  const { livingText, livingDoc, featureText, service } = input;\n  try {\n    const out = mergeAsyncapiSlots(livingText, featureText, service);\n    return out.text === null ? livingDoc : asyncapiDocOf(parse(out.text));\n  } catch (error) {\n    if (error instanceof AsyncapiMergeError) return undefined;\n    throw error;\n  }\n}\n"]}

package/dist/core/diff/current-state.js

@@ -1,96 +0,0 @@
-/**
- * The working-tree side of `loam diff`: the fleet as it stands on disk, read
- * through the invocation's `FleetContext` into the SAME `ServiceState` shape
- * `./base-state.ts` builds from git — one shape, so `./semantic.ts` joins the
- * two sides without caring which one came from the object store.
- *
- * Containment discipline, per subject and per axis: an artifact that EXISTS
- * but cannot be read (non-UTF-8 spec bytes, a directory sitting where a file
- * belongs, broken contract YAML) degrades that one axis to `unreadable` with
- * its path — never a thrown enumeration, never an empty list a diff would
- * read as "everything was removed". Absence stays absence: a file deleted
- * between the existence probe and the read is classified by its errno
- * (ENOENT), the same TOCTOU discipline `loadConfig` documents.
- */
-import { existsSync } from "node:fs";
-import { repoPath } from "../envelope/json.js";
-import { servicePathsAt } from "../repo/paths.js";
-import { inOrder } from "../kernel/concurrency.js";
-function readFailure(e, rel) {
-    const errno = e;
-    if (errno.code === "ENOENT")
-        return { kind: "absent" };
-    return { kind: "unreadable", path: rel, error: e instanceof Error ? e.message : String(e) };
-}
-/** One spec-axis file (`spec.md` / `arch.spec.md`) as parsed requirements. */
-async function requirementsAxis(context, abs, rel) {
-    if (!existsSync(abs))
-        return { kind: "absent" };
-    try {
-        return { kind: "read", value: await context.readRequirements(abs) };
-    }
-    catch (e) {
-        // decodeDocument's non-UTF-8 refusal lands here too: bytes that would
-        // parse as zero requirements must suspend the axis, not empty it.
-        return readFailure(e, rel);
-    }
-}
-async function openapiAxis(context, abs, rel) {
-    if (!existsSync(abs))
-        return { kind: "absent" };
-    try {
-        const doc = await context.readOpenapi(abs);
-        return doc.unreadable
-            ? { kind: "unreadable", path: rel, error: doc.error ?? "not a readable OpenAPI document" }
-            : { kind: "read", value: doc.ops.filter((op) => !op.remove) };
-    }
-    catch (e) {
-        return readFailure(e, rel);
-    }
-}
-async function asyncapiAxis(context, abs, rel) {
-    if (!existsSync(abs))
-        return { kind: "absent" };
-    try {
-        const doc = await context.readAsyncapi(abs);
-        return doc.unreadable
-            ? { kind: "unreadable", path: rel, error: doc.error ?? "not a readable AsyncAPI document" }
-            : { kind: "read", value: doc.messages.filter((m) => m.remove !== true) };
-    }
-    catch (e) {
-        return readFailure(e, rel);
-    }
-}
-/**
- * The current fleet, one `ServiceState` per enumerated service. The
- * enumeration itself (the tree walk) may throw `DocsRepoUnavailableError` —
- * that is the whole-repo refusal `docsRepoReady` fronts, not a per-subject
- * degradation, and it stays a throw for the command layer to map.
- */
-export async function readCurrentFleet(docsDir, context) {
-    const entries = await context.listServices(docsDir);
-    const states = await inOrder(entries, async (entry) => {
-        const paths = servicePathsAt(entry.dir);
-        return {
-            id: entry.id,
-            dir: repoPath(docsDir, entry.dir),
-            spec: await requirementsAxis(context, paths.spec, repoPath(docsDir, paths.spec)),
-            archSpec: await requirementsAxis(context, paths.archSpec, repoPath(docsDir, paths.archSpec)),
-            openapi: await openapiAxis(context, paths.openapi, repoPath(docsDir, paths.openapi)),
-            asyncapi: await asyncapiAxis(context, paths.asyncapi, repoPath(docsDir, paths.asyncapi)),
-        };
-    });
-    const ambiguous = currentCollisions(states);
-    return {
-        services: new Map(states.filter((s) => !ambiguous.has(s.id)).map((s) => [s.id, s])),
-        ambiguous,
-    };
-}
-/** Ids claimed by more than one enumerated directory, with every claimant named. */
-function currentCollisions(states) {
-    const byId = new Map();
-    for (const s of states)
-        byId.set(s.id, [...(byId.get(s.id) ?? []), s.dir]);
-    return new Map([...byId].filter(([, dirs]) => dirs.length > 1));
-}
-//# sourceMappingURL=current-state.js.map

package/dist/core/diff/current-state.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"current-state.js","sourceRoot":"","sources":["../../../src/core/diff/current-state.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The working-tree side of `loam diff`: the fleet as it stands on disk, read\n * through the invocation's `FleetContext` into the SAME `ServiceState` shape\n * `./base-state.ts` builds from git — one shape, so `./semantic.ts` joins the\n * two sides without caring which one came from the object store.\n *\n * Containment discipline, per subject and per axis: an artifact that EXISTS\n * but cannot be read (non-UTF-8 spec bytes, a directory sitting where a file\n * belongs, broken contract YAML) degrades that one axis to `unreadable` with\n * its path — never a thrown enumeration, never an empty list a diff would\n * read as \"everything was removed\". Absence stays absence: a file deleted\n * between the existence probe and the read is classified by its errno\n * (ENOENT), the same TOCTOU discipline `loadConfig` documents.\n */\nimport { existsSync } from \"node:fs\";\nimport type { Requirement } from \"../document/spec.js\";\nimport type { Operation } from \"../openapi/doc.js\";\nimport type { EventMessage } from \"../asyncapi/model.js\";\nimport { repoPath } from \"../envelope/json.js\";\nimport { servicePathsAt } from \"../repo/paths.js\";\nimport { inOrder } from \"../kernel/concurrency.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport type { AxisState, ServiceState } from \"./base-state.js\";\n\nexport interface CurrentFleet {\n  /** By service id, in the enumeration's (sorted-walk) order. Ids the `ambiguous` map claims are excluded. */\n  services: Map<string, ServiceState>;\n  /**\n   * Ids more than one working-tree directory claims — `subsystem.name-collision`'s\n   * live shape, which validate diagnoses. Diffing either claimant would pick a\n   * winner nobody chose (a `new Map` collapse here used to keep the LAST one and\n   * fabricate a whole change story about a service that never moved), so the\n   * subject is suspended exactly as the base side's `ambiguous` map suspends it.\n   */\n  ambiguous: Map<string, string[]>;\n}\n\nfunction readFailure(e: unknown, rel: string): { kind: \"absent\" } | { kind: \"unreadable\"; path: string; error: string } {\n  const errno = e as NodeJS.ErrnoException;\n  if (errno.code === \"ENOENT\") return { kind: \"absent\" };\n  return { kind: \"unreadable\", path: rel, error: e instanceof Error ? e.message : String(e) };\n}\n\n/** One spec-axis file (`spec.md` / `arch.spec.md`) as parsed requirements. */\nasync function requirementsAxis(context: FleetContext, abs: string, rel: string): Promise<AxisState<Requirement[]>> {\n  if (!existsSync(abs)) return { kind: \"absent\" };\n  try {\n    return { kind: \"read\", value: await context.readRequirements(abs) };\n  } catch (e) {\n    // decodeDocument's non-UTF-8 refusal lands here too: bytes that would\n    // parse as zero requirements must suspend the axis, not empty it.\n    return readFailure(e, rel);\n  }\n}\n\nasync function openapiAxis(context: FleetContext, abs: string, rel: string): Promise<AxisState<Operation[]>> {\n  if (!existsSync(abs)) return { kind: \"absent\" };\n  try {\n    const doc = await context.readOpenapi(abs);\n    return doc.unreadable\n      ? { kind: \"unreadable\", path: rel, error: doc.error ?? \"not a readable OpenAPI document\" }\n      : { kind: \"read\", value: doc.ops.filter((op) => !op.remove) };\n  } catch (e) {\n    return readFailure(e, rel);\n  }\n}\n\nasync function asyncapiAxis(context: FleetContext, abs: string, rel: string): Promise<AxisState<EventMessage[]>> {\n  if (!existsSync(abs)) return { kind: \"absent\" };\n  try {\n    const doc = await context.readAsyncapi(abs);\n    return doc.unreadable\n      ? { kind: \"unreadable\", path: rel, error: doc.error ?? \"not a readable AsyncAPI document\" }\n      : { kind: \"read\", value: doc.messages.filter((m) => m.remove !== true) };\n  } catch (e) {\n    return readFailure(e, rel);\n  }\n}\n\n/**\n * The current fleet, one `ServiceState` per enumerated service. The\n * enumeration itself (the tree walk) may throw `DocsRepoUnavailableError` —\n * that is the whole-repo refusal `docsRepoReady` fronts, not a per-subject\n * degradation, and it stays a throw for the command layer to map.\n */\nexport async function readCurrentFleet(docsDir: DocsDir, context: FleetContext): Promise<CurrentFleet> {\n  const entries = await context.listServices(docsDir);\n  const states = await inOrder(entries, async (entry): Promise<ServiceState> => {\n    const paths = servicePathsAt(entry.dir);\n    return {\n      id: entry.id,\n      dir: repoPath(docsDir, entry.dir),\n      spec: await requirementsAxis(context, paths.spec, repoPath(docsDir, paths.spec)),\n      archSpec: await requirementsAxis(context, paths.archSpec, repoPath(docsDir, paths.archSpec)),\n      openapi: await openapiAxis(context, paths.openapi, repoPath(docsDir, paths.openapi)),\n      asyncapi: await asyncapiAxis(context, paths.asyncapi, repoPath(docsDir, paths.asyncapi)),\n    };\n  });\n  const ambiguous = currentCollisions(states);\n  return {\n    services: new Map(states.filter((s) => !ambiguous.has(s.id)).map((s) => [s.id, s])),\n    ambiguous,\n  };\n}\n\n/** Ids claimed by more than one enumerated directory, with every claimant named. */\nfunction currentCollisions(states: readonly ServiceState[]): Map<string, string[]> {\n  const byId = new Map<string, string[]>();\n  for (const s of states) byId.set(s.id, [...(byId.get(s.id) ?? []), s.dir]);\n  return new Map([...byId].filter(([, dirs]) => dirs.length > 1));\n}\n"]}

package/dist/core/diff/victims.js

@@ -1,256 +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) {
-                // An edge whose SOURCE resolves to the provider as well is the
-                // provider's own internal call — the rule `usecase.step-unlinked`
-                // already states, that a service owes no operationId to itself — so it
-                // is not a consumer of the operation it is losing. Without this the
-                // downgrade the message half at :198 has always made was unreachable
-                // for any service that draws its own containers: one internal edge
-                // carrying the op kept every removal `diff.op-removed-consumed`
-                // (verification 2026-09-04, R3).
-                if (r.op === op && resolve(r.target) === provider && resolve(r.source) !== 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        // An edge whose SOURCE resolves to the provider as well is the\n        // provider's own internal call — the rule `usecase.step-unlinked`\n        // already states, that a service owes no operationId to itself — so it\n        // is not a consumer of the operation it is losing. Without this the\n        // downgrade the message half at :198 has always made was unreachable\n        // for any service that draws its own containers: one internal edge\n        // carrying the op kept every removal `diff.op-removed-consumed`\n        // (verification 2026-09-04, R3).\n        if (r.op === op && resolve(r.target) === provider && resolve(r.source) !== provider) {\n          edges.push(EDGE(resolve, r));\n        }\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/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"]}