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

package/dist/core/coherence/retired/archived.js

@@ -0,0 +1,285 @@
+/**
+ * The retired index: what every ARCHIVED feature took out of the fleet's living
+ * contracts, and who took it.
+ *
+ * The question it answers is one the living contract cannot: is an operation
+ * the living contract does not have NEW, or was it RETIRED? Both read as
+ * absent. Before this index existed the feature gate could only treat absent
+ * as new — so a delta quoting an operation that a parallel feature retired and
+ * archived first was graded as an addition (`api.op-unconsumed`, advisory) and
+ * archived at exit 0, putting the retired operation straight back into the
+ * living contract. The baseline gate's unpinned count (openapi/baseline/gate.ts)
+ * could not see it either: it counts only quotes of operations the living
+ * contract still has, so that a genuinely new operation never trips it.
+ *
+ * The record of a retirement is files, not history. An archived feature keeps
+ * its delta under `features/archive/<FEAT>/specs/<svc>/`, and the removal
+ * markers in it say what that merge was ASKED to delete — read through the
+ * same rule the gate grades an in-flight delta by (./retirement.ts), so
+ * relocations are not retirements here either. No git: the docs semantics stay
+ * a property of the tree.
+ *
+ * Asked is not done. The OpenAPI merge deletes only when the living operation
+ * AT the marker's method and path carries the marker's operationId
+ * (openapi/merge/merge.ts); the event merge deletes a channel or operation slot
+ * only when the living contract has that key, and a `components.messages` slot
+ * only when the message declared there carries the marker's name
+ * (asyncapi/merge/merge.ts). A marker that missed — `remove-target-missing` or
+ * `remove-target-mismatch`, archived past under `--approve` — deleted nothing,
+ * and counting it called a genuinely new operation a revival and refused it.
+ * So every marker is checked against the contract the merge ran against: the
+ * feature's snapshot pre-image (`.loam-before/`, staging/snapshot/manifest.ts).
+ * A contract the archive CREATED, or never wrote at all, lost nothing to that
+ * merge, and reads as an empty pre-image. "Never wrote" is the event merge's
+ * case alone: it returns no text when it changes nothing (an asyncapi delta
+ * whose every marker missed), and archive snapshots only what it writes. The
+ * OpenAPI merge returns text whenever the delta has a path entry, so a
+ * contract it left unchanged has an ordinary pre-image equal to what it
+ * wrote — read like any other, and every missed marker misses it again. A
+ * feature with no intact snapshot (archived before the snapshot existed, or
+ * the snapshot edited or removed since) cannot be checked, and its markers
+ * count as written — what the index did before it read pre-images at all.
+ *
+ * The pre-image answers one more thing the delta does not spell: a
+ * CHANNEL-slot removal retires the messages its living channel declared
+ * inline, and those names exist only in the contract the merge ran against. A
+ * feature archived without a pre-image contributes its channel slot and not
+ * the inline names.
+ *
+ * What the index records is every ADDRESS an archived feature vacated, per
+ * operationId or message name: where each executed marker stood, whether the
+ * relocation rule calls it a retirement or a move. A relocation retires
+ * nothing, but it does vacate an address: the id lives on at its new slot,
+ * and a later delta quoting the old one would put it back there too — one
+ * operationId at two addresses, which the merge cannot tell from an addition
+ * any more than it can a retired operation, and which the slot-keyed
+ * baseline gate and an id-keyed check both miss (the id is living, the slot
+ * is empty). A retirement vacates its address the same way once a later
+ * feature re-adds the id somewhere else: indexed by id alone, as this once
+ * was, a quote of the retired address read as harmless because the id was
+ * living, and archived the id at both. So a vacation carries its address,
+ * and for a move where the delta put the entry — kept, because where it
+ * lives NOW may be somewhere a later feature put it (`Vacated`). The event
+ * axis vacates message addresses the same two ways: a `components.messages`
+ * marker, and a channel removal taking its inline declarations. A channel or
+ * operation slot's identity IS its key, so a "moved" channel is a retired key
+ * plus a new one, and the slot index catches a quote of the old key.
+ *
+ * What it cannot see, and SCHEMA.md says so: a removal made by hand-editing a
+ * living contract leaves no marker anywhere, and an archived feature deleted
+ * from disk takes its markers with it. Both read as "never retired" — the gate
+ * falls back to calling the entry new, which is what it did before.
+ *
+ * OpenAPI markers count only when they name an operationId. A marker with
+ * none (`openapi.remove-marker-anonymous`) or one written at PATH level
+ * (`openapi.remove-marker-path-level`) retires nothing at archive — the merge
+ * matches a marker to the living operation by the operationId it names, at
+ * its own method and path, and these name none — so an archived feature that
+ * carried one under `--approve` left the operation living, and indexing its
+ * slot would attribute a retirement that never happened.
+ */
+import { existsSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { parse } from "yaml";
+import { inOrder, memo } from "../../kernel/concurrency.js";
+import { archiveDir, ARTIFACT_FILES, featureSpecPaths } from "../../repo/paths.js";
+import { listFeatures } from "../../repo/repo.js";
+import { openapiFromText, readOpenapi } from "../../openapi/doc.js";
+import { readOr } from "../../openapi/contract-text.js";
+import { asyncapiSlots, slotKey, slotsByKey } from "../../asyncapi/digest.js";
+import { asyncapiFromText, readAsyncapi } from "../../asyncapi/read.js";
+import { readSnapshotPreImage } from "../../staging/snapshot/manifest.js";
+import { messageRetirements, operationRetirements } from "./retirement.js";
+/** `METHOD /path` — how the index records, and every finding names, an operation's address. */
+export function operationAddress(op) {
+    return `${op.method.toUpperCase()} ${op.path}`;
+}
+/** The index's one key spelling. NUL-joined: no id, section, key or message name can contain it. */
+export function retiredKey(...parts) {
+    return parts.join("\0");
+}
+/**
+ * One index per invocation, keyed by the invocation's own FleetContext.
+ *
+ * A module-level cache is normally the wrong shape (AGENTS.md: a value cached
+ * at import time leaks across tests and, in a long-running host, across
+ * invocations). This one is the `c4/resolve/service.ts` exception for the same
+ * reason: the key is the per-invocation context object, so two runs can never
+ * see each other's answer and the entry dies with the context. It is here
+ * rather than a memo on FleetContext because that class sits at L6 and this
+ * package at L8 — the import that memo would need points the wrong way up the
+ * DAG (docs/DESIGN.md's level table) — while the reads underneath (the feature
+ * list, every contract parse) already go through the context's own memos.
+ */
+const PER_INVOCATION = new WeakMap();
+/**
+ * A lazy handle on the index: nothing is read until a grader has a candidate
+ * to ask about — an entry the merged contract answers at an address its
+ * living contract does not, which is exactly the shape the living contract
+ * alone cannot call new or revived. A feature that only edits what the living
+ * contract already holds never walks `features/archive/`; one that adds
+ * anything genuinely new does, since an addition and a revival read the same
+ * until the walk answers. Without a context (archive's gate) the handle
+ * memoises for its own lifetime, which is one `featureCoherence` call, so the
+ * two contract axes still share one walk.
+ */
+export function retiredLookup(docsDir, context) {
+    let own;
+    return () => {
+        if (context === undefined)
+            return (own ??= readRetiredIndex(docsDir));
+        let store = PER_INVOCATION.get(context);
+        if (store === undefined)
+            PER_INVOCATION.set(context, (store = new Map()));
+        return memo(store, resolve(docsDir), () => readRetiredIndex(docsDir, context));
+    };
+}
+/** The index's parts, in the one order `readRetiredIndex` records them. */
+const PARTS = ["operations", "slots", "messages"];
+/** Walk every archived feature's contract deltas and record every address each one vacated. */
+async function readRetiredIndex(docsDir, context) {
+    const index = {
+        operations: new Map(),
+        slots: new Map(),
+        messages: new Map(),
+    };
+    // A `features/archive` that is not a directory holds no archived feature,
+    // and listing it would throw ENOTDIR out of the feature gate — refusing an
+    // archive over a question about OTHER features' history, before the plan
+    // that names the real problem (the final move into that path) is reached.
+    if (!isDirectory(archiveDir(docsDir)))
+        return index;
+    const archived = (await listFeatures(docsDir, { includeArchived: true }, context)).filter((f) => f.archived);
+    const units = archived.flatMap((feature) => feature.services.map((service) => ({ feature, service })));
+    // Every (feature, service) pair is independent of every other, so they are
+    // read concurrently; the only order that matters is the order retirers are
+    // RECORDED in, and `inOrder` hands the answers back in input order — the
+    // features sorted by `compareIds`, as `listFeatures` returns them.
+    for (const found of await inOrder(units, ({ feature, service }) => serviceRetirements(feature, service, context))) {
+        for (const part of PARTS) {
+            for (const { key, at, to } of found[part])
+                record(index[part], key, { by: found.featureId, at, to });
+        }
+    }
+    return index;
+}
+/** One archived feature's vacations on one service — only the markers its merge carried out. */
+async function serviceRetirements(feature, service, context) {
+    const found = { featureId: feature.id, operations: [], slots: [], messages: [] };
+    const paths = featureSpecPaths(feature.dir, service);
+    // An absent delta reads as an empty document; an unreadable one retired
+    // nothing loam could have merged (archive refuses `merge-failed`).
+    const api = await readOpenapi(paths.openapi, context);
+    if (!api.unreadable && api.ops.some((op) => op.remove)) {
+        const before = await preImage(feature.dir, service, ARTIFACT_FILES.openapi);
+        const held = before === undefined ? undefined : openapiFromText(before);
+        // The merge's own match: the operation the pre-image held AT the marker's
+        // slot carries the marker's id. Markers that missed are dropped before the
+        // rule runs, so a relocation whose old-slot marker missed is no
+        // relocation either — it moved nothing out.
+        const carried = api.ops.filter((op) => !op.remove ||
+            held === undefined ||
+            held.unreadable ||
+            held.ops.some((h) => !h.remove && h.id === op.id && h.method === op.method && h.path === op.path));
+        // Every carried marker stands on an address it vacated. The relocation
+        // rule says which kind: an id in `net` is retired, and one the rule took
+        // out of `net` moved — the delta's definitions of it are where it went.
+        const { net } = operationRetirements(carried);
+        for (const op of carried) {
+            if (!op.remove)
+                continue;
+            const to = net.has(op.id) ? [] : carried.filter((d) => !d.remove && d.id === op.id).map(operationAddress);
+            found.operations.push({ key: retiredKey(service, op.id), at: operationAddress(op), to });
+        }
+    }
+    if (!existsSync(paths.asyncapi))
+        return found;
+    const events = await readAsyncapi(paths.asyncapi, context);
+    const text = events.unreadable ? undefined : await readOr(paths.asyncapi, context);
+    if (text === undefined)
+        return found;
+    const eventSlots = asyncapiSlots(parse(text));
+    if (!eventSlots.some((s) => s.remove))
+        return found;
+    const before = await preImageEvents(feature.dir, service);
+    // Presence is the whole match for a channel or operation slot — its
+    // identity IS the key. A message marker must also name the message the
+    // pre-image declared at that key, the merge's exactness on the message axis.
+    const carriedSlots = eventSlots.filter((s) => !s.remove || before === undefined || before.slots.has(slotKey(s)));
+    const carriedEvents = {
+        ...events,
+        messages: events.messages.filter((m) => m.remove !== true ||
+            before === undefined ||
+            before.doc.messages.some((b) => b.remove !== true && b.slot === m.slot && b.name === m.name)),
+    };
+    for (const slot of carriedSlots) {
+        if (!slot.remove || slot.section === "components.messages")
+            continue;
+        found.slots.push({ key: retiredKey(service, slot.section, slot.key), at: `${slot.section}.${slot.key}`, to: [] });
+    }
+    // The operation axis's rule on the message name: a vacated declaration
+    // whose name the delta declares again was relocated — to another key, or
+    // inline under a channel — and those declarations are where it went.
+    const retired = messageRetirements(carriedEvents, carriedSlots, before?.doc ?? NOTHING_DECLARED);
+    for (const m of retired.vacated) {
+        const to = retired.net.has(m.name)
+            ? []
+            : carriedEvents.messages.filter((d) => d.remove !== true && d.name === m.name).map((d) => d.slot);
+        found.messages.push({ key: retiredKey(service, m.name), at: m.slot, to });
+    }
+    return found;
+}
+const NOTHING_DECLARED = asyncapiFromText("");
+/**
+ * The contract one artifact held as this feature's merge found it, or
+ * undefined when the snapshot holds nothing to trust. An artifact the merge
+ * created, or never wrote, lost nothing to it — which is exactly what an empty
+ * pre-image says: every marker in the delta missed, and no channel took inline
+ * names with it.
+ */
+async function preImage(featureDir, service, artifact) {
+    const found = await readSnapshotPreImage(featureDir, { service, artifact });
+    if (found === null)
+        return undefined;
+    return found.kind === "held" ? found.text : "";
+}
+/** The event pre-image as the reader and the slot walk see it — undefined when absent or unreadable. */
+async function preImageEvents(featureDir, service) {
+    const text = await preImage(featureDir, service, ARTIFACT_FILES.asyncapi);
+    if (text === undefined)
+        return undefined;
+    const doc = asyncapiFromText(text);
+    return doc.unreadable ? undefined : { doc, slots: slotsByKey(asyncapiSlots(parse(text))) };
+}
+function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Add one vacation. Already in id order without a sort: the walk records the
+ * features in `listFeatures`' `compareIds` order. Distinct per feature,
+ * address and kind, because two archived directories can carry one feature
+ * id (the id is read off the directory name), and "archived FEAT-7 and
+ * FEAT-7" names one feature twice — a second directory's move away from the
+ * same address widens that feature's destinations instead.
+ */
+function record(into, key, vacated) {
+    const all = into.get(key);
+    if (all === undefined) {
+        into.set(key, [vacated]);
+        return;
+    }
+    const same = (v) => v.by === vacated.by && v.at === vacated.at && (v.to.length === 0) === (vacated.to.length === 0);
+    if (!all.some(same)) {
+        into.set(key, [...all, vacated]);
+        return;
+    }
+    const widen = (v) => (same(v) ? { ...v, to: [...new Set([...v.to, ...vacated.to])] } : v);
+    const [first, ...rest] = all;
+    into.set(key, [widen(first), ...rest.map(widen)]);
+}
+//# sourceMappingURL=archived.js.map

package/dist/core/coherence/retired/archived.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"archived.js","sourceRoot":"","sources":["../../../../src/core/coherence/retired/archived.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The retired index: what every ARCHIVED feature took out of the fleet's living\n * contracts, and who took it.\n *\n * The question it answers is one the living contract cannot: is an operation\n * the living contract does not have NEW, or was it RETIRED? Both read as\n * absent. Before this index existed the feature gate could only treat absent\n * as new — so a delta quoting an operation that a parallel feature retired and\n * archived first was graded as an addition (`api.op-unconsumed`, advisory) and\n * archived at exit 0, putting the retired operation straight back into the\n * living contract. The baseline gate's unpinned count (openapi/baseline/gate.ts)\n * could not see it either: it counts only quotes of operations the living\n * contract still has, so that a genuinely new operation never trips it.\n *\n * The record of a retirement is files, not history. An archived feature keeps\n * its delta under `features/archive/<FEAT>/specs/<svc>/`, and the removal\n * markers in it say what that merge was ASKED to delete — read through the\n * same rule the gate grades an in-flight delta by (./retirement.ts), so\n * relocations are not retirements here either. No git: the docs semantics stay\n * a property of the tree.\n *\n * Asked is not done. The OpenAPI merge deletes only when the living operation\n * AT the marker's method and path carries the marker's operationId\n * (openapi/merge/merge.ts); the event merge deletes a channel or operation slot\n * only when the living contract has that key, and a `components.messages` slot\n * only when the message declared there carries the marker's name\n * (asyncapi/merge/merge.ts). A marker that missed — `remove-target-missing` or\n * `remove-target-mismatch`, archived past under `--approve` — deleted nothing,\n * and counting it called a genuinely new operation a revival and refused it.\n * So every marker is checked against the contract the merge ran against: the\n * feature's snapshot pre-image (`.loam-before/`, staging/snapshot/manifest.ts).\n * A contract the archive CREATED, or never wrote at all, lost nothing to that\n * merge, and reads as an empty pre-image. \"Never wrote\" is the event merge's\n * case alone: it returns no text when it changes nothing (an asyncapi delta\n * whose every marker missed), and archive snapshots only what it writes. The\n * OpenAPI merge returns text whenever the delta has a path entry, so a\n * contract it left unchanged has an ordinary pre-image equal to what it\n * wrote — read like any other, and every missed marker misses it again. A\n * feature with no intact snapshot (archived before the snapshot existed, or\n * the snapshot edited or removed since) cannot be checked, and its markers\n * count as written — what the index did before it read pre-images at all.\n *\n * The pre-image answers one more thing the delta does not spell: a\n * CHANNEL-slot removal retires the messages its living channel declared\n * inline, and those names exist only in the contract the merge ran against. A\n * feature archived without a pre-image contributes its channel slot and not\n * the inline names.\n *\n * What the index records is every ADDRESS an archived feature vacated, per\n * operationId or message name: where each executed marker stood, whether the\n * relocation rule calls it a retirement or a move. A relocation retires\n * nothing, but it does vacate an address: the id lives on at its new slot,\n * and a later delta quoting the old one would put it back there too — one\n * operationId at two addresses, which the merge cannot tell from an addition\n * any more than it can a retired operation, and which the slot-keyed\n * baseline gate and an id-keyed check both miss (the id is living, the slot\n * is empty). A retirement vacates its address the same way once a later\n * feature re-adds the id somewhere else: indexed by id alone, as this once\n * was, a quote of the retired address read as harmless because the id was\n * living, and archived the id at both. So a vacation carries its address,\n * and for a move where the delta put the entry — kept, because where it\n * lives NOW may be somewhere a later feature put it (`Vacated`). The event\n * axis vacates message addresses the same two ways: a `components.messages`\n * marker, and a channel removal taking its inline declarations. A channel or\n * operation slot's identity IS its key, so a \"moved\" channel is a retired key\n * plus a new one, and the slot index catches a quote of the old key.\n *\n * What it cannot see, and SCHEMA.md says so: a removal made by hand-editing a\n * living contract leaves no marker anywhere, and an archived feature deleted\n * from disk takes its markers with it. Both read as \"never retired\" — the gate\n * falls back to calling the entry new, which is what it did before.\n *\n * OpenAPI markers count only when they name an operationId. A marker with\n * none (`openapi.remove-marker-anonymous`) or one written at PATH level\n * (`openapi.remove-marker-path-level`) retires nothing at archive — the merge\n * matches a marker to the living operation by the operationId it names, at\n * its own method and path, and these name none — so an archived feature that\n * carried one under `--approve` left the operation living, and indexing its\n * slot would attribute a retirement that never happened.\n */\nimport { existsSync, statSync } from \"node:fs\";\nimport { resolve } from \"node:path\";\nimport { parse } from \"yaml\";\nimport { inOrder, memo } from \"../../kernel/concurrency.js\";\nimport type { DocsDir } from \"../../kernel/ids/dirs.js\";\nimport type { RawServiceId } from \"../../kernel/ids/service.js\";\nimport type { FeatureEntry } from \"../../repo/entries.js\";\nimport { archiveDir, ARTIFACT_FILES, featureSpecPaths } from \"../../repo/paths.js\";\nimport { listFeatures } from \"../../repo/repo.js\";\nimport { openapiFromText, readOpenapi } from \"../../openapi/doc.js\";\nimport { readOr } from \"../../openapi/contract-text.js\";\nimport { asyncapiSlots, slotKey, slotsByKey, type AsyncapiSlot } from \"../../asyncapi/digest.js\";\nimport { asyncapiFromText, readAsyncapi } from \"../../asyncapi/read.js\";\nimport type { AsyncapiDoc } from \"../../asyncapi/model.js\";\nimport { readSnapshotPreImage } from \"../../staging/snapshot/manifest.js\";\nimport type { FleetContext } from \"../../fleet-context.js\";\nimport { messageRetirements, operationRetirements } from \"./retirement.js\";\n\n/**\n * One archived feature taking one entry out of one address: a retirement\n * (`to` empty) or a move (`to`, every address its delta put the entry at).\n * A move's destination is recorded apart from where the entry lives NOW,\n * because the two part ways as soon as anything lands after the move — A\n * moves an operation from /x to /y, B retires it at /y, D re-adds it at /z —\n * and a finding that named the living address as the mover's destination\n * said \"A moved it to /z\", an address A never wrote.\n */\nexport interface Vacated {\n  by: string;\n  /** `METHOD /path` for an operation, the slot for a message, `<section>.<key>` for a channel or operation slot. */\n  at: string;\n  to: readonly string[];\n}\n\n/**\n * Every vacation of one entry, in feature id order and distinct per feature,\n * address and kind — never empty, because an entry is recorded only together\n * with its first vacation. The tuple says so to the compiler, so the one\n * sentence that names the features (./revival/revived.ts) cannot be handed nobody.\n */\nexport type Vacations = readonly [Vacated, ...Vacated[]];\n\n/** `METHOD /path` — how the index records, and every finding names, an operation's address. */\nexport function operationAddress(op: { method: string; path: string }): string {\n  return `${op.method.toUpperCase()} ${op.path}`;\n}\n\n/** Everything the archived features retired or moved away, each entry naming the features that did it and where. */\nexport interface RetiredIndex {\n  /** `retiredKey(service, operationId)` → every address an archived openapi delta took it out of. */\n  operations: ReadonlyMap<string, Vacations>;\n  /** `retiredKey(service, section, key)` for a `channels` or `operations` slot — always a retirement. */\n  slots: ReadonlyMap<string, Vacations>;\n  /** `retiredKey(service, messageName)` — by the join token, every slot it was taken out of. */\n  messages: ReadonlyMap<string, Vacations>;\n}\n\n/** The index's one key spelling. NUL-joined: no id, section, key or message name can contain it. */\nexport function retiredKey(...parts: string[]): string {\n  return parts.join(\"\\0\");\n}\n\n/** The index, built at most once per caller — what the gate hands both contract axes. */\nexport type RetiredLookup = () => Promise<RetiredIndex>;\n\n/**\n * One index per invocation, keyed by the invocation's own FleetContext.\n *\n * A module-level cache is normally the wrong shape (AGENTS.md: a value cached\n * at import time leaks across tests and, in a long-running host, across\n * invocations). This one is the `c4/resolve/service.ts` exception for the same\n * reason: the key is the per-invocation context object, so two runs can never\n * see each other's answer and the entry dies with the context. It is here\n * rather than a memo on FleetContext because that class sits at L6 and this\n * package at L8 — the import that memo would need points the wrong way up the\n * DAG (docs/DESIGN.md's level table) — while the reads underneath (the feature\n * list, every contract parse) already go through the context's own memos.\n */\nconst PER_INVOCATION = new WeakMap<FleetContext, Map<string, Promise<RetiredIndex>>>();\n\n/**\n * A lazy handle on the index: nothing is read until a grader has a candidate\n * to ask about — an entry the merged contract answers at an address its\n * living contract does not, which is exactly the shape the living contract\n * alone cannot call new or revived. A feature that only edits what the living\n * contract already holds never walks `features/archive/`; one that adds\n * anything genuinely new does, since an addition and a revival read the same\n * until the walk answers. Without a context (archive's gate) the handle\n * memoises for its own lifetime, which is one `featureCoherence` call, so the\n * two contract axes still share one walk.\n */\nexport function retiredLookup(docsDir: DocsDir, context?: FleetContext): RetiredLookup {\n  let own: Promise<RetiredIndex> | undefined;\n  return () => {\n    if (context === undefined) return (own ??= readRetiredIndex(docsDir));\n    let store = PER_INVOCATION.get(context);\n    if (store === undefined) PER_INVOCATION.set(context, (store = new Map()));\n    return memo(store, resolve(docsDir), () => readRetiredIndex(docsDir, context));\n  };\n}\n\n/** One vacation, as one archived feature's walk finds it: the index key of the entry, the address, and any destinations. */\ninterface Found {\n  key: string;\n  at: string;\n  to: string[];\n}\n\n/** What one archived feature's deltas for one service took out, per index part. */\ninterface ServiceRetirements {\n  featureId: string;\n  operations: Found[];\n  slots: Found[];\n  messages: Found[];\n}\n\n/** The index's parts, in the one order `readRetiredIndex` records them. */\nconst PARTS = [\"operations\", \"slots\", \"messages\"] as const;\n\n/** Walk every archived feature's contract deltas and record every address each one vacated. */\nasync function readRetiredIndex(docsDir: DocsDir, context?: FleetContext): Promise<RetiredIndex> {\n  const index = {\n    operations: new Map<string, Vacations>(),\n    slots: new Map<string, Vacations>(),\n    messages: new Map<string, Vacations>(),\n  };\n  // A `features/archive` that is not a directory holds no archived feature,\n  // and listing it would throw ENOTDIR out of the feature gate — refusing an\n  // archive over a question about OTHER features' history, before the plan\n  // that names the real problem (the final move into that path) is reached.\n  if (!isDirectory(archiveDir(docsDir))) return index;\n  const archived = (await listFeatures(docsDir, { includeArchived: true }, context)).filter((f) => f.archived);\n  const units = archived.flatMap((feature) => feature.services.map((service) => ({ feature, service })));\n  // Every (feature, service) pair is independent of every other, so they are\n  // read concurrently; the only order that matters is the order retirers are\n  // RECORDED in, and `inOrder` hands the answers back in input order — the\n  // features sorted by `compareIds`, as `listFeatures` returns them.\n  for (const found of await inOrder(units, ({ feature, service }) => serviceRetirements(feature, service, context))) {\n    for (const part of PARTS) {\n      for (const { key, at, to } of found[part]) record(index[part], key, { by: found.featureId, at, to });\n    }\n  }\n  return index;\n}\n\n/** One archived feature's vacations on one service — only the markers its merge carried out. */\nasync function serviceRetirements(\n  feature: FeatureEntry,\n  service: RawServiceId,\n  context: FleetContext | undefined,\n): Promise<ServiceRetirements> {\n  const found: ServiceRetirements = { featureId: feature.id, operations: [], slots: [], messages: [] };\n  const paths = featureSpecPaths(feature.dir, service);\n  // An absent delta reads as an empty document; an unreadable one retired\n  // nothing loam could have merged (archive refuses `merge-failed`).\n  const api = await readOpenapi(paths.openapi, context);\n  if (!api.unreadable && api.ops.some((op) => op.remove)) {\n    const before = await preImage(feature.dir, service, ARTIFACT_FILES.openapi);\n    const held = before === undefined ? undefined : openapiFromText(before);\n    // The merge's own match: the operation the pre-image held AT the marker's\n    // slot carries the marker's id. Markers that missed are dropped before the\n    // rule runs, so a relocation whose old-slot marker missed is no\n    // relocation either — it moved nothing out.\n    const carried = api.ops.filter(\n      (op) =>\n        !op.remove ||\n        held === undefined ||\n        held.unreadable ||\n        held.ops.some((h) => !h.remove && h.id === op.id && h.method === op.method && h.path === op.path),\n    );\n    // Every carried marker stands on an address it vacated. The relocation\n    // rule says which kind: an id in `net` is retired, and one the rule took\n    // out of `net` moved — the delta's definitions of it are where it went.\n    const { net } = operationRetirements(carried);\n    for (const op of carried) {\n      if (!op.remove) continue;\n      const to = net.has(op.id) ? [] : carried.filter((d) => !d.remove && d.id === op.id).map(operationAddress);\n      found.operations.push({ key: retiredKey(service, op.id), at: operationAddress(op), to });\n    }\n  }\n  if (!existsSync(paths.asyncapi)) return found;\n  const events = await readAsyncapi(paths.asyncapi, context);\n  const text = events.unreadable ? undefined : await readOr(paths.asyncapi, context);\n  if (text === undefined) return found;\n  const eventSlots = asyncapiSlots(parse(text));\n  if (!eventSlots.some((s) => s.remove)) return found;\n  const before = await preImageEvents(feature.dir, service);\n  // Presence is the whole match for a channel or operation slot — its\n  // identity IS the key. A message marker must also name the message the\n  // pre-image declared at that key, the merge's exactness on the message axis.\n  const carriedSlots = eventSlots.filter((s) => !s.remove || before === undefined || before.slots.has(slotKey(s)));\n  const carriedEvents: AsyncapiDoc = {\n    ...events,\n    messages: events.messages.filter(\n      (m) =>\n        m.remove !== true ||\n        before === undefined ||\n        before.doc.messages.some((b) => b.remove !== true && b.slot === m.slot && b.name === m.name),\n    ),\n  };\n  for (const slot of carriedSlots) {\n    if (!slot.remove || slot.section === \"components.messages\") continue;\n    found.slots.push({ key: retiredKey(service, slot.section, slot.key), at: `${slot.section}.${slot.key}`, to: [] });\n  }\n  // The operation axis's rule on the message name: a vacated declaration\n  // whose name the delta declares again was relocated — to another key, or\n  // inline under a channel — and those declarations are where it went.\n  const retired = messageRetirements(carriedEvents, carriedSlots, before?.doc ?? NOTHING_DECLARED);\n  for (const m of retired.vacated) {\n    const to = retired.net.has(m.name)\n      ? []\n      : carriedEvents.messages.filter((d) => d.remove !== true && d.name === m.name).map((d) => d.slot);\n    found.messages.push({ key: retiredKey(service, m.name), at: m.slot, to });\n  }\n  return found;\n}\n\nconst NOTHING_DECLARED: AsyncapiDoc = asyncapiFromText(\"\");\n\n/**\n * The contract one artifact held as this feature's merge found it, or\n * undefined when the snapshot holds nothing to trust. An artifact the merge\n * created, or never wrote, lost nothing to it — which is exactly what an empty\n * pre-image says: every marker in the delta missed, and no channel took inline\n * names with it.\n */\nasync function preImage(featureDir: string, service: string, artifact: string): Promise<string | undefined> {\n  const found = await readSnapshotPreImage(featureDir, { service, artifact });\n  if (found === null) return undefined;\n  return found.kind === \"held\" ? found.text : \"\";\n}\n\n/** The event pre-image as the reader and the slot walk see it — undefined when absent or unreadable. */\nasync function preImageEvents(\n  featureDir: string,\n  service: string,\n): Promise<{ doc: AsyncapiDoc; slots: ReadonlyMap<string, AsyncapiSlot> } | undefined> {\n  const text = await preImage(featureDir, service, ARTIFACT_FILES.asyncapi);\n  if (text === undefined) return undefined;\n  const doc = asyncapiFromText(text);\n  return doc.unreadable ? undefined : { doc, slots: slotsByKey(asyncapiSlots(parse(text))) };\n}\n\nfunction isDirectory(path: string): boolean {\n  try {\n    return statSync(path).isDirectory();\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Add one vacation. Already in id order without a sort: the walk records the\n * features in `listFeatures`' `compareIds` order. Distinct per feature,\n * address and kind, because two archived directories can carry one feature\n * id (the id is read off the directory name), and \"archived FEAT-7 and\n * FEAT-7\" names one feature twice — a second directory's move away from the\n * same address widens that feature's destinations instead.\n */\nfunction record(into: Map<string, Vacations>, key: string, vacated: Vacated): void {\n  const all = into.get(key);\n  if (all === undefined) {\n    into.set(key, [vacated]);\n    return;\n  }\n  const same = (v: Vacated): boolean =>\n    v.by === vacated.by && v.at === vacated.at && (v.to.length === 0) === (vacated.to.length === 0);\n  if (!all.some(same)) {\n    into.set(key, [...all, vacated]);\n    return;\n  }\n  const widen = (v: Vacated): Vacated => (same(v) ? { ...v, to: [...new Set([...v.to, ...vacated.to])] } : v);\n  const [first, ...rest] = all;\n  into.set(key, [widen(first), ...rest.map(widen)]);\n}\n"]}

package/dist/core/coherence/retired/event-pair.js

@@ -0,0 +1,62 @@
+/**
+ * One service's pair of event contracts — the feature delta and the living
+ * contract — read the one way every slot judgement on the event axis reads
+ * them.
+ *
+ * Two readers build it, and they must never disagree: the feature gate's walk
+ * (../events/declared.ts), which grades baselines and markers and collects the
+ * revival candidates, and `serviceRevivals` (./revival/revived.ts), which asks the
+ * revival question standalone for `loam rebase`. The second used to re-spell
+ * the first's guards — existence, decode, an unreadable living side — and its
+ * own living-slot map, so a change to the gate's guard would have left rebase
+ * and validate giving two answers about one tree with no test comparing them.
+ *
+ * Here, in retired/, because it is the lowest package both readers import: the
+ * event walk already imports this package (for the revival candidates), and a
+ * value edge from here up into events/ would be a package cycle. The merge
+ * simulation (./merged.ts) is here for the same reason, and rides on the pair
+ * as `merged()`: the walk grades the post-archive contract with it, and the
+ * revival check compares it with the living contract — one simulation per
+ * pair, whichever asks first.
+ */
+import { existsSync } from "node:fs";
+import { parse } from "yaml";
+import { readOr } from "../../openapi/contract-text.js";
+import { asyncapiSlots, slotsByKey } from "../../asyncapi/digest.js";
+import { mergedAsyncapiDoc } from "./merged.js";
+/**
+ * Read both sides' texts and slots. Each text is parsed ONCE and kept: the
+ * slot walk and the surface half of the baseline grade read the same resolved
+ * tree, and a second `parse` of the same bytes is a second chance for the two
+ * halves to disagree about what the delta declares.
+ */
+export async function readEventPair(sides, context) {
+    const { featPath, featDoc, livingPath, livingDoc, service } = sides;
+    const featText = sides.featText ?? (await readOr(featPath, context));
+    const featPlain = featText === undefined ? {} : parse(featText);
+    const livingExists = existsSync(livingPath);
+    const livingText = !livingExists || livingDoc.unreadable ? undefined : await readOr(livingPath, context);
+    const livingPlain = livingText === undefined ? {} : parse(livingText);
+    const livingAnswers = livingText !== undefined || !livingExists;
+    // Lazy: most pairs never need it on the rebase path, and the walk asks for
+    // it once. Boxed, so an `undefined` answer is remembered too.
+    let simulated;
+    const merged = () => (simulated ??= {
+        merged: !livingAnswers || featText === undefined
+            ? undefined
+            : mergedAsyncapiDoc({ livingText, livingDoc, livingRoot: livingPlain, featureText: featText, service }),
+    }).merged;
+    return {
+        featDoc,
+        featSlots: asyncapiSlots(featPlain),
+        featPlain,
+        featText,
+        livingDoc,
+        livingSlots: slotsByKey(asyncapiSlots(livingPlain)),
+        livingText,
+        livingPlain,
+        livingAnswers,
+        merged,
+    };
+}
+//# sourceMappingURL=event-pair.js.map

package/dist/core/coherence/retired/event-pair.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-pair.js","sourceRoot":"","sources":["../../../../src/core/coherence/retired/event-pair.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAE,MAAM,EAAE,MAAM,gCAAgC,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,UAAU,EAAqB,MAAM,0BAA0B,CAAC;AAGxF,OAAO,EAAE,iBAAiB,EAAqB,MAAM,aAAa,CAAC;AAiEnE;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,KAAgB,EAAE,OAAsB;IAC1E,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC;IACpE,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,CAAC,MAAM,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;IACrE,MAAM,SAAS,GAAY,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IACzE,MAAM,YAAY,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC;IAC5C,MAAM,UAAU,GAAG,CAAC,YAAY,IAAI,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IACzG,MAAM,WAAW,GAAY,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IAC/E,MAAM,aAAa,GAAG,UAAU,KAAK,SAAS,IAAI,CAAC,YAAY,CAAC;IAChE,2EAA2E;IAC3E,8DAA8D;IAC9D,IAAI,SAA2D,CAAC;IAChE,MAAM,MAAM,GAAG,GAA6B,EAAE,CAC5C,CAAC,SAAS,KAAK;QACb,MAAM,EAAE,CAAC,aAAa,IAAI,QAAQ,KAAK,SAAS;YAC9C,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,iBAAiB,CAAC,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;KAC1G,CAAC,CAAC,MAAM,CAAC;IACZ,OAAO;QACL,OAAO;QACP,SAAS,EAAE,aAAa,CAAC,SAAS,CAAC;QACnC,SAAS;QACT,QAAQ;QACR,SAAS;QACT,WAAW,EAAE,UAAU,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC;QACnD,UAAU;QACV,WAAW;QACX,aAAa;QACb,MAAM;KACP,CAAC;AACJ,CAAC","sourcesContent":["/**\n * One service's pair of event contracts — the feature delta and the living\n * contract — read the one way every slot judgement on the event axis reads\n * them.\n *\n * Two readers build it, and they must never disagree: the feature gate's walk\n * (../events/declared.ts), which grades baselines and markers and collects the\n * revival candidates, and `serviceRevivals` (./revival/revived.ts), which asks the\n * revival question standalone for `loam rebase`. The second used to re-spell\n * the first's guards — existence, decode, an unreadable living side — and its\n * own living-slot map, so a change to the gate's guard would have left rebase\n * and validate giving two answers about one tree with no test comparing them.\n *\n * Here, in retired/, because it is the lowest package both readers import: the\n * event walk already imports this package (for the revival candidates), and a\n * value edge from here up into events/ would be a package cycle. The merge\n * simulation (./merged.ts) is here for the same reason, and rides on the pair\n * as `merged()`: the walk grades the post-archive contract with it, and the\n * revival check compares it with the living contract — one simulation per\n * pair, whichever asks first.\n */\nimport { existsSync } from \"node:fs\";\nimport { parse } from \"yaml\";\nimport { readOr } from \"../../openapi/contract-text.js\";\nimport { asyncapiSlots, slotsByKey, type AsyncapiSlot } from \"../../asyncapi/digest.js\";\nimport type { AsyncapiDoc } from \"../../asyncapi/model.js\";\nimport type { FleetContext } from \"../../fleet-context.js\";\nimport { mergedAsyncapiDoc, type MergedEvents } from \"./merged.js\";\n\n/** The four facts every slot judgement reads: each side as the reader parsed it, and as its slots. */\nexport interface EventPair {\n  featDoc: AsyncapiDoc;\n  featSlots: AsyncapiSlot[];\n  livingDoc: AsyncapiDoc;\n  /** The living contract's slots by `slotKey`; empty where it is absent or did not read. */\n  livingSlots: Map<string, AsyncapiSlot>;\n}\n\n/** The pair, plus the texts and trees the gate's other graders read from the same bytes. */\nexport interface EventPairRead extends EventPair {\n  /** The feature delta's resolved parse — `{}` when its text did not decode. */\n  featPlain: unknown;\n  featText: string | undefined;\n  /** The living contract's text — undefined when it is ABSENT or did not read; `livingAnswers` tells the two apart. */\n  livingText: string | undefined;\n  /** The living contract's resolved parse; `{}` where there is no living text. */\n  livingPlain: unknown;\n  /**\n   * Can anything be graded against the living side? Absent is a real answer —\n   * everything the delta spells is new, and a baseline only means something\n   * for a slot that already exists. Unreadable is NOT an answer: grading pins,\n   * markers or revivals against an empty parse would call every restatement\n   * new and every marker stale, so each of those checks stands down and the\n   * (later) merge refuses the unreadable side by name.\n   */\n  livingAnswers: boolean;\n  /**\n   * The living contract as the archive would leave it (./merged.ts), computed\n   * on first ask and kept — the create branch's document where no living\n   * contract exists; undefined where the living side does not answer, or the\n   * merge refuses the pair. The walk asks it only with a living text in hand.\n   * Its tree rides along for the one reader that follows a `$ref` back.\n   */\n  merged(): MergedEvents | undefined;\n}\n\n/**\n * Where one service's two contracts of one axis live, and their parses — read\n * by the caller, which needs them before this. The OpenAPI revival read\n * (./revival/arrivals.ts) takes the same shape.\n */\nexport interface PairSides<Doc = AsyncapiDoc> {\n  featPath: string;\n  /** Readable: an unreadable feature delta is `asyncapi.invalid` (`openapi.invalid`), and nothing is graded against it. */\n  featDoc: Doc;\n  livingPath: string;\n  livingDoc: Doc;\n  /** The service the pair belongs to — what a refusal of the simulated merge would name. */\n  service: string;\n  /**\n   * The delta's text when the caller holds a version of it that is not on\n   * disk yet — `loam rebase`'s, with the pins it is about to write; read from\n   * `featPath` when absent. The merge's quote/edit verdict turns on the pins,\n   * so the revival question asked of the delta as it stood before a repin can\n   * answer for a document rebase is about to replace: a quote pinned to its\n   * own content is skipped, and repinned over another operation it is an edit\n   * that lands. A pin changes no identity or address, so `featDoc`, read from\n   * disk, still names what the text declares.\n   */\n  featText?: string;\n}\n\n/**\n * Read both sides' texts and slots. Each text is parsed ONCE and kept: the\n * slot walk and the surface half of the baseline grade read the same resolved\n * tree, and a second `parse` of the same bytes is a second chance for the two\n * halves to disagree about what the delta declares.\n */\nexport async function readEventPair(sides: PairSides, context?: FleetContext): Promise<EventPairRead> {\n  const { featPath, featDoc, livingPath, livingDoc, service } = sides;\n  const featText = sides.featText ?? (await readOr(featPath, context));\n  const featPlain: unknown = featText === undefined ? {} : parse(featText);\n  const livingExists = existsSync(livingPath);\n  const livingText = !livingExists || livingDoc.unreadable ? undefined : await readOr(livingPath, context);\n  const livingPlain: unknown = livingText === undefined ? {} : parse(livingText);\n  const livingAnswers = livingText !== undefined || !livingExists;\n  // Lazy: most pairs never need it on the rebase path, and the walk asks for\n  // it once. Boxed, so an `undefined` answer is remembered too.\n  let simulated: { merged: MergedEvents | undefined } | undefined;\n  const merged = (): MergedEvents | undefined =>\n    (simulated ??= {\n      merged: !livingAnswers || featText === undefined\n        ? undefined\n        : mergedAsyncapiDoc({ livingText, livingDoc, livingRoot: livingPlain, featureText: featText, service }),\n    }).merged;\n  return {\n    featDoc,\n    featSlots: asyncapiSlots(featPlain),\n    featPlain,\n    featText,\n    livingDoc,\n    livingSlots: slotsByKey(asyncapiSlots(livingPlain)),\n    livingText,\n    livingPlain,\n    livingAnswers,\n    merged,\n  };\n}\n"]}

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

@@ -0,0 +1,79 @@
+/**
+ * The contract as the feature would leave it: the REAL merge
+ * (core/asyncapi/merge/merge.ts, core/openapi/merge/merge.ts) run over the
+ * two texts and read back, nothing written. On the event axis one simulation
+ * feeds three gate questions — the `declares()` join in ../events/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), the consumer gate's wire half (a channel or
+ * operation removal that stops the service SENDING a message the fleet still
+ * consumes), and the revival check (./revival/arrivals.ts) — which asks it on both
+ * axes: where does each operationId and message name stand once the delta
+ * merges, against where it stands now.
+ *
+ * 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. The revival check is
+ * the proof: it re-derived the merge case by case — a relocation marker
+ * anywhere, a swap by a named operation, a channel restated with a `$ref` —
+ * and every review found a shape the derivation missed (a marker at an
+ * address the id never lived at, a replacement with no operationId).
+ *
+ * A living contract that does not exist is the archive's CREATE branch: it
+ * writes the delta with its markers stripped, and that is what the merged
+ * contract is.
+ */
+import { parse } from "yaml";
+import { asyncapiDocOf } from "../../asyncapi/read.js";
+import { AsyncapiMergeError } from "../../asyncapi/merge/error.js";
+import { stripAsyncapiMarkers } from "../../asyncapi/merge/markers.js";
+import { mergeAsyncapiSlots } from "../../asyncapi/merge/merge.js";
+import { openapiFromText } from "../../openapi/doc.js";
+import { OpenapiMergeError } from "../../openapi/merge/error.js";
+import { stripOpenapiRemovalMarkers } from "../../openapi/merge/markers.js";
+import { mergeOpenapiPaths } from "../../openapi/merge/merge.js";
+/**
+ * Simulate the archive-time event merge, or stand down. Both documents are
+ * known readable here (the pair, ./event-pair.ts, asks only with the delta's
+ * text in hand and a living side that answers — readable, or absent — and
+ * both of its readers, the walk in ../events/declared.ts and rebase's
+ * `serviceRevivals`, refuse an unreadable delta first), 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 walk falls back to the feature ∪ living union view, which can
+ * only be too lenient, the revival check grades no message, and the
+ * archive's own plan surfaces the refusal by name — a refusal `--approve`
+ * cannot pass, so nothing it would have graded can land.
+ */
+export function mergedAsyncapiDoc(input) {
+    const { livingText, livingDoc, livingRoot, featureText, service } = input;
+    try {
+        const text = livingText === undefined ? stripAsyncapiMarkers(featureText, service) : mergeAsyncapiSlots(livingText, featureText, service).text;
+        if (text === null)
+            return { doc: livingDoc, root: livingRoot };
+        const root = parse(text);
+        return { doc: asyncapiDocOf(root), root };
+    }
+    catch (error) {
+        if (error instanceof AsyncapiMergeError)
+            return undefined;
+        throw error;
+    }
+}
+/** The OpenAPI twin, through the same function archive's plan calls — `undefined` where that merge refuses. */
+export function mergedOpenapiDoc(input) {
+    const { livingText, livingDoc, featureText, service } = input;
+    try {
+        if (livingText === undefined)
+            return openapiFromText(stripOpenapiRemovalMarkers(featureText, service));
+        const out = mergeOpenapiPaths(livingText, featureText, service);
+        return out.text === null ? livingDoc : openapiFromText(out.text);
+    }
+    catch (error) {
+        if (error instanceof OpenapiMergeError)
+            return undefined;
+        throw error;
+    }
+}
+//# sourceMappingURL=merged.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"merged.js","sourceRoot":"","sources":["../../../../src/core/coherence/retired/merged.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;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,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AACvE,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,EAAE,eAAe,EAAmB,MAAM,sBAAsB,CAAC;AACxE,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,EAAE,0BAA0B,EAAE,MAAM,gCAAgC,CAAC;AAC5E,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAgCjE;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAsB;IACtD,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC;IAC1E,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,oBAAoB,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,kBAAkB,CAAC,UAAU,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC;QAC/I,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;QAC/D,MAAM,IAAI,GAAY,KAAK,CAAC,IAAI,CAAC,CAAC;QAClC,OAAO,EAAE,GAAG,EAAE,aAAa,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC;IAC5C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,kBAAkB;YAAE,OAAO,SAAS,CAAC;QAC1D,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,+GAA+G;AAC/G,MAAM,UAAU,gBAAgB,CAAC,KAAuC;IACtE,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC;IAC9D,IAAI,CAAC;QACH,IAAI,UAAU,KAAK,SAAS;YAAE,OAAO,eAAe,CAAC,0BAA0B,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC;QACvG,MAAM,GAAG,GAAG,iBAAiB,CAAC,UAAU,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;QAChE,OAAO,GAAG,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACnE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,iBAAiB;YAAE,OAAO,SAAS,CAAC;QACzD,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, core/openapi/merge/merge.ts) run over the\n * two texts and read back, nothing written. On the event axis one simulation\n * feeds three gate questions — the `declares()` join in ../events/events.ts\n * (a retired or edited-away send must stop answering \"the service declares\n * this\" BEFORE archive, or a leftover `Publishes:` line passes the gate and\n * breaks the post-archive fleet), the consumer gate's wire half (a channel or\n * operation removal that stops the service SENDING a message the fleet still\n * consumes), and the revival check (./revival/arrivals.ts) — which asks it on both\n * axes: where does each operationId and message name stand once the delta\n * merges, against where it stands now.\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. The revival check is\n * the proof: it re-derived the merge case by case — a relocation marker\n * anywhere, a swap by a named operation, a channel restated with a `$ref` —\n * and every review found a shape the derivation missed (a marker at an\n * address the id never lived at, a replacement with no operationId).\n *\n * A living contract that does not exist is the archive's CREATE branch: it\n * writes the delta with its markers stripped, and that is what the merged\n * contract is.\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 { stripAsyncapiMarkers } from \"../../asyncapi/merge/markers.js\";\nimport { mergeAsyncapiSlots } from \"../../asyncapi/merge/merge.js\";\nimport { openapiFromText, type OpenapiDoc } from \"../../openapi/doc.js\";\nimport { OpenapiMergeError } from \"../../openapi/merge/error.js\";\nimport { stripOpenapiRemovalMarkers } from \"../../openapi/merge/markers.js\";\nimport { mergeOpenapiPaths } from \"../../openapi/merge/merge.js\";\n\n/** The two texts the simulation merges, plus the living side's existing parse. */\nexport interface MergeSimulationInput<Doc> {\n  /** undefined when no living contract exists — the archive then creates one from the delta. */\n  livingText: string | undefined;\n  /** The reader's parse of livingText — reused verbatim when the merge writes nothing. */\n  livingDoc: Doc;\n  featureText: string;\n  service: string;\n}\n\n/** The event simulation's input: the pair's texts, plus the living side's tree. */\nexport interface EventMergeInput extends MergeSimulationInput<AsyncapiDoc> {\n  /** The reader's parse of livingText — the merged tree, verbatim, when the merge writes nothing. */\n  livingRoot: unknown;\n}\n\n/** The contract the event merge would leave: as read, and the tree it was read from. */\nexport interface MergedEvents {\n  doc: AsyncapiDoc;\n  /**\n   * The merged document's parse — where a `$ref` can be followed back to the\n   * slot holding it. The read model keeps no pointer, and the move-back\n   * remedy (./revival/revived.ts) has to name the channels still pointing at\n   * a key it tells the author to retire: told only to retire it, an author\n   * left a living channel `$ref`-ing nothing and its send operation stopped\n   * sending a message the fleet consumes.\n   */\n  root: unknown;\n}\n\n/**\n * Simulate the archive-time event merge, or stand down. Both documents are\n * known readable here (the pair, ./event-pair.ts, asks only with the delta's\n * text in hand and a living side that answers — readable, or absent — and\n * both of its readers, the walk in ../events/declared.ts and rebase's\n * `serviceRevivals`, refuse an unreadable delta first), so the only\n * refusals left are the merge's own judgement calls — an aliased section, a\n * section spelling one slot key twice. `undefined` on those rather than a\n * throw: the walk falls back to the feature ∪ living union view, which can\n * only be too lenient, the revival check grades no message, and the\n * archive's own plan surfaces the refusal by name — a refusal `--approve`\n * cannot pass, so nothing it would have graded can land.\n */\nexport function mergedAsyncapiDoc(input: EventMergeInput): MergedEvents | undefined {\n  const { livingText, livingDoc, livingRoot, featureText, service } = input;\n  try {\n    const text = livingText === undefined ? stripAsyncapiMarkers(featureText, service) : mergeAsyncapiSlots(livingText, featureText, service).text;\n    if (text === null) return { doc: livingDoc, root: livingRoot };\n    const root: unknown = parse(text);\n    return { doc: asyncapiDocOf(root), root };\n  } catch (error) {\n    if (error instanceof AsyncapiMergeError) return undefined;\n    throw error;\n  }\n}\n\n/** The OpenAPI twin, through the same function archive's plan calls — `undefined` where that merge refuses. */\nexport function mergedOpenapiDoc(input: MergeSimulationInput<OpenapiDoc>): OpenapiDoc | undefined {\n  const { livingText, livingDoc, featureText, service } = input;\n  try {\n    if (livingText === undefined) return openapiFromText(stripOpenapiRemovalMarkers(featureText, service));\n    const out = mergeOpenapiPaths(livingText, featureText, service);\n    return out.text === null ? livingDoc : openapiFromText(out.text);\n  } catch (error) {\n    if (error instanceof OpenapiMergeError) return undefined;\n    throw error;\n  }\n}\n"]}

package/dist/core/coherence/retired/retirement.js

@@ -0,0 +1,49 @@
+/**
+ * A relocation — same operationId, removal marker on the old slot, upsert on
+ * the new one — retires nothing. Every rule that asks "is this operation going
+ * away" must therefore ask the NET set (markers this feature does not
+ * redefine), while "did the author write a marker at all" asks the raw one.
+ * Conflating them made moving an endpoint fail three checks at once for a
+ * change that removes nothing.
+ *
+ * A marker with no `operationId` is not here at all: the reader lists it apart
+ * (`anonymousRemovals`), and the merge deletes a living operation only when the
+ * one at the marker's own method and path carries the id the marker names — a
+ * marker naming none matches nothing, so it retires nothing either. That match
+ * is also why a marker is a REQUEST rather than a record: one that missed its
+ * slot deleted nothing, and the retired index (./archived.ts) checks each
+ * against the contract its merge ran against before counting it.
+ */
+export function operationRetirements(ops) {
+    const redefined = new Set(ops.filter((op) => !op.remove).map((op) => op.id));
+    const markerIds = new Set(ops.filter((op) => op.remove).map((op) => op.id));
+    const net = new Set([...markerIds].filter((id) => !redefined.has(id)));
+    return { markerIds, net };
+}
+/**
+ * A relocation — same message name, marker on the old key, declaration at a
+ * new one — retires nothing. "Is this message going away" asks the NET set;
+ * "did the author write a marker" asks the raw one, the OpenAPI distinction
+ * above verbatim. Two raw sets, because the two marker shapes carry different
+ * debts: a message-slot marker must be justified by a REMOVED requirement,
+ * while a channel-slot removal needs exactness only (requirements join on
+ * message names, never channel keys — SCHEMA.md) and its living inline
+ * interior leaves with it.
+ *
+ * `living` is the contract the delta was merged INTO (or is about to be): a
+ * channel removal's inline interior is written there and nowhere in the delta,
+ * which carries only the marker. The feature gate passes the living contract
+ * on disk; the retired index passes the archived feature's snapshot pre-image,
+ * the living contract as it stood the moment that merge ran.
+ */
+export function messageRetirements(featDoc, featSlots, living) {
+    const markers = featDoc.messages.filter((m) => m.remove === true && m.slot.startsWith("components.messages."));
+    const channelRemovals = featSlots.filter((s) => s.section === "channels" && s.remove).map((s) => s.key);
+    const inline = living.messages.filter((m) => channelRemovals.some((ck) => m.slot.startsWith(`channels.${ck}.messages.`)));
+    const markerNames = new Set(markers.map((m) => m.name));
+    const inlineRetired = new Set(inline.map((m) => m.name));
+    const redeclared = new Set(featDoc.messages.filter((m) => m.remove !== true).map((m) => m.name));
+    const net = new Set([...markerNames, ...inlineRetired].filter((name) => !redeclared.has(name)));
+    return { markerNames, inlineRetired, redeclared, net, vacated: [...markers, ...inline] };
+}
+//# sourceMappingURL=retirement.js.map

package/dist/core/coherence/retired/retirement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retirement.js","sourceRoot":"","sources":["../../../../src/core/coherence/retired/retirement.ts"],"names":[],"mappings":"AA6BA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAyB;IAC5D,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC7E,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC5E,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACvE,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC;AAC5B,CAAC;AAqBD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAAoB,EACpB,SAAkC,EAClC,MAAmB;IAEnB,MAAM,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,sBAAsB,CAAC,CAAC,CAAC;IAC/G,MAAM,eAAe,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,UAAU,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACxG,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;IAC1H,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IACxD,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IACzD,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IACjG,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,WAAW,EAAE,GAAG,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAChG,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,UAAU,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,GAAG,MAAM,CAAC,EAAE,CAAC;AAC3F,CAAC","sourcesContent":["/**\n * What ONE contract delta retires — the rule, spelled once for every reader\n * that asks it.\n *\n * Two readers ask it of different features, and they must never disagree. The\n * feature gate asks it of the delta being graded (`../declared.ts` for the\n * OpenAPI axis, `../events/declared.ts` for the event axis): which operations\n * and messages is THIS feature taking out of the living contract. The retired\n * index (`./archived.ts`) asks the same question of every feature already in\n * `features/archive/`: which operations and messages did a shipped feature take\n * out, so a later delta spelling one of them is a revival rather than an\n * addition. A second spelling of the relocation rule in the index is how a\n * moved endpoint would read as retired there while the gate called it moved.\n *\n * Moved here from the two walks verbatim, comments and all; the walks keep the\n * checks that USE the sets, this module keeps the sets.\n */\nimport type { Operation } from \"../../openapi/doc.js\";\nimport type { AsyncapiSlot } from \"../../asyncapi/digest.js\";\nimport type { AsyncapiDoc, EventMessage } from \"../../asyncapi/model.js\";\n\n/** The OpenAPI half: every id a removal marker names, and the ones genuinely retired. */\nexport interface OperationRetirements {\n  /** Every operationId a removal marker names, relocations included — \"did the author write a marker\". */\n  markerIds: Set<string>;\n  /** Markers minus relocations — \"is this operation going away\". */\n  net: Set<string>;\n}\n\n/**\n * A relocation — same operationId, removal marker on the old slot, upsert on\n * the new one — retires nothing. Every rule that asks \"is this operation going\n * away\" must therefore ask the NET set (markers this feature does not\n * redefine), while \"did the author write a marker at all\" asks the raw one.\n * Conflating them made moving an endpoint fail three checks at once for a\n * change that removes nothing.\n *\n * A marker with no `operationId` is not here at all: the reader lists it apart\n * (`anonymousRemovals`), and the merge deletes a living operation only when the\n * one at the marker's own method and path carries the id the marker names — a\n * marker naming none matches nothing, so it retires nothing either. That match\n * is also why a marker is a REQUEST rather than a record: one that missed its\n * slot deleted nothing, and the retired index (./archived.ts) checks each\n * against the contract its merge ran against before counting it.\n */\nexport function operationRetirements(ops: readonly Operation[]): OperationRetirements {\n  const redefined = new Set(ops.filter((op) => !op.remove).map((op) => op.id));\n  const markerIds = new Set(ops.filter((op) => op.remove).map((op) => op.id));\n  const net = new Set([...markerIds].filter((id) => !redefined.has(id)));\n  return { markerIds, net };\n}\n\n/** The event half's four sets — the raw marker shapes, the redeclarations, and what is genuinely going away. */\nexport interface MessageRetirements {\n  /** Names a `components.messages` marker retires, relocations included. */\n  markerNames: Set<string>;\n  /** Names the LIVING contract declares inline under a channel this delta removes. */\n  inlineRetired: Set<string>;\n  /** Names the delta declares again, anywhere — a marker on one of these is a relocation. */\n  redeclared: Set<string>;\n  /** `markerNames ∪ inlineRetired`, minus `redeclared`. */\n  net: Set<string>;\n  /**\n   * The declarations behind the first two sets, each where it stood — the\n   * `components.messages` markers, and the living inline declarations under\n   * a removed channel. What the retired index (./archived.ts) records as the\n   * addresses an archived feature vacated, read off this one spelling.\n   */\n  vacated: EventMessage[];\n}\n\n/**\n * A relocation — same message name, marker on the old key, declaration at a\n * new one — retires nothing. \"Is this message going away\" asks the NET set;\n * \"did the author write a marker\" asks the raw one, the OpenAPI distinction\n * above verbatim. Two raw sets, because the two marker shapes carry different\n * debts: a message-slot marker must be justified by a REMOVED requirement,\n * while a channel-slot removal needs exactness only (requirements join on\n * message names, never channel keys — SCHEMA.md) and its living inline\n * interior leaves with it.\n *\n * `living` is the contract the delta was merged INTO (or is about to be): a\n * channel removal's inline interior is written there and nowhere in the delta,\n * which carries only the marker. The feature gate passes the living contract\n * on disk; the retired index passes the archived feature's snapshot pre-image,\n * the living contract as it stood the moment that merge ran.\n */\nexport function messageRetirements(\n  featDoc: AsyncapiDoc,\n  featSlots: readonly AsyncapiSlot[],\n  living: AsyncapiDoc,\n): MessageRetirements {\n  const markers = featDoc.messages.filter((m) => m.remove === true && m.slot.startsWith(\"components.messages.\"));\n  const channelRemovals = featSlots.filter((s) => s.section === \"channels\" && s.remove).map((s) => s.key);\n  const inline = living.messages.filter((m) => channelRemovals.some((ck) => m.slot.startsWith(`channels.${ck}.messages.`)));\n  const markerNames = new Set(markers.map((m) => m.name));\n  const inlineRetired = new Set(inline.map((m) => m.name));\n  const redeclared = new Set(featDoc.messages.filter((m) => m.remove !== true).map((m) => m.name));\n  const net = new Set([...markerNames, ...inlineRetired].filter((name) => !redeclared.has(name)));\n  return { markerNames, inlineRetired, redeclared, net, vacated: [...markers, ...inline] };\n}\n"]}