@volter/twin-xai 0.1.0 → 0.1.2

package/dist/src/xai-device-auth-ui.js

@@ -1,6 +1,7 @@
 // Server half of xAI's Grok Build device-authorization UI. This is protocol UI, not an
 // invented dashboard: it is served on the OAuth paths and coupled directly to the pending
 // device authorization projected from the Twin kernel.
+import { worldNow } from '@volter/world-core';
 import { createElement } from 'react';
 import { renderToStaticMarkup } from 'react-dom/server';
 import { DeviceConsentPage, DeviceDonePage, DeviceEntryPage, XAI_DEVICE_PERMISSIONS, } from "../client/xai-device-auth.js";
@@ -33,7 +34,7 @@ export function xaiDeviceAuthView(userCode, root, error, nowAt) {
     const normalized = userCode.trim().toUpperCase().replace(/[^A-Z0-9-]/gu, '');
     const state = inspectXaiTwinDeviceAuthorization(normalized, root);
     let status = typeof state?.status === 'string' ? state.status : 'unknown';
-    if (state?.expiresAt && Date.parse(String(state.expiresAt)) <= Date.parse(nowAt ?? new Date().toISOString()) && status === 'pending')
+    if (state?.expiresAt && Date.parse(String(state.expiresAt)) <= Date.parse(nowAt ?? worldNow()) && status === 'pending')
         status = 'expired';
     const supported = new Set(['pending', 'approved', 'denied', 'connected', 'expired', 'unknown']);
     const scopes = new Set(String(state?.scope ?? '').split(/\s+/u).filter(Boolean));

package/dist/src/xai-oauth.js

@@ -1,11 +1,11 @@
-import { applyTwinWrite, applyTwinWriteAtomic, projectResources } from '@volter/world-core';
+import { applyTwinWrite, applyTwinWriteAtomic, projectResources, worldNow } from '@volter/world-core';
 const SERVICE = 'xai';
 const ACCOUNT_ID = 'acct_twin_grok';
 const DEFAULT_SCOPE = 'openid profile email offline_access grok-cli:access api:access conversations:read conversations:write workspaces:read workspaces:write';
 const ACCESS_TTL_SECONDS = 3_600;
 const DEVICE_TTL_SECONDS = 900;
 function at(occurredAt) {
-    return new Date(occurredAt ?? new Date().toISOString());
+    return new Date(occurredAt ?? worldNow());
 }
 /** FNV-1a over the seed, widened by re-hashing with a round counter until `n` hex chars exist. */
 function stableHex(seed, n) {

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.0",
+  "version": "0.1.2",
   "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.0"
+    "@volter/world-core": "2.0.2"
   },
   "devDependencies": {
-    "@volter/world-core": "2.0.0",
+    "@volter/world-core": "2.0.2",
     "@volter/world-tooling": "0.1.0",
     "@ai-sdk/xai": "^3.0.111",
     "ai": "^6.0.0",

package/src/xai-device-auth-ui.ts

@@ -1,6 +1,7 @@
 // Server half of xAI's Grok Build device-authorization UI. This is protocol UI, not an
 // invented dashboard: it is served on the OAuth paths and coupled directly to the pending
 // device authorization projected from the Twin kernel.
+import { worldNow } from '@volter/world-core';
 import { createElement } from 'react';
 import { renderToStaticMarkup } from 'react-dom/server';
 import {
@@ -46,7 +47,7 @@ export function xaiDeviceAuthView(userCode: string, root?: string, error?: strin
   const normalized = userCode.trim().toUpperCase().replace(/[^A-Z0-9-]/gu, '');
   const state = inspectXaiTwinDeviceAuthorization(normalized, root);
   let status = typeof state?.status === 'string' ? state.status : 'unknown';
-  if (state?.expiresAt && Date.parse(String(state.expiresAt)) <= Date.parse(nowAt ?? new Date().toISOString()) && status === 'pending') status = 'expired';
+  if (state?.expiresAt && Date.parse(String(state.expiresAt)) <= Date.parse(nowAt ?? worldNow()) && status === 'pending') status = 'expired';
   const supported = new Set<XaiDeviceAuthView['status']>(['pending', 'approved', 'denied', 'connected', 'expired', 'unknown']);
   const scopes = new Set(String(state?.scope ?? '').split(/\s+/u).filter(Boolean));
   const permissions = XAI_DEVICE_PERMISSIONS.filter((_, index) => [

package/src/xai-oauth.ts

@@ -1,4 +1,4 @@
-import { applyTwinWrite, applyTwinWriteAtomic, projectResources, type TwinResource } from '@volter/world-core';
+import { applyTwinWrite, applyTwinWriteAtomic, projectResources, type TwinResource, worldNow } from '@volter/world-core';
 
 const SERVICE = 'xai';
 const ACCOUNT_ID = 'acct_twin_grok';
@@ -9,7 +9,7 @@ const DEVICE_TTL_SECONDS = 900;
 export type XaiOauthResult = { status: number; body: Record<string, unknown> };
 
 function at(occurredAt?: string): Date {
-  return new Date(occurredAt ?? new Date().toISOString());
+  return new Date(occurredAt ?? worldNow());
 }
 
 /** FNV-1a over the seed, widened by re-hashing with a round counter until `n` hex chars exist. */

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',