@volter/twin-fal 0.1.0

package/src/fal-scenario.ts

@@ -0,0 +1,112 @@
+// The fal pack's HALF of the scenario system, on the kernel's ONE engine (@volter/world-core
+// scenario.ts). The GRAMMAR (ordering, once/scope/phase, extractors, strict parsing, miss
+// records, twin.use) is the kernel's and identical for every vendor; this module declares only
+// the VOCABULARY:
+//   • the `on` keys a handler may match (model id, submitted input text, the queue-vs-sync
+//     surface, and the 1-based ordinal of the submit within the world),
+//   • what a `respond` payload may contain ({ output, inferenceTime? }),
+//   • nothing else — fal's PROTOCOL envelope (the IN_QUEUE → IN_PROGRESS → COMPLETED machine,
+//     queue_position, logs, urls, metrics) stays the twin's, faithful and unscriptable. What a
+//     handler replaces is exactly the GENERATIVE STUB: the `output` a request settles to,
+//     which without a handler is the labeled `[twin-stub:fal:<hash8>]` value.
+//
+// Matching happens at SUBMIT (POST /{model_id}, both the queue and the fal.run sync surface) and
+// the outcome is PERSISTED on the request resource, so completion stays a pure fold of the kernel
+// log — the status progression never consults the engine and holds no hidden session state.
+// `nthRequest` is a PACK matcher over the count of request rows already in the root, not the
+// engine's call counter.
+//
+// The handler FILE (handlers/fal.json in a world dir) is the only write surface.
+import { getActiveWorldStore, parseScenarioDocument, type PackScenarioAdapter, ScenarioError, type ScenarioDocument, ScenarioEngine, type ScenarioFeatures } from '@volter/world-core';
+
+/** The request slice the scenario system sees — built by the submit route from the parsed body. */
+export type FalScenarioRequest = {
+  modelId: string;
+  input: Record<string, unknown>;
+  /** The surface the submit arrived on: fal's queue (queue.fal.run) or the inline fal.run. */
+  surface: 'queue' | 'sync';
+  /** 1-based ordinal of this submit among the request rows in the root. */
+  nthRequest: number;
+};
+export type FalScenarioEngine = ScenarioEngine<FalScenarioRequest>;
+
+/** The scripted outcome: the `output` the request settles to (any JSON value the model would
+ *  return — real fal models answer objects like `{ images: [...] }`, not only strings), and
+ *  optionally the reported inference time. */
+export type FalScenarioRespond = {
+  output: unknown;
+  inferenceTime?: number;
+};
+
+const RESPOND_KEYS = new Set(['output', 'inferenceTime']);
+const nonEmptyString = (cond: unknown): cond is string => typeof cond === 'string' && cond.length > 0;
+
+/** Stable text of a submitted input — the corpus `inputIncludes` and `textPattern` extractors
+ *  read. Key order is sorted so the same input always yields the same corpus. */
+export function canonicalInputText(input: unknown): string {
+  if (input === null || typeof input !== 'object') return JSON.stringify(input) ?? 'null';
+  if (Array.isArray(input)) return `[${input.map(canonicalInputText).join(',')}]`;
+  const keys = Object.keys(input as Record<string, unknown>).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalInputText((input as Record<string, unknown>)[k])}`).join(',')}}`;
+}
+
+export const falScenarioAdapter: PackScenarioAdapter<FalScenarioRequest> = {
+  vendor: 'fal',
+  features: (req): ScenarioFeatures => ({
+    modelId: req.modelId,
+    input: canonicalInputText(req.input).slice(0, 300),
+    surface: req.surface,
+    nthRequest: req.nthRequest,
+  }),
+  matchers: {
+    modelIdEquals: (req, cond) => nonEmptyString(cond) && req.modelId === cond,
+    modelIdIncludes: (req, cond) => nonEmptyString(cond) && req.modelId.toLowerCase().includes(cond.toLowerCase()),
+    inputIncludes: (req, cond) => nonEmptyString(cond) && canonicalInputText(req.input).toLowerCase().includes(cond.toLowerCase()),
+    surfaceEquals: (req, cond) => (cond === 'queue' || cond === 'sync') && req.surface === cond,
+    // The 1-based index among requests submitted into the ROOT, not the engine's call counter —
+    // no hidden session state.
+    nthRequest: (req, cond) => Number.isInteger(cond) && req.nthRequest === cond,
+  },
+  text: (req) => canonicalInputText(req.input),
+  validateOn: (on) => {
+    for (const k of ['modelIdEquals', 'modelIdIncludes', 'inputIncludes'] as const) {
+      if (on[k] !== undefined && (typeof on[k] !== 'string' || !on[k])) return `on.${k} is a non-empty string`;
+    }
+    if (on.surfaceEquals !== undefined && on.surfaceEquals !== 'queue' && on.surfaceEquals !== 'sync') return 'on.surfaceEquals is "queue" or "sync"';
+    if (on.nthRequest !== undefined && (!Number.isInteger(on.nthRequest) || (on.nthRequest as number) < 1)) return 'on.nthRequest is a positive integer';
+    return null;
+  },
+  validateRespond: (respond) => {
+    if (typeof respond !== 'object' || respond === null || Array.isArray(respond)) return 'respond is an object { output, inferenceTime? }';
+    const r = respond as Record<string, unknown>;
+    for (const k of Object.keys(r)) if (!RESPOND_KEYS.has(k)) return `respond: unknown key "${k}" (valid: ${[...RESPOND_KEYS].join(', ')})`;
+    if (!('output' in r)) return 'respond needs output (the value the request settles to — any JSON the model would return)';
+    if (r.output === undefined) return 'respond.output is a JSON value, not undefined';
+    if (r.inferenceTime !== undefined && (typeof r.inferenceTime !== 'number' || !Number.isFinite(r.inferenceTime) || r.inferenceTime < 0)) {
+      return 'respond.inferenceTime is a non-negative number of SECONDS';
+    }
+    return null;
+  },
+};
+
+/** Load + strictly validate a handlers document (handlers/fal.json). A broken file fails server
+ *  construction loudly; it never falls back or misfires silently. */
+export function loadFalScenarioDocument(path: string): ScenarioDocument {
+  let parsed: unknown;
+  try {
+    // Read through the ACTIVE WorldStore, never the filesystem directly (runtime contract R12b):
+    // the handlers document is WORLD STATE, so a MemoryWorldStore / DO-backed world serves ITS
+    // OWN scenario instead of whatever happens to sit on the host disk — and the serve path
+    // stays workerd-clean.
+    const raw = getActiveWorldStore().read(path);
+    if (raw === null) throw new Error(`ENOENT: no such file or directory, open '${path}'`);
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    throw new ScenarioError(`fal scenario: cannot read/parse ${path}: ${e instanceof Error ? e.message : String(e)}`);
+  }
+  return parseScenarioDocument(parsed, falScenarioAdapter);
+}
+
+export function createFalScenarioEngine(document?: ScenarioDocument): FalScenarioEngine {
+  return new ScenarioEngine(falScenarioAdapter, document);
+}

package/src/fal-server.ts

@@ -0,0 +1,64 @@
+// fal twin HTTP server — serve the full fal API twin handler over HTTP so the real
+// `@fal-ai/client` SDK (via a `requestMiddleware` that rewrites the URL to this server — see
+// fal-sdk.integration.test.ts) works unmodified against it. Every route is plain JSON. Request
+// headers are forwarded verbatim — NOTE the server deliberately does NOT thread the incoming
+// HTTP `Host` header as `handleFalTwinRequest`'s `host` param: once a caller's request has been
+// rewritten to point at THIS server (127.0.0.1:<port>), the literal Host header is always
+// 127.0.0.1, which carries no vendor-host information. Host-split routing instead reads the
+// `x-fal-target-url` header (the real fal-js proxy protocol, which carries the ORIGINAL absolute
+// URL) — see fal-twin.ts's `routeFalSurface`. Writable by default; pass readOnly to reject writes
+// with 405 (D3). State is the kernel projection (no side-store) — see fal-twin.ts.
+//
+// FETCH-FIRST (runtime contract R12b): the serve path is the plain fetch below, built from the
+// kernel's ONE adaptation (`createTwinFetchFromHandler` — the keyless read doors, body read,
+// header map, worldNow() stamp, JSON reply); this file contributes only VALUES. The server is one
+// line of Bun.serve around that same closure.
+//
+// THE READ DOORS (runtime contract R5): keyless `GET /twin` (the manifest, which teaches the
+// handler shape) and `GET /twin/scenario` (active handlers + match/miss counts). Both are the
+// adapter's, answered before any vendor routing, and neither takes a credential.
+//
+// SCENARIO scripting (fal-scenario.ts): pass `scenarioPath` (or set the TWIN_FAL_SCENARIO env
+// var) to script what a submitted request settles to. A malformed scenario throws at
+// construction — loudly, never a silent fallback.
+import { serveHttp } from '@volter/world-core';
+import { handleFalTwinRequest } from './fal-twin.ts';
+import { createTwinFetchFromHandler, twinManifest } from '@volter/world-core';
+import { createFalScenarioEngine, loadFalScenarioDocument, type FalScenarioEngine } from './fal-scenario.ts';
+
+/** Options every fal-twin HTTP surface needs, independent of who owns the socket. */
+export interface FalTwinFetchOptions {
+  root?: string;
+  readOnly?: boolean;
+  /** Path to the world dir's handlers/fal.json — read ONCE, at construction, through the active
+   *  WorldStore. Absent → no engine, and every request settles to the labeled stub. */
+  scenarioPath?: string;
+}
+
+export function createFalTwinFetch(options: FalTwinFetchOptions = {}): (request: Request) => Promise<Response> {
+  const scenarioPath = options.scenarioPath ?? process.env.TWIN_FAL_SCENARIO;
+  const scenarioEngine: FalScenarioEngine | undefined = scenarioPath ? createFalScenarioEngine(loadFalScenarioDocument(scenarioPath)) : undefined;
+  const { scenarioPath: _scenarioPath, ...handlerOptions } = options;
+  return createTwinFetchFromHandler(handleFalTwinRequest, {
+    ...handlerOptions,
+    manifest: () => twinManifest({
+      vendor: 'fal',
+      twinOf: 'the fal.ai inference queue',
+      stateSentence: 'Stateful: it stores queued inference requests and their status/log/response lifecycle. Create them through the vendor\'s OWN API (POST /{model_id} on queue.fal.run or fal.run) with any credential.',
+      behaviorSentence: 'The PROTOCOL envelope (IN_QUEUE → IN_PROGRESS → COMPLETED, queue_position, logs, urls, metrics) is the twin\'s and faithful. What a request SETTLES TO is scripted by MSW-shaped handlers in the world dir (handlers/fal.json): {on:{modelIdEquals|modelIdIncludes|inputIncludes|surfaceEquals|nthRequest|nthCall}, respond:{output, inferenceTime?}, once?, phase?}. Matching happens at submit and the outcome persists on the request; unmatched submits settle to the labeled [twin-stub:fal:…] value, and the misses are inspectable at GET /twin/scenario.',
+      exampleHandler: { on: { modelIdIncludes: 'flux' }, respond: { output: { images: [{ url: 'https://cdn.example.com/scripted.png' }] } } },
+      engine: scenarioEngine as never,
+    }),
+    scenarioStatus: () => (scenarioEngine ? scenarioEngine.status() : { vendor: 'fal', handlers: [], misses: 0, recentMisses: [] }),
+    ...(scenarioEngine ? { handlerOptions: { scenarioEngine } } : {}),
+  });
+}
+
+export async function createFalTwinServer(options: { root?: string; port?: number; readOnly?: boolean; scenarioPath?: string } = {}): Promise<{ port: number; stop: () => void }> {
+  const server = await serveHttp({
+    port: options.port ?? 0,
+    idleTimeout: 60,
+    fetch: createFalTwinFetch(options),
+  });
+  return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}

package/src/fal-twin.ts

@@ -0,0 +1,479 @@
+// fal.ai API twin REQUEST HANDLER — a v1 slice of the fal.ai queue-lifecycle model-inference
+// surface, backed by the event/action-log kernel (@volter/world-core). Contract:
+//   handleFalTwinRequest({ method, path, body, host?, headers, root, readOnly }) -> { status, body, headers }
+//
+// SOURCE OF TRUTH: grounded read-only against fal.ai's own published docs (fal.ai/docs/model-
+// endpoints/queue, fal.ai/docs/model-endpoints/webhooks) and the fal-js client source
+// (github.com/fal-ai/fal-js — libs/client/src/{config,middleware,queue,request}.ts), fetched
+// during this build (see spec-sources.json). Every route/field/status below cites one of those
+// two sources; a doc-UNVERIFIED shape is annotated inline (⚠) and NOT claimed beyond what the
+// verify() actually proves.
+//
+// Facts grounded from fal.ai/docs/model-endpoints/queue:
+//   - submit: POST https://queue.fal.run/{model_id} -> {request_id, response_url, status_url,
+//     cancel_url, queue_position}. status: GET .../requests/{request_id}/status[?logs=1] ->
+//     {status: IN_QUEUE|IN_PROGRESS|COMPLETED, request_id, response_url, queue_position
+//     (IN_QUEUE only), logs (IN_PROGRESS/COMPLETED), metrics.inference_time (COMPLETED only)}.
+//   - cancel: PUT .../requests/{request_id}/cancel -> 202 {"status":"CANCELLATION_REQUESTED"} |
+//     400 {"status":"ALREADY_COMPLETED"} | 404 {"status":"NOT_FOUND"} (NOT a {detail} envelope —
+//     this exact shape is doc-grounded, distinct from every other 404 in this pack).
+//   - result: docs literally show GET .../requests/{request_id}/response, but the REAL fal-js
+//     client builds the result URL WITHOUT the /response suffix (verified against the fetched
+//     queue.ts source: `path: /requests/${requestId}`) — a genuine doc/client conflict (⚠2 in the
+//     build spec). This twin serves BOTH forms so either a doc-literal caller or the real SDK
+//     works; the /response form is the doc's own example, still exercised, but not separately
+//     claimed as its own capability (`fal.queue.response_alias_route` stays `todo`).
+// Facts grounded from fal.ai/docs/model-endpoints/webhooks — see fal-webhooks.ts.
+// Facts grounded from fal-js middleware.ts/config.ts/request.ts — see fal-twin.ts's
+// `routeFalSurface` and fal-sdk.integration.test.ts.
+//
+// State lives ENTIRELY in the kernel action log: writes go through `applyTwinWrite`, reads are
+// the projection (`projectResources`). There is NO Map/array side-store (D1). No real fal is
+// ever contacted.
+//
+// THE GENERATIVE STUB (D2 honesty): fal is a GENERATIVE vendor — model inference requires
+// hosted GPU weights that cannot run locally, so a request's `output` is a clearly-labeled
+// DETERMINISTIC stub (`[twin-stub:fal:<hash8>]`), derived from hash(model_id, canonical-
+// JSON(input)) — same input twice -> identical output, different input -> different output. The
+// PROTOCOL ENVELOPE (status machine, queue_position, logs, urls, metrics shape) is faithful; only
+// the generated content is a stub.
+//
+// Honesty (D2): an unmodeled route returns a FastAPI-style `{"detail": "..."}` 404 (fal's
+// gateway is FastAPI-based per its documented 422 validation-error shape), never a fabricated
+// success. readOnly rejects writes with 405.
+//
+// Kernel SUBJECT ids are type-prefixed (`request:<uuid>`) — the PUBLIC request_id emitted to
+// clients is the bare uuid. `kid()` builds the subject id; `rows()` strips the prefix back off.
+import { createHash } from 'node:crypto';
+import { applyTwinWrite, projectResources } from '@volter/world-core';
+import { falJwks } from './fal-webhooks.ts';
+import type { FalScenarioEngine, FalScenarioRespond } from './fal-scenario.ts';
+
+const SERVICE = 'fal';
+
+export type FalRequest = {
+  method: string;
+  path: string;
+  body?: string;
+  /** Explicit host (e.g. from an HTTP `Host` header or a direct routing decision). Takes
+   *  priority over `x-fal-target-url` in `headers`. */
+  host?: string;
+  headers?: Record<string, string>;
+  occurredAt?: string;
+  root?: string;
+  readOnly?: boolean;
+  /** The pack's scenario engine, mounted by the fetch adapter when a world dir carries a
+   *  handlers/fal.json. Absent → every request settles to the labeled deterministic stub,
+   *  unchanged. Consulted at SUBMIT only; the outcome persists on the request resource. */
+  scenarioEngine?: FalScenarioEngine;
+};
+export type FalResponse = { status: number; body: unknown; headers?: Record<string, string> };
+
+// Resource types the twin actually PROJECTS in the kernel — the honest v1 subset. `signing_key`
+// is a lazily-materialized per-root singleton (the same "fold on first touch" pattern replicate's
+// webhook_secret / elevenlabs' dubbing.get use); it's never itself a REST-addressable resource
+// (fal has no admin surface to list/rotate keys — see README ## Coverage), only the ed25519
+// keypair backing the JWKS endpoint + webhook signing.
+export const FAL_RESOURCE_TYPES = ['request', 'signing_key'] as const;
+export type FalResourceType = typeof FAL_RESOURCE_TYPES[number];
+
+function lowerHeaders(h: Record<string, string> | undefined): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(h ?? {})) out[k.toLowerCase()] = v;
+  return out;
+}
+
+// ── host-split surface routing (build spec §1 divergence 2) ──────────────────────────────────
+// fal addresses THREE distinct real hosts with overlapping method+path shapes:
+//   queue.fal.run  — the queue lifecycle (submit/status/result/cancel)
+//   fal.run        — the SYNCHRONOUS variant: identical POST /{model_id}, but settles inline and
+//                     returns the model's direct output (no queue envelope)
+//   rest.fal.ai    — the REST/admin surface (today: only the JWKS endpoint this twin models)
+// Resolution order, per the build spec (GROUNDED from fal-js's real `withProxy` proxy protocol,
+// TARGET_URL_HEADER = 'x-fal-target-url', verified against the fetched middleware.ts source):
+//   1. an explicit `host` (a real Host header, or a caller-supplied routing decision)
+//   2. the `x-fal-target-url` header (fal-js's OWN proxy protocol: when a caller proxies fal
+//      requests through their own server, the proxy middleware rewrites the request URL to the
+//      proxy's endpoint and stashes the ORIGINAL absolute URL in this header — a server acting as
+//      that proxy target recovers the true destination host from it, exactly what this twin's
+//      fal-sdk.integration.test.ts exercises)
+//   3. no host info at all -> default 'queue', EXCEPT: `/.well-known/jwks.json` is always 'rest'
+//      (there is no queue/sync analog of it) and any path containing '/requests/' is always
+//      'queue' (the sync surface never has sub-paths — a sync call is a bare POST /{model_id}).
+export type FalSurface = 'queue' | 'sync' | 'rest';
+
+function hostFromTargetUrlHeader(headers: Record<string, string>): string | undefined {
+  const raw = headers['x-fal-target-url'];
+  if (!raw) return undefined;
+  try {
+    return new URL(raw).host;
+  } catch {
+    return undefined;
+  }
+}
+
+export function routeFalSurface(req: { host?: string; headers?: Record<string, string>; path: string }): FalSurface {
+  const headers = lowerHeaders(req.headers);
+  const path = (req.path.split('?')[0] ?? '/').replace(/\/+$/, '') || '/';
+  const explicitHost = req.host ?? hostFromTargetUrlHeader(headers);
+  if (explicitHost === 'queue.fal.run') return 'queue';
+  if (explicitHost === 'rest.fal.ai') return 'rest';
+  if (explicitHost === 'fal.run') return 'sync';
+  if (path === '/.well-known/jwks.json') return 'rest';
+  if (path.includes('/requests/')) return 'queue';
+  return 'queue'; // default (documented above)
+}
+
+// ── error envelopes ────────────────────────────────────────────────────────────────────────
+// fal's gateway is FastAPI-based (grounded: the documented 422 validation-error shape is
+// FastAPI/Pydantic's standard `{"detail": [{"loc": [...], "msg": "...", "type": "..."}]}`).
+// Unmodeled/unknown-resource 404s are modeled on FastAPI's own default `{"detail": "..."}` 404
+// (doc-UNVERIFIED for the EXACT message text on fal's own routes — the fact of a `{detail}` shape
+// is a defensible FastAPI-framework default, not invented from nothing; capture-verify later).
+function detailNotFound(message = 'Not found.'): FalResponse {
+  return { status: 404, body: { detail: message } };
+}
+function validation422(errors: Array<{ loc: string[]; msg: string; type: string }>): FalResponse {
+  return { status: 422, body: { detail: errors } };
+}
+
+// ── body / time / id helpers ───────────────────────────────────────────────────────────
+function parseBody(body?: string): { ok: true; value: Record<string, unknown> } | { ok: false } {
+  if (body === undefined || body === '') return { ok: true, value: {} };
+  try {
+    const v = JSON.parse(body);
+    if (v && typeof v === 'object' && !Array.isArray(v)) return { ok: true, value: v as Record<string, unknown> };
+    return { ok: false };
+  } catch {
+    return { ok: false };
+  }
+}
+function nowIso(occurredAt?: string): string {
+  return occurredAt ?? new Date().toISOString();
+}
+function kid(type: string, id: string): string {
+  return `${type}:${id}`;
+}
+
+// ── projection helpers ──────────────────────────────────────────────────────────────
+function rows(type: string, root?: string): Array<Record<string, unknown>> {
+  const prefix = `${type}:`;
+  return projectResources(SERVICE, root)
+    .filter((r) => r.type === type && r.id.startsWith(prefix) && (r as Record<string, unknown>)._deleted !== true)
+    .map((r) => ({ ...r, id: r.id.slice(prefix.length) }));
+}
+function getRow(type: string, id: string, root?: string): Record<string, unknown> | undefined {
+  return rows(type, root).find((r) => r.id === id);
+}
+function view(r: Record<string, unknown>): Record<string, unknown> {
+  const { type: _t, updatedAt: _u, ...rest } = r;
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(rest)) if (!k.startsWith('_')) out[k] = v;
+  return out;
+}
+
+async function write(
+  type: string,
+  id: string,
+  fields: Record<string, unknown>,
+  op: string,
+  req: FalRequest,
+): Promise<Record<string, unknown>> {
+  const { resource } = await applyTwinWrite(
+    SERVICE,
+    { operation: op, subjectType: type, subjectId: kid(type, id), fields, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } },
+    req.root,
+  );
+  return view({ ...resource, id });
+}
+
+// ── GENERATIVE STUB (the twin's answer for generated output) ────────────────────────────
+function canonicalJson(v: unknown): string {
+  if (v === null || typeof v !== 'object') return JSON.stringify(v);
+  if (Array.isArray(v)) return `[${v.map(canonicalJson).join(',')}]`;
+  const keys = Object.keys(v as Record<string, unknown>).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson((v as Record<string, unknown>)[k])}`).join(',')}}`;
+}
+function stubOutput(modelId: string, input: unknown): string {
+  const hash = createHash('sha256').update(`${modelId}::${canonicalJson(input)}`).digest('hex').slice(0, 8);
+  return `[twin-stub:fal:${hash}] deterministic output — no GPU/model weights are run by this twin`;
+}
+
+// ── logs (grounded shape: {message, level, source:'USER', timestamp}) ────────────────────────
+type FalLogLevel = 'STDERR' | 'STDOUT' | 'ERROR' | 'INFO' | 'WARN' | 'DEBUG';
+function makeLog(message: string, level: FalLogLevel, occurredAt?: string): Record<string, unknown> {
+  return { message, level, source: 'USER', timestamp: nowIso(occurredAt) };
+}
+
+// ── request envelope views (mirror the fetched fal.ai docs' queue-status shapes) ──────────────
+function requestUrls(modelId: string, requestId: string): { response_url: string; status_url: string; cancel_url: string } {
+  return {
+    response_url: `https://queue.fal.run/${modelId}/requests/${requestId}`,
+    status_url: `https://queue.fal.run/${modelId}/requests/${requestId}/status`,
+    cancel_url: `https://queue.fal.run/${modelId}/requests/${requestId}/cancel`,
+  };
+}
+
+function submitEnvelope(row: Record<string, unknown>, modelId: string, requestId: string): Record<string, unknown> {
+  return {
+    request_id: requestId,
+    // Whether the submit body itself carries `status` is doc-UNVERIFIED (the fal-js client's own
+    // TypeScript response types declare it; the docs' own submit example omits it) — the build
+    // spec's ⚠1 resolves this by preferring the client's typed shape (it is the artifact real
+    // callers actually depend on) and annotating the gap here rather than silently picking one.
+    status: row.status,
+    ...requestUrls(modelId, requestId),
+    queue_position: (row.queue_position as number) ?? 0,
+  };
+}
+
+function statusView(row: Record<string, unknown>, modelId: string, requestId: string, includeLogs: boolean): Record<string, unknown> {
+  const status = row.status as string;
+  const base = { status, request_id: requestId, ...requestUrls(modelId, requestId) };
+  if (status === 'IN_QUEUE') {
+    return { ...base, queue_position: (row.queue_position as number) ?? 0 };
+  }
+  // logs=0 vs unset — both currently OMIT the field (⚠8, doc-UNVERIFIED whether the vendor
+  // distinguishes "absent" from "explicit empty array"; capture-verify later).
+  const logs = includeLogs ? { logs: (row.logs as unknown[]) ?? [] } : {};
+  if (status === 'IN_PROGRESS') return { ...base, ...logs };
+  // COMPLETED
+  return {
+    ...base,
+    ...logs,
+    metrics: { inference_time: (row.inference_time as number) ?? 0.42 },
+    ...(row.error ? { error: row.error, error_type: row.error_type } : {}),
+  };
+}
+
+/**
+ * Deterministic, kernel-folded poll-count progression (mirrors replicate-twin.ts's pattern,
+ * ported to fal's 3-step lifecycle): the FIRST status poll after submit is an IN_QUEUE echo (no
+ * transition — real queues don't jump straight to running), the SECOND transitions to
+ * IN_PROGRESS with the first log line, the THIRD transitions to COMPLETED with the second log
+ * line + a deterministic stub output + metrics. No wall clock, no timers — purely poll-count
+ * folded into the kernel row, so re-running a test suite is bit-for-bit reproducible.
+ */
+async function progressOnce(id: string, req: FalRequest): Promise<void> {
+  const row = getRow('request', id, req.root);
+  if (!row) return;
+  const pollCount = (row.poll_count as number) ?? 0;
+  if (row.status === 'IN_QUEUE') {
+    if (pollCount === 0) {
+      await write('request', id, { poll_count: pollCount + 1 }, 'request.poll', req);
+      return;
+    }
+    await write('request', id, {
+      status: 'IN_PROGRESS',
+      logs: [makeLog('Starting inference', 'INFO', req.occurredAt)],
+      poll_count: pollCount + 1,
+    }, 'request.progress', req);
+    return;
+  }
+  if (row.status === 'IN_PROGRESS') {
+    // The GENERATIVE CARVE-OUT is the one thing a handler may replace: the value the request
+    // settles to. The outcome was resolved at SUBMIT and PERSISTED (`_scripted_*`, stripped by
+    // `view`), so completion stays a pure fold of the log — this path never consults the engine.
+    const out = '_scripted_output' in row ? row._scripted_output : stubOutput(String(row.model_id ?? ''), row.input);
+    const priorLogs = (row.logs as unknown[]) ?? [];
+    await write('request', id, {
+      status: 'COMPLETED',
+      logs: [...priorLogs, makeLog('Inference complete', 'INFO', req.occurredAt)],
+      output: out,
+      completed_at: nowIso(req.occurredAt),
+      inference_time: typeof row._scripted_inference_time === 'number' ? row._scripted_inference_time : 0.42,
+      poll_count: pollCount + 1,
+    }, 'request.complete', req);
+  }
+  // COMPLETED: idempotent no-op — repeated polls of a settled request never regress state.
+}
+
+// ── submit (queue and sync surfaces share this; sync additionally drives it to completion) ────
+async function handleSubmit(modelId: string, rawBody: string | undefined, surface: FalSurface, req: FalRequest): Promise<FalResponse> {
+  const parsed = parseBody(rawBody);
+  // The gateway's own universal validation (independent of any per-model schema, which fal's
+  // gateway does not itself know): the submitted input must be a JSON object. Doc-UNVERIFIED
+  // exact message text — the FastAPI/Pydantic `{"detail":[{loc,msg,type}]}` shape itself IS
+  // grounded (fal's documented 422 examples use it); this specific trigger condition is a
+  // plausible, defensible modeling of it, not a confirmed live-API capture.
+  if (!parsed.ok) {
+    return validation422([{ loc: ['body'], msg: 'Input should be a valid dictionary or object to extract fields from', type: 'model_attributes_type' }]);
+  }
+  const input = parsed.value;
+  const createdAt = nowIso(req.occurredAt);
+  // DETERMINISTIC (R9, resource level): the request id is a UUID-SHAPED mint over
+  // `${type}:${occurredAt}:${ordinal}` — the world instant the submit happened at plus the count
+  // of request rows already stored, read BEFORE the insert — never `randomUUID`, so two
+  // identical worlds mint the same id and the queue's status/result reads are byte-identical.
+  // Two identical submits at one instant still get distinct ids: the ordinal moved.
+  const ordinal = rows('request', req.root).length;
+  const hex = createHash('sha256').update(`request:${createdAt}:${ordinal}`).digest('hex');
+  const id = `${hex.slice(0, 8)}-${hex.slice(8, 12)}-4${hex.slice(13, 16)}-${((parseInt(hex[16]!, 16) & 0x3) | 0x8).toString(16)}${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
+  // Scenario: resolve any scripted outcome NOW (submit time) and persist it on the resource, so
+  // the status progression is a pure fold of the log. A miss leaves the labeled stub in place.
+  const scripted: FalScenarioRespond | null = req.scenarioEngine
+    ? (() => {
+        const decision = req.scenarioEngine!.next({ modelId, input, surface: surface === 'sync' ? 'sync' : 'queue', nthRequest: ordinal + 1 });
+        return decision.kind === 'handler' ? (decision.respond as FalScenarioRespond) : null;
+      })()
+    : null;
+  await write('request', id, {
+    model_id: modelId,
+    input,
+    ...(scripted ? { _scripted_output: scripted.output } : {}),
+    ...(scripted?.inferenceTime !== undefined ? { _scripted_inference_time: scripted.inferenceTime } : {}),
+    status: 'IN_QUEUE',
+    queue_position: 0,
+    logs: [],
+    output: null,
+    error: null,
+    error_type: null,
+    created_at: createdAt,
+    completed_at: null,
+    webhook_url: null,
+    poll_count: 0,
+  }, 'request.create', req);
+
+  if (surface === 'sync') {
+    // fal.run settles INLINE (no queue polling exposed) and returns the model's direct output —
+    // no queue envelope. Drive the SAME deterministic 3-step progression the queue surface takes
+    // across 3 polls (poll1 IN_QUEUE echo -> poll2 IN_PROGRESS -> poll3 COMPLETED) in one call —
+    // mirrors replicate's `Prefer: wait` inline-settle pattern.
+    await progressOnce(id, req);
+    await progressOnce(id, req);
+    await progressOnce(id, req);
+    const settled = getRow('request', id, req.root)!;
+    return { status: 200, body: { output: settled.output } };
+  }
+  const row = getRow('request', id, req.root)!;
+  return { status: 200, body: submitEnvelope(row, modelId, id) };
+}
+
+async function handleStatus(modelId: string, requestId: string, includeLogs: boolean, req: FalRequest): Promise<FalResponse> {
+  const existing = getRow('request', requestId, req.root);
+  if (!existing) return detailNotFound('Request not found.');
+  await progressOnce(requestId, req);
+  const row = getRow('request', requestId, req.root)!;
+  return { status: 200, body: statusView(row, modelId, requestId, includeLogs) };
+}
+
+async function handleResult(requestId: string, req: FalRequest): Promise<FalResponse> {
+  const row = getRow('request', requestId, req.root);
+  if (!row) return detailNotFound('Request not found.');
+  // Pre-completion behavior is genuinely unmodeled (`fal.queue.response_long_poll`, todo — this
+  // twin settles instantly on `status` polls rather than long-polling); every DONE capability
+  // that reads this route first drives the request to COMPLETED via `status` polls.
+  return { status: 200, body: { output: row.output ?? null } };
+}
+
+async function handleCancel(requestId: string, req: FalRequest): Promise<FalResponse> {
+  const row = getRow('request', requestId, req.root);
+  // Cancel's 404 is its OWN documented shape (`{"status":"NOT_FOUND"}`), NOT the generic
+  // `{detail}` 404 envelope every other unknown-resource route in this pack uses — grounded
+  // verbatim from fal.ai/docs/model-endpoints/queue's cancel-endpoint error table.
+  if (!row) return { status: 404, body: { status: 'NOT_FOUND' } };
+  if (row.status === 'COMPLETED') return { status: 400, body: { status: 'ALREADY_COMPLETED' } };
+  // The real terminal state a successful cancellation settles into is UNKNOWN (fal's documented
+  // status enum — IN_QUEUE/IN_PROGRESS/COMPLETED — has no CANCELLED member; `⚠4` in the build
+  // spec). This twin claims ONLY the grounded 202 acknowledgement body, not any resulting state
+  // transition (`fal.queue.cancelled_terminal_state` stays `todo`) — deliberately does NOT
+  // mutate `row.status`, so a subsequent status poll continues its ordinary progression rather
+  // than asserting an invented terminal state.
+  return { status: 202, body: { status: 'CANCELLATION_REQUESTED' } };
+}
+
+// ── route handler ────────────────────────────────────────────────────────────────────
+export async function handleFalTwinRequest(req: FalRequest): Promise<FalResponse> {
+  const method = req.method.toUpperCase();
+  const [rawPath, rawQuery] = req.path.split('?');
+  const path = (rawPath ?? '/').replace(/\/+$/, '') || '/';
+  const headers = lowerHeaders(req.headers);
+  const surface = routeFalSurface({ host: req.host, headers: req.headers, path });
+
+  if (req.readOnly && method !== 'GET' && method !== 'HEAD') {
+    return { status: 405, body: { detail: 'twin is read-only; omit readOnly to accept writes' } };
+  }
+
+  if (path === '/' || path === '') {
+    return { status: 200, body: { service: 'fal', object: 'twin' } };
+  }
+
+  // ── REST surface: today, only the JWKS endpoint ──
+  if (surface === 'rest') {
+    if (method === 'GET' && path === '/.well-known/jwks.json') {
+      return { status: 200, body: await falJwks(req.root) };
+    }
+    return detailNotFound();
+  }
+
+  const seg = path.replace(/^\/+/, '').split('/').filter(Boolean);
+  const reqIdx = seg.indexOf('requests');
+
+  // ── submit: POST /{model_id} (model ids are 2- or 3-segment, e.g. fal-ai/flux/schnell) ──
+  if (reqIdx === -1) {
+    if (method === 'POST' && seg.length >= 1) {
+      return handleSubmit(seg.map(decodeURIComponent).join('/'), req.body, surface, req);
+    }
+    return detailNotFound();
+  }
+
+  // ── queue lifecycle: {model_id}/requests/{request_id}[/status[/stream]|/response|/cancel] ──
+  const modelId = seg.slice(0, reqIdx).map(decodeURIComponent).join('/');
+  const requestId = decodeURIComponent(seg[reqIdx + 1] ?? '');
+  const rest = seg.slice(reqIdx + 2);
+
+  if (method === 'GET' && rest.length === 1 && rest[0] === 'status') {
+    const query = new URLSearchParams(rawQuery ?? '');
+    const includeLogs = query.get('logs') === '1';
+    return handleStatus(modelId, requestId, includeLogs, req);
+  }
+  if (method === 'GET' && rest.length === 2 && rest[0] === 'status' && rest[1] === 'stream') {
+    // SSE streaming (`fal.streaming.status_stream_sse`, todo) — genuinely unmodeled.
+    return detailNotFound();
+  }
+  if (method === 'GET' && rest.length === 0) {
+    return handleResult(requestId, req);
+  }
+  if (method === 'GET' && rest.length === 1 && rest[0] === 'response') {
+    // The doc-example alias route — served so a doc-literal caller works too (⚠2).
+    return handleResult(requestId, req);
+  }
+  if (method === 'PUT' && rest.length === 1 && rest[0] === 'cancel') {
+    return handleCancel(requestId, req);
+  }
+
+  return detailNotFound();
+}
+
+export type FalTwinSnapshot = {
+  resourceTypes: readonly FalResourceType[];
+  implementedEndpoints: readonly string[];
+};
+
+// Endpoint inventory used by the conformance snapshot (self-referential — see fal-conformance.ts
+// header note and docs/contributing/conformance.md's "2 spec" discussion of this pattern, shared with replicate/
+// elevenlabs/polar). fal's real v1 surface is intentionally much smaller than replicate's (no
+// models/versions/collections/trainings/deployments CRUD — build spec §0), so this snapshot
+// counts each INDIVIDUALLY-DOCUMENTED request/response CONTRACT (not just each distinct URL
+// pattern) as its own entry — e.g. cancel's three distinct, separately-grounded status-code
+// contracts (202/400/404) are 3 entries, not 1 — since each is independently verified by its own
+// `done` capability and lumping them would UNDER-count real, grounded, implemented behavior
+// rather than pad it.
+export function falTwinSnapshot(): FalTwinSnapshot {
+  return {
+    resourceTypes: FAL_RESOURCE_TYPES,
+    implementedEndpoints: [
+      'POST queue.fal.run/{model_id} (queue submit)',
+      'POST fal.run/{model_id} (sync submit, direct output)',
+      'GET queue.fal.run/{model_id}/requests/{request_id}/status (IN_QUEUE/IN_PROGRESS/COMPLETED progression, logs param)',
+      'GET queue.fal.run/{model_id}/requests/{request_id}/status (404 unknown request_id)',
+      'GET queue.fal.run/{model_id}/requests/{request_id} (result, client-built bare form)',
+      'GET queue.fal.run/{model_id}/requests/{request_id}/response (result, docs-example alias form)',
+      'PUT queue.fal.run/{model_id}/requests/{request_id}/cancel (202 CANCELLATION_REQUESTED)',
+      'PUT queue.fal.run/{model_id}/requests/{request_id}/cancel (400 ALREADY_COMPLETED)',
+      'PUT queue.fal.run/{model_id}/requests/{request_id}/cancel (404 NOT_FOUND)',
+      'POST queue.fal.run/{model_id} (422 validation error)',
+      'GET rest.fal.ai/.well-known/jwks.json',
+    ],
+  };
+}