* feat(dsl): runtime envelope — RuntimeSession + RuntimeRecord + core-kind skeletons (#869) * feat(dsl): runtime envelope validators (#869) * test(dsl): runtime envelope rides the version ladder; document the runtime contract (#869) * fix(dsl): harden runtime envelope validators and tighten contract linkage (#869) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(dsl): isQuizAttemptSkeleton requires a plain-record answers map (#869) * fix(dsl): review round — ISO 8601 timestamps, dedicated runtime migration ladder, payload excludes undefined (#869) * fix(dsl): mechanical version-line separation + ISO day-overflow check (#869) - Runtime sessions now stamp their own envelope field (runtimeDslVersion, RuntimeVersioned) instead of sharing dslVersion: the document and runtime ladders read disjoint fields, so misrouted data is inert rather than silently reinterpreted once the two lines diverge. Adds runtimeDslVersionOf + needsRuntimeMigration as the runtime-line counterparts of dslVersionOf + needsMigration. - isIsoTimestamp: Date.parse normalizes day-of-month overflow on V8 (2026-02-30 parses, rolls to Mar 2) instead of rejecting it; add a pure calendar round-trip so the verdict is correct and engine-independent. - Report an empty-string timestamp once (required-field table), not twice. - Scope migrateRuntime's contract to RuntimeSession; records are not independently versioned units. - Run the @openmaic/dsl test suite in PR CI (it previously ran only in the publish workflow). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(dsl): isIsoTimestamp validates calendar components without Date.parse (#869) * test(dsl): cover month-00 / day-00 in isIsoTimestamp negatives (#869) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(dsl): cross-line guard makes misrouted data inert across migration ladders (#869) * fix(dsl): mirror the cross-line guard in the migration predicates (#869) runLadder's cross-line guard returns a misrouted aggregate untouched, but needsLadder still reported it as needing migration (its own stamp absent reads as 0.0.0), so a correctly paired `while (needsMigration(x)) x = migrate(x)` loop on a runtime-line object would never terminate. Give the predicates the same guard, restoring the predicate/runner agreement invariant the docs promise. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(dsl): fail loud on ambiguous cross-line envelopes (#869) The guard treated raw sibling-key presence as proof of misrouting, but the same byte state also arises as this line's data carrying a stray foreign stamp — e.g. a valid session that once passed through the document runner. Silently returning it unchanged permanently orphaned that data from its own line (predicate reports current forever, runner never lifts it). The state is undecidable from the envelope, so stop guessing: both runners and both predicates now throw the same cross-line error on own-stamp-absent + sibling-stamp-present, mirroring the malformed-stamp rule. validateRuntimeSession additionally rejects any present dslVersion on a session at the door, so the ambiguous state cannot enter storage through a validated write path. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(dsl): enforce the cross-line rule in the shared envelope reader (#869) dslVersionOf / runtimeDslVersionOf still read a sibling-stamp-only envelope as unversioned while the runners and predicates threw on it, so an authoritative version read (e.g. storage's putScene guard messages) could report 0.0.0 with a load-and-save remediation for a row the load path refuses to migrate. Move the cross-line throw into versionOf itself: the plain readers, the needs*Migration predicates, and the migration runners now give one answer for one envelope, and the duplicated guard sites in runLadder/needsLadder collapse into the shared reader. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(dsl): the runtime line has no unversioned epoch — sessions are born stamped (#869) An unstamped object read as 0.0.0 let the runtime ladder lift arbitrary document-shaped data; once a real session transform lands that walk corrupts or throws. The runtime envelope is brand new — nothing legitimately predates it and stores stamp runtimeDslVersion at write — so an unstamped object on the runtime line is always a bug (a misrouted legacy document or an unstamped producer write), not legacy data: - RUNTIME_DSL_MIGRATIONS drops its legacy-lift entry (empty until the first real shape change appends a step from the pinned initial version). - migrateRuntime / needsRuntimeMigration / runtimeDslVersionOf throw on an unstamped object (versionOf gains a per-line legacy version, null meaning no epoch). The document line keeps its legacy lift — real pre-versioning documents exist. - RuntimeSession requires runtimeDslVersion (type and validator), so an unstamped session cannot pass a validated write path and the type/validator contract stays aligned. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * test(dsl): pin the future runtime ladder's first step to the initial version (#869) A non-empty RUNTIME_DSL_MIGRATIONS must start at INITIAL_RUNTIME_DSL_VERSION — the runtime line has no unversioned epoch, so a ladder starting earlier (a copy-pasted 0.0.0 legacy lift) would reintroduce the lift-arbitrary-unstamped-data hole. The contiguity test now asserts the pinned origin as well. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(dsl): restore the empty runtime ladder — drop swept-in local fault injection (#869) e9d480e1 accidentally swept a local-only fault-injection edit (a mistaken 0.0.0 legacy origin used to exercise the new ladder-origin invariant test) into the commit alongside the test change. The injected fault is exactly what the new test guards against — the suite failed on it as intended. Restore the empty ladder; 189 tests green again. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com> Co-authored-by: 杨慎 <117187635+cosarah@users.noreply.github.com>
255 lines
11 KiB
TypeScript
255 lines
11 KiB
TypeScript
import { describe, expect, it } from 'vitest';
|
|
import {
|
|
CHAT_RUNTIME_ROLES,
|
|
CORE_RUNTIME_KINDS,
|
|
QUIZ_ATTEMPT_PHASES,
|
|
RUNTIME_DSL_VERSION,
|
|
RUNTIME_SESSION_STATUSES,
|
|
isChatMessageSkeleton,
|
|
isChatRuntimeRole,
|
|
isCoreRuntimeKind,
|
|
isIsoTimestamp,
|
|
isQuizAttemptPhase,
|
|
isQuizAttemptSkeleton,
|
|
isRuntimeSessionStatus,
|
|
migrateRuntime,
|
|
type ChatMessageSkeleton,
|
|
type QuizAttemptSkeleton,
|
|
type RuntimeRecord,
|
|
type RuntimeRecordInit,
|
|
type RuntimeSession,
|
|
} from '@openmaic/dsl';
|
|
|
|
describe('runtime envelope guards', () => {
|
|
it('accepts every declared session status and rejects others', () => {
|
|
for (const s of RUNTIME_SESSION_STATUSES) expect(isRuntimeSessionStatus(s)).toBe(true);
|
|
expect(isRuntimeSessionStatus('paused')).toBe(false);
|
|
expect(isRuntimeSessionStatus(undefined)).toBe(false);
|
|
expect(isRuntimeSessionStatus(1)).toBe(false);
|
|
});
|
|
|
|
it('accepts every core kind and rejects app-defined kinds', () => {
|
|
expect(CORE_RUNTIME_KINDS).toEqual(['chat', 'quizAttempt', 'playback']);
|
|
for (const k of CORE_RUNTIME_KINDS) expect(isCoreRuntimeKind(k)).toBe(true);
|
|
expect(isCoreRuntimeKind('myWidget')).toBe(false);
|
|
});
|
|
|
|
it('accepts every chat role and quiz phase', () => {
|
|
for (const r of CHAT_RUNTIME_ROLES) expect(isChatRuntimeRole(r)).toBe(true);
|
|
expect(isChatRuntimeRole('tool')).toBe(false);
|
|
for (const p of QUIZ_ATTEMPT_PHASES) expect(isQuizAttemptPhase(p)).toBe(true);
|
|
expect(isQuizAttemptPhase('graded')).toBe(false);
|
|
});
|
|
});
|
|
|
|
describe('runtime envelope shapes (compile-time contract)', () => {
|
|
it('a session owns identity/lifecycle; a record owns ordering/anchoring/payload', () => {
|
|
const session: RuntimeSession = {
|
|
id: 's1',
|
|
kind: 'chat',
|
|
stageId: 'stage1',
|
|
learnerKey: 'anon:device-1',
|
|
status: 'active',
|
|
createdAt: '2026-01-01T00:00:00.000Z',
|
|
updatedAt: '2026-01-01T00:00:00.000Z',
|
|
runtimeDslVersion: '0.1.0',
|
|
};
|
|
const record: RuntimeRecord<ChatMessageSkeleton> = {
|
|
id: 'r1',
|
|
sessionId: session.id,
|
|
seq: 0,
|
|
sceneId: 'scene1',
|
|
actionIndex: 3,
|
|
createdAt: '2026-01-01T00:00:01.000Z',
|
|
payload: { role: 'user', content: 'hello' },
|
|
};
|
|
expect(record.sessionId).toBe(session.id);
|
|
expect(record.payload.role).toBe('user');
|
|
const quiz: RuntimeRecord<QuizAttemptSkeleton> = {
|
|
id: 'r2',
|
|
sessionId: 's2',
|
|
seq: 0,
|
|
sceneId: 'scene2',
|
|
subAnchor: 'question-3',
|
|
createdAt: '2026-01-01T00:00:02.000Z',
|
|
payload: { phase: 'submitted', answers: { q1: 'A' } },
|
|
};
|
|
expect(quiz.payload.phase).toBe('submitted');
|
|
});
|
|
|
|
it('requires runtimeDslVersion on a session at the type level (born stamped)', () => {
|
|
// The stamp is required: a session is born stamped and the runtime line has
|
|
// no unversioned epoch, so a directly-constructed session omitting it is a
|
|
// type error. (Envelope-view code operates over `RuntimeVersioned`, whose
|
|
// field stays optional; this required-ness is specific to `RuntimeSession`.)
|
|
// @ts-expect-error runtimeDslVersion is required on a RuntimeSession
|
|
const bad: RuntimeSession = {
|
|
id: 's1',
|
|
kind: 'chat',
|
|
stageId: 'stage1',
|
|
learnerKey: 'anon:device-1',
|
|
status: 'active',
|
|
createdAt: '2026-01-01T00:00:00.000Z',
|
|
updatedAt: '2026-01-01T00:00:00.000Z',
|
|
};
|
|
void bad;
|
|
const good: RuntimeSession = {
|
|
id: 's1',
|
|
kind: 'chat',
|
|
stageId: 'stage1',
|
|
learnerKey: 'anon:device-1',
|
|
status: 'active',
|
|
createdAt: '2026-01-01T00:00:00.000Z',
|
|
updatedAt: '2026-01-01T00:00:00.000Z',
|
|
runtimeDslVersion: RUNTIME_DSL_VERSION,
|
|
};
|
|
expect(good.runtimeDslVersion).toBe(RUNTIME_DSL_VERSION);
|
|
});
|
|
|
|
it('excludes undefined from payload at the type level (aligns with the validator)', () => {
|
|
// The validator rejects `payload: undefined`; the static type must agree, so
|
|
// `undefined` is not assignable to the payload — this is a type error.
|
|
const bad: RuntimeRecord = {
|
|
id: 'r1',
|
|
sessionId: 's1',
|
|
seq: 0,
|
|
createdAt: '2026-01-01T00:00:01.000Z',
|
|
// @ts-expect-error payload cannot be undefined (RuntimePayload excludes it)
|
|
payload: undefined,
|
|
};
|
|
void bad;
|
|
// `null` stays a legal stored payload (the validator accepts it too).
|
|
const withNull: RuntimeRecord = {
|
|
id: 'r2',
|
|
sessionId: 's1',
|
|
seq: 0,
|
|
createdAt: '2026-01-01T00:00:01.000Z',
|
|
payload: null,
|
|
};
|
|
expect(withNull.payload).toBe(null);
|
|
// The init shape inherits the same constraint via Omit.
|
|
const initBad: RuntimeRecordInit = {
|
|
id: 'r3',
|
|
sessionId: 's1',
|
|
createdAt: '2026-01-01T00:00:01.000Z',
|
|
// @ts-expect-error payload cannot be undefined on the init shape either
|
|
payload: undefined,
|
|
};
|
|
void initBad;
|
|
});
|
|
|
|
it('lets a producer construct a RuntimeRecordInit without a store-assigned seq', () => {
|
|
// Compile-time contract: `seq` is store-owned, so the creation shape omits
|
|
// it. Supplying `seq` here would be a type error; leaving it out type-checks.
|
|
const init: RuntimeRecordInit<ChatMessageSkeleton> = {
|
|
id: 'r1',
|
|
sessionId: 's1',
|
|
createdAt: '2026-01-01T00:00:01.000Z',
|
|
payload: { role: 'assistant', content: 'hi' },
|
|
};
|
|
expect(init.id).toBe('r1');
|
|
});
|
|
});
|
|
|
|
describe('runtime payload skeleton guards', () => {
|
|
it('narrows chat message skeletons and rejects malformed ones', () => {
|
|
expect(isChatMessageSkeleton({ role: 'user', content: 'hi' })).toBe(true);
|
|
expect(isChatMessageSkeleton({ role: 'assistant', content: '' })).toBe(true);
|
|
expect(isChatMessageSkeleton({ role: 'tool', content: 'hi' })).toBe(false); // bad role
|
|
expect(isChatMessageSkeleton({ role: 'user', content: 42 })).toBe(false); // non-string
|
|
expect(isChatMessageSkeleton({ role: 'user' })).toBe(false); // missing content
|
|
expect(isChatMessageSkeleton(null)).toBe(false);
|
|
expect(isChatMessageSkeleton('user')).toBe(false);
|
|
});
|
|
|
|
it('narrows quiz attempt skeletons and rejects malformed ones', () => {
|
|
expect(isQuizAttemptSkeleton({ phase: 'draft', answers: {} })).toBe(true);
|
|
expect(isQuizAttemptSkeleton({ phase: 'submitted', answers: { q1: 'A' } })).toBe(true);
|
|
expect(isQuizAttemptSkeleton({ phase: 'graded', answers: {} })).toBe(false); // bad phase
|
|
expect(isQuizAttemptSkeleton({ phase: 'draft', answers: [] })).toBe(false); // array, not object
|
|
expect(isQuizAttemptSkeleton({ phase: 'draft', answers: null })).toBe(false); // null answers
|
|
expect(isQuizAttemptSkeleton({ phase: 'draft', answers: new Map() })).toBe(false); // Map, not a plain record
|
|
expect(isQuizAttemptSkeleton({ phase: 'draft', answers: new Date() })).toBe(false); // class instance, not a plain record
|
|
expect(isQuizAttemptSkeleton({ phase: 'draft', answers: Object.create(null) })).toBe(true); // null-prototype plain record
|
|
expect(isQuizAttemptSkeleton({ phase: 'draft' })).toBe(false); // missing answers
|
|
expect(isQuizAttemptSkeleton(null)).toBe(false);
|
|
});
|
|
});
|
|
|
|
describe('isIsoTimestamp', () => {
|
|
it('accepts well-formed zoned timestamps', () => {
|
|
expect(isIsoTimestamp('2026-01-01T00:00:00Z')).toBe(true);
|
|
expect(isIsoTimestamp('2026-01-01T00:00:00.000Z')).toBe(true); // fractional seconds
|
|
expect(isIsoTimestamp('2026-01-01T08:00:00+08:00')).toBe(true); // offset form
|
|
expect(isIsoTimestamp('2024-02-29T00:00:00Z')).toBe(true); // real leap day
|
|
});
|
|
|
|
it('rejects calendar-impossible day-of-month, incl. leap-year rules', () => {
|
|
// V8 NORMALIZES full ISO datetimes like Feb 30 into the next month (a real
|
|
// instant, not NaN), so Date.parse cannot reject these; the component-level
|
|
// day-in-month check is what rejects them, engine-independently.
|
|
expect(isIsoTimestamp('2026-02-30T00:00:00.000Z')).toBe(false);
|
|
expect(isIsoTimestamp('2026-02-29T00:00:00.000Z')).toBe(false); // 2026 is not a leap year
|
|
expect(isIsoTimestamp('2024-02-29T00:00:00.000Z')).toBe(true); // divisible by 4 -> leap
|
|
expect(isIsoTimestamp('2026-04-31T00:00:00.000Z')).toBe(false); // April has 30 days
|
|
expect(isIsoTimestamp('2100-02-29T00:00:00.000Z')).toBe(false); // century, not /400 -> not leap
|
|
expect(isIsoTimestamp('2000-02-29T00:00:00.000Z')).toBe(true); // divisible by 400 -> leap
|
|
});
|
|
|
|
it('rejects field-range violations', () => {
|
|
expect(isIsoTimestamp('2026-13-01T00:00:00Z')).toBe(false); // month 13
|
|
expect(isIsoTimestamp('2026-00-15T00:00:00Z')).toBe(false); // month 00
|
|
expect(isIsoTimestamp('2026-01-00T00:00:00Z')).toBe(false); // day 00
|
|
expect(isIsoTimestamp('2026-01-01T25:00:00Z')).toBe(false); // hour 25
|
|
expect(isIsoTimestamp('2026-01-01T24:00:00.000Z')).toBe(false); // hour 24 (no end-of-day form)
|
|
expect(isIsoTimestamp('2026-01-01T00:60:00Z')).toBe(false); // minute 60
|
|
expect(isIsoTimestamp('2026-01-01T00:00:60Z')).toBe(false); // second 60 (leap second not accepted)
|
|
});
|
|
|
|
it('rejects out-of-range numeric zone offsets', () => {
|
|
expect(isIsoTimestamp('2026-01-01T00:00:00+25:00')).toBe(false); // offset hours 25
|
|
expect(isIsoTimestamp('2026-01-01T00:00:00+00:60')).toBe(false); // offset minutes 60
|
|
});
|
|
|
|
it('rejects zoneless and date-only forms (the regex requires a zone + time)', () => {
|
|
expect(isIsoTimestamp('2026-01-01T00:00:00')).toBe(false); // no zone designator
|
|
expect(isIsoTimestamp('2026-01-01')).toBe(false); // date only
|
|
expect(isIsoTimestamp('2026/01/01T00:00:00Z')).toBe(false); // wrong separators
|
|
expect(isIsoTimestamp('not-a-date')).toBe(false);
|
|
});
|
|
});
|
|
|
|
describe('runtime envelope rides the dedicated runtime version ladder', () => {
|
|
it('throws on an unstamped session — the runtime line has no unversioned epoch', () => {
|
|
// A session is born stamped (`runtimeDslVersion` is required, written at
|
|
// creation), so an object arriving WITHOUT the stamp is not legacy data to
|
|
// lift — it is a misrouted legacy document or an unstamped producer write.
|
|
// `migrateRuntime` fails loud rather than inventing a version, because the
|
|
// runtime line has no unversioned epoch (unlike the document line).
|
|
const unstamped: Omit<RuntimeSession, 'runtimeDslVersion'> = {
|
|
id: 's1',
|
|
kind: 'chat',
|
|
stageId: 'stage1',
|
|
learnerKey: 'anon:device-1',
|
|
status: 'active',
|
|
createdAt: '2026-01-01T00:00:00.000Z',
|
|
updatedAt: '2026-01-01T00:00:00.000Z',
|
|
};
|
|
expect(() => migrateRuntime(unstamped)).toThrow(/no unversioned epoch/);
|
|
});
|
|
|
|
it('leaves a current-version session untouched', () => {
|
|
const current: RuntimeSession = {
|
|
id: 's1',
|
|
kind: 'chat',
|
|
stageId: 'stage1',
|
|
learnerKey: 'anon:device-1',
|
|
status: 'active',
|
|
createdAt: '2026-01-01T00:00:00.000Z',
|
|
updatedAt: '2026-01-01T00:00:00.000Z',
|
|
runtimeDslVersion: RUNTIME_DSL_VERSION,
|
|
};
|
|
expect(migrateRuntime(current)).toEqual(current);
|
|
});
|
|
});
|