@volter/twin-fal

Connector pull: syncFalFromReal reads the current state of each named request handle and hands the resources to the kernel's observeResources, which appends only what changed to the root's log. Check the generated index for protocol standing and use the shared model for current state semantics.

Local fal.ai twin for the model-inference queue lifecycle: submit (queue.fal.run) → status polls with logs → response → cancel, the synchronous fal.run variant, host-split surface routing (the real @fal-ai/client x-fal-target-url proxy protocol), and ed25519-signed webhooks + JWKS — built on the shared @volter/world-core kernel. API-first vendor (no product UI to mirror — the real fal.ai surface agents integrate with is the REST API / @fal-ai/client SDK; the fal.ai dashboard/playground is not an agent navigation target).

bun packages/twin/fal/src/cli.ts

Coverage

This is a v1 slice of the fal.ai API — fal's real REST surface is smaller than a full CRUD vendor's (no models/versions/collections/trainings/deployments admin resources; the vendor is queue lifecycle + the sync variant + webhooks + streaming/realtime/storage periphery). Modeled done (28): the queue lifecycle (submit, multi-segment model ids, status progression IN_QUEUE→IN_PROGRESS→COMPLETED with logs/metrics.inference_time, the result endpoint incl. its doc-example /response alias, request isolation, the cancel trio of exact response bodies 202/400/404), the fal.run synchronous variant + host-split routing + the real x-fal-target-url proxy header, ed25519 webhook signing/verification/JWKS, FastAPI-style 422 validation, readOnly/unmodeled-route safety, kernel-persisted state, the self-referential conformance snapshot, and a handle-driven connector pull (idempotent).

Left as todo (honest gaps, not yet modeled — 29): SSE status streaming, the realtime WebSocket surface, webhook delivery/retry-policy/error-payload variants, the cancelled-terminal state (fal's documented status enum has no CANCELLED member, so only the grounded 202/400/404 acknowledgement bodies are claimed), long-poll pre-completion response behavior, the /response alias as its own claimed capability, a deterministic failure state, submit status-code parity, priority hints, sync-path timeouts (504) and request-id headers, storage/asset upload (initiate, file-url shape, SDK auto-upload), per-model app discovery (unknown-model 404, per-model OpenAPI, a registry fixture), auth 401 parity and key-format validation, the string-detail error variant, 429 rate limiting, 403 budget errors, connector push, connector pull of uploaded storage assets, and a fixtures-seed helper.

API-keys/admin surface: fal.ai key management is dashboard-managed with no public admin REST endpoint — considered during this build and left entirely unmodeled (not even a todo — there is no API surface to model).

Planned (todo): serve deterministic placeholder media bytes at the output urls a request settles to (fal.assets.served_output_bytes) — today the output is a labeled placeholder value.

See src/fal-capabilities.ts for the full manifest (the real vendor surface is the denominator — coverage is honest and partial until the twin reaches it).