@volter/twin-fly 0.1.0 → 0.1.2

package/dist/src/fly-machines.js

@@ -40,7 +40,7 @@
 // speaks): e.g. lease responses are WRAPPED `{status:"success", data:{...}}` (fly-go MachineLease),
 // not the OpenAPI's bare Lease schema. See spec-sources.json for the full citation + every
 // ⚠ doc-unverified modeling choice.
-import { applyTwinWrite, projectResources } from '@volter/world-core';
+import { applyTwinWrite, projectResources, worldNow } from '@volter/world-core';
 import { createHash } from 'node:crypto';
 export const SERVICE = 'fly';
 /**
@@ -96,7 +96,7 @@ export const FLY_MACHINE_STATES = [
 // (created_at, instance_id, image_ref, …) so nothing collides; the bare vendor id is re-attached
 // AFTER projection, never written inside `fields`.
 export function nowIso(occurredAt) {
-    return occurredAt ?? new Date().toISOString();
+    return occurredAt ?? worldNow();
 }
 export function nowEpochMs(occurredAt) {
     return Date.parse(nowIso(occurredAt));

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.0",
+  "version": "0.1.2",
   "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.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",
     "typescript": "^5.9.0"
   },

package/src/fly-machines.ts

@@ -40,7 +40,7 @@
 // speaks): e.g. lease responses are WRAPPED `{status:"success", data:{...}}` (fly-go MachineLease),
 // not the OpenAPI's bare Lease schema. See spec-sources.json for the full citation + every
 // ⚠ doc-unverified modeling choice.
-import { applyTwinWrite, projectResources } from '@volter/world-core';
+import { applyTwinWrite, projectResources, worldNow } from '@volter/world-core';
 import { createHash } from 'node:crypto';
 
 export const SERVICE = 'fly';
@@ -172,7 +172,7 @@ export type FlyMachineState = typeof FLY_MACHINE_STATES[number];
 // AFTER projection, never written inside `fields`.
 
 export function nowIso(occurredAt?: string): string {
-  return occurredAt ?? new Date().toISOString();
+  return occurredAt ?? worldNow();
 }
 export function nowEpochMs(occurredAt?: string): number {
   return Date.parse(nowIso(occurredAt));

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(