@dzhechkov/harness-core 0.8.35 → 0.8.36

package/src/publish.ts

@@ -21,7 +21,7 @@ type ExecSyncOptionsWithStringEncoding = NonNullable<Parameters<typeof execSync>
 import { createHash } from 'node:crypto';
 
 import { claimCheck } from './claim-check.js';
-import { rewriteReleaseLine } from './release-line.js';
+import { rewriteReleaseLine, isReleaseLineToken } from './release-line.js';
 import { packedTarballName } from './packed-install-smoke.js';
 
 export type ProbeOutcome = {
@@ -54,6 +54,21 @@ export interface PublishResult {
    * unmodified `publishPackages` call is byte-compatible with pre-gate behavior.
    */
   readonly claimCheck?: { readonly findings: number; readonly high: number } | undefined;
+  /**
+   * FR-3 (feature publish-readme-stamp-scope): a preview of what `planReadmeVersionSync` would do
+   * (dry-run) or already did (live) to this package's own README.md — never silent about the
+   * lock-step sync. `lines` are the 1-based line numbers actually rewritten; `skippedHistorical` is
+   * a TOKEN count (changelog-region entries + tokens outside every recognised ALLOWLIST shape), not
+   * a line count; `historyLines` names WHERE those kept-as-history tokens sit (fix-round 1, Codex
+   * HIGH: "history has only an aggregate count, not locations"). Absent when the package has no
+   * README.md, or on an 'error' result where the sync never ran/mattered.
+   */
+  readonly readmeSync?: {
+    readonly rewrittenLines: number;
+    readonly lines: readonly number[];
+    readonly skippedHistorical: number;
+    readonly historyLines: readonly number[];
+  } | undefined;
   /**
    * DRY-RUN ONLY, and the reason it exists is a measured incident. A dry run short-circuits
    * BEFORE build, sign and pack (see the `opts.dryRun` branch below), so the package's own
@@ -501,15 +516,177 @@ export function orderByDependencies<T extends { name: string; dir: string }>(pkg
   return ordered;
 }
 
+/** One README line the sync touched: 1-based line number, and the line before/after the rewrite. */
+export interface ReadmeSyncRewrite {
+  readonly line: number;
+  readonly before: string;
+  readonly after: string;
+}
+
+/** The report `planReadmeVersionSync` returns — never silent about what it did and did not touch. */
+export interface ReadmeVersionSyncPlan {
+  readonly text: string;
+  readonly rewritten: readonly ReadmeSyncRewrite[];
+  /** Count of OLD-VERSION token OCCURRENCES left untouched as history (changelog region + every
+   *  token outside every recognised ALLOWLIST shape — FR-1). */
+  readonly skippedHistorical: number;
+  /** The 1-based line numbers carrying at least one of those kept-as-history tokens (fix-round 1,
+   *  Codex HIGH: "history has only an aggregate count, not locations; rewritten lines have
+   *  numbers"). Deduplicated and sorted ascending — a line with two skipped tokens appears once. */
+  readonly historyLines: readonly number[];
+}
+
+/**
+ * A line carrying this HTML comment opts BACK IN to rewriting, overriding both the changelog-region
+ * protection and the allowlist below — the author's explicit "this token is a stamp, not history"
+ * (AC-3).
+ */
+const DZ_VERSION_MARKER = '<!-- dz:version -->';
+
+/**
+ * Shape 4 of the allowlist (fix-round 1 design): the `dz publish` CLI's own example line, quoted
+ * verbatim in a README — `dz publish: tarball <name>@X sha256:…`. In practice every occurrence of
+ * this line is ALSO caught by shape 3 (the version always follows `<name>@`), so this predicate is
+ * mostly documentation of intent — named explicitly because the design brief calls it out as its own
+ * recognised shape, not an accident of shape 3's reach.
+ */
+// Codex r2 HIGH (lead): the tarball example line grants NO whole-line permission any more — its
+// only stampable token is `<name>@X`, which shape 3 (install/pin) already recognises; a trailing
+// `measured on X` on the same example line stays history.
+
+/**
+ * Shape 2 of the allowlist: a current-release FOOTER PREFIX — a short declarative label stamping the
+ * package's OWN current version (`Status: `, `Current release: `, `Current status: `, `Released as `),
+ * optionally preceded by a list marker or bold-open, with the label being the ENTIRE prefix up to the
+ * token — `Status: vX is current.` allows `vX` because nothing but the label sits before it. This is
+ * deliberately POSITION-AWARE (tested against the text before the token, not "does this line contain
+ * the word somewhere"): a line that opens with a footer label but cites an UNRELATED older version
+ * later in the same sentence — `Current release: 1.0.0. (Previous release (v1.1.0 / v1.0.0) …)` —
+ * must allow only the first token, not the second one sitting deep in a citation. `Previous release
+ * (vA / vB)` itself never matches at all: it opens with "Previous", not "release".
+ */
+// Codex r2 HIGH (lead): exactly the three settled footer labels, at line start, colon required —
+// `Status:`, `Version:`, `Current release:` (optional bold / list marker). `Note: X`, `Released X`
+// and every other label stay history.
+// The settled label set (Codex r2 HIGH, lead): `Status:`, `Version:`, `Current release:`,
+// `Current status:` (colon required, optional bold / list marker) and the original footer
+// sentence `Released as vX` — the shapes the 2026-08-25 tests pin. `Note: X`, `Released X on …`,
+// `Status as of X` and every other label are history.
+const FOOTER_STAMP_PREFIX_RE = /^\s*(?:[-*+]\s+)?(?:(?:\*\*)?(?:status|version|current release|current status)(?::\*\*|\*\*:|:)|released as)\s*$/i;
+
+/**
+ * Shape 6 of the allowlist: a shields.io-style badge URL segment — `badge/npm-v0.7.7-…` or
+ * `badge/version-0.7.7-…`. Scoped to the literal `/badge/` marker (not a bare "-v" anywhere) so an
+ * unrelated hyphenated token elsewhere on the line is never mistaken for a badge.
+ */
+// Codex r2 HIGH (lead): a badge segment counts only inside a shields.io badge URL, not any `/badge/` path.
+const BADGE_SEGMENT_RE = /img\.shields\.io\/badge\/[\w.%-]*$/i;
+
+/**
+ * Shape 3 of the allowlist: an install/dependency-pin context. Either the token is immediately
+ * preceded by `@` (`npm i @dzhechkov/harness-core@0.7.6`, the tarball example's `<name>@X`), or it
+ * sits in the JSON-pin shape `"<package-name>": "X"` (a `package.json`/lockfile-style dependency pin
+ * quoted in prose) — the design brief's "for the JSON-pin form accept `\": \"` before the token when
+ * the key is a package name".
+ */
+function isInstallPinContext(line: string, tokenStart: number): boolean {
+  // Codex r2 HIGH (lead): `@X` counts only as `<name>@X` — a package-name character must precede the
+  // `@` (`thing@0.8.25`, `@scope/name@0.8.25`); a bare `see @0.8.25` stays history.
+  if (line[tokenStart - 1] === '@' && /[A-Za-z0-9._-]/.test(line[tokenStart - 2] ?? '')) return true;
+  const before = line.slice(0, tokenStart);
+  return /"[@A-Za-z0-9][\w./-]*"\s*:\s*"$/.test(before);
+}
+
+/**
+ * FR-1 (POSITIVE ALLOWLIST, not a denylist — Codex fix-round 1, 2026-09-15). Outside a changelog
+ * region, an old-version token occurrence rewrites ONLY when it sits in one of six recognised
+ * shapes — the lock-step feature this sync exists for, and NOTHING beyond it. Every shape NOT named
+ * here defaults to HISTORY, whatever prose it is written in: the previous design (a denylist of
+ * three named citation phrases — "on X", "X alike", "/ vX") was corruptible by construction, because
+ * ANY new prose shape citing the outgoing version ("since X", "measured against X", "X behaviour", a
+ * bare "X" in a sentence) rewrote by default until someone thought to deny it too. An allowlist has
+ * no such gap: an unrecognised shape is history by default, not by enumeration.
+ *
+ *  1. a release-line token — `` `harness-core vX` · `harness-cli vY` `` and any generalised
+ *     `` `<name> vX` `` on the same line, including a trailing `` · `memory vZ` `` segment
+ *     (release-line.ts `isReleaseLineToken`/`GENERIC_RELEASE_TOKEN_RE`).
+ *  2. a current-release FOOTER prefix (`FOOTER_STAMP_PREFIX_RE`) — position-aware, so only the
+ *     token immediately after the label is allowed.
+ *  3. an install/dependency-pin context (`isInstallPinContext`).
+ *  4. the `dz publish: tarball <name>@X sha256:…` example line (`TARBALL_EXAMPLE_LINE_RE`).
+ *  5. (handled by the caller, not here) a `<!-- dz:version -->` marker forces the rewrite outright,
+ *     overriding this predicate AND the changelog-region protection (AC-3).
+ *  6. a shields badge URL segment (`BADGE_SEGMENT_RE`).
+ */
+function isAllowlistedRewriteContext(line: string, tokenStart: number, versionEnd: number): boolean {
+  if (isReleaseLineToken(line, tokenStart, versionEnd)) return true; // shape 1
+  if (FOOTER_STAMP_PREFIX_RE.test(line.slice(0, tokenStart))) return true; // shape 2
+  if (isInstallPinContext(line, tokenStart)) return true; // shape 3 (also covers the tarball example's `<name>@X`)
+  if (BADGE_SEGMENT_RE.test(line.slice(0, tokenStart))) return true; // shape 6 (shields.io only)
+  return false;
+}
+
 /**
- * Sync a package's own README to a freshly-bumped version: every exact occurrence of the OLD
- * version token (optionally `v`-prefixed, word-bounded) becomes the new one.
+ * Plan how a README's OLD-VERSION tokens would move to NEW-VERSION — a pure function, no I/O.
  *
- * This kills the perpetual footer off-by-one: publish bumps package.json DURING publishing, so a
- * hand-synced "vX.Y.Z" status line was always one release behind on npmjs.com (or required
- * pre-setting the future version by hand). Exact-old-token matching keeps every other version
- * string (dependency pins, historical notes, examples citing other releases) untouched.
- * Returns the pre-sync README text for failure restore, or undefined when nothing was rewritten.
+ * FR-1 (allowlist, not denylist). Outside a changelog region (FR-2: EVERY entry-shaped run, not
+ * only the first — see `changelogRegion`), a token rewrites ONLY when `isAllowlistedRewriteContext`
+ * recognises its shape; every other token — historical prose of ANY form — is left untouched by
+ * default. A `<!-- dz:version -->` marker on the line forces the rewrite regardless of either
+ * protection (AC-3).
+ *
+ * FR-3 (never silent): every rewritten line is reported with its line number and before/after text;
+ * every token left untouched as history is counted AND located, whether the reason was the
+ * changelog region or simply not matching any allowlist shape.
+ */
+export function planReadmeVersionSync(
+  text: string,
+  oldVersion: string,
+  newVersion: string,
+): ReadmeVersionSyncPlan {
+  const escaped = oldVersion.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const token = new RegExp(`(^|[^0-9A-Za-z.])(v?)${escaped}(?![0-9])(?!\\.[0-9])`, 'g');
+  const lines = text.split('\n');
+  const history = changelogRegion(lines);
+  const rewritten: ReadmeSyncRewrite[] = [];
+  const historyLineSet = new Set<number>();
+  let skippedHistorical = 0;
+
+  const outLines = lines.map((line, i) => {
+    const forced = line.includes(DZ_VERSION_MARKER);
+    const lineIsHistory = history.has(i) && !forced;
+    let touched = false;
+    const after = line.replace(token, (full: string, sep: string, vPrefix: string, offset: number) => {
+      const tokenStart = offset + sep.length; // includes the optional 'v' — allowlist shapes need it
+      const versionStart = tokenStart + vPrefix.length;
+      const versionEnd = versionStart + oldVersion.length;
+      const allowed = forced || (!lineIsHistory && isAllowlistedRewriteContext(line, tokenStart, versionEnd));
+      if (!allowed) {
+        skippedHistorical++;
+        historyLineSet.add(i + 1);
+        return full;
+      }
+      touched = true;
+      return `${sep}${vPrefix}${newVersion}`;
+    });
+    if (touched) rewritten.push({ line: i + 1, before: line, after });
+    return after;
+  });
+
+  return {
+    text: outLines.join('\n'),
+    rewritten,
+    skippedHistorical,
+    historyLines: [...historyLineSet].sort((a, b) => a - b),
+  };
+}
+
+/**
+ * Sync a package's own README to a freshly-bumped version — a thin, atomic-write wrapper around
+ * `planReadmeVersionSync`. Returns the pre-sync README text for failure restore, or undefined when
+ * nothing was rewritten (same contract as before this function grew a real plan underneath it —
+ * `dz publish`'s report reads the plan via `planReadmeVersionSync` directly; this wrapper's return
+ * value stays exactly what its callers already depend on).
  *
  * Bootstrap invariant: exact-token matching MAINTAINS sync but cannot REPAIR pre-existing drift
  * (a footer already one release behind contains a token != oldVersion and is skipped). Bring the
@@ -519,18 +696,12 @@ export function syncReadmeVersion(dir: string, oldVersion: string, newVersion: s
   const readmePath = join(dir, 'README.md');
   if (!existsSync(readmePath)) return undefined;
   const original = readFileSync(readmePath, 'utf-8');
-  const escaped = oldVersion.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  const token = new RegExp(`(^|[^0-9A-Za-z.])(v?)${escaped}(?![0-9])(?!\\.[0-9])`, 'g');
-  const lines = original.split('\n');
-  const history = changelogRegion(lines);
-  const updated = lines
-    .map((line, i) => (history.has(i) ? line : line.replace(token, `$1$2${newVersion}`)))
-    .join('\n');
-  if (updated === original) return undefined;
+  const plan = planReadmeVersionSync(original, oldVersion, newVersion);
+  if (plan.text === original) return undefined;
   // Atomic: a write interrupted after truncation would leave a half-written README in the tarball
   // (cross-family review). temp + rename makes a partial file impossible.
   const tmp = readmePath + '.sync-tmp';
-  writeFileSync(tmp, updated);
+  writeFileSync(tmp, plan.text);
   renameSync(tmp, readmePath);
   return original;
 }
@@ -601,21 +772,35 @@ function maskFences(lines: readonly string[]): string[] {
  * The region ENDS at the next heading rather than at end-of-file on purpose: two of these READMEs
  * carry ordinary sections after Status, and over-protecting them would silently stop the lock-step
  * sync where it is still wanted.
+ *
+ * MEASURED 2026-09-15 (00_complexity_assessment.md, feature publish-readme-stamp-scope): this
+ * function protected only the FIRST such run. A second `## Status` heading further down the SAME
+ * README opens a SECOND entry-shaped run (`memory` 0.2.21/0.2.22 sat under a later `## Status`,
+ * after an earlier `0.1.0` entry whose region had already ended) — and that second run was bare,
+ * so its entries got relabelled by the next bump exactly like the 2026-08-25 incident this function
+ * was written to stop. FR-2: EVERY entry-shaped run in the document is protected, not only the
+ * first — the scan restarts after each run ends instead of stopping there.
  */
 export function changelogRegion(lines: readonly string[]): Set<number> {
   const out = new Set<number>();
   const masked = maskFences(lines);
-  const start = masked.findIndex((l) => ANY_ENTRY.test(l));
-  if (start < 0) return out;
-  // REJECTED design, recorded so it is not retried: "sync the FIRST entry, protect the rest". It
-  // looks like it restores the lock-step for the current release, and it is unsafe in exactly the
-  // case that produced the bug — an author who bumps WITHOUT adding a new entry has the previous
-  // release's entry sitting first, and syncing it relabels that release's contents to the new
-  // version. The whole region stays protected; writing the newest heading is the author's job, and
-  // the prompt for it is that the version they type is the version they are about to publish.
-  for (let i = start; i < masked.length; i++) {
-    if (i > start && REGION_END.test(masked[i] as string)) break;
-    out.add(i);
+  let i = 0;
+  while (i < masked.length) {
+    if (!ANY_ENTRY.test(masked[i] as string)) { i++; continue; }
+    const start = i;
+    // REJECTED design, recorded so it is not retried: "sync the FIRST entry, protect the rest". It
+    // looks like it restores the lock-step for the current release, and it is unsafe in exactly the
+    // case that produced the bug — an author who bumps WITHOUT adding a new entry has the previous
+    // release's entry sitting first, and syncing it relabels that release's contents to the new
+    // version. The whole region stays protected; writing the newest heading is the author's job, and
+    // the prompt for it is that the version they type is the version they are about to publish.
+    while (i < masked.length && !(i > start && REGION_END.test(masked[i] as string))) {
+      out.add(i);
+      i++;
+    }
+    // `i` now sits on the heading that ended this run (or at EOF) — NOT consumed, so the outer loop
+    // re-examines it: a heading is never itself an entry, but the very next line under it can open a
+    // brand-new run, which is exactly the second-`## Status` case above.
   }
   return out;
 }
@@ -734,6 +919,9 @@ export function publishPackages(
     readonly readmePath: string;
     readonly originalReadme: string | undefined;
     readonly claimCheckSummary: { findings: number; high: number } | undefined;
+    /** FR-3 (fix-round 1): carried through the two-pass packed transport so the readme-sync report
+     *  reaches the FINAL 'published'/'error' result too — not only the pass-1 optimistic entry. */
+    readonly readmeSyncSummary: PublishResult['readmeSync'];
   }
   const pendingPacked: PendingPacked[] = [];
 
@@ -879,6 +1067,27 @@ export function publishPackages(
       }
     }
 
+    // FR-3 (feature publish-readme-stamp-scope): preview the README sync BEFORE the dry-run
+    // short-circuit, so `--dry-run` shows what the live sync would do — never silent about it, the
+    // same reasoning as the claim-check gate just above. Reading the README never blocks publish;
+    // an unreadable README simply carries no readmeSync summary.
+    let readmeSyncSummary: PublishResult['readmeSync'];
+    try {
+      const readmePath = join(pkg.dir, 'README.md');
+      if (existsSync(readmePath)) {
+        const text = readFileSync(readmePath, 'utf-8');
+        const plan = planReadmeVersionSync(text, oldVersion, newVersion);
+        readmeSyncSummary = {
+          rewrittenLines: plan.rewritten.length,
+          lines: plan.rewritten.map((r) => r.line),
+          skippedHistorical: plan.skippedHistorical,
+          historyLines: plan.historyLines,
+        };
+      }
+    } catch {
+      /* unreadable README never blocks publish or this preview */
+    }
+
     if (opts.dryRun) {
       // NOT a statement that the package would publish cleanly — only that the gates checked ABOVE
       // this line passed. Everything below it (build, re-sign, pack, the package's own
@@ -893,6 +1102,7 @@ export function publishPackages(
       results.push({
         name: pkg.name, oldVersion, newVersion, status: 'skipped',
         claimCheck: claimCheckSummary,
+        readmeSync: readmeSyncSummary,
         notVerified: NOT_VERIFIED_BY_DRY_RUN,
       });
       landedInBatch.add(pkg.name);
@@ -909,7 +1119,12 @@ export function publishPackages(
       originalReadme = syncReadmeVersion(pkg.dir, oldVersion, newVersion);
 
       if (opts.bumpOnly) {
-        results.push({ name: pkg.name, oldVersion, newVersion, status: 'published', claimCheck: claimCheckSummary });
+        // FR-3 fix-round 1 (Codex HIGH): the readme-sync summary was previously attached only to the
+        // dry-run and main-live paths — --bump-only silently omitted it even though `syncReadmeVersion`
+        // just ran two lines above. Reuse the SAME preview computed before the dry-run branch: it is a
+        // pure function of the same pre-sync text and the same old/new versions, so it already
+        // describes exactly what the write above just did.
+        results.push({ name: pkg.name, oldVersion, newVersion, status: 'published', claimCheck: claimCheckSummary, readmeSync: readmeSyncSummary });
         continue;
       }
 
@@ -1037,6 +1252,7 @@ export function publishPackages(
           readmePath: pathJoin(pkg.dir, 'README.md'),
           originalReadme,
           claimCheckSummary,
+          readmeSyncSummary,
         });
         pinVersions.set(pkg.name, newVersion);
         // Optimistic, mirroring the dry-run branch above: this package WILL land once the
@@ -1062,7 +1278,7 @@ export function publishPackages(
 
       const { registryProbes } = confirmPublished(pkg.name, newVersion, probeLog);
 
-      results.push({ name: pkg.name, oldVersion, newVersion, status: 'published', registryProbes, probeLog, claimCheck: claimCheckSummary });
+      results.push({ name: pkg.name, oldVersion, newVersion, status: 'published', registryProbes, probeLog, claimCheck: claimCheckSummary, readmeSync: readmeSyncSummary });
       landedInBatch.add(pkg.name); // only an ACTUAL publish covers dependents (Codex P1)
     } catch (err) {
       // The version was written BEFORE build+publish; on any failure restore the
@@ -1182,6 +1398,7 @@ export function publishPackages(
           results.push({
             name: p.name, oldVersion: p.oldVersion, newVersion: p.newVersion, status: 'published',
             registryProbes, probeLog, claimCheck: p.claimCheckSummary, sha256: p.sha256,
+            readmeSync: p.readmeSyncSummary, // FR-3 fix-round 1: the third publish path that was silent
           });
           // landedInBatch already carries p.name from pass 1 (optimistic) — now confirmed for real.
         } catch (err) {

package/src/release-line.ts

@@ -29,3 +29,35 @@ export function rewriteReleaseLine(text: string, core: string, cli: string): str
   );
   return lines.join('\n');
 }
+
+/**
+ * A generic RELEASE-LINE token: a backtick-quoted `<pkg-short-name> vX` pair, anywhere on a line —
+ * the shape `RELEASE_LINE_RE` names for the joint `harness-core`/`harness-cli` pair, generalised to
+ * ANY package name (feature publish-readme-stamp-scope, FR-1a) so a per-package README's own status
+ * line — `` `harness-core vX` · `harness-cli vY` · `memory vZ` `` and similar — is recognised as a
+ * release-line shape whatever packages it names, not only the original two, and however many trail
+ * after the first pair (an extra `` · `memory vZ` `` segment needs no bespoke regex of its own).
+ */
+export const GENERIC_RELEASE_TOKEN_RE = /`[a-z][a-z0-9-]*\s+v\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.]+)?`/;
+
+/**
+ * Is the OLD-VERSION occurrence at `[start, end)` in `line` sitting inside a `` `<name> vX` ``
+ * backtick token? A POSITIVE override for `planReadmeVersionSync`'s citation heuristic: a token
+ * this shape matches is a release-line stamp, never a historical citation, even where it sits next
+ * to punctuation ("/", "on ") the citation heuristic would otherwise read as a citation cue.
+ */
+export function isReleaseLineToken(line: string, start: number, end: number): boolean {
+  // Codex r2 HIGH (lead): a `` `<name> vX` `` token is a release-line stamp ONLY on a line that carries
+  // the JOINT release-line shape (`RELEASE_LINE_RE`); an isolated `` `memory v0.8.25` `` in a
+  // historical sentence is history and must not move.
+  // Codex r3 HIGH (lead): the permission is the joint pair PLUS the CONTIGUOUS ` · `<name> vX``
+  // chain that follows it — not the whole line. `` `harness-core vX` · `harness-cli vY` — historically
+  // `memory vZ` `` moves the first two and keeps the third (prose broke the chain).
+  const joint = RELEASE_LINE_RE.exec(line);
+  if (joint === null) return false;
+  const chainTail = new RegExp(`(?:\\s*·\\s*${GENERIC_RELEASE_TOKEN_RE.source})*`, 'y');
+  chainTail.lastIndex = joint.index + joint[0].length;
+  const tail = chainTail.exec(line);
+  const chainEnd = joint.index + joint[0].length + (tail?.[0].length ?? 0);
+  return joint.index <= start && end <= chainEnd;
+}

package/src/vector-tier.ts

@@ -1158,13 +1158,87 @@ export interface RankedPattern {
 
 const RRF_K = 60;
 
+/**
+ * One entry in the total order every post-merge ranking step shares (feature
+ * `recall-parity-tie-break`, FR-1). `evidence` is the SAME three-way rank `mergeHybridHits` has
+ * always used (`both` < lexical-only < semantic-only — lower is stronger), computed once by
+ * {@link evidenceRank} from a hit's `backend`.
+ */
+export interface HybridOrderKey {
+  readonly score: number;
+  readonly evidence: number;
+  readonly dzId: string;
+}
+
+/** `both` outranks lexical-only outranks semantic-only (mergeHybridHits' own rule, ADR-001 AM-4). */
+export function evidenceRank(backend: RecallHit['backend']): number {
+  return backend === 'both' ? 0 : backend === 'vector' ? 2 : 1;
+}
+
+/**
+ * The ONE deterministic total order recall uses at every step where a tie can occur: fused score
+ * DESC, then EVIDENCE (both > lexical-only > semantic-only), then `dzId` ASC. `mergeHybridHits`
+ * always applied exactly this rule inline; it is exported here (FR-1) so `dampQuarantined`,
+ * `orderHitsForReRank` (the pre-sort `enhance()` runs before its reinforcement/bandit re-rank) and
+ * any other post-merge sort can share the SAME tiebreak instead of an ad hoc score-only comparator
+ * that is deterministic only because its input already arrived pre-ordered — a property that
+ * silently breaks the moment an upstream step feeds it hits in a different order
+ * (recall-parity-tie-break T0: MEASURED, `apply-leg-recall-parity.test.ts` AM-4, a racy
+ * reinforcement-signal read, not a comparator defect, actually explained the observed tail swap —
+ * this comparator is hardening kept from that round; the actual causal fix, per fix-round 1, is the
+ * byte-level store snapshot AM-4 now takes, not this comparator and not an awaited flush).
+ *
+ * FINITE-NUMBER INVARIANT (fix-round 1, LOW finding): plain subtraction (`b.score - a.score`) is
+ * NOT total over `number` — `NaN - x` is `NaN`, and the `||` chain treats a `NaN` term as falsy,
+ * silently SKIPPING it and falling through to the next key as if score had never been compared.
+ * Both terms below use explicit `>`/`<` comparisons instead (correct as-is for ±Infinity — IEEE 754
+ * orders infinities correctly) plus an explicit NaN case: a `NaN` score or evidence is the WEAKEST
+ * possible value on its own axis, so it sorts deterministically LAST, never a coincidental tie.
+ */
+function compareScoreDesc(a: number, b: number): number {
+  if (Number.isNaN(a) || Number.isNaN(b)) return Number.isNaN(a) && Number.isNaN(b) ? 0 : Number.isNaN(a) ? 1 : -1;
+  return a > b ? -1 : a < b ? 1 : 0;
+}
+function compareEvidenceAsc(a: number, b: number): number {
+  if (Number.isNaN(a) || Number.isNaN(b)) return Number.isNaN(a) && Number.isNaN(b) ? 0 : Number.isNaN(a) ? 1 : -1;
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+export function compareHybridHits(a: HybridOrderKey, b: HybridOrderKey): number {
+  return compareScoreDesc(a.score, b.score)
+    || compareEvidenceAsc(a.evidence, b.evidence)
+    || (a.dzId < b.dzId ? -1 : a.dzId > b.dzId ? 1 : 0);
+}
+
+/**
+ * Sorts `hits` into the shared total order {@link compareHybridHits} defines — used by `enhance()`
+ * BEFORE its reinforcement/bandit re-rank runs (`applyLearningSignalsWithTerms` et al.,
+ * `learning-backend.ts`, out of this fix's edit scope). That re-rank sorts by an ADJUSTED score
+ * with a STABLE tie-break on each hit's ORIGINAL array position — so pre-ordering the input here
+ * makes any tie in the adjusted score resolve in the SAME evidence/dzId order `compareHybridHits`
+ * would give directly, without touching the re-rank's own internals.
+ *
+ * This closes the ordering gap `enhance()` had (recall-parity-tie-break fix-round 1, HIGH finding):
+ * `dampQuarantined` only ran {@link compareHybridHits} when `memory.learning.quarantine` was ON;
+ * with it OFF (the default), `enhance()`'s final order was whatever the re-rank's own
+ * original-index tie-break happened to preserve — invisible from the printed `score` column,
+ * because the re-rank reorders the hit array but never rewrites `.score`. Real (non-tied) score
+ * differences from reinforcement/bandit re-ranking are UNCHANGED by this — it only decides ties.
+ */
+export function orderHitsForReRank(hits: readonly HybridHit[], idOf: (p: PatternRecord) => string): HybridHit[] {
+  return [...hits].sort((a, b) => compareHybridHits(
+    { score: a.score, evidence: evidenceRank(a.backend), dzId: idOf(a.pattern) },
+    { score: b.score, evidence: evidenceRank(b.backend), dzId: idOf(b.pattern) },
+  ));
+}
+
 /**
  * Reciprocal Rank Fusion merge: `score(p) = Σ 1/(60 + rank)` over the lists containing `p`
  * (semantic ranks weighted by `semanticWeight`). Dedup by id; `backend: 'both'` when a pattern
  *
- * Ordering: fused score, then EVIDENCE (`both` before lexical-only before semantic-only), then id.
- * When `semanticWeight > 1` the lexical top-1 is guaranteed a place in the result, taken from the
- * last seat unless that seat holds a `both` hit. See `features/semantic-keeps-exact-hits`.
+ * Ordering: fused score, then EVIDENCE (`both` before lexical-only before semantic-only), then id
+ * — {@link compareHybridHits}. When `semanticWeight > 1` the lexical top-1 is guaranteed a place in
+ * the result, taken from the last seat unless that seat holds a `both` hit. See
+ * `features/semantic-keeps-exact-hits`.
  *
  * appears in both lists. DETERMINISTIC (AC-6): ties break on id, so fixed inputs always yield
  * the same ordering. Pure — no I/O.
@@ -1196,12 +1270,14 @@ export function mergeHybridHits(
   });
   // Ties break by EVIDENCE, not by the id alphabet: a hit both legs found outranks one only a single
   // leg found. Before this, an exact-term match lost a tie to an arbitrary semantic hit purely
-  // because its id sorted later (ADR-001 AM-4).
-  const evidence = (v: Acc): number => (v.lex !== undefined && v.sem ? 0 : v.lex !== undefined ? 1 : 2);
+  // because its id sorted later (ADR-001 AM-4). Now routed through the shared {@link
+  // compareHybridHits} (FR-1) — same three-part rule, no behaviour change.
+  const evidenceOfAcc = (v: Acc): number => evidenceRank(v.lex !== undefined && v.sem ? 'both' : v.lex ?? 'vector');
   const ordered = [...acc.entries()]
-    .sort((a, b) => b[1].score - a[1].score
-      || evidence(a[1]) - evidence(b[1])
-      || (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+    .sort((a, b) => compareHybridHits(
+      { score: a[1].score, evidence: evidenceOfAcc(a[1]), dzId: a[0] },
+      { score: b[1].score, evidence: evidenceOfAcc(b[1]), dzId: b[0] },
+    ));
   const toHit = ([, v]: [string, Acc]): HybridHit => ({
     pattern: v.pattern,
     backend: v.lex !== undefined && v.sem ? ('both' as const) : v.lex ?? ('vector' as const),
@@ -1256,6 +1332,27 @@ export function mergeHybridHits(
  *
  * `bandit` is passed ONLY when `memory.learning.banditRerank` is armed; when it is absent this
  * function is byte-identical to its pre-feature self — no state file, no lock, no allocation.
+ *
+ * `backend.train()` fires FIRE-AND-FORGET (`void backend.train().catch(() => undefined)`) — this is
+ * a REVERT (recall-parity-tie-break, fix-round 1, MEDIUM finding). An intermediate version of this
+ * fix AWAITED the flush, on the theory that a caller's own reinforcement write landing before it got
+ * an answer would remove the race `apply-leg-recall-parity.test.ts` AM-4 was catching (two tail hits
+ * swapping order between the daemon's `op:recall` reply and a `dz recall --json` invoked a moment
+ * later — MEASURED byte-identical `score` fields, only `uses` differed, so the merge/comparator was
+ * never the cause). MEASURED (lead, 2026-09-15 15:57, temp project, 8 lexical hits, 5 warm runs):
+ * `recallHybrid` took 2 ms with `onRecallHits:false` (no flush at all) vs 57–131 ms with the flush
+ * AWAITED — landing INSIDE the hook's 500 ms `HOOK_RECALL_BUDGET_MS` but a real, avoidable tax on
+ * every recall, for a property the await did not even fully deliver: the awaited write still let a
+ * CLI invoked immediately after the daemon see the DAEMON'S OWN just-computed exposure for that same
+ * query, answering a subtly different question than the daemon had. AM-4 now proves parity by taking
+ * a byte-level SNAPSHOT of the store BEFORE each query's daemon call and pointing `dz recall --json`
+ * at the frozen snapshot (`--project <snapshot>`) — both sides then answer the identical question
+ * from the identical state under PRODUCTION defaults (`onRecallHits` ON), and no write, awaited or
+ * not, can reach the CLI's read. That snapshot is what actually closes the race; this function stays
+ * fire-and-forget, exactly as it always was, because the snapshot makes its timing irrelevant to the
+ * test. `test/lesson-bandit-byte-identity.test.ts` documents the same underlying race in its own
+ * fixture comment and works around it with `onRecallHits: false` there — a narrower, still-valid
+ * isolation for a different test's needs.
  */
 function markRecallHits(
   projectRoot: string,
@@ -1356,7 +1453,15 @@ export async function recallHybrid(
         const q = rec !== undefined && readQuarantineState(rec).quarantined;
         return q ? { ...h, score: h.score * memCfg.quarantineDamp, quarantined: true as const } : h;
       })
-      .sort((a, b) => b.score - a.score);
+      // FR-1 (recall-parity-tie-break): score-only used to rely on the INCOMING array already
+      // being pre-ordered (native Array.sort is stable, so a genuine tie only stayed put by
+      // accident of arrival order). Routed through the same {@link compareHybridHits} the merge
+      // uses, so damping two equally-scored hits can never reorder them differently from how the
+      // merge itself would have.
+      .sort((a, b) => compareHybridHits(
+        { score: a.score, evidence: evidenceRank(a.backend), dzId: idOf(a.pattern) },
+        { score: b.score, evidence: evidenceRank(b.backend), dzId: idOf(b.pattern) },
+      ));
   };
   // lesson-bandit-rerank (ADR-001): the payoff axis. Resolved ONCE per recall; `enabled:false` ⇒
   // the Lesson Payoff context is NEVER CONSTRUCTED — the branch is taken BEFORE any work, so the
@@ -1366,7 +1471,15 @@ export async function recallHybrid(
   let banditReport: BanditRecallReport | undefined;
   let banditExplored: readonly string[] = [];
   const enhance = (hits: readonly HybridHit[]): HybridHit[] => {
-    const candidates = hits.map((h) => {
+    // FR-1 (recall-parity-tie-break, fix-round 1, HIGH finding): pre-sort into the shared total
+    // order BEFORE the reinforcement/bandit re-rank runs — see {@link orderHitsForReRank}.
+    // Why the pre-sort is sufficient and not "reliance on a stable sort" (Codex round 2): the
+    // re-rank's own sort in learning-backend.ts is `b.adjusted - a.adjusted || a.i - b.i` — an
+    // EXPLICIT tie-break on the incoming index, so an adjusted-score tie resolves to exactly the
+    // order built here (score → evidence → dzId), by construction, on any engine. That generic
+    // function only knows `score`, so it cannot call compareHybridHits itself.
+    const ordered = orderHitsForReRank(hits, idOf);
+    const candidates = ordered.map((h) => {
       const dzId = idOf(h.pattern);
       const rec = idToRecord.get(dzId);
       return { dzId, score: h.score, reinforcement: rec !== undefined ? readReinforcementState(rec) : undefined };
@@ -1392,8 +1505,8 @@ export async function recallHybrid(
         ? []
         : [{ id: 'delta', byIndex: candidates.map((c) => deltaMap.get(c.dzId) ?? 0), cap: REINFORCE_RRF_CAP }];
       // The SAME ranking without the payoff term — the only honest way to say what the term moved.
-      const before = dampQuarantined(applyLearningSignalsWithTerms(hits, learning, candidates, REINFORCE_RRF_CAP, baseTerms));
-      const after = dampQuarantined(applyLearningSignalsWithTerms(hits, learning, candidates, REINFORCE_RRF_CAP, [
+      const before = dampQuarantined(applyLearningSignalsWithTerms(ordered, learning, candidates, REINFORCE_RRF_CAP, baseTerms));
+      const after = dampQuarantined(applyLearningSignalsWithTerms(ordered, learning, candidates, REINFORCE_RRF_CAP, [
         ...baseTerms,
         // ADDED, never assigned, and pre-bounded to [-1,+1] by the ACL — so `squash` is identity and
         // `cap` is an EXACT bound on this term's contribution (INV-4).
@@ -1423,9 +1536,9 @@ export async function recallHybrid(
     }
     if (deltaMap !== undefined) {
       const deltaByIndex = candidates.map((c) => deltaMap.get(c.dzId) ?? 0);
-      return dampQuarantined(applyLearningSignalsWithDelta(hits, learning, candidates, REINFORCE_RRF_CAP, deltaByIndex, REINFORCE_RRF_CAP));
+      return dampQuarantined(applyLearningSignalsWithDelta(ordered, learning, candidates, REINFORCE_RRF_CAP, deltaByIndex, REINFORCE_RRF_CAP));
     }
-    return dampQuarantined(applyLearningSignals(hits, learning, candidates, REINFORCE_RRF_CAP));
+    return dampQuarantined(applyLearningSignals(ordered, learning, candidates, REINFORCE_RRF_CAP));
   };
   /** The exposure/telemetry payload for `markRecallHits` — `undefined` while disarmed (INV-1). */
   const banditEmission = (): { readonly contextKey: string; readonly explored: readonly string[]; readonly moved: number; readonly arms: number; readonly deferred?: boolean } | undefined =>