@adea-ai/spatial 0.94.0 → 0.95.0

package/README.md

@@ -17,6 +17,8 @@ package.
 - `scene-spawn.ts`: cross-app spawn encode/parse and portal URL helpers.
 - `telemetry.ts`: `ScenePerformanceReport` schema, validation, envelope, and
   navigation instrumentation.
+- `sim-bridge/` (subpath `@adea-ai/spatial/sim-bridge`): the contract for embedding
+  a separately hosted Agent Sim page. See below.
 - `data/`: tracked scene manifests (`home/`, `work/`), mirrored from the
   engine's `scenes/sim/assets/`; staged into the web public dir by
   `scripts/sync-assets.mjs`.
@@ -27,3 +29,58 @@ version-range compatibility or verify entry bytes. Tracked scene data is a
 public mirror, not proof that every file matches a particular private source
 revision or distributed pack. Manifest and payload acceptance need separate
 checks against the intended pack.
+
+## Hosted Agent Sim bridge (`@adea-ai/spatial/sim-bridge`)
+
+Schema, validators and a launch contract for a hosted Agent Sim page embedded in an
+iframe. It is a subpath export so the default desktop payload and the app bundle do not
+include it, and it contains no private Agent Sim or asset code. It has no transport of its
+own: callers pass `MessageEvent`-shaped values in and post through `postToFrame` /
+`postToHost`.
+
+- **Messages** (`messages.ts`): a closed, versioned set. Frame to host: `frame.ready`,
+  `frame.state`, `frame.close`, `frame.error`. Host to frame: `host.launch`,
+  `host.dispose`. There is no generic call, eval, filesystem, native-RPC or credential
+  message, and the strict payload shapes reject any extra key (a `token` field included).
+  Each message is accepted only when its sender origin is on the exact allowlist, its
+  `event.source` is the exact frame (or parent) window, its envelope carries the
+  per-mount `bridgeId` the host issued (`createBridgeId`), the version is supported, and
+  it stays inside a finite size, depth, width and node budget (about 2 KiB; cyclic, deep and
+  wide payloads are refused without being walked). Accessor properties are never read, and
+  every discriminant is read as an own data property. Posts never use `*`.
+- **Origins** (`origin.ts`): exact canonical `scheme://host[:port]` strings. No
+  wildcards, suffix matching, paths or `null`. Loopback `http:` needs an explicit
+  `allowLoopbackHttp` opt-in for local development. Being on the allowlist says where a
+  frame was served from. It is not proof of an official desktop identity or an
+  entitlement, and neither is localhost or any value embedded in the app.
+- **Launch** (`launch.ts`): the host asks the Adea backend for a launch
+  (`SimLaunchRequest`); the backend checks entitlement and returns a one-time code valid
+  for at most 120 seconds (`SimLaunchGrant`, which is also refused when it is stale, for
+  another surface, or for a frame origin outside the allowlist). The host posts the code
+  to the frame, which exchanges it at the sim origin for a sim-only session
+  (`SimSessionExchangeRequest` / `SimSessionExchangeResult`). Neither body carries a
+  token. `createLaunchOnce` and `createLaunchCodeLedger` pin the single-use behaviour for
+  the frame and for a backend implementation to match.
+- **Launch service** (`service.ts`): the backend logic for both steps, written against
+  injectable ports and with no I/O, endpoint or storage of its own. `createSimLaunchIssuer`
+  checks a caller-supplied `SimEntitlementChecker` and issues a code through a
+  `SimLaunchCodeStore`; `createSimSessionExchange` redeems it once and returns the
+  `Set-Cookie` value separately from the JSON body. The sim origin and the entitlement source
+  are inputs, never defaults: an absent or invalid origin answers `not_configured` before the
+  entitlement source is asked, and any verdict other than `entitled` fails closed. Nothing
+  here chooses where entitlement comes from, where the sim is hosted, or how stores persist.
+- **Session cookie** (`cookie.ts`): named `__Host-adea-sim`, with `HttpOnly`, `Secure`,
+  `Path=/`, `SameSite=None`, `Partitioned`, no `Domain`, and a lifetime of at most one
+  hour. It authorizes the sim origin's assets only, never an Adea account API.
+- **Availability** (`availability.ts`): `reduceSimLaunch` is a pure state machine
+  (`idle`, `requesting`, `awaiting_frame`, `launching`, `running`, `unavailable`,
+  `offline`), and every state carries an `attempt`: `start` begins attempt N+1 and a
+  grant, frame message or timeout is applied only when it names the current attempt, so
+  a late event from an interrupted attempt cannot launch, fail or close a newer one
+  (mint a fresh `bridgeId` per attempt too). A surface is `running` only after the
+  frame says so, and
+  `describeSimAvailability` gives truthful copy that states Chat and Dev are not affected.
+
+Not part of this package: the hosted entry, the backend endpoints, the private backing
+origin that authorizes assets before serving cached responses, and any credentials or
+deployment. Those are separate work.

package/dist/sim-bridge/availability.d.ts

@@ -0,0 +1,98 @@
+import type { SimFrameMessage } from './messages';
+import type { SimLaunchGrant } from './launch';
+/**
+ * What the host knows about a hosted Agent Sim launch, as a pure state machine. The host shows only
+ * what this state says: nothing is "running" until the frame reports it, and every failure names a
+ * cause. Chat and Dev never read this state, so a failed or offline sim cannot affect them.
+ */
+export declare const SIM_UNAVAILABLE_REASONS: readonly ['unauthenticated', 'not_entitled', 'not_configured', 'service_unavailable', 'origin_refused', 'bridge_incompatible', 'launch_rejected', 'engine_failed', 'frame_timeout'];
+export type SimUnavailableReason = (typeof SIM_UNAVAILABLE_REASONS)[number];
+type GrantedLaunch = Extract<SimLaunchGrant, {
+    status: 'granted';
+}>;
+/**
+ * Every state carries the `attempt` it belongs to. `start` begins attempt N+1, and every event
+ * that answers a specific attempt (`grant`, `frame`, `timeout`) names the attempt it was issued
+ * for. An event for any other attempt is dropped, so a late grant, frame message or timer from an
+ * abandoned attempt can never launch, fail or close a newer one. Callers also mint a fresh
+ * `bridgeId` per attempt, which stops a stale frame at the message layer as well.
+ */
+export type SimLaunchState = Readonly<{
+    phase: 'idle';
+    attempt: number;
+}> | Readonly<{
+    phase: 'requesting';
+    attempt: number;
+}> | Readonly<{
+    phase: 'awaiting_frame';
+    attempt: number;
+    grant: GrantedLaunch;
+}> | Readonly<{
+    phase: 'launching';
+    attempt: number;
+}> | Readonly<{
+    phase: 'running';
+    attempt: number;
+}> | Readonly<{
+    phase: 'unavailable';
+    attempt: number;
+    reason: SimUnavailableReason;
+}> | Readonly<{
+    phase: 'offline';
+    attempt: number;
+}>;
+export type SimLaunchEvent = 
+/**
+ * Begins a new attempt. `online: false` means the host already knows it is offline: the attempt
+ * is recorded as `offline` and no grant is requested, so a surface that mounts offline shows the
+ * offline state (with its retry) instead of staying idle, and the backend is never asked.
+ */
+Readonly<{
+    type: 'start';
+    online?: boolean;
+}>
+/** The backend's parsed reply for `attempt`; `null` is a reply that failed validation. */
+ | Readonly<{
+    type: 'grant';
+    attempt: number;
+    grant: SimLaunchGrant | null;
+}> | Readonly<{
+    type: 'frame';
+    attempt: number;
+    message: SimFrameMessage;
+    now: number;
+}> | Readonly<{
+    type: 'timeout';
+    attempt: number;
+}> | Readonly<{
+    type: 'offline';
+}> | Readonly<{
+    type: 'dispose';
+}>;
+export type SimLaunchEffect = Readonly<{
+    type: 'request_grant';
+    attempt: number;
+}> | Readonly<{
+    type: 'post_launch';
+    attempt: number;
+    grant: GrantedLaunch;
+}> | Readonly<{
+    type: 'dispose_frame';
+    attempt: number;
+}>;
+export type SimLaunchStep = Readonly<{
+    state: SimLaunchState;
+    effect?: SimLaunchEffect;
+}>;
+export declare const SIM_IDLE: SimLaunchState;
+export declare function reduceSimLaunch(state: SimLaunchState, event: SimLaunchEvent): SimLaunchStep;
+export type SimAvailabilityNotice = Readonly<{
+    tone: 'neutral' | 'error';
+    title: string;
+    detail: string;
+    /** Whether trying again can help without the user changing anything else. */
+    retryable: boolean;
+}>;
+/** Truthful copy for a state, or null when the surface has nothing to say (idle, loading, running). */
+export declare function describeSimAvailability(state: SimLaunchState): SimAvailabilityNotice | null;
+export {};

package/dist/sim-bridge/availability.js

@@ -0,0 +1,181 @@
+/**
+ * What the host knows about a hosted Agent Sim launch, as a pure state machine. The host shows only
+ * what this state says: nothing is "running" until the frame reports it, and every failure names a
+ * cause. Chat and Dev never read this state, so a failed or offline sim cannot affect them.
+ */
+export const SIM_UNAVAILABLE_REASONS = [
+    'unauthenticated',
+    'not_entitled',
+    'not_configured',
+    'service_unavailable',
+    'origin_refused',
+    'bridge_incompatible',
+    'launch_rejected',
+    'engine_failed',
+    'frame_timeout',
+];
+const FRAME_ERROR_REASONS = {
+    launch_rejected: 'launch_rejected',
+    asset_unavailable: 'service_unavailable',
+    engine_failed: 'engine_failed',
+    bridge_incompatible: 'bridge_incompatible',
+};
+export const SIM_IDLE = { phase: 'idle', attempt: 0 };
+function stay(state) {
+    return { state };
+}
+function unavailable(attempt, reason) {
+    return { state: { phase: 'unavailable', attempt, reason } };
+}
+function reduceFrame(state, message, now) {
+    const { attempt } = state;
+    switch (message.type) {
+        case 'frame.ready': {
+            // Only the first ready of an awaited frame launches; a replay changes nothing.
+            if (state.phase !== 'awaiting_frame')
+                return stay(state);
+            if (Date.parse(state.grant.expiresAt) <= now)
+                return unavailable(attempt, 'frame_timeout');
+            return {
+                state: { phase: 'launching', attempt },
+                effect: { type: 'post_launch', attempt, grant: state.grant },
+            };
+        }
+        case 'frame.state': {
+            if (state.phase !== 'launching' && state.phase !== 'running')
+                return stay(state);
+            const { state: reported, reason } = message.payload;
+            if (reported === 'running')
+                return stay({ phase: 'running', attempt });
+            if (reported === 'offline')
+                return stay({ phase: 'offline', attempt });
+            if (reported === 'unavailable')
+                return unavailable(attempt, reason ?? 'service_unavailable');
+            return stay(state);
+        }
+        case 'frame.error':
+            // A frame that fails before it ever reports ready (an engine that cannot start, a bridge
+            // version the host does not speak) is a failure of this attempt, not noise.
+            if (state.phase !== 'awaiting_frame' &&
+                state.phase !== 'launching' &&
+                state.phase !== 'running')
+                return stay(state);
+            return unavailable(attempt, FRAME_ERROR_REASONS[message.payload.code]);
+        case 'frame.close':
+            return state.phase === 'idle' ? stay(state) : stay({ phase: 'idle', attempt });
+    }
+}
+export function reduceSimLaunch(state, event) {
+    const { attempt } = state;
+    switch (event.type) {
+        case 'start': {
+            if (state.phase !== 'idle' && state.phase !== 'unavailable' && state.phase !== 'offline')
+                return stay(state);
+            const next = attempt + 1;
+            if (event.online === false)
+                return stay({ phase: 'offline', attempt: next });
+            return {
+                state: { phase: 'requesting', attempt: next },
+                effect: { type: 'request_grant', attempt: next },
+            };
+        }
+        case 'grant': {
+            if (event.attempt !== attempt || state.phase !== 'requesting')
+                return stay(state);
+            const { grant } = event;
+            if (!grant)
+                return unavailable(attempt, 'service_unavailable');
+            if (grant.status === 'granted')
+                return stay({ phase: 'awaiting_frame', attempt, grant });
+            return unavailable(attempt, grant.reason);
+        }
+        case 'frame':
+            return event.attempt === attempt ? reduceFrame(state, event.message, event.now) : stay(state);
+        case 'timeout':
+            return event.attempt === attempt &&
+                (state.phase === 'awaiting_frame' || state.phase === 'launching')
+                ? unavailable(attempt, 'frame_timeout')
+                : stay(state);
+        case 'offline':
+            return state.phase === 'idle' ? stay(state) : stay({ phase: 'offline', attempt });
+        case 'dispose':
+            return state.phase === 'idle'
+                ? stay(state)
+                : { state: { phase: 'idle', attempt }, effect: { type: 'dispose_frame', attempt } };
+    }
+}
+const REASON_COPY = {
+    unauthenticated: {
+        title: 'Sign in to open Agent Sim',
+        detail: 'Agent Sim needs your Adea account.',
+        retryable: false,
+    },
+    not_entitled: {
+        title: 'Agent Sim is not included in this account',
+        detail: 'Your account does not include Agent Sim.',
+        retryable: false,
+    },
+    not_configured: {
+        title: 'Agent Sim is not set up here',
+        detail: 'This deployment has no Agent Sim service configured.',
+        retryable: false,
+    },
+    service_unavailable: {
+        title: 'Agent Sim is unavailable right now',
+        detail: 'The Agent Sim service did not respond.',
+        retryable: true,
+    },
+    origin_refused: {
+        title: 'Agent Sim was blocked',
+        detail: 'The Agent Sim frame did not come from an allowed address.',
+        retryable: false,
+    },
+    bridge_incompatible: {
+        title: 'Agent Sim needs an update',
+        detail: 'This version of Adea and Agent Sim cannot talk to each other.',
+        retryable: false,
+    },
+    launch_rejected: {
+        title: 'Agent Sim could not start',
+        detail: 'The launch was refused or had already expired.',
+        retryable: true,
+    },
+    engine_failed: {
+        title: 'Agent Sim stopped working',
+        detail: 'The simulation hit an error.',
+        retryable: true,
+    },
+    frame_timeout: {
+        title: 'Agent Sim took too long to start',
+        detail: 'It did not finish loading in time.',
+        retryable: true,
+    },
+};
+const INDEPENDENCE = ' Chat and Dev are not affected.';
+/** Truthful copy for a state, or null when the surface has nothing to say (idle, loading, running). */
+export function describeSimAvailability(state) {
+    switch (state.phase) {
+        case 'offline':
+            return {
+                tone: 'error',
+                title: 'Agent Sim is offline',
+                detail: `You are offline, so Agent Sim cannot load.${INDEPENDENCE}`,
+                retryable: true,
+            };
+        case 'unavailable': {
+            const copy = REASON_COPY[state.reason];
+            return { tone: 'error', ...copy, detail: `${copy.detail}${INDEPENDENCE}` };
+        }
+        case 'requesting':
+        case 'awaiting_frame':
+        case 'launching':
+            return {
+                tone: 'neutral',
+                title: 'Opening Agent Sim',
+                detail: 'Checking your account and loading the simulation.',
+                retryable: false,
+            };
+        default:
+            return null;
+    }
+}

package/dist/sim-bridge/cookie.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The sim-only session cookie set by the Agent Sim origin after a successful code exchange.
+ *
+ * It is `__Host-` prefixed (Secure, Path=/, no Domain), HttpOnly so no script on either origin can
+ * read it, and `SameSite=None; Partitioned` because the sim is embedded as a third-party frame: the
+ * browser keys it to the embedding Adea site and never sends it in any other context. It
+ * authorizes the sim origin's assets only; it is not an Adea account session and never appears in a
+ * response body or a bridge message.
+ */
+export declare const SIM_SESSION_COOKIE_NAME = "__Host-adea-sim";
+export declare const MAX_SIM_SESSION_SECONDS = 3600;
+export declare function buildSimSessionSetCookie(value: string, maxAgeSeconds: number): string;
+/** Expires the session on the client. */
+export declare function buildSimSessionClearCookie(): string;
+/** Every way a `Set-Cookie` header departs from the contract; empty means it conforms. */
+export declare function simSessionCookieViolations(header: string): readonly string[];
+/**
+ * The session value from a request's `Cookie` header, or null unless exactly one sim cookie of
+ * the right shape is present (a duplicate is refused rather than guessed between).
+ */
+export declare function readSimSessionCookie(cookieHeader: string | null | undefined): string | null;

package/dist/sim-bridge/cookie.js

@@ -0,0 +1,85 @@
+/**
+ * The sim-only session cookie set by the Agent Sim origin after a successful code exchange.
+ *
+ * It is `__Host-` prefixed (Secure, Path=/, no Domain), HttpOnly so no script on either origin can
+ * read it, and `SameSite=None; Partitioned` because the sim is embedded as a third-party frame: the
+ * browser keys it to the embedding Adea site and never sends it in any other context. It
+ * authorizes the sim origin's assets only; it is not an Adea account session and never appears in a
+ * response body or a bridge message.
+ */
+export const SIM_SESSION_COOKIE_NAME = '__Host-adea-sim';
+export const MAX_SIM_SESSION_SECONDS = 3600;
+const SESSION_VALUE = /^[A-Za-z0-9_-]{32,256}$/;
+export function buildSimSessionSetCookie(value, maxAgeSeconds) {
+    if (!SESSION_VALUE.test(value))
+        throw new Error('Invalid Agent Sim session value');
+    return setCookie(value, boundedMaxAge(maxAgeSeconds));
+}
+/** Expires the session on the client. */
+export function buildSimSessionClearCookie() {
+    return setCookie('', 0);
+}
+function boundedMaxAge(seconds) {
+    if (!Number.isInteger(seconds) || seconds < 1 || seconds > MAX_SIM_SESSION_SECONDS)
+        throw new Error('Agent Sim session lifetime out of range');
+    return seconds;
+}
+function setCookie(value, maxAge) {
+    return [
+        `${SIM_SESSION_COOKIE_NAME}=${value}`,
+        `Max-Age=${maxAge}`,
+        'Path=/',
+        'Secure',
+        'HttpOnly',
+        'SameSite=None',
+        'Partitioned',
+    ].join('; ');
+}
+/** Every way a `Set-Cookie` header departs from the contract; empty means it conforms. */
+export function simSessionCookieViolations(header) {
+    const [pair = '', ...attributes] = header.split(';').map((part) => part.trim());
+    const violations = [];
+    if (!pair.startsWith(`${SIM_SESSION_COOKIE_NAME}=`))
+        violations.push('name');
+    const names = new Map();
+    for (const attribute of attributes) {
+        const index = attribute.indexOf('=');
+        const key = (index === -1 ? attribute : attribute.slice(0, index)).toLowerCase();
+        if (names.has(key))
+            violations.push(`duplicate:${key}`);
+        names.set(key, index === -1 ? '' : attribute.slice(index + 1));
+    }
+    if (!names.has('secure'))
+        violations.push('secure');
+    if (!names.has('httponly'))
+        violations.push('httponly');
+    if (!names.has('partitioned'))
+        violations.push('partitioned');
+    if (names.get('path') !== '/')
+        violations.push('path');
+    if (names.has('domain'))
+        violations.push('domain');
+    if (names.get('samesite')?.toLowerCase() !== 'none')
+        violations.push('samesite');
+    const maxAge = names.get('max-age');
+    if (maxAge === undefined || !/^\d+$/.test(maxAge) || Number(maxAge) > MAX_SIM_SESSION_SECONDS)
+        violations.push('max-age');
+    if (names.has('expires'))
+        violations.push('expires');
+    return violations;
+}
+/**
+ * The session value from a request's `Cookie` header, or null unless exactly one sim cookie of
+ * the right shape is present (a duplicate is refused rather than guessed between).
+ */
+export function readSimSessionCookie(cookieHeader) {
+    if (!cookieHeader)
+        return null;
+    const values = cookieHeader
+        .split(';')
+        .map((part) => part.trim())
+        .filter((part) => part.startsWith(`${SIM_SESSION_COOKIE_NAME}=`))
+        .map((part) => part.slice(SIM_SESSION_COOKIE_NAME.length + 1));
+    const [only] = values;
+    return values.length === 1 && only !== undefined && SESSION_VALUE.test(only) ? only : null;
+}

package/dist/sim-bridge/index.d.ts

@@ -0,0 +1,6 @@
+export * from './availability';
+export * from './cookie';
+export * from './launch';
+export * from './messages';
+export * from './origin';
+export * from './service';

package/dist/sim-bridge/index.js

@@ -0,0 +1,6 @@
+export * from './availability';
+export * from './cookie';
+export * from './launch';
+export * from './messages';
+export * from './origin';
+export * from './service';

package/dist/sim-bridge/launch.d.ts

@@ -0,0 +1,111 @@
+import type { OriginAllowlist } from './origin';
+/**
+ * Launch contract between the Adea host, the Adea backend and the hosted Agent Sim origin.
+ *
+ * 1. The host asks the Adea backend to launch a surface (`SimLaunchRequest`). The backend checks
+ *    the signed-in account's entitlement; localhost, an embedded secret or the desktop shell's
+ *    claimed identity are never proof of it.
+ * 2. A granted reply carries one opaque, single-use, short-lived `code`, bound to the host's
+ *    `bridgeId`, the sim origin and the surface. It is not a session and not a credential for any
+ *    other Adea API.
+ * 3. The host posts the code to the sim frame (`host.launch`). The frame calls the sim origin's
+ *    exchange (`SimSessionExchangeRequest`); the sim origin redeems the code once and sets a
+ *    sim-only session cookie (see `cookie.ts`). No token appears in any request or response body.
+ *
+ * Every parser here is strict: unknown keys, wrong types and token-looking extras are refused.
+ */
+export declare const SIM_LAUNCH_SCHEMA_VERSION = 1;
+/** A launch code is useless after this long, whatever the backend says. */
+export declare const MAX_SIM_LAUNCH_TTL_MS = 120000;
+export declare const SIM_SURFACES: readonly ['hq', 'character-designer', 'room-designer'];
+export type SimSurface = (typeof SIM_SURFACES)[number];
+export declare const SIM_PLATFORMS: readonly ['desktop', 'web'];
+export type SimPlatform = (typeof SIM_PLATFORMS)[number];
+export type SimLaunchRequest = Readonly<{
+    schemaVersion: typeof SIM_LAUNCH_SCHEMA_VERSION;
+    workspaceId: string;
+    surface: SimSurface;
+    platform: SimPlatform;
+    bridgeId: string;
+}>;
+export type SimLaunchDeniedReason = 'unauthenticated' | 'not_entitled';
+export type SimLaunchUnavailableReason = 'not_configured' | 'service_unavailable';
+export type SimLaunchGrant = Readonly<{
+    status: 'granted';
+    code: string;
+    expiresAt: string;
+    surface: SimSurface;
+    frameOrigin: string;
+}> | Readonly<{
+    status: 'denied';
+    reason: SimLaunchDeniedReason;
+}> | Readonly<{
+    status: 'unavailable';
+    reason: SimLaunchUnavailableReason;
+}>;
+export type SimSessionExchangeRequest = Readonly<{
+    schemaVersion: typeof SIM_LAUNCH_SCHEMA_VERSION;
+    code: string;
+    bridgeId: string;
+}>;
+export type SimSessionRejectedReason = 'code_expired' | 'code_used' | 'not_entitled' | 'origin_refused';
+export type SimSessionExchangeResult = Readonly<{
+    status: 'session';
+    expiresAt: string;
+}> | Readonly<{
+    status: 'rejected';
+    reason: SimSessionRejectedReason;
+}> | Readonly<{
+    status: 'unavailable';
+}>;
+export declare function parseSimLaunchRequest(value: unknown): SimLaunchRequest | null;
+export type SimGrantExpectation = Readonly<{
+    origins: OriginAllowlist;
+    /** Epoch milliseconds the host considers "now". */
+    now: number;
+    /** The surface the host asked for; a grant for any other surface is refused. */
+    surface: SimSurface;
+}>;
+/**
+ * The backend's launch reply, or null when it is malformed, stale, longer-lived than the contract
+ * allows, for another surface, or points at a frame origin the host did not allowlist.
+ */
+export declare function parseSimLaunchGrant(value: unknown, expected: SimGrantExpectation): SimLaunchGrant | null;
+export declare function parseSimSessionExchangeRequest(value: unknown): SimSessionExchangeRequest | null;
+/** The sim origin's exchange reply. A session reply carries its expiry and nothing else. */
+export declare function parseSimSessionExchangeResult(value: unknown): SimSessionExchangeResult | null;
+export type SimLaunchPayload = Readonly<{
+    code: string;
+    expiresAt: string;
+    surface: SimSurface;
+    character?: string;
+}>;
+/**
+ * Frame side: accepts the first launch payload still inside its window and refuses every later one,
+ * so a replayed or duplicated `host.launch` can never trigger a second exchange.
+ */
+export declare function createLaunchOnce(): Readonly<{
+    take(payload: SimLaunchPayload, now: number): SimLaunchPayload | null;
+}>;
+export type LaunchCodeBinding = Readonly<{
+    bridgeId: string;
+    origin: string;
+    surface: SimSurface;
+}>;
+export type LaunchCodeRedemption = Readonly<{
+    ok: true;
+    surface: SimSurface;
+}> | Readonly<{
+    ok: false;
+    reason: 'unknown' | 'code_expired' | 'code_used' | 'origin_refused';
+}>;
+/**
+ * Reference single-use semantics for the backend's code exchange, used by the local bootstrap tests.
+ * A code redeems at most once: it is spent by its first presentation, whether or not that
+ * presentation matched the binding, so a leaked code cannot be retried with guessed bindings.
+ * A durable implementation keeps the same observable behaviour.
+ */
+export declare function createLaunchCodeLedger(): Readonly<{
+    issue(code: string, binding: LaunchCodeBinding, expiresAt: number): void;
+    redeem(code: string, presented: Omit<LaunchCodeBinding, 'surface'>, now: number): LaunchCodeRedemption;
+}>;