@volter/world-core 2.0.18 → 2.0.19

package/dist/src/serve.d.ts

@@ -25,7 +25,7 @@ export type TwinRequestJournalEntry = {
     /** credential-looking headers/query params that arrived, named + fingerprinted, never quoted. */
     credentials?: TwinCredentialShape[];
 };
-/** The journal read back: every entry kept for a service, oldest first (an empty list when the journal is off or empty). */
+/** The journal read back: every entry kept for a service, oldest first (an empty list when the journal is switched off or empty). */
 export declare function readTwinRequestJournal(service: string, root?: string): TwinRequestJournalEntry[];
 /** 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. */
@@ -35,12 +35,14 @@ 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 served request to the journal — a no-op only when VOLTER_TWIN_REQUEST_JOURNAL=0.
+ * Never throws: an append must not fail a serve.
  */
 export declare function journalTwinRequest(service: string, entry: TwinRequestJournalEntry, root?: string): void;
 export declare const TWIN_JOURNAL_IDENTITY: unique symbol;
@@ -52,8 +54,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,7 +18,7 @@ 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). */
+/** The journal read back: every entry kept for a service, oldest first (an empty list when the journal is switched off or empty). */
 export function readTwinRequestJournal(service, root) {
     const path = twinRequestJournalPath(service, root);
     const out = [];
@@ -102,16 +102,18 @@ 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 served request to the journal — a no-op only when VOLTER_TWIN_REQUEST_JOURNAL=0.
+ * Never throws: an append must not fail a serve.
  */
 export function journalTwinRequest(service, entry, root) {
     if (!twinRequestJournalEnabled())
@@ -137,7 +139,7 @@ export function journalTwinRequest(service, entry, root) {
         store.append(path, `${line}\n`);
     }
     catch {
-        // journaling is best-effort observability; the serve path must not care
+        // the append must not fail the serve it records
     }
 }
 // ── how a wrapped `Bun.serve` learns which twin it is ──────────────────────────────────────────
@@ -196,8 +198,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.19",
   "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/serve.ts

@@ -24,9 +24,9 @@ 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
+// 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). Size-capped:
+// at ~1 MB the file rotates once to `requests.jsonl.1` (previous rotation overwritten), so the
 // journal can never grow unbounded. `volter-world tail --requests` merges these lines live.
 //
 // WHAT A LINE CARRIES. `{at, method, path, status}` — the shape — plus, when the request presented
@@ -84,7 +84,7 @@ export type TwinRequestJournalEntry = {
   credentials?: TwinCredentialShape[];
 };
 
-/** The journal read back: every entry kept for a service, oldest first (an empty list when the journal is off or empty). */
+/** The journal read back: every entry kept for a service, oldest first (an empty list when the journal is switched off or empty). */
 export function readTwinRequestJournal(service: string, root?: string): TwinRequestJournalEntry[] {
   const path = twinRequestJournalPath(service, root);
   const out: TwinRequestJournalEntry[] = [];
@@ -156,8 +156,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,8 +168,8 @@ 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 served request to the journal — a no-op only when VOLTER_TWIN_REQUEST_JOURNAL=0.
+ * Never throws: an append must not fail a serve.
  */
 export function journalTwinRequest(service: string, entry: TwinRequestJournalEntry, root?: string): void {
   if (!twinRequestJournalEnabled()) return;
@@ -191,7 +193,7 @@ export function journalTwinRequest(service: string, entry: TwinRequestJournalEnt
     });
     store.append(path, `${line}\n`);
   } catch {
-    // journaling is best-effort observability; the serve path must not care
+    // the append must not fail the serve it records
   }
 }
 
@@ -260,8 +262,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