@volter/twin-inngest 0.1.0 → 0.1.2

package/dist/src/inngest-runtime.js

@@ -26,7 +26,7 @@
 // Poll-fold pattern ported from fal-twin.ts's `progressOnce` (fal-twin.ts:245-255): each call to
 // `advanceRun` performs AT MOST ONE meaningful state transition (no wall clock, no timers), so a
 // test suite re-running this file is bit-for-bit reproducible regardless of real elapsed time.
-import { applyTwinWrite, projectResources } from '@volter/world-core';
+import { applyTwinWrite, projectResources, worldNow } from '@volter/world-core';
 import { createHash } from 'node:crypto';
 const SERVICE = 'inngest';
 const DEFAULT_MAX_ATTEMPTS = 4; // modeled default (§13 ⚠4 — doc-UNVERIFIED exact vendor default; config.retries overrides it, see inngest-twin.ts)
@@ -34,7 +34,7 @@ function kid(type, id) {
     return `${type}:${id}`;
 }
 export function nowIso(occurredAt) {
-    return occurredAt ?? new Date().toISOString();
+    return occurredAt ?? worldNow();
 }
 // ── canonical JSON + deterministic stub hashing (ported convention: fal-twin.ts:186-195) ──────
 export function canonicalJson(v) {

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-signing.js

@@ -62,7 +62,7 @@
 //
 // `node:crypto` is required LAZILY (server-only), same convention as fal-webhooks.ts, so this
 // module stays browser-bundle safe.
-import { applyTwinWriteAtomic, projectResources, nodeBuiltin } from '@volter/world-core';
+import { applyTwinWriteAtomic, projectResources, nodeBuiltin, worldNow } from '@volter/world-core';
 function nodeCrypto() {
     // eslint-disable-next-line @typescript-eslint/no-require-imports
     return nodeBuiltin('node:crypto');
@@ -160,7 +160,7 @@ function parseHeader(header) {
  *  `now`), or a signature mismatch (constant-time compare). Pure — never touches the handler. */
 export function verifyInngestSignature(body, header, signingKey, opts = {}) {
     const { t, s } = parseHeader(header);
-    const now = opts.now ?? Math.floor(Date.now() / 1000);
+    const now = opts.now ?? Math.floor(Date.parse(worldNow()) / 1000);
     const tolerance = opts.toleranceSec ?? 300;
     if (Math.abs(now - t) > tolerance)
         throw new InngestSignatureError(`Signature timestamp outside the ${tolerance}s tolerance.`);

package/dist/src/inngest-twin.js

@@ -39,6 +39,7 @@
 // Honesty (D2): an unmodeled route returns Inngest's real v2 error envelope
 // (`{errors:[{code,message}]}`, GROUNDED from the fetched v2 OpenAPI `v2ErrorResponse` schema),
 // never a fabricated success. `readOnly` rejects writes with 405.
+import { worldNow } from '@volter/world-core';
 import { advanceRun, cancelRunsForFunction, createRun, functionsCancelledByEvent, functionsMatchingEvent, getRow, listFunctions, recordEvent, registerFunction, runsForEvent, } from "./inngest-runtime.js";
 const SERVICE = 'inngest';
 // The subject types this twin stores and serves — the mirror of the pack descriptor's
@@ -87,7 +88,7 @@ function parseJson(body) {
     }
 }
 function nowIso(occurredAt) {
-    return occurredAt ?? new Date().toISOString();
+    return occurredAt ?? worldNow();
 }
 // ── views ──────────────────────────────────────────────────────────────────────────────────
 const RUN_STATUS_MAP = { QUEUED: 'QUEUED', RUNNING: 'RUNNING', COMPLETED: 'COMPLETED', FAILED: 'FAILED', CANCELLED: 'CANCELLED' };
@@ -244,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.0",
+  "version": "0.1.2",
   "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.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",
     "inngest": "4.12.0",
     "typescript": "^5.9.0"

package/src/inngest-runtime.ts

@@ -26,7 +26,7 @@
 // Poll-fold pattern ported from fal-twin.ts's `progressOnce` (fal-twin.ts:245-255): each call to
 // `advanceRun` performs AT MOST ONE meaningful state transition (no wall clock, no timers), so a
 // test suite re-running this file is bit-for-bit reproducible regardless of real elapsed time.
-import { applyTwinWrite, projectResources } from '@volter/world-core';
+import { applyTwinWrite, projectResources, worldNow } from '@volter/world-core';
 import { createHash } from 'node:crypto';
 
 const SERVICE = 'inngest';
@@ -71,7 +71,7 @@ function kid(type: string, id: string): string {
   return `${type}:${id}`;
 }
 export function nowIso(occurredAt?: string): string {
-  return occurredAt ?? new Date().toISOString();
+  return occurredAt ?? worldNow();
 }
 
 // ── canonical JSON + deterministic stub hashing (ported convention: fal-twin.ts:186-195) ──────

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-signing.ts

@@ -62,7 +62,7 @@
 //
 // `node:crypto` is required LAZILY (server-only), same convention as fal-webhooks.ts, so this
 // module stays browser-bundle safe.
-import { applyTwinWriteAtomic, projectResources, nodeBuiltin } from '@volter/world-core';
+import { applyTwinWriteAtomic, projectResources, nodeBuiltin, worldNow } from '@volter/world-core';
 
 type NodeCrypto = typeof import('node:crypto');
 function nodeCrypto(): NodeCrypto {
@@ -169,7 +169,7 @@ function parseHeader(header: string): { t: number; s: string } {
  *  `now`), or a signature mismatch (constant-time compare). Pure — never touches the handler. */
 export function verifyInngestSignature(body: unknown, header: string, signingKey: string, opts: { now?: number; toleranceSec?: number } = {}): void {
   const { t, s } = parseHeader(header);
-  const now = opts.now ?? Math.floor(Date.now() / 1000);
+  const now = opts.now ?? Math.floor(Date.parse(worldNow()) / 1000);
   const tolerance = opts.toleranceSec ?? 300;
   if (Math.abs(now - t) > tolerance) throw new InngestSignatureError(`Signature timestamp outside the ${tolerance}s tolerance.`);
   const expected = signInngestRequest(body, t, signingKey);

package/src/inngest-twin.ts

@@ -39,6 +39,7 @@
 // Honesty (D2): an unmodeled route returns Inngest's real v2 error envelope
 // (`{errors:[{code,message}]}`, GROUNDED from the fetched v2 OpenAPI `v2ErrorResponse` schema),
 // never a fabricated success. `readOnly` rejects writes with 405.
+import { worldNow } from '@volter/world-core';
 import {
   advanceRun,
   cancelRunsForFunction,
@@ -120,7 +121,7 @@ function parseJson(body?: string): unknown {
   }
 }
 function nowIso(occurredAt?: string): string {
-  return occurredAt ?? new Date().toISOString();
+  return occurredAt ?? worldNow();
 }
 
 // ── views ──────────────────────────────────────────────────────────────────────────────────
@@ -273,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) } } };
 }