@kumwe/studio-testkit 0.1.0-alpha.7 → 0.1.0-rc.1

package/dist/host-testbed.d.ts

@@ -1,14 +1,31 @@
-import { type HostAdapter, type HostErrorCategory, type HostPortError, type HostPortResult, type HostRequestContext, type MediaAsset, type MediaUploadAcceptedAsset, type PreviewRenderPayload, type PreviewRenderedPayload, type QualifiedName, type ResourceSearchHit, type Revision, type StableId, type StudioArtifact, type StudioWireProtocolVersion, type TelemetryEvent } from '@kumwe/studio-protocol';
-export type TestbedPortName = 'artifact' | 'localization' | 'media' | 'permission' | 'preview' | 'recovery' | 'resource' | 'telemetry';
+import { HostPortFailure, type HostAdapter, type HostErrorCategory, type HostPortError, type HostPortResult, type HostRequestContext, type JsonObject, type MediaAsset, type MediaUploadAcceptedAsset, type PreviewRenderPayload, type PreviewRenderedPayload, type QualifiedName, type ResourceSearchHit, type Revision, type StableId, type StudioArtifact, type StudioWireProtocolVersion, type TelemetryEvent } from '@kumwe/studio-protocol';
+export type TestbedPortName = 'artifact' | 'localization' | 'media' | 'model' | 'permission' | 'preview' | 'recovery' | 'resource' | 'telemetry';
 export interface TestbedHostOptions {
+    /**
+     * Permits the fixture-only `studio.test/operation` wildcard used by broad
+     * unit tests. Defaults to false and MUST remain false for conformance replay.
+     */
+    allowTestOperationId?: boolean;
     documents?: StudioArtifact[];
+    initialClockMilliseconds?: number;
     mediaAssets?: MediaAsset[];
     messages?: Record<string, Record<QualifiedName, string>>;
     permissions?: QualifiedName[];
-    render?: (payload: PreviewRenderPayload) => PreviewRenderedPayload;
+    rateLimits?: TestbedRateLimitPolicy[];
+    render?: (payload: PreviewRenderPayload) => PreviewRenderedPayload | Promise<PreviewRenderedPayload>;
     resources?: ResourceSearchHit[];
+    /** Exact live generation to seed before the first portable request. */
+    sessionGeneration?: Revision;
+}
+/** A deterministic fixed-window policy used by portable sequence replays. */
+export interface TestbedRateLimitPolicy {
+    maximumRequests: number;
+    operationId: QualifiedName;
+    windowMilliseconds: number;
 }
 export interface TestbedControls {
+    advanceClock(milliseconds: number): void;
+    artifactStatus(id: StableId): StudioArtifact['status'] | undefined;
     disconnect(): void;
     failNext(portName: TestbedPortName, operation: string, category: HostErrorCategory): void;
     /**
@@ -24,7 +41,10 @@ export interface TestbedControls {
      */
     importExternalMedia(candidate: string, context: HostRequestContext): Promise<HostPortResult<MediaUploadAcceptedAsset>>;
     reconnect(): void;
+    recoveryEnvelope(resourceContextKey: StableId): JsonObject | undefined;
     revisionOf(id: StableId): Revision | undefined;
+    readonly pendingPreviewRenders: number;
+    readonly previewDeliveries: readonly string[];
     readonly sessionGeneration: Revision;
     setPermissions(permissions: QualifiedName[]): void;
     readonly telemetryEvents: readonly TelemetryEvent[];
@@ -43,8 +63,7 @@ export interface HostRequestContextFixtureOptions {
     resourceContextKey?: StableId;
     sessionGeneration?: Revision;
 }
-export declare class TestbedHostError extends Error {
-    readonly error: HostPortError;
+export declare class TestbedHostError extends HostPortFailure {
     constructor(error: HostPortError);
 }
 export declare function createHostRequestContextFixture(options?: HostRequestContextFixtureOptions): HostRequestContext;

package/dist/host-testbed.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"host-testbed.d.ts","sourceRoot":"","sources":["../src/host-testbed.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EAGvB,KAAK,UAAU,EACf,KAAK,wBAAwB,EAI7B,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,QAAQ,EACb,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,yBAAyB,EAC9B,KAAK,cAAc,EACpB,MAAM,wBAAwB,CAAC;AAEhC,MAAM,MAAM,eAAe,GACvB,UAAU,GACV,cAAc,GACd,OAAO,GACP,YAAY,GACZ,SAAS,GACT,UAAU,GACV,UAAU,GACV,WAAW,CAAC;AAEhB,MAAM,WAAW,kBAAkB;IACjC,SAAS,CAAC,EAAE,cAAc,EAAE,CAAC;IAC7B,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC,CAAC;IACzD,WAAW,CAAC,EAAE,aAAa,EAAE,CAAC;IAC9B,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,sBAAsB,CAAC;IACnE,SAAS,CAAC,EAAE,iBAAiB,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,IAAI,IAAI,CAAC;IACnB,QAAQ,CAAC,QAAQ,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC1F;;;;;;;;;;OAUG;IACH,mBAAmB,CACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,cAAc,CAAC,wBAAwB,CAAC,CAAC,CAAC;IACrD,SAAS,IAAI,IAAI,CAAC;IAClB,UAAU,CAAC,EAAE,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC/C,QAAQ,CAAC,iBAAiB,EAAE,QAAQ,CAAC;IACrC,cAAc,CAAC,WAAW,EAAE,aAAa,EAAE,GAAG,IAAI,CAAC;IACnD,QAAQ,CAAC,eAAe,EAAE,SAAS,cAAc,EAAE,CAAC;CACrD;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,eAAe,CAAC;IAC1B,IAAI,EAAE,WAAW,CAAC;CACnB;AAED,MAAM,WAAW,gCAAgC;IAC/C,gBAAgB,CAAC,EAAE,QAAQ,CAAC;IAC5B,cAAc,CAAC,EAAE,QAAQ,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,aAAa,CAAC;IAC5B,eAAe,CAAC,EAAE,yBAAyB,CAAC;IAC5C,SAAS,CAAC,EAAE,QAAQ,CAAC;IACrB,kBAAkB,CAAC,EAAE,QAAQ,CAAC;IAC9B,iBAAiB,CAAC,EAAE,QAAQ,CAAC;CAC9B;AAED,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,SAAgB,KAAK,EAAE,aAAa,CAAC;gBAElB,KAAK,EAAE,aAAa;CAKxC;AAED,wBAAgB,+BAA+B,CAC7C,OAAO,GAAE,gCAAqC,GAC7C,kBAAkB,CAapB;AAeD,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,kBAAuB,GAAG,WAAW,CAue/E"}
+{"version":3,"file":"host-testbed.d.ts","sourceRoot":"","sources":["../src/host-testbed.ts"],"names":[],"mappings":"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"}

package/dist/host-testbed.js

@@ -1,11 +1,9 @@
-import { validateExternalUrl } from '@kumwe/studio-core';
-import { STUDIO_CONTRACT_VERSION, STUDIO_WIRE_PROTOCOL_VERSION, } from '@kumwe/studio-protocol';
-export class TestbedHostError extends Error {
-    error;
+import { canonicalStringify, validateExternalUrl } from '@kumwe/studio-core';
+import { HostPortFailure, STUDIO_CONTRACT_VERSION, STUDIO_STALE_SESSION_GENERATION_DIAGNOSTIC_CODE, STUDIO_WIRE_PROTOCOL_VERSION, } from '@kumwe/studio-protocol';
+export class TestbedHostError extends HostPortFailure {
     constructor(error) {
-        super(error.message.defaultMessage ?? error.message.key);
+        super(error);
         this.name = 'TestbedHostError';
-        this.error = error;
     }
 }
 export function createHostRequestContextFixture(options = {}) {
@@ -33,13 +31,21 @@ const PUBLISH_PERMISSION = 'studio.permission/publish';
 const UPLOAD_CHUNK_BYTES = 5_242_880;
 const UPLOAD_MAXIMUM_BYTES = 52_428_800;
 const GRANT_EXPIRY = '2030-01-01T00:00:00Z';
+const MAXIMUM_RATE_LIMIT_REQUESTS = 1000;
+const MAXIMUM_RATE_LIMIT_WINDOW_MILLISECONDS = 86_400_000;
 export function createTestbedHost(options = {}) {
     const artifactStore = new Map();
     for (const seeded of options.documents ?? []) {
         const document = cloneValue(seeded);
-        const revision = `${document.id}-r1`;
-        document.revision = revision;
-        artifactStore.set(document.id, { document, revision, serial: 1 });
+        if (artifactStore.has(document.id)) {
+            throw new TypeError(`Testbed artifact ${document.id} is duplicated.`);
+        }
+        const revision = document.revision;
+        artifactStore.set(document.id, {
+            document,
+            revision,
+            serial: seededRevisionSerial(document.id, revision),
+        });
     }
     const mediaAssets = cloneValue(options.mediaAssets ?? []);
     const resources = cloneValue(options.resources ?? []);
@@ -48,16 +54,43 @@ export function createTestbedHost(options = {}) {
     const telemetryEvents = [];
     const injectedFailures = [];
     const renderCallback = options.render ?? defaultRender;
+    const idempotencyRecords = new Map();
+    const pendingPreviewRenders = new Map();
+    const previewDeliveries = [];
+    const rateLimitPolicies = new Map();
+    const rateLimitWindows = new Map();
+    for (const policy of options.rateLimits ?? []) {
+        if (!Number.isSafeInteger(policy.maximumRequests) ||
+            policy.maximumRequests < 1 ||
+            policy.maximumRequests > MAXIMUM_RATE_LIMIT_REQUESTS ||
+            !Number.isSafeInteger(policy.windowMilliseconds) ||
+            policy.windowMilliseconds < 1 ||
+            policy.windowMilliseconds > MAXIMUM_RATE_LIMIT_WINDOW_MILLISECONDS) {
+            throw new RangeError('Testbed rate limits require positive safe-integer bounds.');
+        }
+        if (rateLimitPolicies.has(policy.operationId)) {
+            throw new TypeError(`Testbed rate limit ${policy.operationId} is duplicated.`);
+        }
+        rateLimitPolicies.set(policy.operationId, { ...policy });
+    }
     const uploadGrants = new Map();
     const acceptedUploads = new Map();
     let uploadSerial = 0;
     let permissions = (options.permissions ?? []).slice();
-    let generationSerial = 1;
+    let liveGeneration = options.sessionGeneration ?? 'session-r1';
+    if (!isNonEmptyString(liveGeneration) || liveGeneration.length > 200) {
+        throw new TypeError('The testbed session generation must be a non-empty bounded revision.');
+    }
+    let generationSerial = seededRevisionSerial('session', liveGeneration);
     let connected = true;
     let correlationSerial = 0;
     let importSerial = 0;
+    let clockMilliseconds = options.initialClockMilliseconds ?? 0;
+    if (!Number.isSafeInteger(clockMilliseconds) || clockMilliseconds < 0) {
+        throw new RangeError('The testbed logical clock must be a non-negative safe integer.');
+    }
     function currentGeneration() {
-        return `session-r${generationSerial}`;
+        return liveGeneration;
     }
     function createError(category, defaultMessage, extras = {}) {
         correlationSerial += 1;
@@ -68,24 +101,20 @@ export function createTestbedHost(options = {}) {
             kind: 'host-error',
             message: { defaultMessage, key: `studio.testbed/${category}` },
             retryable: extras.retryable ?? (category === 'rate-limited' || category === 'unavailable'),
+            ...(extras.diagnostics === undefined ? {} : { diagnostics: cloneValue(extras.diagnostics) }),
+            ...(extras.retryAfterMilliseconds === undefined
+                ? {}
+                : { retryAfterMilliseconds: extras.retryAfterMilliseconds }),
             ...(extras.revision === undefined ? {} : { revision: extras.revision }),
         };
     }
     function fail(category, defaultMessage, extras = {}) {
         throw new TestbedHostError(createError(category, defaultMessage, extras));
     }
-    function guard(portName, operation, context) {
+    function guardEnvelope(portName, operation, context) {
         if (!connected) {
             fail('unavailable', 'The testbed host is disconnected.');
         }
-        const index = injectedFailures.findIndex((entry) => entry.portName === portName && entry.operation === operation);
-        if (index >= 0) {
-            const injected = injectedFailures[index];
-            injectedFailures.splice(index, 1);
-            if (injected !== undefined) {
-                fail(injected.category, 'The testbed injected this failure.');
-            }
-        }
         if (!isNonEmptyString(context.requestId) ||
             !isNonEmptyString(context.operationId) ||
             !isNonEmptyString(context.resourceContextKey) ||
@@ -96,19 +125,122 @@ export function createTestbedHost(options = {}) {
             fail('incompatible', 'The request protocol version is not supported by this testbed.');
         }
         if (context.sessionGeneration !== currentGeneration()) {
-            fail('invalid-request', 'The session generation is no longer valid.');
+            fail('invalid-request', 'The session generation is no longer valid.', {
+                diagnostics: [
+                    {
+                        code: STUDIO_STALE_SESSION_GENERATION_DIAGNOSTIC_CODE,
+                        message: {
+                            defaultMessage: 'The request belongs to an obsolete Studio session generation.',
+                            key: STUDIO_STALE_SESSION_GENERATION_DIAGNOSTIC_CODE,
+                        },
+                        severity: 'blocking',
+                    },
+                ],
+            });
+        }
+        const expectedOperationId = `studio.operation/${portName}.${operation}`;
+        if (context.operationId !== expectedOperationId &&
+            !(options.allowTestOperationId === true && context.operationId === 'studio.test/operation')) {
+            fail('invalid-request', 'The request operation identifier does not match the invoked port.');
         }
     }
-    function run(portName, operation, context, body) {
+    function applyOperationalGuards(portName, operation, context) {
+        const index = injectedFailures.findIndex((entry) => entry.portName === portName && entry.operation === operation);
+        if (index >= 0) {
+            const injected = injectedFailures[index];
+            injectedFailures.splice(index, 1);
+            if (injected !== undefined) {
+                fail(injected.category, 'The testbed injected this failure.');
+            }
+        }
+        const policy = rateLimitPolicies.get(context.operationId);
+        if (policy === undefined) {
+            return;
+        }
+        let rateWindow = rateLimitWindows.get(context.operationId);
+        if (rateWindow === undefined ||
+            clockMilliseconds >= rateWindow.startedAtMilliseconds + policy.windowMilliseconds) {
+            rateWindow = { requestCount: 0, startedAtMilliseconds: clockMilliseconds };
+            rateLimitWindows.set(context.operationId, rateWindow);
+        }
+        if (rateWindow.requestCount >= policy.maximumRequests) {
+            fail('rate-limited', 'The operation has reached its deterministic request bound.', {
+                retryAfterMilliseconds: rateWindow.startedAtMilliseconds + policy.windowMilliseconds - clockMilliseconds,
+            });
+        }
+        rateWindow.requestCount += 1;
+    }
+    async function executeBody(body) {
         try {
-            guard(portName, operation, context);
-            return Promise.resolve(body());
+            return await body();
         }
         catch (error) {
             if (error instanceof TestbedHostError) {
-                return Promise.reject(error);
+                throw error;
+            }
+            throw new TestbedHostError(createError('internal', 'The testbed operation failed unexpectedly.'));
+        }
+    }
+    function run(portName, operation, context, body) {
+        try {
+            guardEnvelope(portName, operation, context);
+            applyOperationalGuards(portName, operation, context);
+            return executeBody(body);
+        }
+        catch (error) {
+            return executeBody(() => {
+                throw error;
+            });
+        }
+    }
+    function runMutation(portName, operation, argument, context, body) {
+        try {
+            guardEnvelope(portName, operation, context);
+            const idempotencyKey = context.idempotencyKey;
+            if (idempotencyKey === undefined) {
+                applyOperationalGuards(portName, operation, context);
+                return executeBody(body);
             }
-            return Promise.reject(new TestbedHostError(createError('internal', 'The testbed operation failed unexpectedly.')));
+            const scope = canonicalStringify({
+                idempotencyKey,
+                operationId: context.operationId,
+                resourceContextKey: context.resourceContextKey,
+                sessionGeneration: context.sessionGeneration,
+            });
+            const fingerprint = canonicalStringify({
+                argument,
+                context: {
+                    ...(context.expectedRevision === undefined
+                        ? {}
+                        : { expectedRevision: context.expectedRevision }),
+                    ...(context.locale === undefined ? {} : { locale: context.locale }),
+                    protocolVersion: context.protocolVersion,
+                },
+            });
+            const prior = idempotencyRecords.get(scope);
+            if (prior !== undefined) {
+                if (prior.fingerprint !== fingerprint) {
+                    fail('invalid-request', 'The idempotency key was already accepted for another intent.');
+                }
+                return prior.promise.then((result) => cloneValue(result));
+            }
+            applyOperationalGuards(portName, operation, context);
+            const accepted = executeBody(body).then((result) => cloneValue(result));
+            idempotencyRecords.set(scope, {
+                fingerprint,
+                promise: accepted,
+            });
+            void accepted.catch(() => {
+                if (idempotencyRecords.get(scope)?.promise === accepted) {
+                    idempotencyRecords.delete(scope);
+                }
+            });
+            return accepted.then((result) => cloneValue(result));
+        }
+        catch (error) {
+            return executeBody(() => {
+                throw error;
+            });
         }
     }
     /**
@@ -176,10 +308,10 @@ export function createTestbedHost(options = {}) {
                 });
             },
             publish(reference, context) {
-                return run('artifact', 'publish', context, () => setStatus(reference.id, context, 'published'));
+                return runMutation('artifact', 'publish', reference, context, () => setStatus(reference.id, context, 'published'));
             },
             save(document, context) {
-                return run('artifact', 'save', context, () => {
+                return runMutation('artifact', 'save', document, context, () => {
                     requireArtifactPermission(SAVE_PERMISSION);
                     const stored = requireStored(document.id);
                     ensureExpectedRevision(stored, context);
@@ -188,7 +320,7 @@ export function createTestbedHost(options = {}) {
                 });
             },
             unpublish(reference, context) {
-                return run('artifact', 'unpublish', context, () => setStatus(reference.id, context, 'draft'));
+                return runMutation('artifact', 'unpublish', reference, context, () => setStatus(reference.id, context, 'draft'));
             },
         },
         localization: {
@@ -211,7 +343,7 @@ export function createTestbedHost(options = {}) {
         },
         media: {
             abortUpload(uploadId, context) {
-                return run('media', 'abort-upload', context, () => {
+                return runMutation('media', 'abort-upload', uploadId, context, () => {
                     if (!uploadGrants.delete(uploadId)) {
                         fail('not-found', 'The requested upload is not available.');
                     }
@@ -219,7 +351,7 @@ export function createTestbedHost(options = {}) {
                 });
             },
             authorizeUpload(request, context) {
-                return run('media', 'authorize-upload', context, () => {
+                return runMutation('media', 'authorize-upload', request, context, () => {
                     assertUploadRequest(request);
                     uploadSerial += 1;
                     const uploadId = `uploads/testbed-${String(uploadSerial)}`;
@@ -240,7 +372,7 @@ export function createTestbedHost(options = {}) {
                 });
             },
             completeUpload(uploadId, context) {
-                return run('media', 'complete-upload', context, () => {
+                return runMutation('media', 'complete-upload', uploadId, context, () => {
                     const pending = uploadGrants.get(uploadId);
                     if (pending === undefined) {
                         fail('not-found', 'The requested upload is not available.');
@@ -287,7 +419,7 @@ export function createTestbedHost(options = {}) {
                 });
             },
             importExternal(url, context) {
-                return run('media', 'import-external', context, () => {
+                return runMutation('media', 'import-external', url, context, () => {
                     const verdict = validateExternalUrl(url);
                     if (!verdict.ok) {
                         // The stable reason is disclosed; the candidate never is.
@@ -313,6 +445,33 @@ export function createTestbedHost(options = {}) {
                 });
             },
         },
+        model: {
+            get(reference, context) {
+                return run('model', 'get', context, () => {
+                    const stored = requireStored(reference.id);
+                    if (stored.document.kind !== 'content-model' ||
+                        stored.document.version !== reference.version ||
+                        ('revision' in reference && reference.revision !== stored.revision)) {
+                        fail('not-found', 'The requested model projection is not available.');
+                    }
+                    return {
+                        revision: stored.revision,
+                        value: cloneValue(stored.document),
+                    };
+                });
+            },
+            list(context) {
+                return run('model', 'list', context, () => {
+                    const value = [...artifactStore.values()]
+                        .filter((stored) => stored.document.kind === 'content-model')
+                        .map((stored) => cloneValue(stored.document))
+                        .sort((left, right) => compareCodeUnits(left.id, right.id) ||
+                        compareCodeUnits(left.version, right.version) ||
+                        compareCodeUnits(left.revision, right.revision));
+                    return { value };
+                });
+            },
+        },
         permission: {
             explain(operation, context) {
                 return run('permission', 'explain', context, () => {
@@ -336,17 +495,48 @@ export function createTestbedHost(options = {}) {
         },
         preview: {
             cancel(draftDigest, context) {
-                return run('preview', 'cancel', context, () => ({ value: null }));
+                return run('preview', 'cancel', context, () => {
+                    const pending = pendingPreviewRenders.get(previewRenderKey(draftDigest, context));
+                    pending?.cancel();
+                    return { value: null };
+                });
             },
             render(payload, context) {
-                return run('preview', 'render', context, () => ({
-                    value: cloneValue(renderCallback(cloneValue(payload))),
-                }));
+                return run('preview', 'render', context, async () => {
+                    const key = previewRenderKey(payload.draftDigest, context);
+                    if (pendingPreviewRenders.has(key)) {
+                        fail('invalid-request', 'A render for this draft is already in flight.');
+                    }
+                    let cancel = () => undefined;
+                    const cancellation = new Promise((_resolve, reject) => {
+                        cancel = () => {
+                            reject(new TestbedHostError(createError('cancelled', 'The in-flight preview render was cancelled.', {
+                                retryable: false,
+                            })));
+                        };
+                    });
+                    pendingPreviewRenders.set(key, { cancel });
+                    try {
+                        const rendered = await Promise.race([
+                            Promise.resolve(renderCallback(cloneValue(payload))),
+                            cancellation,
+                        ]);
+                        if (rendered.draftDigest !== payload.draftDigest ||
+                            rendered.requestId !== payload.requestId) {
+                            fail('internal', 'The preview renderer returned a result for a different render attempt.');
+                        }
+                        previewDeliveries.push(payload.draftDigest);
+                        return { value: cloneValue(rendered) };
+                    }
+                    finally {
+                        pendingPreviewRenders.delete(key);
+                    }
+                });
             },
         },
         recovery: {
             discard(context) {
-                return run('recovery', 'discard', context, () => {
+                return runMutation('recovery', 'discard', null, context, () => {
                     recoveryStore.delete(context.resourceContextKey);
                     return { value: null };
                 });
@@ -359,7 +549,7 @@ export function createTestbedHost(options = {}) {
                 });
             },
             store(envelope, context) {
-                return run('recovery', 'store', context, () => {
+                return runMutation('recovery', 'store', envelope, context, () => {
                     recoveryStore.set(context.resourceContextKey, cloneValue(envelope));
                     return { value: null };
                 });
@@ -390,7 +580,7 @@ export function createTestbedHost(options = {}) {
         },
         telemetry: {
             emit(event, context) {
-                return run('telemetry', 'emit', context, () => {
+                return runMutation('telemetry', 'emit', event, context, () => {
                     if (event.attributes !== undefined) {
                         for (const attribute of Object.values(event.attributes)) {
                             if (!isJsonPrimitiveValue(attribute)) {
@@ -405,6 +595,19 @@ export function createTestbedHost(options = {}) {
         },
     };
     const controls = {
+        advanceClock(milliseconds) {
+            if (!Number.isSafeInteger(milliseconds) || milliseconds < 0) {
+                throw new RangeError('Testbed clock advances must be non-negative safe integers.');
+            }
+            const next = clockMilliseconds + milliseconds;
+            if (!Number.isSafeInteger(next)) {
+                throw new RangeError('The testbed logical clock cannot exceed the safe-integer bound.');
+            }
+            clockMilliseconds = next;
+        },
+        artifactStatus(id) {
+            return artifactStore.get(id)?.document.status;
+        },
         disconnect() {
             connected = false;
         },
@@ -438,15 +641,26 @@ export function createTestbedHost(options = {}) {
         reconnect() {
             connected = true;
         },
+        recoveryEnvelope(resourceContextKey) {
+            const envelope = recoveryStore.get(resourceContextKey);
+            return envelope === undefined ? undefined : cloneValue(envelope);
+        },
         revisionOf(id) {
             return artifactStore.get(id)?.revision;
         },
+        get pendingPreviewRenders() {
+            return pendingPreviewRenders.size;
+        },
+        get previewDeliveries() {
+            return previewDeliveries.slice();
+        },
         get sessionGeneration() {
             return currentGeneration();
         },
         setPermissions(next) {
             permissions = next.slice();
             generationSerial += 1;
+            liveGeneration = `session-r${generationSerial}`;
         },
         get telemetryEvents() {
             return cloneValue(telemetryEvents);
@@ -455,7 +669,25 @@ export function createTestbedHost(options = {}) {
     return { controls, host };
 }
 function defaultRender(payload) {
-    return { diagnostics: [], draftDigest: payload.draftDigest, markers: [] };
+    return {
+        diagnostics: [],
+        draftDigest: payload.draftDigest,
+        markerMap: {},
+        markers: [],
+        requestId: payload.requestId,
+    };
+}
+function previewRenderKey(draftDigest, context) {
+    return `${context.sessionGeneration}\u0000${context.resourceContextKey}\u0000${draftDigest}`;
+}
+function seededRevisionSerial(id, revision) {
+    const prefix = `${id}-r`;
+    if (!revision.startsWith(prefix)) {
+        return 0;
+    }
+    const suffix = revision.slice(prefix.length);
+    const parsed = Number(suffix);
+    return Number.isSafeInteger(parsed) && parsed >= 0 && String(parsed) === suffix ? parsed : 0;
 }
 function isNonEmptyString(value) {
     return typeof value === 'string' && value.length > 0;
@@ -513,6 +745,9 @@ function decodeCursor(cursor) {
 function cloneValue(value) {
     return JSON.parse(JSON.stringify(value));
 }
+function compareCodeUnits(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
 /**
  * The policy gate that runs before any byte moves: a declared upload larger
  * than the host's bound, or one carrying a filename the canonical shape