@volter/world-runtime 2.0.32 → 2.0.34

package/dist/src/served-world.js

@@ -26,7 +26,7 @@ import { getActiveWorldStore, withAncestryLock, captureHistory, historyAtInstant
 // to `.volter/token` and `.volter/token.read` (0600).
 // One writer per world by construction: the doors run in this process, serialized per twin.
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
-import { assertSafeChangesetName, blobDigest, destinationOf, openSealedAt, getActiveBlobStore, journalTwinRequest, loadCheck, mirrorShellUnder, readTwinRequestJournal, serveHttp, twinRequestCredentials, TWIN_PREFIX_HEADER, validateRemoteOrigin } from '@volter/world-core';
+import { assertSafeChangesetName, blobDigest, destinationOf, openSealedAt, getActiveBlobStore, journalTwinRequest, loadCheck, twinRequestJournalFailures, mirrorShellUnder, readTwinRequestJournal, serveHttp, twinRequestCredentials, TWIN_PREFIX_HEADER, validateRemoteOrigin } from '@volter/world-core';
 import { APP_READ_ENDPOINT_ENV } from "./init.js";
 import { grantOf, presentedSecrets, sameSecret, spentPasses, verifyPass } from '@volter/world-access';
 import { createHash } from 'node:crypto';
@@ -950,7 +950,12 @@ export class WorldDoors {
         if (offered.some((p) => p.startsWith('tok_')) || (offered.length && grantOf(offered, null, this.issued())))
             caller.delete('authorization');
         // an opened seal keeps the audit a twin keeps: the same line in the same journal under the link's
-        // name, with the credential shape of what the caller sent on
+        // name, with the credential shape of what the caller sent on. As an audit device does, the request is
+        // written before the real credential is used, and a request whose audit cannot be written is refused.
+        const credentials = twinRequestCredentials(caller, url);
+        if (!journalTwinRequest(name, { phase: 'request', method: request.method, path: `/${rest}`, status: 0, credentials }, this.controlRoot(name))) {
+            return Response.json({ error: `the ${name} link's audit could not be written: nothing was sent` }, { status: 503 });
+        }
         const startedAt = Date.now();
         let status = 500;
         try {
@@ -959,7 +964,7 @@ export class WorldDoors {
             return answer;
         }
         finally {
-            journalTwinRequest(name, { method: request.method, path: `/${rest}`, status, ms: Date.now() - startedAt, credentials: twinRequestCredentials(caller, url) }, this.controlRoot(name));
+            journalTwinRequest(name, { method: request.method, path: `/${rest}`, status, ms: Date.now() - startedAt, credentials }, this.controlRoot(name));
         }
     }
     async forwardSealed(request, caller, url, rest, name, origin) {
@@ -1184,6 +1189,15 @@ export class WorldDoors {
         }
         if (kind === 'links' && !name && request.method === 'GET')
             return Response.json({ links: this.links() });
+        // OPENING A SEAL — pointing this World at a vendor (a link, a twin's root) or sealing the credential it uses there — is
+        // the World token's act, or a person's at its page: never a key's, which an app or a script holds (an app that could
+        // open its own seal would be unsealed by itself, not deliberately)
+        const opensSeal = (kind === 'links' && name && (request.method === 'PUT' || request.method === 'DELETE'))
+            || (kind === 'twins' && name && (verb === 'root' || verb === 'credential') && request.method === 'PUT')
+            // a check runs in a local World's own process, with all it can reach: putting or removing one is the same act
+            || (kind === 'checks' && name && (request.method === 'PUT' || request.method === 'DELETE'));
+        if (opensSeal && via === 'key')
+            return Response.json({ error: 'opening a seal is the World\'s token\'s act, or a person\'s at its page: a key cannot point this World at a vendor, seal a credential, or change its checks' }, { status: 403 });
         if (kind === 'links' && name && request.method === 'PUT') {
             if (!/^[a-z0-9][a-z0-9_-]{0,63}$/.test(name) || this.up().services[name])
                 return Response.json({ error: 'a link is named [a-z0-9_-] and is not a twin of this World' }, { status: 400 });
@@ -1328,7 +1342,8 @@ export class WorldDoors {
             const since = Date.now() - sinceMs;
             const twins = [];
             for (const vendor of [...new Set([...Object.keys(this.up().services), ...Object.keys(this.links())])]) {
-                const entries = readTwinRequestJournal(vendor, this.controlRoot(vendor)).filter((e) => !e.at || Date.parse(e.at) >= since);
+                // a link's request entries (written before it forwards) are its audit, not traffic: its outcomes are counted
+                const entries = readTwinRequestJournal(vendor, this.controlRoot(vendor), { since }).filter((e) => e.phase !== 'request' && (!e.at || Date.parse(e.at) >= since));
                 const byStatus = {};
                 const routes = new Map();
                 const times = [];
@@ -1344,7 +1359,7 @@ export class WorldDoors {
                 const pct = (p) => (times.length ? times[Math.min(times.length - 1, Math.floor((p / 100) * times.length))] : null);
                 twins.push({ twin: vendor, requests: entries.length, byStatus, p50Ms: pct(50), p95Ms: pct(95), topRoutes: [...routes.entries()].sort((a, b) => b[1] - a[1]).slice(0, 10).map(([route, requests]) => ({ route, requests })) });
             }
-            return Response.json({ world: this.served, hours: sinceMs / 3_600_000, twins, requests: twins.reduce((n, t) => n + t.requests, 0) });
+            return Response.json({ world: this.served, hours: sinceMs / 3_600_000, twins, requests: twins.reduce((n, t) => n + t.requests, 0), journalFailures: twins.reduce((n, t) => n + twinRequestJournalFailures(t.twin, this.controlRoot(t.twin)), 0) });
         }
         if (kind === 'twins' && !name && request.method === 'GET') {
             // every twin of the world as a consumer sees it — the status door mapped over the world; what a

package/dist/src/tail.js

@@ -7,7 +7,7 @@
 // records its first action, so discovery re-runs on every poll and a missing ledger is a
 // notice, never an error.
 import { closeSync, existsSync, openSync, readFileSync, readSync, readdirSync, statSync } from 'node:fs';
-import { join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import { stateDirName } from '@volter/world-core';
 import { statusWorld } from "./runtime.js";
 /** Every action ledger a world service currently owns. One world service can record actions
@@ -43,10 +43,24 @@ function readNewLines(path, offsets) {
     catch {
         return []; // vanished between discovery and read (e.g. a purge mid-tail) — next poll rediscovers
     }
-    if (size < offset)
-        offset = 0; // rewritten shorter (scrub/rebuild) — replay rather than silently skip
-    if (size === offset)
-        return [];
+    let closed = [];
+    if (size < offset) {
+        // a request journal that closed into its next segment (world-core serve.ts): what was appended there
+        // after the last poll is read from the segment first; any other shorter rewrite (scrub/rebuild) replays
+        const segment = newestSegment(path);
+        let closedSize = -1;
+        try {
+            closedSize = segment ? statSync(segment).size : -1;
+        }
+        catch { /* gone between list and stat */ }
+        if (segment && closedSize >= offset)
+            closed = readNewLines(segment, new Map([[segment, offset]]));
+        offset = 0;
+    }
+    if (size === offset) {
+        offsets.set(path, offset);
+        return closed;
+    }
     const fd = openSync(path, 'r');
     const buffer = Buffer.alloc(size - offset);
     try {
@@ -56,10 +70,29 @@ function readNewLines(path, offsets) {
         closeSync(fd);
     }
     const lastNewline = buffer.lastIndexOf(0x0a);
-    if (lastNewline < 0)
-        return [];
+    if (lastNewline < 0) {
+        offsets.set(path, offset);
+        return closed;
+    }
     offsets.set(path, offset + lastNewline + 1);
-    return buffer.subarray(0, lastNewline).toString('utf8').split('\n').filter((line) => line.trim() !== '');
+    return [...closed, ...buffer.subarray(0, lastNewline).toString('utf8').split('\n').filter((line) => line.trim() !== '')];
+}
+/** A journal's newest closed segment (`<file>.<n>`), or null. */
+function newestSegment(path) {
+    const dir = dirname(path);
+    const base = basename(path);
+    let best = 0;
+    try {
+        for (const name of readdirSync(dir)) {
+            const n = name.startsWith(`${base}.`) ? Number(name.slice(base.length + 1)) : NaN;
+            if (Number.isInteger(n) && n > best)
+                best = n;
+        }
+    }
+    catch {
+        return null;
+    }
+    return best ? `${path}.${best}` : null;
 }
 /** Local wall-clock `HH:MM:SS.mmm` — the operator is watching a live feed on this machine. */
 function formatOccurredAt(occurredAt) {
@@ -85,6 +118,9 @@ function formatEntry(entry, json) {
         const creds = (record.credentials ?? [])
             .map((c) => `${c.name ?? '?'}${c.in === 'query' ? '(query)' : ''}=${c.empty ? 'EMPTY' : `${c.scheme ? `${c.scheme} ` : ''}${(c.fp ?? '').replace(/^sha256:/, '').slice(0, 8)}`}`)
             .join(' ');
+        // a link's request entry, written before it forwards: the request on its way, its outcome follows
+        if (record.phase === 'request')
+            return `${formatOccurredAt(entryInstant(entry))} ${entry.service} → ${record.method ?? '?'} ${record.path ?? '?'}${creds ? ` [${creds}]` : ''}`;
         return `${formatOccurredAt(entryInstant(entry))} ${entry.service} ${record.method ?? '?'} ${record.path ?? '?'} ${record.status ?? '?'}${typeof record.ms === 'number' ? ` in ${record.ms}ms` : ''}${creds ? ` [${creds}]` : ''}`;
     }
     return `${formatOccurredAt(record.occurredAt)} ${entry.service} ${record.operation ?? record.op ?? '?'} ${record.subject?.id ?? '?'}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "2.0.32",
+  "version": "2.0.34",
   "description": "World configs for twins: boot named local runtimes, allocate ports, generate world.env/instance.json, and run apps against fake-key twin worlds.",
   "keywords": [
     "twin",
@@ -67,14 +67,14 @@
     "node": ">=22.3"
   },
   "peerDependencies": {
-    "@volter/world-core": "2.0.19",
-    "@volter/world-console": "2.0.11"
+    "@volter/world-core": "2.0.20",
+    "@volter/world-console": "2.0.12"
   },
   "dependencies": {
     "@electric-sql/pglite": "0.5.8",
     "@electric-sql/pglite-pgvector": "0.0.9",
     "@volter/world-access": "2.0.2",
-    "@volter/world-core": "2.0.19",
+    "@volter/world-core": "2.0.20",
     "pg-gateway": "0.3.0-beta.4",
     "smol-toml": "^1.8.0"
   },
@@ -84,6 +84,6 @@
     }
   },
   "optionalDependencies": {
-    "@volter/twin-mongodb": "0.1.19"
+    "@volter/twin-mongodb": "0.1.20"
   }
 }

package/src/served-world.ts

@@ -26,7 +26,7 @@ import { getActiveWorldStore, withAncestryLock, captureHistory, historyAtInstant
 // to `.volter/token` and `.volter/token.read` (0600).
 // One writer per world by construction: the doors run in this process, serialized per twin.
 import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync , rmSync} from 'node:fs';
-import { assertSafeChangesetName, blobDigest, destinationOf, openSealedAt, getActiveBlobStore, journalTwinRequest, loadCheck, mirrorShellUnder, readTwinRequestJournal, serveHttp, twinRequestCredentials, TWIN_PREFIX_HEADER, validateRemoteOrigin, type SealedCredential, type TwinStreamConnection, type TwinStreamSink } from '@volter/world-core';
+import { assertSafeChangesetName, blobDigest, destinationOf, openSealedAt, getActiveBlobStore, journalTwinRequest, loadCheck, twinRequestJournalFailures, mirrorShellUnder, readTwinRequestJournal, serveHttp, twinRequestCredentials, TWIN_PREFIX_HEADER, validateRemoteOrigin, type SealedCredential, type TwinStreamConnection, type TwinStreamSink } from '@volter/world-core';
 import { APP_READ_ENDPOINT_ENV } from './init.ts';
 import { grantOf, presentedSecrets, sameSecret, spentPasses, verifyPass, type TrustedIssuer, type WorldCredentials } from '@volter/world-access';
 import { createHash } from 'node:crypto';
@@ -849,14 +849,19 @@ export class WorldDoors {
     const offered = authorization ? presentedSecrets(new Headers({ authorization }), { token: TOKEN_HEADER, twinsKey: TWINS_KEY_HEADER }) : [];
     if (offered.some((p) => p.startsWith('tok_')) || (offered.length && grantOf(offered, null, this.issued()))) caller.delete('authorization');
     // an opened seal keeps the audit a twin keeps: the same line in the same journal under the link's
-    // name, with the credential shape of what the caller sent on
+    // name, with the credential shape of what the caller sent on. As an audit device does, the request is
+    // written before the real credential is used, and a request whose audit cannot be written is refused.
+    const credentials = twinRequestCredentials(caller, url);
+    if (!journalTwinRequest(name, { phase: 'request', method: request.method, path: `/${rest}`, status: 0, credentials }, this.controlRoot(name))) {
+      return Response.json({ error: `the ${name} link's audit could not be written: nothing was sent` }, { status: 503 });
+    }
     const startedAt = Date.now(); let status = 500;
     try {
       const answer = await this.forwardSealed(request, caller, url, rest, name, origin);
       status = answer.status;
       return answer;
     } finally {
-      journalTwinRequest(name, { method: request.method, path: `/${rest}`, status, ms: Date.now() - startedAt, credentials: twinRequestCredentials(caller, url) }, this.controlRoot(name));
+      journalTwinRequest(name, { method: request.method, path: `/${rest}`, status, ms: Date.now() - startedAt, credentials }, this.controlRoot(name));
     }
   }
 
@@ -1032,6 +1037,14 @@ export class WorldDoors {
       return Response.json(approveWorldChangeset(name, { root: this.worldRoot, world: this.name, principal, ...(body.note ? { note: body.note } : {}) }));
     }
     if (kind === 'links' && !name && request.method === 'GET') return Response.json({ links: this.links() });
+    // OPENING A SEAL — pointing this World at a vendor (a link, a twin's root) or sealing the credential it uses there — is
+    // the World token's act, or a person's at its page: never a key's, which an app or a script holds (an app that could
+    // open its own seal would be unsealed by itself, not deliberately)
+    const opensSeal = (kind === 'links' && name && (request.method === 'PUT' || request.method === 'DELETE'))
+      || (kind === 'twins' && name && (verb === 'root' || verb === 'credential') && request.method === 'PUT')
+      // a check runs in a local World's own process, with all it can reach: putting or removing one is the same act
+      || (kind === 'checks' && name && (request.method === 'PUT' || request.method === 'DELETE'));
+    if (opensSeal && via === 'key') return Response.json({ error: 'opening a seal is the World\'s token\'s act, or a person\'s at its page: a key cannot point this World at a vendor, seal a credential, or change its checks' }, { status: 403 });
     if (kind === 'links' && name && request.method === 'PUT') {
       if (!/^[a-z0-9][a-z0-9_-]{0,63}$/.test(name) || this.up().services[name]) return Response.json({ error: 'a link is named [a-z0-9_-] and is not a twin of this World' }, { status: 400 });
       const body = (await request.json()) as { origin?: string };
@@ -1145,13 +1158,14 @@ export class WorldDoors {
       const sinceMs = Number(url.searchParams.get('hours') ?? '24') * 3_600_000; const since = Date.now() - sinceMs;
       const twins: Array<{ twin: string; requests: number; byStatus: Record<string, number>; p50Ms: number | null; p95Ms: number | null; topRoutes: Array<{ route: string; requests: number }> }> = [];
       for (const vendor of [...new Set([...Object.keys(this.up().services), ...Object.keys(this.links())])]) {
-        const entries = readTwinRequestJournal(vendor, this.controlRoot(vendor)).filter((e) => !e.at || Date.parse(e.at) >= since);
+        // a link's request entries (written before it forwards) are its audit, not traffic: its outcomes are counted
+        const entries = readTwinRequestJournal(vendor, this.controlRoot(vendor), { since }).filter((e) => e.phase !== 'request' && (!e.at || Date.parse(e.at) >= since));
         const byStatus: Record<string, number> = {}; const routes = new Map<string, number>(); const times: number[] = [];
         for (const e of entries) { const cls = `${String(e.status)[0]}xx`; byStatus[cls] = (byStatus[cls] ?? 0) + 1; const route = `${e.method} ${e.path.replace(/\/[0-9]+(?=\/|$)/g, '/{id}')}`; routes.set(route, (routes.get(route) ?? 0) + 1); if (typeof e.ms === 'number') times.push(e.ms); }
         times.sort((a, b) => a - b); const pct = (p: number): number | null => (times.length ? times[Math.min(times.length - 1, Math.floor((p / 100) * times.length))]! : null);
         twins.push({ twin: vendor, requests: entries.length, byStatus, p50Ms: pct(50), p95Ms: pct(95), topRoutes: [...routes.entries()].sort((a, b) => b[1] - a[1]).slice(0, 10).map(([route, requests]) => ({ route, requests })) });
       }
-      return Response.json({ world: this.served, hours: sinceMs / 3_600_000, twins, requests: twins.reduce((n, t) => n + t.requests, 0) });
+      return Response.json({ world: this.served, hours: sinceMs / 3_600_000, twins, requests: twins.reduce((n, t) => n + t.requests, 0), journalFailures: twins.reduce((n, t) => n + twinRequestJournalFailures(t.twin, this.controlRoot(t.twin)), 0) });
     }
     if (kind === 'twins' && !name && request.method === 'GET') {
       // every twin of the world as a consumer sees it — the status door mapped over the world; what a

package/src/tail.ts

@@ -7,7 +7,7 @@
 // records its first action, so discovery re-runs on every poll and a missing ledger is a
 // notice, never an error.
 import { closeSync, existsSync, openSync, readFileSync, readSync, readdirSync, statSync } from 'node:fs';
-import { join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import { stateDirName } from '@volter/world-core';
 import { statusWorld } from './runtime.ts';
 
@@ -84,8 +84,16 @@ function readNewLines(path: string, offsets: Map<string, number>): string[] {
   } catch {
     return []; // vanished between discovery and read (e.g. a purge mid-tail) — next poll rediscovers
   }
-  if (size < offset) offset = 0; // rewritten shorter (scrub/rebuild) — replay rather than silently skip
-  if (size === offset) return [];
+  let closed: string[] = [];
+  if (size < offset) {
+    // a request journal that closed into its next segment (world-core serve.ts): what was appended there
+    // after the last poll is read from the segment first; any other shorter rewrite (scrub/rebuild) replays
+    const segment = newestSegment(path);
+    let closedSize = -1; try { closedSize = segment ? statSync(segment).size : -1; } catch { /* gone between list and stat */ }
+    if (segment && closedSize >= offset) closed = readNewLines(segment, new Map([[segment, offset]]));
+    offset = 0;
+  }
+  if (size === offset) { offsets.set(path, offset); return closed; }
   const fd = openSync(path, 'r');
   const buffer = Buffer.alloc(size - offset);
   try {
@@ -94,9 +102,17 @@ function readNewLines(path: string, offsets: Map<string, number>): string[] {
     closeSync(fd);
   }
   const lastNewline = buffer.lastIndexOf(0x0a);
-  if (lastNewline < 0) return [];
+  if (lastNewline < 0) { offsets.set(path, offset); return closed; }
   offsets.set(path, offset + lastNewline + 1);
-  return buffer.subarray(0, lastNewline).toString('utf8').split('\n').filter((line) => line.trim() !== '');
+  return [...closed, ...buffer.subarray(0, lastNewline).toString('utf8').split('\n').filter((line) => line.trim() !== '')];
+}
+
+/** A journal's newest closed segment (`<file>.<n>`), or null. */
+function newestSegment(path: string): string | null {
+  const dir = dirname(path); const base = basename(path);
+  let best = 0;
+  try { for (const name of readdirSync(dir)) { const n = name.startsWith(`${base}.`) ? Number(name.slice(base.length + 1)) : NaN; if (Number.isInteger(n) && n > best) best = n; } } catch { return null; }
+  return best ? `${path}.${best}` : null;
 }
 
 /** Local wall-clock `HH:MM:SS.mmm` — the operator is watching a live feed on this machine. */
@@ -123,6 +139,8 @@ function formatEntry(entry: TailEntry, json: boolean): string {
     const creds = (record.credentials ?? [])
       .map((c) => `${c.name ?? '?'}${c.in === 'query' ? '(query)' : ''}=${c.empty ? 'EMPTY' : `${c.scheme ? `${c.scheme} ` : ''}${(c.fp ?? '').replace(/^sha256:/, '').slice(0, 8)}`}`)
       .join(' ');
+    // a link's request entry, written before it forwards: the request on its way, its outcome follows
+    if (record.phase === 'request') return `${formatOccurredAt(entryInstant(entry))} ${entry.service} → ${record.method ?? '?'} ${record.path ?? '?'}${creds ? ` [${creds}]` : ''}`;
     return `${formatOccurredAt(entryInstant(entry))} ${entry.service} ${record.method ?? '?'} ${record.path ?? '?'} ${record.status ?? '?'}${typeof record.ms === 'number' ? ` in ${record.ms}ms` : ''}${creds ? ` [${creds}]` : ''}`;
   }
   return `${formatOccurredAt(record.occurredAt)} ${entry.service} ${record.operation ?? record.op ?? '?'} ${record.subject?.id ?? '?'}`;