@volter/twin-fal 0.1.0

package/dist/src/fal-scenario.d.ts

@@ -0,0 +1,26 @@
+import { type PackScenarioAdapter, type ScenarioDocument, ScenarioEngine } 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;
+};
+/** 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 declare function canonicalInputText(input: unknown): string;
+export declare const falScenarioAdapter: PackScenarioAdapter<FalScenarioRequest>;
+/** Load + strictly validate a handlers document (handlers/fal.json). A broken file fails server
+ *  construction loudly; it never falls back or misfires silently. */
+export declare function loadFalScenarioDocument(path: string): ScenarioDocument;
+export declare function createFalScenarioEngine(document?: ScenarioDocument): FalScenarioEngine;

package/dist/src/fal-scenario.js

@@ -0,0 +1,100 @@
+// 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, ScenarioError, ScenarioEngine } from '@volter/world-core';
+const RESPOND_KEYS = new Set(['output', 'inferenceTime']);
+const nonEmptyString = (cond) => 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) {
+    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).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalInputText(input[k])}`).join(',')}}`;
+}
+export const falScenarioAdapter = {
+    vendor: 'fal',
+    features: (req) => ({
+        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']) {
+            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 < 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;
+        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) {
+    let parsed;
+    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) {
+    return new ScenarioEngine(falScenarioAdapter, document);
+}

package/dist/src/fal-server.d.ts

@@ -0,0 +1,18 @@
+/** 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 declare function createFalTwinFetch(options?: FalTwinFetchOptions): (request: Request) => Promise<Response>;
+export declare function createFalTwinServer(options?: {
+    root?: string;
+    port?: number;
+    readOnly?: boolean;
+    scenarioPath?: string;
+}): Promise<{
+    port: number;
+    stop: () => void;
+}>;

package/dist/src/fal-server.js

@@ -0,0 +1,53 @@
+// 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.js";
+import { createTwinFetchFromHandler, twinManifest } from '@volter/world-core';
+import { createFalScenarioEngine, loadFalScenarioDocument } from "./fal-scenario.js";
+export function createFalTwinFetch(options = {}) {
+    const scenarioPath = options.scenarioPath ?? process.env.TWIN_FAL_SCENARIO;
+    const scenarioEngine = 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,
+        }),
+        scenarioStatus: () => (scenarioEngine ? scenarioEngine.status() : { vendor: 'fal', handlers: [], misses: 0, recentMisses: [] }),
+        ...(scenarioEngine ? { handlerOptions: { scenarioEngine } } : {}),
+    });
+}
+export async function createFalTwinServer(options = {}) {
+    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/dist/src/fal-twin.d.ts

@@ -0,0 +1,36 @@
+import type { FalScenarioEngine } from './fal-scenario.js';
+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>;
+};
+export declare const FAL_RESOURCE_TYPES: readonly ["request", "signing_key"];
+export type FalResourceType = typeof FAL_RESOURCE_TYPES[number];
+export type FalSurface = 'queue' | 'sync' | 'rest';
+export declare function routeFalSurface(req: {
+    host?: string;
+    headers?: Record<string, string>;
+    path: string;
+}): FalSurface;
+export declare function handleFalTwinRequest(req: FalRequest): Promise<FalResponse>;
+export type FalTwinSnapshot = {
+    resourceTypes: readonly FalResourceType[];
+    implementedEndpoints: readonly string[];
+};
+export declare function falTwinSnapshot(): FalTwinSnapshot;

package/dist/src/fal-twin.js

@@ -0,0 +1,414 @@
+// 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.js";
+const SERVICE = 'fal';
+// 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'];
+function lowerHeaders(h) {
+    const out = {};
+    for (const [k, v] of Object.entries(h ?? {}))
+        out[k.toLowerCase()] = v;
+    return out;
+}
+function hostFromTargetUrlHeader(headers) {
+    const raw = headers['x-fal-target-url'];
+    if (!raw)
+        return undefined;
+    try {
+        return new URL(raw).host;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function routeFalSurface(req) {
+    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.') {
+    return { status: 404, body: { detail: message } };
+}
+function validation422(errors) {
+    return { status: 422, body: { detail: errors } };
+}
+// ── body / time / id helpers ───────────────────────────────────────────────────────────
+function parseBody(body) {
+    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 };
+        return { ok: false };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+function nowIso(occurredAt) {
+    return occurredAt ?? new Date().toISOString();
+}
+function kid(type, id) {
+    return `${type}:${id}`;
+}
+// ── projection helpers ──────────────────────────────────────────────────────────────
+function rows(type, root) {
+    const prefix = `${type}:`;
+    return projectResources(SERVICE, root)
+        .filter((r) => r.type === type && r.id.startsWith(prefix) && r._deleted !== true)
+        .map((r) => ({ ...r, id: r.id.slice(prefix.length) }));
+}
+function getRow(type, id, root) {
+    return rows(type, root).find((r) => r.id === id);
+}
+function view(r) {
+    const { type: _t, updatedAt: _u, ...rest } = r;
+    const out = {};
+    for (const [k, v] of Object.entries(rest))
+        if (!k.startsWith('_'))
+            out[k] = v;
+    return out;
+}
+async function write(type, id, fields, op, req) {
+    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) {
+    if (v === null || typeof v !== 'object')
+        return JSON.stringify(v);
+    if (Array.isArray(v))
+        return `[${v.map(canonicalJson).join(',')}]`;
+    const keys = Object.keys(v).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(v[k])}`).join(',')}}`;
+}
+function stubOutput(modelId, input) {
+    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`;
+}
+function makeLog(message, level, occurredAt) {
+    return { message, level, source: 'USER', timestamp: nowIso(occurredAt) };
+}
+// ── request envelope views (mirror the fetched fal.ai docs' queue-status shapes) ──────────────
+function requestUrls(modelId, requestId) {
+    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, modelId, requestId) {
+    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 ?? 0,
+    };
+}
+function statusView(row, modelId, requestId, includeLogs) {
+    const status = row.status;
+    const base = { status, request_id: requestId, ...requestUrls(modelId, requestId) };
+    if (status === 'IN_QUEUE') {
+        return { ...base, queue_position: row.queue_position ?? 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 ?? [] } : {};
+    if (status === 'IN_PROGRESS')
+        return { ...base, ...logs };
+    // COMPLETED
+    return {
+        ...base,
+        ...logs,
+        metrics: { inference_time: row.inference_time ?? 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, req) {
+    const row = getRow('request', id, req.root);
+    if (!row)
+        return;
+    const pollCount = row.poll_count ?? 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 ?? [];
+        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, rawBody, surface, req) {
+    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 = req.scenarioEngine
+        ? (() => {
+            const decision = req.scenarioEngine.next({ modelId, input, surface: surface === 'sync' ? 'sync' : 'queue', nthRequest: ordinal + 1 });
+            return decision.kind === 'handler' ? decision.respond : 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, requestId, includeLogs, req) {
+    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, req) {
+    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, req) {
+    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) {
+    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();
+}
+// 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() {
+    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',
+        ],
+    };
+}