@volter/twin-openrouter 0.1.0

package/src/openrouter-conformance.ts

@@ -0,0 +1,60 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { handleOpenRouterTwinRequest } from './openrouter-twin.ts';
+import type { SseEvent } from './openrouter-types.ts';
+
+export type OpenRouterConformanceReport = {
+  ok: boolean;
+  checksRun: number;
+  violations: Array<{ check: string; detail: string }>;
+};
+
+type Body = Record<string, any>;
+
+export async function checkOpenRouterConformance(opts: { root?: string } = {}): Promise<OpenRouterConformanceReport> {
+  const root = opts.root ?? mkdtempSync(join(tmpdir(), 'openrouter-conf-'));
+  const owned = opts.root === undefined;
+  const violations: Array<{ check: string; detail: string }> = [];
+  let checksRun = 0;
+  const fail = (check: string, detail: string) => violations.push({ check, detail });
+  const h = (method: string, path: string, body?: unknown, sseSink?: (event: SseEvent) => void) =>
+    handleOpenRouterTwinRequest({ method, path, body: body === undefined ? undefined : JSON.stringify(body), root, ...(sseSink ? { sseSink } : {}) });
+
+  try {
+    checksRun++;
+    const chat = await h('POST', '/api/v1/chat/completions', { model: 'openai/gpt-4o', messages: [{ role: 'user', content: 'hello' }] });
+    const cb = chat.body as Body;
+    if (chat.status !== 200 || cb.object !== 'chat.completion' || cb.choices?.[0]?.message?.role !== 'assistant') fail('chat.envelope', 'invalid chat completion envelope');
+    if (typeof cb.usage?.cost !== 'number') fail('chat.usage', 'OpenRouter usage cost missing');
+
+    checksRun++;
+    const events: SseEvent[] = [];
+    await h('POST', '/api/v1/chat/completions', { model: 'openai/gpt-4o', stream: true, messages: [{ role: 'user', content: 'stream' }] }, (event) => events.push(event));
+    if (!events.some((event) => event.data?.object === 'chat.completion.chunk') || events.at(-1)?.done !== true) fail('streaming', 'missing chunk or [DONE]');
+
+    checksRun++;
+    const models = await h('GET', '/api/v1/models');
+    if (!Array.isArray((models.body as Body).data) || (models.body as Body).data.length === 0) fail('models.list', 'missing models data');
+    const one = await h('GET', '/api/v1/models/openai/gpt-4o');
+    if ((one.body as Body).data?.id !== 'openai/gpt-4o') fail('models.retrieve', 'missing model');
+
+    checksRun++;
+    const gen = await h('GET', `/api/v1/generation?id=${encodeURIComponent(cb.id)}`);
+    if ((gen.body as Body).data?.model !== 'openai/gpt-4o') fail('generation.stats', 'generation lookup failed');
+
+    checksRun++;
+    const bad = await h('POST', '/api/v1/chat/completions', { model: 'openai/gpt-4o', messages: [] });
+    if (bad.status !== 400 || !(bad.body as Body).error) fail('error.envelope', 'bad chat request did not return error envelope');
+
+    checksRun++;
+    const resp = await h('POST', '/api/v1/responses', { model: 'openai/gpt-4o', input: 'hi' });
+    if (resp.status !== 200 || (resp.body as Body).object !== 'response') fail('responses.create', 'responses envelope invalid');
+    const embed = await h('POST', '/api/v1/embeddings', { model: 'm', input: 'hi' });
+    if (embed.status !== 200 || !Array.isArray((embed.body as Body).data?.[0]?.embedding)) fail('embeddings.create', 'embeddings envelope invalid');
+  } finally {
+    if (owned) rmSync(root, { recursive: true, force: true });
+  }
+
+  return { ok: violations.length === 0, checksRun, violations };
+}

package/src/openrouter-connector.ts

@@ -0,0 +1,264 @@
+// OpenRouter CONNECTOR — pull/push against an INJECTED `OpenRouterExecute`, so every test and every
+// capability verify runs offline against a deterministic fake.
+//
+// `liveOpenRouterExecute` below is the pack's ONE construction site for a real, network-calling
+// execute — the choke point the rate budget sits inside. Before it existed there was nowhere for a
+// guard to live: the pack only ever received an execute, so a budget could only be something the
+// caller remembered to opt into, and "the caller remembered" is exactly the assumption that cost a
+// ~4.5-day Figma token lockout (2026-07-25). See `openrouter-budget.ts` for the numbers, and for the
+// honest statement that none of OpenRouter's published figures governs this connector exactly.
+//
+// The injected contract is UNCHANGED: everything below still takes a plain `OpenRouterExecute`.
+import { confirmAction, deployableEntries, observeResources } from '@volter/world-core';
+import type { PerformContext, PushOutcome, RemoteExecute, SyncResource, TwinAction } from '@volter/world-core';
+import type { GenerationStat } from './openrouter-types.ts';
+import { OpenRouterBudget, OpenRouterBudgetError, openRouterCallWeight, type OpenRouterBudgetOptions } from './openrouter-budget.ts';
+
+export type OpenRouterExecute = (req: { method: string; path: string; body?: unknown }) => Promise<{ status: number; data: unknown }>;
+const DEFAULT_OCCURRED_AT = '1970-01-01T00:00:00.000Z';
+
+/** The real OpenRouter API host. The ONLY place this pack names it as a target. */
+export const OPENROUTER_API_BASE = 'https://openrouter.ai';
+
+/**
+ * THE CHOKE POINT — the one place this pack builds an `OpenRouterExecute` that really reaches
+ * openrouter.ai, and therefore the one place the rate budget has to be enforced.
+ *
+ * Reads the API key from `OPENROUTER_API_KEY` (never a literal, never a credentials file) and sends it
+ * as `Authorization: Bearer …`, which is how OpenRouter authenticates its OpenAI-compatible surface.
+ *
+ * EVERY request is guarded: the budget is charged BEFORE it goes out (`checkBudget`, which THROWS
+ * instead of returning once the ceiling or a persisted cooldown says stop) and the response is fed
+ * back (`recordCall`) so a `Retry-After` / 429 / rate-limit-exhaustion signal becomes a persisted
+ * cooldown that makes every later call fail fast WITHOUT touching OpenRouter. There is deliberately
+ * NO option to disable the guard.
+ *
+ * No vendor SDK is imported: real-transport `fetch` keeps this pack SDK-free at runtime, which the
+ * architecture guardrail requires.
+ */
+export function liveOpenRouterExecute(
+  opts: {
+    apiKey?: string;
+    baseUrl?: string;
+    fetchImpl?: typeof fetch;
+    /** An existing budget to share across executes. Omit and one is constructed. Cannot be null. */
+    budget?: OpenRouterBudget;
+    /** Construction options for the default budget (ledger path, clock). Cannot loosen it. */
+    budgetOptions?: OpenRouterBudgetOptions;
+  } = {},
+): OpenRouterExecute {
+  const apiKey = opts.apiKey ?? process.env.OPENROUTER_API_KEY ?? '';
+  if (!apiKey) throw new Error('OPENROUTER_API_KEY is not set — the live OpenRouter client needs an API key');
+  const baseUrl = opts.baseUrl ?? OPENROUTER_API_BASE;
+  const doFetch = opts.fetchImpl ?? fetch;
+  // There is no value a caller can pass to end up with an unguarded execute. `null`/`undefined` (or
+  // omitting it) build the default budget; anything that is not a REAL `OpenRouterBudget` is refused
+  // loudly rather than trusted — a duck-typed stand-in with a no-op `checkBudget` would otherwise be
+  // the one clean way around the guard.
+  if (opts.budget !== undefined && opts.budget !== null && !(opts.budget instanceof OpenRouterBudget)) {
+    throw new Error('liveOpenRouterExecute: `budget` must be an OpenRouterBudget — refusing to build a live OpenRouter client around an unverified rate guard');
+  }
+  // The default ledger is keyed by a hash of THIS key — OpenRouter's limits are per key / per
+  // account, so a cwd-scoped ledger would hand the same key a fresh allowance per checkout/CI leg.
+  const budget = opts.budget instanceof OpenRouterBudget
+    ? opts.budget
+    : new OpenRouterBudget({ token: apiKey, ...(opts.budgetOptions ?? {}) });
+  return async (req) => {
+    requireVendorPath(req.path);
+    const method = (req.method || 'GET').toUpperCase();
+    const weight = openRouterCallWeight(method, req.path);
+    // THROWS instead of calling. Nothing below this line runs when the budget refuses.
+    const reservation = budget.checkBudget(weight);
+    const res = await doFetch(new URL(req.path, baseUrl).toString(), {
+      method,
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        Accept: 'application/json',
+        ...(req.body === undefined ? {} : { 'Content-Type': 'application/json' }),
+      },
+      ...(req.body === undefined ? {} : { body: JSON.stringify(req.body) }),
+    });
+    const headers = lowerCasedHeaders(res.headers);
+    const text = await res.text();
+    let data: unknown = null;
+    try { data = text ? JSON.parse(text) : null; } catch { data = { raw: text }; }
+    // Settles the reservation and, on a back-off signal, arms the cooldown. May itself throw (a
+    // Retry-After beyond the cap is not something to sleep off) — the cooldown is persisted first
+    // either way, so the refusal survives the throw.
+    // recordCall may THROW after arming the cooldown (a back-off beyond the cap). On a refused
+    // call that louder refusal wins; an answer OpenRouter ACCEPTED is kept, so a write that landed is
+    // never recorded as failed and performed again on retry.
+    try {
+      budget.recordCall(weight, headers, { status: res.status, reservation });
+    } catch (error) {
+      if (!(error instanceof OpenRouterBudgetError) || !res.ok) throw error;
+    }
+    return { status: res.status, data };
+  };
+}
+
+/**
+ * Refuse a `path` that is not a same-origin ABSOLUTE PATH.
+ *
+ * `new URL(path, base)` treats `https://evil.test/x` AND the protocol-relative `//evil.test/x` as
+ * absolute and silently retargets the host — and this factory attaches the credential
+ * unconditionally, so a caller-supplied absolute path would exfiltrate it to an arbitrary server.
+ * Figma's guarded client sidesteps this by concatenating rather than resolving; this execute takes an
+ * arbitrary `{ path }` from its caller, so it validates instead. (§9 finding, 2026-07-26.)
+ *
+ * `/twin/...` is refused for a different reason: those are the twin's OWN seed routes
+ * (`*RequestForAction` builds them), which the real vendor has never heard of. Sending one live is a
+ * guaranteed 404 that still burns budget and puts the live credential on the wire for nothing.
+ */
+function requireVendorPath(path: string): void {
+  if (typeof path !== 'string' || !/^\/(?!\/)/.test(path)) {
+    throw new Error(`liveOpenRouterExecute: path must be a same-origin absolute path beginning with a single "/" (got ${String(path)}) — refusing to let a caller-supplied absolute URL retarget the host with the credential attached`);
+  }
+  if (path === '/twin' || path.startsWith('/twin/')) {
+    throw new Error(`liveOpenRouterExecute: refusing to send the twin-only path ${path} to real OpenRouter — that route exists only in the local twin`);
+  }
+}
+
+/** Response headers as a plain lower-cased record — what the kernel's back-off reader expects. */
+function lowerCasedHeaders(h: Headers): Record<string, string> {
+  const out: Record<string, string> = {};
+  h.forEach((v: string, k: string) => { out[k.toLowerCase()] = v; });
+  return out;
+}
+
+/** Fetch OpenRouter's model catalog and provisioning keys through the injected client, mapped to SyncResource[] (no fold). */
+async function collectOpenRouterState(execute: OpenRouterExecute): Promise<SyncResource[]> {
+  const resources: SyncResource[] = [];
+
+  const models = await execute({ method: 'GET', path: '/api/v1/models' });
+  const catalog = (models.data as { data?: Array<Record<string, unknown>> }).data ?? [];
+  for (const model of catalog) {
+    if (typeof model.id === 'string') resources.push({ type: 'model', id: `model_${model.id}`, fields: model });
+  }
+
+  // The PROVISIONING keys (`GET /api/v1/keys`) — the one part of an OpenRouter account a world both
+  // WRITES and can read back, so it is the pull that makes the mirror a mirror rather than a
+  // catalog copy. The vendor addresses a key by its `hash` and never returns the prefixed form, so
+  // the subject id is rebuilt exactly as `createApiKey` mints it.
+  const keys = await execute({ method: 'GET', path: '/api/v1/keys' });
+  for (const key of (keys.data as { data?: Array<Record<string, unknown>> }).data ?? []) {
+    const hash = typeof key.hash === 'string' ? key.hash : typeof key.id === 'string' ? key.id : null;
+    if (!hash) continue;
+    resources.push({ type: 'api_key', id: `key_${hash}`, fields: { ...key, id: `key_${hash}`, hash } });
+  }
+
+  return resources;
+}
+
+export async function pullOpenRouterState(execute: OpenRouterExecute, opts: { root?: string; occurredAt?: string } = {}): Promise<void> {
+  const resources = await collectOpenRouterState(execute);
+  const at = opts.occurredAt ?? DEFAULT_OCCURRED_AT;
+  observeResources('openrouter', resources, { ...(opts.root !== undefined ? { root: opts.root } : {}), at, batch: `obs:openrouter:${at}` });
+}
+
+/**
+ * D7 consumer-facing pull entry point: gather all OpenRouter domains (the model catalog and the account's provisioning keys) and
+ * fold them into the twin as ONE observation, returning the standard result shape. Idempotent:
+ * a re-pull of identical state appends no new deltas.
+ */
+export async function syncOpenRouterFromReal(
+  execute: OpenRouterExecute,
+  opts: { root?: string; occurredAt?: string } = {},
+): Promise<{ observed: number; deltasAppended: number }> {
+  const resources = await collectOpenRouterState(execute);
+  const at = opts.occurredAt ?? DEFAULT_OCCURRED_AT;
+  const result = observeResources('openrouter', resources, { ...(opts.root !== undefined ? { root: opts.root } : {}), at, batch: `obs:openrouter:${at}` });
+  return { observed: resources.length, deltasAppended: result.appended };
+}
+
+export function openRouterRequestForAction(action: TwinAction): { method: string; path: string; body?: unknown } | null {
+  if (action.operation === 'generation.record') {
+    const stat = action.fields as unknown as GenerationStat;
+    return { method: 'GET', path: `/api/v1/generation?id=${encodeURIComponent(stat.id.replace(/^generation_/, ''))}` };
+  }
+  return null;
+}
+
+export async function pushOpenRouterAction(action: TwinAction, execute: OpenRouterExecute, opts: { root?: string; occurredAt?: string } = {}): Promise<boolean> {
+  const req = openRouterRequestForAction(action);
+  if (!req) return false;
+  const result = await execute(req);
+  if (result.status < 200 || result.status >= 300) return false;
+  // The vendor's OWN id for the subject, and the receipt that says the crossing happened — protocol
+  // 2's confirmation carries both, so a later read can tell a deployed subject from a local one.
+  const answered = (result.data as { data?: Record<string, unknown> } | undefined)?.data;
+  const vendorSubjectId = typeof answered?.id === 'string' ? answered.id : action.subject.id;
+  confirmAction({
+    service: 'openrouter',
+    actionId: action.id,
+    subject: action.subject,
+    fields: action.fields ?? {},
+    occurredAt: opts.occurredAt ?? DEFAULT_OCCURRED_AT,
+    vendorSubjectId,
+    receipt: { status: 'deployed' },
+    ...(opts.root !== undefined ? { root: opts.root } : {}),
+  });
+  return true;
+}
+
+export async function pushPendingOpenRouterActions(execute: OpenRouterExecute, opts: { root?: string; occurredAt?: string } = {}): Promise<number> {
+  let pushed = 0;
+  for (const action of deployableEntries('openrouter', opts.root)) {
+    if (await pushOpenRouterAction(action, execute, opts)) pushed++;
+  }
+  return pushed;
+}
+
+// ── PROTOCOL 2: the pack's half of the real state system ────────────────────────────────────
+
+/**
+ * An `OpenRouterExecute` over the kernel's executor. At a REAL boundary the kernel sets the sealed
+ * credential over these headers (executor.ts); at the twin's own wire any credential is one.
+ *
+ * The paths carry OpenRouter's `/api` prefix, which `collectOpenRouterState` already uses and the
+ * twin's own router accepts alongside the bare `/v1` form.
+ */
+export function openRouterExecuteOver(execute: RemoteExecute): OpenRouterExecute {
+  return async (req) => {
+    const res = await execute({
+      method: req.method,
+      path: req.path,
+      headers: { accept: 'application/json', 'content-type': 'application/json', authorization: 'Bearer twin' },
+      ...(req.body === undefined ? {} : { body: JSON.stringify(req.body) }),
+    });
+    let data: unknown = {};
+    try { data = JSON.parse(res.body || '{}'); } catch { data = {}; }
+    return { status: res.status, data };
+  };
+}
+
+/** The refresh adapter: pull the account's state through the executor and fold it into the root. */
+export async function syncOpenRouterFromRemote(
+  execute: RemoteExecute,
+  opts: { root?: string; origin?: string; occurredAt?: string } = {},
+): Promise<{ observed: number; deltasAppended: number }> {
+  return syncOpenRouterFromReal(openRouterExecuteOver(execute), {
+    ...(opts.root !== undefined ? { root: opts.root } : {}),
+    occurredAt: opts.occurredAt ?? new Date().toISOString(),
+  });
+}
+
+/**
+ * The perform adapter. OpenRouter's provisioning surface is what a world can really write:
+ * `pushOpenRouterAction` maps the one crossing operation it models and answers `false` for the
+ * rest, which are the twin's OWN record (a generation is a completion this twin produced; there is
+ * nothing at OpenRouter to create). Saying so is the honest outcome, never a silent success.
+ */
+export async function performOpenRouterAction(execute: RemoteExecute, action: TwinAction, _ctx: PerformContext): Promise<PushOutcome> {
+  const client = openRouterExecuteOver(execute);
+  const req = openRouterRequestForAction(action);
+  if (!req) {
+    const op = action.operation ?? `${action.subject.type}.update`;
+    return { externalId: action.subject.id, data: { performed: false, reason: `${op} is the twin's own record — nothing at OpenRouter to write` } };
+  }
+  const result = await client(req);
+  if (result.status < 200 || result.status >= 300) {
+    throw new Error(`openrouter ${req.method} ${req.path} refused: HTTP ${result.status}`);
+  }
+  return { externalId: action.subject.id, data: (result.data ?? {}) as Record<string, unknown> };
+}

package/src/openrouter-local-generation.ts

@@ -0,0 +1,207 @@
+/** Optional pack-owned transport to a separately World-owned loopback generation service. */
+
+export const LOCAL_GENERATION_BODY_LIMIT = 8 * 1024 * 1024;
+export type LocalGenerationFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+
+export function localGenerationOrigin(value: string): string {
+  const match = /^http:\/\/127\.0\.0\.1:([1-9][0-9]{0,4})\/?$/.exec(value);
+  const port = match ? Number(match[1]) : 0;
+  if (!port || port > 65535) {
+    throw new Error('local_generation_url_invalid: expected http://127.0.0.1:<nonzero-port> with no credentials, path, query, or fragment');
+  }
+  return `http://127.0.0.1:${port}`;
+}
+
+/** Read only the opt-in generation request body; ordinary twin routes retain their old path. */
+export async function readLocalGenerationBody(request: Request): Promise<{ bytes: Uint8Array<ArrayBuffer>; text: string }> {
+  request.signal.throwIfAborted();
+  const reader = request.body?.getReader();
+  if (!reader) return { bytes: new Uint8Array(0), text: '' };
+  const parts: Uint8Array[] = [];
+  let length = 0;
+  let readFailed = false;
+  let done = false;
+  let primary: unknown;
+  let failed = false;
+  let cleanupFailure: unknown;
+  let cleanupFailed = false;
+  let result: { bytes: Uint8Array<ArrayBuffer>; text: string } | undefined;
+  let abortCleanup: Promise<void> | undefined;
+  const onAbort = () => {
+    abortCleanup ??= reader.cancel(request.signal.reason);
+    // The request's finally block observes the same promise even if cancellation rejects first.
+    void abortCleanup.catch(() => {});
+  };
+  request.signal.addEventListener('abort', onAbort, { once: true });
+  if (request.signal.aborted) onAbort();
+  try {
+    while (true) {
+      request.signal.throwIfAborted();
+      let part;
+      try { part = await reader.read(); }
+      catch (error) { readFailed = true; throw error; }
+      request.signal.throwIfAborted();
+      if (part.done) { done = true; break; }
+      length += part.value.byteLength;
+      if (length > LOCAL_GENERATION_BODY_LIMIT) throw new Error('local_generation_body_too_large: 8 MiB limit');
+      parts.push(part.value);
+    }
+    const bytes = new Uint8Array(length);
+    let offset = 0;
+    for (const part of parts) { bytes.set(part, offset); offset += part.byteLength; }
+    try { result = { bytes, text: new TextDecoder('utf-8', { fatal: true }).decode(bytes) }; }
+    catch (error) { throw new Error('local_generation_invalid_utf8: request body is not valid UTF-8', { cause: error }); }
+  } catch (error) {
+    primary = error;
+    failed = true;
+  } finally {
+    request.signal.removeEventListener('abort', onAbort);
+    if (!done && (!readFailed || abortCleanup)) {
+      try { await (abortCleanup ?? reader.cancel(primary)); }
+      catch (cleanup) { cleanupFailure = cleanup; cleanupFailed = true; }
+    }
+    try { reader.releaseLock(); }
+    catch (cleanup) {
+      cleanupFailure = cleanupFailed ? new AggregateError([cleanupFailure, cleanup], 'local_generation_body_cleanup_failed') : cleanup;
+      cleanupFailed = true;
+    }
+  }
+  if (cleanupFailed) throw new AggregateError(failed ? [primary, cleanupFailure] : [cleanupFailure], 'local_generation_body_cleanup_failed');
+  if (failed) throw primary;
+  if (!result) throw new Error('local_generation_body_read_failed: no completed body');
+  return result;
+}
+
+function localError(status: number, code: string, message: string): Response {
+  return Response.json({ error: { message, type: 'local_generation_error', code } }, { status });
+}
+
+/** One pull from the caller means at most one read from the local response. */
+export async function forwardLocalGeneration(args: {
+  origin: string;
+  request: Request;
+  pathname: string;
+  body: Uint8Array<ArrayBuffer>;
+  fetchImpl?: LocalGenerationFetch;
+}): Promise<Response> {
+  const relay = new AbortController();
+  const abort = () => relay.abort(args.request.signal.reason);
+  args.request.signal.addEventListener('abort', abort, { once: true });
+  if (args.request.signal.aborted) abort();
+  const headers = new Headers();
+  for (const key of ['content-type', 'accept']) {
+    const value = args.request.headers.get(key);
+    if (value !== null) headers.set(key, value);
+  }
+  let upstream: Response;
+  try {
+    upstream = await (args.fetchImpl ?? fetch)(`${args.origin}${args.pathname}`, {
+      method: 'POST', headers, body: args.body, redirect: 'manual', signal: relay.signal,
+    });
+  } catch (error) {
+    args.request.signal.removeEventListener('abort', abort);
+    if (args.request.signal.aborted) throw error;
+    return localError(503, 'local_generation_unavailable', `Local generation service unavailable: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (upstream.status >= 300 && upstream.status < 400) {
+    try { await upstream.body?.cancel(); }
+    catch (error) {
+      args.request.signal.removeEventListener('abort', abort);
+      return localError(502, 'local_generation_cleanup_failed', `Local generation redirect body cleanup failed: ${String(error)}`);
+    }
+    args.request.signal.removeEventListener('abort', abort);
+    return localError(502, 'local_generation_redirect_refused', 'Local generation service redirect refused');
+  }
+  if (args.request.signal.aborted) {
+    args.request.signal.removeEventListener('abort', abort);
+    try { await upstream.body?.cancel(args.request.signal.reason); }
+    catch (cleanup) { throw new AggregateError([args.request.signal.reason, cleanup], 'local_generation_cleanup_failed'); }
+    throw args.request.signal.reason;
+  }
+  const responseHeaders = new Headers();
+  for (const key of ['content-type', 'retry-after', 'retry-after-ms']) {
+    const value = upstream.headers.get(key);
+    if (value !== null) responseHeaders.set(key, value);
+  }
+  if (!upstream.body) {
+    args.request.signal.removeEventListener('abort', abort);
+    return new Response(null, { status: upstream.status, headers: responseHeaders });
+  }
+  const reader = upstream.body.getReader();
+  let terminal = false;
+  let cancelPromise: Promise<void> | undefined;
+  let failure: unknown;
+  let abortCleanup: Promise<void> | undefined;
+  let streamController: ReadableStreamDefaultController<Uint8Array> | undefined;
+  let readerTerminal: 'pending' | 'closed' | 'errored' = 'pending';
+  void reader.closed.then(() => { readerTerminal = 'closed'; }, () => { readerTerminal = 'errored'; });
+  const cancelReader = (reason?: unknown): Promise<void> => {
+    if (cancelPromise) return cancelPromise;
+    cancelPromise = (async () => {
+      let primary: unknown;
+      let failed = false;
+      await Promise.resolve();
+      if (readerTerminal === 'pending') {
+        try { await reader.cancel(reason); } catch (error) { primary = error; failed = true; }
+      }
+      try { reader.releaseLock(); }
+      catch (cleanup) {
+        primary = failed ? new AggregateError([primary, cleanup], 'local_generation_cleanup_failed') : cleanup;
+        failed = true;
+      }
+      if (failed) throw primary;
+    })();
+    return cancelPromise;
+  };
+  const finish = () => {
+    if (terminal) return;
+    terminal = true;
+    args.request.signal.removeEventListener('abort', onAbort);
+  };
+  const onAbort = () => {
+    relay.abort(args.request.signal.reason);
+    failure = args.request.signal.reason;
+    abortCleanup = cancelReader(failure);
+    void abortCleanup.then(
+      () => { finish(); try { streamController?.error(failure); } catch { /* an active pull already reported the abort */ } },
+      (cleanup) => {
+        failure = new AggregateError([failure, cleanup], 'local_generation_cleanup_failed');
+        finish();
+        try { streamController?.error(failure); } catch { /* an active pull already reported the failure */ }
+      },
+    );
+  };
+  args.request.signal.removeEventListener('abort', abort);
+  args.request.signal.addEventListener('abort', onAbort, { once: true });
+  if (args.request.signal.aborted) onAbort();
+  const body = new ReadableStream<Uint8Array>({
+    start(controller) {
+      streamController = controller;
+      if (failure !== undefined && !abortCleanup) controller.error(failure);
+    },
+    async pull(controller) {
+      if (failure !== undefined) {
+        if (abortCleanup) await abortCleanup.then(() => {}, () => {});
+        finish();
+        try { controller.error(failure); } catch { /* abort callback already reported it */ }
+        return;
+      }
+      try {
+        const part = await reader.read();
+        if (abortCleanup) { await abortCleanup.then(() => {}, () => {}); throw failure; }
+        if (part.done) { finish(); reader.releaseLock(); controller.close(); }
+        else controller.enqueue(part.value);
+      } catch (error) {
+        finish();
+        try { reader.releaseLock(); } catch { /* read/cancel race; retain original stream error */ }
+        try { controller.error(failure ?? error); } catch { /* already errored by abort callback */ }
+      }
+    },
+    async cancel(reason) {
+      finish();
+      relay.abort(reason);
+      await cancelReader(reason);
+    },
+  }, { highWaterMark: 0 });
+  return new Response(body, { status: upstream.status, headers: responseHeaders });
+}

package/src/openrouter-mirror-ui.ts

@@ -0,0 +1,84 @@
+// OpenRouter MIRROR UI — a models/playground/generations console served as a React/TSX app
+// (bundled by Bun).
+//
+// PURE FRONTEND (R3): the mirror imports no handler module and no twin internals — it MOUNTS the
+// pack's OWN fetch adapter (`createOpenRouterTwinFetch`) as its API backend and reads every byte of
+// state back over the wire. The client fetches OPENROUTER'S REAL VENDOR PATHS (`/api/v1/models`,
+// `/api/v1/chat/completions`, `/api/v1/generations`, `/api/v1/generation?id=…`) on the same origin,
+// so there is exactly ONE serving code path and API<->UI parity cannot drift: the screen shows real
+// twin state or nothing. Mounting the adapter also hands the mirror the streaming lane, the world
+// clock and an honorable `readOnly` for free — the hand-rolled dispatch this replaced used
+// `new Date()` and ignored `readOnly` (the airtable §9 round-two finding 13 drift, verbatim).
+import { readFile } from 'node:fs/promises';
+import { bundleClient, fileResponse } from '@volter/world-core';
+import { serveHttp } from '@volter/world-core';
+import { createOpenRouterTwinFetch } from './openrouter-server.ts';
+
+const CLIENT_ENTRY = () => new URL('../client/openrouter-mirror.tsx', import.meta.url).pathname;  // lazy: workerd rejects top-level relative URL from import.meta.url (bundled via pack index)
+const CLIENT_CSS = () => new URL('../client/openrouter-mirror.css', import.meta.url).pathname;  // lazy: workerd rejects top-level relative URL from import.meta.url (bundled via pack index)
+
+const APP_SHELL = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<base href="/"><title>OpenRouter (twin)</title><link rel="stylesheet" href="assets/styles.css"></head>
+<body><div id="root"></div><script type="module" src="assets/app.js"></script></body></html>`;
+
+let clientBundle: Promise<string> | null = null;
+
+export function buildOpenRouterMirrorClient(): Promise<string> {
+  if (!clientBundle) {
+    clientBundle = bundleClient(CLIENT_ENTRY())
+      .catch((error) => {
+        clientBundle = null;
+        throw error;
+      });
+  }
+  return clientBundle;
+}
+
+export async function createOpenRouterMirrorServer(options: { root?: string; port?: number; readOnly?: boolean } = {}): Promise<{ port: number; stop: () => void }> {
+  // Built ONCE, above the socket — never per request: the adapter is a closure over the twin's
+  // options and is the very same one `createOpenRouterTwinServer` serves.
+  const twin = createOpenRouterTwinFetch(options);
+  const server = await serveHttp({
+    // LOOPBACK-SPECIFIC bind (2026-08-20, the roving ui-verify flake): with the default
+    // wildcard hostname, `port: 0` can be handed a port some long-running app already LISTENS
+    // on at 127.0.0.1 (SO_REUSEADDR allows the overlapping non-identical bind), and the more
+    // specific loopback listener then shadows this server for every 127.0.0.1 fetch — the
+    // verify talks to a STRANGER (captured: a desktop app's asset server answering 404s on the
+    // mirror's port). Binding 127.0.0.1 makes the kernel allocate a port that is actually free
+    // on loopback, so the verify's fetches deterministically reach THIS server.
+    hostname: '127.0.0.1',
+    port: options.port ?? 0,
+    idleTimeout: 60,
+    async fetch(request) {
+      const url = new URL(request.url);
+      if (request.method === 'GET' && url.pathname === '/assets/app.js') {
+        try {
+          return new Response(await buildOpenRouterMirrorClient(), { headers: { 'content-type': 'text/javascript; charset=utf-8' } });
+        } catch (error) {
+          return new Response(String(error), { status: 500 });
+        }
+      }
+      if (request.method === 'GET' && url.pathname === '/assets/styles.css') {
+        return fileResponse(CLIENT_CSS(), { headers: { 'content-type': 'text/css; charset=utf-8' } });
+      }
+      if (request.method === 'GET' && (url.pathname === '/' || url.pathname === '')) {
+        return new Response(APP_SHELL, { headers: { 'content-type': 'text/html; charset=utf-8' } });
+      }
+      // everything else -> the twin's OWN FETCH ADAPTER (composition, R2/R3). That includes the
+      // uniform `GET /twin` door and the SSE lane; nothing about the mirror port may differ from
+      // the API port.
+      return twin(request);
+    },
+  });
+  return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}
+
+export function openrouterMirrorHtml(): string {
+  return APP_SHELL;
+}
+
+/** The mirror's stylesheet, for a host serving the shell's `assets/styles.css` itself (the hosted mirror mount). */
+export function openrouterMirrorStyles(): Promise<string> {
+  return readFile(CLIENT_CSS(), 'utf8');
+}