@ybotok/loam 0.1.0-beta.3 → 0.2.0-alpha.1

package/dist/core/openapi/depth.js

@@ -0,0 +1,122 @@
+/**
+ * The contract-depth probes: does an operation say anything about what it
+ * returns, and does every internal `$ref` point at something.
+ *
+ * Form validated and depth did not, and that was invisible from the output:
+ * an operation whose one response is `description: OK`, and a `$ref` to a
+ * schema nobody ever wrote, both validate exactly as cleanly as a complete
+ * contract even though a reader still needs the code. Everything here is a
+ * PRESENCE probe over the document's own keys: nothing reads what a schema
+ * says, only whether one was declared at all, so the reader's structure-only
+ * stance holds.
+ *
+ * A local pointer walk rather than an import from `merge/components.ts`: the merge
+ * package already imports this package (`HTTP_METHODS` from doc.ts), so the
+ * reverse import would be a package cycle — the same reason read-side
+ * `resolvePointer` copies exist on the asyncapi axis.
+ */
+/** Status codes whose response legitimately carries no body. */
+const NO_CONTENT = new Set(["204", "304"]);
+/**
+ * True when no response declares content with a schema while at least one
+ * response should carry a body — an operation with no `responses` at all
+ * counts, one whose only responses are 204/304 does not. A response that is
+ * itself a `$ref` counts as described: somebody wrote the shape down, and the
+ * dangling case is the ref probe's finding, not this one's.
+ */
+export function responseUndescribed(op) {
+    if (op === null || typeof op !== "object")
+        return true;
+    const responses = op["responses"];
+    if (responses === null || responses === undefined || typeof responses !== "object" || Array.isArray(responses)) {
+        return true;
+    }
+    const entries = Object.entries(responses);
+    if (entries.length === 0)
+        return true;
+    let owesBody = false;
+    for (const [code, resp] of entries) {
+        if (NO_CONTENT.has(code))
+            continue;
+        owesBody = true;
+        if (resp === null || typeof resp !== "object" || Array.isArray(resp))
+            continue;
+        const rec = resp;
+        if ("$ref" in rec)
+            return false;
+        const content = rec["content"];
+        if (content === null || typeof content !== "object" || Array.isArray(content))
+            continue;
+        for (const media of Object.values(content)) {
+            if (media !== null && typeof media === "object" && "schema" in media) {
+                return false;
+            }
+        }
+    }
+    return owesBody;
+}
+/**
+ * The non-2xx response codes an operation declares, in document order.
+ *
+ * Exact three-digit codes only. `default` names no case — it is whatever else
+ * happens — and the `4XX`/`5XX` wildcards name a class rather than a refusal,
+ * so no scenario could be written for either and demanding one would teach an
+ * author to write a scenario about nothing. 1xx and 3xx are excluded with 2xx:
+ * a redirect or a continue is not the service saying no.
+ */
+export function failureCodesOf(op) {
+    if (op === null || typeof op !== "object")
+        return [];
+    const responses = op["responses"];
+    if (responses === null || typeof responses !== "object" || Array.isArray(responses))
+        return [];
+    return Object.keys(responses).filter((code) => /^[45]\d\d$/.test(code));
+}
+/**
+ * Every internal `#/` reference in the document that resolves to nothing —
+ * deduped, document order. External references (URLs, file paths) are out of
+ * scope and never graded, matching the merge's documented stance.
+ */
+export function danglingRefs(root) {
+    const out = new Set();
+    const walk = (node) => {
+        if (Array.isArray(node)) {
+            for (const value of node)
+                walk(value);
+            return;
+        }
+        if (node === null || typeof node !== "object")
+            return;
+        for (const [key, value] of Object.entries(node)) {
+            if (key === "$ref" && typeof value === "string") {
+                if (value.startsWith("#/") && !resolves(root, value))
+                    out.add(value);
+                continue;
+            }
+            walk(value);
+        }
+    };
+    walk(root);
+    return [...out];
+}
+/** Does a local JSON pointer (`#/a/b~1c`) reach a node in this tree? */
+function resolves(root, ref) {
+    let current = root;
+    for (const raw of ref.slice(2).split("/")) {
+        const segment = raw.replace(/~1/g, "/").replace(/~0/g, "~");
+        if (Array.isArray(current)) {
+            const index = Number(segment);
+            if (!Number.isInteger(index) || index < 0 || index >= current.length)
+                return false;
+            current = current[index];
+        }
+        else if (current !== null && typeof current === "object" && segment in current) {
+            current = current[segment];
+        }
+        else {
+            return false;
+        }
+    }
+    return true;
+}
+//# sourceMappingURL=depth.js.map

package/dist/core/openapi/depth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"depth.js","sourceRoot":"","sources":["../../../src/core/openapi/depth.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The contract-depth probes: does an operation say anything about what it\n * returns, and does every internal `$ref` point at something.\n *\n * Form validated and depth did not, and that was invisible from the output:\n * an operation whose one response is `description: OK`, and a `$ref` to a\n * schema nobody ever wrote, both validate exactly as cleanly as a complete\n * contract even though a reader still needs the code. Everything here is a\n * PRESENCE probe over the document's own keys: nothing reads what a schema\n * says, only whether one was declared at all, so the reader's structure-only\n * stance holds.\n *\n * A local pointer walk rather than an import from `merge/components.ts`: the merge\n * package already imports this package (`HTTP_METHODS` from doc.ts), so the\n * reverse import would be a package cycle — the same reason read-side\n * `resolvePointer` copies exist on the asyncapi axis.\n */\n\n/** Status codes whose response legitimately carries no body. */\nconst NO_CONTENT = new Set([\"204\", \"304\"]);\n\n/**\n * True when no response declares content with a schema while at least one\n * response should carry a body — an operation with no `responses` at all\n * counts, one whose only responses are 204/304 does not. A response that is\n * itself a `$ref` counts as described: somebody wrote the shape down, and the\n * dangling case is the ref probe's finding, not this one's.\n */\nexport function responseUndescribed(op: unknown): boolean {\n  if (op === null || typeof op !== \"object\") return true;\n  const responses = (op as Record<string, unknown>)[\"responses\"];\n  if (responses === null || responses === undefined || typeof responses !== \"object\" || Array.isArray(responses)) {\n    return true;\n  }\n  const entries = Object.entries(responses as Record<string, unknown>);\n  if (entries.length === 0) return true;\n  let owesBody = false;\n  for (const [code, resp] of entries) {\n    if (NO_CONTENT.has(code)) continue;\n    owesBody = true;\n    if (resp === null || typeof resp !== \"object\" || Array.isArray(resp)) continue;\n    const rec = resp as Record<string, unknown>;\n    if (\"$ref\" in rec) return false;\n    const content = rec[\"content\"];\n    if (content === null || typeof content !== \"object\" || Array.isArray(content)) continue;\n    for (const media of Object.values(content as Record<string, unknown>)) {\n      if (media !== null && typeof media === \"object\" && \"schema\" in (media as Record<string, unknown>)) {\n        return false;\n      }\n    }\n  }\n  return owesBody;\n}\n\n/**\n * The non-2xx response codes an operation declares, in document order.\n *\n * Exact three-digit codes only. `default` names no case — it is whatever else\n * happens — and the `4XX`/`5XX` wildcards name a class rather than a refusal,\n * so no scenario could be written for either and demanding one would teach an\n * author to write a scenario about nothing. 1xx and 3xx are excluded with 2xx:\n * a redirect or a continue is not the service saying no.\n */\nexport function failureCodesOf(op: unknown): string[] {\n  if (op === null || typeof op !== \"object\") return [];\n  const responses = (op as Record<string, unknown>)[\"responses\"];\n  if (responses === null || typeof responses !== \"object\" || Array.isArray(responses)) return [];\n  return Object.keys(responses as Record<string, unknown>).filter((code) => /^[45]\\d\\d$/.test(code));\n}\n\n/**\n * Every internal `#/` reference in the document that resolves to nothing —\n * deduped, document order. External references (URLs, file paths) are out of\n * scope and never graded, matching the merge's documented stance.\n */\nexport function danglingRefs(root: unknown): string[] {\n  const out = new Set<string>();\n  const walk = (node: unknown): void => {\n    if (Array.isArray(node)) {\n      for (const value of node) walk(value);\n      return;\n    }\n    if (node === null || typeof node !== \"object\") return;\n    for (const [key, value] of Object.entries(node as Record<string, unknown>)) {\n      if (key === \"$ref\" && typeof value === \"string\") {\n        if (value.startsWith(\"#/\") && !resolves(root, value)) out.add(value);\n        continue;\n      }\n      walk(value);\n    }\n  };\n  walk(root);\n  return [...out];\n}\n\n/** Does a local JSON pointer (`#/a/b~1c`) reach a node in this tree? */\nfunction resolves(root: unknown, ref: string): boolean {\n  let current: unknown = root;\n  for (const raw of ref.slice(2).split(\"/\")) {\n    const segment = raw.replace(/~1/g, \"/\").replace(/~0/g, \"~\");\n    if (Array.isArray(current)) {\n      const index = Number(segment);\n      if (!Number.isInteger(index) || index < 0 || index >= current.length) return false;\n      current = current[index];\n    } else if (current !== null && typeof current === \"object\" && segment in (current as Record<string, unknown>)) {\n      current = (current as Record<string, unknown>)[segment];\n    } else {\n      return false;\n    }\n  }\n  return true;\n}\n"]}

package/dist/core/openapi/digest.js

@@ -0,0 +1,189 @@
+/**
+ * What operation content HASHES to, and what a recorded hash means when it is
+ * read back.
+ *
+ * A module of its own because the digest and the comparison it must agree with
+ * are a matched pair: key order must not matter here, since the merge's own
+ * idea of "this operation differs" is `isDeepStrictEqual`, which ignores it. A
+ * second spelling of either would go stale over a reordered `summary` pair the
+ * merge calls identical — a false collision on the one check whose whole worth
+ * is that it fires only for real ones.
+ */
+import { createHash } from "node:crypto";
+/**
+ * The baseline marker: which living version of this operation a FEATURE delta
+ * was written against. Same idea as a requirement's `Based-On:` (core/document/spec.ts),
+ * in the vendor-extension shape this axis already uses for `x-loam-remove`.
+ *
+ * This axis needs it MORE than the requirement axis does, because a feature's
+ * openapi.yaml is a COMPLETE document rather than a patch: authors restate the
+ * living contract around the slot they are changing, and the merge upserts every
+ * operation the document spells. So a feature that never meant to touch
+ * `refundOrder` — it merely quoted it — pushes its authoring-time copy back over
+ * whatever landed in between, reverting another team's shipped change without
+ * either feature overlapping the other at all. The pin is what lets the merge
+ * tell a QUOTE from an EDIT: a quote equals its own baseline, and is skipped.
+ */
+export const OPENAPI_BASELINE_KEY = "x-loam-based-on";
+/**
+ * The feature-only ROOT record that pins the surfaces the operation pin cannot
+ * reach: path-item non-method keys and components. `{ pathItems: {<path>:
+ * {<key>: <16-hex>}}, components: {"<kind>/<name>": <16-hex>} }` — written by
+ * `loam rebase`, graded by validate/archive, consumed by the merge, and
+ * stripped from every living document exactly like the pin. A single root
+ * record rather than in-value extensions because a component's value can be a
+ * bare boolean (JSON Schema allows `true`), which no in-value key survives.
+ */
+export const OPENAPI_BASELINES_KEY = "x-loam-baselines";
+/** The feature-only explicit removal marker's key. */
+export const OPENAPI_REMOVE_KEY = "x-loam-remove";
+/** Is this operation node a feature-only explicit removal marker? */
+export function isRemoval(node) {
+    return node !== null &&
+        typeof node === "object" &&
+        node[OPENAPI_REMOVE_KEY] === true;
+}
+/**
+ * Every key that is an instruction to loam rather than part of the contract.
+ * At PATH level none has any meaning — `x-loam-remove` addresses one
+ * operation and `x-loam-based-on` pins one — so a path item carrying either
+ * is an authoring mistake, and one that must not be published whatever else
+ * is done about it. Lives HERE, in the openapi root beside the keys it names,
+ * because both `merge/` and `baseline/` consume it and a value edge between
+ * those two packages in either direction would be a package cycle.
+ */
+export const FEATURE_ONLY_KEYS = new Set([OPENAPI_REMOVE_KEY, OPENAPI_BASELINE_KEY]);
+/**
+ * `value` with every feature-only key removed, at ANY depth — or the value
+ * unchanged (same reference) when it carries none. The component closure
+ * writes values VERBATIM into the living contract, and a component holding an
+ * operation shape (a `pathItems` component, a callback) can nest the markers
+ * where the path-level strip never walks: `--approve` once published
+ * `x-loam-remove: true` inside a living component, invisible even to
+ * `validate`, whose marker sweep reads `paths` alone.
+ */
+export function withoutFeatureKeysDeep(value) {
+    if (value === null || typeof value !== "object")
+        return value;
+    if (Array.isArray(value)) {
+        let changed = false;
+        const out = value.map((v) => {
+            const stripped = withoutFeatureKeysDeep(v);
+            if (stripped !== v)
+                changed = true;
+            return stripped;
+        });
+        return changed ? out : value;
+    }
+    const record = value;
+    let changed = false;
+    const out = {};
+    for (const [key, v] of Object.entries(record)) {
+        if (FEATURE_ONLY_KEYS.has(key)) {
+            changed = true;
+            continue;
+        }
+        const stripped = withoutFeatureKeysDeep(v);
+        if (stripped !== v)
+            changed = true;
+        out[key] = stripped;
+    }
+    return changed ? out : value;
+}
+/** How much of the sha256 an `x-loam-based-on` carries — the length every loam digest uses. */
+export const OPERATION_DIGEST_LENGTH = 16;
+/** The value shape of an `x-loam-based-on`, exactly as `operationDigest` writes it. */
+export const OPERATION_DIGEST_RE = new RegExp(`^[0-9a-f]{${OPERATION_DIGEST_LENGTH}}$`);
+/**
+ * Canonical JSON for a resolved YAML value: object keys sorted, arrays left in
+ * order, everything else as JSON writes it.
+ *
+ * Key ORDER must not matter, because the merge's own idea of "this operation
+ * differs" is `isDeepStrictEqual` (./merge/merge.ts), which ignores it. A
+ * digest that disagreed with that comparison would go stale over a reordered
+ * `summary`/`operationId` pair the merge itself calls identical — a false
+ * collision on the one check whose worth is that it fires only for real ones.
+ *
+ * Exported for the ASYNCAPI axis (core/asyncapi/digest.ts), whose slot
+ * digests are the same rule over different sections: one spelling of the
+ * canonical form for both axes, because two spellings would eventually
+ * disagree — the exact drift this module's own header names as the failure
+ * mode. The import direction is asyncapi → openapi only; nothing under
+ * core/openapi/ may import from core/asyncapi/, or the package graph cycles.
+ */
+export function canonicalJson(node) {
+    if (node === null || typeof node !== "object")
+        return JSON.stringify(node) ?? "null";
+    if (Array.isArray(node))
+        return `[${node.map(canonicalJson).join(",")}]`;
+    const entries = Object.entries(node)
+        .filter(([, value]) => value !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${entries.map(([key, value]) => `${JSON.stringify(key)}:${canonicalJson(value)}`).join(",")}}`;
+}
+/**
+ * The operation without its own baseline marker — what a digest is taken over,
+ * and what the merge writes.
+ *
+ * A pin is a statement ABOUT a delta, never part of the operation it describes.
+ * Inside the digest input, an operation's identity would depend on the pin
+ * pointing at it and no baseline could ever be self-consistent; inside the
+ * merged contract, a living operation would carry a pin to a version of itself
+ * and the next feature's baseline would hash the previous feature's bookkeeping.
+ */
+export function withoutOperationBaseline(node) {
+    if (node === null || typeof node !== "object" || Array.isArray(node))
+        return node;
+    const record = node;
+    if (!(OPENAPI_BASELINE_KEY in record))
+        return node;
+    const rest = { ...record };
+    delete rest[OPENAPI_BASELINE_KEY];
+    return rest;
+}
+/**
+ * The identity of ANY resolved value: sha256 of its canonical form. The one
+ * digest the path-item and component baselines carry — order-of-keys blind,
+ * array-order sensitive, legal over scalars and booleans, exactly as the
+ * operation digest always was.
+ */
+export function valueDigest(node) {
+    return createHash("sha256").update(canonicalJson(node), "utf8").digest("hex").slice(0, OPERATION_DIGEST_LENGTH);
+}
+/** The identity of an operation's CONTENT: sha256 of its canonical form, pin excluded. */
+export function operationDigest(node) {
+    return valueDigest(withoutOperationBaseline(node));
+}
+/**
+ * What a pin says, from digests alone — the one definition every decider
+ * shares: the gate (./baseline/gate.ts) and the merge
+ * (./merge/{merge,components,pin}.ts) alike. Two spellings of
+ * this rule would eventually disagree about which operations a merge writes,
+ * and the disagreement would be invisible until a contract came back wrong.
+ *
+ * Order matters: `quote` is settled against the delta's OWN content before the
+ * living contract is consulted. An operation equal to its own baseline was not
+ * edited, so what living holds now is nobody's business but the feature that
+ * put it there.
+ */
+export function classifyBaselineDigests(pin, ownDigest, livingDigest) {
+    if (pin === undefined)
+        return "unpinned";
+    if (livingDigest === undefined)
+        return "unfounded";
+    if (pin === ownDigest)
+        return "quote";
+    if (pin === livingDigest)
+        return "edit";
+    return "stale";
+}
+/** The `x-loam-based-on` a node declares, or undefined — non-strings included, so validate can refuse them. */
+export function operationBaselineOf(node) {
+    if (node === null || typeof node !== "object" || Array.isArray(node))
+        return undefined;
+    const value = node[OPENAPI_BASELINE_KEY];
+    if (value === undefined)
+        return undefined;
+    return typeof value === "string" ? value.trim() : String(value);
+}
+//# sourceMappingURL=digest.js.map

package/dist/core/openapi/digest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"digest.js","sourceRoot":"","sources":["../../../src/core/openapi/digest.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What operation content HASHES to, and what a recorded hash means when it is\n * read back.\n *\n * A module of its own because the digest and the comparison it must agree with\n * are a matched pair: key order must not matter here, since the merge's own\n * idea of \"this operation differs\" is `isDeepStrictEqual`, which ignores it. A\n * second spelling of either would go stale over a reordered `summary` pair the\n * merge calls identical — a false collision on the one check whose whole worth\n * is that it fires only for real ones.\n */\nimport { createHash } from \"node:crypto\";\n\n/**\n * The baseline marker: which living version of this operation a FEATURE delta\n * was written against. Same idea as a requirement's `Based-On:` (core/document/spec.ts),\n * in the vendor-extension shape this axis already uses for `x-loam-remove`.\n *\n * This axis needs it MORE than the requirement axis does, because a feature's\n * openapi.yaml is a COMPLETE document rather than a patch: authors restate the\n * living contract around the slot they are changing, and the merge upserts every\n * operation the document spells. So a feature that never meant to touch\n * `refundOrder` — it merely quoted it — pushes its authoring-time copy back over\n * whatever landed in between, reverting another team's shipped change without\n * either feature overlapping the other at all. The pin is what lets the merge\n * tell a QUOTE from an EDIT: a quote equals its own baseline, and is skipped.\n */\nexport const OPENAPI_BASELINE_KEY = \"x-loam-based-on\";\n\n/**\n * The feature-only ROOT record that pins the surfaces the operation pin cannot\n * reach: path-item non-method keys and components. `{ pathItems: {<path>:\n * {<key>: <16-hex>}}, components: {\"<kind>/<name>\": <16-hex>} }` — written by\n * `loam rebase`, graded by validate/archive, consumed by the merge, and\n * stripped from every living document exactly like the pin. A single root\n * record rather than in-value extensions because a component's value can be a\n * bare boolean (JSON Schema allows `true`), which no in-value key survives.\n */\nexport const OPENAPI_BASELINES_KEY = \"x-loam-baselines\";\n\n/** The feature-only explicit removal marker's key. */\nexport const OPENAPI_REMOVE_KEY = \"x-loam-remove\";\n\n/** Is this operation node a feature-only explicit removal marker? */\nexport function isRemoval(node: unknown): boolean {\n  return node !== null &&\n    typeof node === \"object\" &&\n    (node as Record<string, unknown>)[OPENAPI_REMOVE_KEY] === true;\n}\n\n/**\n * Every key that is an instruction to loam rather than part of the contract.\n * At PATH level none has any meaning — `x-loam-remove` addresses one\n * operation and `x-loam-based-on` pins one — so a path item carrying either\n * is an authoring mistake, and one that must not be published whatever else\n * is done about it. Lives HERE, in the openapi root beside the keys it names,\n * because both `merge/` and `baseline/` consume it and a value edge between\n * those two packages in either direction would be a package cycle.\n */\nexport const FEATURE_ONLY_KEYS: ReadonlySet<string> = new Set([OPENAPI_REMOVE_KEY, OPENAPI_BASELINE_KEY]);\n\n/**\n * `value` with every feature-only key removed, at ANY depth — or the value\n * unchanged (same reference) when it carries none. The component closure\n * writes values VERBATIM into the living contract, and a component holding an\n * operation shape (a `pathItems` component, a callback) can nest the markers\n * where the path-level strip never walks: `--approve` once published\n * `x-loam-remove: true` inside a living component, invisible even to\n * `validate`, whose marker sweep reads `paths` alone.\n */\nexport function withoutFeatureKeysDeep(value: unknown): unknown {\n  if (value === null || typeof value !== \"object\") return value;\n  if (Array.isArray(value)) {\n    let changed = false;\n    const out = value.map((v) => {\n      const stripped = withoutFeatureKeysDeep(v);\n      if (stripped !== v) changed = true;\n      return stripped;\n    });\n    return changed ? out : value;\n  }\n  const record = value as Record<string, unknown>;\n  let changed = false;\n  const out: Record<string, unknown> = {};\n  for (const [key, v] of Object.entries(record)) {\n    if (FEATURE_ONLY_KEYS.has(key)) {\n      changed = true;\n      continue;\n    }\n    const stripped = withoutFeatureKeysDeep(v);\n    if (stripped !== v) changed = true;\n    out[key] = stripped;\n  }\n  return changed ? out : value;\n}\n\n/** How much of the sha256 an `x-loam-based-on` carries — the length every loam digest uses. */\nexport const OPERATION_DIGEST_LENGTH = 16;\n\n/** The value shape of an `x-loam-based-on`, exactly as `operationDigest` writes it. */\nexport const OPERATION_DIGEST_RE = new RegExp(`^[0-9a-f]{${OPERATION_DIGEST_LENGTH}}$`);\n\n/**\n * Canonical JSON for a resolved YAML value: object keys sorted, arrays left in\n * order, everything else as JSON writes it.\n *\n * Key ORDER must not matter, because the merge's own idea of \"this operation\n * differs\" is `isDeepStrictEqual` (./merge/merge.ts), which ignores it. A\n * digest that disagreed with that comparison would go stale over a reordered\n * `summary`/`operationId` pair the merge itself calls identical — a false\n * collision on the one check whose worth is that it fires only for real ones.\n *\n * Exported for the ASYNCAPI axis (core/asyncapi/digest.ts), whose slot\n * digests are the same rule over different sections: one spelling of the\n * canonical form for both axes, because two spellings would eventually\n * disagree — the exact drift this module's own header names as the failure\n * mode. The import direction is asyncapi → openapi only; nothing under\n * core/openapi/ may import from core/asyncapi/, or the package graph cycles.\n */\nexport function canonicalJson(node: unknown): string {\n  if (node === null || typeof node !== \"object\") return JSON.stringify(node) ?? \"null\";\n  if (Array.isArray(node)) return `[${node.map(canonicalJson).join(\",\")}]`;\n  const entries = Object.entries(node as Record<string, unknown>)\n    .filter(([, value]) => value !== undefined)\n    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));\n  return `{${entries.map(([key, value]) => `${JSON.stringify(key)}:${canonicalJson(value)}`).join(\",\")}}`;\n}\n\n/**\n * The operation without its own baseline marker — what a digest is taken over,\n * and what the merge writes.\n *\n * A pin is a statement ABOUT a delta, never part of the operation it describes.\n * Inside the digest input, an operation's identity would depend on the pin\n * pointing at it and no baseline could ever be self-consistent; inside the\n * merged contract, a living operation would carry a pin to a version of itself\n * and the next feature's baseline would hash the previous feature's bookkeeping.\n */\nexport function withoutOperationBaseline(node: unknown): unknown {\n  if (node === null || typeof node !== \"object\" || Array.isArray(node)) return node;\n  const record = node as Record<string, unknown>;\n  if (!(OPENAPI_BASELINE_KEY in record)) return node;\n  const rest = { ...record };\n  delete rest[OPENAPI_BASELINE_KEY];\n  return rest;\n}\n\n/**\n * The identity of ANY resolved value: sha256 of its canonical form. The one\n * digest the path-item and component baselines carry — order-of-keys blind,\n * array-order sensitive, legal over scalars and booleans, exactly as the\n * operation digest always was.\n */\nexport function valueDigest(node: unknown): string {\n  return createHash(\"sha256\").update(canonicalJson(node), \"utf8\").digest(\"hex\").slice(0, OPERATION_DIGEST_LENGTH);\n}\n\n/** The identity of an operation's CONTENT: sha256 of its canonical form, pin excluded. */\nexport function operationDigest(node: unknown): string {\n  return valueDigest(withoutOperationBaseline(node));\n}\n\n/**\n * What a pin says, from digests alone — the one definition every decider\n * shares: the gate (./baseline/gate.ts) and the merge\n * (./merge/{merge,components,pin}.ts) alike. Two spellings of\n * this rule would eventually disagree about which operations a merge writes,\n * and the disagreement would be invisible until a contract came back wrong.\n *\n * Order matters: `quote` is settled against the delta's OWN content before the\n * living contract is consulted. An operation equal to its own baseline was not\n * edited, so what living holds now is nobody's business but the feature that\n * put it there.\n */\nexport function classifyBaselineDigests(\n  pin: string | undefined,\n  ownDigest: string,\n  livingDigest: string | undefined,\n): \"unpinned\" | \"quote\" | \"edit\" | \"stale\" | \"unfounded\" {\n  if (pin === undefined) return \"unpinned\";\n  if (livingDigest === undefined) return \"unfounded\";\n  if (pin === ownDigest) return \"quote\";\n  if (pin === livingDigest) return \"edit\";\n  return \"stale\";\n}\n\n/** The `x-loam-based-on` a node declares, or undefined — non-strings included, so validate can refuse them. */\nexport function operationBaselineOf(node: unknown): string | undefined {\n  if (node === null || typeof node !== \"object\" || Array.isArray(node)) return undefined;\n  const value = (node as Record<string, unknown>)[OPENAPI_BASELINE_KEY];\n  if (value === undefined) return undefined;\n  return typeof value === \"string\" ? value.trim() : String(value);\n}\n\n"]}

package/dist/core/{openapi.js → openapi/doc.js}

@@ -1,9 +1,22 @@
+/**
+ * A service's OpenAPI contract as loam reads it: which keys hold operations,
+ * what an operation is once loam's own markers are accounted for, and what the
+ * fleet will provide after a feature is applied.
+ *
+ * Split from `./digest.ts` because the two answer different questions about the
+ * same file. This one is about STRUCTURE — a path item's operation-bearing
+ * keys, an `operationId`, a removal marker — and every reader of a contract
+ * comes through here. The digest is about IDENTITY, and only the pin and the
+ * merge need it.
+ */
 import { isUtf8 } from "node:buffer";
-import { createHash } from "node:crypto";
+import { danglingRefs, failureCodesOf, responseUndescribed } from "./depth.js";
+import { operationBaselineOf, operationDigest } from "./digest.js";
 import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { parse } from "yaml";
-import { featureSpecPaths, servicePaths } from "./repo.js";
+import { featureSpecPaths } from "../repo/paths.js";
+import { locateServicePaths } from "../repo/service-target.js";
 /**
  * The path-item keys that hold operations. A path item also carries `summary`,
  * `parameters`, `servers` and vendor `x-*` extensions — an object-valued one with
@@ -13,104 +26,6 @@ import { featureSpecPaths, servicePaths } from "./repo.js";
  * of the same keys.
  */
 export const HTTP_METHODS = new Set(["get", "put", "post", "delete", "options", "head", "patch", "trace"]);
-/**
- * The baseline marker: which living version of this operation a FEATURE delta
- * was written against. Same idea as a requirement's `Based-On:` (core/spec.ts),
- * in the vendor-extension shape this axis already uses for `x-loam-remove`.
- *
- * This axis needs it MORE than the requirement axis does, because a feature's
- * openapi.yaml is a COMPLETE document rather than a patch: authors restate the
- * living contract around the slot they are changing, and the merge upserts every
- * operation the document spells. So a feature that never meant to touch
- * `refundOrder` — it merely quoted it — pushes its authoring-time copy back over
- * whatever landed in between, reverting another team's shipped change without
- * either feature overlapping the other at all. The pin is what lets the merge
- * tell a QUOTE from an EDIT: a quote equals its own baseline, and is skipped.
- */
-export const OPENAPI_BASELINE_KEY = "x-loam-based-on";
-/** How much of the sha256 an `x-loam-based-on` carries — the length every loam digest uses. */
-export const OPERATION_DIGEST_LENGTH = 16;
-/** The value shape of an `x-loam-based-on`, exactly as `operationDigest` writes it. */
-export const OPERATION_DIGEST_RE = new RegExp(`^[0-9a-f]{${OPERATION_DIGEST_LENGTH}}$`);
-/**
- * Canonical JSON for a resolved YAML value: object keys sorted, arrays left in
- * order, everything else as JSON writes it.
- *
- * Key ORDER must not matter, because the merge's own idea of "this operation
- * differs" is `isDeepStrictEqual` (core/openapi-merge.ts), which ignores it. A
- * digest that disagreed with that comparison would go stale over a reordered
- * `summary`/`operationId` pair the merge itself calls identical — a false
- * collision on the one check whose worth is that it fires only for real ones.
- */
-function canonicalJson(node) {
-    if (node === null || typeof node !== "object")
-        return JSON.stringify(node) ?? "null";
-    if (Array.isArray(node))
-        return `[${node.map(canonicalJson).join(",")}]`;
-    const entries = Object.entries(node)
-        .filter(([, value]) => value !== undefined)
-        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
-    return `{${entries.map(([key, value]) => `${JSON.stringify(key)}:${canonicalJson(value)}`).join(",")}}`;
-}
-/**
- * The operation without its own baseline marker — what a digest is taken over,
- * and what the merge writes.
- *
- * A pin is a statement ABOUT a delta, never part of the operation it describes.
- * Inside the digest input, an operation's identity would depend on the pin
- * pointing at it and no baseline could ever be self-consistent; inside the
- * merged contract, a living operation would carry a pin to a version of itself
- * and the next feature's baseline would hash the previous feature's bookkeeping.
- */
-export function withoutOperationBaseline(node) {
-    if (node === null || typeof node !== "object" || Array.isArray(node))
-        return node;
-    const record = node;
-    if (!(OPENAPI_BASELINE_KEY in record))
-        return node;
-    const rest = { ...record };
-    delete rest[OPENAPI_BASELINE_KEY];
-    return rest;
-}
-/** The identity of an operation's CONTENT: sha256 of its canonical form, pin excluded. */
-export function operationDigest(node) {
-    return createHash("sha256")
-        .update(canonicalJson(withoutOperationBaseline(node)), "utf8")
-        .digest("hex")
-        .slice(0, OPERATION_DIGEST_LENGTH);
-}
-/**
- * What a pin says, from digests alone — the one definition both the gate
- * (core/coherence.ts, which has parsed Operations) and the merge
- * (core/openapi-merge.ts, which has raw YAML trees) decide by. Two spellings of
- * this rule would eventually disagree about which operations a merge writes,
- * and the disagreement would be invisible until a contract came back wrong.
- *
- * Order matters: `quote` is settled against the delta's OWN content before the
- * living contract is consulted. An operation equal to its own baseline was not
- * edited, so what living holds now is nobody's business but the feature that
- * put it there.
- */
-export function classifyBaselineDigests(pin, ownDigest, livingDigest) {
-    if (pin === undefined)
-        return "unpinned";
-    if (livingDigest === undefined)
-        return "unfounded";
-    if (pin === ownDigest)
-        return "quote";
-    if (pin === livingDigest)
-        return "edit";
-    return "stale";
-}
-/** The `x-loam-based-on` a node declares, or undefined — non-strings included, so validate can refuse them. */
-export function operationBaselineOf(node) {
-    if (node === null || typeof node !== "object" || Array.isArray(node))
-        return undefined;
-    const value = node[OPENAPI_BASELINE_KEY];
-    if (value === undefined)
-        return undefined;
-    return typeof value === "string" ? value.trim() : String(value);
-}
 /**
  * Extract operations from an OpenAPI document by walking the parsed YAML
  * structure (paths.<path>.<method>, method filtered to the HTTP set).
@@ -149,9 +64,20 @@ export async function readOpenapi(openapiPath, context) {
     // reads the contract stays suspended.
     if (!isUtf8(bytes))
         return { ...empty(), unreadable: true, error: "file is not valid UTF-8" };
+    return openapiFromText(bytes.toString("utf8"));
+}
+/**
+ * The same read over text already in hand — the parse half of `readOpenapi`,
+ * split out so `loam diff` can read a contract fetched from a base git ref
+ * (core/diff/base-state.ts) without writing it to disk. One spelling of the
+ * walk for both entries, so a base-ref contract can never parse differently
+ * from the living file the same bytes would produce; the byte concerns
+ * (existence, UTF-8) stay with the reader that holds the bytes.
+ */
+export function openapiFromText(text) {
     let doc;
     try {
-        doc = parse(bytes.toString("utf8"));
+        doc = parse(text);
     }
     catch (e) {
         return { ...empty(), unreadable: true, error: e instanceof Error ? e.message : String(e) };
@@ -162,9 +88,12 @@ export async function readOpenapi(openapiPath, context) {
     if (doc !== null && (typeof doc !== "object" || Array.isArray(doc))) {
         return { ...empty(), unreadable: true, error: "document is not a YAML mapping" };
     }
+    // Refs are probed over the WHOLE document: a schema in `components` that
+    // `$ref`s a neighbour nobody wrote is exactly as broken as one under a path.
+    const refs = danglingRefs(doc);
     const paths = doc?.paths;
     if (!paths || typeof paths !== "object")
-        return empty();
+        return { ...empty(), danglingRefs: refs };
     const ops = [];
     const anonymousRemovals = [];
     const pathLevelRemovals = [];
@@ -196,14 +125,23 @@ export async function readOpenapi(openapiPath, context) {
                 method,
                 digest: operationDigest(op),
                 ...(basedOn === undefined ? {} : { basedOn }),
+                ...(responseUndescribed(op) ? { undescribed: true } : {}),
+                failureCodes: failureCodesOf(op),
             });
         }
     }
     const duplicateIds = [...seen].filter(([, n]) => n > 1).map(([id]) => id);
-    return { ops, duplicateIds, anonymousRemovals, pathLevelRemovals, unreadable: false };
+    return { ops, duplicateIds, anonymousRemovals, pathLevelRemovals, unreadable: false, danglingRefs: refs };
 }
 function empty() {
-    return { ops: [], duplicateIds: [], anonymousRemovals: [], pathLevelRemovals: [], unreadable: false };
+    return {
+        ops: [],
+        duplicateIds: [],
+        anonymousRemovals: [],
+        pathLevelRemovals: [],
+        unreadable: false,
+        danglingRefs: [],
+    };
 }
 /** The operations alone — for every caller whose own finding already covers the unreadable case. */
 export async function operations(openapiPath, context) {
@@ -236,7 +174,7 @@ export async function operationIds(openapiPath, context) {
  * it.
  */
 export async function serviceOperationIds(docsDir, service, featureDir, context) {
-    const ids = new Set((await operations(servicePaths(docsDir, service).openapi, context)).filter((op) => !op.remove).map((op) => op.id));
+    const ids = new Set((await operations((await locateServicePaths(docsDir, service, context)).openapi, context)).filter((op) => !op.remove).map((op) => op.id));
     // Absence is `undefined`, the shape the optional parameter declares. The
     // truthiness test also read "" as "no feature", which is a caller mistake
     // worth surfacing rather than answering as though the feature carried no
@@ -252,4 +190,4 @@ export async function serviceOperationIds(docsDir, service, featureDir, context)
     }
     return [...ids];
 }
-//# sourceMappingURL=openapi.js.map
+//# sourceMappingURL=doc.js.map

package/dist/core/openapi/doc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc.js","sourceRoot":"","sources":["../../../src/core/openapi/doc.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * A service's OpenAPI contract as loam reads it: which keys hold operations,\n * what an operation is once loam's own markers are accounted for, and what the\n * fleet will provide after a feature is applied.\n *\n * Split from `./digest.ts` because the two answer different questions about the\n * same file. This one is about STRUCTURE — a path item's operation-bearing\n * keys, an `operationId`, a removal marker — and every reader of a contract\n * comes through here. The digest is about IDENTITY, and only the pin and the\n * merge need it.\n */\nimport { isUtf8 } from \"node:buffer\";\nimport { danglingRefs, failureCodesOf, responseUndescribed } from \"./depth.js\";\nimport { operationBaselineOf, operationDigest } from \"./digest.js\";\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { parse } from \"yaml\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport type { PathableService } from \"../kernel/ids/service.js\";\nimport { featureSpecPaths } from \"../repo/paths.js\";\nimport { locateServicePaths } from \"../repo/service-target.js\";\nimport type { DocsDir, FeatureDir } from \"../kernel/ids/dirs.js\";\n\n/**\n * The path-item keys that hold operations. A path item also carries `summary`,\n * `parameters`, `servers` and vendor `x-*` extensions — an object-valued one with\n * an `operationId` inside (x-legacy and friends) is not an operation, and a\n * phantom id from it would make a broken contract look \"available\" to the\n * op-exists checks. Shared with archive's merge, which asks the same question\n * of the same keys.\n */\nexport const HTTP_METHODS = new Set([\"get\", \"put\", \"post\", \"delete\", \"options\", \"head\", \"patch\", \"trace\"]);\n\n/** One operation as the reader sees it, including loam's feature-only removal marker. */\nexport interface Operation {\n  id: string;\n  /**\n   * The standard per-operation OpenAPI `deprecated` flag — lifecycle\n   * visibility, the documented first step of retiring an op.\n   */\n  deprecated: boolean;\n  /**\n   * `x-loam-remove: true` asks a FEATURE delta to remove this exact operation\n   * on archive. The marker is never a callable operation and is illegal in a\n   * living contract.\n   */\n  remove: boolean;\n  /** Exact slot the marker/upsert addresses; removal is deliberately path+method-safe. */\n  path: string;\n  method: string;\n  /**\n   * `operationDigest` of this operation as it stands in ITS OWN document —\n   * computed here so every caller compares content the one way the merge does.\n   */\n  digest: string;\n  /**\n   * The living version this operation was written against, from\n   * `x-loam-based-on`. Feature deltas only: a living contract never carries one\n   * (the merge strips it), and an adopted contract never had one.\n   */\n  basedOn?: string;\n  /**\n   * Present when no response declares content with a schema while at least one\n   * should carry a body (`depth.ts`). Set only when true, so the many callers\n   * that compare operations structurally never see the field on a described\n   * contract.\n   */\n  undescribed?: true;\n  /**\n   * Declared non-2xx response codes, in document order — the refusals this\n   * operation promises. `default` and any `4XX`/`5XX` wildcard are excluded:\n   * neither names a case a scenario could be written for.\n   *\n   * The contract is the only place in the corpus that enumerates what an\n   * operation REFUSES, and until this was read nothing joined those refusals to\n   * anything. `api.ungoverned` grades whole operations against requirements,\n   * so an operation documented by its happy path alone — one requirement, one\n   * scenario, twelve declared failure codes — passed every check loam had.\n   */\n  failureCodes: string[];\n}\n\n/** A `x-loam-remove: true` marker with no usable operationId — a slot named but no operation named. */\nexport interface AnonymousRemoval {\n  path: string;\n  method: string;\n}\n\n/** The parse of one OpenAPI document: its operations, and whether the file could be read at all. */\nexport interface OpenapiDoc {\n  ops: Operation[];\n  /**\n   * operationIds this document defines in more than one (path, method) slot.\n   * A LIVING contract with two slots claiming one id is ambiguous to every\n   * check that joins on the id — a requirement's `Operations:` line, an edge's\n   * `metadata { op }`, a removal marker — and the join silently picks one.\n   */\n  duplicateIds: string[];\n  /**\n   * Removal markers the operation reader cannot name. They are invisible to\n   * every id-keyed check, so a delta carrying one used to archive cleanly and\n   * write `x-loam-remove: true` straight into a living contract.\n   */\n  anonymousRemovals: AnonymousRemoval[];\n  /**\n   * Paths carrying `x-loam-remove: true` at PATH level, beside the methods\n   * rather than inside one.\n   *\n   * Not an operation, so nothing keyed by (path, method) could see it — and this\n   * reader is method-keyed like the merge was. A marker written there addressed\n   * no operation, so archive copied it into the living contract verbatim, where\n   * it was invisible to `openapi.remove-marker-living` for the same reason and\n   * kept the empty-path cleanup from ever firing. Reported as its own list\n   * because the answer differs by document: in a FEATURE delta it is an\n   * authoring mistake, in a LIVING contract it is a marker that must never have\n   * been published.\n   */\n  pathLevelRemovals: string[];\n  /**\n   * True when the file EXISTS but cannot be read as an OpenAPI document —\n   * broken YAML, or a document that is not a mapping. A missing file is not\n   * unreadable (absence is `service.no-openapi`'s question), and an empty one\n   * parses to null and honestly defines nothing.\n   */\n  unreadable: boolean;\n  /** The parser's own message, when there is one to quote back. */\n  error?: string;\n  /** Internal `#/` refs that resolve to nothing in this document (`depth.ts`). */\n  danglingRefs: string[];\n}\n\n/**\n * Extract operations from an OpenAPI document by walking the parsed YAML\n * structure (paths.<path>.<method>, method filtered to the HTTP set).\n * Structure-aware on purpose: a regex scan both drops legal ids (kebab-case,\n * dotted) and picks up phantom ids from description text. Each operation\n * carries its id and its `deprecated: true` flag (exactly `true` counts —\n * strings and truthy noise do not). `ops` is the defined set, keyed by the\n * (path, method) SLOT — not by operationId.\n *\n * Keying by id used to drop the second slot claiming a name, which made the\n * single most common contract edit invisible: relocating an endpoint is a\n * removal marker at the old slot plus an upsert at the new one, the SAME\n * operationId twice. Whichever came second in document order vanished, so\n * either the marker addressed a slot loam could not see (`remove-target-missing`\n * on a perfectly good delta) or the new definition did. Two slots claiming one\n * id in a LIVING contract is a real ambiguity rather than a merge failure, so\n * it rides out as `duplicateIds` for the caller to grade.\n *\n * An unreadable document yields [] ops PLUS the `unreadable` flag. Parsers\n * never diagnose — the policy of every reader here — so the failure travels as\n * a flag for validate to grade (`openapi.invalid`). Swallowing it into a bare\n * [] made a broken contract indistinguishable from an EMPTY one, and the spine\n * check then reported every inbound edge broken (`spine.op-undefined`) — a\n * false diagnosis pointing at the landscape when the truth was this file.\n */\nexport async function readOpenapi(openapiPath: string, context?: FleetContext): Promise<OpenapiDoc> {\n  if (context !== undefined) return context.readOpenapi(openapiPath);\n  if (!existsSync(openapiPath)) return empty();\n  const bytes = await readFile(openapiPath);\n  // A contract whose bytes are not UTF-8 is as unreadable as broken YAML, and\n  // for a worse reason: `toString(\"utf8\")` would substitute U+FFFD and hand the\n  // parser a document nobody wrote. It travels as `unreadable` so validate\n  // grades it `openapi.invalid` — the file is the error, and every check that\n  // reads the contract stays suspended.\n  if (!isUtf8(bytes)) return { ...empty(), unreadable: true, error: \"file is not valid UTF-8\" };\n  return openapiFromText(bytes.toString(\"utf8\"));\n}\n\n/**\n * The same read over text already in hand — the parse half of `readOpenapi`,\n * split out so `loam diff` can read a contract fetched from a base git ref\n * (core/diff/base-state.ts) without writing it to disk. One spelling of the\n * walk for both entries, so a base-ref contract can never parse differently\n * from the living file the same bytes would produce; the byte concerns\n * (existence, UTF-8) stay with the reader that holds the bytes.\n */\nexport function openapiFromText(text: string): OpenapiDoc {\n  let doc: unknown;\n  try {\n    doc = parse(text);\n  } catch (e) {\n    return { ...empty(), unreadable: true, error: e instanceof Error ? e.message : String(e) };\n  }\n  // A scalar or sequence document is as unreadable as broken YAML: there is no\n  // mapping to look `paths` up in, so nothing can be concluded from it. null\n  // (an empty file) stays readable — it defines nothing, and says so honestly.\n  if (doc !== null && (typeof doc !== \"object\" || Array.isArray(doc))) {\n    return { ...empty(), unreadable: true, error: \"document is not a YAML mapping\" };\n  }\n  // Refs are probed over the WHOLE document: a schema in `components` that\n  // `$ref`s a neighbour nobody wrote is exactly as broken as one under a path.\n  const refs = danglingRefs(doc);\n  const paths = (doc as { paths?: unknown } | null)?.paths;\n  if (!paths || typeof paths !== \"object\") return { ...empty(), danglingRefs: refs };\n  const ops: Operation[] = [];\n  const anonymousRemovals: AnonymousRemoval[] = [];\n  const pathLevelRemovals: string[] = [];\n  const seen = new Map<string, number>();\n  for (const [path, item] of Object.entries(paths as Record<string, unknown>)) {\n    if (!item || typeof item !== \"object\") continue;\n    if ((item as Record<string, unknown>)[\"x-loam-remove\"] === true) pathLevelRemovals.push(path);\n    for (const [method, op] of Object.entries(item as Record<string, unknown>)) {\n      if (!HTTP_METHODS.has(method)) continue;\n      if (!op || typeof op !== \"object\") continue;\n      const id = (op as Record<string, unknown>)[\"operationId\"];\n      const remove = (op as Record<string, unknown>)[\"x-loam-remove\"] === true;\n      if (typeof id !== \"string\" || id.length === 0) {\n        if (remove) anonymousRemovals.push({ path, method });\n        continue;\n      }\n      seen.set(id, (seen.get(id) ?? 0) + 1);\n      const basedOn = operationBaselineOf(op);\n      ops.push({\n        id,\n        deprecated: (op as Record<string, unknown>)[\"deprecated\"] === true,\n        remove,\n        path,\n        method,\n        digest: operationDigest(op),\n        ...(basedOn === undefined ? {} : { basedOn }),\n        ...(responseUndescribed(op) ? { undescribed: true as const } : {}),\n        failureCodes: failureCodesOf(op),\n      });\n    }\n  }\n  const duplicateIds = [...seen].filter(([, n]) => n > 1).map(([id]) => id);\n  return { ops, duplicateIds, anonymousRemovals, pathLevelRemovals, unreadable: false, danglingRefs: refs };\n}\n\nfunction empty(): OpenapiDoc {\n  return {\n    ops: [],\n    duplicateIds: [],\n    anonymousRemovals: [],\n    pathLevelRemovals: [],\n    unreadable: false,\n    danglingRefs: [],\n  };\n}\n\n/** The operations alone — for every caller whose own finding already covers the unreadable case. */\nexport async function operations(openapiPath: string, context?: FleetContext): Promise<Operation[]> {\n  return (await readOpenapi(openapiPath, context)).ops;\n}\n\n/** The operationIds alone — `operations` for every caller that asks only \"does it exist\". */\nexport async function operationIds(openapiPath: string, context?: FleetContext): Promise<string[]> {\n  return (await operations(openapiPath, context)).map((o) => o.id);\n}\n\n/**\n * The operationIds a service will provide after a feature is applied: living\n * operations, plus feature upserts, minus explicit feature removals.\n *\n * Removals are applied BEFORE upserts, which is what makes the answer\n * independent of the order the feature's document happens to spell them in.\n * Interleaving them one operation at a time meant a relocation — the same id\n * removed from `/old` and defined on `/new` — answered \"defined\" or \"gone\"\n * depending on which path sorted first in the YAML, and the requirement\n * governing it was reported undefined (`spec-api.op-undefined`) on exactly one\n * of the two spellings of the same change.\n *\n * A context is threaded into the READS and never asked for the answer. It used\n * to own a second copy of this function, and that copy interleaved removals\n * with upserts — the exact bug the paragraph above describes as fixed. So the\n * commands that pass a context (`validate`, `status`) and the one that does not\n * (`archive`) disagreed about whether a relocated operation still existed, and\n * `spec-api.op-undefined` — an error that gates archive — fired or not\n * depending on which path key the author happened to type first. Memoising is\n * the context's job; the ordering rule is this function's, and there is one of\n * it.\n */\nexport async function serviceOperationIds(\n  docsDir: DocsDir,\n  service: PathableService,\n  featureDir?: FeatureDir,\n  context?: FleetContext,\n): Promise<string[]> {\n  const ids = new Set(\n    (await operations((await locateServicePaths(docsDir, service, context)).openapi, context)).filter((op) => !op.remove).map((op) => op.id),\n  );\n  // Absence is `undefined`, the shape the optional parameter declares. The\n  // truthiness test also read \"\" as \"no feature\", which is a caller mistake\n  // worth surfacing rather than answering as though the feature carried no\n  // contract delta.\n  if (featureDir !== undefined) {\n    const featOps = await operations(featureSpecPaths(featureDir, service).openapi, context);\n    for (const op of featOps) if (op.remove) ids.delete(op.id);\n    for (const op of featOps) if (!op.remove) ids.add(op.id);\n  }\n  return [...ids];\n}\n\n"]}