@volter/twin-inngest 0.1.1 → 0.1.3

package/dist/src/inngest-server.js

@@ -13,9 +13,11 @@
 import { serveHttp } from '@volter/world-core';
 import { handleInngestTwinRequest } from "./inngest-twin.js";
 import { rows } from "./inngest-runtime.js";
-import { createTwinFetchFromHandler, statefulTwinManifest } from '@volter/world-core';
+import { createTwinFetchFromHandler, statefulTwinManifest, withRequestScopes } from '@volter/world-core';
 export function createInngestTwinFetch(options = {}) {
-    return createTwinFetchFromHandler(handleInngestTwinRequest, {
+    // a read-only request (x-volter-read-only) is a request to a read-only twin: a run poll answers the run
+    // as it stands without running a step, nothing is written (withRequestScopes: the pack opts in)
+    return withRequestScopes(createTwinFetchFromHandler(handleInngestTwinRequest, {
         ...options,
         manifest: statefulTwinManifest({ vendor: 'inngest', twinOf: 'the Inngest durable-execution surface', stores: 'events, registered functions and their kernel-persisted run state' }),
         // THE STORE DOOR (R5c). The vendor's own read surface is addressed BY ID
@@ -29,7 +31,7 @@ export function createInngestTwinFetch(options = {}) {
             runs: () => rows('run', options.root),
         },
         extras: (_request, url) => ({ host: url.host }),
-    });
+    }), { refuse: () => Response.json({ error: 'read_only', hint: 'this twin was started read-only; omit readOnly to accept writes' }, { status: 405 }) });
 }
 export async function createInngestTwinServer(options = {}) {
     const server = await serveHttp({

package/dist/src/inngest-twin.js

@@ -245,7 +245,9 @@ async function handleGetRun(runId, req) {
     const existing = getRow('run', runId, req.root);
     if (!existing)
         return apiError(404, 'run_not_found', `No run with id "${runId}".`);
-    const result = await advanceRun(runId, req.root, req.occurredAt); // poll-fold advance on read (fal-twin.ts progressOnce pattern)
+    // poll-fold advance on read (fal-twin.ts progressOnce pattern). A read-only twin (a World's read
+    // token) answers the run as it stands and never runs a step: the app's next poll sees what it would have.
+    const result = req.readOnly ? undefined : await advanceRun(runId, req.root, req.occurredAt);
     const row = result?.run ?? existing;
     return { status: 200, body: { data: runView(row), metadata: { fetchedAt: nowIso(req.occurredAt) } } };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/twin-inngest",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Local Inngest twin for the durable-execution workflow-orchestration surface: event send/batch (Event API), function register/introspect (SDK exec protocol), and a REAL kernel-persisted step-machine (step.run memoize/replay, sleep/sleepUntil instant-advance, waitForEvent gating, exact retry-attempt counters), run status/get/list/cancel-via-event, HMAC-SHA256 executor<->SDK request signing, 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.1"
+    "@volter/world-core": "2.0.3"
   },
   "devDependencies": {
     "@types/bun": "^1.2.20",
     "@types/node": "^24.0.0",
-    "@volter/world-core": "2.0.1",
+    "@volter/world-core": "2.0.3",
     "@volter/world-tooling": "0.1.0",
     "inngest": "4.12.0",
     "typescript": "^5.9.0"

package/src/inngest-server.ts

@@ -13,7 +13,7 @@
 import { serveHttp } from '@volter/world-core';
 import { handleInngestTwinRequest } from './inngest-twin.ts';
 import { rows } from './inngest-runtime.ts';
-import { createTwinFetchFromHandler, statefulTwinManifest } from '@volter/world-core';
+import { createTwinFetchFromHandler, statefulTwinManifest, withRequestScopes } from '@volter/world-core';
 
 /** Options every Inngest-twin HTTP surface needs, independent of who owns the socket. */
 export interface InngestTwinFetchOptions {
@@ -22,7 +22,9 @@ export interface InngestTwinFetchOptions {
 }
 
 export function createInngestTwinFetch(options: InngestTwinFetchOptions = {}): (request: Request) => Promise<Response> {
-  return createTwinFetchFromHandler(handleInngestTwinRequest, {
+  // a read-only request (x-volter-read-only) is a request to a read-only twin: a run poll answers the run
+  // as it stands without running a step, nothing is written (withRequestScopes: the pack opts in)
+  return withRequestScopes(createTwinFetchFromHandler(handleInngestTwinRequest, {
     ...options,
     manifest: statefulTwinManifest({ vendor: 'inngest', twinOf: 'the Inngest durable-execution surface', stores: 'events, registered functions and their kernel-persisted run state' }),
     // THE STORE DOOR (R5c). The vendor's own read surface is addressed BY ID
@@ -36,7 +38,7 @@ export function createInngestTwinFetch(options: InngestTwinFetchOptions = {}): (
       runs: () => rows('run', options.root),
     },
     extras: (_request, url) => ({ host: url.host }),
-  });
+  }), { refuse: () => Response.json({ error: 'read_only', hint: 'this twin was started read-only; omit readOnly to accept writes' }, { status: 405 }) });
 }
 
 export async function createInngestTwinServer(options: { root?: string; port?: number; readOnly?: boolean } = {}): Promise<{ port: number; stop: () => void }> {

package/src/inngest-twin.ts

@@ -274,7 +274,9 @@ async function handleExecInvoke(rawBody: string | undefined, req: InngestRequest
 async function handleGetRun(runId: string, req: InngestRequest): Promise<InngestResponse> {
   const existing = getRow('run', runId, req.root);
   if (!existing) return apiError(404, 'run_not_found', `No run with id "${runId}".`);
-  const result = await advanceRun(runId, req.root, req.occurredAt); // poll-fold advance on read (fal-twin.ts progressOnce pattern)
+  // poll-fold advance on read (fal-twin.ts progressOnce pattern). A read-only twin (a World's read
+  // token) answers the run as it stands and never runs a step: the app's next poll sees what it would have.
+  const result = req.readOnly ? undefined : await advanceRun(runId, req.root, req.occurredAt);
   const row = result?.run ?? existing;
   return { status: 200, body: { data: runView(row), metadata: { fetchedAt: nowIso(req.occurredAt) } } };
 }