Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Ambient recall hooks (issue #1) — context_pack + delta frozen verbs, the
* shared session cursor, world-only-by-default visibility, and cross-caller
* isolation. Hermetic in-memory PGLite.
*
* Coverage map (plan verification + eng-review findings):
* - session-state round-trip, surfaced-slug union, ISO cursor, GC
* - eng 1B: cross-caller isolation via the (source_id, client_id, session_id) key
* - eng 1A / D2=A: world-only default; include_private widens only for
* trusted-local (ctx.remote === false); remote NEVER widens (fail-closed)
* - delta cursor lifecycle (establish → advance), page dedup, since|session gate
* - MEMORY_VERBS_VERSION stays 1 (additive; the P1 fix)
* - v0.45.7 gap-closure wave: delta visibility fail-closed mirror, stateless
* keyset resume + explicit since_slug precedence, forced budget overflow,
* session-state outage fail-open, banked-entity warm-pack visibility
*/
import { describe, test, expect, beforeAll, afterAll, beforeEach } from 'bun:test';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { configureGateway, resetGateway } from '../src/core/ai/gateway.ts';
import { operations } from '../src/core/operations.ts';
import { MEMORY_VERBS_VERSION, VERB_NAMES } from '../src/core/verbs.ts';
import { estimateTokens } from '../src/core/search/token-budget.ts';
import { deltaHeaderCost, renderFactLine, renderPageLine, renderThreadLine } from '../src/core/context/turn-context.ts';
import {
getSessionContextState,
upsertSessionContextState,
gcSessionContextState,
resolveClientId,
LOCAL_CLIENT_SENTINEL,
} from '../src/core/context/session-state.ts';
import { __resetHotMemoryCacheForTests } from '../src/core/facts/meta-hook.ts';
import type { OperationContext } from '../src/core/operations.ts';
import type { GBrainConfig } from '../src/core/config.ts';
let engine: PGLiteEngine;
const noopLogger = { info: () => {}, warn: () => {}, error: () => {} };
function ctxFor(opts: { remote: boolean; clientId?: string }): OperationContext {
return {
engine,
config: {} as GBrainConfig,
logger: noopLogger,
dryRun: false,
remote: opts.remote,
sourceId: 'default',
...(opts.clientId ? { auth: { clientId: opts.clientId, scopes: [] } as never } : {}),
} as OperationContext;
}
const contextPack = operations.find((o) => o.name === 'context_pack')!;
const del = operations.find((o) => o.name === 'delta')!;
const remember = operations.find((o) => o.name === 'remember')!;
/** Handler results are `unknown` on the Operation type; tests branch on fields. */
// eslint-disable-next-line @typescript-eslint/no-explicit-any
type VerbResult = Record<string, any>;
async function call(
op: typeof contextPack,
ctx: OperationContext,
p: Record<string, unknown>,
): Promise<VerbResult> {
return (await op.handler(ctx, p)) as VerbResult;
}
beforeAll(async () => {
// Hermetic embedding: pin the gateway to a KEYLESS config (empty env) so
// `remember`'s fact-embed degrades gracefully (degraded_dedup) instead of
// firing a real OpenAI call. On CI the process carries a dummy
// OPENAI_API_KEY (sk-test-*) that a shard-neighbor can leak into the
// gateway singleton via a captured env (the bunfig preload configures with
// `env: {...process.env}`); a present-but-invalid key turns the keyless
// degrade into a hard 401. The delta/context_pack tests exercise
// cursor/budget logic, not embedding quality, so keyless is correct and
// makes them independent of shard bin-packing. Dimensions stay 1536 to
// match the preload's schema.
configureGateway({ embedding_model: 'openai:text-embedding-3-large', embedding_dimensions: 1536, env: {} });
engine = new PGLiteEngine();
await engine.connect({});
await engine.initSchema();
}, 120_000);
afterAll(async () => {
await engine.disconnect();
// Restore the preload baseline — leaving the keyless config in place
// configures every LATER file in this shard's process (the exact
// leak-to-neighbor class the beforeAll pin defends against).
resetGateway();
});
beforeEach(async () => {
await engine.executeRaw('DELETE FROM session_context_state');
__resetHotMemoryCacheForTests();
});
describe('protocol additivity (P1 fix)', () => {
test('MEMORY_VERBS_VERSION stays 1 with 7 frozen verbs', () => {
expect(MEMORY_VERBS_VERSION).toBe(1);
expect(VERB_NAMES).toContain('context_pack');
expect(VERB_NAMES).toContain('delta');
expect(VERB_NAMES.length).toBe(7);
});
test('context_pack + delta are verbs on the surface, scope read', () => {
expect(contextPack.verb).toBe(true);
expect(contextPack.scope).toBe('read');
expect(del.verb).toBe(true);
expect(del.scope).toBe('read');
});
test('responses stamp protocol_version 1', async () => {
const pack = await call(contextPack, ctxFor({ remote: false }), { entities: 'a,b' });
expect(pack.protocol_version).toBe(1);
const d = await call(del, ctxFor({ remote: false }), { since: '1970-01-01T00:00:00Z' });
expect(d.protocol_version).toBe(1);
});
});
describe('session-state cursor', () => {
test('absent → null; round-trips + ISO cursor + keyset slug', async () => {
expect(await getSessionContextState(engine, 'default', null, 's1')).toBeNull();
await upsertSessionContextState(engine, 'default', null, 's1', {
standingEntities: ['people/alice-example'],
lastWakeAt: '2026-08-01T00:00:00Z',
cursorSlug: 'notes/x',
});
const st = (await getSessionContextState(engine, 'default', null, 's1'))!;
expect(st.standing_entities).toEqual(['people/alice-example']);
expect(st.surfaced_slugs).toEqual(['notes/x']); // keyset slug, single element
// ISO-normalized regardless of the engine's ::text format
expect(st.last_wake_at).toMatch(/^\d{4}-\d{2}-\d{2}T.*Z$/);
expect(new Date(st.last_wake_at!).toISOString()).toBe('2026-08-01T00:00:00.000Z');
});
test('cursorSlug REPLACES on each advance; omission keeps standing + wake', async () => {
await upsertSessionContextState(engine, 'default', null, 's1', {
standingEntities: ['e1'],
cursorSlug: 'notes/a',
lastWakeAt: '2026-08-01T00:00:00Z',
});
// replace cursor slug; omit standing + wake → both kept
await upsertSessionContextState(engine, 'default', null, 's1', { cursorSlug: 'notes/c' });
const st = (await getSessionContextState(engine, 'default', null, 's1'))!;
expect(st.surfaced_slugs).toEqual(['notes/c']);
expect(st.standing_entities).toEqual(['e1']); // keep-if-absent
expect(new Date(st.last_wake_at!).toISOString()).toBe('2026-08-01T00:00:00.000Z');
});
test('cursor is last-writer-wins on lastWakeAt (keyset ordering lives in the handler)', async () => {
await upsertSessionContextState(engine, 'default', null, 'lww', { lastWakeAt: '2026-08-05T00:00:00Z' });
await upsertSessionContextState(engine, 'default', null, 'lww', { lastWakeAt: '2026-08-01T00:00:00Z' });
const st = (await getSessionContextState(engine, 'default', null, 'lww'))!;
// A null lastWakeAt keeps the prior; a concrete one always wins.
expect(new Date(st.last_wake_at!).toISOString()).toBe('2026-08-01T00:00:00.000Z');
await upsertSessionContextState(engine, 'default', null, 'lww', { cursorSlug: 'notes/z' });
expect(new Date((await getSessionContextState(engine, 'default', null, 'lww'))!.last_wake_at!).toISOString())
.toBe('2026-08-01T00:00:00.000Z'); // null wake → kept
});
test('eng 1B: cross-caller isolation — local sentinel vs auth client are separate rows', async () => {
await upsertSessionContextState(engine, 'default', null, 's1', { cursorSlug: 'local-only' });
await upsertSessionContextState(engine, 'default', 'client-XYZ', 's1', { cursorSlug: 'remote-only' });
const local = (await getSessionContextState(engine, 'default', null, 's1'))!;
const remote = (await getSessionContextState(engine, 'default', 'client-XYZ', 's1'))!;
expect(local.surfaced_slugs).toEqual(['local-only']);
expect(remote.surfaced_slugs).toEqual(['remote-only']);
expect(resolveClientId(null)).toBe(LOCAL_CLIENT_SENTINEL);
expect(resolveClientId('client-XYZ')).toBe('client-XYZ');
});
test('GC ages out stale rows', async () => {
await upsertSessionContextState(engine, 'default', null, 'old', { cursorSlug: 'x' });
await engine.executeRaw(`UPDATE session_context_state SET updated_at = now() - interval '30 days' WHERE session_id = 'old'`);
await gcSessionContextState(engine, 7);
expect(await getSessionContextState(engine, 'default', null, 'old')).toBeNull();
});
test('GC caps rows per (source, client) — oldest evicted past the cap', async () => {
// Seed 3 rows, age them so ordering is deterministic, cap to 2.
for (const s of ['c1', 'c2', 'c3']) {
await upsertSessionContextState(engine, 'default', 'capclient', s, { cursorSlug: s });
}
await engine.executeRaw(`UPDATE session_context_state SET updated_at = '2026-08-01T00:00:00Z' WHERE session_id = 'c1'`);
await engine.executeRaw(`UPDATE session_context_state SET updated_at = '2026-08-02T00:00:00Z' WHERE session_id = 'c2'`);
await engine.executeRaw(`UPDATE session_context_state SET updated_at = '2026-08-03T00:00:00Z' WHERE session_id = 'c3'`);
// Directly exercise the windowed cap via a tiny inline DELETE mirror (the
// real gc uses MAX_ROWS_PER_CLIENT=1000; prove the ORDER here with cap 2).
await engine.executeRaw(
`DELETE FROM session_context_state s USING (
SELECT source_id, client_id, session_id,
row_number() OVER (PARTITION BY source_id, client_id ORDER BY updated_at DESC) AS rn
FROM session_context_state
) ranked
WHERE s.source_id = ranked.source_id AND s.client_id = ranked.client_id
AND s.session_id = ranked.session_id AND ranked.rn > 2`,
);
expect(await getSessionContextState(engine, 'default', 'capclient', 'c1')).toBeNull(); // oldest evicted
expect(await getSessionContextState(engine, 'default', 'capclient', 'c3')).not.toBeNull(); // newest kept
});
});
describe('delta cursor lifecycle', () => {
test('first wake with session establishes an ISO cursor and empty delta', async () => {
const r = await call(del, ctxFor({ remote: false }), { session_id: 'sess-1' });
expect(r.pages).toEqual([]);
expect(r.since).toMatch(/^\d{4}-\d{2}-\d{2}T.*Z$/);
// cursor persisted
const st = await getSessionContextState(engine, 'default', null, 'sess-1');
expect(st?.last_wake_at).toBeTruthy();
});
test('since OR session required; else invalid_params', async () => {
await expect(del.handler(ctxFor({ remote: false }), {})).rejects.toThrow(/requires|since|session/i);
});
test('explicit since is echoed, NORMALIZED to ISO (F4 — never the raw string)', async () => {
const r = await call(del, ctxFor({ remote: false }), { since: '1970-01-01T00:00:00Z' });
expect(r.since).toBe('1970-01-01T00:00:00.000Z');
// A parseable NON-ISO form is normalized to canonical ISO, never echoed raw
// into the injectable `text` block.
const r2 = await call(del, ctxFor({ remote: false }), { since: 'January 1, 2000 00:00:00 GMT' });
expect(r2.since).toBe('2000-01-01T00:00:00.000Z');
expect(r2.text as string).not.toContain('January 1, 2000');
// An UNPARSEABLE string is rejected outright (defense in depth).
await expect(call(del, ctxFor({ remote: false }), { since: 'definitely not a date' })).rejects.toThrow(/parseable|ISO/i);
// Wave review: a calendar-INVALID value in the microsecond passthrough shape
// is Date.parse-able (JS rolls Feb 31 to Mar 3) but would reach the
// ::timestamptz cast raw → engine error. It is invalid_params instead.
for (const since of [
'2026-02-31T00:00:00Z',
'2026-02-31T00:00:00.000Z',
'2026-02-31T00:00:00.000000Z',
]) {
await expect(call(del, ctxFor({ remote: false }), { since })).rejects.toThrow(/calendar|ISO/i);
}
// ...while a valid microsecond cursor still passes through verbatim.
const r3 = await call(del, ctxFor({ remote: false }), { since: '2026-02-28T00:00:00.000100Z' });
expect(r3.since).toBe('2026-02-28T00:00:00.000100Z');
});
test('remote caller cursor is namespaced by auth client', async () => {
await call(del, ctxFor({ remote: true, clientId: 'harness-A' }), { session_id: 'shared' });
await call(del, ctxFor({ remote: true, clientId: 'harness-B' }), { session_id: 'shared' });
const a = await getSessionContextState(engine, 'default', 'harness-A', 'shared');
const b = await getSessionContextState(engine, 'default', 'harness-B', 'shared');
expect(a).not.toBeNull();
expect(b).not.toBeNull();
// 'local' sentinel row must NOT exist for a remote-only session
expect(await getSessionContextState(engine, 'default', null, 'shared')).toBeNull();
});
test('auth-less remote (stdio) lands in the "remote" namespace, never "local" (adversarial P2)', async () => {
await call(del, ctxFor({ remote: true }), { session_id: 'anon-sess' });
expect(await getSessionContextState(engine, 'default', 'remote', 'anon-sess')).not.toBeNull();
expect(await getSessionContextState(engine, 'default', null, 'anon-sess')).toBeNull();
});
test('at-least-once: budget-dropped pages surface on the next wake (adversarial P2)', async () => {
const putPage = operations.find((o) => o.name === 'put_page')!;
const local = ctxFor({ remote: false });
// establish cursor first
await call(del, local, { session_id: 'alo' });
// three page changes after the cursor
for (const s of ['alo-a', 'alo-b', 'alo-c']) {
await call(putPage, local, { slug: `notes/${s}`, content: `# ${s}\n\ncontent for ${s}` });
}
// tiny budget: deliver a strict subset, has_more = true, cursor lags
const r1 = await call(del, local, { session_id: 'alo', budget_tokens: 80 });
expect(r1.has_more).toBe(true);
expect(r1.pages.length).toBeGreaterThan(0);
expect(r1.pages.length).toBeLessThan(3);
// big budget: the remaining pages arrive — nothing was lost
const r2 = await call(del, local, { session_id: 'alo', budget_tokens: 100000 });
const delivered = new Set([...r1.pages, ...r2.pages].map((p: { slug: string }) => p.slug));
expect(delivered.has('notes/alo-a')).toBe(true);
expect(delivered.has('notes/alo-b')).toBe(true);
expect(delivered.has('notes/alo-c')).toBe(true);
expect(r2.has_more).toBe(false);
});
test('text is rendered from the budget-packed sets, not the full sets (adversarial P2)', async () => {
const putPage = operations.find((o) => o.name === 'put_page')!;
const local = ctxFor({ remote: false });
await call(del, local, { session_id: 'txt' });
for (const s of ['txt-a', 'txt-b', 'txt-c']) {
await call(putPage, local, { slug: `notes/${s}`, content: `# ${s}\n\ncontent` });
}
const r = await call(del, local, { session_id: 'txt', budget_tokens: 80 });
const inText = ['txt-a', 'txt-b', 'txt-c'].filter((s) => (r.text as string).includes(s));
expect(inText.length).toBe(r.pages.length); // text lists exactly the delivered pages
});
test('equal-timestamp ties survive across wakes (boundary-tie dedup, pre-landing P2)', async () => {
const putPage = operations.find((o) => o.name === 'put_page')!;
const local = ctxFor({ remote: false });
for (const s of ['tie-a', 'tie-b', 'tie-c', 'tie-d']) {
await call(putPage, local, { slug: `notes/${s}`, content: `# ${s}\n\nbody` });
}
// Force all four onto ONE identical timestamp (the bulk-sync shape).
await engine.executeRaw(
`UPDATE pages SET updated_at = '2026-08-10T12:00:00Z' WHERE slug LIKE 'notes/tie-%'`,
);
// Seed the keyset cursor BEFORE the tie cluster (empty slug = start of the
// bucket) via the INSERT path.
await upsertSessionContextState(engine, 'default', null, 'tie', {
lastWakeAt: '2026-08-10T11:00:00Z', cursorSlug: '',
});
// Tiny budget: deliver a strict subset of the tie cluster (all 4 share one
// timestamp — the keyset paginates within it by slug).
const r1 = await call(del, local, { session_id: 'tie', budget_tokens: 80 });
expect(r1.pages.length).toBeGreaterThan(0);
expect(r1.pages.length).toBeLessThan(4);
expect(r1.has_more).toBe(true);
// Next wake MUST deliver the remaining ties (timestamp-only cursors lost them).
const r2 = await call(del, local, { session_id: 'tie', budget_tokens: 100000 });
const delivered = new Set([...r1.pages, ...r2.pages].map((p: { slug: string }) => p.slug));
for (const s of ['tie-a', 'tie-b', 'tie-c', 'tie-d']) expect(delivered.has(`notes/${s}`)).toBe(true);
// And already-delivered ties must NOT re-deliver on a third wake.
const r3 = await call(del, local, { session_id: 'tie', budget_tokens: 100000 });
const redelivered = (r3.pages as Array<{ slug: string }>).filter((p) => p.slug.startsWith('notes/tie-'));
expect(redelivered).toEqual([]);
});
test('F1: a tie cluster LARGER than the fetch limit fully drains (no livelock)', async () => {
const putPage = operations.find((o) => o.name === 'put_page')!;
const local = ctxFor({ remote: false });
const N = 55; // > DELTA_PAGE_FETCH_LIMIT (50) at ONE timestamp
for (let i = 0; i < N; i++) {
await call(putPage, local, { slug: `notes/big-${String(i).padStart(3, '0')}`, content: `# big-${i}\n\nb` });
}
await engine.executeRaw(`UPDATE pages SET updated_at = '2026-08-11T09:00:00Z' WHERE slug LIKE 'notes/big-%'`);
await upsertSessionContextState(engine, 'default', null, 'big', {
lastWakeAt: '2026-08-11T08:00:00Z', cursorSlug: '',
});
const seenBig = new Set<string>();
let guard = 0;
let more = true;
while (more && guard < 10) {
const r = await call(del, local, { session_id: 'big', budget_tokens: 100000 });
for (const pg of r.pages as Array<{ slug: string }>) {
if (pg.slug.startsWith('notes/big-')) seenBig.add(pg.slug);
}
more = r.has_more === true;
guard++;
}
expect(guard).toBeLessThan(10); // did NOT livelock (the F1 failure was a stuck has_more)
expect(more).toBe(false);
expect(seenBig.size).toBe(N); // every tied page in the >limit cluster delivered, across wakes
});
test('zero-delivery wake does not advance the cursor (deliver-before-advance)', async () => {
const putPage = operations.find((o) => o.name === 'put_page')!;
const local = ctxFor({ remote: false });
await call(del, local, { session_id: 'zd' });
const before = (await getSessionContextState(engine, 'default', null, 'zd'))!.last_wake_at;
await call(putPage, local, { slug: 'notes/zd-page-with-a-very-long-title-to-cost-tokens', content: '# long\n\nbody' });
const r = await call(del, local, { session_id: 'zd', budget_tokens: 1 });
expect(r.pages).toEqual([]);
expect(r.has_more).toBe(true);
expect((await getSessionContextState(engine, 'default', null, 'zd'))!.last_wake_at).toBe(before);
});
test('remote caller with an empty-string clientId lands in "remote", never "local"', async () => {
const ctx = ctxFor({ remote: true, clientId: '' });
await call(del, ctx, { session_id: 'blank-cid' });
expect(await getSessionContextState(engine, 'default', null, 'blank-cid')).toBeNull();
expect(await getSessionContextState(engine, 'default', 'remote', 'blank-cid')).not.toBeNull();
});
test('malformed since → invalid_params with a suggestion (both verbs)', async () => {
await expect(call(del, ctxFor({ remote: false }), { since: 'not-a-date' })).rejects.toThrow(/parseable|ISO/i);
await expect(
call(contextPack, ctxFor({ remote: false }), { entities: 'a', since: 'yesterday-ish' }),
).rejects.toThrow(/parseable|ISO/i);
});
test('first wake echoes the budget footer when budget_tokens was passed', async () => {
const r = await call(del, ctxFor({ remote: false }), { session_id: 'fw-budget', budget_tokens: 500 });
expect(r.budget_tokens).toBe(500);
expect(r.budget_used).toBe(0);
expect(r.dropped_count).toBe(0);
});
test('context_pack echoes the CAPPED entity list (max 8)', async () => {
const many = Array.from({ length: 12 }, (_, i) => `entity-${i}`).join(',');
const r = await call(contextPack, ctxFor({ remote: false }), { entities: many });
expect((r.entities as string[]).length).toBe(8);
});
test('delta facts filter uses RECORDING time and reaches past 24h (pre-landing P2)', async () => {
const local = ctxFor({ remote: false });
await call(remember, local, { fact: 'old recorded fact for delta window test', provenance: 't', visibility: 'world' });
// Age the fact's created_at 3 days back — the old hot-memory fallback
// window (24h) would have silently missed it for a 5-day-old cursor.
await engine.executeRaw(
`UPDATE facts SET created_at = now() - interval '3 days' WHERE fact = 'old recorded fact for delta window test'`,
);
const since = new Date(Date.now() - 5 * 24 * 60 * 60 * 1000).toISOString();
const r = await call(del, local, { since });
const found = (r.facts as Array<{ fact: string }>).some((f) => f.fact.includes('old recorded fact'));
expect(found).toBe(true);
});
test('stateless keyset resume: next_cursor.since/.slug drains a tie cluster, no re-delivery (v0.45.7)', async () => {
const putPage = operations.find((o) => o.name === 'put_page')!;
const local = ctxFor({ remote: false });
for (const s of ['sr-a', 'sr-b', 'sr-c', 'sr-d']) {
await call(putPage, local, { slug: `notes/${s}`, content: `# ${s}\n\nbody` });
}
// One identical timestamp, earlier than every other fixture cluster.
await engine.executeRaw(`UPDATE pages SET updated_at = '2026-08-09T10:00:00Z' WHERE slug LIKE 'notes/sr-%'`);
// NO session_id anywhere: resume rides next_cursor.since/.slug alone.
// budget 80 ≈ 1 page per call (#4761: ~53 tokens of envelope+headers are
// reserved, each rendered page line is ~15), so the 4-page cluster needs
// several wakes.
const seen: string[] = [];
let since = '2026-08-09T09:59:00Z';
let sinceSlug: string | undefined;
let guard = 0;
while (seen.length < 4 && guard < 10) {
const r = await call(del, ctxFor({ remote: false }), {
since,
...(sinceSlug !== undefined ? { since_slug: sinceSlug } : {}),
budget_tokens: 80,
});
for (const pg of r.pages as Array<{ slug: string }>) {
if (pg.slug.startsWith('notes/sr-')) seen.push(pg.slug);
}
since = (r.next_cursor as { since: string }).since;
sinceSlug = (r.next_cursor as { slug: string }).slug;
guard++;
}
// Full drain, exactly once each — a re-delivery would duplicate in `seen`.
expect(seen.sort()).toEqual(['notes/sr-a', 'notes/sr-b', 'notes/sr-c', 'notes/sr-d']);
// One more resumed call: the drained cluster must NOT re-deliver.
const r = await call(del, ctxFor({ remote: false }), { since, since_slug: sinceSlug, budget_tokens: 100000 });
const redelivered = (r.pages as Array<{ slug: string }>).filter((p) => p.slug.startsWith('notes/sr-'));
expect(redelivered).toEqual([]);
});
test('explicit since_slug wins over the session cursor slug when both are present (v0.45.7)', async () => {
const putPage = operations.find((o) => o.name === 'put_page')!;
const local = ctxFor({ remote: false });
for (const s of ['ow-a', 'ow-b', 'ow-c', 'ow-d']) {
await call(putPage, local, { slug: `notes/${s}`, content: `# ${s}\n\nbody` });
}
await engine.executeRaw(`UPDATE pages SET updated_at = '2026-08-08T10:00:00Z' WHERE slug LIKE 'notes/ow-%'`);
// Session cursor at the START of the tie bucket — on its own it would
// deliver the whole cluster from ow-a.
await upsertSessionContextState(engine, 'default', null, 'ow', {
lastWakeAt: '2026-08-08T10:00:00Z', cursorSlug: '',
});
const r = await call(del, local, { session_id: 'ow', since_slug: 'notes/ow-b', budget_tokens: 100000 });
const cluster = (r.pages as Array<{ slug: string }>)
.map((p) => p.slug)
.filter((s) => s.startsWith('notes/ow-'));
// Strictly after the EXPLICIT slug — the session's '' slug would have
// re-delivered ow-a/ow-b.
expect(cluster).toEqual(['notes/ow-c', 'notes/ow-d']);
});
test('fail-open: a session_context_state outage never blocks the delta read path (v0.45.7)', async () => {
// Proxy engine: executeRaw throws ONLY for statements touching
// session_context_state; everything else hits the real engine (the delta
// page/fact reads must keep working through the outage).
const failing = new Proxy(engine, {
get(t, k) {
if (k === 'executeRaw') {
return (sql: unknown, params?: unknown[]) => {
if (typeof sql === 'string' && sql.includes('session_context_state')) {
throw new Error('injected session-state outage');
}
return t.executeRaw(sql as never, params as never);
};
}
const v = (t as unknown as Record<string | symbol, unknown>)[k];
return typeof v === 'function' && k !== 'constructor'
? (v as (...a: unknown[]) => unknown).bind(t)
: v;
},
});
// The state READ degrades to null, never a throw.
await expect(getSessionContextState(failing as never, 'default', null, 'outage')).resolves.toBeNull();
const ctx = { ...ctxFor({ remote: false }), engine: failing } as OperationContext;
// Session-state read failure with no explicit position: a failed read is
// NOT a first wake (contributor audit wave P0), so no cursor is
// initialized at now; the refusal is retryable and names the reason.
await expect(call(del, ctx, { session_id: 'outage' })).rejects.toMatchObject({ code: 'unavailable', reason: 'session_state' });
// Full delta path: assembly reads run fine; the cursor-advance write fails
// silently and the payload is still complete.
const r2 = await call(del, ctx, { session_id: 'outage', since: '1970-01-01T00:00:00Z' });
expect(r2.protocol_version).toBe(1);
expect(Array.isArray(r2.pages)).toBe(true);
expect(r2.since).toBe('1970-01-01T00:00:00.000Z');
expect(r2.next_cursor).toBeTruthy();
// The writes really did fail: nothing persisted for this session.
expect(await getSessionContextState(engine, 'default', null, 'outage')).toBeNull();
});
});
describe('push-path IPC handler (extracted, real engine)', () => {
test('bankOnly persists standing entities under the local lane; assembly merges them back', async () => {
const { makeContextPackIpcHandler } = await import('../src/mcp/context-pack-handler.ts');
const handler = makeContextPackIpcHandler(engine, 'default');
const bank = await handler({
kind: 'context_pack', protocol: 2, secret: 's',
sessionId: 'push-1',
window: [{ role: 'user', text: 'we should follow up with Acme Example about the pilot' }],
bankOnly: true,
});
expect(bank?.text).toBe('');
const st = await getSessionContextState(engine, 'default', null, 'push-1');
expect((st?.standing_entities ?? []).length).toBeGreaterThan(0);
// Assembly path picks the banked set back up (cards may be empty — the
// entities need not resolve — but the merge itself must not throw and the
// cursor must advance on a complete pack).
const before = st?.last_wake_at ?? null;
const res = await handler({ kind: 'context_pack', protocol: 2, secret: 's', sessionId: 'push-1' });
expect(res).not.toBeNull();
const after = await getSessionContextState(engine, 'default', null, 'push-1');
expect(after?.last_wake_at).not.toBe(before); // complete pack advances the cursor
});
test('a deadline-degraded pack does NOT advance the wake cursor', async () => {
const { makeContextPackIpcHandler } = await import('../src/mcp/context-pack-handler.ts');
// Freeze a known cursor + banked entities first (INSERT path) so the
// handler's assembly has real card work to blow the deadline on.
await upsertSessionContextState(engine, 'default', null, 'push-2', {
lastWakeAt: '2026-08-01T00:00:00Z',
standingEntities: ['slow-ent-a', 'slow-ent-b', 'slow-ent-c'],
});
// A proxy engine that delays EVERY method call well past the pack budget
// (arms use engine methods, not just executeRaw).
const DELAY = 250;
const slowEngine = new Proxy(engine, {
get(t, k) {
const v = (t as unknown as Record<string | symbol, unknown>)[k];
if (typeof v === 'function' && k !== 'constructor') {
return async (...a: unknown[]) => {
await new Promise((r) => setTimeout(r, DELAY));
return (v as (...x: unknown[]) => unknown).apply(t, a);
};
}
return v;
},
});
const { assembleContextPack } = await import('../src/core/context/turn-context.ts');
const res = await assembleContextPack(slowEngine as never, {
sourceId: 'default',
entities: ['slow-ent-a', 'slow-ent-b', 'slow-ent-c'],
deadlineMs: 100,
});
expect(res.degradedReason).toBe('deadline');
// Snapshot semantics: the returned arrays must not grow after resolution.
const lenCards = res.cards!.length;
await new Promise((r) => setTimeout(r, 4 * DELAY));
expect(res.cards!.length).toBe(lenCards);
// And the handler skips the cursor advance on a degraded result — proven
// via the real handler against the slow engine. (The handler's own state
// read/write use the REAL engine here so we can assert directly.)
const handler = makeContextPackIpcHandler(slowEngine as never, 'default');
await handler({ kind: 'context_pack', protocol: 2, secret: 's', sessionId: 'push-2' });
const st = await getSessionContextState(engine, 'default', null, 'push-2');
expect(new Date(st!.last_wake_at!).toISOString()).toBe('2026-08-01T00:00:00.000Z');
}, 20_000);
test('banked entities surface as VISIBLE warm-pack content on the next wake (v0.45.7)', async () => {
const { makeContextPackIpcHandler } = await import('../src/mcp/context-pack-handler.ts');
const putPage = operations.find((o) => o.name === 'put_page')!;
// A REAL page the banked window entity resolves to (title + slug-suffix arms).
await call(putPage, ctxFor({ remote: false }), {
slug: 'people/dana-example',
content: '# Dana Example\n\nFounder of widget-co; met at the retreat.',
});
const handler = makeContextPackIpcHandler(engine, 'default');
// PreCompact banking: the window NAMES the seeded page.
const bank = await handler({
kind: 'context_pack', protocol: 2, secret: 's',
sessionId: 'push-vis',
window: [{ role: 'user', text: 'we should sync with Dana Example before the board meeting' }],
bankOnly: true,
});
expect(bank?.text).toBe('');
const st = await getSessionContextState(engine, 'default', null, 'push-vis');
expect(st?.standing_entities ?? []).toContain('Dana Example');
// Post-compaction wake: the banked entity resolves to its page and lands in
// the rendered pack — traceable CONTENT, not merely a cursor advance.
const res = await handler({ kind: 'context_pack', protocol: 2, secret: 's', sessionId: 'push-vis' });
expect(res).not.toBeNull();
expect((res!.cards ?? []).some((c) => c.entity.slug === 'people/dana-example')).toBe(true);
expect(res!.text).toContain('## Standing entities');
expect(res!.text).toContain('people/dana-example');
});
});
describe('hot-memory cache: cross-tier isolation (adversarial P1 regression)', () => {
test('a local include_private call must not warm the cache the remote read hits', async () => {
const local = ctxFor({ remote: false });
await call(remember, local, { fact: 'tier-secret burn detail', provenance: 't', entity: 'tier-acme', visibility: 'private' });
__resetHotMemoryCacheForTests();
// Warm the cache at the trusted-local tier (private facts included).
const warm = await call(contextPack, local, { entities: 'tier-acme', include_private: true });
expect((warm.facts as Array<{ fact: string }>).map((f) => f.fact).join('|')).toContain('tier-secret');
// NO cache reset here — the remote call with the same source/session must
// MISS the local-tier entry (the leak was: same key, served private).
const r = await call(contextPack, ctxFor({ remote: true, clientId: 'c1' }), { entities: 'tier-acme', include_private: true });
expect((r.facts as Array<{ fact: string }>).map((f) => f.fact).join('|')).not.toContain('tier-secret');
});
});
describe('visibility (eng 1A / D2=A): world-only default, fail-closed widen', () => {
beforeEach(async () => {
// seed one world + one private fact about the same entity
const local = ctxFor({ remote: false });
await call(remember, local, { fact: 'acme-example raised a seed round', provenance: 'test', entity: 'acme-example', visibility: 'world' });
await call(remember, local, { fact: 'acme-example secret burn rate detail', provenance: 'test', entity: 'acme-example', visibility: 'private' });
__resetHotMemoryCacheForTests();
});
test('local include_private=true widens facts to include private', async () => {
const r = await call(contextPack, ctxFor({ remote: false }), { entities: 'acme-example', include_private: true });
const facts = (r.facts as Array<{ fact: string }>).map((f) => f.fact).join(' | ');
expect(facts).toContain('secret burn rate');
});
test('local default (no include_private) is world-only', async () => {
const r = await call(contextPack, ctxFor({ remote: false }), { entities: 'acme-example' });
const facts = (r.facts as Array<{ fact: string }>).map((f) => f.fact).join(' | ');
expect(facts).not.toContain('secret burn rate');
});
test('remote caller NEVER widens even with include_private=true (fail-closed)', async () => {
const r = await call(contextPack, ctxFor({ remote: true, clientId: 'c1' }), { entities: 'acme-example', include_private: true });
const facts = (r.facts as Array<{ fact: string }>).map((f) => f.fact).join(' | ');
expect(facts).not.toContain('secret burn rate');
});
// v0.45.7 gap closure: `delta` mirrors the same fail-closed ladder — the
// facts arm routes through listFactsSince's visibility filter, not the
// hot-memory tier, so it needs its own pins.
test('delta local default (no include_private) is world-only in facts[] AND text', async () => {
const since = new Date(Date.now() - 5 * 60_000).toISOString();
const r = await call(del, ctxFor({ remote: false }), { since });
const facts = (r.facts as Array<{ fact: string }>).map((f) => f.fact).join(' | ');
expect(facts).toContain('raised a seed round');
expect(facts).not.toContain('secret burn rate');
expect(r.text as string).not.toContain('secret burn rate');
});
test('delta local include_private=true widens facts to include private', async () => {
const since = new Date(Date.now() - 5 * 60_000).toISOString();
const r = await call(del, ctxFor({ remote: false }), { since, include_private: true });
const facts = (r.facts as Array<{ fact: string }>).map((f) => f.fact).join(' | ');
expect(facts).toContain('secret burn rate');
});
test('delta remote caller NEVER widens even with include_private=true (fail-closed)', async () => {
const since = new Date(Date.now() - 5 * 60_000).toISOString();
const r = await call(del, ctxFor({ remote: true, clientId: 'c1' }), { since, include_private: true });
const facts = (r.facts as Array<{ fact: string }>).map((f) => f.fact).join(' | ');
expect(facts).not.toContain('secret burn rate');
expect(r.text as string).not.toContain('secret burn rate');
});
test('delta page arm widens private pages only for trusted local include_private', async () => {
const since = new Date(Date.now() - 5 * 60_000).toISOString();
await engine.putPage('notes/delta-world-page', {
title: 'Delta World Page',
type: 'note',
frontmatter: { visibility: 'world' },
compiled_truth: 'world page body',
timeline: '',
});
await engine.putPage('notes/delta-private-page', {
title: 'Delta Private Page',
type: 'note',
frontmatter: { visibility: 'private' },
compiled_truth: 'private page body',
timeline: '',
});
const worldOnly = await call(del, ctxFor({ remote: false }), { since });
const widened = await call(del, ctxFor({ remote: false }), {
since,
include_private: true,
});
const remote = await call(del, ctxFor({ remote: true, clientId: 'c1' }), {
since,
include_private: true,
});
for (const result of [worldOnly, widened, remote]) {
expect(result.pages.map((p: { slug: string }) => p.slug)).toContain(
'notes/delta-world-page',
);
}
expect(worldOnly.pages.map((p: { slug: string }) => p.slug)).not.toContain(
'notes/delta-private-page',
);
expect(worldOnly.text as string).not.toContain('Delta Private Page');
expect(widened.pages.map((p: { slug: string }) => p.slug)).toContain(
'notes/delta-private-page',
);
expect(widened.text as string).toContain('Delta Private Page');
expect(remote.pages.map((p: { slug: string }) => p.slug)).not.toContain(
'notes/delta-private-page',
);
expect(remote.text as string).not.toContain('Delta Private Page');
});
});
describe('budget packing + drop footer', () => {
beforeEach(async () => {
const local = ctxFor({ remote: false });
for (let i = 0; i < 8; i++) {
await call(remember, local, { fact: `fact number ${i} with some length to consume tokens`, provenance: 'test', visibility: 'world' });
}
__resetHotMemoryCacheForTests();
});
test('tiny budget reports dropped_count and never trims client-side', async () => {
const r = await call(contextPack, ctxFor({ remote: false }), { entities: 'acme-example', budget_tokens: 5 });
expect(r.budget_tokens).toBe(5);
expect(typeof r.budget_used).toBe('number');
expect(r.dropped_count).toBeGreaterThanOrEqual(0);
});
test('no budget → no footer fields', async () => {
const r = await call(contextPack, ctxFor({ remote: false }), { entities: 'acme-example' });
expect(r.budget_tokens).toBeUndefined();
expect(r.dropped_count).toBeUndefined();
});
// #4761: `text` is what harnesses inject — it must fit budget_tokens, so the
// packer prices the RENDERED line (+ envelope/header reserve), not raw fields.
test('context_pack text never exceeds budget_tokens (#4761)', async () => {
const r = await call(contextPack, ctxFor({ remote: false }), { entities: 'acme-example', budget_tokens: 80 });
expect((r.facts as unknown[]).length).toBeGreaterThan(0);
expect(r.dropped_count).toBeGreaterThan(0);
expect(estimateTokens(r.text as string)).toBeLessThanOrEqual(80);
expect(r.budget_used).toBeLessThanOrEqual(80);
});
test('delta text never exceeds budget_tokens (#4761)', async () => {
const putPage = operations.find((o) => o.name === 'put_page')!;
const local = ctxFor({ remote: false });
await call(del, local, { session_id: 'fit' });
for (const s of ['fit-a', 'fit-b', 'fit-c', 'fit-d', 'fit-e', 'fit-f']) {
await call(putPage, local, { slug: `notes/${s}`, content: `# ${s}\n\ncontent` });
}
const r = await call(del, local, { session_id: 'fit', budget_tokens: 90 });
expect((r.pages as unknown[]).length).toBeGreaterThan(0);
expect(r.has_more).toBe(true);
expect(estimateTokens(r.text as string)).toBeLessThanOrEqual(90);
expect(r.budget_used).toBeLessThanOrEqual(90);
});
// Threads are the commitments a heartbeat must never miss: delta reserves
// every thread line ahead of pages/facts and never budget-drops one. Only
// pages and facts count toward dropped_count; budget_used reports the real
// rendered size (it exceeds the budget only when header + threads alone do).
test('delta never budget-drops threads — dropped_count counts only pages/facts', async () => {
const putPage = operations.find((o) => o.name === 'put_page')!;
const local = ctxFor({ remote: false });
await call(putPage, local, { slug: 'people/alice-example', content: '# Alice Example\n\nbody' });
for (const tag of ['nt-a', 'nt-b', 'nt-c']) {
await call(remember, local, {
fact: `${tag} alice-example will send the signed term sheet by Friday`,
kind: 'commitment',
entity: 'people/alice-example',
provenance: 'test',
visibility: 'world',
});
}
__resetHotMemoryCacheForTests();
const since = '1970-01-01T00:00:00Z';
const full = await call(del, local, { since, entities: 'people/alice-example' });
const threadText = (r: VerbResult) => (r.threads as Array<{ text: string }>).map((t) => t.text).sort();
expect((full.threads as unknown[]).length).toBe(3);
expect((full.pages as unknown[]).length + (full.facts as unknown[]).length).toBeGreaterThan(0);
// A budget below even the envelope: every page and fact drops, every thread stays.
const r = await call(del, local, { since, entities: 'people/alice-example', budget_tokens: 1 });
expect(threadText(r)).toEqual(threadText(full));
expect(r.pages).toEqual([]);
expect(r.facts).toEqual([]);
expect(r.dropped_count).toBe((full.pages as unknown[]).length + (full.facts as unknown[]).length);
expect(r.has_more).toBe(true);
for (const t of threadText(full)) expect(r.text as string).toContain(t);
expect(r.budget_used).toBe(estimateTokens(r.text as string));
expect(r.budget_used).toBeGreaterThan(1); // documented: threads are never truncated
});
// Cursor semantics are the v1 page keyset alone: facts/threads never move
// `next_cursor`, and it carries exactly { since, slug } (no skip list).
test('next_cursor is the page keyset — unaffected by delivered or dropped facts/threads', async () => {
const putPage = operations.find((o) => o.name === 'put_page')!;
const local = ctxFor({ remote: false });
await call(putPage, local, { slug: 'people/bob-example', content: '# Bob Example\n\nbody' });
const entityBeforeRemember = (await engine.readPageSnapshot('people/bob-example', { sourceId: 'default' }))!;
await new Promise((r) => setTimeout(r, 5));
let since = new Date().toISOString();
await new Promise((r) => setTimeout(r, 5));
for (const s of ['kc-a', 'kc-b']) {
await call(putPage, local, { slug: `notes/${s}`, content: `# ${s}\n\ncontent` });
}
await new Promise((r) => setTimeout(r, 5));
let mid = new Date().toISOString();
await new Promise((r) => setTimeout(r, 5));
for (let i = 0; i < 3; i++) {
await call(remember, local, { fact: `kc-fact-${i} ${'z'.repeat(120)}`, provenance: 'test', visibility: 'world' });
}
await call(remember, local, {
fact: 'bob-example will send the revised partnership deck',
kind: 'commitment',
entity: 'people/bob-example',
provenance: 'test',
visibility: 'world',
});
const entityAfterRemember = (await engine.readPageSnapshot('people/bob-example', { sourceId: 'default' }))!;
expect(entityAfterRemember.revision).not.toBe(entityBeforeRemember.revision);
// Entity-bound remember publishes a canonical facts fence and advances the
// page revision. Pin this fixture's page clock before the cutoff so the
// keyset assertions below isolate pages from newer fact/thread records. The
// facts remembered without an entity publish memory/unattributed (GBRA-190 G4); pin it too.
expect(entityBeforeRemember.page.updated_at.getTime()).toBeLessThan(Date.parse(since));
await engine.executeRaw('UPDATE pages SET updated_at = $1::timestamptz WHERE source_id = $2 AND slug = ANY($3::text[])',
[entityBeforeRemember.page.updated_at.toISOString(), 'default', ['people/bob-example', 'memory/unattributed']]);
// delta never advances a cursor past now() - 2 s (commit-visibility lag),
// so age the whole fixture a minute to keep the keyset assertions exact.
await engine.executeRaw(`UPDATE pages SET updated_at = updated_at - interval '1 minute'`);
await engine.executeRaw(`UPDATE facts SET created_at = created_at - interval '1 minute'`);
since = new Date(Date.parse(since) - 60_000).toISOString();
mid = new Date(Date.parse(mid) - 60_000).toISOString();
__resetHotMemoryCacheForTests();
const full = await call(del, local, { since, entities: 'people/bob-example' });
const pages = full.pages as Parameters<typeof renderPageLine>[0][];
expect(pages.map((p) => p.slug)).toEqual(['notes/kc-a', 'notes/kc-b']);
expect((full.facts as unknown[]).length).toBeGreaterThanOrEqual(3);
expect((full.threads as unknown[]).length).toBeGreaterThan(0);
// Unbudgeted: the cursor is the last delivered page, exactly as a
// stateless page-only call would report it.
expect(full.next_cursor).toMatchObject({ since: pages[1].updated_at, slug: pages[1].slug });
// Budget = header + every thread line + the first page line + a sliver:
// one page delivered, every fact dropped — the cursor is still that page.
const reserved =
deltaHeaderCost(since) +
(full.threads as Parameters<typeof renderThreadLine>[0][]).reduce((n, t) => n + estimateTokens(renderThreadLine(t) + '\n'), 0);
const r1 = await call(del, local, {
since,
entities: 'people/bob-example',
budget_tokens: reserved + estimateTokens(renderPageLine(pages[0]) + '\n') + 2,
});
expect((r1.pages as Array<{ slug: string }>).map((p) => p.slug)).toEqual(['notes/kc-a']);
expect(r1.facts).toEqual([]);
expect((r1.threads as unknown[]).length).toBe((full.threads as unknown[]).length);
expect(r1.has_more).toBe(true);
expect(r1.next_cursor).toMatchObject({ since: pages[0].updated_at, slug: pages[0].slug });
expect(estimateTokens(r1.text as string)).toBeLessThanOrEqual(r1.budget_tokens);
// Page-less wake: facts/threads delivered and some facts dropped. The
// legacy time cursor moves to the delivered fact and stays strictly before
// the oldest dropped one, so an old client drains the rest instead of
// re-reading the same prefix (contributor audit wave P0).
const oneFact = estimateTokens(renderFactLine((full.facts as Parameters<typeof renderFactLine>[0][])[0]) + '\n');
const r2 = await call(del, local, { since: mid, entities: 'people/bob-example', budget_tokens: reserved + oneFact + 2 });
expect(r2.pages).toEqual([]);
expect((r2.facts as unknown[]).length).toBe(1);
expect((r2.threads as unknown[]).length).toBe((full.threads as unknown[]).length);
expect(r2.has_more).toBe(true);
expect(r2.next_cursor.slug).toBe('');
expect(r2.next_cursor.since > mid).toBe(true);
const r3 = await call(del, local, { since: r2.next_cursor.since, since_slug: r2.next_cursor.slug, entities: 'people/bob-example', budget_tokens: reserved + oneFact + 2 });
expect((r3.facts as Array<{ fact: string }>)[0].fact).not.toBe((r2.facts as Array<{ fact: string }>)[0].fact);
});
test('forced overflow: dropped_count > 0 and budget_used stays within budget_tokens (v0.45.7)', async () => {
const local = ctxFor({ remote: false });
// Long facts (~55 tokens each): even ONE cannot fit the 20-token budget,
// so overflow is GUARANTEED, not merely allowed (the >= 0 escape hatch).
for (let i = 0; i < 5; i++) {
await call(remember, local, {
fact: `overflow filler fact ${i} ${'x'.repeat(200)}`,
provenance: 'test',
visibility: 'world',
});
}
__resetHotMemoryCacheForTests();
// Precondition: the unbudgeted pack actually carries facts to drop.
const full = await call(contextPack, local, { entities: 'acme-example' });
expect((full.facts as unknown[]).length).toBeGreaterThan(0);
const r = await call(contextPack, local, { entities: 'acme-example', budget_tokens: 20 });
expect(r.budget_tokens).toBe(20);
expect(r.dropped_count).toBeGreaterThan(0);
expect(r.budget_used).toBeLessThanOrEqual(20);
expect((r.facts as unknown[]).length).toBeLessThan((full.facts as unknown[]).length);
});
});