@volter/twin-fal 0.1.0

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

@@ -0,0 +1,60 @@
+export type FalWebhookEvent = {
+    request_id: string;
+    gateway_request_id: string;
+    status: 'OK' | 'ERROR';
+    payload: unknown;
+    error?: string;
+    payload_error?: string;
+};
+export declare class FalWebhookVerificationError extends Error {
+    constructor(message: string);
+}
+/** The JWKS document served at GET /.well-known/jwks.json — stable per root, across processes. */
+export declare function falJwks(root?: string): Promise<{
+    keys: Array<{
+        kty: 'OKP';
+        crv: 'Ed25519';
+        x: string;
+    }>;
+}>;
+/** Reconstruct a public key from a served JWKS entry — used to verify a signature using ONLY
+ *  what the JWKS *endpoint* returned (not a fresh local re-derivation from `root`), so a
+ *  signature-verification capability that routes through this has real teeth against a
+ *  sabotaged handler (build spec §3: "through handler → teeth"). */
+export declare function falWebhookPublicKeyFromJwk(jwk: {
+    x: string;
+}): import('node:crypto').KeyObject;
+/** Compute the hex ed25519 signature for a webhook delivery (real crypto, not a stub — a real
+ *  Ed25519/JWKS verifier accepts this unchanged). */
+export declare function computeFalWebhookSignature(requestId: string, userId: string, timestamp: number, rawBody: string, root?: string): Promise<string>;
+/** Verify a webhook delivery against a caller-provided public key (e.g. one recovered from a
+ *  served JWKS document via `falWebhookPublicKeyFromJwk`). Throws `FalWebhookVerificationError`
+ *  on any missing header, stale timestamp, or signature mismatch. */
+export declare function verifyFalWebhookSignatureWithKey(rawBody: string, headers: Record<string, string>, publicKey: import('node:crypto').KeyObject, opts?: {
+    tolerance?: number;
+    now?: number;
+}): FalWebhookEvent;
+/** Verify a webhook delivery against the root's persisted keypair directly (pure local crypto —
+ *  does not touch the twin handler/JWKS route at all). */
+export declare function verifyFalWebhook(rawBody: string, headers: Record<string, string>, root?: string, opts?: {
+    tolerance?: number;
+    now?: number;
+}): Promise<FalWebhookEvent>;
+/**
+ * Build a SIGNED webhook delivery for a completed (or failed) request: the fal webhook payload +
+ * the real ed25519-signed X-Fal-Webhook-* headers. Deterministic + offline.
+ */
+export declare function buildSignedFalWebhook(args: {
+    requestId: string;
+    userId?: string;
+    gatewayRequestId?: string;
+    status: 'OK' | 'ERROR';
+    payload?: unknown;
+    error?: string;
+    occurredAt: string;
+    root?: string;
+}): Promise<{
+    headers: Record<string, string>;
+    body: string;
+    event: FalWebhookEvent;
+}>;

package/dist/src/fal-webhooks.js

@@ -0,0 +1,202 @@
+// fal.ai webhooks — REAL ed25519-signed delivery + JWKS, written FRESH for this pack (the build
+// spec is explicit: do NOT port replicate-webhooks.ts, which is Standard-Webhooks HMAC — fal uses
+// a completely different, asymmetric scheme).
+//
+// GROUNDED (2026-07-09, read-only) from fal.ai/docs/model-endpoints/webhooks:
+//   - Four request headers on every webhook delivery: `X-Fal-Webhook-Request-Id`,
+//     `X-Fal-Webhook-User-Id`, `X-Fal-Webhook-Timestamp` (unix seconds), `X-Fal-Webhook-Signature`
+//     (HEX-encoded, not base64 — unlike replicate's Standard-Webhooks base64 HMAC).
+//   - Signed message: `${request_id}\n${user_id}\n${timestamp}\n${sha256hex(raw_body)}` — four
+//     newline-joined fields, the last being a SHA-256 hex digest of the raw request body (not the
+//     body itself).
+//   - Public keys are served as a JWKS document at `https://rest.fal.ai/.well-known/jwks.json`
+//     (NOT rest.alpha.fal.ai) — `{keys: [{kty:'OKP', crv:'Ed25519', x: <base64url raw pubkey>}]}`
+//     (RFC 8037 OKP/Ed25519 JWK — modeled per the RFC's standard shape; the doc confirms the
+//     endpoint + field names, not byte-for-byte against a captured live document, so the exact
+//     document shape carries the same doc-UNVERIFIED caveat routine capture-verify would close).
+//   - ±300s (5 minute) timestamp leeway.
+//   - Payload shape: `{request_id, gateway_request_id, status: 'OK'|'ERROR', payload, error?,
+//     payload_error?}`.
+//   - Retry policy: 15s per-attempt timeout, up to 10 retries over a 2h window (`todo` —
+//     `fal.webhooks.retry_policy` — this pack signs/verifies deliveries; it does not implement
+//     the delivery/retry loop itself, the same shape replicate's `webhooks.delivery` todo takes).
+//
+// ENTROPY-BORN, PERSISTED KEYPAIR (the googleoauth-jwt.ts `ensureKeypair` precedent). The ed25519
+// SEED is 32 bytes of REAL entropy, generated ONCE per root and PERSISTED as twin state — the
+// `signing_key` resource FAL_RESOURCE_TYPES already declares, folded on first touch through the
+// kernel action log (so it rides snapshots/hydrate/flush like every other fact this twin holds,
+// and no `node:fs` is on the serve path). Every later read derives the keypair from that stored
+// seed: the seed is wrapped in the fixed PKCS8 DER prefix for an Ed25519 private key (RFC 8410 —
+// `302e020100300506032b657004220420` + 32-byte seed = 48 bytes total) and imported via
+// `crypto.createPrivateKey`, so signing and the served JWKS are always the SAME key and both
+// survive a process restart.
+//
+// This is the runtime contract's ONE NAMED EXCEPTION to R9 (keying material generated once per
+// root and persisted, exactly like googleoauth's RSA pair): same-root byte-identical, cross-root
+// divergent BY CONSTRUCTION. The reads that serve it — `/.well-known/jwks.json` — therefore stay
+// out of this pack's replay, which gate.ts states. The seed is never derived from the root PATH:
+// a key computed from where a world happens to sit is a key the environment owns, and it moves
+// with the directory instead of with the state.
+//
+// `node:crypto` is required LAZILY (server-only), same convention as replicate-webhooks.ts, so
+// this module stays browser-bundle safe.
+import { applyTwinWriteAtomic, projectResources, nodeBuiltin } from '@volter/world-core';
+function nodeCrypto() {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    return nodeBuiltin('node:crypto');
+}
+const ED25519_PKCS8_PREFIX_HEX = '302e020100300506032b657004220420';
+// The fixed 12-byte ASN.1 header every Ed25519 SPKI (public-key) DER encoding starts with (RFC
+// 8410) — followed by exactly 32 raw public-key bytes (44 bytes total). Slicing it off recovers
+// the raw key JWKS wants in its `x` field.
+const ED25519_SPKI_HEADER_LEN = 12;
+export class FalWebhookVerificationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'FalWebhookVerificationError';
+    }
+}
+const SERVICE = 'fal';
+// The seed is stored as the pack's declared `signing_key` resource — the SAME substrate every
+// other fal fact uses, no parallel side-store (D1). Subject ids are type-prefixed exactly like
+// fal-twin.ts's `kid()`; `_`-prefixed fields are twin-internal and never served (fal-twin.ts's
+// `view()` strips them, and no route projects this type at all).
+const SIGNING_KEY_TYPE = 'signing_key';
+const SIGNING_KEY_SUBJECT = 'signing_key:webhook';
+const SEED_BYTES = 32; // ed25519's seed length, exactly
+function storedSeed(resources) {
+    const row = resources.find((r) => r.type === SIGNING_KEY_TYPE && r.id === SIGNING_KEY_SUBJECT);
+    const seed = row?.['_seed'];
+    return typeof seed === 'string' && seed.length > 0 ? seed : undefined;
+}
+/**
+ * The base64 ed25519 SEED for `root` — generated with real entropy on FIRST use and persisted,
+ * stable forever after (across calls AND across processes). The decide-and-append runs inside the
+ * kernel's own action lock (`applyTwinWriteAtomic`), so two processes racing a first use agree on
+ * ONE seed rather than each signing with a seed the other's state does not hold.
+ */
+async function ensureFalSigningSeed(root) {
+    const fast = storedSeed(projectResources(SERVICE, root));
+    if (fast)
+        return fast;
+    const { value } = await applyTwinWriteAtomic(SERVICE, (resources) => {
+        const existing = storedSeed(resources);
+        if (existing)
+            return { kind: 'skip', value: existing };
+        const seed = nodeCrypto().randomBytes(SEED_BYTES).toString('base64');
+        return {
+            kind: 'write',
+            value: seed,
+            write: {
+                operation: 'signing_key.create',
+                subjectType: SIGNING_KEY_TYPE,
+                subjectId: SIGNING_KEY_SUBJECT,
+                fields: { _seed: seed },
+                actor: { kind: 'system' },
+            },
+        };
+    }, root);
+    return value;
+}
+/** The per-root ed25519 keypair, derived from the PERSISTED seed. */
+async function falSigningKey(root) {
+    const crypto = nodeCrypto();
+    const seed = Buffer.from(await ensureFalSigningSeed(root), 'base64');
+    if (seed.length !== SEED_BYTES)
+        throw new Error(`fal signing key: persisted seed is ${seed.length} bytes, expected ${SEED_BYTES}`);
+    const der = Buffer.concat([Buffer.from(ED25519_PKCS8_PREFIX_HEX, 'hex'), seed]);
+    const privateKey = crypto.createPrivateKey({ key: der, format: 'der', type: 'pkcs8' });
+    const publicKey = crypto.createPublicKey(privateKey);
+    return { privateKey, publicKey };
+}
+function rawPublicKeyBytes(publicKey) {
+    const spki = publicKey.export({ format: 'der', type: 'spki' });
+    return spki.subarray(ED25519_SPKI_HEADER_LEN);
+}
+/** The JWKS document served at GET /.well-known/jwks.json — stable per root, across processes. */
+export async function falJwks(root) {
+    const { publicKey } = await falSigningKey(root);
+    const x = rawPublicKeyBytes(publicKey).toString('base64url');
+    return { keys: [{ kty: 'OKP', crv: 'Ed25519', x }] };
+}
+/** Reconstruct a public key from a served JWKS entry — used to verify a signature using ONLY
+ *  what the JWKS *endpoint* returned (not a fresh local re-derivation from `root`), so a
+ *  signature-verification capability that routes through this has real teeth against a
+ *  sabotaged handler (build spec §3: "through handler → teeth"). */
+export function falWebhookPublicKeyFromJwk(jwk) {
+    return nodeCrypto().createPublicKey({ key: { kty: 'OKP', crv: 'Ed25519', x: jwk.x }, format: 'jwk' });
+}
+/** Build the exact signed message fal signs: id \n user \n ts \n sha256hex(body). */
+function signingMessage(requestId, userId, timestamp, rawBody) {
+    const bodyHash = nodeCrypto().createHash('sha256').update(rawBody, 'utf8').digest('hex');
+    return `${requestId}\n${userId}\n${timestamp}\n${bodyHash}`;
+}
+/** Compute the hex ed25519 signature for a webhook delivery (real crypto, not a stub — a real
+ *  Ed25519/JWKS verifier accepts this unchanged). */
+export async function computeFalWebhookSignature(requestId, userId, timestamp, rawBody, root) {
+    const { privateKey } = await falSigningKey(root);
+    const message = signingMessage(requestId, userId, timestamp, rawBody);
+    // Node's `crypto.sign(algorithm, data, key)` takes `null` for the one-shot Ed25519 signing
+    // algorithm (Ed25519 has no separate digest step — verified against Node's own crypto docs).
+    return nodeCrypto().sign(null, Buffer.from(message, 'utf8'), privateKey).toString('hex');
+}
+function verifyRaw(rawBody, headers, publicKey, opts) {
+    const lower = {};
+    for (const [k, v] of Object.entries(headers))
+        lower[k.toLowerCase()] = v;
+    const requestId = lower['x-fal-webhook-request-id'];
+    const userId = lower['x-fal-webhook-user-id'];
+    const ts = Number(lower['x-fal-webhook-timestamp']);
+    const sigHex = lower['x-fal-webhook-signature'];
+    if (!requestId || !userId || !sigHex || !Number.isFinite(ts)) {
+        throw new FalWebhookVerificationError('Missing required webhook headers (X-Fal-Webhook-Request-Id / X-Fal-Webhook-User-Id / X-Fal-Webhook-Timestamp / X-Fal-Webhook-Signature).');
+    }
+    const tolerance = opts.tolerance ?? 300;
+    const now = opts.now ?? Math.floor(Date.now() / 1000);
+    if (Math.abs(now - ts) > tolerance) {
+        throw new FalWebhookVerificationError(`Webhook timestamp outside the ${tolerance}s tolerance.`);
+    }
+    const message = signingMessage(requestId, userId, ts, rawBody);
+    let sigBuf;
+    try {
+        sigBuf = Buffer.from(sigHex, 'hex');
+    }
+    catch {
+        throw new FalWebhookVerificationError('Malformed hex signature.');
+    }
+    const ok = sigBuf.length > 0 && nodeCrypto().verify(null, Buffer.from(message, 'utf8'), publicKey, sigBuf);
+    if (!ok)
+        throw new FalWebhookVerificationError('Signature verification failed.');
+    return JSON.parse(rawBody);
+}
+/** Verify a webhook delivery against a caller-provided public key (e.g. one recovered from a
+ *  served JWKS document via `falWebhookPublicKeyFromJwk`). Throws `FalWebhookVerificationError`
+ *  on any missing header, stale timestamp, or signature mismatch. */
+export function verifyFalWebhookSignatureWithKey(rawBody, headers, publicKey, opts = {}) {
+    return verifyRaw(rawBody, headers, publicKey, opts);
+}
+/** Verify a webhook delivery against the root's persisted keypair directly (pure local crypto —
+ *  does not touch the twin handler/JWKS route at all). */
+export async function verifyFalWebhook(rawBody, headers, root, opts = {}) {
+    const { publicKey } = await falSigningKey(root);
+    return verifyRaw(rawBody, headers, publicKey, opts);
+}
+/**
+ * Build a SIGNED webhook delivery for a completed (or failed) request: the fal webhook payload +
+ * the real ed25519-signed X-Fal-Webhook-* headers. Deterministic + offline.
+ */
+export async function buildSignedFalWebhook(args) {
+    const userId = args.userId ?? 'twin-user';
+    const ts = Math.floor(Date.parse(args.occurredAt) / 1000);
+    const event = args.status === 'OK'
+        ? { request_id: args.requestId, gateway_request_id: args.gatewayRequestId ?? args.requestId, status: 'OK', payload: args.payload ?? null }
+        : { request_id: args.requestId, gateway_request_id: args.gatewayRequestId ?? args.requestId, status: 'ERROR', payload: null, error: args.error ?? 'unknown error' };
+    const body = JSON.stringify(event);
+    const headers = {
+        'x-fal-webhook-request-id': args.requestId,
+        'x-fal-webhook-user-id': userId,
+        'x-fal-webhook-timestamp': String(ts),
+        'x-fal-webhook-signature': await computeFalWebhookSignature(args.requestId, userId, ts, body, args.root),
+    };
+    return { headers, body, event };
+}

package/dist/src/index.d.ts

@@ -0,0 +1,13 @@
+export { handleFalTwinRequest, routeFalSurface, falTwinSnapshot, FAL_RESOURCE_TYPES, } from './fal-twin.js';
+export type { FalRequest, FalResponse, FalResourceType, FalSurface, FalTwinSnapshot, } from './fal-twin.js';
+export { createFalTwinFetch, createFalTwinServer, type FalTwinFetchOptions } from './fal-server.js';
+export { canonicalInputText, createFalScenarioEngine, falScenarioAdapter, loadFalScenarioDocument } from './fal-scenario.js';
+export type { FalScenarioEngine, FalScenarioRequest, FalScenarioRespond } from './fal-scenario.js';
+export { mapQueueRequest, pullFalRequests, syncFalFromReal, } from './fal-connector.js';
+export type { FalLikeClient, FalRequestHandle, FalRealQueueStatus, FalRealQueueLog, FalBudgetedOptions } from './fal-connector.js';
+export { FAL_BUDGETED_METHODS, FAL_BUDGET_CEILING, FAL_BUDGET_MAX_RETRY_AFTER_S, FAL_BUDGET_WINDOW_MS, FAL_CALL_WEIGHTS, FAL_RATE_BUDGET, FalBudget, FalBudgetError, falBudgetPath, falCallWeight, falClientBudget, guardFalClient, } from './fal-budget.js';
+export type { FalBudgetErrorKind, FalBudgetOptions, FalBudgetReservation, FalBudgetSnapshot } from './fal-budget.js';
+export { falJwks, falWebhookPublicKeyFromJwk, computeFalWebhookSignature, verifyFalWebhook, verifyFalWebhookSignatureWithKey, buildSignedFalWebhook, FalWebhookVerificationError, } from './fal-webhooks.js';
+export type { FalWebhookEvent } from './fal-webhooks.js';
+import type { TwinPack } from '@volter/world-core';
+export declare const pack: TwinPack;

package/dist/src/index.js

@@ -0,0 +1,55 @@
+// @volter/twin-fal — the fal.ai (fal.run / queue.fal.run) model-inference queue-lifecycle twin,
+// built on the shared @volter/world-core kernel. REST transport over the queue.fal.run / fal.run /
+// rest.fal.ai host-split shapes; state lives entirely in the kernel action log (no side-store).
+// Queue lifecycle (submit → status polls with logs → response → cancel), the synchronous
+// `fal.run` variant, host-split surface routing (incl. the real fal-js `x-fal-target-url` proxy
+// protocol), and ed25519-signed webhooks + JWKS.
+//
+// THE GENERATIVE STUB: a request's output is a clearly-labeled DETERMINISTIC stub
+// (`[twin-stub:fal:…]`) derived from hash(model_id, input), while the protocol envelope (status
+// machine, queue_position, logs, urls, metrics) is faithful. The stub is also the ONE thing a
+// scenario handler may replace: a world
+// dir's handlers/fal.json scripts what a submitted request settles to, run by the ONE kernel
+// engine through this pack's adapter (fal-scenario.ts) and inspectable at GET /twin/scenario.
+// (Conformance/capability tooling lives in @volter/world-tooling, a dev dependency — NOT shipped.)
+export { handleFalTwinRequest, routeFalSurface, falTwinSnapshot, FAL_RESOURCE_TYPES, } from "./fal-twin.js";
+export { createFalTwinFetch, createFalTwinServer } from "./fal-server.js";
+// The pack's HALF of the scenario system (the grammar is the kernel's ONE engine). Exported so a
+// test can build an engine and `use()` handlers in-process, and so the fetch adapter can mount it.
+export { canonicalInputText, createFalScenarioEngine, falScenarioAdapter, loadFalScenarioDocument } from "./fal-scenario.js";
+export { mapQueueRequest, pullFalRequests, syncFalFromReal, } from "./fal-connector.js";
+// The client-side rate budget — the fail-closed backstop every live call goes through. The
+// MECHANISM is the kernel's shared, vendor-agnostic `RateBudget`; what lives here is this vendor's
+// DECLARATION (window/ceiling/per-method weights) plus `guardFalClient`, the choke point the
+// connector entrypoints apply unconditionally. Exported so an operator can inspect spend
+// (`snapshot`) and a caller can catch `FalBudgetError` by type; there is deliberately no export
+// that disables the guard.
+export { FAL_BUDGETED_METHODS, FAL_BUDGET_CEILING, FAL_BUDGET_MAX_RETRY_AFTER_S, FAL_BUDGET_WINDOW_MS, FAL_CALL_WEIGHTS, FAL_RATE_BUDGET, FalBudget, FalBudgetError, falBudgetPath, falCallWeight, falClientBudget, guardFalClient, } from "./fal-budget.js";
+export { falJwks, falWebhookPublicKeyFromJwk, computeFalWebhookSignature, verifyFalWebhook, verifyFalWebhookSignatureWithKey, buildSignedFalWebhook, FalWebhookVerificationError, } from "./fal-webhooks.js";
+import { FAL_RATE_BUDGET as RATE_BUDGET } from "./fal-budget.js";
+export const pack = {
+    // The SAME object fal-budget.ts declares at module load — one source of truth, so registering
+    // the pack and importing the connector can never arm two different ceilings.
+    rateBudget: RATE_BUDGET,
+    vendor: 'fal',
+    transport: 'rest',
+    archetype: 'generative',
+    bin: 'world-fal',
+    resources: ['request', 'signing_key'],
+    specSource: 'fal-conformance.ts (self-referential endpoint/resource inventory) — grounded read-only against fal.ai/docs/model-endpoints/{queue,webhooks} and the fal-js client source (github.com/fal-ai/fal-js) fetched during the build; see spec-sources.json.',
+    description: 'fal.ai model-inference queue-lifecycle twin — submit/status/response/cancel on queue.fal.run, the synchronous fal.run variant, host-split surface routing (incl. the real fal-js x-fal-target-url proxy protocol), and ed25519-signed webhooks + JWKS. Request output is a deterministic [twin-stub] value (no GPU/model weights) with a faithful protocol envelope. Kernel-backed.',
+    browserRouting: { apiPathPrefix: '/', loaderHost: 'https://queue.fal.run' },
+    // INTERCEPTION RULING — hostsNone, the pack's own home for it: host-split surface (fal.run /
+    // queue.fal.run) with no injector entry grounded yet — worlds wire the twin via the client's
+    // explicit endpoint config; a visible gap until its hosts are grounded here.
+    hostsNone: "host-split surface (fal.run / queue.fal.run) with no injector entry grounded yet — worlds wire the twin via the client's explicit endpoint config; a visible gap until its hosts are grounded here",
+    // Adoption, moved off the central maps unchanged (descriptor-first back-migration, adding-a-twin.md §3,
+    // 2026-08-31).
+    adoption: {
+        // Both official fal.ai distributions: the API client and the serverless framework.
+        pypi: ['fal-client', 'fal'],
+        sdks: ['@fal-ai/client', '@fal-ai/serverless-client'],
+        scopes: ['@fal-ai/'],
+        envStems: ['FAL'],
+    },
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@volter/twin-fal",
+  "version": "0.1.0",
+  "description": "Local fal.ai twin for the model-inference queue lifecycle (submit/status/response/cancel on queue.fal.run, the sync fal.run variant, host-split routing, ed25519-signed webhooks) built on @volter/world-core.",
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "!**/*.test.ts",
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin.git",
+    "directory": "packages/twin/fal"
+  },
+  "homepage": "https://github.com/volter-ai/twin/tree/main/packages/twin/fal#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "world-fal": "dist/src/cli.js"
+  },
+  "scripts": {
+    "test": "bun test src/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "node ../../../scripts/publish/build.mjs",
+    "prepack": "node ../../../scripts/publish/prepare-publish.mjs prepack",
+    "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
+  },
+  "peerDependencies": {
+    "@volter/world-core": "2.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.20",
+    "@types/node": "^24.0.0",
+    "@volter/world-core": "2.0.0",
+    "@volter/world-tooling": "0.1.0",
+    "@fal-ai/client": "^1.10.1",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=22.3"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+// world-fal CLI: serve the KERNEL-BACKED Fal API twin, or run conformance. State
+// lives in the @volter/world-core action log (no in-memory side-store). Conformance is dev-only +
+// lazy-imported so the bin runs without @volter/world-tooling (E2).
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { createFalTwinServer } from './fal-server.ts';
+
+const [cmd, ...rest] = process.argv.slice(2);
+const port = Number(optionValue(rest, '--port', String(process.env.PORT ?? '0'))) || undefined;
+const root = optionValue(rest, '--root') || undefined;
+const scenario = optionValue(rest, '--scenario') || undefined;
+const readOnly = hasFlag(rest, '--read-only'); // a twin accepts writes unless started read-only
+
+if (cmd === 'serve' || cmd === undefined) {
+  const s = await createFalTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}), ...(scenario ? { scenarioPath: scenario } : {}) });
+  process.stdout.write(`fal twin (model-inference queue lifecycle: submit/status/response/cancel, host-split, ed25519 webhooks)${readOnly ? ' [read-only]' : ''}${scenario ? ' [scenario]' : ''} at http://127.0.0.1:${s.port}\n`);
+  await keepProcessAlive();
+} else if (cmd === 'conformance') {
+  const { checkFalConformance } = await import('./fal-conformance.ts');
+  const report = checkFalConformance();
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  if (!report.ok) process.exitCode = 1;
+} else {
+  process.stdout.write('Usage: world-fal serve|conformance [--port N] [--root DIR] [--read-only] [--scenario FILE]\n');
+}