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

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

@@ -0,0 +1,166 @@
+/**
+ * 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
+ * upserted quotations too, which reverted whatever had landed on them since.
+ *
+ * Extracted from `coherence/declared.ts` when the operation pin grew its two
+ * sibling surfaces (path-item non-method keys, components): the grading is one
+ * subject with three families, and coherence/ is at its file limit. Everything
+ * here is graded by the ONE classifier in `../digest.ts` over the ONE surface
+ * enumeration in `./record.ts`, so the gate, the rebase plan and the merge
+ * cannot drift into different ideas of what a delta restates.
+ */
+import { parse } from "yaml";
+import { classifyBaselineDigests, OPENAPI_BASELINE_KEY, OPENAPI_BASELINES_KEY, OPERATION_DIGEST_LENGTH, OPERATION_DIGEST_RE, valueDigest, } from "../digest.js";
+import { entryFor, readBaselineRecord, restatedSurfaces, surfaceIn } from "./record.js";
+/**
+ * Grade every baseline this feature contract carries — operation pins,
+ * path-item keys, components — against the living contract. Slot-keyed for
+ * operations, (path, key)-keyed and (kind/name)-keyed for the record, exactly
+ * as the merge writes. With no living side there are no surface checks at all:
+ * everything the delta spells is new, and a baseline only means something for
+ * a value that already exists.
+ */
+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) {
+        // 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;
+        const where = `${op.method.toUpperCase()} ${op.path}`;
+        const livingOp = livingBySlot.get(`${op.method} ${op.path}`);
+        if (op.basedOn !== undefined && !OPERATION_DIGEST_RE.test(op.basedOn)) {
+            issues.push({
+                severity: "error",
+                code: "openapi.baseline-invalid",
+                subject: service,
+                message: `${service}: ${where} has invalid ${OPENAPI_BASELINE_KEY} '${op.basedOn}' — expected ${OPERATION_DIGEST_LENGTH} lowercase hex characters, as \`loam rebase\` writes them`,
+            });
+            continue;
+        }
+        const verdict = classifyBaselineDigests(op.basedOn, op.digest, livingOp?.digest);
+        if (verdict === "unfounded") {
+            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`,
+            });
+        }
+        else if (verdict === "stale") {
+            issues.push({
+                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}\`.`,
+            });
+        }
+        else if (verdict === "unpinned" && livingOp !== undefined) {
+            // Counted, not listed. A delta over a thirty-operation service quotes
+            // twenty-nine of them, and twenty-nine identical warnings naming a fix
+            // that is ONE command teaches people to filter the code out.
+            unpinned += 1;
+        }
+    }
+    // The two surfaces the operation pin cannot reach, graded from the
+    // `x-loam-baselines` record by the same classifier. Unreadable documents
+    // never get here on the feature side (`openapi.invalid` suspends the axis);
+    // an unreadable LIVING side is that contract's own `openapi.invalid`, and
+    // grading against its empty parse would call every restatement new.
+    const missing = { keys: 0, components: 0 };
+    if (input.livingText !== undefined && !featDoc.unreadable && !livingDoc.unreadable) {
+        const featPlain = parse(input.featureText);
+        const livingPlain = parse(input.livingText);
+        const { record, problems } = readBaselineRecord(featPlain);
+        for (const problem of problems) {
+            issues.push({
+                severity: "error",
+                code: "openapi.baseline-invalid",
+                subject: service,
+                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`,
+            });
+        }
+        const surfaces = restatedSurfaces(featPlain);
+        // An entry pinning a surface the delta does not restate is a claim about
+        // nothing — usually a surface the author deleted after rebasing. Distinct
+        // from `unfounded` below, where the surface IS restated and the LIVING
+        // side is what vanished.
+        const restated = new Set(surfaces.map((s) => (s.kind === "path-item" ? `${s.path}\0${s.key}` : s.id)));
+        for (const [path, keys] of Object.entries(record.pathItems)) {
+            for (const key of Object.keys(keys)) {
+                if (restated.has(`${path}\0${key}`))
+                    continue;
+                issues.push({
+                    severity: "error",
+                    code: "openapi.baseline-invalid",
+                    subject: service,
+                    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`,
+                });
+            }
+        }
+        for (const id of Object.keys(record.components)) {
+            if (restated.has(id))
+                continue;
+            issues.push({
+                severity: "error",
+                code: "openapi.baseline-invalid",
+                subject: service,
+                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`,
+            });
+        }
+        for (const s of surfaces) {
+            const label = s.kind === "path-item" ? `path-level key '${s.key}' (${s.path})` : `component '${s.id}'`;
+            const entry = entryFor(record, s);
+            const living = surfaceIn(livingPlain, s);
+            const livingDigest = living.found ? valueDigest(living.value) : undefined;
+            const verdict = classifyBaselineDigests(entry, valueDigest(s.value), livingDigest);
+            if (verdict === "unpinned") {
+                if (living.found) {
+                    if (s.kind === "path-item")
+                        missing.keys += 1;
+                    else
+                        missing.components += 1;
+                }
+            }
+            else if (verdict === "stale") {
+                issues.push({
+                    severity: "error",
+                    code: "openapi.baseline-stale",
+                    subject: service,
+                    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}\`.`,
+                });
+            }
+            else if (verdict === "unfounded") {
+                issues.push({
+                    severity: "error",
+                    code: "openapi.baseline-invalid",
+                    subject: service,
+                    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}\``,
+                });
+            }
+        }
+    }
+    if (unpinned > 0 || missing.keys > 0 || missing.components > 0) {
+        // A warning that GATES archive, same doctrine as `delta.baseline-missing`
+        // (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.
+        issues.push({
+            severity: "warn",
+            gates: true,
+            code: "openapi.baseline-missing",
+            subject: service,
+            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.`,
+        });
+    }
+    return issues;
+}
+//# sourceMappingURL=gate.js.map

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

@@ -0,0 +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"]}

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

@@ -0,0 +1,112 @@
+/**
+ * What `loam rebase` writes on the surface axis: the `x-loam-baselines` record,
+ * rebuilt wholesale from what is on disk right now.
+ *
+ * The record is rebuilt rather than patched for the same reason the operation
+ * pin is always the LIVING digest: a pin is a claim about what its author read,
+ * and an entry left behind for a surface the delta no longer restates — or one
+ * whose living counterpart is gone — is a claim nobody is making any more.
+ * Wholesale rebuild prunes both without a second code path, and the sorted
+ * serialization (`buildRecord`) is what makes a second run byte-identical.
+ *
+ * This module must not import from `../merge/` — the merge reads
+ * `./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
+ * either side cannot parse, so the silent answer here is unreachable in
+ * practice and merely keeps the failure ownership where it already lives.
+ */
+import { isDeepStrictEqual } from "node:util";
+import { parseDocument } from "yaml";
+import { isRecord } from "../../kernel/records.js";
+import { OPENAPI_BASELINES_KEY, valueDigest } from "../digest.js";
+import { buildRecord, entryFor, readBaselineRecord, restatedSurfaces, surfaceIn } from "./record.js";
+/**
+ * Pin every restated path-item key and component of a feature contract against
+ * 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`.
+ */
+export function planOpenapiBaselines(featureText, livingText, _service) {
+    const doc = parseDocument(featureText);
+    if (doc.errors.length > 0)
+        return { text: null, pins: [] };
+    let featPlain;
+    let livingPlain;
+    try {
+        featPlain = doc.toJS() ?? {};
+        const living = parseDocument(livingText);
+        if (living.errors.length > 0)
+            return { text: null, pins: [] };
+        livingPlain = living.toJS() ?? {};
+    }
+    catch {
+        return { text: null, pins: [] };
+    }
+    const current = readBaselineRecord(featPlain).record;
+    const pathItems = new Map();
+    const components = new Map();
+    const pins = [];
+    for (const surface of restatedSurfaces(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.
+        const from = entryFor(current, surface);
+        const base = {
+            kind: surface.kind,
+            target: surface.kind === "path-item" ? `${surface.path} '${surface.key}'` : surface.id,
+        };
+        const livingValue = surfaceIn(livingPlain, surface);
+        if (!livingValue.found) {
+            pins.push({ ...base, status: "unresolved", from: from ?? null, to: null });
+            continue;
+        }
+        const digest = valueDigest(livingValue.value);
+        if (surface.kind === "path-item") {
+            let keys = pathItems.get(surface.path);
+            if (keys === undefined)
+                pathItems.set(surface.path, (keys = new Map()));
+            keys.set(surface.key, digest);
+        }
+        else {
+            components.set(surface.id, digest);
+        }
+        pins.push({
+            ...base,
+            status: from === digest ? "unchanged" : from === undefined ? "pinned" : "repinned",
+            from: from ?? null,
+            to: digest,
+        });
+    }
+    // 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.
+    const rebuilt = buildRecord({ pathItems, components });
+    const written = {};
+    if (Object.keys(rebuilt.pathItems).length > 0)
+        written["pathItems"] = rebuilt.pathItems;
+    if (Object.keys(rebuilt.components).length > 0)
+        written["components"] = rebuilt.components;
+    const raw = isRecord(featPlain) ? featPlain[OPENAPI_BASELINES_KEY] : undefined;
+    if (Object.keys(written).length === 0) {
+        if (raw === undefined)
+            return { text: null, pins };
+        doc.deleteIn([OPENAPI_BASELINES_KEY]);
+        return { text: doc.toString(), pins };
+    }
+    // Deep-equal, not byte-equal: the comparison must ignore key order exactly as
+    // the digests do, so a record an author reordered by hand is left in their
+    // order — and a second run over this function's own sorted output finds the
+    // parse equal and writes nothing, which is the byte-for-byte idempotence
+    // `loam rebase` promises.
+    if (isDeepStrictEqual(raw, written))
+        return { text: null, pins };
+    doc.setIn([OPENAPI_BASELINES_KEY], written);
+    return { text: doc.toString(), pins };
+}
+//# sourceMappingURL=plan.js.map

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

@@ -0,0 +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"]}

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

@@ -0,0 +1,175 @@
+/**
+ * The `x-loam-baselines` record: what it holds, how it reads back, and which
+ * of a feature document's surfaces it may speak for.
+ *
+ * One enumeration (`restatedSurfaces`) shared by the rebase plan, the gate and
+ * the merge, so the three cannot drift into different ideas of what a feature
+ * "restates" — the exact drift the operation axis's shared classifier exists
+ * to prevent. Reading is deliberately permissive-with-problems: a malformed
+ * record is DESCRIBED (`problems`), never diagnosed here — the gate refuses
+ * it, parsers never print, which is doc.ts's own doctrine.
+ */
+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 = [];
+    const record = { pathItems: {}, components: {} };
+    if (!isRecord(plain))
+        return { record, problems };
+    const raw = plain[OPENAPI_BASELINES_KEY];
+    if (raw === undefined)
+        return { record, problems };
+    if (!isRecord(raw)) {
+        problems.push(`${OPENAPI_BASELINES_KEY} is not a mapping`);
+        return { record, problems };
+    }
+    const items = raw["pathItems"];
+    if (items !== undefined) {
+        if (!isRecord(items))
+            problems.push(`${OPENAPI_BASELINES_KEY}.pathItems is not a mapping`);
+        else {
+            for (const [path, keys] of Object.entries(items)) {
+                if (!isRecord(keys)) {
+                    problems.push(`${OPENAPI_BASELINES_KEY}.pathItems['${path}'] is not a mapping`);
+                    continue;
+                }
+                for (const [key, digest] of Object.entries(keys)) {
+                    if (typeof digest !== "string" || !OPERATION_DIGEST_RE.test(digest)) {
+                        problems.push(`${OPENAPI_BASELINES_KEY}.pathItems['${path}']['${key}'] is not a 16-hex digest`);
+                        continue;
+                    }
+                    (record.pathItems[path] ??= {})[key] = digest;
+                }
+            }
+        }
+    }
+    const comps = raw["components"];
+    if (comps !== undefined) {
+        if (!isRecord(comps))
+            problems.push(`${OPENAPI_BASELINES_KEY}.components is not a mapping`);
+        else {
+            for (const [id, digest] of Object.entries(comps)) {
+                if (typeof digest !== "string" || !OPERATION_DIGEST_RE.test(digest)) {
+                    problems.push(`${OPENAPI_BASELINES_KEY}.components['${id}'] is not a 16-hex digest`);
+                    continue;
+                }
+                record.components[id] = digest;
+            }
+        }
+    }
+    for (const key of Object.keys(raw)) {
+        if (key !== "pathItems" && key !== "components")
+            problems.push(`${OPENAPI_BASELINES_KEY}.${key} is not a recognised section`);
+    }
+    return { record, problems };
+}
+/**
+ * Every surface this feature document RESTATES — the enumeration the plan
+ * pins, the gate grades and the merge classifies. Path-item surfaces are the
+ * non-HTTP-method keys (the feature-only markers are bookkeeping, not
+ * surfaces; a METHOD whose value is a removal marker is the operation pin's
+ * territory — but a non-method key is a surface whatever its value looks
+ * like, because skipping the removal SHAPE here once let it through unpinned
+ * and the merge wrote `{x-loam-remove: true}` over a living shared
+ * `parameters` at exit 0). Component surfaces are every
+ * `components/<kind>/<name>` the document declares.
+ */
+export function restatedSurfaces(plain) {
+    const out = [];
+    if (!isRecord(plain))
+        return out;
+    const paths = plain["paths"];
+    if (isRecord(paths)) {
+        for (const [path, item] of Object.entries(paths)) {
+            if (!isRecord(item))
+                continue;
+            for (const [key, value] of Object.entries(item)) {
+                // Methods are the operation pin's territory and the feature-only
+                // markers are bookkeeping; everything else is a surface — INCLUDING a
+                // non-method key whose value happens to be removal-shaped. Skipping
+                // that shape here once let it through unpinned and ungraded, and the
+                // merge then wrote `{x-loam-remove: true}` over a living shared
+                // `parameters` array at exit 0. The merge's own publishable filter
+                // (markers.ts withoutFeatureMarkers) must keep agreeing with this
+                // pair of exclusions — the surfaces test pins the agreement.
+                if (HTTP_METHODS.has(key) || FEATURE_ONLY_KEYS.has(key))
+                    continue;
+                out.push({ kind: "path-item", path, key, value });
+            }
+        }
+    }
+    const comps = plain["components"];
+    if (isRecord(comps)) {
+        for (const [kind, names] of Object.entries(comps)) {
+            if (!isRecord(names))
+                continue;
+            for (const [name, value] of Object.entries(names)) {
+                out.push({ kind: "component", id: `${kind}/${name}`, value });
+            }
+        }
+    }
+    return out;
+}
+/**
+ * The value one plain-parsed document holds for one surface, `found`
+ * distinguishing "absent" from a legal null. ONE spelling for the plan and the
+ * gate, because "does the living contract have this surface" is half of every
+ * verdict — two lookups could disagree about absence, and the disagreement
+ * would surface as a pin graded against the wrong baseline.
+ */
+/**
+ * The record's entry for one surface, or undefined — the mirror of
+ * `surfaceIn`, and one spelling for the same reason: four open-coded lookups
+ * could disagree about absence, and a disagreement surfaces as a pin graded
+ * against the wrong baseline.
+ */
+export function entryFor(record, surface) {
+    return surface.kind === "path-item" ? record.pathItems[surface.path]?.[surface.key] : record.components[surface.id];
+}
+export function surfaceIn(plain, surface) {
+    const absent = { found: false, value: undefined };
+    if (!isRecord(plain))
+        return absent;
+    if (surface.kind === "path-item") {
+        const paths = plain["paths"];
+        if (!isRecord(paths))
+            return absent;
+        const item = paths[surface.path];
+        if (!isRecord(item) || !(surface.key in item))
+            return absent;
+        return { found: true, value: item[surface.key] };
+    }
+    // The first `/` is the kind boundary, exactly as the merge's `#/components/`
+    // regex reads it — OpenAPI component names cannot legally contain one.
+    const cut = surface.id.indexOf("/");
+    const comps = plain["components"];
+    if (!isRecord(comps))
+        return absent;
+    const names = comps[surface.id.slice(0, cut)];
+    const name = surface.id.slice(cut + 1);
+    if (!isRecord(names) || !(name in names))
+        return absent;
+    return { found: true, value: names[name] };
+}
+/**
+ * The record as rebase writes it: lexicographically sorted at every level, so
+ * a second run is byte-identical and diffs stay readable.
+ */
+export function buildRecord(pins) {
+    const sorted = (keys) => [...keys].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    const record = { pathItems: {}, components: {} };
+    for (const path of sorted(pins.pathItems.keys())) {
+        const keys = pins.pathItems.get(path);
+        const entry = {};
+        for (const key of sorted(keys.keys()))
+            entry[key] = keys.get(key);
+        record.pathItems[path] = entry;
+    }
+    for (const id of sorted(pins.components.keys()))
+        record.components[id] = pins.components.get(id);
+    return record;
+}
+//# sourceMappingURL=record.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"record.js","sourceRoot":"","sources":["../../../../src/core/openapi/baseline/record.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The `x-loam-baselines` record: what it holds, how it reads back, and which\n * of a feature document's surfaces it may speak for.\n *\n * One enumeration (`restatedSurfaces`) shared by the rebase plan, the gate and\n * the merge, so the three cannot drift into different ideas of what a feature\n * \"restates\" — the exact drift the operation axis's shared classifier exists\n * to prevent. Reading is deliberately permissive-with-problems: a malformed\n * record is DESCRIBED (`problems`), never diagnosed here — the gate refuses\n * it, parsers never print, which is doc.ts's own doctrine.\n */\nimport { isRecord } from \"../../kernel/records.js\";\nimport { HTTP_METHODS } from \"../doc.js\";\nimport { FEATURE_ONLY_KEYS, OPENAPI_BASELINES_KEY, OPERATION_DIGEST_RE } from \"../digest.js\";\n\n/** The record as read: per-(path, key) digests and per-(kind/name) digests. */\nexport interface BaselineRecord {\n  pathItems: Record<string, Record<string, string>>;\n  components: Record<string, string>;\n}\n\nexport const EMPTY_RECORD: BaselineRecord = { pathItems: {}, components: {} };\n\n/** One surface a feature restates: a path-item non-method key, or a component. */\nexport type RestatedSurface =\n  | { kind: \"path-item\"; path: string; key: string; value: unknown }\n  | { kind: \"component\"; id: string; value: unknown };\n\n/** The record a plain-parsed feature document carries, plus everything wrong with it. */\nexport function readBaselineRecord(plain: unknown): { record: BaselineRecord; problems: string[] } {\n  const problems: string[] = [];\n  const record: BaselineRecord = { pathItems: {}, components: {} };\n  if (!isRecord(plain)) return { record, problems };\n  const raw = plain[OPENAPI_BASELINES_KEY];\n  if (raw === undefined) return { record, problems };\n  if (!isRecord(raw)) {\n    problems.push(`${OPENAPI_BASELINES_KEY} is not a mapping`);\n    return { record, problems };\n  }\n  const items = raw[\"pathItems\"];\n  if (items !== undefined) {\n    if (!isRecord(items)) problems.push(`${OPENAPI_BASELINES_KEY}.pathItems is not a mapping`);\n    else {\n      for (const [path, keys] of Object.entries(items)) {\n        if (!isRecord(keys)) {\n          problems.push(`${OPENAPI_BASELINES_KEY}.pathItems['${path}'] is not a mapping`);\n          continue;\n        }\n        for (const [key, digest] of Object.entries(keys)) {\n          if (typeof digest !== \"string\" || !OPERATION_DIGEST_RE.test(digest)) {\n            problems.push(`${OPENAPI_BASELINES_KEY}.pathItems['${path}']['${key}'] is not a 16-hex digest`);\n            continue;\n          }\n          (record.pathItems[path] ??= {})[key] = digest;\n        }\n      }\n    }\n  }\n  const comps = raw[\"components\"];\n  if (comps !== undefined) {\n    if (!isRecord(comps)) problems.push(`${OPENAPI_BASELINES_KEY}.components is not a mapping`);\n    else {\n      for (const [id, digest] of Object.entries(comps)) {\n        if (typeof digest !== \"string\" || !OPERATION_DIGEST_RE.test(digest)) {\n          problems.push(`${OPENAPI_BASELINES_KEY}.components['${id}'] is not a 16-hex digest`);\n          continue;\n        }\n        record.components[id] = digest;\n      }\n    }\n  }\n  for (const key of Object.keys(raw)) {\n    if (key !== \"pathItems\" && key !== \"components\") problems.push(`${OPENAPI_BASELINES_KEY}.${key} is not a recognised section`);\n  }\n  return { record, problems };\n}\n\n/**\n * Every surface this feature document RESTATES — the enumeration the plan\n * pins, the gate grades and the merge classifies. Path-item surfaces are the\n * non-HTTP-method keys (the feature-only markers are bookkeeping, not\n * surfaces; a METHOD whose value is a removal marker is the operation pin's\n * territory — but a non-method key is a surface whatever its value looks\n * like, because skipping the removal SHAPE here once let it through unpinned\n * and the merge wrote `{x-loam-remove: true}` over a living shared\n * `parameters` at exit 0). Component surfaces are every\n * `components/<kind>/<name>` the document declares.\n */\nexport function restatedSurfaces(plain: unknown): RestatedSurface[] {\n  const out: RestatedSurface[] = [];\n  if (!isRecord(plain)) return out;\n  const paths = plain[\"paths\"];\n  if (isRecord(paths)) {\n    for (const [path, item] of Object.entries(paths)) {\n      if (!isRecord(item)) continue;\n      for (const [key, value] of Object.entries(item)) {\n        // Methods are the operation pin's territory and the feature-only\n        // markers are bookkeeping; everything else is a surface — INCLUDING a\n        // non-method key whose value happens to be removal-shaped. Skipping\n        // that shape here once let it through unpinned and ungraded, and the\n        // merge then wrote `{x-loam-remove: true}` over a living shared\n        // `parameters` array at exit 0. The merge's own publishable filter\n        // (markers.ts withoutFeatureMarkers) must keep agreeing with this\n        // pair of exclusions — the surfaces test pins the agreement.\n        if (HTTP_METHODS.has(key) || FEATURE_ONLY_KEYS.has(key)) continue;\n        out.push({ kind: \"path-item\", path, key, value });\n      }\n    }\n  }\n  const comps = plain[\"components\"];\n  if (isRecord(comps)) {\n    for (const [kind, names] of Object.entries(comps)) {\n      if (!isRecord(names)) continue;\n      for (const [name, value] of Object.entries(names)) {\n        out.push({ kind: \"component\", id: `${kind}/${name}`, value });\n      }\n    }\n  }\n  return out;\n}\n\n/**\n * The value one plain-parsed document holds for one surface, `found`\n * distinguishing \"absent\" from a legal null. ONE spelling for the plan and the\n * gate, because \"does the living contract have this surface\" is half of every\n * verdict — two lookups could disagree about absence, and the disagreement\n * would surface as a pin graded against the wrong baseline.\n */\n/**\n * The record's entry for one surface, or undefined — the mirror of\n * `surfaceIn`, and one spelling for the same reason: four open-coded lookups\n * could disagree about absence, and a disagreement surfaces as a pin graded\n * against the wrong baseline.\n */\nexport function entryFor(record: BaselineRecord, surface: RestatedSurface): string | undefined {\n  return surface.kind === \"path-item\" ? record.pathItems[surface.path]?.[surface.key] : record.components[surface.id];\n}\n\nexport function surfaceIn(plain: unknown, surface: RestatedSurface): { found: boolean; value: unknown } {\n  const absent = { found: false, value: undefined };\n  if (!isRecord(plain)) return absent;\n  if (surface.kind === \"path-item\") {\n    const paths = plain[\"paths\"];\n    if (!isRecord(paths)) return absent;\n    const item = paths[surface.path];\n    if (!isRecord(item) || !(surface.key in item)) return absent;\n    return { found: true, value: item[surface.key] };\n  }\n  // The first `/` is the kind boundary, exactly as the merge's `#/components/`\n  // regex reads it — OpenAPI component names cannot legally contain one.\n  const cut = surface.id.indexOf(\"/\");\n  const comps = plain[\"components\"];\n  if (!isRecord(comps)) return absent;\n  const names = comps[surface.id.slice(0, cut)];\n  const name = surface.id.slice(cut + 1);\n  if (!isRecord(names) || !(name in names)) return absent;\n  return { found: true, value: names[name] };\n}\n\n/**\n * The record as rebase writes it: lexicographically sorted at every level, so\n * a second run is byte-identical and diffs stay readable.\n */\nexport function buildRecord(pins: { pathItems: Map<string, Map<string, string>>; components: Map<string, string> }): BaselineRecord {\n  const sorted = (keys: Iterable<string>): string[] => [...keys].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));\n  const record: BaselineRecord = { pathItems: {}, components: {} };\n  for (const path of sorted(pins.pathItems.keys())) {\n    const keys = pins.pathItems.get(path)!;\n    const entry: Record<string, string> = {};\n    for (const key of sorted(keys.keys())) entry[key] = keys.get(key)!;\n    record.pathItems[path] = entry;\n  }\n  for (const id of sorted(pins.components.keys())) record.components[id] = pins.components.get(id)!;\n  return record;\n}\n"]}