Skip to content
This repository was archived by the owner on Jul 13, 2026. It is now read-only.

Commit 4d24927

Browse files
fix(cache): resolve transform/cache-stability council audit (5 real bugs + hardening)
Source-verified the blind Athena council audit of the transform pipeline + m[0]/m[1] cache-stability system (both harnesses). 5 real fixes + 1 hardening + docs; each with a cache-stability regression test where applicable. cortexkit#1 (Pi, High) — memory feature-gate leak. Pi resolved projectIdentity unconditionally and rendered <project-memory> into m[0]/m[1] even when memory.enabled=false (OpenCode gates this via projectPath=undefined). Added a memoryProjectPath() helper that short-circuits all memory reads when disabled; docs + key-files still render (they key off projectDirectory). Threaded memoryEnabled through PiInjectionOptions → RunPipelineArgs → injectM0M1Pi state. +regression test. cortexkit#2 (Pi) — defer→execute promotion broke boundary-execution parity. Pi force- promoted schedulerDecision defer→execute when a deferred-execute flag existed, and ALSO fed the flag into baseShouldApplyPendingOps. OpenCode treats the flag as drain-on-success ONLY (peekDeferredExecutePending is read solely by the drain); the idempotent scheduler re-issues execute on the next non-mid-turn pass while pressure holds. Removed both couplings → exact parity. +regression test. cortexkit#3 (OpenCode) — history loss on injectM0M1 failure. prepareCompartmentInjection trims the tail to the latest compartment and caches that new boundary, and the refresh signal is drained before injectM0M1 runs. If injectM0M1 throws, a later same-process defer pass reused the cached new boundary while replaying stale m[1] → a just-published compartment vanished from both. Now clearInjectionCache() in the failure catch so the next defer pass cold-rebuilds to the persisted baseline. +regression test (hazard + fix). cortexkit#4 (OpenCode) — null-boundary regression in the restart-history fix. The cold- rebuild trim fell back to the latest-compartment boundary whenever the persisted baseline was null — but null is also legitimate when m[0] materialized before any compartment existed (every fresh v2 session), reintroducing the exact loss the fix prevents. readCachedBaselineState now discriminates on cached_m0_bytes presence (no-trim on null boundary) vs legacy/never-materialized (latest). +regression test. cortexkit#5 (Pi) — soft-refresh boundary/snapshot mismatch. renderM1PiWithMetadata read compartments live while the boundary advanced from the pre-transaction snapshot; a concurrent sibling publish left a compartment in m[1] AND the raw tail (duplication). Threaded compartmentsOverride so both use one set. (Materialize path already safe: renders inside BEGIN IMMEDIATE with a maxCompartmentSeq stale-check.) cortexkit#6 (hardening) — JSON-array CAS (note-nudge/auto-search) used `= ?` with a coalesced "[]" that never matches a genuinely-NULL row. The NULL case is already prevented (NOT NULL default + migration v17 heal), but switched to `IS ?` with the raw stored value for defense-in-depth, matching applyStrippedPlaceholderDelta. cortexkit#7 (docs) — PARITY.md §12 + AUDIT-KNOWN-ISSUES A30: Pi upgrade_state is now dynamic (legacy|ready, HARD-bust marker) — parity with OpenCode, no longer a static constant. Gate: plugin 1851/0, Pi 413/0 (+2), CLI 146/0; tsc + biome clean across all three; both dists rebuilt. Co-authored-by: Alfonso [Magic Context] <[email protected]>
1 parent fecfbbb commit 4d24927

11 files changed

Lines changed: 391 additions & 101 deletions

‎docs/AUDIT-KNOWN-ISSUES.md‎

Lines changed: 11 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -480,16 +480,14 @@ boundary is the runtime gate, which is correct.
480480
> `getSessionFacts` as "dead" — the render-path retirement and the staging-carry
481481
> reader are separate facts.
482482
483-
### A30. Pi `upgrade_state` m[0] marker is a static constant (inert, not a missed refold)
484-
485-
`inject-compartments-pi.ts` pins `PI_M0_UPGRADE_STATE = "pi-m0m1-v2"` while
486-
OpenCode's `mustMaterialize` reads a dynamic `getUpgradeState(db, sessionId)`.
487-
Auditors flag that a Pi `/ctx-session-upgrade` therefore won't refold m[0] via
488-
the `renderer_upgrade` trigger. **Verified inert, not a bug:** Pi's upgrade path
489-
calls the SHARED `executeContextRecompWithResult` → `compartment-runner-recomp`,
490-
which runs `clearCachedM0M1(db)` (+ `appendM0Mutation`). The cleared cache makes
491-
Pi's very next pass return `first_render` (HARD refold) regardless of the static
492-
`upgrade_state` — so the marker never needs to fire. Making it dynamic would be a
493-
no-op. Documented in PARITY.md; the static const is internally consistent
494-
(stored == current always, so it never falsely triggers and never misses a real
495-
transition because the cache-clear already forces the refold).
483+
### A30. Pi `upgrade_state` m[0] marker is dynamic (parity with OpenCode) — superseded
484+
485+
**Superseded — no longer a divergence.** Earlier this entry described Pi pinning
486+
`PI_M0_UPGRADE_STATE` to a static constant while OpenCode used a dynamic
487+
`getUpgradeState`. Pi's marker is now **dynamic**: `inject-compartments-pi.ts`
488+
computes `${PI_M0_UPGRADE_STATE}:${legacy|ready}` from the presence of legacy
489+
compartments and the materialize stale-check compares it
490+
(`current.upgradeState !== snapshotMarkers.upgradeState`), so a session crossing
491+
from legacy → upgraded HARD-refolds m[0] via the marker — matching OpenCode. (The
492+
shared `clearCachedM0M1` cache-clear in the upgrade path is still a belt-and-
493+
suspenders backstop.) See PARITY.md §12, now also marked parity.

‎packages/pi-plugin/PARITY.md‎

Lines changed: 14 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -232,21 +232,20 @@ Pi does NOT need the incremental watermark machinery because its source is the
232232
bounded wire array, not an ever-growing DB table. Do not "port" the OpenCode
233233
lazy/incremental path to Pi — it would be solving a cost Pi does not have.
234234

235-
## 12. m[0] upgrade-state marker: Pi pins a constant, OpenCode is dynamic
236-
237-
OpenCode flips a per-session m[0] upgrade-state marker (`getUpgradeState`) when
238-
`/ctx-session-upgrade` rebuilds legacy → v2 compartments, which forces an m[0]
239-
refold so the upgraded content materializes. Pi pins the same marker to a
240-
constant (`PI_M0_UPGRADE_STATE = "pi-m0m1-v2"`).
241-
242-
This is **not a live bug**: OpenCode and Pi session IDs never collide, and each
243-
session's m[0] is produced by exactly one harness — so a Pi session never needs
244-
to react to an OpenCode upgrade-state transition (or vice versa). It is a latent
245-
divergence only: if Pi ever gains its own legacy→v2 `/ctx-session-upgrade` flow
246-
that must refold an already-cached m[0] mid-session, Pi would need a dynamic
247-
upgrade-state hook mirroring OpenCode's. Until then the constant is correct and
248-
cheaper. (Pi's detached recomp/upgrade — divergence #11b — already re-signals
249-
materialization through its own path, so today's upgrade flow is covered.)
235+
## 12. m[0] upgrade-state marker: both harnesses are dynamic (parity)
236+
237+
Both harnesses derive a per-session m[0] upgrade-state marker dynamically and use
238+
it as a HARD-bust trigger so an upgraded session re-materializes m[0]. OpenCode
239+
computes `getUpgradeState`; Pi computes `${PI_M0_UPGRADE_STATE}:${legacy|ready}`
240+
from the presence of legacy compartments at render time
241+
(`inject-compartments-pi.ts`), and the materialize stale-check compares it
242+
(`current.upgradeState !== snapshotMarkers.upgradeState`).
243+
244+
This is **parity**, not a divergence. (Earlier revisions of this doc described
245+
Pi's marker as a pinned constant — that is stale: Pi gained its own legacy→v2
246+
`/ctx-session-upgrade` flow and the marker was made dynamic to refold m[0] when a
247+
session crosses from legacy to upgraded. Pi's detached recomp/upgrade —
248+
divergence #11b — additionally re-signals materialization through its own path.)
250249

251250
---
252251

‎packages/pi-plugin/src/boundary-execution-pi.test.ts‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,4 +95,34 @@ describe("boundary execution Pi integration", () => {
9595
}
9696
expect(peekDeferredExecutePending(db, "s1")?.id).toBe("flag-1");
9797
});
98+
99+
it("15. a prior deferred flag does NOT promote a defer decision to execute (parity with OpenCode contract #4)", () => {
100+
// Regression: Pi previously force-promoted schedulerDecision defer→execute
101+
// whenever a deferred-execute flag existed and the pass wasn't mid-turn,
102+
// diverging from OpenCode (which treats the flag as drain-on-success ONLY
103+
// and never re-raises execute — boundary-execution-integration.test.ts #4).
104+
// The idempotent scheduler re-issues execute on the next non-mid-turn pass
105+
// while pressure holds, so no override is needed. Model the post-fix
106+
// contract: a base-defer pass stays defer regardless of the flag's presence,
107+
// and the flag is preserved (drained later only when work genuinely runs).
108+
const db = createDb();
109+
ensureSessionMetaRow(db, "s1");
110+
setDeferredExecutePendingIfAbsent(db, "s1", flag());
111+
112+
// base=defer → applyMidTurnDeferral yields defer; the flag must NOT change it.
113+
const decision = applyMidTurnDeferral({
114+
base: "defer",
115+
bypassReason: "none",
116+
midTurn: false,
117+
});
118+
// The removed Pi-only promotion would have done: if (flag && effective ===
119+
// "defer" && !midTurn) effective = "execute". Assert that does NOT happen —
120+
// the effective decision stays defer even with the flag present.
121+
const flagExists = peekDeferredExecutePending(db, "s1") !== null;
122+
expect(flagExists).toBe(true);
123+
expect(decision.midTurnAdjustedSchedulerDecision).toBe("defer");
124+
125+
// Flag preserved (drain-on-success only): no execute ran this pass.
126+
expect(peekDeferredExecutePending(db, "s1")?.id).toBe("flag-1");
127+
});
98128
});

‎packages/pi-plugin/src/context-handler.ts‎

Lines changed: 35 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -662,6 +662,9 @@ export interface PiHeuristicsOptions {
662662

663663
/** <session-history> injection config — writes compartments+facts+memories into message[0]. */
664664
export interface PiInjectionOptions {
665+
/** When false (config `memory.enabled=false`), project memories are NOT read
666+
* or rendered into m[0]/m[1]. Docs + key-files still render. */
667+
memoryEnabled?: boolean;
665668
injectionBudgetTokens: number;
666669
temporalAwareness?: boolean;
667670
keyFilesEnabled?: boolean;
@@ -1783,17 +1786,18 @@ export function registerPiContextHandler(
17831786
}
17841787

17851788
schedulerDecision = midTurnAdjustedSchedulerDecision;
1786-
const deferredExecutePending = peekDeferredExecutePending(
1787-
options.db,
1788-
sessionId,
1789-
);
1790-
if (
1791-
deferredExecutePending !== null &&
1792-
schedulerDecision === "defer" &&
1793-
!midTurn
1794-
) {
1795-
schedulerDecision = "execute";
1796-
}
1789+
// NOTE: do NOT promote defer→execute when a deferred-execute flag
1790+
// exists. OpenCode treats the flag as drain-on-success ONLY (it never
1791+
// re-raises execute) — see transform-postprocess-phase.ts boundary-exec
1792+
// drain + boundary-execution-integration.test.ts case 4 ("boundary defer
1793+
// with prior flag preserves the flag"). The scheduler is idempotent:
1794+
// shouldExecute re-returns "execute" on the next non-mid-turn pass while
1795+
// pressure still holds, so the deferred execute fires naturally without a
1796+
// Pi-only override. Promoting here diverged from OpenCode in exactly the
1797+
// case where pressure dropped below threshold after the mid-turn defer:
1798+
// OpenCode correctly defers (byte-stable) while Pi force-executed a
1799+
// spurious cache-busting pass. The flag is drained on the next pass that
1800+
// genuinely executes (peek+clear at the end of runPipeline).
17971801
sessionLog(
17981802
sessionId,
17991803
`[boundary-exec] base=${schedulerDecisionEarly} bypass=${bypassReason} midTurn=${midTurn} effective=${midTurnAdjustedSchedulerDecision} sideEffect=${sideEffect}`,
@@ -1909,6 +1913,7 @@ export function registerPiContextHandler(
19091913
injection: options.injection
19101914
? {
19111915
...options.injection,
1916+
memoryEnabled: options.injection.memoryEnabled,
19121917
// v2 decay rendering needs the HISTORY budget (~60K), not the
19131918
// memory injection budget (~4K). Compute it from live usage +
19141919
// historian config, mirroring OpenCode's decayPressure budget.
@@ -2760,6 +2765,9 @@ interface RunPipelineArgs {
27602765
};
27612766
/** Memory-injection config — when omitted, no <session-history> injection runs. */
27622767
injection?: {
2768+
/** When false (config `memory.enabled=false`), project memories are NOT
2769+
* read or rendered into m[0]/m[1]. Docs + key-files still render. */
2770+
memoryEnabled?: boolean;
27632771
injectionBudgetTokens: number;
27642772
/** v2 decay-render history budget (~60K), distinct from the memory
27652773
* injection budget. Drives compartment tier demotion in renderM0Pi. */
@@ -3049,14 +3057,20 @@ async function runPipeline(args: RunPipelineArgs): Promise<RunPipelineResult> {
30493057
args.sessionId,
30503058
);
30513059
const deferredHistoryRefreshWasPending = deferredHistoryWasPendingAtPassStart;
3052-
const deferredExecuteWasPending =
3053-
peekDeferredExecutePending(args.db, args.sessionId) !== null;
30543060
const pendingOps = getPendingOps(args.db, args.sessionId);
3061+
// The deferred-execute flag is drain-on-success ONLY — it must NOT appear
3062+
// here. OpenCode never gates work on the flag (peekDeferredExecutePending is
3063+
// read solely by the drain in transform-postprocess-phase.ts); the idempotent
3064+
// scheduler re-returns "execute" on the next non-mid-turn pass (pressure ≥
3065+
// threshold or TTL elapsed) and THAT drives the deferred execute. Including
3066+
// the flag here made Pi apply pending ops on a defer pass purely because the
3067+
// flag existed — a cache-busting half-execute (ops without heuristics) on a
3068+
// pass OpenCode keeps byte-stable. The flag is drained below on the next pass
3069+
// that genuinely executes.
30553070
const baseShouldApplyPendingOps =
30563071
args.schedulerDecision === "execute" ||
30573072
args.forceMaterialization ||
3058-
hasPendingMaterializeSignal ||
3059-
deferredExecuteWasPending;
3073+
hasPendingMaterializeSignal;
30603074
const canConsumeDeferredLate =
30613075
baseShouldApplyPendingOps || shouldRunHeuristics;
30623076
const deferredMaterialize =
@@ -3068,13 +3082,11 @@ async function runPipeline(args: RunPipelineArgs): Promise<RunPipelineResult> {
30683082
if (shouldApplyPendingOps) {
30693083
const applyReason = hasPendingMaterializeSignal
30703084
? "explicit_flush"
3071-
: deferredExecuteWasPending
3072-
? "deferred_boundary_execute"
3073-
: deferredMaterialize
3074-
? "deferred_publication"
3075-
: args.forceMaterialization
3076-
? "force_materialization"
3077-
: `scheduler_execute (scheduler=${args.schedulerDecision})`;
3085+
: deferredMaterialize
3086+
? "deferred_publication"
3087+
: args.forceMaterialization
3088+
? "force_materialization"
3089+
: `scheduler_execute (scheduler=${args.schedulerDecision})`;
30783090
sessionLog(
30793091
args.sessionId,
30803092
`pending ops WILL APPLY — reason=${applyReason}, pendingOps=${pendingOps.length}, context=${args.contextUsage.percentage.toFixed(1)}%`,
@@ -3484,6 +3496,7 @@ async function runPipeline(args: RunPipelineArgs): Promise<RunPipelineResult> {
34843496
sessionId: args.sessionId,
34853497
projectIdentity: args.projectIdentity,
34863498
projectDirectory: args.projectDirectory,
3499+
memoryEnabled: args.injection.memoryEnabled,
34873500
injectionBudgetTokens: args.injection.injectionBudgetTokens,
34883501
historyBudgetTokens: args.injection.historyBudgetTokens,
34893502
keyFilesEnabled: args.injection.keyFilesEnabled,

‎packages/pi-plugin/src/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -622,6 +622,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
622622
// project memories into message[0]. Cross-harness coherent:
623623
// memories shared with OpenCode show up here automatically.
624624
injection: {
625+
memoryEnabled: config.memory.enabled,
625626
injectionBudgetTokens: config.memory.injection_budget_tokens,
626627
temporalAwareness: config.temporal_awareness === true,
627628
keyFilesEnabled: config.dreamer?.pin_key_files?.enabled ?? false,

‎packages/pi-plugin/src/inject-compartments-pi.test.ts‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -260,6 +260,63 @@ function piState(sessionId: string, cwd: string) {
260260
};
261261
}
262262

263+
describe("injectM0M1Pi memory feature gate", () => {
264+
it("does NOT render project memories into m[0]/m[1] when memoryEnabled=false", () => {
265+
const db = createTestDb();
266+
const cwd = mkdtempSync(join(tmpdir(), "pi-m0m1-memgate-"));
267+
try {
268+
const base = piState("ses-pi-memgate", cwd);
269+
// A compartment (history) MUST still render — only memory is gated.
270+
appendCompartments(db, base.sessionId, [
271+
{
272+
sequence: 1,
273+
startMessage: 1,
274+
endMessage: 1,
275+
startMessageId: "m0",
276+
endMessageId: "m0",
277+
title: "history",
278+
content: "U: a turn\ncompartment body present",
279+
},
280+
]);
281+
insertMemory(db, {
282+
projectPath: base.projectIdentity,
283+
category: "ARCHITECTURE",
284+
content: "SECRET project memory must not leak when disabled",
285+
sourceType: "historian",
286+
});
287+
288+
// memoryEnabled=false → memory suppressed, compartments retained.
289+
const disabledState = { ...base, memoryEnabled: false };
290+
const off = [userMessage("hello", 10)];
291+
injectM0M1Pi(disabledState, db, off as never, undefined, true);
292+
const offM0 = textOf(off[0] as never);
293+
expect(offM0).not.toContain("SECRET project memory");
294+
expect(offM0).not.toContain("<project-memory");
295+
expect(offM0).toContain("compartment body present");
296+
297+
// Control: a fresh session with memoryEnabled left on DOES render it,
298+
// proving the gate (not some other filter) is responsible.
299+
const onState = piState("ses-pi-memgate-on", cwd);
300+
appendCompartments(db, onState.sessionId, [
301+
{
302+
sequence: 1,
303+
startMessage: 1,
304+
endMessage: 1,
305+
startMessageId: "m0",
306+
endMessageId: "m0",
307+
title: "history",
308+
content: "U: a turn\ncompartment body present",
309+
},
310+
]);
311+
const on = [userMessage("hello", 10)];
312+
injectM0M1Pi(onState, db, on as never, undefined, true);
313+
expect(textOf(on[0] as never)).toContain("SECRET project memory");
314+
} finally {
315+
closeQuietly(db);
316+
}
317+
});
318+
});
319+
263320
describe("injectM0M1Pi", () => {
264321
it("renders first-pass m[0] with no inner content and m[1] placeholder", () => {
265322
const db = createTestDb();

0 commit comments

Comments
 (0)