wyuc 83fdecf399
feat(dsl): runtime envelope — RuntimeSession + RuntimeRecord + core-kind skeletons (#869 Part A) (#870)
* 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>
2026-07-08 17:47:30 +08:00

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);
});
});