@adea-ai/spatial 0.94.0 → 0.96.0

package/src/sim-bridge/availability.ts

@@ -0,0 +1,238 @@
+import type { SimFrameStatusMessage } 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 const SIM_UNAVAILABLE_REASONS = [
+  'unauthenticated',
+  'not_entitled',
+  'not_configured',
+  'service_unavailable',
+  'origin_refused',
+  'bridge_incompatible',
+  'launch_rejected',
+  'engine_failed',
+  'frame_timeout',
+] as const
+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: SimFrameStatusMessage; 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 }>
+
+const FRAME_ERROR_REASONS = {
+  launch_rejected: 'launch_rejected',
+  asset_unavailable: 'service_unavailable',
+  engine_failed: 'engine_failed',
+  bridge_incompatible: 'bridge_incompatible',
+} as const
+
+export const SIM_IDLE: SimLaunchState = { phase: 'idle', attempt: 0 }
+
+function stay(state: SimLaunchState): SimLaunchStep {
+  return { state }
+}
+
+function unavailable(attempt: number, reason: SimUnavailableReason): SimLaunchStep {
+  return { state: { phase: 'unavailable', attempt, reason } }
+}
+
+function reduceFrame(
+  state: SimLaunchState,
+  message: SimFrameStatusMessage,
+  now: number
+): SimLaunchStep {
+  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: SimLaunchState, event: SimLaunchEvent): SimLaunchStep {
+  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 } }
+  }
+}
+
+export type SimAvailabilityNotice = Readonly<{
+  tone: 'neutral' | 'error'
+  title: string
+  detail: string
+  /** Whether trying again can help without the user changing anything else. */
+  retryable: boolean
+}>
+
+const REASON_COPY: Record<SimUnavailableReason, Omit<SimAvailabilityNotice, 'tone'>> = {
+  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: SimLaunchState): SimAvailabilityNotice | null {
+  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/src/sim-bridge/character.ts

@@ -0,0 +1,53 @@
+/**
+ * The character value the bridge carries in `host.launch` and `frame.character.save`.
+ *
+ * Two forms, both finite and structurally checked. The bridge never learns the private part
+ * catalog: slot contents are bounded opaque ids and the engine keeps validating membership.
+ *
+ * 1. A catalog id, such as `configurable`.
+ * 2. `character:v1:` followed by exactly 13 `|`-separated slots in `SIM_CHARACTER_SLOTS` order.
+ *    An empty slot is `-`, and `body` is required.
+ */
+
+export const SIM_CHARACTER_SLOTS = [
+  'body',
+  'ears',
+  'face',
+  'hair',
+  'hat',
+  'top',
+  'bottom',
+  'shoes',
+  'socks',
+  'glasses',
+  'gloves',
+  'accessory',
+  'costume',
+] as const
+
+export const SIM_SERIALIZED_CHARACTER_PREFIX = 'character:v1:'
+/** The audited serializer's longest value is 251 characters; this leaves headroom, not slack. */
+export const MAX_SIM_SERIALIZED_CHARACTER_LENGTH = 384
+
+const CATALOG_ID = /^[A-Za-z0-9_.:-]{1,64}$/
+const SLOT_PART_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,47}$/
+const EMPTY_SLOT = '-'
+
+export function isSerializedSimCharacter(value: unknown): value is string {
+  if (
+    typeof value !== 'string' ||
+    value.length > MAX_SIM_SERIALIZED_CHARACTER_LENGTH ||
+    !value.startsWith(SIM_SERIALIZED_CHARACTER_PREFIX)
+  )
+    return false
+  const slots = value.slice(SIM_SERIALIZED_CHARACTER_PREFIX.length).split('|')
+  if (slots.length !== SIM_CHARACTER_SLOTS.length) return false
+  return slots.every((slot, index) => (slot === EMPTY_SLOT ? index !== 0 : SLOT_PART_ID.test(slot)))
+}
+
+/** The value when it is a catalog id or a well-formed serialized character; otherwise null. */
+export function parseSimCharacterValue(value: unknown): string | null {
+  if (typeof value !== 'string') return null
+  if (value.startsWith('character:')) return isSerializedSimCharacter(value) ? value : null
+  return CATALOG_ID.test(value) ? value : null
+}

package/src/sim-bridge/cookie.ts

@@ -0,0 +1,82 @@
+/**
+ * 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: string, maxAgeSeconds: number): string {
+  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(): string {
+  return setCookie('', 0)
+}
+
+function boundedMaxAge(seconds: number): number {
+  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: string, maxAge: number): string {
+  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: string): readonly string[] {
+  const [pair = '', ...attributes] = header.split(';').map((part) => part.trim())
+  const violations: string[] = []
+  if (!pair.startsWith(`${SIM_SESSION_COOKIE_NAME}=`)) violations.push('name')
+  const names = new Map<string, string>()
+  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: string | null | undefined): string | null {
+  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/src/sim-bridge/index.ts

@@ -0,0 +1,8 @@
+export * from './availability'
+export * from './character'
+export * from './cookie'
+export * from './launch'
+export * from './messages'
+export * from './origin'
+export * from './save-client'
+export * from './service'

package/src/sim-bridge/launch.ts

@@ -0,0 +1,227 @@
+import { boundedString, isoInstant, ownDataValue, strictRecord } from './record'
+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 const SIM_LAUNCH_SCHEMA_VERSION = 1
+/** A launch code is useless after this long, whatever the backend says. */
+export const MAX_SIM_LAUNCH_TTL_MS = 120_000
+
+export const SIM_SURFACES = ['hq', 'character-designer', 'room-designer'] as const
+export type SimSurface = (typeof SIM_SURFACES)[number]
+export const SIM_PLATFORMS = ['desktop', 'web'] as const
+export type SimPlatform = (typeof SIM_PLATFORMS)[number]
+
+const BRIDGE_ID = /^[A-Za-z0-9_-]{16,64}$/
+const LAUNCH_CODE = /^[A-Za-z0-9_-]{32,128}$/
+const WORKSPACE_ID = /^[A-Za-z0-9_.:-]{1,128}$/
+
+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' }>
+
+const DENIED_REASONS = ['unauthenticated', 'not_entitled'] as const
+const UNAVAILABLE_REASONS = ['not_configured', 'service_unavailable'] as const
+const REJECTED_REASONS = ['code_expired', 'code_used', 'not_entitled', 'origin_refused'] as const
+
+export function parseSimLaunchRequest(value: unknown): SimLaunchRequest | null {
+  const body = strictRecord(value, [
+    'schemaVersion',
+    'workspaceId',
+    'surface',
+    'platform',
+    'bridgeId',
+  ])
+  if (!body || body.schemaVersion !== SIM_LAUNCH_SCHEMA_VERSION) return null
+  const workspaceId = boundedString(body.workspaceId, WORKSPACE_ID)
+  const bridgeId = boundedString(body.bridgeId, BRIDGE_ID)
+  const surface = SIM_SURFACES.find((item) => item === body.surface)
+  const platform = SIM_PLATFORMS.find((item) => item === body.platform)
+  if (!workspaceId || !bridgeId || !surface || !platform) return null
+  return { schemaVersion: SIM_LAUNCH_SCHEMA_VERSION, workspaceId, surface, platform, bridgeId }
+}
+
+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 function parseSimLaunchGrant(
+  value: unknown,
+  expected: SimGrantExpectation
+): SimLaunchGrant | null {
+  const status = ownDataValue(value, 'status')
+  if (status === 'denied') {
+    const body = strictRecord(value, ['status', 'reason'])
+    const reason = DENIED_REASONS.find((item) => item === body?.reason)
+    return reason ? { status, reason } : null
+  }
+  if (status === 'unavailable') {
+    const body = strictRecord(value, ['status', 'reason'])
+    const reason = UNAVAILABLE_REASONS.find((item) => item === body?.reason)
+    return reason ? { status, reason } : null
+  }
+  if (status !== 'granted') return null
+  const body = strictRecord(value, ['status', 'code', 'expiresAt', 'surface', 'frameOrigin'])
+  const code = boundedString(body?.code, LAUNCH_CODE)
+  const expiresAt = isoInstant(body?.expiresAt)
+  const surface = SIM_SURFACES.find((item) => item === body?.surface)
+  const frameOrigin = body?.frameOrigin
+  if (!body || !code || expiresAt === null || surface !== expected.surface) return null
+  if (!expected.origins.has(frameOrigin) || typeof frameOrigin !== 'string') return null
+  if (expiresAt <= expected.now || expiresAt > expected.now + MAX_SIM_LAUNCH_TTL_MS) return null
+  return { status, code, expiresAt: body.expiresAt as string, surface, frameOrigin }
+}
+
+export function parseSimSessionExchangeRequest(value: unknown): SimSessionExchangeRequest | null {
+  const body = strictRecord(value, ['schemaVersion', 'code', 'bridgeId'])
+  if (!body || body.schemaVersion !== SIM_LAUNCH_SCHEMA_VERSION) return null
+  const code = boundedString(body.code, LAUNCH_CODE)
+  const bridgeId = boundedString(body.bridgeId, BRIDGE_ID)
+  return code && bridgeId ? { schemaVersion: SIM_LAUNCH_SCHEMA_VERSION, code, bridgeId } : null
+}
+
+/** The sim origin's exchange reply. A session reply carries its expiry and nothing else. */
+export function parseSimSessionExchangeResult(value: unknown): SimSessionExchangeResult | null {
+  const status = ownDataValue(value, 'status')
+  if (status === 'unavailable') return strictRecord(value, ['status']) ? { status } : null
+  if (status === 'rejected') {
+    const body = strictRecord(value, ['status', 'reason'])
+    const reason = REJECTED_REASONS.find((item) => item === body?.reason)
+    return reason ? { status, reason } : null
+  }
+  if (status !== 'session') return null
+  const body = strictRecord(value, ['status', 'expiresAt'])
+  return body && isoInstant(body.expiresAt) !== null
+    ? { status, expiresAt: body.expiresAt as string }
+    : 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 function createLaunchOnce(): Readonly<{
+  take(payload: SimLaunchPayload, now: number): SimLaunchPayload | null
+}> {
+  let taken = false
+  return {
+    take(payload, now) {
+      if (taken) return null
+      const expiresAt = isoInstant(payload.expiresAt)
+      if (expiresAt === null || expiresAt <= now) return null
+      taken = true
+      return payload
+    },
+  }
+}
+
+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 function createLaunchCodeLedger(): Readonly<{
+  issue(code: string, binding: LaunchCodeBinding, expiresAt: number): void
+  redeem(
+    code: string,
+    presented: Omit<LaunchCodeBinding, 'surface'>,
+    now: number
+  ): LaunchCodeRedemption
+}> {
+  const entries = new Map<
+    string,
+    { binding: LaunchCodeBinding; expiresAt: number; spent: boolean }
+  >()
+  return {
+    issue(code, binding, expiresAt) {
+      if (!Number.isFinite(expiresAt)) throw new RangeError('launch code expiry must be finite')
+      entries.set(code, { binding, expiresAt, spent: false })
+    },
+    redeem(code, presented, now) {
+      // An unusable clock reading cannot prove the code is still live, so it fails closed. Nothing
+      // is spent: the comparison below would otherwise be false for NaN and let an expired code pass.
+      if (!Number.isFinite(now)) return { ok: false, reason: 'code_expired' }
+      const entry = entries.get(code)
+      if (!entry) return { ok: false, reason: 'unknown' }
+      if (entry.spent) return { ok: false, reason: 'code_used' }
+      entry.spent = true
+      if (entry.expiresAt <= now) return { ok: false, reason: 'code_expired' }
+      if (
+        entry.binding.bridgeId !== presented.bridgeId ||
+        entry.binding.origin !== presented.origin
+      )
+        return { ok: false, reason: 'origin_refused' }
+      return { ok: true, surface: entry.binding.surface }
+    },
+  }
+}