@ybotok/loam 0.1.0-beta.1 → 0.1.0-beta.2

package/dist/core/openapi.js

@@ -224,13 +224,25 @@ export async function operationIds(openapiPath, context) {
  * depending on which path sorted first in the YAML, and the requirement
  * governing it was reported undefined (`spec-api.op-undefined`) on exactly one
  * of the two spellings of the same change.
+ *
+ * A context is threaded into the READS and never asked for the answer. It used
+ * to own a second copy of this function, and that copy interleaved removals
+ * with upserts — the exact bug the paragraph above describes as fixed. So the
+ * commands that pass a context (`validate`, `status`) and the one that does not
+ * (`archive`) disagreed about whether a relocated operation still existed, and
+ * `spec-api.op-undefined` — an error that gates archive — fired or not
+ * depending on which path key the author happened to type first. Memoising is
+ * the context's job; the ordering rule is this function's, and there is one of
+ * it.
  */
 export async function serviceOperationIds(docsDir, service, featureDir, context) {
-    if (context !== undefined)
-        return context.serviceOperationIds(docsDir, service, featureDir);
-    const ids = new Set((await operations(servicePaths(docsDir, service).openapi)).filter((op) => !op.remove).map((op) => op.id));
-    if (featureDir) {
-        const featOps = await operations(featureSpecPaths(featureDir, service).openapi);
+    const ids = new Set((await operations(servicePaths(docsDir, service).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
+    // contract delta.
+    if (featureDir !== undefined) {
+        const featOps = await operations(featureSpecPaths(featureDir, service).openapi, context);
         for (const op of featOps)
             if (op.remove)
                 ids.delete(op.id);

package/dist/core/openapi.js.map

@@ -1 +1 @@
-{"version":3,"file":"openapi.js","sourceRoot":"","sources":["../../src/core/openapi.ts"],"names":[],"mappings":"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","sourcesContent":["import { isUtf8 } from \"node:buffer\";\nimport { createHash } from \"node:crypto\";\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { parse } from \"yaml\";\nimport type { FleetContext } from \"./fleet-context.js\";\nimport { featureSpecPaths, servicePaths } from \"./repo.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/**\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/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/** 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` (core/openapi-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 */\nfunction 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/** The identity of an operation's CONTENT: sha256 of its canonical form, pin excluded. */\nexport function operationDigest(node: unknown): string {\n  return createHash(\"sha256\")\n    .update(canonicalJson(withoutOperationBaseline(node)), \"utf8\")\n    .digest(\"hex\")\n    .slice(0, OPERATION_DIGEST_LENGTH);\n}\n\n/**\n * What a pin says, from digests alone — the one definition both the gate\n * (core/coherence.ts, which has parsed Operations) and the merge\n * (core/openapi-merge.ts, which has raw YAML trees) decide by. 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/** 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\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}\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  let doc: unknown;\n  try {\n    doc = parse(bytes.toString(\"utf8\"));\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  const paths = (doc as { paths?: unknown } | null)?.paths;\n  if (!paths || typeof paths !== \"object\") return empty();\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      });\n    }\n  }\n  const duplicateIds = [...seen].filter(([, n]) => n > 1).map(([id]) => id);\n  return { ops, duplicateIds, anonymousRemovals, pathLevelRemovals, unreadable: false };\n}\n\nfunction empty(): OpenapiDoc {\n  return { ops: [], duplicateIds: [], anonymousRemovals: [], pathLevelRemovals: [], unreadable: false };\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 */\nexport async function serviceOperationIds(\n  docsDir: string,\n  service: string,\n  featureDir?: string,\n  context?: FleetContext,\n): Promise<string[]> {\n  if (context !== undefined) return context.serviceOperationIds(docsDir, service, featureDir);\n  const ids = new Set(\n    (await operations(servicePaths(docsDir, service).openapi)).filter((op) => !op.remove).map((op) => op.id),\n  );\n  if (featureDir) {\n    const featOps = await operations(featureSpecPaths(featureDir, service).openapi);\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"]}
+{"version":3,"file":"openapi.js","sourceRoot":"","sources":["../../src/core/openapi.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,KAAK,EAAE,MAAM,MAAM,CAAC;AAE7B,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAE3D;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;AAE3G;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,iBAAiB,CAAC;AAEtD,+FAA+F;AAC/F,MAAM,CAAC,MAAM,uBAAuB,GAAG,EAAE,CAAC;AAE1C,uFAAuF;AACvF,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,MAAM,CAAC,aAAa,uBAAuB,IAAI,CAAC,CAAC;AAExF;;;;;;;;;GASG;AACH,SAAS,aAAa,CAAC,IAAa;IAClC,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC;IACrF,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IACzE,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,IAA+B,CAAC;SAC5D,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,CAAC;SAC1C,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpD,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;AAC1G,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,wBAAwB,CAAC,IAAa;IACpD,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAClF,MAAM,MAAM,GAAG,IAA+B,CAAC;IAC/C,IAAI,CAAC,CAAC,oBAAoB,IAAI,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IACnD,MAAM,IAAI,GAAG,EAAE,GAAG,MAAM,EAAE,CAAC;IAC3B,OAAO,IAAI,CAAC,oBAAoB,CAAC,CAAC;IAClC,OAAO,IAAI,CAAC;AACd,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,eAAe,CAAC,IAAa;IAC3C,OAAO,UAAU,CAAC,QAAQ,CAAC;SACxB,MAAM,CAAC,aAAa,CAAC,wBAAwB,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC;SAC7D,MAAM,CAAC,KAAK,CAAC;SACb,KAAK,CAAC,CAAC,EAAE,uBAAuB,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,uBAAuB,CACrC,GAAuB,EACvB,SAAiB,EACjB,YAAgC;IAEhC,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,UAAU,CAAC;IACzC,IAAI,YAAY,KAAK,SAAS;QAAE,OAAO,WAAW,CAAC;IACnD,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,OAAO,CAAC;IACtC,IAAI,GAAG,KAAK,YAAY;QAAE,OAAO,MAAM,CAAC;IACxC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,+GAA+G;AAC/G,MAAM,UAAU,mBAAmB,CAAC,IAAa;IAC/C,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IACvF,MAAM,KAAK,GAAI,IAAgC,CAAC,oBAAoB,CAAC,CAAC;IACtE,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1C,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAClE,CAAC;AA+ED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,WAAmB,EAAE,OAAsB;IAC3E,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,OAAO,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;IACnE,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC;QAAE,OAAO,KAAK,EAAE,CAAC;IAC7C,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,WAAW,CAAC,CAAC;IAC1C,4EAA4E;IAC5E,8EAA8E;IAC9E,yEAAyE;IACzE,4EAA4E;IAC5E,sCAAsC;IACtC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,GAAG,KAAK,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK,EAAE,yBAAyB,EAAE,CAAC;IAC9F,IAAI,GAAY,CAAC;IACjB,IAAI,CAAC;QACH,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;IACtC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,EAAE,GAAG,KAAK,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7F,CAAC;IACD,6EAA6E;IAC7E,2EAA2E;IAC3E,6EAA6E;IAC7E,IAAI,GAAG,KAAK,IAAI,IAAI,CAAC,OAAO,GAAG,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;QACpE,OAAO,EAAE,GAAG,KAAK,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK,EAAE,gCAAgC,EAAE,CAAC;IACnF,CAAC;IACD,MAAM,KAAK,GAAI,GAAkC,EAAE,KAAK,CAAC;IACzD,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,EAAE,CAAC;IACxD,MAAM,GAAG,GAAgB,EAAE,CAAC;IAC5B,MAAM,iBAAiB,GAAuB,EAAE,CAAC;IACjD,MAAM,iBAAiB,GAAa,EAAE,CAAC;IACvC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAkB,CAAC;IACvC,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,EAAE,CAAC;QAC5E,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,SAAS;QAChD,IAAK,IAAgC,CAAC,eAAe,CAAC,KAAK,IAAI;YAAE,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC9F,KAAK,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAA+B,CAAC,EAAE,CAAC;YAC3E,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC;gBAAE,SAAS;YACxC,IAAI,CAAC,EAAE,IAAI,OAAO,EAAE,KAAK,QAAQ;gBAAE,SAAS;YAC5C,MAAM,EAAE,GAAI,EAA8B,CAAC,aAAa,CAAC,CAAC;YAC1D,MAAM,MAAM,GAAI,EAA8B,CAAC,eAAe,CAAC,KAAK,IAAI,CAAC;YACzE,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC9C,IAAI,MAAM;oBAAE,iBAAiB,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;gBACrD,SAAS;YACX,CAAC;YACD,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YACtC,MAAM,OAAO,GAAG,mBAAmB,CAAC,EAAE,CAAC,CAAC;YACxC,GAAG,CAAC,IAAI,CAAC;gBACP,EAAE;gBACF,UAAU,EAAG,EAA8B,CAAC,YAAY,CAAC,KAAK,IAAI;gBAClE,MAAM;gBACN,IAAI;gBACJ,MAAM;gBACN,MAAM,EAAE,eAAe,CAAC,EAAE,CAAC;gBAC3B,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC;aAC9C,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,MAAM,YAAY,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;IAC1E,OAAO,EAAE,GAAG,EAAE,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;AACxF,CAAC;AAED,SAAS,KAAK;IACZ,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,YAAY,EAAE,EAAE,EAAE,iBAAiB,EAAE,EAAE,EAAE,iBAAiB,EAAE,EAAE,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;AACxG,CAAC;AAED,oGAAoG;AACpG,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,WAAmB,EAAE,OAAsB;IAC1E,OAAO,CAAC,MAAM,WAAW,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;AACvD,CAAC;AAED,6FAA6F;AAC7F,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,WAAmB,EAAE,OAAsB;IAC5E,OAAO,CAAC,MAAM,UAAU,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AACnE,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,OAAe,EACf,OAAe,EACf,UAAmB,EACnB,OAAsB;IAEtB,MAAM,GAAG,GAAG,IAAI,GAAG,CACjB,CAAC,MAAM,UAAU,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,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,CAClH,CAAC;IACF,yEAAyE;IACzE,0EAA0E;IAC1E,yEAAyE;IACzE,kBAAkB;IAClB,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,MAAM,OAAO,GAAG,MAAM,UAAU,CAAC,gBAAgB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACzF,KAAK,MAAM,EAAE,IAAI,OAAO;YAAE,IAAI,EAAE,CAAC,MAAM;gBAAE,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QAC3D,KAAK,MAAM,EAAE,IAAI,OAAO;YAAE,IAAI,CAAC,EAAE,CAAC,MAAM;gBAAE,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC;AAClB,CAAC","sourcesContent":["import { isUtf8 } from \"node:buffer\";\nimport { createHash } from \"node:crypto\";\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { parse } from \"yaml\";\nimport type { FleetContext } from \"./fleet-context.js\";\nimport { featureSpecPaths, servicePaths } from \"./repo.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/**\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/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/** 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` (core/openapi-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 */\nfunction 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/** The identity of an operation's CONTENT: sha256 of its canonical form, pin excluded. */\nexport function operationDigest(node: unknown): string {\n  return createHash(\"sha256\")\n    .update(canonicalJson(withoutOperationBaseline(node)), \"utf8\")\n    .digest(\"hex\")\n    .slice(0, OPERATION_DIGEST_LENGTH);\n}\n\n/**\n * What a pin says, from digests alone — the one definition both the gate\n * (core/coherence.ts, which has parsed Operations) and the merge\n * (core/openapi-merge.ts, which has raw YAML trees) decide by. 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/** 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\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}\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  let doc: unknown;\n  try {\n    doc = parse(bytes.toString(\"utf8\"));\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  const paths = (doc as { paths?: unknown } | null)?.paths;\n  if (!paths || typeof paths !== \"object\") return empty();\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      });\n    }\n  }\n  const duplicateIds = [...seen].filter(([, n]) => n > 1).map(([id]) => id);\n  return { ops, duplicateIds, anonymousRemovals, pathLevelRemovals, unreadable: false };\n}\n\nfunction empty(): OpenapiDoc {\n  return { ops: [], duplicateIds: [], anonymousRemovals: [], pathLevelRemovals: [], unreadable: false };\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: string,\n  service: string,\n  featureDir?: string,\n  context?: FleetContext,\n): Promise<string[]> {\n  const ids = new Set(\n    (await operations(servicePaths(docsDir, service).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"]}

package/dist/core/openspec-inventory.js

@@ -5,6 +5,8 @@ import { existsSync } from "node:fs";
 import { lstat, readFile, readdir, realpath, stat } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { parse as parseYaml } from "yaml";
+import { asRecord, dictionary, ownValue } from "./records.js";
+import { FEATURE_ID_RULE, isFeatureId } from "./ids.js";
 import { compareIds } from "./repo.js";
 import { isRequirementsHeading, parseRequirements, REQUIREMENT_ID_RE, requirementIdDeclarations, requirementIdProblems, sectionHeadings, } from "./spec.js";
 /** Released behavior and the newer upstream snapshot used as a compatibility canary. */
@@ -19,6 +21,32 @@ export const OPENSPEC_BASELINES = Object.freeze({
         commit: "45cca5db6137ed209117cc70510eb3e057fb981b",
     }),
 });
+/**
+ * The dispositions as values, not only as a type, because a mapping file names
+ * one as a plain string and the parse boundary has to be able to ask whether
+ * that string is one of these. A hand-written second spelling of the same list
+ * is how a disposition added here would go on being unrecognised where it is
+ * read from somebody else's YAML.
+ */
+export const OPENSPEC_ARTIFACT_DISPOSITIONS = [
+    "translate-project-context",
+    "record-external-planning-root",
+    "remove-after-cutover",
+    "map-requirements",
+    "review-as-service-adr",
+    "translate-change-metadata",
+    "convert-to-intent",
+    "preserve-as-legacy-checklist",
+    "review-as-feature-adr",
+    "map-delta",
+    "review-custom-workflow",
+    "retain-read-only",
+    "manual-review",
+];
+/** Whether an authored string names a disposition this codebase actually defines. */
+export function isOpenSpecArtifactDisposition(value) {
+    return OPENSPEC_ARTIFACT_DISPOSITIONS.includes(value);
+}
 export class OpenSpecRootError extends Error {
     constructor(message) {
         super(message);
@@ -166,16 +194,13 @@ async function isSymbolicLink(path) {
         return false;
     }
 }
-function asRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value)
-        ? value
-        : null;
-}
-function dictionary() {
-    return Object.create(null);
-}
-function ownValue(record, key) {
-    return Object.prototype.hasOwnProperty.call(record, key) ? record[key] : undefined;
+/**
+ * `Array.isArray` narrows an `unknown` to `any[]`, which is how a checked
+ * element type went on being asserted back in a line later. Deciding both
+ * halves in one predicate makes the narrowing carry the check.
+ */
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string");
 }
 async function yamlRecord(path) {
     const parsed = parseYaml(await readFile(path, "utf8"));
@@ -338,6 +363,14 @@ function inspectChangeShape(path, raw, scope, renames, unsupported) {
         issue(unsupported, scope, "openspec.change-requirements-outside-delta-sections", path, `${stranded.length} requirement(s) would be stranded outside delta sections.`);
     }
 }
+/**
+ * The parsed requirements come back with the counts because both callers wanted
+ * them and each opened the file a second time to get its own copy — two reads
+ * of the same bytes per spec.md, and two readings of it: the counts came from
+ * this parse while the requirement names, and the living corpus every rename is
+ * resolved against, came from the other. A file edited mid-audit could be
+ * counted from one of them and routed from the other.
+ */
 async function inspectSpecFile(root, absolute, kind, scope, mapping, renamed, unsupported) {
     const path = portable(root, absolute);
     const raw = await readFile(absolute, "utf8");
@@ -364,7 +397,7 @@ async function inspectSpecFile(root, absolute, kind, scope, mapping, renamed, un
         renamed.push(...usages);
         inspectChangeShape(path, raw, changeScope, usages, unsupported);
     }
-    return { path, counts };
+    return { path, counts, requirements };
 }
 async function inspectConfig(root, unsupported) {
     const path = join(root, "config.yaml");
@@ -438,8 +471,8 @@ async function inspectChangeMetadata(root, dir, scope, fallbackSchema, unsupport
             invalid("goal must be a non-empty string when present.");
         }
         if ("affected_areas" in metadata
-            && (!Array.isArray(metadata.affected_areas)
-                || metadata.affected_areas.some((value) => typeof value !== "string" || value.length === 0))) {
+            && (!isStringArray(metadata.affected_areas)
+                || metadata.affected_areas.some((value) => value.length === 0))) {
             invalid("affected_areas must be an array of non-empty strings when present.");
         }
         if ("initiative" in metadata) {
@@ -549,22 +582,19 @@ function validArtifactSchema(document) {
             || typeof artifact.template !== "string"
             || artifact.template.length === 0
             || ("instruction" in artifact && typeof artifact.instruction !== "string")
-            || ("requires" in artifact
-                && (!Array.isArray(artifact.requires)
-                    || artifact.requires.some((dependency) => typeof dependency !== "string")))) {
+            || ("requires" in artifact && !isStringArray(artifact.requires))) {
             return false;
         }
         artifacts.push({
             id: artifact.id,
-            requires: Array.isArray(artifact.requires) ? artifact.requires : [],
+            requires: isStringArray(artifact.requires) ? artifact.requires : [],
         });
     }
     if ("apply" in document) {
         const apply = asRecord(document.apply);
         if (apply === null
-            || !Array.isArray(apply.requires)
+            || !isStringArray(apply.requires)
             || apply.requires.length === 0
-            || apply.requires.some((dependency) => typeof dependency !== "string")
             || ("tracks" in apply && apply.tracks !== null && typeof apply.tracks !== "string")
             || ("instruction" in apply && typeof apply.instruction !== "string")) {
             return false;
@@ -630,11 +660,10 @@ async function inventoryChanges(root, base, ids, scope, fallbackSchema, mapping,
         for (const specFile of specFiles) {
             const inspected = await inspectSpecFile(root, specFile, "change", scope, mapping, renamed, unsupported);
             files.push(inspected.path);
-            const parsed = parseRequirements(await readFile(specFile, "utf8"));
             specs.push({
                 capability: portable(specRoot, dirname(specFile)),
                 path: inspected.path,
-                requirementNames: [...new Set(parsed.filter((item) => item.kind !== "BASE").map((item) => item.name))].sort(compareIds),
+                requirementNames: [...new Set(inspected.requirements.filter((item) => item.kind !== "BASE").map((item) => item.name))].sort(compareIds),
                 ...inspected.counts,
             });
             addCounts(counts, inspected.counts);
@@ -729,7 +758,6 @@ function artifactFor(root, absolute) {
 function sortIssues(issues) {
     issues.sort((a, b) => compareIds(a.path, b.path) || compareIds(a.code, b.code));
 }
-const LOAM_FEATURE_ID_RE = /^[A-Za-z][A-Za-z0-9]*-\d+$/;
 function titleFromChangeId(id) {
     const words = id.split(/[-_]+/).filter(Boolean);
     const text = words.join(" ");
@@ -781,7 +809,13 @@ export function createOpenSpecMappingSkeleton(inventory) {
                 from: rename.from,
                 to: rename.to,
                 existingRequirementId: rename.existingRequirementId,
-                requirementId: rename.status === "mapped" ? rename.existingRequirementId : null,
+                // The identity the inventory settled on, which is the field the
+                // skeleton is asking a human to fill in. `existingRequirementId` is
+                // the living source's own id and happens to equal it on the only path
+                // that reaches here today — but a caller that audits WITH a mapping
+                // would have a settled id and no existing one, and the skeleton would
+                // hand that decision back as unmade.
+                requirementId: rename.requirementId,
             }])),
         artifacts: Object.fromEntries(inventory.artifactDecisions.map((decision) => [
             decision.path,
@@ -859,7 +893,7 @@ export async function inventoryOpenSpec(input, options = {}) {
     for (const specFile of livingFiles) {
         const id = portable(specsRoot, dirname(specFile));
         const inspected = await inspectSpecFile(root, specFile, "living", null, mapping, renamed, blockers);
-        livingRequirements.set(id, parseRequirements(await readFile(specFile, "utf8")));
+        livingRequirements.set(id, inspected.requirements);
         const capability = { id, files: [inspected.path], ...inspected.counts };
         capabilities.push(capability);
         addCounts(livingCounts, inspected.counts);
@@ -1105,11 +1139,11 @@ export async function inventoryOpenSpec(input, options = {}) {
                 message: `Active change '${change.id}' needs a non-empty title.`,
             });
         }
-        if (feature !== null && !LOAM_FEATURE_ID_RE.test(feature)) {
+        if (feature !== null && !isFeatureId(feature)) {
             mappingIssues.push({
                 code: "mapping.feature-id-invalid",
                 key: change.id,
-                message: `Active change '${change.id}' maps to invalid loam feature id '${feature}'. Expected <word>-<number>.`,
+                message: `Active change '${change.id}' maps to invalid loam feature id '${feature}'. ${FEATURE_ID_RULE}`,
             });
         }
         return {
@@ -1123,7 +1157,7 @@ export async function inventoryOpenSpec(input, options = {}) {
     });
     const featureOwners = new Map();
     for (const decision of changeDecisions) {
-        if (decision.feature === null || !LOAM_FEATURE_ID_RE.test(decision.feature))
+        if (decision.feature === null || !isFeatureId(decision.feature))
             continue;
         const key = decision.feature.toLowerCase();
         const owners = featureOwners.get(key) ?? [];
@@ -1313,6 +1347,9 @@ export async function inventoryOpenSpec(input, options = {}) {
         };
     });
     const artifactPaths = new Set(artifactDecisions.map((decision) => decision.path));
+    // Sets of plain strings: the question being asked is "is this authored value
+    // one of the ones this kind accepts", and a set of the union could not be
+    // asked it without an assertion putting the answer back where it started.
     const dispositionsByKind = {
         proposal: new Set(["convert-to-intent", "retain-read-only", "manual-review"]),
         tasks: new Set(["preserve-as-legacy-checklist", "retain-read-only", "manual-review"]),