@volter/twin-fly 0.1.1 → 0.1.3

package/dist/src/fly-server.js

@@ -11,7 +11,7 @@
 // engine is a provider behind a door, never the serve path's business.
 import { serveHttp } from '@volter/world-core';
 import { rows, VIRTUAL_FLY_RUNTIME } from "./fly-machines.js";
-import { worldNow, statefulTwinManifest } from '@volter/world-core';
+import { isReadOnlyRequest, worldNow, statefulTwinManifest, withRequestScopes } from '@volter/world-core';
 import { handleFlyTwinRequest } from "./fly-twin.js";
 /**
  * The pack's whole HTTP surface as a plain fetch (runtime contract R12b): `createFlyTwinServer`
@@ -23,10 +23,13 @@ import { handleFlyTwinRequest } from "./fly-twin.js";
  * header map, which the adapter's fixed request shape does not thread.
  */
 export function createFlyTwinFetch(options = {}) {
-    const readOnly = options.readOnly ?? false;
     const root = options.root; // undefined resolves through the kernel's projectRoot — the serve path never reads the process (R4)
     const runtime = options.runtime ?? VIRTUAL_FLY_RUNTIME;
-    return async function flyTwinFetch(request) {
+    // a read-only request (x-volter-read-only) is a request to a read-only twin: a machine read answers the
+    // control plane's current state without folding a runtime exit into it (no inspect, no restart, no
+    // write), nothing is written (withRequestScopes: the pack opts in)
+    return withRequestScopes(async function flyTwinFetch(request) {
+        const readOnly = (options.readOnly ?? false) || isReadOnlyRequest(request);
         const url = new URL(request.url);
         // GET /twin — the discovery manifest (education inside the twin). Constants only: no
         // clock, no state, so every replay of this door is byte-identical (R9).
@@ -49,7 +52,7 @@ export function createFlyTwinFetch(options = {}) {
         if (status === 204 || out === null)
             return new Response(null, { status });
         return new Response(JSON.stringify(out), { status, headers: { 'content-type': 'application/json' } });
-    };
+    }, { refuse: () => Response.json({ error: 'read-only twin: writes are disabled' }, { status: 405 }) });
 }
 export async function createFlyTwinServer(options = {}) {
     const readOnly = options.readOnly ?? false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/twin-fly",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Local Fly.io Machines API twin (api.machines.dev v1: apps/machines/volumes/secrets CRUD, machine lifecycle states+events, leases, wait) whose execution plane is REAL local Docker — control plane twinned, containers genuinely run. Built on @volter/world-core.",
   "author": "Volter (https://github.com/volter-ai)",
   "license": "Apache-2.0",
@@ -36,12 +36,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",
     "typescript": "^5.9.0"
   },

package/src/fly-server.ts

@@ -11,7 +11,7 @@
 // engine is a provider behind a door, never the serve path's business.
 import { serveHttp } from '@volter/world-core';
 import { rows, VIRTUAL_FLY_RUNTIME, type FlyContainerRuntime } from './fly-machines.ts';
-import { worldNow, statefulTwinManifest} from '@volter/world-core';
+import { isReadOnlyRequest, worldNow, statefulTwinManifest, withRequestScopes } from '@volter/world-core';
 import { handleFlyTwinRequest } from './fly-twin.ts';
 
 /** Options every Fly-twin HTTP surface needs, independent of who owns the socket. The
@@ -34,10 +34,13 @@ export interface FlyTwinFetchOptions {
  * header map, which the adapter's fixed request shape does not thread.
  */
 export function createFlyTwinFetch(options: FlyTwinFetchOptions = {}): (request: Request) => Promise<Response> {
-  const readOnly = options.readOnly ?? false;
   const root = options.root; // undefined resolves through the kernel's projectRoot — the serve path never reads the process (R4)
   const runtime = options.runtime ?? VIRTUAL_FLY_RUNTIME;
-  return async function flyTwinFetch(request: Request): Promise<Response> {
+  // a read-only request (x-volter-read-only) is a request to a read-only twin: a machine read answers the
+  // control plane's current state without folding a runtime exit into it (no inspect, no restart, no
+  // write), nothing is written (withRequestScopes: the pack opts in)
+  return withRequestScopes(async function flyTwinFetch(request: Request): Promise<Response> {
+    const readOnly = (options.readOnly ?? false) || isReadOnlyRequest(request);
     const url = new URL(request.url);
     // GET /twin — the discovery manifest (education inside the twin). Constants only: no
     // clock, no state, so every replay of this door is byte-identical (R9).
@@ -59,7 +62,7 @@ export function createFlyTwinFetch(options: FlyTwinFetchOptions = {}): (request:
     });
     if (status === 204 || out === null) return new Response(null, { status });
     return new Response(JSON.stringify(out), { status, headers: { 'content-type': 'application/json' } });
-  };
+  }, { refuse: () => Response.json({ error: 'read-only twin: writes are disabled' }, { status: 405 }) });
 }
 
 export async function createFlyTwinServer(