@volter/world-core 2.0.18 → 2.0.20

package/dist/src/index.d.ts

@@ -33,7 +33,7 @@ export { SqlWorldStore } from './world-store-sql.js';
 export type { SqlExec } from './world-store-sql.js';
 export { FsBlobStore, MemoryBlobStore, blobDigest, getActiveBlobStore, setActiveBlobStore, withBlobStore, readBlobRange, } from './blob-store.js';
 export type { BlobStore } from './blob-store.js';
-export { applyTwinWrite, applyTwinWriteAtomic, createTwinServer, journalTwinRequest, twinRequestCredentials, readTwinRequestJournal, resolveTwinRead, twinRequestJournalEnabled, twinRequestJournalPath, twinResources, } from './serve.js';
+export { applyTwinWrite, applyTwinWriteAtomic, createTwinServer, journalTwinRequest, twinRequestJournalFailures, twinRequestCredentials, readTwinRequestJournal, resolveTwinRead, twinRequestJournalEnabled, twinRequestJournalPath, twinResources, } from './serve.js';
 export type { AtomicTwinWriteDecision, TwinRequestJournalEntry, TwinResource, TwinWriteInput, TwinWriteResult, } from './serve.js';
 export { createTwinProxy } from './proxy.js';
 export type { TwinProxy, TwinProxyOptions, VendorRoute } from './proxy.js';

package/dist/src/index.js

@@ -55,7 +55,7 @@ export { SqlWorldStore } from "./world-store-sql.js";
 // The blob seam (runtime contract R11): byte storage behind byte-carrying handlers, so a
 // serverless namespace puts bytes in object storage while local worlds keep today's layout.
 export { FsBlobStore, MemoryBlobStore, blobDigest, getActiveBlobStore, setActiveBlobStore, withBlobStore, readBlobRange, } from "./blob-store.js";
-export { applyTwinWrite, applyTwinWriteAtomic, createTwinServer, journalTwinRequest, twinRequestCredentials, readTwinRequestJournal, resolveTwinRead, twinRequestJournalEnabled, twinRequestJournalPath, twinResources, } from "./serve.js";
+export { applyTwinWrite, applyTwinWriteAtomic, createTwinServer, journalTwinRequest, twinRequestJournalFailures, twinRequestCredentials, readTwinRequestJournal, resolveTwinRead, twinRequestJournalEnabled, twinRequestJournalPath, twinResources, } from "./serve.js";
 export { createTwinProxy } from "./proxy.js";
 export { forkTwin, isFork, readForkMeta, } from "./fork.js";
 export { appendAction, appendTransactionCommit, checkPrecondition, confirmAction, listActions, listTransactionCommits, pendingActions, pushablePendingActions, isTwinBookkeeping, pendingTransactionCommits, projectResources, projectOwnerResources, OwnerStoreAmbiguousError, revertAction, TwinActionPreconditionError, subjectAliases, resolveSubjectId, runWithCorrelationId, currentCorrelationId } from "./actions.js";

package/dist/src/serve.d.ts

@@ -24,9 +24,18 @@ export type TwinRequestJournalEntry = {
     ms?: number;
     /** credential-looking headers/query params that arrived, named + fingerprinted, never quoted. */
     credentials?: TwinCredentialShape[];
+    /** `request`: written BEFORE the request is served (an audit device's request entry, so a request whose
+     *  audit cannot be written is refused); its outcome is the entry without a phase written after. */
+    phase?: 'request';
 };
-/** The journal read back: every entry kept for a service, oldest first (an empty list when the journal is off or empty). */
-export declare function readTwinRequestJournal(service: string, root?: string): TwinRequestJournalEntry[];
+/** The journal read back: every entry kept for a service, oldest first (an empty list when the journal is switched off or empty).
+ *  With `since` (epoch ms), segments that ended before it are not read. */
+export declare function readTwinRequestJournal(service: string, root?: string, options?: {
+    since?: number;
+}): TwinRequestJournalEntry[];
+/** Journal lines this process failed to keep, since it started, for one service's journal under `root`
+ *  (a World's request report sums its own twins and links). */
+export declare function twinRequestJournalFailures(service: string, root?: string): number;
 /** Non-reversible, stable fingerprint. 64 bits of sha256 — enough that two distinct credentials
  *  never collide in a journal, far too little to walk back to a real key. */
 export declare function credentialFingerprint(value: string): string;
@@ -35,14 +44,17 @@ export declare function credentialFingerprint(value: string): string;
  * fingerprinted, sorted for stable diffing. Values never leave this function.
  */
 export declare function twinRequestCredentials(headers: Headers | Record<string, string>, url?: string | URL): TwinCredentialShape[];
+/** The audit is kept unless it is switched off (VOLTER_TWIN_REQUEST_JOURNAL=0): no audit is the
+ *  setting someone chooses, never the default. */
 export declare function twinRequestJournalEnabled(env?: Record<string, string | undefined>): boolean;
 /** Where a service's request journal lives: beside its `actions.jsonl`. */
 export declare function twinRequestJournalPath(service: string, root?: string): string;
 /**
- * Append one served request to the journal — a no-op unless VOLTER_TWIN_REQUEST_JOURNAL=1, so
- * the default path does zero I/O. Never throws: an observability append must not fail a serve.
+ * Append one request to the journal — a no-op only when VOLTER_TWIN_REQUEST_JOURNAL=0. Never throws;
+ * answers whether the line was kept (true when the journal is switched off: no audit was chosen), so a
+ * caller that must not act unaudited (a link) can refuse.
  */
-export declare function journalTwinRequest(service: string, entry: TwinRequestJournalEntry, root?: string): void;
+export declare function journalTwinRequest(service: string, entry: TwinRequestJournalEntry, root?: string): boolean;
 export declare const TWIN_JOURNAL_IDENTITY: unique symbol;
 export type TwinJournalIdentity = {
     service: string;
@@ -52,8 +64,7 @@ export declare function vendorFromStack(stack: string | undefined): string | und
 /**
  * Wrap `Bun.serve` so EVERY twin's HTTP surface journals, with no per-pack line. Idempotent
  * (a `Symbol.for` marker survives a second copy of this module) and a strict pass-through when
- * VOLTER_TWIN_REQUEST_JOURNAL is not `1` — the default path adds one function call per request
- * and does zero I/O. Called once at module load, below; exported so a test can assert it.
+ * VOLTER_TWIN_REQUEST_JOURNAL=0. Called once at module load, below; exported so a test can assert it.
  *
  * A pack that knows its own identity may declare it by putting `{service, root}` on the serve
  * options under `TWIN_JOURNAL_IDENTITY` (a symbol key Bun's option reader ignores). Nothing in

package/dist/src/serve.js

@@ -18,27 +18,60 @@ import { hashFieldValue } from "./hash.js";
 import { appendActionIfAbsent, appendActionOccurrence, decideAndAppendAction, projectResources } from "./actions.js";
 import { observeWorldPaths, worldPaths } from "./storage.js";
 import { getActiveWorldStore } from "./world-store.js";
-/** The journal read back: every entry kept for a service, oldest first (an empty list when the journal is off or empty). */
-export function readTwinRequestJournal(service, root) {
+/** The journal's closed segments, oldest first: `requests.jsonl.<n>` beside the live file. */
+function journalSegments(path) {
+    const base = path.slice(path.lastIndexOf('/') + 1);
+    return getActiveWorldStore().list(dirname(path))
+        .map((name) => (name.startsWith(`${base}.`) ? Number(name.slice(base.length + 1)) : NaN))
+        .filter((n) => Number.isInteger(n) && n > 0)
+        .sort((a, b) => a - b)
+        .map((n) => `${path}.${n}`);
+}
+/** The journal read back: every entry kept for a service, oldest first (an empty list when the journal is switched off or empty).
+ *  With `since` (epoch ms), segments that ended before it are not read. */
+export function readTwinRequestJournal(service, root, options = {}) {
     const path = twinRequestJournalPath(service, root);
-    const out = [];
-    for (const file of [`${path}.1`, path]) {
+    const parse = (file) => {
         const text = getActiveWorldStore().read(file);
         if (!text)
-            continue;
+            return [];
+        const rows = [];
         for (const line of text.split('\n')) {
             if (!line)
                 continue;
             try {
-                out.push(JSON.parse(line));
+                rows.push(JSON.parse(line));
             }
-            catch { /* a torn line at rotation */ }
+            catch { /* a torn line */ }
         }
+        return rows;
+    };
+    const kept = [parse(path)];
+    // newest first, stopping at the first segment that ended before `since`
+    for (const file of journalSegments(path).reverse()) {
+        const rows = parse(file);
+        const last = rows[rows.length - 1]?.at;
+        if (options.since !== undefined && last && Date.parse(last) < options.since)
+            break;
+        kept.unshift(rows);
+    }
+    return kept.flat();
+}
+/** Lines not kept, per journal: keyed by the journal's own path, so a process serving many Worlds
+ *  (a host; an isolate holding several) answers for each World alone. */
+const journalFailures = new Map();
+/** Journal lines this process failed to keep, since it started, for one service's journal under `root`
+ *  (a World's request report sums its own twins and links). */
+export function twinRequestJournalFailures(service, root) {
+    try {
+        return journalFailures.get(twinRequestJournalPath(service, root)) ?? 0;
+    }
+    catch {
+        return 0;
     }
-    return out;
 }
-/** ~1 MB cap before a one-deep rotation — small enough to never matter on disk, large enough for
- *  tens of thousands of entries (a shape line is ~80 bytes). */
+/** ~1 MB per segment: tens of thousands of entries (a shape line is ~80 bytes), and a report over a
+ *  recent period reads only the segments that reach into it. */
 const REQUEST_JOURNAL_MAX_BYTES = 1_000_000;
 /**
  * Does this header/param NAME look like it carries a credential? Deliberately a generic word
@@ -102,42 +135,52 @@ export function twinRequestCredentials(headers, url) {
     catch { /* an unparseable URL must not fail a serve */ }
     return shapes.sort((a, b) => (a.in === b.in ? a.name.localeCompare(b.name) : a.in.localeCompare(b.in)));
 }
+/** The audit is kept unless it is switched off (VOLTER_TWIN_REQUEST_JOURNAL=0): no audit is the
+ *  setting someone chooses, never the default. */
 export function twinRequestJournalEnabled(env = process.env) {
-    return env.VOLTER_TWIN_REQUEST_JOURNAL === '1';
+    return env.VOLTER_TWIN_REQUEST_JOURNAL !== '0';
 }
 /** Where a service's request journal lives: beside its `actions.jsonl`. */
 export function twinRequestJournalPath(service, root) {
     return join(dirname(worldPaths(service, root).events), 'requests.jsonl');
 }
 /**
- * Append one served request to the journal — a no-op unless VOLTER_TWIN_REQUEST_JOURNAL=1, so
- * the default path does zero I/O. Never throws: an observability append must not fail a serve.
+ * Append one request to the journal — a no-op only when VOLTER_TWIN_REQUEST_JOURNAL=0. Never throws;
+ * answers whether the line was kept (true when the journal is switched off: no audit was chosen), so a
+ * caller that must not act unaudited (a link) can refuse.
  */
 export function journalTwinRequest(service, entry, root) {
     if (!twinRequestJournalEnabled())
-        return;
+        return true;
+    const line = JSON.stringify({
+        at: entry.at ?? new Date().toISOString(),
+        ...(entry.phase ? { phase: entry.phase } : {}),
+        method: entry.method.toUpperCase(),
+        path: entry.path.split('?')[0], // the query STRING never lands; its credential params do, named + fingerprinted
+        status: entry.status,
+        ...(typeof entry.ms === 'number' ? { ms: entry.ms } : {}),
+        ...(entry.credentials?.length ? { credentials: entry.credentials } : {}),
+    });
+    let path;
     try {
         const store = getActiveWorldStore();
-        const path = twinRequestJournalPath(service, root);
+        path = twinRequestJournalPath(service, root);
         store.mkdir(dirname(path));
-        const size = store.stat(path)?.size ?? 0;
-        if (size >= REQUEST_JOURNAL_MAX_BYTES) {
-            // one-deep rotation: the previous overflow is overwritten, the live file starts fresh.
-            store.writeAtomic(`${path}.1`, store.read(path) ?? '');
+        if ((store.stat(path)?.size ?? 0) >= REQUEST_JOURNAL_MAX_BYTES) {
+            // the live file closes into the next segment; no segment is ever overwritten or removed (a crash between
+            // the two writes leaves the live lines in both: repeated in the next segment, never lost)
+            const next = Number(journalSegments(path).pop()?.slice(path.length + 1) ?? 0) + 1;
+            store.writeAtomic(`${path}.${next}`, store.read(path) ?? '');
             store.write(path, '');
         }
-        const line = JSON.stringify({
-            at: entry.at ?? new Date().toISOString(),
-            method: entry.method.toUpperCase(),
-            path: entry.path.split('?')[0], // the query STRING never lands; its credential params do, named + fingerprinted
-            status: entry.status,
-            ...(typeof entry.ms === 'number' ? { ms: entry.ms } : {}),
-            ...(entry.credentials?.length ? { credentials: entry.credentials } : {}),
-        });
         store.append(path, `${line}\n`);
+        return true;
     }
-    catch {
-        // journaling is best-effort observability; the serve path must not care
+    catch (error) {
+        const key = path ?? `${root ?? ''}/${service}`;
+        journalFailures.set(key, (journalFailures.get(key) ?? 0) + 1);
+        console.error(`[request-journal] ${service}: a line was not kept: ${error.message}`);
+        return false;
     }
 }
 // ── how a wrapped `Bun.serve` learns which twin it is ──────────────────────────────────────────
@@ -196,8 +239,7 @@ export function vendorFromStack(stack) {
 /**
  * Wrap `Bun.serve` so EVERY twin's HTTP surface journals, with no per-pack line. Idempotent
  * (a `Symbol.for` marker survives a second copy of this module) and a strict pass-through when
- * VOLTER_TWIN_REQUEST_JOURNAL is not `1` — the default path adds one function call per request
- * and does zero I/O. Called once at module load, below; exported so a test can assert it.
+ * VOLTER_TWIN_REQUEST_JOURNAL=0. Called once at module load, below; exported so a test can assert it.
  *
  * A pack that knows its own identity may declare it by putting `{service, root}` on the serve
  * options under `TWIN_JOURNAL_IDENTITY` (a symbol key Bun's option reader ignores). Nothing in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-core",
-  "version": "2.0.18",
+  "version": "2.0.20",
   "description": "The kernel of Volter World: one log per twin, branches as pointers, checkpoints, the fold that keeps a twin current, the head that performs a write against the vendor, references, and the git plane. A twin package builds on it; the runtime serves it.",
   "keywords": [
     "twin",

package/src/index.ts

@@ -162,6 +162,7 @@ export {
   applyTwinWriteAtomic,
   createTwinServer,
   journalTwinRequest,
+  twinRequestJournalFailures,
   twinRequestCredentials,
   readTwinRequestJournal,
   resolveTwinRead,

package/src/serve.ts

@@ -24,10 +24,12 @@ import { getActiveWorldStore } from './world-store.ts';
 // ── the request journal: the INSPECT half of the read path ─────────────────────────────────────
 // `actions.jsonl` records MUTATIONS only, so a twin's READS are invisible to `volter-world tail`
 // — an empty-catalog GET that 404s leaves no trace, and "did the app even ask?" is unanswerable.
-// The journal is the minimal honest answer: an OPT-IN (VOLTER_TWIN_REQUEST_JOURNAL=1) per-twin
-// `requests.jsonl` beside `actions.jsonl`, one line per served HTTP request. Size-capped: at ~1 MB
-// the file rotates once to `requests.jsonl.1` (previous rotation overwritten), so an enabled
-// journal can never grow unbounded. `volter-world tail --requests` merges these lines live.
+// The journal is the minimal honest answer: a per-twin `requests.jsonl` beside `actions.jsonl`, one
+// line per served HTTP request, kept unless switched off (VOLTER_TWIN_REQUEST_JOURNAL=0). It is an
+// audit trail, so nothing in it is ever deleted: at ~1 MB the live file closes into the next numbered
+// segment (`requests.jsonl.1`, `.2`, … oldest first) and a fresh one starts. An append that fails is
+// said on stderr and counted per journal (`twinRequestJournalFailures`), never silent. `volter-world tail
+// --requests` merges the live lines.
 //
 // WHAT A LINE CARRIES. `{at, method, path, status}` — the shape — plus, when the request presented
 // one, the CREDENTIAL SHAPE: which header/query-param NAMES carried a credential-looking value,
@@ -82,21 +84,54 @@ export type TwinRequestJournalEntry = {
   ms?: number;
   /** credential-looking headers/query params that arrived, named + fingerprinted, never quoted. */
   credentials?: TwinCredentialShape[];
+  /** `request`: written BEFORE the request is served (an audit device's request entry, so a request whose
+   *  audit cannot be written is refused); its outcome is the entry without a phase written after. */
+  phase?: 'request';
 };
 
-/** The journal read back: every entry kept for a service, oldest first (an empty list when the journal is off or empty). */
-export function readTwinRequestJournal(service: string, root?: string): TwinRequestJournalEntry[] {
+/** The journal's closed segments, oldest first: `requests.jsonl.<n>` beside the live file. */
+function journalSegments(path: string): string[] {
+  const base = path.slice(path.lastIndexOf('/') + 1);
+  return getActiveWorldStore().list(dirname(path))
+    .map((name) => (name.startsWith(`${base}.`) ? Number(name.slice(base.length + 1)) : NaN))
+    .filter((n) => Number.isInteger(n) && n > 0)
+    .sort((a, b) => a - b)
+    .map((n) => `${path}.${n}`);
+}
+
+/** The journal read back: every entry kept for a service, oldest first (an empty list when the journal is switched off or empty).
+ *  With `since` (epoch ms), segments that ended before it are not read. */
+export function readTwinRequestJournal(service: string, root?: string, options: { since?: number } = {}): TwinRequestJournalEntry[] {
   const path = twinRequestJournalPath(service, root);
-  const out: TwinRequestJournalEntry[] = [];
-  for (const file of [`${path}.1`, path]) {
-    const text = getActiveWorldStore().read(file); if (!text) continue;
-    for (const line of text.split('\n')) { if (!line) continue; try { out.push(JSON.parse(line) as TwinRequestJournalEntry); } catch { /* a torn line at rotation */ } }
+  const parse = (file: string): TwinRequestJournalEntry[] => {
+    const text = getActiveWorldStore().read(file); if (!text) return [];
+    const rows: TwinRequestJournalEntry[] = [];
+    for (const line of text.split('\n')) { if (!line) continue; try { rows.push(JSON.parse(line) as TwinRequestJournalEntry); } catch { /* a torn line */ } }
+    return rows;
+  };
+  const kept: TwinRequestJournalEntry[][] = [parse(path)];
+  // newest first, stopping at the first segment that ended before `since`
+  for (const file of journalSegments(path).reverse()) {
+    const rows = parse(file);
+    const last = rows[rows.length - 1]?.at;
+    if (options.since !== undefined && last && Date.parse(last) < options.since) break;
+    kept.unshift(rows);
   }
-  return out;
+  return kept.flat();
 }
 
-/** ~1 MB cap before a one-deep rotation — small enough to never matter on disk, large enough for
- *  tens of thousands of entries (a shape line is ~80 bytes). */
+/** Lines not kept, per journal: keyed by the journal's own path, so a process serving many Worlds
+ *  (a host; an isolate holding several) answers for each World alone. */
+const journalFailures = new Map<string, number>();
+/** Journal lines this process failed to keep, since it started, for one service's journal under `root`
+ *  (a World's request report sums its own twins and links). */
+export function twinRequestJournalFailures(service: string, root?: string): number {
+  try { return journalFailures.get(twinRequestJournalPath(service, root)) ?? 0; } catch { return 0; }
+}
+
+
+/** ~1 MB per segment: tens of thousands of entries (a shape line is ~80 bytes), and a report over a
+ *  recent period reads only the segments that reach into it. */
 const REQUEST_JOURNAL_MAX_BYTES = 1_000_000;
 
 /**
@@ -156,8 +191,10 @@ export function twinRequestCredentials(headers: Headers | Record<string, string>
   return shapes.sort((a, b) => (a.in === b.in ? a.name.localeCompare(b.name) : a.in.localeCompare(b.in)));
 }
 
+/** The audit is kept unless it is switched off (VOLTER_TWIN_REQUEST_JOURNAL=0): no audit is the
+ *  setting someone chooses, never the default. */
 export function twinRequestJournalEnabled(env: Record<string, string | undefined> = process.env): boolean {
-  return env.VOLTER_TWIN_REQUEST_JOURNAL === '1';
+  return env.VOLTER_TWIN_REQUEST_JOURNAL !== '0';
 }
 
 /** Where a service's request journal lives: beside its `actions.jsonl`. */
@@ -166,32 +203,40 @@ export function twinRequestJournalPath(service: string, root?: string): string {
 }
 
 /**
- * Append one served request to the journal — a no-op unless VOLTER_TWIN_REQUEST_JOURNAL=1, so
- * the default path does zero I/O. Never throws: an observability append must not fail a serve.
+ * Append one request to the journal — a no-op only when VOLTER_TWIN_REQUEST_JOURNAL=0. Never throws;
+ * answers whether the line was kept (true when the journal is switched off: no audit was chosen), so a
+ * caller that must not act unaudited (a link) can refuse.
  */
-export function journalTwinRequest(service: string, entry: TwinRequestJournalEntry, root?: string): void {
-  if (!twinRequestJournalEnabled()) return;
+export function journalTwinRequest(service: string, entry: TwinRequestJournalEntry, root?: string): boolean {
+  if (!twinRequestJournalEnabled()) return true;
+  const line = JSON.stringify({
+    at: entry.at ?? new Date().toISOString(),
+    ...(entry.phase ? { phase: entry.phase } : {}),
+    method: entry.method.toUpperCase(),
+    path: entry.path.split('?')[0], // the query STRING never lands; its credential params do, named + fingerprinted
+    status: entry.status,
+    ...(typeof entry.ms === 'number' ? { ms: entry.ms } : {}),
+    ...(entry.credentials?.length ? { credentials: entry.credentials } : {}),
+  });
+  let path: string | undefined;
   try {
     const store = getActiveWorldStore();
-    const path = twinRequestJournalPath(service, root);
+    path = twinRequestJournalPath(service, root);
     store.mkdir(dirname(path));
-    const size = store.stat(path)?.size ?? 0;
-    if (size >= REQUEST_JOURNAL_MAX_BYTES) {
-      // one-deep rotation: the previous overflow is overwritten, the live file starts fresh.
-      store.writeAtomic(`${path}.1`, store.read(path) ?? '');
+    if ((store.stat(path)?.size ?? 0) >= REQUEST_JOURNAL_MAX_BYTES) {
+      // the live file closes into the next segment; no segment is ever overwritten or removed (a crash between
+      // the two writes leaves the live lines in both: repeated in the next segment, never lost)
+      const next = Number(journalSegments(path).pop()?.slice(path.length + 1) ?? 0) + 1;
+      store.writeAtomic(`${path}.${next}`, store.read(path) ?? '');
       store.write(path, '');
     }
-    const line = JSON.stringify({
-      at: entry.at ?? new Date().toISOString(),
-      method: entry.method.toUpperCase(),
-      path: entry.path.split('?')[0], // the query STRING never lands; its credential params do, named + fingerprinted
-      status: entry.status,
-      ...(typeof entry.ms === 'number' ? { ms: entry.ms } : {}),
-      ...(entry.credentials?.length ? { credentials: entry.credentials } : {}),
-    });
     store.append(path, `${line}\n`);
-  } catch {
-    // journaling is best-effort observability; the serve path must not care
+    return true;
+  } catch (error) {
+    const key = path ?? `${root ?? ''}/${service}`;
+    journalFailures.set(key, (journalFailures.get(key) ?? 0) + 1);
+    console.error(`[request-journal] ${service}: a line was not kept: ${(error as Error).message}`);
+    return false;
   }
 }
 
@@ -260,8 +305,7 @@ export function vendorFromStack(stack: string | undefined): string | undefined {
 /**
  * Wrap `Bun.serve` so EVERY twin's HTTP surface journals, with no per-pack line. Idempotent
  * (a `Symbol.for` marker survives a second copy of this module) and a strict pass-through when
- * VOLTER_TWIN_REQUEST_JOURNAL is not `1` — the default path adds one function call per request
- * and does zero I/O. Called once at module load, below; exported so a test can assert it.
+ * VOLTER_TWIN_REQUEST_JOURNAL=0. Called once at module load, below; exported so a test can assert it.
  *
  * A pack that knows its own identity may declare it by putting `{service, root}` on the serve
  * options under `TWIN_JOURNAL_IDENTITY` (a symbol key Bun's option reader ignores). Nothing in