wyuc 3eea9dc542
feat(runtime): complete the #869 learner-data cutover — quiz + playback onto RuntimeStore (#955)
* feat(runtime): persist quiz attempts in RuntimeStore

* fix(runtime): coalesce quiz draft snapshots

* fix(runtime): recover concurrent quiz attempts

* fix(runtime): handle quiz completion races

* fix(runtime): commit quiz review atomically

* fix(runtime): dedupe concurrent quiz writes

* fix(runtime): drop stale quiz drafts

* fix: harden quiz runtime review recovery

* fix: serialize quiz attempt identity

* feat: read quiz state from runtime store

* fix: persist quiz retries before resetting

* fix: preserve authoritative quiz outcomes

* fix: preserve legacy quiz retries during cutover

* fix: reconcile legacy quiz snapshots safely

* fix: drain rollover quiz write queues

* fix: drain completed quiz retry queues

* fix: reuse concurrent quiz retries

* fix(quiz): preserve drafts across abrupt reloads

* fix(quiz): recover empty retry sessions

* fix(chat): abort stalled runtime state reads

* fix(quiz): expose queued phases to readers

* fix(quiz): retain concurrent writer tails

* fix(quiz): canonicalize retry branches

* fix(quiz): keep retry rollovers monotonic

* fix(quiz): validate skipped retry siblings

* fix(quiz): close read cutover races

* test(classroom): cover legacy quiz summaries

* fix(quiz): reset async consumers on scene changes

* fix(quiz): close scene transition windows

* test(pbl): cover launch freshness guards

* fix(quiz): close cutover concurrency gaps

* fix(quiz): harden retry and context freshness

* fix(quiz): reject malformed legacy answers

* fix(quiz): validate legacy answer values

* test(quiz): cover legacy multi-answer migration

* fix(merge): retire dead ChatRequestTemplate.storeState after quiz read cutover

Main's three call sites built static storeState blocks that runAgentLoopFn
never consumed (it always rebuilds fresh state via getStoreState); the quiz
read cutover replaced that callback with the async two-phase RuntimeStore
read, leaving the template field with zero consumers. Drop it.

* feat(storage): conform HTTP/PG backends and reference server to RuntimeAppendOptions

The quiz write path's expectedLastSeq / sessionTransition / RuntimeAppendConflictError
semantics existed only in the browser backend; server-backed deployments would
silently accept conflicting appends and leave completed sessions active. Forward
the options over the wire, detect conflicts atomically under the PG transaction,
map them to HTTP 409 RUNTIME_APPEND_CONFLICT, and rematerialize the typed error
client-side so quiz retry logic works across every backend.

Co-authored-by: Codex <codex@openai.com>

* fix(chat): Pi single requests build storeState via the async runtime quiz read

Pi bypasses runAgentLoop's per-iteration getStoreState and serializes the
request template straight to /api/chat/pi, which rejects bodies without
storeState. Extract the fresh-snapshot builder (async RuntimeStore quiz read
with the scene-transition guard) and call it on the Pi path too.

* ci: whitelist the runtime-data-cutover integration trunk for PR checks

* feat(runtime): playback cutover — cursor in KV, discussion facts in RuntimeStore (#956)

* feat(runtime): cut playback over to the runtime layer — cursor in KV, facts in RuntimeStore (#869)

The fourth and last runtime family. Consumed-discussion facts become
append-only 'playback' records folded into a set at read (at-least-once
appends, no conflict machinery); the resume cursor is device-scoped
last-write-wins KV per the amended #779/#869 split. sessionStorage keeps
same-tab priority; KV takes over on fresh tabs/reloads. The dead Dexie
playbackState machinery is retired, with a one-time lazy migration of any
legacy row (cursor half + facts half) before deletion, and stage deletion
now clears both the KV cursor and any unmigrated legacy row.

Co-authored-by: Codex <codex@openai.com>

* test(runtime): include playbackState in the stage-delete db mock

---------

Co-authored-by: Codex <codex@openai.com>

* fix(playback): persist discussion facts on every consumption path (#957)

* fix(playback): persist discussion facts on every consumption path (final-review P0+P1s)

- The engine now publishes a progress snapshot the moment a discussion is
  consumed (join / skip / unselected-agent auto-skip). onProgress otherwise
  fires before the discussion action executes and a discussion is the scene's
  last action, so the fact never reached persistence.
- Reads fold records across ALL playback sessions in the learner partition
  (mergeLearner deliberately preserves same-kind sessions from both keys).
- Legacy migration appends only not-yet-durable facts, so an interrupted
  migration resumes instead of dropping the tail.
- recordConsumedDiscussion reports durability; the component drops failed ids
  from its observed set so a later progress tick retries (at-least-once).

* test(e2e): live verification of the playback persistence chain

Seeds a deterministic stage straight into the Dexie DB, starts the lecture
via the canvas overlay, and asserts the full chain: discussion auto-skip
appends a discussionConsumed record to maic-runtime, the device cursor lands
in KV, and both survive a fresh browsing context (empty sessionStorage).

* refactor(playback): consumed-discussion state is volatile by decision — cursor-only persistence (#959)

Product ruling on #869's fourth family: playback learner state is front-end
ephemeral UX, not learner data. A re-shown proactive card auto-skips, joined
discussions' content already lives in chat runtime records, and no replay
export / analytics consumer exists — so durable facts bought nothing over
in-memory + same-tab sessionStorage. Drop lib/playback/runtime.ts and the
RuntimeStore facts wiring; keep the device-scoped KV resume cursor (the half
with real UX value), the engine's consumption-time progress snapshot (cursor
freshness), and the legacy Dexie retirement (cursor half migrates, row
deletes, consumed ids are dropped).

* fix(review): P3 pair from cross-review — scene-id boundary + sessionTransition 400 (#966)

* fix(review): scene-id boundary for quiz context + 4xx for malformed sessionTransition (P3 pair)

Review findings on #955: didActiveSceneRemainUnchanged compared the active
scene by object identity, so a store update reallocating the scene during
the async quiz read dropped the learner's graded answers from that turn's
request — the scene id is the real boundary. The records route now
classifies a malformed sessionTransition as a validation failure instead of
letting the store's throw surface as a 500.

* fix(playback): superseded-engine cursor guard + migration write-window recheck

Second-vendor review of the #959 shrink (requested after the cross-review
noted it had single-vendor coverage) found: an engine orphaned by a scene
switch during async lecture resume could pass the idle-only recheck, be
resurrected, and publish its old scene's progress over the new scene's
debounced cursor — the resume continuation now requires identity with the
installed engine, and onProgress drops snapshots from superseded engines.
The legacy cursor migration also rechecks KV immediately before its write
so a concurrent tab's newer cursor cannot be overwritten and orphaned by
the legacy-row delete.

Co-authored-by: Codex <codex@openai.com>

---------

Co-authored-by: Codex <codex@openai.com>

* fix(review): approval follow-up P3 nits (#967)

* release: v0.3.1

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(review): approval P3 nits — ISO gate on sessionTransition, dead mocks, corrupt-timestamp guard

- The records route's sessionTransition guard now requires an ISO
  updatedAt (isIsoTimestamp), matching the sibling PATCH /status route
- Dead vi.mock factories for the deleted playback-storage module dropped
- A corrupt legacy playback timestamp falls back to 'now' instead of
  wedging migration into a permanent re-throw that disabled resume

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Codex <codex@openai.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-07-22 15:28:04 +08:00

337 lines
14 KiB
TypeScript

import { describe, expect, test } from 'vitest';
import { IDBFactory } from 'fake-indexeddb';
import { RUNTIME_DSL_VERSION_KEY } from '@openmaic/dsl';
import { BrowserRuntimeStore } from '../src/index.js';
import { makeRecordInit, makeSession, runRuntimeStoreContract } from './runtime-contract.js';
// Each store gets its own in-memory IndexedDB factory so contract cases stay
// isolated without leaning on an ambient global.
runRuntimeStoreContract(
'BrowserRuntimeStore',
() => new BrowserRuntimeStore({ indexedDB: new IDBFactory() }),
);
// --- backend-specific: version-skew behaviours need to seed a raw session row
// at a foreign version, which the public API (the store always stamps the
// current version) can't express. Mirrors the document backend's reStampStage. ---
// Open the raw DB the store uses and rewrite one stored session row in place,
// simulating a row written by another (older / newer / broken) client.
async function rewriteSessionRow(
idb: IDBFactory,
dbName: string,
sessionId: string,
rewrite: (row: Record<string, unknown>) => void,
): Promise<void> {
const db = await new Promise<IDBDatabase>((resolve, reject) => {
const req = idb.open(dbName);
req.onsuccess = () => resolve(req.result);
req.onerror = () => reject(req.error);
});
await new Promise<void>((resolve, reject) => {
const tx = db.transaction('sessions', 'readwrite');
const store = tx.objectStore('sessions');
const get = store.get(sessionId);
get.onsuccess = () => {
const row = get.result as Record<string, unknown>;
rewrite(row);
store.put(row);
};
tx.oncomplete = () => resolve();
tx.onerror = () => reject(tx.error);
});
db.close();
}
// Overwrite the session row's version stamp. `version: undefined` DELETES the
// stamp — a corrupt row no producer can write.
async function reStampSession(
idb: IDBFactory,
dbName: string,
sessionId: string,
version: string | undefined,
): Promise<void> {
await rewriteSessionRow(idb, dbName, sessionId, (row) => {
if (version === undefined) delete row[RUNTIME_DSL_VERSION_KEY];
else row[RUNTIME_DSL_VERSION_KEY] = version;
});
}
describe('BrowserRuntimeStore migrate-on-read', () => {
test('a below-epoch stamp fails loud on read (no ladder path)', async () => {
const idb = new IDBFactory();
const dbName = 'maic-runtime-stale';
const store = new BrowserRuntimeStore({ indexedDB: idb, dbName });
await store.createSession(makeSession());
await reStampSession(idb, dbName, 'sess-1', '0.0.9');
// '0.0.9' predates the runtime line's pinned initial version, so no ladder
// will EVER have a path from it — the runtime line has no unversioned
// epoch, and its migrations start at the pinned first shipped version.
// This below-epoch fail-loud case therefore stays valid forever. When the
// first real runtime migration lands, ADD a new test seeding the pinned
// initial version and asserting the lift (mirroring the document backend's
// legacy-stamp test) — do not repurpose this one.
await expect(store.getSession('sess-1')).rejects.toThrow(/no migration path/);
});
});
describe('BrowserRuntimeStore forward-compatibility', () => {
test('a future-stamped session reads through unchanged but rejects writes', async () => {
const idb = new IDBFactory();
const dbName = 'maic-runtime-future';
const store = new BrowserRuntimeStore({ indexedDB: idb, dbName });
await store.createSession(makeSession());
await reStampSession(idb, dbName, 'sess-1', '9.9.9');
// Read never downgrades: the newer-shaped row survives for the next
// compatible reader.
const loaded = await store.getSession('sess-1');
expect(loaded!.runtimeDslVersion).toBe('9.9.9');
// ...but an older client must not mutate newer-versioned data.
await expect(store.appendRecord(makeRecordInit('sess-1'))).rejects.toThrow(
/newer than this client/,
);
await expect(
store.setSessionStatus('sess-1', 'completed', '2026-01-01T00:01:00.000Z'),
).rejects.toThrow(/newer than this client/);
});
});
describe('BrowserRuntimeStore injected payload validators', () => {
test('payloadValidators: {} replaces (not merges) the default skeleton gate', async () => {
const store = new BrowserRuntimeStore({
indexedDB: new IDBFactory(),
payloadValidators: {},
});
await store.createSession(makeSession()); // kind: 'chat'
// A non-skeleton chat payload — rejected by the default map (see the
// contract suite), accepted once the app owns the whole mapping.
await expect(
store.appendRecord(makeRecordInit('sess-1', { payload: { phase: 'draft' } })),
).resolves.toMatchObject({ seq: 0 });
});
test('a custom validator gates its kind with its own message', async () => {
const store = new BrowserRuntimeStore({
indexedDB: new IDBFactory(),
payloadValidators: {
playback: (p) =>
typeof p === 'object' && p !== null && 'position' in p
? { valid: true }
: {
valid: false,
errors: [{ path: '/payload', message: 'playback payload requires a position' }],
},
},
});
await store.createSession(makeSession({ kind: 'playback' }));
await expect(
store.appendRecord(makeRecordInit('sess-1', { payload: { position: 1 } })),
).resolves.toMatchObject({ seq: 0 });
await expect(
store.appendRecord(makeRecordInit('sess-1', { payload: { note: 'x' } })),
).rejects.toThrow(/playback payload requires a position/);
});
});
describe('BrowserRuntimeStore atomic append transition', () => {
test('an invalid parent transition aborts both the record and session write', async () => {
const store = new BrowserRuntimeStore({ indexedDB: new IDBFactory() });
await store.createSession(makeSession());
await expect(
store.appendRecord(makeRecordInit('sess-1'), {
sessionTransition: { status: 'completed', updatedAt: 'not-iso' },
}),
).rejects.toThrow(/updatedAt/);
expect(await store.listRecords('sess-1')).toEqual([]);
expect(await store.getSession('sess-1')).toMatchObject({
status: 'active',
updatedAt: '2026-01-01T00:00:00.000Z',
});
});
test('a stale append precondition aborts its requested parent transition', async () => {
const store = new BrowserRuntimeStore({ indexedDB: new IDBFactory() });
await store.createSession(makeSession());
const existing = await store.appendRecord(makeRecordInit('sess-1'));
await expect(
store.appendRecord(makeRecordInit('sess-1'), {
expectedLastSeq: null,
sessionTransition: {
status: 'completed',
updatedAt: '2026-01-01T00:01:00.000Z',
},
}),
).rejects.toMatchObject({ name: 'RuntimeAppendConflictError' });
expect(await store.listRecords('sess-1')).toEqual([existing]);
expect(await store.getSession('sess-1')).toMatchObject({
status: 'active',
updatedAt: '2026-01-01T00:00:00.000Z',
});
});
});
describe('BrowserRuntimeStore corrupt rows', () => {
test('a raw row missing its runtime stamp fails loud on read', async () => {
const idb = new IDBFactory();
const dbName = 'maic-runtime-unstamped';
const store = new BrowserRuntimeStore({ indexedDB: idb, dbName });
await store.createSession(makeSession());
await reStampSession(idb, dbName, 'sess-1', undefined); // strip the stamp
// The runtime line has no unversioned epoch: sessions are born stamped, so
// an unstamped stored row is corruption (or a misrouted document-line
// aggregate), never legacy data — it fails loud instead of resurrecting
// silently at some guessed version.
await expect(store.getSession('sess-1')).rejects.toThrow(/no unversioned epoch/);
});
test('writes against a stamp-stripped row fail loud too', async () => {
const idb = new IDBFactory();
const dbName = 'maic-runtime-unstamped-writes';
const store = new BrowserRuntimeStore({ indexedDB: idb, dbName });
await store.createSession(makeSession());
await reStampSession(idb, dbName, 'sess-1', undefined);
// The write guards read the stored row's version first, so a corrupt stamp
// surfaces the runtime line's own error rather than being written through.
await expect(
store.setSessionStatus('sess-1', 'completed', '2026-01-01T00:01:00.000Z'),
).rejects.toThrow(/no unversioned epoch/);
await expect(store.appendRecord(makeRecordInit('sess-1'))).rejects.toThrow(
/no unversioned epoch/,
);
});
test('a version-valid row with a corrupt envelope fails loud on direct read', async () => {
const idb = new IDBFactory();
const dbName = 'maic-runtime-corrupt-envelope';
const store = new BrowserRuntimeStore({ indexedDB: idb, dbName });
await store.createSession(makeSession());
// The stamp stays valid; another field is corrupted — version resolution
// alone would wave this row through.
await rewriteSessionRow(idb, dbName, 'sess-1', (row) => {
row.createdAt = 'not-iso';
});
await expect(store.getSession('sess-1')).rejects.toThrow(/createdAt/);
});
test('envelope-corrupt rows are omitted from listings like version-corrupt ones', async () => {
const idb = new IDBFactory();
const dbName = 'maic-runtime-corrupt-envelope-listing';
const store = new BrowserRuntimeStore({ indexedDB: idb, dbName });
await store.createSession(makeSession({ id: 'h1' }));
await store.createSession(makeSession({ id: 'h2' }));
await store.createSession(makeSession({ id: 'bad-created' }));
await store.createSession(makeSession({ id: 'bad-status' }));
await rewriteSessionRow(idb, dbName, 'bad-created', (row) => {
row.createdAt = 'not-iso';
});
await rewriteSessionRow(idb, dbName, 'bad-status', (row) => {
row.status = 'paused';
});
// Corrupt-row tolerance covers the whole envelope, not just the stamp.
expect((await store.listSessions('stage-1', 'anon:device-1')).map((s) => s.id)).toEqual([
'h1',
'h2',
]);
});
test('a corrupt row is omitted from listings but stays loud on direct read', async () => {
const idb = new IDBFactory();
const dbName = 'maic-runtime-tolerant-listing';
const store = new BrowserRuntimeStore({ indexedDB: idb, dbName });
await store.createSession(makeSession({ id: 'h1' }));
await store.createSession(makeSession({ id: 'h2' }));
await store.createSession(makeSession({ id: 'corrupt' }));
await reStampSession(idb, dbName, 'corrupt', undefined);
// One poison row must not make the whole partition unenumerable: listings
// tolerate corrupt rows by omission (the listDocuments precedent), while a
// direct read stays fail-loud and the delete paths remain the cleanup tool.
expect((await store.listSessions('stage-1', 'anon:device-1')).map((s) => s.id)).toEqual([
'h1',
'h2',
]);
await expect(store.getSession('corrupt')).rejects.toThrow(/no unversioned epoch/);
});
});
describe('BrowserRuntimeStore mergeLearner guards', () => {
test('a sibling-stamped row aborts the whole merge atomically', async () => {
const idb = new IDBFactory();
const dbName = 'maic-runtime-merge-poison';
const store = new BrowserRuntimeStore({ indexedDB: idb, dbName });
// 'a-healthy' sorts before 'z-poison' in the index walk, so its re-key is
// written first and the poison row's throw must roll it back.
await store.createSession(makeSession({ id: 'a-healthy' }));
await store.createSession(makeSession({ id: 'z-poison' }));
await store.createSession(makeSession({ id: 'existing', learnerKey: 'user:42' }));
// Sibling-stamped: the document line's stamp present, the runtime line's
// absent — the undecidable cross-line state the version readers reject.
await rewriteSessionRow(idb, dbName, 'z-poison', (row) => {
delete row[RUNTIME_DSL_VERSION_KEY];
row.dslVersion = '0.1.0';
});
await expect(store.mergeLearner('anon:device-1', 'user:42')).rejects.toThrow(/misrouted/);
// Atomic abort: NOTHING moved — the target partition is unchanged and the
// healthy row is still under the source key (its in-tx re-key rolled back).
expect((await store.listSessions('stage-1', 'user:42')).map((s) => s.id)).toEqual(['existing']);
expect((await store.listSessions('stage-1', 'anon:device-1')).map((s) => s.id)).toEqual([
'a-healthy',
]);
});
test('a below-epoch stale row aborts the merge with nothing moved', async () => {
const idb = new IDBFactory();
const dbName = 'maic-runtime-merge-stale';
const store = new BrowserRuntimeStore({ indexedDB: idb, dbName });
await store.createSession(makeSession({ id: 'a-healthy' }));
await store.createSession(makeSession({ id: 'z-stale' }));
await store.createSession(makeSession({ id: 'existing', learnerKey: 'user:42' }));
await reStampSession(idb, dbName, 'z-stale', '0.0.9');
// The merge migrates each stale row in place before re-keying it (the same
// migrate-in-place semantics as setSessionStatus/appendRecord), so a
// below-epoch stamp hits the ladder's fail-loud — the same error every
// path gives it until a real runtime migration lands.
await expect(store.mergeLearner('anon:device-1', 'user:42')).rejects.toThrow(
/no migration path/,
);
expect((await store.listSessions('stage-1', 'user:42')).map((s) => s.id)).toEqual(['existing']);
expect((await store.listSessions('stage-1', 'anon:device-1')).map((s) => s.id)).toEqual([
'a-healthy',
]);
});
test('a future-stamped row aborts the merge with nothing moved', async () => {
const idb = new IDBFactory();
const dbName = 'maic-runtime-merge-future';
const store = new BrowserRuntimeStore({ indexedDB: idb, dbName });
await store.createSession(makeSession({ id: 'a-healthy' }));
await store.createSession(makeSession({ id: 'z-future' }));
await store.createSession(makeSession({ id: 'existing', learnerKey: 'user:42' }));
await reStampSession(idb, dbName, 'z-future', '9.9.9');
// Re-keying is a mutation; a newer client's session must not be mutated.
await expect(store.mergeLearner('anon:device-1', 'user:42')).rejects.toThrow(
/newer than this client/,
);
expect((await store.listSessions('stage-1', 'user:42')).map((s) => s.id)).toEqual(['existing']);
// future rows pass through listings unchanged, so both remain visible here
expect((await store.listSessions('stage-1', 'anon:device-1')).map((s) => s.id)).toEqual([
'a-healthy',
'z-future',
]);
});
});