@volter/twin-fal 0.1.0 → 0.1.2

package/dist/src/fal-server.js

@@ -23,13 +23,15 @@
 // 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 { createTwinFetchFromHandler, twinManifest, withRequestScopes } 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, {
+    // a read-only request (x-volter-read-only) is a request to a read-only twin: a status poll answers the
+    // request's current status without advancing it, nothing is written (withRequestScopes: the pack opts in)
+    return withRequestScopes(createTwinFetchFromHandler(handleFalTwinRequest, {
         ...handlerOptions,
         manifest: () => twinManifest({
             vendor: 'fal',
@@ -41,7 +43,7 @@ export function createFalTwinFetch(options = {}) {
         }),
         scenarioStatus: () => (scenarioEngine ? scenarioEngine.status() : { vendor: 'fal', handlers: [], misses: 0, recentMisses: [] }),
         ...(scenarioEngine ? { handlerOptions: { scenarioEngine } } : {}),
-    });
+    }), { refuse: () => Response.json({ detail: 'twin is read-only; omit readOnly to accept writes' }, { status: 405 }) });
 }
 export async function createFalTwinServer(options = {}) {
     const server = await serveHttp({

package/dist/src/fal-twin.js

@@ -45,7 +45,7 @@
 // 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 { applyTwinWrite, projectResources, worldNow } 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`
@@ -114,7 +114,7 @@ function parseBody(body) {
     }
 }
 function nowIso(occurredAt) {
-    return occurredAt ?? new Date().toISOString();
+    return occurredAt ?? worldNow();
 }
 function kid(type, id) {
     return `${type}:${id}`;
@@ -301,7 +301,10 @@ 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);
+    // ADVANCE ON POLL — one step per status check. A read-only twin (a World's read token) answers the
+    // request's current status and never advances it: the app's next poll sees what it would have.
+    if (!req.readOnly)
+        await progressOnce(requestId, req);
     const row = getRow('request', requestId, req.root);
     return { status: 200, body: statusView(row, modelId, requestId, includeLogs) };
 }

package/dist/src/fal-webhooks.js

@@ -40,7 +40,7 @@
 //
 // `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';
+import { applyTwinWriteAtomic, projectResources, nodeBuiltin, worldNow, runAsVendorMove } from '@volter/world-core';
 function nodeCrypto() {
     // eslint-disable-next-line @typescript-eslint/no-require-imports
     return nodeBuiltin('node:crypto');
@@ -79,7 +79,8 @@ async function ensureFalSigningSeed(root) {
     const fast = storedSeed(projectResources(SERVICE, root));
     if (fast)
         return fast;
-    const { value } = await applyTwinWriteAtomic(SERVICE, (resources) => {
+    // fal's own signing key: a vendor move, made on first use whoever asks (a read-only request too)
+    const { value } = await runAsVendorMove(() => applyTwinWriteAtomic(SERVICE, (resources) => {
         const existing = storedSeed(resources);
         if (existing)
             return { kind: 'skip', value: existing };
@@ -95,7 +96,7 @@ async function ensureFalSigningSeed(root) {
                 actor: { kind: 'system' },
             },
         };
-    }, root);
+    }, root));
     return value;
 }
 /** The per-root ed25519 keypair, derived from the PERSISTED seed. */
@@ -152,7 +153,7 @@ function verifyRaw(rawBody, headers, publicKey, opts) {
         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);
+    const now = opts.now ?? Math.floor(Date.parse(worldNow()) / 1000);
     if (Math.abs(now - ts) > tolerance) {
         throw new FalWebhookVerificationError(`Webhook timestamp outside the ${tolerance}s tolerance.`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/twin-fal",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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",
@@ -35,12 +35,12 @@
     "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
   },
   "peerDependencies": {
-    "@volter/world-core": "2.0.0"
+    "@volter/world-core": "2.0.2"
   },
   "devDependencies": {
     "@types/bun": "^1.2.20",
     "@types/node": "^24.0.0",
-    "@volter/world-core": "2.0.0",
+    "@volter/world-core": "2.0.2",
     "@volter/world-tooling": "0.1.0",
     "@fal-ai/client": "^1.10.1",
     "typescript": "^5.9.0"

package/src/fal-server.ts

@@ -23,7 +23,7 @@
 // construction — loudly, never a silent fallback.
 import { serveHttp } from '@volter/world-core';
 import { handleFalTwinRequest } from './fal-twin.ts';
-import { createTwinFetchFromHandler, twinManifest } from '@volter/world-core';
+import { createTwinFetchFromHandler, twinManifest, withRequestScopes } from '@volter/world-core';
 import { createFalScenarioEngine, loadFalScenarioDocument, type FalScenarioEngine } from './fal-scenario.ts';
 
 /** Options every fal-twin HTTP surface needs, independent of who owns the socket. */
@@ -39,7 +39,9 @@ export function createFalTwinFetch(options: FalTwinFetchOptions = {}): (request:
   const scenarioPath = options.scenarioPath ?? process.env.TWIN_FAL_SCENARIO;
   const scenarioEngine: FalScenarioEngine | undefined = scenarioPath ? createFalScenarioEngine(loadFalScenarioDocument(scenarioPath)) : undefined;
   const { scenarioPath: _scenarioPath, ...handlerOptions } = options;
-  return createTwinFetchFromHandler(handleFalTwinRequest, {
+  // a read-only request (x-volter-read-only) is a request to a read-only twin: a status poll answers the
+  // request's current status without advancing it, nothing is written (withRequestScopes: the pack opts in)
+  return withRequestScopes(createTwinFetchFromHandler(handleFalTwinRequest, {
     ...handlerOptions,
     manifest: () => twinManifest({
       vendor: 'fal',
@@ -51,7 +53,7 @@ export function createFalTwinFetch(options: FalTwinFetchOptions = {}): (request:
     }),
     scenarioStatus: () => (scenarioEngine ? scenarioEngine.status() : { vendor: 'fal', handlers: [], misses: 0, recentMisses: [] }),
     ...(scenarioEngine ? { handlerOptions: { scenarioEngine } } : {}),
-  });
+  }), { refuse: () => Response.json({ detail: 'twin is read-only; omit readOnly to accept writes' }, { status: 405 }) });
 }
 
 export async function createFalTwinServer(options: { root?: string; port?: number; readOnly?: boolean; scenarioPath?: string } = {}): Promise<{ port: number; stop: () => void }> {

package/src/fal-twin.ts

@@ -45,7 +45,7 @@
 // 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 { applyTwinWrite, projectResources, worldNow } from '@volter/world-core';
 import { falJwks } from './fal-webhooks.ts';
 import type { FalScenarioEngine, FalScenarioRespond } from './fal-scenario.ts';
 
@@ -149,7 +149,7 @@ function parseBody(body?: string): { ok: true; value: Record<string, unknown> }
   }
 }
 function nowIso(occurredAt?: string): string {
-  return occurredAt ?? new Date().toISOString();
+  return occurredAt ?? worldNow();
 }
 function kid(type: string, id: string): string {
   return `${type}:${id}`;
@@ -352,7 +352,9 @@ async function handleSubmit(modelId: string, rawBody: string | undefined, surfac
 async function handleStatus(modelId: string, requestId: string, includeLogs: boolean, req: FalRequest): Promise<FalResponse> {
   const existing = getRow('request', requestId, req.root);
   if (!existing) return detailNotFound('Request not found.');
-  await progressOnce(requestId, req);
+  // ADVANCE ON POLL — one step per status check. A read-only twin (a World's read token) answers the
+  // request's current status and never advances it: the app's next poll sees what it would have.
+  if (!req.readOnly) await progressOnce(requestId, req);
   const row = getRow('request', requestId, req.root)!;
   return { status: 200, body: statusView(row, modelId, requestId, includeLogs) };
 }

package/src/fal-webhooks.ts

@@ -40,7 +40,7 @@
 //
 // `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';
+import { applyTwinWriteAtomic, projectResources, nodeBuiltin, worldNow, runAsVendorMove } from '@volter/world-core';
 
 type NodeCrypto = typeof import('node:crypto');
 function nodeCrypto(): NodeCrypto {
@@ -96,7 +96,8 @@ function storedSeed(resources: readonly { type: string; id: string }[]): string
 async function ensureFalSigningSeed(root?: string): Promise<string> {
   const fast = storedSeed(projectResources(SERVICE, root));
   if (fast) return fast;
-  const { value } = await applyTwinWriteAtomic<string>(SERVICE, (resources) => {
+  // fal's own signing key: a vendor move, made on first use whoever asks (a read-only request too)
+  const { value } = await runAsVendorMove(() => applyTwinWriteAtomic<string>(SERVICE, (resources) => {
     const existing = storedSeed(resources);
     if (existing) return { kind: 'skip', value: existing };
     const seed = nodeCrypto().randomBytes(SEED_BYTES).toString('base64');
@@ -111,7 +112,7 @@ async function ensureFalSigningSeed(root?: string): Promise<string> {
         actor: { kind: 'system' },
       },
     };
-  }, root);
+  }, root));
   return value;
 }
 
@@ -173,7 +174,7 @@ function verifyRaw(rawBody: string, headers: Record<string, string>, publicKey:
     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);
+  const now = opts.now ?? Math.floor(Date.parse(worldNow()) / 1000);
   if (Math.abs(now - ts) > tolerance) {
     throw new FalWebhookVerificationError(`Webhook timestamp outside the ${tolerance}s tolerance.`);
   }