@gamaze/hicortex 0.20.9 → 0.21.0

package/dist/reconsolidation.d.ts

@@ -42,13 +42,32 @@
  * NOTHING else: no status change, no rewrite, no merge queue; both records
  * stay live so the consumer sees both truths. Both merge paths (the zone's
  * planDedup and the judged mergeMemoryIds) refuse to blend a conflicts-linked
- * pair, counted as conflict_skipped. The zone therefore runs AFTER the
- * rewrite phase — with the zone first, a >=0.92 conflict pair was blended
+ * pair, counted as conflict_skipped. The zone therefore runs AFTER the scan —
+ * with the zone first, a >=0.92 conflict pair was blended
  * before the judge ever saw it (the planted-eval harm: canonical=older, the
  * newer truth erased); running it last means verdicts/marks/binds land first
  * and the zone merges only what no verdict claimed — a conflicts bind set by
  * this run's scan guards the SAME run's zone.
  *
+ * #439 apply-on-confirm — confirmed merges and rewrite groups apply at the
+ * candidate BOUNDARY (the end of the scan iteration that confirmed them), not
+ * in post-scan phases. The old end-of-run batch was a completion assumption
+ * written when nightlies finished in an hour; under #405 budget pressure it
+ * became a days-long queue where confirmed work never landed and every night
+ * re-paid the judgment cost (cursor held below un-applied groups, pairs
+ * re-detected, re-judged). Now each judged-merge pair applies via
+ * mergeMemoryIds in its OWN transaction at confirmation time, each rewrite
+ * group via its own rewrite call + applyRewriteGroup transaction; the cursor
+ * advances per APPLIED candidate, so a deferral holds it below exactly ONE
+ * candidate's pairs. One pre-merge backup per run (lazy, before the first
+ * application); the capture lock is taken per boundary batch with a same-run
+ * retry list + a final drain. A shared trigger IS the current candidate, so
+ * the multi-target keep rule resolves across the boundary's groups (any keep
+ * keeps). A target corrected by two different candidates takes two sequential
+ * rewrites — the second composes the already-corrected story — instead of one
+ * grouped call (the ONE-call grouping was a cost optimization, not a
+ * correctness invariant; accepted semantics change).
+ *
  * Status vocabulary (code-defined, extensible — deliberately NOT config):
  *   NULL/'active' default | 'superseded' + 'retracted' demote in ranking |
  *   'corrected' = rewritten, never demotes (demoting it would bury the
@@ -129,9 +148,9 @@ export interface ReconsolidationOptions {
      */
     deadline?: RunDeadline;
     /**
-     * Capture-lock acquirer override (tests) — the deterministic zone and the
-     * judged-merge phase each hold a short lock window. Defaults to the real
-     * capture.ts lock. DedupOptions.acquireLock pattern.
+     * Capture-lock acquirer override (tests) — the deterministic zone and each
+     * #439 boundary's judged-merge batch hold a short lock window. Defaults to
+     * the real capture.ts lock. DedupOptions.acquireLock pattern.
      */
     acquireLock?: typeof acquireCaptureLock;
 }
@@ -329,16 +348,18 @@ export declare function buildResolutionBands(floor: number, ceiling: number): Re
  */
 export declare function bandForCosine(bands: ResolutionBand[], cosine: number): ResolutionBand | null;
 /**
- * Nightly reconsolidation stage (#384, #392 — THE unified resolution stage).
+ * Nightly reconsolidation stage (#384, #392 — THE unified resolution stage;
+ * #439 apply-on-confirm).
  *
  * Phase order (#393 guard-C): the deterministic merge zone (pairs >= the
- * ceiling) runs LAST — after the scan, the judged-merge phase, and the
- * rewrite phase. Judgment outranks the deterministic sweep: verdicts, marks,
- * and binds land first and the zone merges only what no verdict claimed. With
- * the zone first, a >=0.92 genuine-conflict pair was blended before the judge
- * ever saw it (the planted-eval harm); running it last means a `conflicts`
- * bind set by this run's scan guards the SAME run's zone. Zone internals
- * (lock, backup, deadline, persistBand, fail-soft) are unchanged.
+ * ceiling) runs LAST — after the scan (which now includes every judged-merge
+ * application and rewrite, #439). Judgment outranks the deterministic sweep:
+ * verdicts, marks, and binds land first and the zone merges only what no
+ * verdict claimed. With the zone first, a >=0.92 genuine-conflict pair was
+ * blended before the judge ever saw it (the planted-eval harm); running it
+ * last means a `conflicts` bind set by this run's scan guards the SAME run's
+ * zone. Zone internals (lock, backup, deadline, persistBand, fail-soft) are
+ * unchanged.
  *
  * Scan: every memory with rowid > reconsolidationCursor (no shape filter;
  * absorbed candidates are skipped — invisible memories are not re-judged).
@@ -349,25 +370,33 @@ export declare function bandForCosine(bands: ResolutionBand[], cosine: number):
  * judged) plus the scout's FTS hits for correction-shaped memories (same
  * verdict loop, NO similarity gate; guard-C: a scout hit whose KNN twin sits
  * at/above the ceiling is re-tagged scout so the pair IS judged instead of
- * being left for the zone to blend). Confirmed
- * `corrects` pairs above the confidence gate on fact-shaped targets group by
- * target into ONE rewrite call each (AC3); confirmed `merge` pairs queue for
- * the merge phase; a `conflicts` verdict writes the conflicts link and
- * nothing else (both live); everything else is mark-only.
+ * being left for the zone to blend). Confirmed `corrects` pairs above the
+ * confidence gate on fact-shaped targets group by target; a `conflicts`
+ * verdict writes the conflicts link and nothing else (both live); everything
+ * else is mark-only.
  *
- * Merge phase (#392): queued pairs merge through the dedup core under one
- * lock/backup window. A pair that cannot apply keeps both memories and holds
- * the cursor; a conflicts-linked or metadata-mismatched refusal keeps both
- * and advances (the verdict was rendered).
+ * #439 BOUNDARY apply: at the END of each candidate iteration everything it
+ * confirmed applies IMMEDIATELY — merges first (each judged-merge pair via
+ * mergeMemoryIds in its own transaction, under the boundary's short lock
+ * window; ONE lazy pre-merge backup per run), then the iteration's rewrite
+ * groups (one rewrite LLM call + one applyRewriteGroup transaction each;
+ * dispositions resolved ACROSS the boundary's groups — the multi-target keep
+ * rule: a trigger absorbed only if every group's contract says absorb). A
+ * busy capture lock pushes the boundary's merges onto a same-run retry list
+ * (retried at the next boundary and once in a final drain after the scan);
+ * a deadline, a backup failure, or a rewrite-call refusal/infra error defers
+ * the remaining work and holds the cursor.
  *
- * Cursor discipline mirrors stageSupersession: the cursor advances past a
- * candidate once its neighbor set has been considered, regardless of infra
- * skips — EXCEPT when rewrite groups or confirmed merges could not be applied
- * (budget exhausted / rewrite-call infra error / merge cap or lock): the
- * cursor then holds BELOW the earliest candidate contributing to the
- * un-applied work, so those pairs are re-detected next run (dup-over-loss —
- * an un-marked, un-rewritten, un-merged confirmed resolution must never be
- * silently dropped by the cursor passing it).
+ * Cursor discipline: the cursor advances past a candidate only when its
+ * iteration's confirmed work has LANDED (or was refused-with-verdict-rendered:
+ * metadata mismatch, conflict-linked, mark-only fallback). A deferral holds
+ * the cursor BELOW the current candidate — bounded to ONE candidate's pairs,
+ * re-detected and re-judged next run (dup-over-loss — a confirmed resolution
+ * must never be silently dropped by the cursor passing it). The separate
+ * scan high-water (state.reconsolidationScannedRowid) records the max
+ * candidate rowid ENTERED and is never held back, so the report can split
+ * verdict calls into pairs_reevaluated (at/below the prior high-water) vs
+ * pairs_new — the convergence measurement.
  *
  * Dry-run: the zone's discovery + the free idempotency check only — zero LLM
  * calls, zero writes, no cursor or band-stats persistence. Gate discovery is