@volter/twin-fal 0.1.0

package/dist/src/fal-capabilities.js

@@ -0,0 +1,419 @@
+// fal capability manifest — the EXPECTED REAL-PRODUCT SURFACE (the target), authored top-down
+// from what the fal.ai API actually does — GROUNDED read-only (2026-07-09) against
+// fal.ai/docs/model-endpoints/{queue,webhooks} and the fal-js client source
+// (github.com/fal-ai/fal-js, libs/client/src/{config,middleware,queue,request}.ts) — see
+// spec-sources.json — NOT from what this twin has built. This is the honest denominator: many
+// entries start as `todo` and coverage reads LOW until the twin truly reaches 100% of the API.
+// `verify()` (required to count as done) is ground truth and drives the KERNEL-BACKED handler on
+// a FRESH temp root — never a spawned mock. `expected:'done'` only on capabilities we genuinely
+// claim, so a broken one shows as a regression.
+//
+// v1 SLICE (honesty, per the build spec): queue lifecycle (submit/status/response/cancel) +
+// the sync `fal.run` variant + host-split routing + ed25519 webhooks/JWKS + FastAPI error
+// envelopes are modeled `done`. fal's real surface is genuinely SMALLER than replicate's here —
+// no models/versions/collections/trainings/deployments CRUD (no such REST resources exist for
+// fal) — but SSE streaming, realtime WS, storage/asset upload, and per-model app discovery are
+// left `todo` with vendor-shaped failure (unmodeled route -> 404) — a deliberate v1 scope cut,
+// not an oversight; see README `## Coverage`.
+//
+// THE GENERATIVE STUB IS THE ANSWER: a request's output is a clearly-labeled deterministic stub
+// while the protocol envelope (status machine, queue_position, logs, urls, metrics) is faithful.
+// Every entry here is either done or todo.
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { checkCapabilities, verifyBoundary } from '@volter/world-tooling';
+import { handleFalTwinRequest } from "./fal-twin.js";
+import { checkFalConformance } from "./fal-conformance.js";
+import { syncFalFromReal } from "./fal-connector.js";
+import { buildSignedFalWebhook, verifyFalWebhook, verifyFalWebhookSignatureWithKey, falWebhookPublicKeyFromJwk, FalWebhookVerificationError, } from "./fal-webhooks.js";
+// (fal is an API-first vendor with no product UI worth mirroring — docs/contributing/architecture.md C1b — so this
+// pack ships no mirror, and there are no UI capabilities.)
+const OCCURRED_AT = '2026-01-01T00:00:00.000Z';
+// Every webhook verify below pins `now` to this same fixed instant — the tolerance check
+// otherwise defaults to the REAL current wall clock, which drifts arbitrarily far from a fixed
+// past `occurredAt` (this file is authored once; `bun test` may run it months later) and would
+// spuriously fail outside `fal.webhooks.timestamp_tolerance`'s own dedicated test of that check.
+const OCCURRED_AT_EPOCH_SEC = Math.floor(Date.parse(OCCURRED_AT) / 1000);
+/** Run a sequence of real fal requests against an isolated root; return all responses. The
+ *  callback also receives `root` itself — some verifies (webhook/JWKS key-matching) need to
+ *  build local artifacts against the SAME root the handler used. */
+async function withRoot(steps) {
+    const root = mkdtempSync(join(tmpdir(), 'fal-cap-'));
+    const h = (s) => handleFalTwinRequest({
+        method: s.m,
+        path: s.p,
+        body: s.b === undefined ? undefined : JSON.stringify(s.b),
+        root,
+        ...(s.h ? { headers: s.h } : {}),
+        ...(s.host ? { host: s.host } : {}),
+    });
+    try {
+        return await verifyBoundary('fal.withRoot', () => steps(h, root));
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+}
+/** An isolated root for the verifies that exercise ONLY the local ed25519 helpers (no handler).
+ *  They still touch state: the signing seed is entropy-born and PERSISTED on first use
+ *  (fal-webhooks.ts), so a root of their own keeps them hermetic instead of folding a key into
+ *  whatever project root the suite happens to run from. */
+async function withTempRoot(steps) {
+    const root = mkdtempSync(join(tmpdir(), 'fal-cap-'));
+    try {
+        return await steps(root);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+}
+const done = (id, area, title, dimension, tier, verify) => ({ id, area, title, dimension, tier, expected: 'done', verify });
+const todo = (id, area, title, dimension, tier) => ({ id, area, title, dimension, tier, expected: 'todo' });
+export const FAL_CAPABILITIES = [
+    todo('fal.assets.served_output_bytes', 'storage', 'Output URLs resolve: persist and serve deterministic placeholder media bytes at the output urls a request settles to (today the output is a labeled placeholder value)', 'api', 'common'),
+    // ── QUEUE (submit -> status progression -> response -> cancel) ──────────────────────────
+    done('fal.queue.submit', 'queue', 'POST queue.fal.run/{model_id} submits -> 200 (⚠ status code doc-unverified — the docs\' own example omits an explicit code) with request_id/urls/queue_position', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/acme/widget', b: { prompt: 'hi' }, host: 'queue.fal.run' });
+        if (r.status !== 200)
+            return false;
+        const b = r.body;
+        const id = b.request_id;
+        return typeof id === 'string' && /^[0-9a-f-]{36}$/i.test(id) && b.status === 'IN_QUEUE' && b.queue_position === 0
+            && typeof b.response_url === 'string' && b.response_url.includes(id)
+            && typeof b.status_url === 'string' && b.status_url.includes(id)
+            && typeof b.cancel_url === 'string' && b.cancel_url.includes(id);
+    })),
+    done('fal.queue.submit_nested_model_id', 'queue', '3-segment model id (owner/app/variant, e.g. fal-ai/flux/schnell) round-trips through the /requests/ split', 'api', 'common', () => withRoot(async (h) => {
+        const c = await h({ m: 'POST', p: '/fal-ai/flux/schnell', b: { prompt: 'hi' }, host: 'queue.fal.run' });
+        const id = c.body.request_id;
+        // a dead twin returns {} — id must be a REAL non-empty string first, or the final
+        // comparison (undefined === undefined) is vacuous (the mutation gate catches exactly this).
+        if (typeof id !== 'string' || id.length === 0)
+            return false;
+        const s = await h({ m: 'GET', p: `/fal-ai/flux/schnell/requests/${id}/status`, host: 'queue.fal.run' });
+        return c.status === 200 && s.status === 200 && s.body.request_id === id;
+    })),
+    done('fal.queue.status_in_queue', 'queue', 'first status GET after submit: IN_QUEUE echo + queue_position + base url fields', 'api', 'core', () => withRoot(async (h) => {
+        const c = await h({ m: 'POST', p: '/acme/widget', b: {}, host: 'queue.fal.run' });
+        const id = c.body.request_id;
+        const s = await h({ m: 'GET', p: `/acme/widget/requests/${id}/status`, host: 'queue.fal.run' });
+        const b = s.body;
+        return s.status === 200 && b.status === 'IN_QUEUE' && b.queue_position === 0 && b.request_id === id
+            && typeof b.response_url === 'string' && typeof b.status_url === 'string' && typeof b.cancel_url === 'string';
+    })),
+    done('fal.queue.status_progresses', 'queue', 'status polls progress IN_QUEUE -> IN_PROGRESS -> COMPLETED; COMPLETED carries numeric metrics.inference_time', 'api', 'core', () => withRoot(async (h) => {
+        const c = await h({ m: 'POST', p: '/acme/widget', b: {}, host: 'queue.fal.run' });
+        const id = c.body.request_id;
+        const p1 = await h({ m: 'GET', p: `/acme/widget/requests/${id}/status`, host: 'queue.fal.run' });
+        const p2 = await h({ m: 'GET', p: `/acme/widget/requests/${id}/status`, host: 'queue.fal.run' });
+        const p3 = await h({ m: 'GET', p: `/acme/widget/requests/${id}/status`, host: 'queue.fal.run' });
+        if (p1.body.status !== 'IN_QUEUE')
+            return false;
+        if (p2.body.status !== 'IN_PROGRESS')
+            return false;
+        const b3 = p3.body;
+        return b3.status === 'COMPLETED' && typeof b3.metrics?.inference_time === 'number';
+    })),
+    done('fal.queue.status_logs_param', 'queue', '?logs=1 returns log entries {message,level,source:USER,timestamp}; logs unset -> absent (⚠ doc-unverified: absent vs explicit-empty)', 'api', 'common', () => withRoot(async (h) => {
+        const submit = async () => (await h({ m: 'POST', p: '/acme/widget', b: {}, host: 'queue.fal.run' })).body.request_id;
+        const idA = await submit();
+        const idB = await submit();
+        await h({ m: 'GET', p: `/acme/widget/requests/${idA}/status`, host: 'queue.fal.run' }); // poll1 IN_QUEUE
+        const a2 = await h({ m: 'GET', p: `/acme/widget/requests/${idA}/status?logs=1`, host: 'queue.fal.run' }); // poll2 IN_PROGRESS, logs requested
+        await h({ m: 'GET', p: `/acme/widget/requests/${idB}/status`, host: 'queue.fal.run' }); // poll1 IN_QUEUE
+        const b2 = await h({ m: 'GET', p: `/acme/widget/requests/${idB}/status`, host: 'queue.fal.run' }); // poll2 IN_PROGRESS, no logs param
+        const aBody = a2.body;
+        const bBody = b2.body;
+        if (aBody.status !== 'IN_PROGRESS' || bBody.status !== 'IN_PROGRESS')
+            return false;
+        const logs = aBody.logs;
+        if (!Array.isArray(logs) || logs.length === 0)
+            return false;
+        const entry = logs[0];
+        const shapeOk = typeof entry.message === 'string' && typeof entry.timestamp === 'string' && typeof entry.level === 'string' && entry.source === 'USER';
+        return shapeOk && bBody.logs === undefined;
+    })),
+    done('fal.queue.logs_progress', 'queue', 'logs array grows across polls (poll2 length < poll3 length), deterministic across independent requests', 'api', 'common', () => withRoot(async (h) => {
+        const c = await h({ m: 'POST', p: '/acme/widget', b: {}, host: 'queue.fal.run' });
+        const id = c.body.request_id;
+        await h({ m: 'GET', p: `/acme/widget/requests/${id}/status?logs=1`, host: 'queue.fal.run' }); // poll1
+        const p2 = await h({ m: 'GET', p: `/acme/widget/requests/${id}/status?logs=1`, host: 'queue.fal.run' }); // poll2
+        const p3 = await h({ m: 'GET', p: `/acme/widget/requests/${id}/status?logs=1`, host: 'queue.fal.run' }); // poll3
+        const logs2 = p2.body.logs;
+        const logs3 = p3.body.logs;
+        if (!Array.isArray(logs2) || !Array.isArray(logs3) || logs2.length >= logs3.length)
+            return false;
+        // determinism: an independent, identically-shaped request reaches the SAME poll-2 log text.
+        const c2 = await h({ m: 'POST', p: '/acme/widget', b: {}, host: 'queue.fal.run' });
+        const id2 = c2.body.request_id;
+        await h({ m: 'GET', p: `/acme/widget/requests/${id2}/status?logs=1`, host: 'queue.fal.run' });
+        const p2b = await h({ m: 'GET', p: `/acme/widget/requests/${id2}/status?logs=1`, host: 'queue.fal.run' });
+        const logs2b = p2b.body.logs;
+        return logs2[0].message === logs2b[0].message;
+    })),
+    done('fal.queue.response', 'queue', 'GET .../requests/{id} after COMPLETED returns the stub output; the docs-example /response alias route also serves it', 'api', 'core', () => withRoot(async (h) => {
+        const c = await h({ m: 'POST', p: '/acme/widget', b: { prompt: 'hi' }, host: 'queue.fal.run' });
+        const id = c.body.request_id;
+        await h({ m: 'GET', p: `/acme/widget/requests/${id}/status`, host: 'queue.fal.run' });
+        await h({ m: 'GET', p: `/acme/widget/requests/${id}/status`, host: 'queue.fal.run' });
+        await h({ m: 'GET', p: `/acme/widget/requests/${id}/status`, host: 'queue.fal.run' });
+        const bare = await h({ m: 'GET', p: `/acme/widget/requests/${id}`, host: 'queue.fal.run' });
+        const alias = await h({ m: 'GET', p: `/acme/widget/requests/${id}/response`, host: 'queue.fal.run' });
+        const out1 = bare.body.output;
+        const out2 = alias.body.output;
+        return bare.status === 200 && alias.status === 200 && typeof out1 === 'string' && out1.includes('[twin-stub:fal:') && out1 === out2;
+    })),
+    done('fal.queue.response_deterministic_stub', 'queue', 'stub output is a pure fn of (model_id, input): same input twice -> identical, different input -> different', 'api', 'core', () => withRoot(async (h) => {
+        const settle = async (input) => {
+            const c = await h({ m: 'POST', p: '/acme/widget', b: input, host: 'queue.fal.run' });
+            const id = c.body.request_id;
+            await h({ m: 'GET', p: `/acme/widget/requests/${id}/status`, host: 'queue.fal.run' }); // poll1 IN_QUEUE
+            await h({ m: 'GET', p: `/acme/widget/requests/${id}/status`, host: 'queue.fal.run' }); // poll2 IN_PROGRESS
+            await h({ m: 'GET', p: `/acme/widget/requests/${id}/status`, host: 'queue.fal.run' }); // poll3 COMPLETED
+            const r = await h({ m: 'GET', p: `/acme/widget/requests/${id}`, host: 'queue.fal.run' });
+            return r.body.output;
+        };
+        const a = await settle({ text: 'same' });
+        const b = await settle({ text: 'same' });
+        const c = await settle({ text: 'different' });
+        return typeof a === 'string' && a.includes('[twin-stub:fal:') && a === b && a !== c;
+    })),
+    done('fal.queue.request_isolation', 'queue', 'two independent submits: progressing one to COMPLETED leaves the other at IN_QUEUE', 'api', 'common', () => withRoot(async (h) => {
+        const a = await h({ m: 'POST', p: '/acme/widget', b: {}, host: 'queue.fal.run' });
+        const b = await h({ m: 'POST', p: '/acme/widget', b: {}, host: 'queue.fal.run' });
+        const idA = a.body.request_id;
+        const idB = b.body.request_id;
+        await h({ m: 'GET', p: `/acme/widget/requests/${idA}/status`, host: 'queue.fal.run' });
+        await h({ m: 'GET', p: `/acme/widget/requests/${idA}/status`, host: 'queue.fal.run' });
+        const sa = await h({ m: 'GET', p: `/acme/widget/requests/${idA}/status`, host: 'queue.fal.run' });
+        const sb = await h({ m: 'GET', p: `/acme/widget/requests/${idB}/status`, host: 'queue.fal.run' });
+        return sa.body.status === 'COMPLETED' && sb.body.status === 'IN_QUEUE';
+    })),
+    done('fal.queue.status_unknown_404', 'queue', 'GET status for an unknown request_id -> 404 {detail} (⚠ doc-unverified exact message text)', 'api', 'common', () => withRoot(async (h) => {
+        const r = await h({ m: 'GET', p: '/acme/widget/requests/does-not-exist/status', host: 'queue.fal.run' });
+        return r.status === 404 && typeof r.body.detail === 'string';
+    })),
+    done('fal.queue.cancel_in_queue', 'queue', 'PUT cancel on a non-terminal request -> 202 {"status":"CANCELLATION_REQUESTED"} exact', 'api', 'core', () => withRoot(async (h) => {
+        const c = await h({ m: 'POST', p: '/acme/widget', b: {}, host: 'queue.fal.run' });
+        const id = c.body.request_id;
+        const r = await h({ m: 'PUT', p: `/acme/widget/requests/${id}/cancel`, host: 'queue.fal.run' });
+        return r.status === 202 && JSON.stringify(r.body) === JSON.stringify({ status: 'CANCELLATION_REQUESTED' });
+    })),
+    done('fal.queue.cancel_completed_400', 'queue', 'PUT cancel on a COMPLETED request -> 400 {"status":"ALREADY_COMPLETED"} exact', 'api', 'common', () => withRoot(async (h) => {
+        const c = await h({ m: 'POST', p: '/acme/widget', b: {}, host: 'queue.fal.run' });
+        const id = c.body.request_id;
+        await h({ m: 'GET', p: `/acme/widget/requests/${id}/status`, host: 'queue.fal.run' });
+        await h({ m: 'GET', p: `/acme/widget/requests/${id}/status`, host: 'queue.fal.run' });
+        await h({ m: 'GET', p: `/acme/widget/requests/${id}/status`, host: 'queue.fal.run' });
+        const r = await h({ m: 'PUT', p: `/acme/widget/requests/${id}/cancel`, host: 'queue.fal.run' });
+        return r.status === 400 && JSON.stringify(r.body) === JSON.stringify({ status: 'ALREADY_COMPLETED' });
+    })),
+    done('fal.queue.cancel_unknown_404', 'queue', 'PUT cancel on an unknown request_id -> 404 {"status":"NOT_FOUND"} exact (its OWN documented shape, distinct from the {detail} envelope every other 404 in this pack uses)', 'api', 'common', () => withRoot(async (h) => {
+        const r = await h({ m: 'PUT', p: '/acme/widget/requests/does-not-exist/cancel', host: 'queue.fal.run' });
+        return r.status === 404 && JSON.stringify(r.body) === JSON.stringify({ status: 'NOT_FOUND' });
+    })),
+    done('fal.queue.urls_self_consistent', 'queue', 'response_url/status_url/cancel_url are IDENTICAL across the submit and status responses, and embed the same model_id/request_id', 'api', 'common', () => withRoot(async (h) => {
+        const c = await h({ m: 'POST', p: '/acme/widget', b: {}, host: 'queue.fal.run' });
+        const cb = c.body;
+        const id = cb.request_id;
+        const s = await h({ m: 'GET', p: `/acme/widget/requests/${id}/status`, host: 'queue.fal.run' });
+        const sb = s.body;
+        const urlsMatch = cb.response_url === sb.response_url && cb.status_url === sb.status_url && cb.cancel_url === sb.cancel_url;
+        return urlsMatch && cb.status_url.includes('acme/widget') && cb.status_url.includes(id);
+    })),
+    // ── SYNC (fal.run direct-output variant) + HOST-SPLIT ROUTING ────────────────────────────
+    done('fal.sync.run', 'sync', 'POST fal.run/{model_id} (sync surface) settles in one call; output equals the queue-completed stub for the same input', 'api', 'core', () => withRoot(async (h) => {
+        const input = { text: 'sync-test' };
+        const sync = await h({ m: 'POST', p: '/acme/widget', b: input, host: 'fal.run' });
+        const queueC = await h({ m: 'POST', p: '/acme/widget', b: input, host: 'queue.fal.run' });
+        const qid = queueC.body.request_id;
+        await h({ m: 'GET', p: `/acme/widget/requests/${qid}/status`, host: 'queue.fal.run' }); // poll1 IN_QUEUE
+        await h({ m: 'GET', p: `/acme/widget/requests/${qid}/status`, host: 'queue.fal.run' }); // poll2 IN_PROGRESS
+        await h({ m: 'GET', p: `/acme/widget/requests/${qid}/status`, host: 'queue.fal.run' }); // poll3 COMPLETED
+        const qOut = await h({ m: 'GET', p: `/acme/widget/requests/${qid}`, host: 'queue.fal.run' });
+        const syncOut = sync.body.output;
+        return sync.status === 200 && typeof syncOut === 'string' && syncOut === qOut.body.output;
+    })),
+    done('fal.sync.host_split', 'sync', 'identical POST method+path routed by HOST alone: queue.fal.run -> queue envelope (request_id/urls), fal.run -> direct output (no envelope)', 'api', 'common', () => withRoot(async (h) => {
+        const queueR = await h({ m: 'POST', p: '/acme/widget', b: { x: 1 }, host: 'queue.fal.run' });
+        const syncR = await h({ m: 'POST', p: '/acme/widget', b: { x: 1 }, host: 'fal.run' });
+        const qb = queueR.body;
+        const sb = syncR.body;
+        return queueR.status === 200 && syncR.status === 200 && typeof qb.request_id === 'string' && qb.output === undefined
+            && sb.request_id === undefined && typeof sb.output === 'string';
+    })),
+    done('fal.proxy.target_url_header', 'proxy', 'x-fal-target-url header (the REAL fal-js proxy protocol) routes to the queue surface with no explicit host', 'api', 'common', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/acme/widget', b: {}, h: { 'x-fal-target-url': 'https://queue.fal.run/acme/widget' } });
+        return r.status === 200 && typeof r.body.request_id === 'string';
+    })),
+    // ── WEBHOOKS (ed25519 sign/verify + JWKS) ─────────────────────────────────────────────────
+    done('fal.webhooks.request_signing', 'webhooks', 'ed25519 sign/verify round-trip over request_id\\nuser_id\\ntimestamp\\nsha256hex(body); a tampered signature is rejected', 'api', 'common', () => withTempRoot(async (root) => {
+        const built = await buildSignedFalWebhook({ requestId: 'req_abc', userId: 'user_1', status: 'OK', payload: { ok: true }, occurredAt: OCCURRED_AT, root });
+        const verified = await verifyFalWebhook(built.body, built.headers, root, { now: OCCURRED_AT_EPOCH_SEC });
+        if (verified.request_id !== 'req_abc' || verified.status !== 'OK')
+            return false;
+        const lastChar = built.headers['x-fal-webhook-signature'].slice(-1);
+        const flipped = lastChar === 'a' ? 'b' : 'a';
+        const tampered = { ...built.headers, 'x-fal-webhook-signature': built.headers['x-fal-webhook-signature'].slice(0, -1) + flipped };
+        try {
+            await verifyFalWebhook(built.body, tampered, root, { now: OCCURRED_AT_EPOCH_SEC });
+            return false;
+        }
+        catch (err) {
+            return err instanceof FalWebhookVerificationError;
+        }
+    })),
+    done('fal.webhooks.jwks', 'webhooks', "GET /.well-known/jwks.json -> {keys:[{kty:'OKP',crv:'Ed25519',x}]}, stable per root; a locally-built signed webhook verifies against the key the ROUTE served (through the handler -> real teeth)", 'api', 'common', () => withRoot(async (h, root) => {
+        const a = await h({ m: 'GET', p: '/.well-known/jwks.json', host: 'rest.fal.ai' });
+        const ab = a.body;
+        if (a.status !== 200 || ab.keys?.[0]?.kty !== 'OKP' || ab.keys[0]?.crv !== 'Ed25519' || !ab.keys[0]?.x)
+            return false;
+        const built = await buildSignedFalWebhook({ requestId: 'req_jwks', status: 'OK', payload: { a: 1 }, occurredAt: OCCURRED_AT, root });
+        const pubKey = falWebhookPublicKeyFromJwk(ab.keys[0]);
+        const verified = verifyFalWebhookSignatureWithKey(built.body, built.headers, pubKey, { now: OCCURRED_AT_EPOCH_SEC });
+        const b = await h({ m: 'GET', p: '/.well-known/jwks.json', host: 'rest.fal.ai' });
+        const stable = b.body.keys?.[0]?.x === ab.keys[0].x;
+        return verified.request_id === 'req_jwks' && stable;
+    })),
+    done('fal.webhooks.timestamp_tolerance', 'webhooks', 'reject a webhook whose |now - timestamp| exceeds the 300s tolerance; accept one within it', 'api', 'common', () => withTempRoot(async (root) => {
+        const built = await buildSignedFalWebhook({ requestId: 'req_ts', status: 'OK', payload: {}, occurredAt: OCCURRED_AT, root });
+        const stale = Math.floor(Date.parse(OCCURRED_AT) / 1000) + 301;
+        try {
+            await verifyFalWebhook(built.body, built.headers, root, { now: stale });
+            return false;
+        }
+        catch (err) {
+            if (!(err instanceof FalWebhookVerificationError))
+                return false;
+        }
+        const fresh = Math.floor(Date.parse(OCCURRED_AT) / 1000) + 100;
+        const verified = await verifyFalWebhook(built.body, built.headers, root, { now: fresh });
+        return verified.request_id === 'req_ts';
+    })),
+    done('fal.webhooks.payload_shape', 'webhooks', 'OK and ERROR webhook payload variants match the exact documented shape ({request_id,gateway_request_id,status,payload} / {...,error})', 'api', 'common', () => withTempRoot(async (root) => {
+        const ok = await buildSignedFalWebhook({ requestId: 'req_ok', gatewayRequestId: 'gw_1', status: 'OK', payload: { output: 'x' }, occurredAt: OCCURRED_AT, root });
+        const okEvent = JSON.parse(ok.body);
+        const okShape = okEvent.request_id === 'req_ok' && okEvent.gateway_request_id === 'gw_1' && okEvent.status === 'OK'
+            && JSON.stringify(okEvent.payload) === JSON.stringify({ output: 'x' }) && okEvent.error === undefined;
+        const err = await buildSignedFalWebhook({ requestId: 'req_err', status: 'ERROR', error: 'boom', occurredAt: OCCURRED_AT, root });
+        const errEvent = JSON.parse(err.body);
+        const errShape = errEvent.request_id === 'req_err' && errEvent.status === 'ERROR' && errEvent.payload === null && errEvent.error === 'boom';
+        return okShape && errShape;
+    })),
+    // ── ERRORS ────────────────────────────────────────────────────────────────────────────────
+    done('fal.errors.validation_422', 'errors', 'submit with a non-object JSON body -> 422 {detail:[{loc,msg,type}]} (FastAPI/Pydantic shape)', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/acme/widget', b: [1, 2, 3], host: 'queue.fal.run' });
+        if (r.status !== 422)
+            return false;
+        const detail = r.body.detail;
+        return Array.isArray(detail) && detail.length > 0 && Array.isArray(detail[0].loc) && typeof detail[0].msg === 'string' && typeof detail[0].type === 'string';
+    })),
+    // ── SAFETY / HONESTY ─────────────────────────────────────────────────────────────────────
+    done('fal.read_only.rejects_writes', 'safety', 'readOnly mode rejects writes with 405 but allows GET (incl. the JWKS route)', 'api', 'common', async () => {
+        const root = mkdtempSync(join(tmpdir(), 'fal-ro-'));
+        try {
+            const w = await handleFalTwinRequest({ method: 'POST', path: '/acme/widget', body: JSON.stringify({}), root, readOnly: true, host: 'queue.fal.run' });
+            const g = await handleFalTwinRequest({ method: 'GET', path: '/.well-known/jwks.json', root, readOnly: true, host: 'rest.fal.ai' });
+            return w.status === 405 && g.status === 200;
+        }
+        finally {
+            rmSync(root, { recursive: true, force: true });
+        }
+    }),
+    done('fal.unmodeled_route.404', 'safety', 'an unmodeled REST route returns a FastAPI-style 404 {detail} envelope (never a fabricated success)', 'api', 'common', () => withRoot(async (h) => {
+        const r = await h({ m: 'GET', p: '/some/totally/unknown/route', host: 'rest.fal.ai' });
+        return r.status === 404 && typeof r.body.detail === 'string';
+    })),
+    done('fal.state.kernel_persisted', 'state', 'state is kernel-folded — a request created in one call is visible (by id) in the next', 'api', 'core', () => withRoot(async (h) => {
+        const c = await h({ m: 'POST', p: '/acme/widget', b: { a: 1 }, host: 'queue.fal.run' });
+        const id = c.body.request_id;
+        // a dead twin returns {} — the id must be a REAL non-empty string first, or the final
+        // comparison is vacuous (undefined === undefined).
+        if (typeof id !== 'string' || id.length === 0)
+            return false;
+        const s = await h({ m: 'GET', p: `/acme/widget/requests/${id}/status`, host: 'queue.fal.run' });
+        return s.status === 200 && s.body.request_id === id;
+    })),
+    // ── CONFORMANCE / CONNECTOR ──────────────────────────────────────────────────────────────
+    done('fal.conformance.snapshot', 'conformance', 'conformance snapshot covers both resource types + the core queue-lifecycle contracts', 'api', 'common', () => {
+        const report = checkFalConformance();
+        return report.ok && report.endpointsChecked >= 10 && report.resourceTypesChecked === 2;
+    }),
+    done('fal.connector.sync.entrypoint', 'connector', 'syncFalFromReal pulls the CURRENT real state of explicitly-named {modelId,requestId} handles (fal has no list-requests API) into the twin; idempotent re-pull', 'connector', 'core', async () => {
+        const root = mkdtempSync(join(tmpdir(), 'fal-conn-'));
+        try {
+            const client = {
+                queue: {
+                    status: async () => ({ status: 'COMPLETED', queue_position: 0, logs: [{ message: 'done', level: 'INFO', timestamp: OCCURRED_AT }], metrics: { inference_time: 1.5 } }),
+                    result: async () => ({ output: 'real pulled output' }),
+                },
+            };
+            const handles = [{ modelId: 'acme/real-model', requestId: 'real-req-1' }];
+            const first = await syncFalFromReal(client, { root, requests: handles, occurredAt: OCCURRED_AT, budgetOptions: { root } });
+            if (first.observed !== 1 || first.deltasAppended < 1)
+                return false;
+            // a re-pull of identical state is a no-op (shadow-diff dedup) -> 0 deltas appended
+            const second = await syncFalFromReal(client, { root, requests: handles, occurredAt: OCCURRED_AT, budgetOptions: { root } });
+            if (second.deltasAppended !== 0)
+                return false;
+            // the pulled request is now visible via the twin handler (real fold, not a count)
+            const r = await handleFalTwinRequest({ method: 'GET', path: '/acme/real-model/requests/real-req-1/status', root, host: 'queue.fal.run' });
+            return r.status === 200 && r.body.status === 'COMPLETED';
+        }
+        finally {
+            rmSync(root, { recursive: true, force: true });
+        }
+    }),
+    done('fal.connector.empty_client', 'connector', 'syncFalFromReal with no client.queue / no handles observes nothing', 'connector', 'common', async () => {
+        // isolated temp root — never the process default root (a verify must not touch shared state).
+        const root = mkdtempSync(join(tmpdir(), 'fal-conn-empty-'));
+        try {
+            const result = await syncFalFromReal({}, { root, budgetOptions: { root } });
+            return result.observed === 0 && result.deltasAppended === 0;
+        }
+        finally {
+            rmSync(root, { recursive: true, force: true });
+        }
+    }),
+    // ── TODO: the rest of the fal.ai v1 surface (honest denominator) ────────────────────────
+    todo('fal.streaming.status_stream_sse', 'streaming', 'GET .../requests/{id}/status/stream — SSE token stream of status updates', 'api', 'common'),
+    todo('fal.streaming.model_stream', 'streaming', 'fal.stream() — per-model streaming inference (distinct from the queue status SSE)', 'api', 'niche'),
+    todo('fal.realtime.websocket', 'realtime', 'fal realtime WebSocket API (low-latency bidirectional model sessions)', 'api', 'niche'),
+    todo('fal.webhooks.delivery', 'webhooks', 'an injected offline deliverer actually POSTs the signed webhook to the registered URL on completion', 'api', 'common'),
+    todo('fal.webhooks.retry_policy', 'webhooks', 'delivery retry policy (15s timeout, up to 10 retries over 2h)', 'api', 'niche'),
+    todo('fal.webhooks.error_payload_delivery', 'webhooks', 'a FAILED request delivers the ERROR-status webhook payload variant end-to-end', 'api', 'common'),
+    todo('fal.webhooks.submit_param_validation', 'webhooks', '?fal_webhook= / webhook_url submit-time param validation (malformed URL -> 422)', 'api', 'niche'),
+    todo('fal.queue.cancelled_terminal_state', 'queue', "the real terminal state a successful cancellation settles into (fal's documented status enum has no CANCELLED member)", 'api', 'common'),
+    todo('fal.queue.response_long_poll', 'queue', 'pre-completion long-poll behavior of the result endpoint (this twin settles instantly on status polls instead)', 'api', 'niche'),
+    todo('fal.queue.response_alias_route', 'queue', 'the /response alias route as its OWN claimed capability (today it is served but only exercised via fal.queue.response)', 'api', 'niche'),
+    todo('fal.queue.failed_state', 'queue', 'a deterministic, input-triggered FAILED status + error/error_type fields', 'api', 'common'),
+    todo('fal.queue.submit_status_code_parity', 'queue', 'confirm the real submit response status code against a live account (modeled as 200; doc-unverified)', 'api', 'niche'),
+    todo('fal.queue.priority_hint', 'queue', 'a priority/queue-jump hint on submit', 'api', 'niche'),
+    todo('fal.sync.timeout_504', 'sync', "the fal.run sync surface's documented 504 user-timeout behavior + headers", 'api', 'niche'),
+    todo('fal.sync.request_id_header', 'sync', "a request-id response header on the sync surface (parity with the queue envelope's request_id field)", 'api', 'niche'),
+    todo('fal.storage.initiate_upload', 'storage', 'fal storage: initiate-upload handshake for large inputs', 'api', 'common'),
+    todo('fal.storage.file_url_shape', 'storage', 'the fal.media CDN file-url shape returned by storage uploads', 'api', 'niche'),
+    todo('fal.storage.client_auto_upload', 'storage', "the fal-js client's automatic large-input-to-storage-URL substitution", 'api', 'niche'),
+    todo('fal.apps.unknown_model_404', 'apps', 'submitting to a genuinely unknown/unregistered model_id — a distinct 404 shape from an unknown request_id', 'api', 'common'),
+    todo('fal.apps.per_model_openapi', 'apps', 'GET /{model_id}/openapi.json — the per-model input/output schema document', 'api', 'niche'),
+    todo('fal.apps.registry_fixture', 'apps', 'a small fixture registry of real, named fal model ids (for realistic model_id enumeration in tests)', 'api', 'niche'),
+    todo('fal.auth.key_401_parity', 'auth', 'missing/invalid `Authorization: Key $FAL_KEY` -> 401 parity', 'api', 'common'),
+    todo('fal.auth.key_format', 'auth', 'FAL_KEY format validation (the documented `id:secret` shape)', 'api', 'niche'),
+    todo('fal.errors.detail_string_variant', 'errors', 'the plain-string `detail` error variant (vs. the structured array form) on non-validation errors', 'api', 'niche'),
+    todo('fal.errors.429_rate_limit', 'errors', 'rate limit (429) deterministic opt-in trigger + Retry-After envelope', 'api', 'niche'),
+    todo('fal.errors.403_budget', 'errors', 'account-budget-exceeded 403 envelope', 'api', 'niche'),
+    todo('fal.connector.push', 'connector', 'push a locally-created request against a real fal account (fal has no such write API for pre-existing requests today — see README ## Coverage)', 'connector', 'common'),
+    todo('fal.connector.pull_storage', 'connector', 'connector: pull uploaded storage assets from the real account', 'connector', 'common'),
+    todo('fal.fixtures.seed', 'connector', 'seed a small library of realistic model ids + inputs from fixtures', 'connector', 'niche'),
+];
+export const FAL_AREAS = [
+    'queue', 'sync', 'streaming', 'realtime', 'webhooks', 'storage', 'apps', 'proxy', 'auth',
+    'errors', 'connector', 'conformance', 'safety', 'state',
+];
+// NOTE: deliberately NO 'pagination' area — fal has no list endpoints in its real surface (no
+// GET /requests, no GET /models — every route is either handle-scoped or a bare model_id path),
+// so there is nothing to paginate. Recorded here rather than silently omitted.
+export async function falCapabilities() {
+    return checkCapabilities('fal', FAL_CAPABILITIES);
+}

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

@@ -0,0 +1,7 @@
+export type FalConformanceReport = {
+    ok: boolean;
+    endpointsChecked: number;
+    resourceTypesChecked: number;
+    violations: string[];
+};
+export declare function checkFalConformance(): FalConformanceReport;

package/dist/src/fal-conformance.js

@@ -0,0 +1,38 @@
+// fal conformance (dev-only; lazy-imported by the CLI, NEVER from index.ts/runtime — E2).
+// Checks the twin's endpoint/resource inventory against itself — SELF-REFERENTIAL, the same
+// pattern replicate/elevenlabs/polar use (docs/contributing/conformance.md's "2 spec" discussion): it does not
+// diff against a captured vendor document, it asserts the pack's own declared snapshot is
+// internally consistent (every resource type has a route, the core lifecycle routes exist).
+import { falTwinSnapshot, FAL_RESOURCE_TYPES } from "./fal-twin.js";
+export function checkFalConformance() {
+    const snapshot = falTwinSnapshot();
+    const violations = [];
+    // Every declared resource type must have at least one implemented endpoint touching it.
+    // `signing_key` has no REST path of its own — it's served (lazily materialized) at the JWKS
+    // endpoint, so it maps to the 'jwks' stem instead of its own name.
+    const stemFor = {
+        request: '/requests',
+        signing_key: 'jwks',
+    };
+    for (const type of FAL_RESOURCE_TYPES) {
+        const stem = stemFor[type];
+        if (!stem || !snapshot.implementedEndpoints.some((e) => e.includes(stem))) {
+            violations.push(`resource type '${type}' has no implemented endpoint`);
+        }
+    }
+    // The core queue-lifecycle endpoints must be present in the protocol surface.
+    if (!snapshot.implementedEndpoints.some((e) => e.startsWith('POST queue.fal.run')))
+        violations.push('missing queue submit endpoint');
+    if (!snapshot.implementedEndpoints.some((e) => e.startsWith('POST fal.run')))
+        violations.push('missing sync submit endpoint');
+    if (!snapshot.implementedEndpoints.some((e) => e.includes('/cancel')))
+        violations.push('missing cancel endpoint');
+    if (!snapshot.implementedEndpoints.some((e) => e.includes('jwks')))
+        violations.push('missing JWKS endpoint');
+    return {
+        ok: violations.length === 0,
+        endpointsChecked: snapshot.implementedEndpoints.length,
+        resourceTypesChecked: snapshot.resourceTypes.length,
+        violations,
+    };
+}

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

@@ -0,0 +1,58 @@
+import type { ObservedResource } from '@volter/world-core';
+import { type FalBudgetedOptions } from './fal-budget.js';
+export type { FalBudgetedOptions };
+export type FalRequestHandle = {
+    modelId: string;
+    requestId: string;
+};
+export type FalRealQueueLog = {
+    message: string;
+    level?: string;
+    timestamp?: string;
+};
+export type FalRealQueueStatus = {
+    status: string;
+    queue_position?: number | null;
+    logs?: FalRealQueueLog[];
+    metrics?: {
+        inference_time?: number | null;
+    };
+    error?: string | null;
+    error_type?: string | null;
+};
+export interface FalLikeClient {
+    queue?: {
+        status: (opts: {
+            endpointId: string;
+            requestId: string;
+            logs?: boolean;
+        }) => Promise<FalRealQueueStatus>;
+        result: (opts: {
+            endpointId: string;
+            requestId: string;
+        }) => Promise<unknown>;
+    };
+}
+/** Pure mapper (real fal queue-status/result → ObservedResource) — never touches a client, so the
+ *  mutation-test connector-seam sweep (which sabotages every export matching the
+ *  sync-or-push-or-pull-or-fullSync naming convention) leaves this real, per the pack convention
+ *  (`replicate-connector.ts`'s `mapModel`). */
+export declare function mapQueueRequest(handle: FalRequestHandle, status: FalRealQueueStatus, result: unknown): ObservedResource;
+/** Pull the CURRENT real state of every named handle. A handle with no `client.queue` (or an
+ *  empty handle list) observes nothing — there is nothing to enumerate without a handle. */
+export declare function pullFalRequests(rawClient: FalLikeClient, handles: FalRequestHandle[], opts?: FalBudgetedOptions): Promise<ObservedResource[]>;
+/**
+ * D7 entry point: pull the current real state of every explicitly-named `{modelId, requestId}`
+ * handle and OBSERVE it as ONE batch (the kernel diffs against the root's tree). No type is named
+ * `complete`: the pull reads only the handles it was given, never an enumeration, so a request it
+ * did not name says nothing about whether it still exists. Returns `{observed, deltasAppended}` —
+ * a re-pull of identical state appends ZERO deltas.
+ */
+export declare function syncFalFromReal(rawClient: FalLikeClient, opts?: {
+    root?: string;
+    occurredAt?: string;
+    requests?: FalRequestHandle[];
+} & FalBudgetedOptions): Promise<{
+    observed: number;
+    deltasAppended: number;
+}>;

package/dist/src/fal-connector.js

@@ -0,0 +1,91 @@
+// fal CONNECTOR — the live-vendor pull path that gives the fal twin the "git for SaaS"
+// lifecycle over an INJECTED client (the auth boundary).
+//
+// PULL (real → twin) is deliberately HANDLE-DRIVEN, not list-driven: fal has NO API to list
+// outstanding/past queue requests (grounded — fal.ai/docs/model-endpoints/queue documents only
+// per-request status/result/cancel by an already-known `{model_id, request_id}` handle; there is
+// no `GET /requests` enumeration endpoint anywhere in the surface). The real fal-js client's own
+// `fal.queue.status({...})` / `fal.queue.result({...})` methods are themselves handle-scoped for
+// the same reason. So a caller of this connector must already know which requests it cares about
+// (e.g. from its own application database of request ids it previously submitted) — the connector
+// pulls the CURRENT real state of each named handle and OBSERVES it (the kernel diffs each
+// resource against the root's tree and folds only what changed, so a re-pull of identical state
+// appends nothing).
+//
+// The vendor I/O is an INJECTED client interface (`FalLikeClient`): a fake in tests, the real
+// `@fal-ai/client` singleton in prod. The pack imports NO SDK and holds NO key.
+import { observeResources } from '@volter/world-core';
+//
+// ── The client-side RATE BUDGET is not optional here ────────────────────────────────────────
+// fal publishes CONCURRENCY limits (2 concurrent requests on a new account) and documents that
+// IN_QUEUE requests do not count toward them — so queue.status / queue.result polling, which is all
+// this connector does, has no published ceiling at all.
+// Every entrypoint below GUARDS the injected client before touching it (`guardFalClient`, which is
+// idempotent — a caller who already wrapped is not double-charged, a caller who forgot is protected
+// anyway); there is deliberately no option that turns the budget off. See fal-budget.ts.
+import { falBudgetOf, guardFalClient } from "./fal-budget.js";
+const SERVICE = 'fal';
+function kid(type, id) {
+    return `${type}:${id}`;
+}
+/** Pure mapper (real fal queue-status/result → ObservedResource) — never touches a client, so the
+ *  mutation-test connector-seam sweep (which sabotages every export matching the
+ *  sync-or-push-or-pull-or-fullSync naming convention) leaves this real, per the pack convention
+ *  (`replicate-connector.ts`'s `mapModel`). */
+export function mapQueueRequest(handle, status, result) {
+    return {
+        type: 'request',
+        id: kid('request', handle.requestId),
+        fields: {
+            model_id: handle.modelId,
+            status: status.status,
+            queue_position: status.queue_position ?? null,
+            logs: status.logs ?? [],
+            output: status.status === 'COMPLETED' ? (result ?? null) : null,
+            error: status.error ?? null,
+            error_type: status.error_type ?? null,
+            inference_time: status.metrics?.inference_time ?? null,
+            created_at: null,
+            completed_at: null,
+            webhook_url: null,
+            poll_count: 0,
+        },
+    };
+}
+/** Pull the CURRENT real state of every named handle. A handle with no `client.queue` (or an
+ *  empty handle list) observes nothing — there is nothing to enumerate without a handle. */
+export async function pullFalRequests(rawClient, handles, opts = {}) {
+    const client = guardFalClient(rawClient, opts);
+    if (!client.queue || handles.length === 0)
+        return [];
+    const out = [];
+    for (const handle of handles) {
+        const status = await client.queue.status({ endpointId: handle.modelId, requestId: handle.requestId, logs: true });
+        let result = null;
+        if (status.status === 'COMPLETED') {
+            result = await client.queue.result({ endpointId: handle.modelId, requestId: handle.requestId });
+        }
+        out.push(mapQueueRequest(handle, status, result));
+    }
+    return out;
+}
+/**
+ * D7 entry point: pull the current real state of every explicitly-named `{modelId, requestId}`
+ * handle and OBSERVE it as ONE batch (the kernel diffs against the root's tree). No type is named
+ * `complete`: the pull reads only the handles it was given, never an enumeration, so a request it
+ * did not name says nothing about whether it still exists. Returns `{observed, deltasAppended}` —
+ * a re-pull of identical state appends ZERO deltas.
+ */
+export async function syncFalFromReal(rawClient, opts = {}) {
+    // Guard ONCE here and hand the guarded client down: the per-handle loop below is unbounded in
+    // handle count, so this is the entrypoint that must be unable to run unbudgeted.
+    const client = guardFalClient(rawClient, falBudgetOf(opts));
+    const occurredAt = opts.occurredAt ?? new Date().toISOString();
+    const resources = await pullFalRequests(client, opts.requests ?? []);
+    const report = observeResources(SERVICE, resources, {
+        ...(opts.root !== undefined ? { root: opts.root } : {}),
+        at: occurredAt,
+        batch: `obs:${SERVICE}:${occurredAt}`,
+    });
+    return { observed: report.observed, deltasAppended: report.appended + report.removed };
+}