@kumwe/studio-testkit 0.1.0-alpha.6 → 0.1.0-alpha.8

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';
+import { 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' | '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[];

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,EAE7B,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,CAsY/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,4 +1,4 @@
-import { validateExternalUrl } from '@kumwe/studio-core';
+import { canonicalStringify, validateExternalUrl } from '@kumwe/studio-core';
 import { STUDIO_CONTRACT_VERSION, STUDIO_WIRE_PROTOCOL_VERSION, } from '@kumwe/studio-protocol';
 export class TestbedHostError extends Error {
     error;
@@ -22,13 +22,32 @@ export function createHostRequestContextFixture(options = {}) {
         sessionGeneration: options.sessionGeneration ?? 'session-r1',
     };
 }
+/**
+ * The permissions this reference host gates artifact mutations behind. A host
+ * chooses its own names; what the contract fixes is that a mutation is
+ * authorized and that a withheld permission is refused as `forbidden`.
+ */
+const SAVE_PERMISSION = 'studio.permission/save';
+const PUBLISH_PERMISSION = 'studio.permission/publish';
+/** Deterministic bounds the reference host authorizes uploads within. */
+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 ?? []);
@@ -37,13 +56,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;
@@ -54,24 +103,19 @@ export function createTestbedHost(options = {}) {
             kind: 'host-error',
             message: { defaultMessage, key: `studio.testbed/${category}` },
             retryable: extras.retryable ?? (category === 'rate-limited' || category === 'unavailable'),
+            ...(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) ||
@@ -84,17 +128,120 @@ export function createTestbedHost(options = {}) {
         if (context.sessionGeneration !== currentGeneration()) {
             fail('invalid-request', 'The session generation is no longer valid.');
         }
+        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;
             }
-            return Promise.reject(new TestbedHostError(createError('internal', 'The testbed operation failed unexpectedly.')));
+            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);
+            }
+            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;
+            });
+        }
+    }
+    /**
+     * The authorization gate a production host applies to every mutation. Reads
+     * are authorized by the resolved request context; mutations additionally
+     * require the host-declared permission for the operation, and a withheld
+     * permission is refused without disclosing whether the artifact exists.
+     */
+    function requireArtifactPermission(permission) {
+        if (!permissions.includes(permission)) {
+            fail('forbidden', 'The session does not hold the permission this operation requires.');
         }
     }
     function requireStored(id) {
@@ -118,6 +265,7 @@ export function createTestbedHost(options = {}) {
         return stored.revision;
     }
     function setStatus(id, context, status) {
+        requireArtifactPermission(PUBLISH_PERMISSION);
         const stored = requireStored(id);
         ensureExpectedRevision(stored, context);
         stored.document.status = status;
@@ -150,10 +298,11 @@ 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);
                     stored.document = cloneValue(document);
@@ -161,7 +310,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: {
@@ -183,6 +332,53 @@ export function createTestbedHost(options = {}) {
             },
         },
         media: {
+            abortUpload(uploadId, context) {
+                return runMutation('media', 'abort-upload', uploadId, context, () => {
+                    if (!uploadGrants.delete(uploadId)) {
+                        fail('not-found', 'The requested upload is not available.');
+                    }
+                    return { value: null };
+                });
+            },
+            authorizeUpload(request, context) {
+                return runMutation('media', 'authorize-upload', request, context, () => {
+                    assertUploadRequest(request);
+                    uploadSerial += 1;
+                    const uploadId = `uploads/testbed-${String(uploadSerial)}`;
+                    const grant = {
+                        expiresAt: GRANT_EXPIRY,
+                        headers: { 'X-Upload-Session': uploadId },
+                        method: 'PUT',
+                        plan: {
+                            chunkBytes: UPLOAD_CHUNK_BYTES,
+                            maximumBytes: UPLOAD_MAXIMUM_BYTES,
+                            resumable: true,
+                        },
+                        uploadId,
+                        url: `https://uploads.testbed.invalid/${uploadId}`,
+                    };
+                    uploadGrants.set(uploadId, { grant, request: cloneValue(request) });
+                    return { value: cloneValue(grant) };
+                });
+            },
+            completeUpload(uploadId, 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.');
+                    }
+                    uploadGrants.delete(uploadId);
+                    // The host verifies what it received; a declared media type is
+                    // never trusted, so acceptance lands in `processing`.
+                    const accepted = {
+                        id: `assets/${uploadId.replace('uploads/', '')}`,
+                        revision: `${uploadId}-r1`,
+                        state: 'processing',
+                    };
+                    acceptedUploads.set(accepted.id, accepted);
+                    return { revision: accepted.revision, value: cloneValue(accepted) };
+                });
+            },
             get(assetId, context) {
                 return run('media', 'get', context, () => {
                     const asset = mediaAssets.find((entry) => entry.id === assetId);
@@ -212,6 +408,32 @@ export function createTestbedHost(options = {}) {
                     };
                 });
             },
+            importExternal(url, context) {
+                return runMutation('media', 'import-external', url, context, () => {
+                    const verdict = validateExternalUrl(url);
+                    if (!verdict.ok) {
+                        // The stable reason is disclosed; the candidate never is.
+                        fail('validation-failed', `The external media candidate was refused: ${verdict.reason}.`);
+                    }
+                    importSerial += 1;
+                    const accepted = {
+                        id: `assets/imported-${String(importSerial)}`,
+                        revision: `imports/testbed-${String(importSerial)}-r1`,
+                        state: 'processing',
+                    };
+                    acceptedUploads.set(accepted.id, accepted);
+                    return { revision: accepted.revision, value: cloneValue(accepted) };
+                });
+            },
+            uploadStatus(assetId, context) {
+                return run('media', 'upload-status', context, () => {
+                    const accepted = acceptedUploads.get(assetId);
+                    if (accepted === undefined) {
+                        fail('not-found', 'The requested asset is not available.');
+                    }
+                    return { revision: accepted.revision, value: cloneValue(accepted) };
+                });
+            },
         },
         permission: {
             explain(operation, context) {
@@ -236,17 +458,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 };
                 });
@@ -259,7 +512,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 };
                 });
@@ -290,7 +543,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)) {
@@ -305,6 +558,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;
         },
@@ -338,15 +604,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);
@@ -355,7 +632,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;
@@ -413,4 +708,35 @@ function decodeCursor(cursor) {
 function cloneValue(value) {
     return JSON.parse(JSON.stringify(value));
 }
+/**
+ * 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
+ * refuses, is rejected at authorization rather than after a transfer.
+ */
+function assertUploadRequest(request) {
+    if (request.byteSize > UPLOAD_MAXIMUM_BYTES) {
+        throw new TestbedHostError({
+            category: 'limit-exceeded',
+            contractVersion: STUDIO_CONTRACT_VERSION,
+            kind: 'host-error',
+            message: {
+                defaultMessage: 'The declared upload exceeds the accepted size.',
+                key: 'studio.testbed/limit-exceeded',
+            },
+            retryable: false,
+        });
+    }
+    if (request.filename.includes('/') || request.filename.includes('\\')) {
+        throw new TestbedHostError({
+            category: 'validation-failed',
+            contractVersion: STUDIO_CONTRACT_VERSION,
+            kind: 'host-error',
+            message: {
+                defaultMessage: 'The declared filename is not a canonical display name.',
+                key: 'studio.testbed/validation-failed',
+            },
+            retryable: false,
+        });
+    }
+}
 //# sourceMappingURL=host-testbed.js.map