@volter/twin-xai 0.1.1 → 0.1.3

package/dist/src/xai-server.js

@@ -10,7 +10,7 @@
 // Scenario scripting (xai-scenario.ts): a JSON scenario file — via the scenarioPath option,
 // the TWIN_XAI_SCENARIO env var, or `world-xai serve --scenario <path>` — scripts the exact
 // assistant turns for POST /v1/chat/completions. One session per server (nthCall/once state).
-import { serveHttp } from '@volter/world-core';
+import { isReadOnlyRequest, serveHttp, withRequestScopes } from '@volter/world-core';
 import { twinManifest, twinPublicBase, worldNow } from '@volter/world-core';
 import { createXaiScenarioEngine, loadXaiScenarioDocument } from "./xai-scenario.js";
 import { handleXaiTwinRequest } from "./xai-twin.js";
@@ -68,10 +68,14 @@ function html(body, status = 200) {
  * (xai-device-auth-ui.ts), so the OAuth protocol UI is workerd-servable too.
  */
 export function createXaiTwinFetch(options = {}) {
-    const readOnly = options.readOnly ?? false;
     const scenarioPath = options.scenarioPath ?? process.env.TWIN_XAI_SCENARIO;
     const scenarioEngine = scenarioPath ? createXaiScenarioEngine(loadXaiScenarioDocument(scenarioPath)) : undefined;
-    return async function xaiTwinFetch(request) {
+    // a read-only request (x-volter-read-only, a World's read token) is a request to a read-only twin: no
+    // device grant is started or decided, no token minted, no completion run or usage recorded, and a
+    // deferred completion is only PEEKED (xai-twin.ts retrieveDeferredCompletion: the app's one retrieval
+    // is never spent by a viewer); the kernel refuses any write that slips past as xAI's own error shape
+    return withRequestScopes(async function xaiTwinFetch(request) {
+        const readOnly = (options.readOnly ?? false) || isReadOnlyRequest(request);
         const url = new URL(request.url);
         const path = url.pathname + (url.search || '');
         const cleanPath = url.pathname.replace(/\/+$/, '');
@@ -220,7 +224,7 @@ export function createXaiTwinFetch(options = {}) {
             ...(scenarioEngine ? { scenarioEngine } : {}),
         });
         return new Response(JSON.stringify(out), { status, headers: { 'content-type': 'application/json', 'x-request-id': 'req_twin', ...(outHeaders ?? {}) } });
-    };
+    }, { refuse: () => new Response(JSON.stringify({ code: 'method_not_allowed', error: 'this request is read-only' }), { status: 405, headers: { 'content-type': 'application/json' } }) });
 }
 export async function createXaiTwinServer(options) {
     const server = await serveHttp({

package/dist/src/xai-twin.js

@@ -543,6 +543,11 @@ async function retrieveDeferredCompletion(requestId, req) {
     // consume is a WRITE, so it is skipped (the lifecycle simply cannot advance in a read-only
     // mirror, and repeated read-only polls keep serving the still-unconsumed result). §9 found
     // this consume unguarded — a read-only GET was consuming the row.
+    // A World's READ token (x-volter-read-only) arrives here as readOnly too, and PEEKS rather than
+    // being refused: xAI's own shapes already say everything a viewer may see without spending
+    // anything — 202 with an empty body while pending, the completion once ready — so a peek answers
+    // exactly the vendor's shape for the row's current state and advances nothing (neither the first
+    // poll nor the one-time retrieval). The app's own poll then still gets its one retrieval.
     if (!req.readOnly) {
         await applyTwinWrite(SERVICE, {
             operation: 'deferred_completion.consume',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/twin-xai",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Local xAI (Grok) twin — a faithful, stateful local API plus the Grok Build device-OAuth browser surface. The model is stubbed (deterministic) and Live Search citations are labeled stubs, while the OAuth/account/usage world and API protocol envelopes remain coherent and vendor-shaped. Built on @volter/world-core.",
   "keywords": [
     "twin",
@@ -56,10 +56,10 @@
     "react-dom": "^19.2.7"
   },
   "peerDependencies": {
-    "@volter/world-core": "2.0.1"
+    "@volter/world-core": "2.0.3"
   },
   "devDependencies": {
-    "@volter/world-core": "2.0.1",
+    "@volter/world-core": "2.0.3",
     "@volter/world-tooling": "0.1.0",
     "@ai-sdk/xai": "^3.0.111",
     "ai": "^6.0.0",

package/src/xai-server.ts

@@ -10,7 +10,7 @@
 // Scenario scripting (xai-scenario.ts): a JSON scenario file — via the scenarioPath option,
 // the TWIN_XAI_SCENARIO env var, or `world-xai serve --scenario <path>` — scripts the exact
 // assistant turns for POST /v1/chat/completions. One session per server (nthCall/once state).
-import { serveHttp } from '@volter/world-core';
+import { isReadOnlyRequest, serveHttp, withRequestScopes } from '@volter/world-core';
 import { twinManifest, twinPublicBase, worldNow } from '@volter/world-core';
 import { createXaiScenarioEngine, loadXaiScenarioDocument, type XaiScenarioEngine } from './xai-scenario.ts';
 import { handleXaiTwinRequest } from './xai-twin.ts';
@@ -89,10 +89,14 @@ export interface XaiTwinFetchOptions {
  * (xai-device-auth-ui.ts), so the OAuth protocol UI is workerd-servable too.
  */
 export function createXaiTwinFetch(options: XaiTwinFetchOptions = {}): (request: Request) => Promise<Response> {
-  const readOnly = options.readOnly ?? false;
   const scenarioPath = options.scenarioPath ?? process.env.TWIN_XAI_SCENARIO;
   const scenarioEngine: XaiScenarioEngine | undefined = scenarioPath ? createXaiScenarioEngine(loadXaiScenarioDocument(scenarioPath)) : undefined;
-  return async function xaiTwinFetch(request: Request): Promise<Response> {
+  // a read-only request (x-volter-read-only, a World's read token) is a request to a read-only twin: no
+  // device grant is started or decided, no token minted, no completion run or usage recorded, and a
+  // deferred completion is only PEEKED (xai-twin.ts retrieveDeferredCompletion: the app's one retrieval
+  // is never spent by a viewer); the kernel refuses any write that slips past as xAI's own error shape
+  return withRequestScopes(async function xaiTwinFetch(request: Request): Promise<Response> {
+    const readOnly = (options.readOnly ?? false) || isReadOnlyRequest(request);
     const url = new URL(request.url);
     const path = url.pathname + (url.search || '');
     const cleanPath = url.pathname.replace(/\/+$/, '');
@@ -245,7 +249,7 @@ export function createXaiTwinFetch(options: XaiTwinFetchOptions = {}): (request:
       ...(scenarioEngine ? { scenarioEngine } : {}),
     });
     return new Response(JSON.stringify(out), { status, headers: { 'content-type': 'application/json', 'x-request-id': 'req_twin', ...(outHeaders ?? {}) } });
-  };
+  }, { refuse: () => new Response(JSON.stringify({ code: 'method_not_allowed', error: 'this request is read-only' }), { status: 405, headers: { 'content-type': 'application/json' } }) });
 }
 
 export async function createXaiTwinServer(options: { root?: string; port?: number; readOnly?: boolean; scenarioPath?: string }): Promise<{ port: number; stop: () => void }> {

package/src/xai-twin.ts

@@ -629,6 +629,11 @@ async function retrieveDeferredCompletion(requestId: string, req: XaiRequest): P
   // consume is a WRITE, so it is skipped (the lifecycle simply cannot advance in a read-only
   // mirror, and repeated read-only polls keep serving the still-unconsumed result). §9 found
   // this consume unguarded — a read-only GET was consuming the row.
+  // A World's READ token (x-volter-read-only) arrives here as readOnly too, and PEEKS rather than
+  // being refused: xAI's own shapes already say everything a viewer may see without spending
+  // anything — 202 with an empty body while pending, the completion once ready — so a peek answers
+  // exactly the vendor's shape for the row's current state and advances nothing (neither the first
+  // poll nor the one-time retrieval). The app's own poll then still gets its one retrieval.
   if (!req.readOnly) {
     await applyTwinWrite(SERVICE, {
       operation: 'deferred_completion.consume',