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

package/dist/core/mcp/tools.js

@@ -19,6 +19,12 @@
  * run that has not happened yet), so an MCP-only host that could not reach
  * them could not fetch the protocol its own generated skill points at.
  *
+ * `adopt` is here for the same reason one step later: it writes nothing — it
+ * emits the brief an agent then writes a baseline from — and the loam-adopt
+ * protocol an MCP-only host fetches through `loam_instructions` opens by
+ * running it. Without the tool that host could read the protocol and never
+ * receive the brief the protocol is about.
+ *
  * Every table entry mirrors a real registration in `src/commands/` — same
  * positionals, same flags, same spellings — so the contract an MCP client
  * sees is the CLI contract, not a second one. `--json` is appended by
@@ -102,9 +108,10 @@ export const MCP_TOOLS = [
         name: "loam_list",
         command: "list",
         description: "List the services and features in the docs repo. " +
-            "CLI equivalent: loam list [section] [--archived] [--needs-work] [--review-order] [--subsystem <name>] [--owners <path>] --json",
+            "CLI equivalent: loam list [section] [name] [--archived] [--needs-work] [--review-order] [--subsystem <name>] [--owners <path>] --json",
         positionals: [
-            { property: "section", required: false, variadic: false, description: "services | features | capabilities (default: services + features)" },
+            { property: "section", required: false, variadic: false, description: "services | features | capabilities | glossary | suites (default: services + features)" },
+            { property: "name", required: false, variadic: false, description: "suites only: the one suite to show" },
         ],
         flags: [
             { property: "archived", flag: "--archived", kind: "boolean", description: "include archived features" },
@@ -136,6 +143,19 @@ export const MCP_TOOLS = [
         ],
         flags: [{ ...SERVICE_FLAG, description: "service to project onto (defaults to the configured service)" }],
     },
+    {
+        name: "loam_tasks",
+        command: "tasks",
+        description: "What is still open on a feature, at which step, and what closes each unit — a read-only projection that writes nothing. " +
+            "CLI equivalent: loam tasks <featureId> [--service <id>] [--next] --json",
+        positionals: [
+            { property: "featureId", required: true, variadic: false, description: "feature id, e.g. FEAT-101" },
+        ],
+        flags: [
+            { ...SERVICE_FLAG, description: "narrow the packet to the units one service owns (a lens: no binding needed)" },
+            { property: "next", flag: "--next", kind: "boolean", description: "the frontier head alone — the single leaf to hand to a worker" },
+        ],
+    },
     {
         name: "loam_explore",
         command: "explore",
@@ -196,14 +216,27 @@ export const MCP_TOOLS = [
             { property: "feature", flag: "--feature", kind: "string", description: "narrow the in-flight section to this one feature" },
         ],
     },
+    {
+        name: "loam_adopt",
+        command: "adopt",
+        description: "Brief an agent to write one service's baseline docs from its code, and say what will be checked — writes nothing. " +
+            "CLI equivalent: loam adopt [--service <id>] [--subsystem <name>] [--targets] --json",
+        positionals: [],
+        flags: [
+            { ...SERVICE_FLAG, description: "service to adopt (defaults to the configured service)" },
+            { property: "subsystem", flag: "--subsystem", kind: "string", description: "brief a NEW service's baseline into this subsystem instead of the services/ root" },
+            { property: "targets", flag: "--targets", kind: "boolean", description: "only what varies by service; a `full` field names the run that carries the walk, the checks and the unchecked list" },
+        ],
+    },
     {
         name: "loam_gate",
         command: "gate",
         description: "Can this service deploy? A read-only query over recorded evidence — advisory by default. " +
-            "CLI equivalent: loam gate [--service <id>] [--strict] --json",
+            "CLI equivalent: loam gate [--service <id>] [--since <ref>] [--strict] --json",
         positionals: [],
         flags: [
             { ...SERVICE_FLAG, description: "the service being deployed (defaults to the configured service)" },
+            { property: "since", flag: "--since", kind: "string", description: "also grade features archived after this docs-repo git ref; without it only in-flight features are read" },
             { property: "strict", flag: "--strict", kind: "boolean", description: "exit 1 on any warning too; the payload does not change" },
         ],
     },
@@ -243,9 +276,9 @@ export const MCP_TOOLS = [
         command: "instructions",
         description: "Print a workflow, support protocol or reference page, version-matched to this binary; reads no config and no docs repo, so it answers " +
             "before the repository is wired. Ask for loam-check DELIBERATELY: it is by far the largest protocol " +
-            "(its per-code fix tables are ~83 KB of the ~84 KB it prints), and noFixTables true returns the narrowed page " +
+            "(almost all of what it prints is its per-code fix tables), and noFixTables true returns the narrowed page " +
             "— every paragraph that introduces a table, none of the rows — after which loam_explain answers any one code " +
-            "a run reports in under 500 bytes. " +
+            "a run reports, on its own. " +
             "CLI equivalent: loam instructions [workflow] [args...] [--no-fix-tables] --json",
         positionals: [
             {
@@ -280,35 +313,12 @@ export const MCP_TOOLS = [
 export function toolByName(name, tools = MCP_TOOLS) {
     return tools.find((tool) => tool.name === name);
 }
-/** The MCP inputSchema for one tool: a closed object, so a typo'd argument refuses instead of vanishing. */
-export function toInputSchema(tool) {
-    const properties = {};
-    for (const positional of tool.positionals) {
-        properties[positional.property] = positional.variadic
-            ? { type: "array", items: { type: "string" }, description: positional.description }
-            : { type: "string", description: positional.description };
-    }
-    for (const flag of tool.flags) {
-        properties[flag.property] =
-            flag.kind === "boolean"
-                ? { type: "boolean", description: flag.description }
-                : flag.kind === "strings"
-                    ? { type: "array", items: { type: "string" }, description: flag.description }
-                    : { type: "string", description: flag.description };
-    }
-    const required = [
-        ...tool.positionals.filter((p) => p.required).map((p) => p.property),
-        ...tool.flags.filter((f) => f.required === true).map((f) => f.property),
-    ];
-    return {
-        type: "object",
-        properties,
-        ...(required.length > 0 ? { required } : {}),
-        additionalProperties: false,
-    };
-}
 // How a tool call's JSON arguments become an argv — including the refusal of
 // any string a shell-less argv would still read as a flag — lives in
 // `./argv.ts`: the table above says WHAT the tools are, that module says how
-// a call crosses into the CLI's own parsing.
+// a call crosses into the CLI's own parsing. The inputSchema each tool is
+// advertised with (`toInputSchema`) lives there too: it DECLARES the argument
+// contract `toArgv` ENFORCES — the closed object, the required set, the order
+// the positionals are read in — and the two halves change together or a
+// client validates against one rule and is refused by another.
 //# sourceMappingURL=tools.js.map

package/dist/core/mcp/tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../../src/core/mcp/tools.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The curated MCP tool table: which loam commands an MCP client can reach,\n * and how a JSON argument object becomes an argv the CLI already trusts.\n *\n * This base table is read-only. Opt-in writers live in `./author-tools.ts`;\n * vouch and a committing archive remain absent: an MCP caller is definitionally\n * an agent, `loam vouch` is a HUMAN act (the CLI refuses unattended runs with\n * vouch-unattended), and exposing it here would rebuild the hole the generated\n * skill files' allowlist was narrowed to close. verify is excluded with them: its read form and its\n * attesting `--record`/`--results`/`--contract-results` form are one command,\n * and a facade that exposes \"only the read half\" of a writer is one\n * flag-mapping bug away from exposing the writer.\n *\n * The inclusion of the two commands that read no CONFIG — `explain` and\n * `instructions` — is equally deliberate, and is recorded here because the\n * gap is otherwise re-derivable as an oversight: an agent meets both BEFORE\n * the repository is wired (every generated skill's first line is `loam\n * instructions <workflow>`, and `loam explain <code>` answers a code from a\n * run that has not happened yet), so an MCP-only host that could not reach\n * them could not fetch the protocol its own generated skill points at.\n *\n * Every table entry mirrors a real registration in `src/commands/` — same\n * positionals, same flags, same spellings — so the contract an MCP client\n * sees is the CLI contract, not a second one. `--json` is appended by\n * `toArgv` unconditionally: the tool result IS the machine envelope.\n */\n\nimport { TERMS } from \"../explain/terms.js\";\n\n/**\n * The concept-term names, from the registry that owns them — `loam_explain`'s\n * schema description must not be a hand copy that silently trails TERMS.\n */\nconst TERM_LIST = TERMS.map(({ term }) => term).join(\", \");\n\n/** A positional argument, in declaration order. A variadic one is always last. */\nexport interface ToolPositional {\n  readonly property: string;\n  readonly required: boolean;\n  /** True when the JSON argument is an array of strings spread as trailing positionals. */\n  readonly variadic: boolean;\n  readonly description: string;\n}\n\n/** One CLI flag: `kind` decides both the JSON Schema type and the argv shape. */\nexport interface ToolFlag {\n  readonly property: string;\n  readonly flag: string;\n  readonly kind: \"string\" | \"boolean\" | \"strings\";\n  /**\n   * Set when the CLI declares the option with `requiredOption` — the schema\n   * then requires the property and the argv builder refuses its absence, so\n   * a client learns the requirement from the schema instead of from an\n   * invalid-option envelope after the call. The shape test asserts this\n   * mirrors commander's own `mandatory`, both ways.\n   */\n  readonly required?: true;\n  readonly description: string;\n}\n\nexport interface McpTool {\n  readonly name: string;\n  readonly command: string;\n  readonly description: string;\n  readonly positionals: readonly ToolPositional[];\n  readonly flags: readonly ToolFlag[];\n  /** Arguments enforced by the server rather than exposed to the caller. */\n  readonly fixed?: readonly string[];\n  readonly annotations?: Readonly<Record<string, boolean>>;\n}\n\nconst SERVICE_FLAG = {\n  property: \"service\",\n  flag: \"--service\",\n  kind: \"string\",\n  description: \"service id (defaults to the one loam.json configures)\",\n} as const;\n\n/**\n * The tool annotations EVERY entry in this table carries — one shared literal,\n * because the table is read-only by construction and a per-tool copy is a\n * place for one of them to drift into claiming something else.\n *\n * `readOnlyHint` is the whole point: without it a host has no machine signal\n * that `loam_validate` or `loam_context` is safe, so a call that only reads\n * files falls into the same approval prompt as a mutating tool. Read-only\n * hints are what let a host auto-approve, and the reason the writers are\n * excluded from the table above is precisely so this hint can be true of\n * everything left. `openWorldHint: false` states the other half a host acts\n * on: loam reaches no network and no service — it reads the files in the\n * directory the server started in, and nothing else.\n *\n * `idempotentHint` and `destructiveHint` are deliberately ABSENT rather than\n * spelled `true`/`false`: MCP defines both as meaningful only when\n * `readOnlyHint` is false, so shipping them would be noise a reviewer has to\n * justify before deciding they mean nothing here.\n *\n * `outputSchema` lives in `./protocol.ts`, beside `toolReply`: the declaration\n * and the fallback structured envelope have to change together or a client is\n * promised structured content one branch can omit.\n */\nexport const READ_ONLY_ANNOTATIONS = { readOnlyHint: true, openWorldHint: false } as const;\n\n/**\n * The `loam_` prefix on every name: multi-server MCP hosts flatten tool names\n * into one namespace, and a bare `validate` collides with anybody else's.\n * Each description names the CLI command it mirrors, so the equivalence is\n * stated where the client reads it.\n */\nexport const MCP_TOOLS: readonly McpTool[] = [\n  {\n    name: \"loam_validate\",\n    command: \"validate\",\n    description:\n      \"Validate a service (C4 + requirement coverage), a feature (delta + coverage), or the whole fleet. \" +\n      \"CLI equivalent: loam validate [target] [--service <id>] [--feature <id>] [--all] [--strict] [--errors-only] --json\",\n    positionals: [\n      {\n        property: \"target\",\n        required: false,\n        variadic: false,\n        description: \"service or feature id (a feature wins when both match; service/feature force the reading)\",\n      },\n    ],\n    flags: [\n      { ...SERVICE_FLAG, description: \"service to validate (defaults to the configured service)\" },\n      { property: \"feature\", flag: \"--feature\", kind: \"string\", description: \"validate a feature delta instead of a service\" },\n      { property: \"all\", flag: \"--all\", kind: \"boolean\", description: \"validate every service and every active feature\" },\n      { property: \"strict\", flag: \"--strict\", kind: \"boolean\", description: \"exit 1 on any warning too; the payload does not change\" },\n      { property: \"errorsOnly\", flag: \"--errors-only\", kind: \"boolean\", description: \"print only errors and warnings; the payload does not change\" },\n    ],\n  },\n  {\n    name: \"loam_status\",\n    command: \"status\",\n    description:\n      \"Where the work stands and what to do next, derived from the files. \" +\n      \"CLI equivalent: loam status [feature] [--service <id>] --json\",\n    positionals: [\n      { property: \"feature\", required: false, variadic: false, description: \"feature id or directory name; omit for the whole repository\" },\n    ],\n    flags: [{ ...SERVICE_FLAG, description: \"narrow the per-service view to one service\" }],\n  },\n  {\n    name: \"loam_list\",\n    command: \"list\",\n    description:\n      \"List the services and features in the docs repo. \" +\n      \"CLI equivalent: loam list [section] [--archived] [--needs-work] [--review-order] [--subsystem <name>] [--owners <path>] --json\",\n    positionals: [\n      { property: \"section\", required: false, variadic: false, description: \"services | features | capabilities (default: services + features)\" },\n    ],\n    flags: [\n      { property: \"archived\", flag: \"--archived\", kind: \"boolean\", description: \"include archived features\" },\n      { property: \"needsWork\", flag: \"--needs-work\", kind: \"boolean\", description: \"services only: every service below vouched, with what it is missing\" },\n      { property: \"reviewOrder\", flag: \"--review-order\", kind: \"boolean\", description: \"with needsWork: order the worklist by fan-in, highest blast radius first\" },\n      { property: \"subsystem\", flag: \"--subsystem\", kind: \"string\", description: \"services only: limit the listing to services filed under this subsystem, at any depth ('unfiled' selects the ones filed under none)\" },\n      { property: \"owners\", flag: \"--owners\", kind: \"string\", description: \"services only: group the listing by owning team from this CODEOWNERS file (directory-pattern rules only; unsupported rules are listed as skipped, never guessed)\" },\n    ],\n  },\n  {\n    name: \"loam_show\",\n    command: \"show\",\n    description:\n      \"Everything loam knows about a service or a feature. \" +\n      \"CLI equivalent: loam show <target> [--type service|feature] --json\",\n    positionals: [\n      { property: \"target\", required: true, variadic: false, description: \"service id or feature id\" },\n    ],\n    flags: [\n      { property: \"type\", flag: \"--type\", kind: \"string\", description: \"force the reading: service | feature\" },\n    ],\n  },\n  {\n    name: \"loam_delta\",\n    command: \"delta\",\n    description:\n      \"Project a feature onto a service: why + requirement delta + C4 changes. \" +\n      \"CLI equivalent: loam delta <featureId> [--service <id>] --json\",\n    positionals: [\n      { property: \"featureId\", required: true, variadic: false, description: \"feature id, e.g. FEAT-101\" },\n    ],\n    flags: [{ ...SERVICE_FLAG, description: \"service to project onto (defaults to the configured service)\" }],\n  },\n  {\n    name: \"loam_explore\",\n    command: \"explore\",\n    description:\n      \"Read the fleet around a change nobody has written down yet — writes nothing. \" +\n      \"CLI equivalent: loam explore [service...] [--op <id>] [--capability <id>] [--as <FEAT>] --json\",\n    positionals: [\n      { property: \"services\", required: false, variadic: true, description: \"service ids the change starts from\" },\n    ],\n    flags: [\n      { property: \"op\", flag: \"--op\", kind: \"strings\", description: \"seed from an operation instead of a service; repeatable\" },\n      { property: \"capability\", flag: \"--capability\", kind: \"strings\", description: \"seed from a declared capability's realizing services; repeatable\" },\n      { property: \"as\", flag: \"--as\", kind: \"string\", description: \"feature id for the suggested command line\" },\n    ],\n  },\n  {\n    name: \"loam_dependencies\",\n    command: \"dependencies\",\n    description:\n      \"Dependencies and conflicts derived from active feature artifacts. \" +\n      \"CLI equivalent: loam dependencies [featureId] --json\",\n    positionals: [\n      { property: \"featureId\", required: false, variadic: false, description: \"active feature id; omit for the whole in-flight graph\" },\n    ],\n    flags: [],\n  },\n  {\n    name: \"loam_diff\",\n    command: \"diff\",\n    description:\n      \"Semantic diff of the living docs against a base git ref of the docs repo — removals graded against their current consumers; read-only. \" +\n      \"CLI equivalent: loam diff --base <ref> --json\",\n    positionals: [],\n    flags: [\n      {\n        property: \"base\",\n        flag: \"--base\",\n        kind: \"string\",\n        required: true,\n        description: \"base git ref of the docs repo (e.g. main, origin/main, a commit sha)\",\n      },\n    ],\n  },\n  {\n    name: \"loam_doctor\",\n    command: \"doctor\",\n    description:\n      \"Diagnose local loam configuration and docs-repo accessibility without writing. \" +\n      \"CLI equivalent: loam doctor --json\",\n    positionals: [],\n    flags: [],\n  },\n  {\n    name: \"loam_context\",\n    command: \"context\",\n    description:\n      \"Assemble one service's whole docs slice as one deterministic briefing. \" +\n      \"CLI equivalent: loam context <service> [--feature <FEAT>] --json\",\n    positionals: [\n      { property: \"service\", required: true, variadic: false, description: \"service id, e.g. payment-service\" },\n    ],\n    flags: [\n      { property: \"feature\", flag: \"--feature\", kind: \"string\", description: \"narrow the in-flight section to this one feature\" },\n    ],\n  },\n  {\n    name: \"loam_gate\",\n    command: \"gate\",\n    description:\n      \"Can this service deploy? A read-only query over recorded evidence — advisory by default. \" +\n      \"CLI equivalent: loam gate [--service <id>] [--strict] --json\",\n    positionals: [],\n    flags: [\n      { ...SERVICE_FLAG, description: \"the service being deployed (defaults to the configured service)\" },\n      { property: \"strict\", flag: \"--strict\", kind: \"boolean\", description: \"exit 1 on any warning too; the payload does not change\" },\n    ],\n  },\n  {\n    name: \"loam_steps\",\n    command: \"steps\",\n    description:\n      \"Inventory the step phrases of a service's scenarios — how many step definitions its suite needs. \" +\n      \"CLI equivalent: loam steps [--service <id>] [--duplicates] --json\",\n    positionals: [],\n    flags: [\n      { ...SERVICE_FLAG, description: \"service to inventory (defaults to the configured service)\" },\n      {\n        property: \"duplicates\",\n        flag: \"--duplicates\",\n        kind: \"boolean\",\n        description: \"list only the near-duplicate groups — phrases that differ by an article or a trailing clause\",\n      },\n    ],\n  },\n  {\n    name: \"loam_explain\",\n    command: \"explain\",\n    description:\n      \"Explain a finding code, a refusal code, or a loam concept term, version-matched to this binary; reads no config and no docs repo. \" +\n      \"CLI equivalent: loam explain [subject] --json\",\n    positionals: [\n      {\n        property: \"subject\",\n        required: false,\n        variadic: false,\n        description: `finding code (spine.op-undefined), refusal code (docs-busy), or concept term (${TERM_LIST}); omit to list the terms`,\n      },\n    ],\n    flags: [],\n  },\n  {\n    name: \"loam_instructions\",\n    command: \"instructions\",\n    description:\n      \"Print a workflow, support protocol or reference page, version-matched to this binary; reads no config and no docs repo, so it answers \" +\n      \"before the repository is wired. Ask for loam-check DELIBERATELY: it is by far the largest protocol \" +\n      \"(its per-code fix tables are ~83 KB of the ~84 KB it prints), and noFixTables true returns the narrowed page \" +\n      \"— every paragraph that introduces a table, none of the rows — after which loam_explain answers any one code \" +\n      \"a run reports in under 500 bytes. \" +\n      \"CLI equivalent: loam instructions [workflow] [args...] [--no-fix-tables] --json\",\n    positionals: [\n      {\n        property: \"workflow\",\n        required: false,\n        variadic: false,\n        description: \"workflow, support or reference name (loam-adopt, loam-report, loam-codes, …); omit to list them\",\n      },\n      {\n        property: \"args\",\n        required: false,\n        variadic: true,\n        description: \"values substituted for the protocol's $1, $2, … placeholders\",\n      },\n    ],\n    flags: [\n      {\n        // `noFixTables`, not `fixTables`, and the mismatch with commander's own\n        // attribute name (`fixTables`, because `--no-` negates) is the point:\n        // `toArgv` spells a true boolean as its flag string, so a property named\n        // for the option's ATTRIBUTE would make `{fixTables: true}` emit\n        // `--no-fix-tables` and turn the tables off. The JSON property is named\n        // for what setting it true DOES.\n        property: \"noFixTables\",\n        flag: \"--no-fix-tables\",\n        kind: \"boolean\",\n        description: \"drop the per-code fix tables; loam_explain answers any code a run reports\",\n      },\n    ],\n  },\n];\n\nexport function toolByName(\n  name: string,\n  tools: readonly McpTool[] = MCP_TOOLS,\n): McpTool | undefined {\n  return tools.find((tool) => tool.name === name);\n}\n\n/** The MCP inputSchema for one tool: a closed object, so a typo'd argument refuses instead of vanishing. */\nexport function toInputSchema(tool: McpTool): Record<string, unknown> {\n  const properties: Record<string, unknown> = {};\n  for (const positional of tool.positionals) {\n    properties[positional.property] = positional.variadic\n      ? { type: \"array\", items: { type: \"string\" }, description: positional.description }\n      : { type: \"string\", description: positional.description };\n  }\n  for (const flag of tool.flags) {\n    properties[flag.property] =\n      flag.kind === \"boolean\"\n        ? { type: \"boolean\", description: flag.description }\n        : flag.kind === \"strings\"\n          ? { type: \"array\", items: { type: \"string\" }, description: flag.description }\n          : { type: \"string\", description: flag.description };\n  }\n  const required = [\n    ...tool.positionals.filter((p) => p.required).map((p) => p.property),\n    ...tool.flags.filter((f) => f.required === true).map((f) => f.property),\n  ];\n  return {\n    type: \"object\",\n    properties,\n    ...(required.length > 0 ? { required } : {}),\n    additionalProperties: false,\n  };\n}\n\n// How a tool call's JSON arguments become an argv — including the refusal of\n// any string a shell-less argv would still read as a flag — lives in\n// `./argv.ts`: the table above says WHAT the tools are, that module says how\n// a call crosses into the CLI's own parsing.\n"]}
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../../src/core/mcp/tools.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The curated MCP tool table: which loam commands an MCP client can reach,\n * and how a JSON argument object becomes an argv the CLI already trusts.\n *\n * This base table is read-only. Opt-in writers live in `./author-tools.ts`;\n * vouch and a committing archive remain absent: an MCP caller is definitionally\n * an agent, `loam vouch` is a HUMAN act (the CLI refuses unattended runs with\n * vouch-unattended), and exposing it here would rebuild the hole the generated\n * skill files' allowlist was narrowed to close. verify is excluded with them: its read form and its\n * attesting `--record`/`--results`/`--contract-results` form are one command,\n * and a facade that exposes \"only the read half\" of a writer is one\n * flag-mapping bug away from exposing the writer.\n *\n * The inclusion of the two commands that read no CONFIG — `explain` and\n * `instructions` — is equally deliberate, and is recorded here because the\n * gap is otherwise re-derivable as an oversight: an agent meets both BEFORE\n * the repository is wired (every generated skill's first line is `loam\n * instructions <workflow>`, and `loam explain <code>` answers a code from a\n * run that has not happened yet), so an MCP-only host that could not reach\n * them could not fetch the protocol its own generated skill points at.\n *\n * `adopt` is here for the same reason one step later: it writes nothing — it\n * emits the brief an agent then writes a baseline from — and the loam-adopt\n * protocol an MCP-only host fetches through `loam_instructions` opens by\n * running it. Without the tool that host could read the protocol and never\n * receive the brief the protocol is about.\n *\n * Every table entry mirrors a real registration in `src/commands/` — same\n * positionals, same flags, same spellings — so the contract an MCP client\n * sees is the CLI contract, not a second one. `--json` is appended by\n * `toArgv` unconditionally: the tool result IS the machine envelope.\n */\n\nimport { TERMS } from \"../explain/terms.js\";\n\n/**\n * The concept-term names, from the registry that owns them — `loam_explain`'s\n * schema description must not be a hand copy that silently trails TERMS.\n */\nconst TERM_LIST = TERMS.map(({ term }) => term).join(\", \");\n\n/** A positional argument, in declaration order. A variadic one is always last. */\nexport interface ToolPositional {\n  readonly property: string;\n  readonly required: boolean;\n  /** True when the JSON argument is an array of strings spread as trailing positionals. */\n  readonly variadic: boolean;\n  readonly description: string;\n}\n\n/** One CLI flag: `kind` decides both the JSON Schema type and the argv shape. */\nexport interface ToolFlag {\n  readonly property: string;\n  readonly flag: string;\n  readonly kind: \"string\" | \"boolean\" | \"strings\";\n  /**\n   * Set when the CLI declares the option with `requiredOption` — the schema\n   * then requires the property and the argv builder refuses its absence, so\n   * a client learns the requirement from the schema instead of from an\n   * invalid-option envelope after the call. The shape test asserts this\n   * mirrors commander's own `mandatory`, both ways.\n   */\n  readonly required?: true;\n  readonly description: string;\n}\n\nexport interface McpTool {\n  readonly name: string;\n  readonly command: string;\n  readonly description: string;\n  readonly positionals: readonly ToolPositional[];\n  readonly flags: readonly ToolFlag[];\n  /** Arguments enforced by the server rather than exposed to the caller. */\n  readonly fixed?: readonly string[];\n  readonly annotations?: Readonly<Record<string, boolean>>;\n}\n\nconst SERVICE_FLAG = {\n  property: \"service\",\n  flag: \"--service\",\n  kind: \"string\",\n  description: \"service id (defaults to the one loam.json configures)\",\n} as const;\n\n/**\n * The tool annotations EVERY entry in this table carries — one shared literal,\n * because the table is read-only by construction and a per-tool copy is a\n * place for one of them to drift into claiming something else.\n *\n * `readOnlyHint` is the whole point: without it a host has no machine signal\n * that `loam_validate` or `loam_context` is safe, so a call that only reads\n * files falls into the same approval prompt as a mutating tool. Read-only\n * hints are what let a host auto-approve, and the reason the writers are\n * excluded from the table above is precisely so this hint can be true of\n * everything left. `openWorldHint: false` states the other half a host acts\n * on: loam reaches no network and no service — it reads the files in the\n * directory the server started in, and nothing else.\n *\n * `idempotentHint` and `destructiveHint` are deliberately ABSENT rather than\n * spelled `true`/`false`: MCP defines both as meaningful only when\n * `readOnlyHint` is false, so shipping them would be noise a reviewer has to\n * justify before deciding they mean nothing here.\n *\n * `outputSchema` lives in `./protocol.ts`, beside `toolReply`: the declaration\n * and the fallback structured envelope have to change together or a client is\n * promised structured content one branch can omit.\n */\nexport const READ_ONLY_ANNOTATIONS = { readOnlyHint: true, openWorldHint: false } as const;\n\n/**\n * The `loam_` prefix on every name: multi-server MCP hosts flatten tool names\n * into one namespace, and a bare `validate` collides with anybody else's.\n * Each description names the CLI command it mirrors, so the equivalence is\n * stated where the client reads it.\n */\nexport const MCP_TOOLS: readonly McpTool[] = [\n  {\n    name: \"loam_validate\",\n    command: \"validate\",\n    description:\n      \"Validate a service (C4 + requirement coverage), a feature (delta + coverage), or the whole fleet. \" +\n      \"CLI equivalent: loam validate [target] [--service <id>] [--feature <id>] [--all] [--strict] [--errors-only] --json\",\n    positionals: [\n      {\n        property: \"target\",\n        required: false,\n        variadic: false,\n        description: \"service or feature id (a feature wins when both match; service/feature force the reading)\",\n      },\n    ],\n    flags: [\n      { ...SERVICE_FLAG, description: \"service to validate (defaults to the configured service)\" },\n      { property: \"feature\", flag: \"--feature\", kind: \"string\", description: \"validate a feature delta instead of a service\" },\n      { property: \"all\", flag: \"--all\", kind: \"boolean\", description: \"validate every service and every active feature\" },\n      { property: \"strict\", flag: \"--strict\", kind: \"boolean\", description: \"exit 1 on any warning too; the payload does not change\" },\n      { property: \"errorsOnly\", flag: \"--errors-only\", kind: \"boolean\", description: \"print only errors and warnings; the payload does not change\" },\n    ],\n  },\n  {\n    name: \"loam_status\",\n    command: \"status\",\n    description:\n      \"Where the work stands and what to do next, derived from the files. \" +\n      \"CLI equivalent: loam status [feature] [--service <id>] --json\",\n    positionals: [\n      { property: \"feature\", required: false, variadic: false, description: \"feature id or directory name; omit for the whole repository\" },\n    ],\n    flags: [{ ...SERVICE_FLAG, description: \"narrow the per-service view to one service\" }],\n  },\n  {\n    name: \"loam_list\",\n    command: \"list\",\n    description:\n      \"List the services and features in the docs repo. \" +\n      \"CLI equivalent: loam list [section] [name] [--archived] [--needs-work] [--review-order] [--subsystem <name>] [--owners <path>] --json\",\n    positionals: [\n      { property: \"section\", required: false, variadic: false, description: \"services | features | capabilities | glossary | suites (default: services + features)\" },\n      { property: \"name\", required: false, variadic: false, description: \"suites only: the one suite to show\" },\n    ],\n    flags: [\n      { property: \"archived\", flag: \"--archived\", kind: \"boolean\", description: \"include archived features\" },\n      { property: \"needsWork\", flag: \"--needs-work\", kind: \"boolean\", description: \"services only: every service below vouched, with what it is missing\" },\n      { property: \"reviewOrder\", flag: \"--review-order\", kind: \"boolean\", description: \"with needsWork: order the worklist by fan-in, highest blast radius first\" },\n      { property: \"subsystem\", flag: \"--subsystem\", kind: \"string\", description: \"services only: limit the listing to services filed under this subsystem, at any depth ('unfiled' selects the ones filed under none)\" },\n      { property: \"owners\", flag: \"--owners\", kind: \"string\", description: \"services only: group the listing by owning team from this CODEOWNERS file (directory-pattern rules only; unsupported rules are listed as skipped, never guessed)\" },\n    ],\n  },\n  {\n    name: \"loam_show\",\n    command: \"show\",\n    description:\n      \"Everything loam knows about a service or a feature. \" +\n      \"CLI equivalent: loam show <target> [--type service|feature] --json\",\n    positionals: [\n      { property: \"target\", required: true, variadic: false, description: \"service id or feature id\" },\n    ],\n    flags: [\n      { property: \"type\", flag: \"--type\", kind: \"string\", description: \"force the reading: service | feature\" },\n    ],\n  },\n  {\n    name: \"loam_delta\",\n    command: \"delta\",\n    description:\n      \"Project a feature onto a service: why + requirement delta + C4 changes. \" +\n      \"CLI equivalent: loam delta <featureId> [--service <id>] --json\",\n    positionals: [\n      { property: \"featureId\", required: true, variadic: false, description: \"feature id, e.g. FEAT-101\" },\n    ],\n    flags: [{ ...SERVICE_FLAG, description: \"service to project onto (defaults to the configured service)\" }],\n  },\n  {\n    name: \"loam_tasks\",\n    command: \"tasks\",\n    description:\n      \"What is still open on a feature, at which step, and what closes each unit — a read-only projection that writes nothing. \" +\n      \"CLI equivalent: loam tasks <featureId> [--service <id>] [--next] --json\",\n    positionals: [\n      { property: \"featureId\", required: true, variadic: false, description: \"feature id, e.g. FEAT-101\" },\n    ],\n    flags: [\n      { ...SERVICE_FLAG, description: \"narrow the packet to the units one service owns (a lens: no binding needed)\" },\n      { property: \"next\", flag: \"--next\", kind: \"boolean\", description: \"the frontier head alone — the single leaf to hand to a worker\" },\n    ],\n  },\n  {\n    name: \"loam_explore\",\n    command: \"explore\",\n    description:\n      \"Read the fleet around a change nobody has written down yet — writes nothing. \" +\n      \"CLI equivalent: loam explore [service...] [--op <id>] [--capability <id>] [--as <FEAT>] --json\",\n    positionals: [\n      { property: \"services\", required: false, variadic: true, description: \"service ids the change starts from\" },\n    ],\n    flags: [\n      { property: \"op\", flag: \"--op\", kind: \"strings\", description: \"seed from an operation instead of a service; repeatable\" },\n      { property: \"capability\", flag: \"--capability\", kind: \"strings\", description: \"seed from a declared capability's realizing services; repeatable\" },\n      { property: \"as\", flag: \"--as\", kind: \"string\", description: \"feature id for the suggested command line\" },\n    ],\n  },\n  {\n    name: \"loam_dependencies\",\n    command: \"dependencies\",\n    description:\n      \"Dependencies and conflicts derived from active feature artifacts. \" +\n      \"CLI equivalent: loam dependencies [featureId] --json\",\n    positionals: [\n      { property: \"featureId\", required: false, variadic: false, description: \"active feature id; omit for the whole in-flight graph\" },\n    ],\n    flags: [],\n  },\n  {\n    name: \"loam_diff\",\n    command: \"diff\",\n    description:\n      \"Semantic diff of the living docs against a base git ref of the docs repo — removals graded against their current consumers; read-only. \" +\n      \"CLI equivalent: loam diff --base <ref> --json\",\n    positionals: [],\n    flags: [\n      {\n        property: \"base\",\n        flag: \"--base\",\n        kind: \"string\",\n        required: true,\n        description: \"base git ref of the docs repo (e.g. main, origin/main, a commit sha)\",\n      },\n    ],\n  },\n  {\n    name: \"loam_doctor\",\n    command: \"doctor\",\n    description:\n      \"Diagnose local loam configuration and docs-repo accessibility without writing. \" +\n      \"CLI equivalent: loam doctor --json\",\n    positionals: [],\n    flags: [],\n  },\n  {\n    name: \"loam_context\",\n    command: \"context\",\n    description:\n      \"Assemble one service's whole docs slice as one deterministic briefing. \" +\n      \"CLI equivalent: loam context <service> [--feature <FEAT>] --json\",\n    positionals: [\n      { property: \"service\", required: true, variadic: false, description: \"service id, e.g. payment-service\" },\n    ],\n    flags: [\n      { property: \"feature\", flag: \"--feature\", kind: \"string\", description: \"narrow the in-flight section to this one feature\" },\n    ],\n  },\n  {\n    name: \"loam_adopt\",\n    command: \"adopt\",\n    description:\n      \"Brief an agent to write one service's baseline docs from its code, and say what will be checked — writes nothing. \" +\n      \"CLI equivalent: loam adopt [--service <id>] [--subsystem <name>] [--targets] --json\",\n    positionals: [],\n    flags: [\n      { ...SERVICE_FLAG, description: \"service to adopt (defaults to the configured service)\" },\n      { property: \"subsystem\", flag: \"--subsystem\", kind: \"string\", description: \"brief a NEW service's baseline into this subsystem instead of the services/ root\" },\n      { property: \"targets\", flag: \"--targets\", kind: \"boolean\", description: \"only what varies by service; a `full` field names the run that carries the walk, the checks and the unchecked list\" },\n    ],\n  },\n  {\n    name: \"loam_gate\",\n    command: \"gate\",\n    description:\n      \"Can this service deploy? A read-only query over recorded evidence — advisory by default. \" +\n      \"CLI equivalent: loam gate [--service <id>] [--since <ref>] [--strict] --json\",\n    positionals: [],\n    flags: [\n      { ...SERVICE_FLAG, description: \"the service being deployed (defaults to the configured service)\" },\n      { property: \"since\", flag: \"--since\", kind: \"string\", description: \"also grade features archived after this docs-repo git ref; without it only in-flight features are read\" },\n      { property: \"strict\", flag: \"--strict\", kind: \"boolean\", description: \"exit 1 on any warning too; the payload does not change\" },\n    ],\n  },\n  {\n    name: \"loam_steps\",\n    command: \"steps\",\n    description:\n      \"Inventory the step phrases of a service's scenarios — how many step definitions its suite needs. \" +\n      \"CLI equivalent: loam steps [--service <id>] [--duplicates] --json\",\n    positionals: [],\n    flags: [\n      { ...SERVICE_FLAG, description: \"service to inventory (defaults to the configured service)\" },\n      {\n        property: \"duplicates\",\n        flag: \"--duplicates\",\n        kind: \"boolean\",\n        description: \"list only the near-duplicate groups — phrases that differ by an article or a trailing clause\",\n      },\n    ],\n  },\n  {\n    name: \"loam_explain\",\n    command: \"explain\",\n    description:\n      \"Explain a finding code, a refusal code, or a loam concept term, version-matched to this binary; reads no config and no docs repo. \" +\n      \"CLI equivalent: loam explain [subject] --json\",\n    positionals: [\n      {\n        property: \"subject\",\n        required: false,\n        variadic: false,\n        description: `finding code (spine.op-undefined), refusal code (docs-busy), or concept term (${TERM_LIST}); omit to list the terms`,\n      },\n    ],\n    flags: [],\n  },\n  {\n    name: \"loam_instructions\",\n    command: \"instructions\",\n    description:\n      \"Print a workflow, support protocol or reference page, version-matched to this binary; reads no config and no docs repo, so it answers \" +\n      \"before the repository is wired. Ask for loam-check DELIBERATELY: it is by far the largest protocol \" +\n      \"(almost all of what it prints is its per-code fix tables), and noFixTables true returns the narrowed page \" +\n      \"— every paragraph that introduces a table, none of the rows — after which loam_explain answers any one code \" +\n      \"a run reports, on its own. \" +\n      \"CLI equivalent: loam instructions [workflow] [args...] [--no-fix-tables] --json\",\n    positionals: [\n      {\n        property: \"workflow\",\n        required: false,\n        variadic: false,\n        description: \"workflow, support or reference name (loam-adopt, loam-report, loam-codes, …); omit to list them\",\n      },\n      {\n        property: \"args\",\n        required: false,\n        variadic: true,\n        description: \"values substituted for the protocol's $1, $2, … placeholders\",\n      },\n    ],\n    flags: [\n      {\n        // `noFixTables`, not `fixTables`, and the mismatch with commander's own\n        // attribute name (`fixTables`, because `--no-` negates) is the point:\n        // `toArgv` spells a true boolean as its flag string, so a property named\n        // for the option's ATTRIBUTE would make `{fixTables: true}` emit\n        // `--no-fix-tables` and turn the tables off. The JSON property is named\n        // for what setting it true DOES.\n        property: \"noFixTables\",\n        flag: \"--no-fix-tables\",\n        kind: \"boolean\",\n        description: \"drop the per-code fix tables; loam_explain answers any code a run reports\",\n      },\n    ],\n  },\n];\n\nexport function toolByName(\n  name: string,\n  tools: readonly McpTool[] = MCP_TOOLS,\n): McpTool | undefined {\n  return tools.find((tool) => tool.name === name);\n}\n\n// How a tool call's JSON arguments become an argv — including the refusal of\n// any string a shell-less argv would still read as a flag — lives in\n// `./argv.ts`: the table above says WHAT the tools are, that module says how\n// a call crosses into the CLI's own parsing. The inputSchema each tool is\n// advertised with (`toInputSchema`) lives there too: it DECLARES the argument\n// contract `toArgv` ENFORCES — the closed object, the required set, the order\n// the positionals are read in — and the two halves change together or a\n// client validates against one rule and is refused by another.\n"]}

package/dist/core/openapi/baseline/gate.js

@@ -1,7 +1,7 @@
 /**
  * The baseline axis of the feature gate: which of the surfaces this delta
- * SPELLS does it actually edit? A feature's openapi.yaml is a complete
- * document, so most of it is quotation — and until the pins existed the merge
+ * SPELLS does it actually edit? A feature's openapi.yaml needs only what it
+ * changes, but it may quote more — and until the pins existed the merge
  * upserted quotations too, which reverted whatever had landed on them since.
  *
  * Extracted from `coherence/declared.ts` when the operation pin grew its two
@@ -25,14 +25,25 @@ import { entryFor, readBaselineRecord, restatedSurfaces, surfaceIn } from "./rec
 export function openapiBaselineIssues(input) {
     const { featDoc, livingDoc, service, featureId } = input;
     const issues = [];
-    const livingBySlot = new Map(livingDoc.ops.map((op) => [`${op.method} ${op.path}`, op]));
-    let unpinned = 0;
-    for (const op of featDoc.ops) {
+    // Slot-keyed on BOTH sides, an operation with no operationId included: the
+    // merge replaces whatever stands at a method and path, and `loam rebase`
+    // pins against whatever stands there, named or not. Reading named
+    // operations alone, this gate refused as pinned over "no operation at that
+    // slot" the very pin rebase had just written over an unnamed one — the two
+    // could never agree — and an unpinned quote over it drew no
+    // `openapi.baseline-missing` at all.
+    const livingBySlot = new Map([...livingDoc.ops, ...livingDoc.anonymousOps].map((op) => [`${op.method} ${op.path}`, op]));
+    const restated = [
         // A removal marker is not a restatement of anything; its own exactness
         // check (`openapi.remove-target-mismatch`) already guards the slot.
-        if (op.remove)
-            continue;
+        ...featDoc.ops.filter((op) => !op.remove),
+        ...featDoc.anonymousOps,
+    ];
+    let unpinned = 0;
+    for (const op of restated) {
         const where = `${op.method.toUpperCase()} ${op.path}`;
+        // How the messages name it: the slot, and the operationId where it has one.
+        const named = op.id === undefined ? where : `${where} ('${op.id}')`;
         const livingOp = livingBySlot.get(`${op.method} ${op.path}`);
         if (op.basedOn !== undefined && !OPERATION_DIGEST_RE.test(op.basedOn)) {
             issues.push({
@@ -45,11 +56,36 @@ export function openapiBaselineIssues(input) {
         }
         const verdict = classifyBaselineDigests(op.basedOn, op.digest, livingOp?.digest);
         if (verdict === "unfounded") {
+            // Three ways here, and the message must not pick the wrong one for the
+            // author. A pin is only ever written over a living operation, so a pin
+            // with nothing living behind it usually means the operation was there
+            // and LEFT — a parallel feature retired it, or MOVED it to another slot
+            // (moving an endpoint is the most common contract edit there is). This
+            // used to say "drop the marker", and dropping it is exactly how the
+            // quote then archived as an addition and put the operation back — and
+            // for a move the retirement advice is wrong too: the id still lives, so
+            // archiving past `openapi.op-revived` would answer it at both slots.
+            // The living contract says which: a move leaves the id at another slot
+            // (and so does a retirement here followed by a re-add there, which
+            // reads the same from this side). The third way — a pin hand-written
+            // onto a genuinely new operation — is the rare one. The two addresses
+            // are a condition ("while it still lives there"), not a forecast: a
+            // delta swapping the id back defines another operation at the address
+            // it lives at, with or without an operationId, and the merge replaces
+            // it there. The revival check (coherence/retired/revival/) reads the
+            // contract that merge would write and stands down whenever it answers
+            // an id the living contract still holds — as here — at one address, so
+            // this must not tell the author otherwise —
+            // and for that delta a removal marker at the address cannot be written
+            // beside the other operation, hence the second remedy.
+            const movedTo = op.id === undefined ? [] : livingDoc.ops.filter((l) => !l.remove && l.id === op.id).map((l) => `${l.method.toUpperCase()} ${l.path}`);
             issues.push({
                 severity: "error",
                 code: "openapi.baseline-invalid",
                 subject: service,
-                message: `${service}: ${where} ('${op.id}') carries ${OPENAPI_BASELINE_KEY}, but the living contract has no operation at that slot — a new operation has no living version to be based on; drop the marker`,
+                message: movedTo.length > 0
+                    ? `${service}: ${where} ('${op.id}') carries ${OPENAPI_BASELINE_KEY}, but the living contract has no operation at that slot — '${op.id}' lives at ${movedTo.join(" and ")} now: a parallel feature moved it there (or retired it here, and another re-added it there). Re-read it there and delete this operation from the delta, making any change at its new address; archived while it still lives there, it would put '${op.id}' back at ${where} as well, one operationId at two addresses. To move it back on purpose, drop the pin and add a removal marker for '${op.id}' at ${movedTo.join(" and ")} to this delta, or define another operation there.`
+                    : `${service}: ${named} carries ${OPENAPI_BASELINE_KEY}, but the living contract has no operation at that slot — the version it was pinned to is gone. If a parallel feature retired it, re-read the living contract and delete this operation from the delta, unless this feature deliberately brings it back (then drop the pin and archive with --approve past \`openapi.op-revived\`). A genuinely new operation has no living version to be based on and carries no pin.`,
             });
         }
         else if (verdict === "stale") {
@@ -57,7 +93,7 @@ export function openapiBaselineIssues(input) {
                 severity: "error",
                 code: "openapi.baseline-stale",
                 subject: service,
-                message: `${service}: ${where} ('${op.id}') was written against living version ${op.basedOn}, but the living contract now holds ${livingOp.digest} — somebody landed a change to it in between, and merging this would replace theirs outright. Re-read the living operation, fold in what you still mean, then run \`loam rebase ${featureId}\`.`,
+                message: `${service}: ${named} was written against living version ${op.basedOn}, but the living contract now holds ${livingOp.digest} — somebody landed a change to it in between, and merging this would replace theirs outright. Re-read the living operation, fold in what you still mean, then run \`loam rebase ${featureId}\`.`,
             });
         }
         else if (verdict === "unpinned" && livingOp !== undefined) {
@@ -150,9 +186,14 @@ export function openapiBaselineIssues(input) {
         // (delta/select.ts): the document is legal, but an unpinned quote is
         // exactly the shape that reverts another feature's landed change at exit
         // 0, and every count covers only values the living contract already has —
-        // a genuinely new operation, key or component never trips it. `loam
-        // rebase` pins a whole service in one command; `--approve` says the
-        // unpinned merge is meant.
+        // a genuinely new operation, key or component never trips it. That is
+        // also why it cannot see a quote of an operation a parallel feature
+        // RETIRED: absent from living, it reads exactly like a new one — nor of
+        // one a parallel feature MOVED, quoted at the slot it left, since nothing
+        // living stands at that slot. Telling either apart from an addition takes
+        // the archived features' removal markers, which this gate never reads —
+        // `openapi.op-revived` (core/coherence/retired/) asks that question. `loam rebase` pins a whole service in one command;
+        // `--approve` says the unpinned merge is meant.
         issues.push({
             severity: "warn",
             gates: true,

package/dist/core/openapi/baseline/gate.js.map

@@ -1 +1 @@
-{"version":3,"file":"gate.js","sourceRoot":"","sources":["../../../../src/core/openapi/baseline/gate.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The baseline axis of the feature gate: which of the surfaces this delta\n * SPELLS does it actually edit? A feature's openapi.yaml is a complete\n * document, so most of it is quotation — and until the pins existed the merge\n * upserted quotations too, which reverted whatever had landed on them since.\n *\n * Extracted from `coherence/declared.ts` when the operation pin grew its two\n * sibling surfaces (path-item non-method keys, components): the grading is one\n * subject with three families, and coherence/ is at its file limit. Everything\n * here is graded by the ONE classifier in `../digest.ts` over the ONE surface\n * enumeration in `./record.ts`, so the gate, the rebase plan and the merge\n * cannot drift into different ideas of what a delta restates.\n */\nimport { parse } from \"yaml\";\nimport type { Issue } from \"../../vocabulary/issue.js\";\nimport type { OpenapiDoc } from \"../doc.js\";\nimport {\n  classifyBaselineDigests,\n  OPENAPI_BASELINE_KEY,\n  OPENAPI_BASELINES_KEY,\n  OPERATION_DIGEST_LENGTH,\n  OPERATION_DIGEST_RE,\n  valueDigest,\n} from \"../digest.js\";\nimport { entryFor, readBaselineRecord, restatedSurfaces, surfaceIn } from \"./record.js\";\n\n/** Everything the gate needs about one service's pair of contracts. */\nexport interface BaselineGateInput {\n  /** The FEATURE contract as `readOpenapi` parsed it — ops carry digests and pins. */\n  featDoc: OpenapiDoc;\n  /** The LIVING contract's parse; empty when the file is absent. */\n  livingDoc: OpenapiDoc;\n  /** The feature contract's text — the surface record and values are read from it. */\n  featureText: string;\n  /** The living contract's text, or undefined when no living contract exists. */\n  livingText: string | undefined;\n  service: string;\n  featureId: string;\n}\n\n/**\n * Grade every baseline this feature contract carries — operation pins,\n * path-item keys, components — against the living contract. Slot-keyed for\n * operations, (path, key)-keyed and (kind/name)-keyed for the record, exactly\n * as the merge writes. With no living side there are no surface checks at all:\n * everything the delta spells is new, and a baseline only means something for\n * a value that already exists.\n */\nexport function openapiBaselineIssues(input: BaselineGateInput): Issue[] {\n  const { featDoc, livingDoc, service, featureId } = input;\n  const issues: Issue[] = [];\n  const livingBySlot = new Map(livingDoc.ops.map((op) => [`${op.method} ${op.path}`, op]));\n  let unpinned = 0;\n  for (const op of featDoc.ops) {\n    // A removal marker is not a restatement of anything; its own exactness\n    // check (`openapi.remove-target-mismatch`) already guards the slot.\n    if (op.remove) continue;\n    const where = `${op.method.toUpperCase()} ${op.path}`;\n    const livingOp = livingBySlot.get(`${op.method} ${op.path}`);\n    if (op.basedOn !== undefined && !OPERATION_DIGEST_RE.test(op.basedOn)) {\n      issues.push({\n        severity: \"error\",\n        code: \"openapi.baseline-invalid\",\n        subject: service,\n        message: `${service}: ${where} has invalid ${OPENAPI_BASELINE_KEY} '${op.basedOn}' — expected ${OPERATION_DIGEST_LENGTH} lowercase hex characters, as \\`loam rebase\\` writes them`,\n      });\n      continue;\n    }\n    const verdict = classifyBaselineDigests(op.basedOn, op.digest, livingOp?.digest);\n    if (verdict === \"unfounded\") {\n      issues.push({\n        severity: \"error\",\n        code: \"openapi.baseline-invalid\",\n        subject: service,\n        message: `${service}: ${where} ('${op.id}') carries ${OPENAPI_BASELINE_KEY}, but the living contract has no operation at that slot — a new operation has no living version to be based on; drop the marker`,\n      });\n    } else if (verdict === \"stale\") {\n      issues.push({\n        severity: \"error\",\n        code: \"openapi.baseline-stale\",\n        subject: service,\n        message: `${service}: ${where} ('${op.id}') was written against living version ${op.basedOn}, but the living contract now holds ${livingOp!.digest} — somebody landed a change to it in between, and merging this would replace theirs outright. Re-read the living operation, fold in what you still mean, then run \\`loam rebase ${featureId}\\`.`,\n      });\n    } else if (verdict === \"unpinned\" && livingOp !== undefined) {\n      // Counted, not listed. A delta over a thirty-operation service quotes\n      // twenty-nine of them, and twenty-nine identical warnings naming a fix\n      // that is ONE command teaches people to filter the code out.\n      unpinned += 1;\n    }\n  }\n\n  // The two surfaces the operation pin cannot reach, graded from the\n  // `x-loam-baselines` record by the same classifier. Unreadable documents\n  // never get here on the feature side (`openapi.invalid` suspends the axis);\n  // an unreadable LIVING side is that contract's own `openapi.invalid`, and\n  // grading against its empty parse would call every restatement new.\n  const missing = { keys: 0, components: 0 };\n  if (input.livingText !== undefined && !featDoc.unreadable && !livingDoc.unreadable) {\n    const featPlain: unknown = parse(input.featureText);\n    const livingPlain: unknown = parse(input.livingText);\n    const { record, problems } = readBaselineRecord(featPlain);\n    for (const problem of problems) {\n      issues.push({\n        severity: \"error\",\n        code: \"openapi.baseline-invalid\",\n        subject: service,\n        message: `${service}: ${problem} — the record is \\`loam rebase\\`'s bookkeeping and cannot be graded as it stands; re-run \\`loam rebase ${featureId}\\` to rebuild it`,\n      });\n    }\n    const surfaces = restatedSurfaces(featPlain);\n    // An entry pinning a surface the delta does not restate is a claim about\n    // nothing — usually a surface the author deleted after rebasing. Distinct\n    // from `unfounded` below, where the surface IS restated and the LIVING\n    // side is what vanished.\n    const restated = new Set(surfaces.map((s) => (s.kind === \"path-item\" ? `${s.path}\\0${s.key}` : s.id)));\n    for (const [path, keys] of Object.entries(record.pathItems)) {\n      for (const key of Object.keys(keys)) {\n        if (restated.has(`${path}\\0${key}`)) continue;\n        issues.push({\n          severity: \"error\",\n          code: \"openapi.baseline-invalid\",\n          subject: service,\n          message: `${service}: ${OPENAPI_BASELINES_KEY} pins '${key}' (${path}), but this feature's openapi.yaml does not restate that key — re-run \\`loam rebase ${featureId}\\` to rebuild the record`,\n        });\n      }\n    }\n    for (const id of Object.keys(record.components)) {\n      if (restated.has(id)) continue;\n      issues.push({\n        severity: \"error\",\n        code: \"openapi.baseline-invalid\",\n        subject: service,\n        message: `${service}: ${OPENAPI_BASELINES_KEY} pins component '${id}', but this feature's openapi.yaml does not declare it — re-run \\`loam rebase ${featureId}\\` to rebuild the record`,\n      });\n    }\n    for (const s of surfaces) {\n      const label = s.kind === \"path-item\" ? `path-level key '${s.key}' (${s.path})` : `component '${s.id}'`;\n      const entry = entryFor(record, s);\n      const living = surfaceIn(livingPlain, s);\n      const livingDigest = living.found ? valueDigest(living.value) : undefined;\n      const verdict = classifyBaselineDigests(entry, valueDigest(s.value), livingDigest);\n      if (verdict === \"unpinned\") {\n        if (living.found) {\n          if (s.kind === \"path-item\") missing.keys += 1;\n          else missing.components += 1;\n        }\n      } else if (verdict === \"stale\") {\n        issues.push({\n          severity: \"error\",\n          code: \"openapi.baseline-stale\",\n          subject: service,\n          message: `${service}: ${label} was pinned to living version ${entry}, but the living contract now holds ${livingDigest} — somebody landed a change to it in between, and merging this would replace theirs outright. Re-read the living value, fold in what you still mean, then run \\`loam rebase ${featureId}\\`.`,\n        });\n      } else if (verdict === \"unfounded\") {\n        issues.push({\n          severity: \"error\",\n          code: \"openapi.baseline-invalid\",\n          subject: service,\n          message: `${service}: ${label} is pinned to ${entry}, but the living contract no longer has that surface — the pin is structurally unresolvable; re-read the living contract, then run \\`loam rebase ${featureId}\\``,\n        });\n      }\n    }\n  }\n\n  if (unpinned > 0 || missing.keys > 0 || missing.components > 0) {\n    // A warning that GATES archive, same doctrine as `delta.baseline-missing`\n    // (delta/select.ts): the document is legal, but an unpinned quote is\n    // exactly the shape that reverts another feature's landed change at exit\n    // 0, and every count covers only values the living contract already has —\n    // a genuinely new operation, key or component never trips it. `loam\n    // rebase` pins a whole service in one command; `--approve` says the\n    // unpinned merge is meant.\n    issues.push({\n      severity: \"warn\",\n      gates: true,\n      code: \"openapi.baseline-missing\",\n      subject: service,\n      message: `${service}: ${unpinned} operation(s), ${missing.keys} path-level key(s) and ${missing.components} component(s) in this feature's openapi.yaml carry no baseline pin (${OPENAPI_BASELINE_KEY} / ${OPENAPI_BASELINES_KEY}), so the merge cannot tell which ones this delta EDITS from the ones it merely restates — it will upsert all of them, reverting anything that landed on the restated ones. Run \\`loam rebase ${featureId} --service ${service}\\`, or archive with --approve to merge unpinned deliberately.`,\n    });\n  }\n  return issues;\n}\n"]}
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../../../../src/core/openapi/baseline/gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,MAAM,CAAC;AAG7B,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,qBAAqB,EACrB,uBAAuB,EACvB,mBAAmB,EACnB,WAAW,GACZ,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,QAAQ,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAgBxF;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAwB;IAC5D,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,KAAK,CAAC;IACzD,MAAM,MAAM,GAAY,EAAE,CAAC;IAC3B,2EAA2E;IAC3E,yEAAyE;IACzE,kEAAkE;IAClE,2EAA2E;IAC3E,2EAA2E;IAC3E,4DAA4D;IAC5D,qCAAqC;IACrC,MAAM,YAAY,GAAG,IAAI,GAAG,CAC1B,CAAC,GAAG,SAAS,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,YAAY,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,MAAM,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC,CAC3F,CAAC;IACF,MAAM,QAAQ,GAA2F;QACvG,uEAAuE;QACvE,oEAAoE;QACpE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC;QACzC,GAAG,OAAO,CAAC,YAAY;KACxB,CAAC;IACF,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,KAAK,MAAM,EAAE,IAAI,QAAQ,EAAE,CAAC;QAC1B,MAAM,KAAK,GAAG,GAAG,EAAE,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC;QACtD,4EAA4E;QAC5E,MAAM,KAAK,GAAG,EAAE,CAAC,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,MAAM,EAAE,CAAC,EAAE,IAAI,CAAC;QACpE,MAAM,QAAQ,GAAG,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,MAAM,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;QAC7D,IAAI,EAAE,CAAC,OAAO,KAAK,SAAS,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;YACtE,MAAM,CAAC,IAAI,CAAC;gBACV,QAAQ,EAAE,OAAO;gBACjB,IAAI,EAAE,0BAA0B;gBAChC,OAAO,EAAE,OAAO;gBAChB,OAAO,EAAE,GAAG,OAAO,KAAK,KAAK,gBAAgB,oBAAoB,KAAK,EAAE,CAAC,OAAO,gBAAgB,uBAAuB,2DAA2D;aACnL,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QACD,MAAM,OAAO,GAAG,uBAAuB,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;QACjF,IAAI,OAAO,KAAK,WAAW,EAAE,CAAC;YAC5B,uEAAuE;YACvE,uEAAuE;YACvE,sEAAsE;YACtE,wEAAwE;YACxE,uEAAuE;YACvE,oEAAoE;YACpE,sEAAsE;YACtE,wEAAwE;YACxE,qEAAqE;YACrE,uEAAuE;YACvE,mEAAmE;YACnE,qEAAqE;YACrE,sEAAsE;YACtE,oEAAoE;YACpE,sEAAsE;YACtE,sEAAsE;YACtE,qEAAqE;YACrE,sEAAsE;YACtE,uEAAuE;YACvE,4CAA4C;YAC5C,uEAAuE;YACvE,uDAAuD;YACvD,MAAM,OAAO,GAAG,EAAE,CAAC,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;YACtJ,MAAM,CAAC,IAAI,CAAC;gBACV,QAAQ,EAAE,OAAO;gBACjB,IAAI,EAAE,0BAA0B;gBAChC,OAAO,EAAE,OAAO;gBAChB,OAAO,EAAE,OAAO,CAAC,MAAM,GAAG,CAAC;oBACzB,CAAC,CAAC,GAAG,OAAO,KAAK,KAAK,MAAM,EAAE,CAAC,EAAE,cAAc,oBAAoB,8DAA8D,EAAE,CAAC,EAAE,cAAc,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,oPAAoP,EAAE,CAAC,EAAE,aAAa,KAAK,sHAAsH,EAAE,CAAC,EAAE,QAAQ,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,oDAAoD;oBAChoB,CAAC,CAAC,GAAG,OAAO,KAAK,KAAK,YAAY,oBAAoB,wZAAwZ;aACjd,CAAC,CAAC;QACL,CAAC;aAAM,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;YAC/B,MAAM,CAAC,IAAI,CAAC;gBACV,QAAQ,EAAE,OAAO;gBACjB,IAAI,EAAE,wBAAwB;gBAC9B,OAAO,EAAE,OAAO;gBAChB,OAAO,EAAE,GAAG,OAAO,KAAK,KAAK,uCAAuC,EAAE,CAAC,OAAO,uCAAuC,QAAS,CAAC,MAAM,mLAAmL,SAAS,KAAK;aACvU,CAAC,CAAC;QACL,CAAC;aAAM,IAAI,OAAO,KAAK,UAAU,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC5D,sEAAsE;YACtE,uEAAuE;YACvE,6DAA6D;YAC7D,QAAQ,IAAI,CAAC,CAAC;QAChB,CAAC;IACH,CAAC;IAED,mEAAmE;IACnE,yEAAyE;IACzE,4EAA4E;IAC5E,0EAA0E;IAC1E,oEAAoE;IACpE,MAAM,OAAO,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC;IAC3C,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS,IAAI,CAAC,OAAO,CAAC,UAAU,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,CAAC;QACnF,MAAM,SAAS,GAAY,KAAK,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;QACpD,MAAM,WAAW,GAAY,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QACrD,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,kBAAkB,CAAC,SAAS,CAAC,CAAC;QAC3D,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAC/B,MAAM,CAAC,IAAI,CAAC;gBACV,QAAQ,EAAE,OAAO;gBACjB,IAAI,EAAE,0BAA0B;gBAChC,OAAO,EAAE,OAAO;gBAChB,OAAO,EAAE,GAAG,OAAO,KAAK,OAAO,0GAA0G,SAAS,kBAAkB;aACrK,CAAC,CAAC;QACL,CAAC;QACD,MAAM,QAAQ,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;QAC7C,yEAAyE;QACzE,0EAA0E;QAC1E,uEAAuE;QACvE,yBAAyB;QACzB,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QACvG,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC;YAC5D,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;gBACpC,IAAI,QAAQ,CAAC,GAAG,CAAC,GAAG,IAAI,KAAK,GAAG,EAAE,CAAC;oBAAE,SAAS;gBAC9C,MAAM,CAAC,IAAI,CAAC;oBACV,QAAQ,EAAE,OAAO;oBACjB,IAAI,EAAE,0BAA0B;oBAChC,OAAO,EAAE,OAAO;oBAChB,OAAO,EAAE,GAAG,OAAO,KAAK,qBAAqB,UAAU,GAAG,MAAM,IAAI,uFAAuF,SAAS,0BAA0B;iBAC/L,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QACD,KAAK,MAAM,EAAE,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC;YAChD,IAAI,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;gBAAE,SAAS;YAC/B,MAAM,CAAC,IAAI,CAAC;gBACV,QAAQ,EAAE,OAAO;gBACjB,IAAI,EAAE,0BAA0B;gBAChC,OAAO,EAAE,OAAO;gBAChB,OAAO,EAAE,GAAG,OAAO,KAAK,qBAAqB,oBAAoB,EAAE,iFAAiF,SAAS,0BAA0B;aACxL,CAAC,CAAC;QACL,CAAC;QACD,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;YACzB,MAAM,KAAK,GAAG,CAAC,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,EAAE,GAAG,CAAC;YACvG,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;YAClC,MAAM,MAAM,GAAG,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;YACzC,MAAM,YAAY,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YAC1E,MAAM,OAAO,GAAG,uBAAuB,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC,CAAC;YACnF,IAAI,OAAO,KAAK,UAAU,EAAE,CAAC;gBAC3B,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;oBACjB,IAAI,CAAC,CAAC,IAAI,KAAK,WAAW;wBAAE,OAAO,CAAC,IAAI,IAAI,CAAC,CAAC;;wBACzC,OAAO,CAAC,UAAU,IAAI,CAAC,CAAC;gBAC/B,CAAC;YACH,CAAC;iBAAM,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;gBAC/B,MAAM,CAAC,IAAI,CAAC;oBACV,QAAQ,EAAE,OAAO;oBACjB,IAAI,EAAE,wBAAwB;oBAC9B,OAAO,EAAE,OAAO;oBAChB,OAAO,EAAE,GAAG,OAAO,KAAK,KAAK,iCAAiC,KAAK,uCAAuC,YAAY,+KAA+K,SAAS,KAAK;iBACpT,CAAC,CAAC;YACL,CAAC;iBAAM,IAAI,OAAO,KAAK,WAAW,EAAE,CAAC;gBACnC,MAAM,CAAC,IAAI,CAAC;oBACV,QAAQ,EAAE,OAAO;oBACjB,IAAI,EAAE,0BAA0B;oBAChC,OAAO,EAAE,OAAO;oBAChB,OAAO,EAAE,GAAG,OAAO,KAAK,KAAK,iBAAiB,KAAK,oJAAoJ,SAAS,IAAI;iBACrN,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAED,IAAI,QAAQ,GAAG,CAAC,IAAI,OAAO,CAAC,IAAI,GAAG,CAAC,IAAI,OAAO,CAAC,UAAU,GAAG,CAAC,EAAE,CAAC;QAC/D,0EAA0E;QAC1E,qEAAqE;QACrE,yEAAyE;QACzE,0EAA0E;QAC1E,sEAAsE;QACtE,oEAAoE;QACpE,wEAAwE;QACxE,0EAA0E;QAC1E,0EAA0E;QAC1E,wEAAwE;QACxE,wHAAwH;QACxH,gDAAgD;QAChD,MAAM,CAAC,IAAI,CAAC;YACV,QAAQ,EAAE,MAAM;YAChB,KAAK,EAAE,IAAI;YACX,IAAI,EAAE,0BAA0B;YAChC,OAAO,EAAE,OAAO;YAChB,OAAO,EAAE,GAAG,OAAO,KAAK,QAAQ,kBAAkB,OAAO,CAAC,IAAI,0BAA0B,OAAO,CAAC,UAAU,uEAAuE,oBAAoB,MAAM,qBAAqB,iMAAiM,SAAS,cAAc,OAAO,+DAA+D;SAC/f,CAAC,CAAC;IACL,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC","sourcesContent":["/**\n * The baseline axis of the feature gate: which of the surfaces this delta\n * SPELLS does it actually edit? A feature's openapi.yaml needs only what it\n * changes, but it may quote more — and until the pins existed the merge\n * upserted quotations too, which reverted whatever had landed on them since.\n *\n * Extracted from `coherence/declared.ts` when the operation pin grew its two\n * sibling surfaces (path-item non-method keys, components): the grading is one\n * subject with three families, and coherence/ is at its file limit. Everything\n * here is graded by the ONE classifier in `../digest.ts` over the ONE surface\n * enumeration in `./record.ts`, so the gate, the rebase plan and the merge\n * cannot drift into different ideas of what a delta restates.\n */\nimport { parse } from \"yaml\";\nimport type { Issue } from \"../../vocabulary/issue.js\";\nimport type { OpenapiDoc } from \"../doc.js\";\nimport {\n  classifyBaselineDigests,\n  OPENAPI_BASELINE_KEY,\n  OPENAPI_BASELINES_KEY,\n  OPERATION_DIGEST_LENGTH,\n  OPERATION_DIGEST_RE,\n  valueDigest,\n} from \"../digest.js\";\nimport { entryFor, readBaselineRecord, restatedSurfaces, surfaceIn } from \"./record.js\";\n\n/** Everything the gate needs about one service's pair of contracts. */\nexport interface BaselineGateInput {\n  /** The FEATURE contract as `readOpenapi` parsed it — ops carry digests and pins. */\n  featDoc: OpenapiDoc;\n  /** The LIVING contract's parse; empty when the file is absent. */\n  livingDoc: OpenapiDoc;\n  /** The feature contract's text — the surface record and values are read from it. */\n  featureText: string;\n  /** The living contract's text, or undefined when no living contract exists. */\n  livingText: string | undefined;\n  service: string;\n  featureId: string;\n}\n\n/**\n * Grade every baseline this feature contract carries — operation pins,\n * path-item keys, components — against the living contract. Slot-keyed for\n * operations, (path, key)-keyed and (kind/name)-keyed for the record, exactly\n * as the merge writes. With no living side there are no surface checks at all:\n * everything the delta spells is new, and a baseline only means something for\n * a value that already exists.\n */\nexport function openapiBaselineIssues(input: BaselineGateInput): Issue[] {\n  const { featDoc, livingDoc, service, featureId } = input;\n  const issues: Issue[] = [];\n  // Slot-keyed on BOTH sides, an operation with no operationId included: the\n  // merge replaces whatever stands at a method and path, and `loam rebase`\n  // pins against whatever stands there, named or not. Reading named\n  // operations alone, this gate refused as pinned over \"no operation at that\n  // slot\" the very pin rebase had just written over an unnamed one — the two\n  // could never agree — and an unpinned quote over it drew no\n  // `openapi.baseline-missing` at all.\n  const livingBySlot = new Map<string, { digest: string }>(\n    [...livingDoc.ops, ...livingDoc.anonymousOps].map((op) => [`${op.method} ${op.path}`, op]),\n  );\n  const restated: Array<{ id?: string; path: string; method: string; digest: string; basedOn?: string }> = [\n    // A removal marker is not a restatement of anything; its own exactness\n    // check (`openapi.remove-target-mismatch`) already guards the slot.\n    ...featDoc.ops.filter((op) => !op.remove),\n    ...featDoc.anonymousOps,\n  ];\n  let unpinned = 0;\n  for (const op of restated) {\n    const where = `${op.method.toUpperCase()} ${op.path}`;\n    // How the messages name it: the slot, and the operationId where it has one.\n    const named = op.id === undefined ? where : `${where} ('${op.id}')`;\n    const livingOp = livingBySlot.get(`${op.method} ${op.path}`);\n    if (op.basedOn !== undefined && !OPERATION_DIGEST_RE.test(op.basedOn)) {\n      issues.push({\n        severity: \"error\",\n        code: \"openapi.baseline-invalid\",\n        subject: service,\n        message: `${service}: ${where} has invalid ${OPENAPI_BASELINE_KEY} '${op.basedOn}' — expected ${OPERATION_DIGEST_LENGTH} lowercase hex characters, as \\`loam rebase\\` writes them`,\n      });\n      continue;\n    }\n    const verdict = classifyBaselineDigests(op.basedOn, op.digest, livingOp?.digest);\n    if (verdict === \"unfounded\") {\n      // Three ways here, and the message must not pick the wrong one for the\n      // author. A pin is only ever written over a living operation, so a pin\n      // with nothing living behind it usually means the operation was there\n      // and LEFT — a parallel feature retired it, or MOVED it to another slot\n      // (moving an endpoint is the most common contract edit there is). This\n      // used to say \"drop the marker\", and dropping it is exactly how the\n      // quote then archived as an addition and put the operation back — and\n      // for a move the retirement advice is wrong too: the id still lives, so\n      // archiving past `openapi.op-revived` would answer it at both slots.\n      // The living contract says which: a move leaves the id at another slot\n      // (and so does a retirement here followed by a re-add there, which\n      // reads the same from this side). The third way — a pin hand-written\n      // onto a genuinely new operation — is the rare one. The two addresses\n      // are a condition (\"while it still lives there\"), not a forecast: a\n      // delta swapping the id back defines another operation at the address\n      // it lives at, with or without an operationId, and the merge replaces\n      // it there. The revival check (coherence/retired/revival/) reads the\n      // contract that merge would write and stands down whenever it answers\n      // an id the living contract still holds — as here — at one address, so\n      // this must not tell the author otherwise —\n      // and for that delta a removal marker at the address cannot be written\n      // beside the other operation, hence the second remedy.\n      const movedTo = op.id === undefined ? [] : livingDoc.ops.filter((l) => !l.remove && l.id === op.id).map((l) => `${l.method.toUpperCase()} ${l.path}`);\n      issues.push({\n        severity: \"error\",\n        code: \"openapi.baseline-invalid\",\n        subject: service,\n        message: movedTo.length > 0\n          ? `${service}: ${where} ('${op.id}') carries ${OPENAPI_BASELINE_KEY}, but the living contract has no operation at that slot — '${op.id}' lives at ${movedTo.join(\" and \")} now: a parallel feature moved it there (or retired it here, and another re-added it there). Re-read it there and delete this operation from the delta, making any change at its new address; archived while it still lives there, it would put '${op.id}' back at ${where} as well, one operationId at two addresses. To move it back on purpose, drop the pin and add a removal marker for '${op.id}' at ${movedTo.join(\" and \")} to this delta, or define another operation there.`\n          : `${service}: ${named} carries ${OPENAPI_BASELINE_KEY}, but the living contract has no operation at that slot — the version it was pinned to is gone. If a parallel feature retired it, re-read the living contract and delete this operation from the delta, unless this feature deliberately brings it back (then drop the pin and archive with --approve past \\`openapi.op-revived\\`). A genuinely new operation has no living version to be based on and carries no pin.`,\n      });\n    } else if (verdict === \"stale\") {\n      issues.push({\n        severity: \"error\",\n        code: \"openapi.baseline-stale\",\n        subject: service,\n        message: `${service}: ${named} was written against living version ${op.basedOn}, but the living contract now holds ${livingOp!.digest} — somebody landed a change to it in between, and merging this would replace theirs outright. Re-read the living operation, fold in what you still mean, then run \\`loam rebase ${featureId}\\`.`,\n      });\n    } else if (verdict === \"unpinned\" && livingOp !== undefined) {\n      // Counted, not listed. A delta over a thirty-operation service quotes\n      // twenty-nine of them, and twenty-nine identical warnings naming a fix\n      // that is ONE command teaches people to filter the code out.\n      unpinned += 1;\n    }\n  }\n\n  // The two surfaces the operation pin cannot reach, graded from the\n  // `x-loam-baselines` record by the same classifier. Unreadable documents\n  // never get here on the feature side (`openapi.invalid` suspends the axis);\n  // an unreadable LIVING side is that contract's own `openapi.invalid`, and\n  // grading against its empty parse would call every restatement new.\n  const missing = { keys: 0, components: 0 };\n  if (input.livingText !== undefined && !featDoc.unreadable && !livingDoc.unreadable) {\n    const featPlain: unknown = parse(input.featureText);\n    const livingPlain: unknown = parse(input.livingText);\n    const { record, problems } = readBaselineRecord(featPlain);\n    for (const problem of problems) {\n      issues.push({\n        severity: \"error\",\n        code: \"openapi.baseline-invalid\",\n        subject: service,\n        message: `${service}: ${problem} — the record is \\`loam rebase\\`'s bookkeeping and cannot be graded as it stands; re-run \\`loam rebase ${featureId}\\` to rebuild it`,\n      });\n    }\n    const surfaces = restatedSurfaces(featPlain);\n    // An entry pinning a surface the delta does not restate is a claim about\n    // nothing — usually a surface the author deleted after rebasing. Distinct\n    // from `unfounded` below, where the surface IS restated and the LIVING\n    // side is what vanished.\n    const restated = new Set(surfaces.map((s) => (s.kind === \"path-item\" ? `${s.path}\\0${s.key}` : s.id)));\n    for (const [path, keys] of Object.entries(record.pathItems)) {\n      for (const key of Object.keys(keys)) {\n        if (restated.has(`${path}\\0${key}`)) continue;\n        issues.push({\n          severity: \"error\",\n          code: \"openapi.baseline-invalid\",\n          subject: service,\n          message: `${service}: ${OPENAPI_BASELINES_KEY} pins '${key}' (${path}), but this feature's openapi.yaml does not restate that key — re-run \\`loam rebase ${featureId}\\` to rebuild the record`,\n        });\n      }\n    }\n    for (const id of Object.keys(record.components)) {\n      if (restated.has(id)) continue;\n      issues.push({\n        severity: \"error\",\n        code: \"openapi.baseline-invalid\",\n        subject: service,\n        message: `${service}: ${OPENAPI_BASELINES_KEY} pins component '${id}', but this feature's openapi.yaml does not declare it — re-run \\`loam rebase ${featureId}\\` to rebuild the record`,\n      });\n    }\n    for (const s of surfaces) {\n      const label = s.kind === \"path-item\" ? `path-level key '${s.key}' (${s.path})` : `component '${s.id}'`;\n      const entry = entryFor(record, s);\n      const living = surfaceIn(livingPlain, s);\n      const livingDigest = living.found ? valueDigest(living.value) : undefined;\n      const verdict = classifyBaselineDigests(entry, valueDigest(s.value), livingDigest);\n      if (verdict === \"unpinned\") {\n        if (living.found) {\n          if (s.kind === \"path-item\") missing.keys += 1;\n          else missing.components += 1;\n        }\n      } else if (verdict === \"stale\") {\n        issues.push({\n          severity: \"error\",\n          code: \"openapi.baseline-stale\",\n          subject: service,\n          message: `${service}: ${label} was pinned to living version ${entry}, but the living contract now holds ${livingDigest} — somebody landed a change to it in between, and merging this would replace theirs outright. Re-read the living value, fold in what you still mean, then run \\`loam rebase ${featureId}\\`.`,\n        });\n      } else if (verdict === \"unfounded\") {\n        issues.push({\n          severity: \"error\",\n          code: \"openapi.baseline-invalid\",\n          subject: service,\n          message: `${service}: ${label} is pinned to ${entry}, but the living contract no longer has that surface — the pin is structurally unresolvable; re-read the living contract, then run \\`loam rebase ${featureId}\\``,\n        });\n      }\n    }\n  }\n\n  if (unpinned > 0 || missing.keys > 0 || missing.components > 0) {\n    // A warning that GATES archive, same doctrine as `delta.baseline-missing`\n    // (delta/select.ts): the document is legal, but an unpinned quote is\n    // exactly the shape that reverts another feature's landed change at exit\n    // 0, and every count covers only values the living contract already has —\n    // a genuinely new operation, key or component never trips it. That is\n    // also why it cannot see a quote of an operation a parallel feature\n    // RETIRED: absent from living, it reads exactly like a new one — nor of\n    // one a parallel feature MOVED, quoted at the slot it left, since nothing\n    // living stands at that slot. Telling either apart from an addition takes\n    // the archived features' removal markers, which this gate never reads —\n    // `openapi.op-revived` (core/coherence/retired/) asks that question. `loam rebase` pins a whole service in one command;\n    // `--approve` says the unpinned merge is meant.\n    issues.push({\n      severity: \"warn\",\n      gates: true,\n      code: \"openapi.baseline-missing\",\n      subject: service,\n      message: `${service}: ${unpinned} operation(s), ${missing.keys} path-level key(s) and ${missing.components} component(s) in this feature's openapi.yaml carry no baseline pin (${OPENAPI_BASELINE_KEY} / ${OPENAPI_BASELINES_KEY}), so the merge cannot tell which ones this delta EDITS from the ones it merely restates — it will upsert all of them, reverting anything that landed on the restated ones. Run \\`loam rebase ${featureId} --service ${service}\\`, or archive with --approve to merge unpinned deliberately.`,\n    });\n  }\n  return issues;\n}\n"]}

package/dist/core/openapi/baseline/plan.js

@@ -13,7 +13,8 @@
  * `./record.ts`, so a value edge back into `merge/` would be a package cycle.
  * That is also why an unreadable document is answered with "nothing to pin"
  * instead of `OpenapiMergeError`: every caller chains this AFTER
- * `pinOpenapiOperations`, which has already thrown that error for any document
+ * `pinOpenapiOperations` (on the event axis, after `pinAsyncapiSlots` and its
+ * `AsyncapiMergeError`), which has already thrown that error for any document
  * either side cannot parse, so the silent answer here is unreachable in
  * practice and merely keeps the failure ownership where it already lives.
  */
@@ -27,11 +28,22 @@ import { buildRecord, entryFor, readBaselineRecord, restatedSurfaces, surfaceIn
  * the living one. The entry is always `valueDigest` of the LIVING value, never
  * of the delta's own — the one rule that yields both merge verdicts: a surface
  * the author only QUOTED equals its own entry, one they EDITED differs from it.
+ *
  * A surface with no living counterpart is `unresolved` and deliberately absent
- * from the record: there is no baseline to claim, and inventing one would make
- * `classifyBaselineDigests` call a genuinely new value `unfounded`.
+ * from the record. Stamping a pin against nothing is not a harmless extra key:
+ * `classifyBaselineDigests` calls a pin with no living side `unfounded`, and
+ * the gate then refuses the delta as `openapi.baseline-invalid` (or
+ * `asyncapi.baseline-invalid`) — rebase would be writing the file the gate
+ * sends its author back to rebase.
+ *
+ * `surfacesOf` is the one thing the two contract axes do differently: the
+ * OpenAPI default walks `paths` and `components`, and the event axis passes
+ * `asyncapiSurfaces` (core/asyncapi/baseline/surfaces.ts says why it is a
+ * separate enumeration). Everything after the walk — the record, its sorted
+ * writer, the idempotence check — is axis-neutral, which is why the event
+ * planner is this function rather than a copy of it.
  */
-export function planOpenapiBaselines(featureText, livingText, _service) {
+export function planOpenapiBaselines(featureText, livingText, surfacesOf = restatedSurfaces) {
     const doc = parseDocument(featureText);
     if (doc.errors.length > 0)
         return { text: null, pins: [] };
@@ -51,11 +63,12 @@ export function planOpenapiBaselines(featureText, livingText, _service) {
     const pathItems = new Map();
     const components = new Map();
     const pins = [];
-    for (const surface of restatedSurfaces(featPlain)) {
+    for (const surface of surfacesOf(featPlain)) {
         // A malformed current entry reads back as absent (readBaselineRecord drops
         // it into `problems`), so this run reports `pinned` and overwrites it —
-        // rebase is the command the gate's `openapi.baseline-invalid` sends people
-        // to, and it must repair what it names.
+        // rebase is the command the gate's `openapi.baseline-invalid` (and
+        // `asyncapi.baseline-invalid`) sends people to, and it must repair what it
+        // names.
         const from = entryFor(current, surface);
         const base = {
             kind: surface.kind,
@@ -85,7 +98,8 @@ export function planOpenapiBaselines(featureText, livingText, _service) {
     }
     // The written form drops empty sections, and the whole key when both are —
     // a bare `x-loam-baselines: {}` would be bookkeeping about nothing, in every
-    // delta whose surfaces are all new.
+    // delta whose surfaces are all new. An AsyncAPI document has no path items,
+    // so on that axis `pathItems` is always the empty section dropped here.
     const rebuilt = buildRecord({ pathItems, components });
     const written = {};
     if (Object.keys(rebuilt.pathItems).length > 0)

package/dist/core/openapi/baseline/plan.js.map

@@ -1 +1 @@
-{"version":3,"file":"plan.js","sourceRoot":"","sources":["../../../../src/core/openapi/baseline/plan.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What `loam rebase` writes on the surface axis: the `x-loam-baselines` record,\n * rebuilt wholesale from what is on disk right now.\n *\n * The record is rebuilt rather than patched for the same reason the operation\n * pin is always the LIVING digest: a pin is a claim about what its author read,\n * and an entry left behind for a surface the delta no longer restates — or one\n * whose living counterpart is gone — is a claim nobody is making any more.\n * Wholesale rebuild prunes both without a second code path, and the sorted\n * serialization (`buildRecord`) is what makes a second run byte-identical.\n *\n * This module must not import from `../merge/` — the merge reads\n * `./record.ts`, so a value edge back into `merge/` would be a package cycle.\n * That is also why an unreadable document is answered with \"nothing to pin\"\n * instead of `OpenapiMergeError`: every caller chains this AFTER\n * `pinOpenapiOperations`, which has already thrown that error for any document\n * either side cannot parse, so the silent answer here is unreachable in\n * practice and merely keeps the failure ownership where it already lives.\n */\nimport { isDeepStrictEqual } from \"node:util\";\nimport { parseDocument } from \"yaml\";\nimport { isRecord } from \"../../kernel/records.js\";\nimport { OPENAPI_BASELINES_KEY, valueDigest } from \"../digest.js\";\nimport { buildRecord, entryFor, readBaselineRecord, restatedSurfaces, surfaceIn } from \"./record.js\";\n\n/** What happened to one restated surface's baseline entry. */\nexport interface SurfacePin {\n  /** Which surface family the entry pins. */\n  kind: \"path-item\" | \"component\";\n  /** `/orders '<key>'` for a path-item key; `<kind>/<name>` for a component. */\n  target: string;\n  status:\n    /** It had no entry and now has one. */\n    | \"pinned\"\n    /** It named an older living version; it now names the current one. */\n    | \"repinned\"\n    /** It already named the current living version — no write. */\n    | \"unchanged\"\n    /** The living contract has no such surface: this feature is adding it, and it gets NO entry. */\n    | \"unresolved\";\n  from: string | null;\n  to: string | null;\n}\n\nexport interface OpenapiBaselinePlan {\n  /** The rewritten contract, or null when the record already says what this run would write. */\n  text: string | null;\n  pins: SurfacePin[];\n}\n\n/**\n * Pin every restated path-item key and component of a feature contract against\n * the living one. The entry is always `valueDigest` of the LIVING value, never\n * of the delta's own — the one rule that yields both merge verdicts: a surface\n * the author only QUOTED equals its own entry, one they EDITED differs from it.\n * A surface with no living counterpart is `unresolved` and deliberately absent\n * from the record: there is no baseline to claim, and inventing one would make\n * `classifyBaselineDigests` call a genuinely new value `unfounded`.\n */\nexport function planOpenapiBaselines(\n  featureText: string,\n  livingText: string,\n  _service: string,\n): OpenapiBaselinePlan {\n  const doc = parseDocument(featureText);\n  if (doc.errors.length > 0) return { text: null, pins: [] };\n  let featPlain: unknown;\n  let livingPlain: unknown;\n  try {\n    featPlain = doc.toJS() ?? {};\n    const living = parseDocument(livingText);\n    if (living.errors.length > 0) return { text: null, pins: [] };\n    livingPlain = living.toJS() ?? {};\n  } catch {\n    return { text: null, pins: [] };\n  }\n\n  const current = readBaselineRecord(featPlain).record;\n  const pathItems = new Map<string, Map<string, string>>();\n  const components = new Map<string, string>();\n  const pins: SurfacePin[] = [];\n  for (const surface of restatedSurfaces(featPlain)) {\n    // A malformed current entry reads back as absent (readBaselineRecord drops\n    // it into `problems`), so this run reports `pinned` and overwrites it —\n    // rebase is the command the gate's `openapi.baseline-invalid` sends people\n    // to, and it must repair what it names.\n    const from = entryFor(current, surface);\n    const base = {\n      kind: surface.kind,\n      target: surface.kind === \"path-item\" ? `${surface.path} '${surface.key}'` : surface.id,\n    } as const;\n    const livingValue = surfaceIn(livingPlain, surface);\n    if (!livingValue.found) {\n      pins.push({ ...base, status: \"unresolved\", from: from ?? null, to: null });\n      continue;\n    }\n    const digest = valueDigest(livingValue.value);\n    if (surface.kind === \"path-item\") {\n      let keys = pathItems.get(surface.path);\n      if (keys === undefined) pathItems.set(surface.path, (keys = new Map()));\n      keys.set(surface.key, digest);\n    } else {\n      components.set(surface.id, digest);\n    }\n    pins.push({\n      ...base,\n      status: from === digest ? \"unchanged\" : from === undefined ? \"pinned\" : \"repinned\",\n      from: from ?? null,\n      to: digest,\n    });\n  }\n\n  // The written form drops empty sections, and the whole key when both are —\n  // a bare `x-loam-baselines: {}` would be bookkeeping about nothing, in every\n  // delta whose surfaces are all new.\n  const rebuilt = buildRecord({ pathItems, components });\n  const written: Record<string, unknown> = {};\n  if (Object.keys(rebuilt.pathItems).length > 0) written[\"pathItems\"] = rebuilt.pathItems;\n  if (Object.keys(rebuilt.components).length > 0) written[\"components\"] = rebuilt.components;\n  const raw = isRecord(featPlain) ? featPlain[OPENAPI_BASELINES_KEY] : undefined;\n  if (Object.keys(written).length === 0) {\n    if (raw === undefined) return { text: null, pins };\n    doc.deleteIn([OPENAPI_BASELINES_KEY]);\n    return { text: doc.toString(), pins };\n  }\n  // Deep-equal, not byte-equal: the comparison must ignore key order exactly as\n  // the digests do, so a record an author reordered by hand is left in their\n  // order — and a second run over this function's own sorted output finds the\n  // parse equal and writes nothing, which is the byte-for-byte idempotence\n  // `loam rebase` promises.\n  if (isDeepStrictEqual(raw, written)) return { text: null, pins };\n  doc.setIn([OPENAPI_BASELINES_KEY], written);\n  return { text: doc.toString(), pins };\n}\n"]}
+{"version":3,"file":"plan.js","sourceRoot":"","sources":["../../../../src/core/openapi/baseline/plan.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What `loam rebase` writes on the surface axis: the `x-loam-baselines` record,\n * rebuilt wholesale from what is on disk right now.\n *\n * The record is rebuilt rather than patched for the same reason the operation\n * pin is always the LIVING digest: a pin is a claim about what its author read,\n * and an entry left behind for a surface the delta no longer restates — or one\n * whose living counterpart is gone — is a claim nobody is making any more.\n * Wholesale rebuild prunes both without a second code path, and the sorted\n * serialization (`buildRecord`) is what makes a second run byte-identical.\n *\n * This module must not import from `../merge/` — the merge reads\n * `./record.ts`, so a value edge back into `merge/` would be a package cycle.\n * That is also why an unreadable document is answered with \"nothing to pin\"\n * instead of `OpenapiMergeError`: every caller chains this AFTER\n * `pinOpenapiOperations` (on the event axis, after `pinAsyncapiSlots` and its\n * `AsyncapiMergeError`), which has already thrown that error for any document\n * either side cannot parse, so the silent answer here is unreachable in\n * practice and merely keeps the failure ownership where it already lives.\n */\nimport { isDeepStrictEqual } from \"node:util\";\nimport { parseDocument } from \"yaml\";\nimport { isRecord } from \"../../kernel/records.js\";\nimport { OPENAPI_BASELINES_KEY, valueDigest } from \"../digest.js\";\nimport { buildRecord, entryFor, readBaselineRecord, restatedSurfaces, surfaceIn, type RestatedSurface } from \"./record.js\";\n\n/** What happened to one restated surface's baseline entry. */\nexport interface SurfacePin {\n  /** Which surface family the entry pins. */\n  kind: \"path-item\" | \"component\";\n  /** `/orders '<key>'` for a path-item key; `<kind>/<name>` for a component. */\n  target: string;\n  status:\n    /** It had no entry and now has one. */\n    | \"pinned\"\n    /** It named an older living version; it now names the current one. */\n    | \"repinned\"\n    /** It already named the current living version — no write. */\n    | \"unchanged\"\n    /** The living contract has no such surface: this feature is adding it, and it gets NO entry. */\n    | \"unresolved\";\n  from: string | null;\n  to: string | null;\n}\n\nexport interface OpenapiBaselinePlan {\n  /** The rewritten contract, or null when the record already says what this run would write. */\n  text: string | null;\n  pins: SurfacePin[];\n}\n\n/**\n * Pin every restated path-item key and component of a feature contract against\n * the living one. The entry is always `valueDigest` of the LIVING value, never\n * of the delta's own — the one rule that yields both merge verdicts: a surface\n * the author only QUOTED equals its own entry, one they EDITED differs from it.\n *\n * A surface with no living counterpart is `unresolved` and deliberately absent\n * from the record. Stamping a pin against nothing is not a harmless extra key:\n * `classifyBaselineDigests` calls a pin with no living side `unfounded`, and\n * the gate then refuses the delta as `openapi.baseline-invalid` (or\n * `asyncapi.baseline-invalid`) — rebase would be writing the file the gate\n * sends its author back to rebase.\n *\n * `surfacesOf` is the one thing the two contract axes do differently: the\n * OpenAPI default walks `paths` and `components`, and the event axis passes\n * `asyncapiSurfaces` (core/asyncapi/baseline/surfaces.ts says why it is a\n * separate enumeration). Everything after the walk — the record, its sorted\n * writer, the idempotence check — is axis-neutral, which is why the event\n * planner is this function rather than a copy of it.\n */\nexport function planOpenapiBaselines(\n  featureText: string,\n  livingText: string,\n  surfacesOf: (plain: unknown) => readonly RestatedSurface[] = restatedSurfaces,\n): OpenapiBaselinePlan {\n  const doc = parseDocument(featureText);\n  if (doc.errors.length > 0) return { text: null, pins: [] };\n  let featPlain: unknown;\n  let livingPlain: unknown;\n  try {\n    featPlain = doc.toJS() ?? {};\n    const living = parseDocument(livingText);\n    if (living.errors.length > 0) return { text: null, pins: [] };\n    livingPlain = living.toJS() ?? {};\n  } catch {\n    return { text: null, pins: [] };\n  }\n\n  const current = readBaselineRecord(featPlain).record;\n  const pathItems = new Map<string, Map<string, string>>();\n  const components = new Map<string, string>();\n  const pins: SurfacePin[] = [];\n  for (const surface of surfacesOf(featPlain)) {\n    // A malformed current entry reads back as absent (readBaselineRecord drops\n    // it into `problems`), so this run reports `pinned` and overwrites it —\n    // rebase is the command the gate's `openapi.baseline-invalid` (and\n    // `asyncapi.baseline-invalid`) sends people to, and it must repair what it\n    // names.\n    const from = entryFor(current, surface);\n    const base = {\n      kind: surface.kind,\n      target: surface.kind === \"path-item\" ? `${surface.path} '${surface.key}'` : surface.id,\n    } as const;\n    const livingValue = surfaceIn(livingPlain, surface);\n    if (!livingValue.found) {\n      pins.push({ ...base, status: \"unresolved\", from: from ?? null, to: null });\n      continue;\n    }\n    const digest = valueDigest(livingValue.value);\n    if (surface.kind === \"path-item\") {\n      let keys = pathItems.get(surface.path);\n      if (keys === undefined) pathItems.set(surface.path, (keys = new Map()));\n      keys.set(surface.key, digest);\n    } else {\n      components.set(surface.id, digest);\n    }\n    pins.push({\n      ...base,\n      status: from === digest ? \"unchanged\" : from === undefined ? \"pinned\" : \"repinned\",\n      from: from ?? null,\n      to: digest,\n    });\n  }\n\n  // The written form drops empty sections, and the whole key when both are —\n  // a bare `x-loam-baselines: {}` would be bookkeeping about nothing, in every\n  // delta whose surfaces are all new. An AsyncAPI document has no path items,\n  // so on that axis `pathItems` is always the empty section dropped here.\n  const rebuilt = buildRecord({ pathItems, components });\n  const written: Record<string, unknown> = {};\n  if (Object.keys(rebuilt.pathItems).length > 0) written[\"pathItems\"] = rebuilt.pathItems;\n  if (Object.keys(rebuilt.components).length > 0) written[\"components\"] = rebuilt.components;\n  const raw = isRecord(featPlain) ? featPlain[OPENAPI_BASELINES_KEY] : undefined;\n  if (Object.keys(written).length === 0) {\n    if (raw === undefined) return { text: null, pins };\n    doc.deleteIn([OPENAPI_BASELINES_KEY]);\n    return { text: doc.toString(), pins };\n  }\n  // Deep-equal, not byte-equal: the comparison must ignore key order exactly as\n  // the digests do, so a record an author reordered by hand is left in their\n  // order — and a second run over this function's own sorted output finds the\n  // parse equal and writes nothing, which is the byte-for-byte idempotence\n  // `loam rebase` promises.\n  if (isDeepStrictEqual(raw, written)) return { text: null, pins };\n  doc.setIn([OPENAPI_BASELINES_KEY], written);\n  return { text: doc.toString(), pins };\n}\n"]}

package/dist/core/openapi/baseline/record.js

@@ -12,7 +12,6 @@
 import { isRecord } from "../../kernel/records.js";
 import { HTTP_METHODS } from "../doc.js";
 import { FEATURE_ONLY_KEYS, OPENAPI_BASELINES_KEY, OPERATION_DIGEST_RE } from "../digest.js";
-export const EMPTY_RECORD = { pathItems: {}, components: {} };
 /** The record a plain-parsed feature document carries, plus everything wrong with it. */
 export function readBaselineRecord(plain) {
     const problems = [];