mandrel 1.57.0

package/.agents/scripts/lib/baselines/scope.js

@@ -0,0 +1,291 @@
+// .agents/scripts/lib/baselines/scope.js
+//
+// Story #1962 / Task #1970 — One ScopeResolution helper that the
+// `check-baselines.js` dispatcher and the per-kind regression writers
+// (Epic #1943) both consume. Routing every scope decision through this
+// single function is what guarantees read/write parity: the dispatcher
+// can never decide "diff against epic/1943" while the writer assumes
+// "full repo", because both call `resolveScope()` with the same inputs.
+//
+// The resolver is intentionally pure — it takes already-extracted
+// inputs and returns a frozen ScopeResolution. CLI parsing, env
+// reading, and config loading happen in the caller; that keeps this
+// module trivially testable and prevents the precedence rules from
+// being silently re-implemented at every call site.
+//
+// Precedence (highest → lowest):
+//
+//   1. CLI flags — `cliFlags.fullScope: true` or `cliFlags.changedSinceRef`.
+//      Operator-typed beats anything in env/config. A CLI override of
+//      `--full-scope` wins even if the config says `'diff'`.
+//   2. Environment — `BASELINE_SCOPE` ('full' | 'diff') and
+//      `BASELINE_REF` (any git ref). The dispatcher reads these from
+//      `process.env` and forwards via `cliFlags.envScope` /
+//      `cliFlags.envRef` so the resolver itself never touches process
+//      state. CI usually sets these.
+//   3. Config — `configScope` ('full' | 'diff') and `configRef` (any
+//      git ref) from `delivery.quality.gateScoping` in `.agentrc.json`.
+//   4. Default — `mode='diff'` against `ref='main'`. This is the
+//      framework-wide fallback when nothing else is configured.
+//
+// Missing-ref fallback: when the resolved mode is `'diff'` but no ref
+// is supplied at any layer, the resolver falls back to `'main'` rather
+// than producing a half-resolved scope with `ref=null`. The dispatcher
+// would have to invent a default anyway; centralising it here keeps
+// every gate aligned.
+//
+// `kind` (e.g. `'lint'`, `'coverage'`, `'crap'`) is currently echoed
+// through to the resolution unchanged. The argument exists so future
+// per-kind overrides (e.g. "lint always runs full") have a place to
+// land without breaking call signatures. Today: pass it; ignore it.
+//
+// Returned shape:
+//
+//   {
+//     kind: string,        // echoed back for caller convenience
+//     mode: 'full' | 'diff',
+//     ref:  string | null, // null in full mode; ref string in diff mode
+//     files: Set<string>,  // empty Set in full mode (sentinel for "all")
+//     source: string,      // which layer won (debug / friction signal)
+//   }
+//
+// `files` is intentionally a Set rather than an Array — callers
+// repeatedly check membership during per-row filtering, and Set lookup
+// is O(1). An empty Set in `'full'` mode means "no filter applies".
+// A non-empty Set in `'diff'` mode means "only these paths are in
+// scope" (the dispatcher pre-computes them via `git diff --name-only`
+// and forwards via `cliFlags.changedFiles`); when omitted, the writer
+// is expected to compute the diff itself against `ref`.
+
+const VALID_MODES = new Set(['full', 'diff']);
+const DEFAULT_DIFF_REF = 'main';
+
+/**
+ * Coerce a candidate value to a non-empty string, or `null`.
+ *
+ * @param {unknown} v
+ * @returns {string | null}
+ */
+function asNonEmptyString(v) {
+  return typeof v === 'string' && v.length > 0 ? v : null;
+}
+
+/**
+ * Coerce a candidate scope value to one of the canonical modes, or
+ * `null` if it is not a recognised mode. Unknown strings are dropped
+ * rather than coerced — the layer "did not specify" rather than
+ * "specified an invalid value".
+ *
+ * @param {unknown} v
+ * @returns {'full' | 'diff' | null}
+ */
+function asMode(v) {
+  return typeof v === 'string' && VALID_MODES.has(v) ? v : null;
+}
+
+/**
+ * Coerce a candidate set/array of files to a frozen Set. Returns an
+ * empty Set when the input is missing or empty.
+ *
+ * @param {unknown} v
+ * @returns {Set<string>}
+ */
+function asFilesSet(v) {
+  if (v instanceof Set) {
+    return new Set(
+      Array.from(v).filter((f) => typeof f === 'string' && f.length > 0),
+    );
+  }
+  if (Array.isArray(v)) {
+    return new Set(v.filter((f) => typeof f === 'string' && f.length > 0));
+  }
+  return new Set();
+}
+
+/**
+ * Resolve a scope against the layered precedence (CLI > env > config >
+ * default). Pure; no I/O.
+ *
+ * @param {object} input
+ * @param {string} input.kind         - Baseline kind (e.g. `'lint'`).
+ * @param {string} [input.configScope] - `'full'` | `'diff'` from agentrc.
+ * @param {string} [input.configRef]   - Diff ref from agentrc.
+ * @param {object} [input.cliFlags]    - Pre-parsed CLI / env layer.
+ * @param {boolean} [input.cliFlags.fullScope]      - `--full-scope`.
+ * @param {string}  [input.cliFlags.changedSinceRef] - `--changed-since <ref>`.
+ * @param {string}  [input.cliFlags.envScope]        - From `BASELINE_SCOPE`.
+ * @param {string}  [input.cliFlags.envRef]          - From `BASELINE_REF`.
+ * @param {Iterable<string>} [input.cliFlags.changedFiles]
+ *        Pre-computed diff paths (when caller already ran `git diff
+ *        --name-only`). Becomes `files`; only meaningful in `'diff'` mode.
+ * @returns {{
+ *   kind: string,
+ *   mode: 'full' | 'diff',
+ *   ref: string | null,
+ *   files: Set<string>,
+ *   source: string,
+ * }}
+ */
+export function resolveScope(input = {}) {
+  const kind =
+    typeof input.kind === 'string' && input.kind.length > 0
+      ? input.kind
+      : 'unknown';
+  const cli = input.cliFlags ?? {};
+
+  // ---- Layer 1: CLI flags (highest precedence) -------------------------
+  if (cli.fullScope === true) {
+    return Object.freeze({
+      kind,
+      mode: 'full',
+      ref: null,
+      files: new Set(),
+      source: 'cli:--full-scope',
+    });
+  }
+  const cliRef = asNonEmptyString(cli.changedSinceRef);
+  if (cliRef) {
+    return Object.freeze({
+      kind,
+      mode: 'diff',
+      ref: cliRef,
+      files: asFilesSet(cli.changedFiles),
+      source: 'cli:--changed-since',
+    });
+  }
+
+  // ---- Layer 2: Environment (extracted by caller into cliFlags.env*) ---
+  const envMode = asMode(cli.envScope);
+  if (envMode === 'full') {
+    return Object.freeze({
+      kind,
+      mode: 'full',
+      ref: null,
+      files: new Set(),
+      source: 'env:BASELINE_SCOPE=full',
+    });
+  }
+  const envRef = asNonEmptyString(cli.envRef);
+  if (envMode === 'diff' || envRef) {
+    return Object.freeze({
+      kind,
+      mode: 'diff',
+      ref: envRef ?? DEFAULT_DIFF_REF,
+      files: asFilesSet(cli.changedFiles),
+      source: envRef ? 'env:BASELINE_REF' : 'env:BASELINE_SCOPE=diff',
+    });
+  }
+
+  // ---- Layer 3: Config (delivery.quality.gateScoping) -----------------
+  const cfgMode = asMode(input.configScope);
+  if (cfgMode === 'full') {
+    return Object.freeze({
+      kind,
+      mode: 'full',
+      ref: null,
+      files: new Set(),
+      source: 'config:gateScoping.scope=full',
+    });
+  }
+  const cfgRef = asNonEmptyString(input.configRef);
+  if (cfgMode === 'diff' || cfgRef) {
+    return Object.freeze({
+      kind,
+      mode: 'diff',
+      ref: cfgRef ?? DEFAULT_DIFF_REF,
+      files: asFilesSet(cli.changedFiles),
+      source: cfgRef
+        ? 'config:gateScoping.diffRef'
+        : 'config:gateScoping.scope=diff',
+    });
+  }
+
+  // ---- Layer 4: Default ------------------------------------------------
+  return Object.freeze({
+    kind,
+    mode: 'diff',
+    ref: DEFAULT_DIFF_REF,
+    files: asFilesSet(cli.changedFiles),
+    source: 'default',
+  });
+}
+
+/**
+ * Generic scope-aware row merge for s-diff-scoped-writes (Story #1974).
+ *
+ * Each per-kind module re-exports a thin wrapper that pins `scopeKey` to
+ * the field used to identify the file the row belongs to (path / route /
+ * bundle). This helper does the actual merge:
+ *
+ *   - `scope.mode === 'full'` (or `scope` is null/undefined / `scope.files`
+ *     is empty): regenerated wins everywhere — returned as-is. This keeps
+ *     the legacy "always rewrite" behaviour intact when no scope filter is
+ *     applied.
+ *   - `scope.mode === 'diff'`: rows whose `scopeKey` value is OUTSIDE
+ *     `scope.files` are preserved from `prior` verbatim. Rows whose
+ *     `scopeKey` value is INSIDE `scope.files` are taken from
+ *     `regenerated` (the regenerated values for in-scope files). Prior
+ *     rows for in-scope files are dropped (regen replaces them); regen
+ *     rows for out-of-scope files are dropped (the writer should not have
+ *     computed them, but we filter defensively).
+ *   - Missing `prior` (null / undefined / empty) — regenerated wins
+ *     everywhere; behaves like full mode.
+ *
+ * Identity matching uses the per-kind `identity(row)` function — for
+ * coverage / lint / maintainability / mutation / lighthouse / bundle-size
+ * the identity is the keyField value; for crap it's a composite
+ * `path::method@startLine`. The merge preserves row ordering by
+ * concatenating in-scope regen rows then out-of-scope prior rows; the
+ * downstream `sortRows` from the per-kind module re-sorts before write.
+ *
+ * Pure. No I/O.
+ *
+ * @template TRow
+ * @param {object} args
+ * @param {Array<TRow>|null|undefined} args.prior
+ * @param {Array<TRow>|null|undefined} args.regenerated
+ * @param {{mode?: 'full'|'diff', files?: Set<string>|Iterable<string>}|null|undefined} args.scope
+ * @param {(row: TRow) => string} args.scopeKey  Per-kind scope-key extractor — returns the
+ *        file path / route / bundle name used to match against `scope.files`.
+ * @param {(row: TRow) => string} [args.identity] Per-kind identity extractor — defaults to
+ *        the same as `scopeKey`. CRAP overrides this with `path::method@startLine`.
+ * @returns {Array<TRow>}
+ */
+export function mergeRowsByScope({
+  prior,
+  regenerated,
+  scope,
+  scopeKey,
+  identity,
+} = {}) {
+  const regenRows = Array.isArray(regenerated) ? regenerated : [];
+  const priorRows = Array.isArray(prior) ? prior : [];
+  if (typeof scopeKey !== 'function') {
+    throw new TypeError('mergeRowsByScope: scopeKey must be a function');
+  }
+  const idFn = typeof identity === 'function' ? identity : scopeKey;
+
+  // No scope filter / full mode / no prior → regen wins everywhere.
+  const mode = scope?.mode;
+  if (!scope || mode === 'full' || priorRows.length === 0) {
+    return regenRows.slice();
+  }
+
+  // Coerce scope.files to a Set for O(1) membership tests. An empty Set in
+  // diff mode means "no files in scope" — every prior row is preserved
+  // and every regen row is dropped (defensive: writer feeds in-scope rows).
+  const filesSet =
+    scope.files instanceof Set ? scope.files : new Set(scope.files ?? []);
+
+  // In-scope regen rows: keep regen.
+  const regenInScope = regenRows.filter((row) => filesSet.has(scopeKey(row)));
+  // Out-of-scope prior rows: keep prior, but drop any whose identity
+  // collides with an in-scope regen row (defensive — should not happen
+  // since identity within a kind is keyField-derived).
+  const inScopeIds = new Set(regenInScope.map((row) => idFn(row)));
+  const priorOutOfScope = priorRows.filter(
+    (row) => !filesSet.has(scopeKey(row)) && !inScopeIds.has(idFn(row)),
+  );
+
+  return regenInScope.concat(priorOutOfScope);
+}

package/.agents/scripts/lib/baselines/writer.js

@@ -0,0 +1,312 @@
+/**
+ * writer.js — shared baseline writer (Story #1891, Epic #1786).
+ *
+ * Every legacy baseline-refresh script (`update-crap-baseline.js`,
+ * `update-maintainability-baseline.js`, `lib/coverage-baseline.js`,
+ * `lib/auto-refresh-baselines.js`) used to assemble its own envelope and
+ * call `fs.writeFileSync`. That meant the path canonicalisation, rollup
+ * math, kernel-version stamping, and JSON-serialisation conventions were
+ * duplicated five-ish times, each with subtly different rules. The
+ * worktree-prefix bug that prompted Story #1891 is the proof: each
+ * refresh path had to remember to strip `.worktrees/<workspace>/` on its
+ * own, and the maintainability path forgot.
+ *
+ * `write({ kind, rows, components, kernelVersion?, generatedAt? })` is
+ * the single funnel:
+ *
+ *   1. Look up the per-kind module via the kernel registry. The module
+ *      declares the `keyField`, `projectRow`, `sortRows`, `rollup`, and
+ *      `kernelVersion()` functions.
+ *   2. Run every row through `projectRow` — that's where the path is
+ *      canonicalised via `path-canon.canonicalise()`. After projection,
+ *      the writer asserts every key field is already canonical
+ *      (`path-canon.assertCanonical()`), refusing to silently rewrite
+ *      identity.
+ *   3. Sort the rows for deterministic on-disk diffs.
+ *   4. Compute the per-component rollup (always including `*`).
+ *   5. Stamp the envelope via `buildEnvelope` — `$schema`, `kernelVersion`,
+ *      `generatedAt`.
+ *   6. Validate the envelope via `assertEnvelope` (AJV against the per-kind
+ *      schema).
+ *   7. Return the envelope object. Callers serialise via `writeFile()`
+ *      (separate seam so tests can round-trip without touching disk).
+ *
+ * `writeFile(absPath, envelope)` is the serialise + flush seam. It
+ * stringifies the envelope with two-space indent, appends a trailing
+ * newline, creates the parent directory, and writes atomically (write to
+ * `<path>.tmp` then `rename` — `rename` is atomic on every platform we
+ * support).
+ *
+ * @module lib/baselines/writer
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { deepEqual } from '../json-utils.js';
+import { assertEnvelope, buildEnvelope } from './envelope.js';
+import { currentKernelVersion, getKindModule } from './kernel.js';
+import { assertCanonical } from './path-canon.js';
+
+/**
+ * Assemble + validate a baseline envelope. Returns the envelope object
+ * (no disk I/O). Callers feed the result into `writeFile()` when they're
+ * ready to persist.
+ *
+ * Story #1964 (s-stability-epsilon) added the optional `prior` and
+ * `epsilon` parameters. When both are present, the writer calls the
+ * per-kind `applyEpsilon(prior, regenerated, epsilon)` stabilizer
+ * **after** projection but **before** sort/rollup/serialise. Sub-epsilon
+ * row deltas resolve to the prior bytes, so env variance never rewrites
+ * the on-disk envelope. When either is absent (`undefined`), behaviour is
+ * unchanged from the pre-#1964 contract — this is regression-fail-safe by
+ * design so existing call sites stay untouched.
+ *
+ * Story #1974 (s-diff-scoped-writes) added the optional `scope` parameter.
+ * When `scope` is present *and* `prior` is supplied, the writer calls the
+ * per-kind `mergeRows(prior, projected, scope)` filter **after** projection
+ * but **before** `applyEpsilon`. The composition is intentional: scope-
+ * filter first (preserve out-of-scope prior rows verbatim), then stabilise
+ * the in-scope rows against the same prior under epsilon. The merged result
+ * is sorted, rolled up, and serialised exactly as before. When `scope` is
+ * absent (or `prior` is absent), behaviour is unchanged from the pre-#1974
+ * contract — also regression-fail-safe.
+ *
+ * `prior` MUST be an array of rows already in canonical (per-kind
+ * `projectRow`) shape — the on-disk baseline format is canonical
+ * end-to-end, and the writer no longer re-projects prior rows on entry.
+ *
+ * Story #2135 (Task #2146) added the structural-equality short-circuit on
+ * top of `prior`. When a `prior` envelope (or `priorEnvelope`) is supplied
+ * and the projected `rows + rollup` deep-equal the prior's `rows + rollup`,
+ * the writer returns the prior envelope unchanged — same `generatedAt`,
+ * same kernelVersion, same byte payload. Without this guard every
+ * auto-refresh that ran on a no-op Story would stamp a fresh
+ * `generatedAt` and surface a spurious one-line diff. The short-circuit
+ * is the semantic replacement for the legacy byte-equality compare that
+ * lived in `baseline-snapshot.js`.
+ *
+ * @param {{
+ *   kind: string,
+ *   rows: Array<object>,
+ *   components?: Array<object>,
+ *   kernelVersion?: string,
+ *   generatedAt?: string,
+ *   prior?: Array<object>,
+ *   priorEnvelope?: object,
+ *   epsilon?: number,
+ *   scope?: {mode: 'full'|'diff', files: Set<string>|Iterable<string>}|null,
+ * }} params
+ * @returns {object}
+ */
+export function write({
+  kind,
+  rows,
+  components,
+  kernelVersion,
+  generatedAt,
+  prior,
+  priorEnvelope,
+  epsilon,
+  scope,
+} = {}) {
+  if (typeof kind !== 'string' || kind.length === 0) {
+    throw new TypeError('writer.write: kind is required');
+  }
+  if (!Array.isArray(rows)) {
+    throw new TypeError('writer.write: rows must be an array');
+  }
+
+  const mod = getKindModule(kind);
+  const projected = rows.map((row, idx) => {
+    try {
+      return mod.projectRow(row);
+    } catch (err) {
+      throw new Error(
+        `writer.write: failed to project ${kind} row at index ${idx}: ${err.message}`,
+      );
+    }
+  });
+
+  // Defensive: assert every key field on the projected rows is canonical.
+  // The per-kind `projectRow` already funnels paths through `canonicalise`,
+  // but the assertion catches a future per-kind module that forgets — and
+  // catches absolute paths in inputs that the canonicaliser would also
+  // throw on (we surface a writer-scoped error pointing at the row).
+  if (mod.keyField === 'path') {
+    projected.forEach((row, idx) => {
+      try {
+        assertCanonical(row.path);
+      } catch (err) {
+        throw new Error(
+          `writer.write: ${kind} row at index ${idx} has a non-canonical path: ${err.message}`,
+        );
+      }
+    });
+  }
+
+  const merged = scopeMergeRows(mod, projected, prior, scope);
+  const stabilised = stabiliseRows(mod, merged, prior, epsilon);
+
+  const sortedRows = mod.sortRows(stabilised);
+  const rollup = mod.rollup(sortedRows, components ?? []);
+
+  // The rollup() implementations always seed `*` from `aggregate()`, but
+  // the AC pins this explicitly: the envelope ALWAYS carries `*` even
+  // when `components` is undefined or empty. Belt-and-braces.
+  if (!Object.hasOwn(rollup, '*')) {
+    throw new Error(
+      `writer.write: ${kind} rollup is missing the required "*" key`,
+    );
+  }
+
+  // Story #2135 / Task #2146 — structural-equality short-circuit. When the
+  // caller supplies a `priorEnvelope` (or, for backwards-compatibility, the
+  // bare `prior` array is itself a full envelope object), and the projected
+  // rows + rollup deep-equal what's on the prior, return the prior envelope
+  // unchanged. This is the semantic replacement for the byte-equality
+  // compare in `baseline-snapshot.js` and is what makes a no-op auto-refresh
+  // produce a zero-byte baseline diff.
+  const priorEnv = resolvePriorEnvelope(priorEnvelope, prior);
+  if (
+    priorEnv &&
+    deepEqual(sortedRows, priorEnv.rows) &&
+    deepEqual(rollup, priorEnv.rollup)
+  ) {
+    // Re-validate defensively before returning so a caller cannot smuggle
+    // an invalid envelope through the short-circuit.
+    assertEnvelope(priorEnv);
+    return priorEnv;
+  }
+
+  const envelope = buildEnvelope({
+    kind,
+    rows: sortedRows,
+    rollup,
+    kernelVersion: kernelVersion ?? currentKernelVersion(kind),
+    generatedAt,
+  });
+  assertEnvelope(envelope);
+  return envelope;
+}
+
+/**
+ * Resolve the prior envelope used by the structural-equality short-circuit.
+ * Accepts either an explicit `priorEnvelope` (preferred) or, for backwards
+ * compatibility, recognises when `prior` is itself a full envelope object
+ * carrying `rows` + `rollup` rather than a bare rows array. Returns null
+ * when neither yields a usable envelope — the short-circuit is opt-in by
+ * design.
+ */
+function resolvePriorEnvelope(priorEnvelope, prior) {
+  if (
+    priorEnvelope &&
+    typeof priorEnvelope === 'object' &&
+    !Array.isArray(priorEnvelope) &&
+    Array.isArray(priorEnvelope.rows) &&
+    priorEnvelope.rollup &&
+    typeof priorEnvelope.rollup === 'object'
+  ) {
+    return priorEnvelope;
+  }
+  if (
+    prior &&
+    typeof prior === 'object' &&
+    !Array.isArray(prior) &&
+    Array.isArray(prior.rows) &&
+    prior.rollup &&
+    typeof prior.rollup === 'object'
+  ) {
+    return prior;
+  }
+  return null;
+}
+
+/**
+ * Serialise an envelope to `absPath`. Deterministic: two-space indent,
+ * trailing newline, sorted keys for the top-level envelope keys (rows are
+ * already sorted by the per-kind module's `sortRows`). Atomic: writes to
+ * `<absPath>.tmp` then `rename`s onto the destination so a crash mid-write
+ * never leaves a half-flushed envelope on disk.
+ *
+ * Story #2135 / Task #2146 — the optional `fsImpl` seam lets tests inject
+ * a virtual filesystem (or an in-memory recorder) the way the legacy
+ * saver helpers allowed. Production callers omit it and fall through to
+ * `node:fs`. The seam covers `mkdirSync`, `writeFileSync`, and
+ * `renameSync` — the three calls this function actually makes — so a mock
+ * that exposes a subset of `fs` works without leaking real disk I/O.
+ *
+ * Backwards-compatible: two-argument callers (`writeFile(abs, env)`)
+ * continue to work unchanged.
+ *
+ * @param {string} absPath
+ * @param {object} envelope
+ * @param {{ fsImpl?: { mkdirSync: typeof fs.mkdirSync, writeFileSync: typeof fs.writeFileSync, renameSync: typeof fs.renameSync } }} [opts]
+ * @returns {string}  The absolute path written.
+ */
+export function writeFile(absPath, envelope, opts = {}) {
+  if (typeof absPath !== 'string' || !path.isAbsolute(absPath)) {
+    throw new TypeError(
+      `writer.writeFile: absPath must be an absolute path (got ${JSON.stringify(absPath)})`,
+    );
+  }
+  // Re-validate at the seam — a caller might mutate the envelope between
+  // `write()` and `writeFile()`.
+  assertEnvelope(envelope);
+
+  const fsImpl = opts?.fsImpl ? opts.fsImpl : fs;
+
+  // Canonical key order on the top-level envelope keeps diffs stable
+  // across runs and platforms. Per-kind row keys retain their natural
+  // declaration order; the row sort is done by `sortRows()`.
+  const canonical = {
+    $schema: envelope.$schema,
+    kernelVersion: envelope.kernelVersion,
+    generatedAt: envelope.generatedAt,
+    rollup: envelope.rollup,
+    rows: envelope.rows,
+  };
+
+  const tmpPath = `${absPath}.tmp`;
+  fsImpl.mkdirSync(path.dirname(absPath), { recursive: true });
+  fsImpl.writeFileSync(tmpPath, `${JSON.stringify(canonical, null, 2)}\n`);
+  fsImpl.renameSync(tmpPath, absPath);
+  return absPath;
+}
+
+/**
+ * Story #1974 — s-diff-scoped-writes scope-merge dispatch. When `scope` is
+ * present, defer to the per-kind `mergeRows(prior, projected, scope)` to
+ * preserve out-of-scope prior rows verbatim. Returns `projected` unchanged
+ * when `scope` is omitted, when the kind doesn't ship the merger
+ * (forward-compatible), or when `prior` is absent (nothing to preserve).
+ */
+function scopeMergeRows(mod, projected, prior, scope) {
+  if (scope === undefined || scope === null) return projected;
+  if (typeof mod.mergeRows !== 'function') return projected;
+  // mergeRows treats null/undefined/empty prior as "no preservation needed"
+  // and returns projected verbatim — that branch is covered upstream and
+  // here for symmetry.
+  return mod.mergeRows(prior ?? [], projected, scope);
+}
+
+/**
+ * Story #1964 — s-stability-epsilon stabilizer dispatch. When both
+ * `prior` and `epsilon` are present, fold sub-epsilon row deltas back to
+ * the prior bytes via the per-kind `applyEpsilon`. Returns `projected`
+ * unchanged when either is omitted, or when the kind doesn't ship the
+ * stabilizer (forward-compatible).
+ */
+function stabiliseRows(mod, projected, prior, epsilon) {
+  if (prior === undefined || epsilon === undefined) return projected;
+  if (!Array.isArray(prior)) {
+    throw new TypeError('writer.write: prior must be an array when provided');
+  }
+  if (typeof epsilon !== 'number' || !Number.isFinite(epsilon) || epsilon < 0) {
+    throw new TypeError(
+      `writer.write: epsilon must be a non-negative finite number (got ${JSON.stringify(epsilon)})`,
+    );
+  }
+  return typeof mod.applyEpsilon === 'function'
+    ? mod.applyEpsilon(prior, projected, epsilon)
+    : projected;
+}