wehub-resource-sync
332 lines
14 KiB
TypeScript
332 lines
14 KiB
TypeScript
// Implementation-agnostic contract for `RuntimeStore`. Every backend is proven
|
|
// equivalent by running this same suite against it, so a new backend cannot
|
|
// silently diverge from the store's semantics.
|
|
//
|
|
// Backend-specific behaviours live in the backend's own test file, not here:
|
|
// seeding raw rows (migrate-on-read, future-stamp skew) and — mirroring how
|
|
// document-contract handles injected scene validators — building a store with
|
|
// non-default options (`payloadValidators` overrides).
|
|
import { describe, expect, test } from 'vitest';
|
|
import { RUNTIME_DSL_VERSION } from '@openmaic/dsl';
|
|
import type { RuntimeRecordInit } from '@openmaic/dsl';
|
|
import type { RuntimeStore, RuntimeSessionInit } from '../src/index.js';
|
|
|
|
// --- fixtures ---------------------------------------------------------------
|
|
|
|
const T0 = '2026-01-01T00:00:00.000Z';
|
|
const T1 = '2026-01-01T00:01:00.000Z';
|
|
|
|
/** A valid session init (the pre-stamp shape `createSession` takes). */
|
|
export function makeSession(overrides: Partial<RuntimeSessionInit> = {}): RuntimeSessionInit {
|
|
return {
|
|
id: 'sess-1',
|
|
kind: 'chat',
|
|
stageId: 'stage-1',
|
|
learnerKey: 'anon:device-1',
|
|
status: 'active',
|
|
createdAt: T0,
|
|
updatedAt: T0,
|
|
...overrides,
|
|
};
|
|
}
|
|
|
|
// Deterministic id counter: fixture ids must be unique per call (records are
|
|
// append-only under one session) but stable across runs — no randomness.
|
|
let recordCounter = 0;
|
|
|
|
/** A valid record init (the pre-`seq` shape `appendRecord` takes). */
|
|
export function makeRecordInit(
|
|
sessionId: string,
|
|
overrides: Record<string, unknown> = {},
|
|
): RuntimeRecordInit {
|
|
recordCounter += 1;
|
|
return {
|
|
id: `rec-${recordCounter}`,
|
|
sessionId,
|
|
createdAt: T1,
|
|
payload: { role: 'user', content: 'hello' },
|
|
...overrides,
|
|
} as RuntimeRecordInit;
|
|
}
|
|
|
|
// --- contract ---------------------------------------------------------------
|
|
|
|
export function runRuntimeStoreContract(name: string, makeStore: () => RuntimeStore): void {
|
|
describe(`RuntimeStore contract: ${name}`, () => {
|
|
describe('sessions', () => {
|
|
test('createSession stamps the runtime version; getSession round-trips it', async () => {
|
|
const store = makeStore();
|
|
const created = await store.createSession(makeSession());
|
|
expect(created.runtimeDslVersion).toBe(RUNTIME_DSL_VERSION);
|
|
expect(created).toMatchObject(makeSession());
|
|
|
|
const loaded = await store.getSession('sess-1');
|
|
expect(loaded).toEqual(created);
|
|
});
|
|
|
|
test('createSession rejects a duplicate id — creating twice is a caller bug', async () => {
|
|
const store = makeStore();
|
|
await store.createSession(makeSession());
|
|
await expect(store.createSession(makeSession())).rejects.toThrow(/already exists/);
|
|
});
|
|
|
|
test('createSession rejects an invalid envelope and stores nothing', async () => {
|
|
const store = makeStore();
|
|
await expect(store.createSession(makeSession({ learnerKey: '' }))).rejects.toThrow(
|
|
/learnerKey/,
|
|
);
|
|
expect(await store.getSession('sess-1')).toBeUndefined();
|
|
});
|
|
|
|
test('getSession resolves undefined for an absent id', async () => {
|
|
const store = makeStore();
|
|
expect(await store.getSession('nope')).toBeUndefined();
|
|
});
|
|
|
|
test('listSessions returns only the (stageId, learnerKey) partition, ordered by createdAt', async () => {
|
|
const store = makeStore();
|
|
// Insert the later-created session first: order must come from
|
|
// `createdAt`, not insertion order.
|
|
await store.createSession(makeSession({ id: 'a2', createdAt: T1, updatedAt: T1 }));
|
|
await store.createSession(makeSession({ id: 'a1' }));
|
|
await store.createSession(makeSession({ id: 'b1', learnerKey: 'anon:device-2' }));
|
|
await store.createSession(makeSession({ id: 'c1', stageId: 'stage-2' }));
|
|
|
|
const partition = await store.listSessions('stage-1', 'anon:device-1');
|
|
expect(partition.map((s) => s.id)).toEqual(['a1', 'a2']);
|
|
// isolation both ways: other learner, other stage
|
|
expect((await store.listSessions('stage-1', 'anon:device-2')).map((s) => s.id)).toEqual([
|
|
'b1',
|
|
]);
|
|
expect((await store.listSessions('stage-2', 'anon:device-1')).map((s) => s.id)).toEqual([
|
|
'c1',
|
|
]);
|
|
});
|
|
|
|
test('listSessions orders by the instant a timestamp denotes, not by the string', async () => {
|
|
const store = makeStore();
|
|
// As strings the Z form sorts first ('2025-…' < '2026-…'); as instants
|
|
// the offset form is earlier (2026-01-01T00:30+02:00 = 2025-12-31T22:30Z).
|
|
await store.createSession(
|
|
makeSession({
|
|
id: 'zulu',
|
|
createdAt: '2025-12-31T23:00:00Z',
|
|
updatedAt: '2025-12-31T23:00:00Z',
|
|
}),
|
|
);
|
|
await store.createSession(
|
|
makeSession({
|
|
id: 'offset',
|
|
createdAt: '2026-01-01T00:30:00+02:00',
|
|
updatedAt: '2026-01-01T00:30:00+02:00',
|
|
}),
|
|
);
|
|
expect((await store.listSessions('stage-1', 'anon:device-1')).map((s) => s.id)).toEqual([
|
|
'offset',
|
|
'zulu',
|
|
]);
|
|
});
|
|
|
|
test('setSessionStatus transitions active → completed with the supplied updatedAt', async () => {
|
|
const store = makeStore();
|
|
await store.createSession(makeSession());
|
|
await store.setSessionStatus('sess-1', 'completed', T1);
|
|
|
|
const loaded = await store.getSession('sess-1');
|
|
expect(loaded!.status).toBe('completed');
|
|
expect(loaded!.updatedAt).toBe(T1);
|
|
});
|
|
|
|
test('setSessionStatus rejects an absent session', async () => {
|
|
const store = makeStore();
|
|
await expect(store.setSessionStatus('ghost', 'completed', T1)).rejects.toThrow(
|
|
/no session/i,
|
|
);
|
|
});
|
|
|
|
test('deleteSession removes the session and its records; idempotent', async () => {
|
|
const store = makeStore();
|
|
await store.createSession(makeSession());
|
|
await store.appendRecord(makeRecordInit('sess-1'));
|
|
await store.deleteSession('sess-1');
|
|
|
|
expect(await store.getSession('sess-1')).toBeUndefined();
|
|
expect(await store.listRecords('sess-1')).toEqual([]);
|
|
await expect(store.deleteSession('sess-1')).resolves.toBeUndefined();
|
|
});
|
|
});
|
|
|
|
describe('records', () => {
|
|
test('appendRecord assigns monotonic seq from 0 and stamps nothing on the record', async () => {
|
|
const store = makeStore();
|
|
await store.createSession(makeSession());
|
|
const r0 = await store.appendRecord(makeRecordInit('sess-1'));
|
|
const r1 = await store.appendRecord(makeRecordInit('sess-1'));
|
|
const r2 = await store.appendRecord(makeRecordInit('sess-1'));
|
|
|
|
expect([r0.seq, r1.seq, r2.seq]).toEqual([0, 1, 2]);
|
|
// records ride the parent session's version — no stamp of their own
|
|
expect('runtimeDslVersion' in r0).toBe(false);
|
|
});
|
|
|
|
test('appendRecord round-trips a null payload and rejects an undefined one', async () => {
|
|
const store = makeStore();
|
|
await store.createSession(makeSession({ kind: 'playback' }));
|
|
const stored = await store.appendRecord(makeRecordInit('sess-1', { payload: null }));
|
|
expect(stored.payload).toBeNull();
|
|
expect((await store.listRecords('sess-1'))[0]!.payload).toBeNull();
|
|
|
|
await expect(
|
|
store.appendRecord(makeRecordInit('sess-1', { payload: undefined })),
|
|
).rejects.toThrow(/payload/);
|
|
});
|
|
|
|
test('appendRecord rejects an absent parent and a non-active parent', async () => {
|
|
const store = makeStore();
|
|
await expect(store.appendRecord(makeRecordInit('ghost'))).rejects.toThrow(/no session/i);
|
|
|
|
await store.createSession(makeSession());
|
|
await store.setSessionStatus('sess-1', 'completed', T1);
|
|
await expect(store.appendRecord(makeRecordInit('sess-1'))).rejects.toThrow(/active/);
|
|
});
|
|
|
|
test('appendRecord validates skeleton payloads for skeleton kinds by default', async () => {
|
|
const store = makeStore();
|
|
await store.createSession(makeSession()); // kind: 'chat'
|
|
await expect(
|
|
store.appendRecord(makeRecordInit('sess-1', { payload: { role: 'user', content: 'x' } })),
|
|
).resolves.toMatchObject({ seq: 0 });
|
|
// a quiz-shaped payload on a chat session fails the chat skeleton guard
|
|
await expect(
|
|
store.appendRecord(makeRecordInit('sess-1', { payload: { phase: 'draft' } })),
|
|
).rejects.toThrow(/payload/);
|
|
|
|
// `playback` has no DSL skeleton: an arbitrary object payload is accepted
|
|
await store.createSession(makeSession({ id: 'sess-2', kind: 'playback' }));
|
|
await expect(
|
|
store.appendRecord(makeRecordInit('sess-2', { payload: { position: 42 } })),
|
|
).resolves.toMatchObject({ seq: 0 });
|
|
});
|
|
|
|
// Injected `payloadValidators` overrides need a store built with
|
|
// non-default options, which this factory cannot express — they are
|
|
// covered in the backend's own test file (as document-contract does for
|
|
// injected scene validators).
|
|
|
|
test('listRecords orders by seq and narrows to anchored records with { sceneId }', async () => {
|
|
const store = makeStore();
|
|
await store.createSession(makeSession({ kind: 'playback' }));
|
|
const a = await store.appendRecord(
|
|
makeRecordInit('sess-1', { sceneId: 'scene-1', payload: { n: 0 } }),
|
|
);
|
|
const b = await store.appendRecord(
|
|
makeRecordInit('sess-1', { sceneId: 'scene-2', payload: { n: 1 } }),
|
|
);
|
|
const c = await store.appendRecord(
|
|
makeRecordInit('sess-1', { sceneId: 'scene-1', payload: { n: 2 } }),
|
|
);
|
|
const unanchored = await store.appendRecord(
|
|
makeRecordInit('sess-1', { payload: { n: 3 } }),
|
|
);
|
|
|
|
const all = await store.listRecords('sess-1');
|
|
expect(all.map((r) => r.id)).toEqual([a.id, b.id, c.id, unanchored.id]);
|
|
|
|
const anchored = await store.listRecords('sess-1', { sceneId: 'scene-1' });
|
|
// only records anchored to scene-1; the un-anchored record is excluded
|
|
expect(anchored.map((r) => r.id)).toEqual([a.id, c.id]);
|
|
});
|
|
});
|
|
|
|
describe('learner ops', () => {
|
|
test('mergeLearner re-keys every session of the source learner across all stages', async () => {
|
|
const store = makeStore();
|
|
await store.createSession(makeSession({ id: 'from-1' }));
|
|
await store.createSession(makeSession({ id: 'from-2', stageId: 'stage-2' }));
|
|
await store.createSession(makeSession({ id: 'kept', learnerKey: 'user:42' }));
|
|
|
|
const moved = await store.mergeLearner('anon:device-1', 'user:42');
|
|
expect(moved).toBe(2);
|
|
|
|
// the target learner now owns both partitions, existing sessions untouched
|
|
expect((await store.listSessions('stage-1', 'user:42')).map((s) => s.id).sort()).toEqual([
|
|
'from-1',
|
|
'kept',
|
|
]);
|
|
expect((await store.listSessions('stage-2', 'user:42')).map((s) => s.id)).toEqual([
|
|
'from-2',
|
|
]);
|
|
expect(await store.listSessions('stage-1', 'anon:device-1')).toEqual([]);
|
|
|
|
// idempotent: a second run finds nothing to move
|
|
expect(await store.mergeLearner('anon:device-1', 'user:42')).toBe(0);
|
|
});
|
|
|
|
test('mergeLearner rejects empty learner keys', async () => {
|
|
const store = makeStore();
|
|
// a merge is a write: keys createSession would reject must not be
|
|
// written by the merge either
|
|
await expect(store.mergeLearner('', 'user:42')).rejects.toThrow(/non-empty/);
|
|
await expect(store.mergeLearner('anon:device-1', '')).rejects.toThrow(/non-empty/);
|
|
});
|
|
|
|
test('a self-merge moves nothing and returns 0, repeatably', async () => {
|
|
const store = makeStore();
|
|
await store.createSession(makeSession());
|
|
expect(await store.mergeLearner('anon:device-1', 'anon:device-1')).toBe(0);
|
|
expect(await store.mergeLearner('anon:device-1', 'anon:device-1')).toBe(0);
|
|
// the session is untouched under its original key
|
|
expect((await store.listSessions('stage-1', 'anon:device-1')).map((s) => s.id)).toEqual([
|
|
'sess-1',
|
|
]);
|
|
});
|
|
|
|
test('deleteLearnerRuntime removes exactly one learner on one stage; idempotent', async () => {
|
|
const store = makeStore();
|
|
await store.createSession(makeSession({ id: 'target' }));
|
|
await store.appendRecord(makeRecordInit('target'));
|
|
await store.createSession(makeSession({ id: 'other-learner', learnerKey: 'user:42' }));
|
|
await store.createSession(makeSession({ id: 'other-stage', stageId: 'stage-2' }));
|
|
|
|
await store.deleteLearnerRuntime('stage-1', 'anon:device-1');
|
|
expect(await store.getSession('target')).toBeUndefined();
|
|
expect(await store.listRecords('target')).toEqual([]);
|
|
// other learner and other stage survive
|
|
expect(await store.getSession('other-learner')).toBeDefined();
|
|
expect(await store.getSession('other-stage')).toBeDefined();
|
|
|
|
await expect(
|
|
store.deleteLearnerRuntime('stage-1', 'anon:device-1'),
|
|
).resolves.toBeUndefined();
|
|
});
|
|
|
|
test('deleteStageRuntime removes every learner on the stage; other stages survive', async () => {
|
|
const store = makeStore();
|
|
await store.createSession(makeSession({ id: 's1' }));
|
|
await store.appendRecord(makeRecordInit('s1'));
|
|
await store.createSession(makeSession({ id: 's2', learnerKey: 'user:42' }));
|
|
await store.createSession(makeSession({ id: 's3', stageId: 'stage-2' }));
|
|
|
|
await store.deleteStageRuntime('stage-1');
|
|
expect(await store.getSession('s1')).toBeUndefined();
|
|
expect(await store.getSession('s2')).toBeUndefined();
|
|
expect(await store.listRecords('s1')).toEqual([]);
|
|
expect(await store.getSession('s3')).toBeDefined();
|
|
|
|
await expect(store.deleteStageRuntime('stage-1')).resolves.toBeUndefined();
|
|
});
|
|
});
|
|
|
|
describe('version line', () => {
|
|
test('a stored session carries the runtime stamp only — never a dslVersion key', async () => {
|
|
const store = makeStore();
|
|
await store.createSession(makeSession());
|
|
const stored = await store.getSession('sess-1');
|
|
expect(stored!.runtimeDslVersion).toBe(RUNTIME_DSL_VERSION);
|
|
// the document line's stamp must not leak onto the runtime line
|
|
expect('dslVersion' in stored!).toBe(false);
|
|
});
|
|
});
|
|
});
|
|
}
|