@volter/world-core 2.0.0 → 2.0.1

package/src/storage.ts

@@ -59,13 +59,25 @@ function assertServiceName(service: string): string {
  */
 let worldPathsObserver: ((service: string, root: string | undefined) => void) | undefined;
 
-export function observeWorldPaths(observer: (service: string, root: string | undefined) => void): void {
+/** Install the observer; the one it replaces is returned (a test puts it back). */
+export function observeWorldPaths(observer: ((service: string, root: string | undefined) => void) | undefined): ((service: string, root: string | undefined) => void) | undefined {
+  const previous = worldPathsObserver;
   worldPathsObserver = observer;
+  return previous;
+}
+
+/** While > 0, a read of ANOTHER pack's store is in progress (`projectOwnerResources`): that is not the request's twin
+ *  saying who it is, so it claims no journal identity. */
+let identityQuiet = 0;
+/** Run `fn` without its worldPaths calls reaching the identity observer. */
+export function withoutIdentityClaim<T>(fn: () => T): T {
+  identityQuiet++;
+  try { return fn(); } finally { identityQuiet--; }
 }
 
 export function worldPaths(service: string, root?: string): WorldPaths {
   const safeService = assertServiceName(service);
-  worldPathsObserver?.(safeService, root);
+  if (identityQuiet === 0) worldPathsObserver?.(safeService, root);
   const resolvedRoot = projectRoot(root);
   const dir = join(worldStateRoot(root), safeService);
   return {
@@ -81,6 +93,44 @@ export function worldPaths(service: string, root?: string): WorldPaths {
   };
 }
 
+/**
+ * THE WORLD'S DATA DIRECTORY, as the World runtime hands it to every service it starts. Each twin of a World runs on
+ * its own root, `<data>/<service id>` (world-runtime's startService and startColocatedServices), so one twin's
+ * `.volter/world/<service>` is not another's; `ownerStoreRoots` finds a store across them.
+ */
+export const WORLD_DATA_ENV = 'VOLTER_WORLD_DATA';
+
+/** Does `root` hold `service`'s store: its log or its branch record (what a write or a fork leaves; a read leaves
+ *  neither)? The paths are built without worldPaths, so a probe claims no journal identity. */
+function holdsStore(service: string, root: string): boolean {
+  const dir = join(worldStateRoot(root), service);
+  const store = getActiveWorldStore();
+  return ['events.jsonl', 'actions.jsonl', 'branch.json'].some((file) => store.exists(join(dir, file)));
+}
+
+/**
+ * The roots that hold the store of `owner` (ANOTHER pack's, read by contract: architecture A3), for a twin on `root`:
+ *   - `[root]` when `root` itself holds that store (both packs on one root: `volter world serve`, a test, a pack serving
+ *     several services on its root, as aws does);
+ *   - else, when `root` is one of a World's service roots (a directory directly under the World's data directory), every
+ *     other service root there that holds it (usually one; two when the World runs the owning pack twice);
+ *   - else `[]`: nothing is issued yet, or the twin runs outside a World.
+ * Only a declared cross-pack read resolves through here (`projectOwnerResources`); a pack's reads of its OWN store never
+ * leave its root, so a fresh twin never reads a sibling that happens to run the same pack. Not memoized: it is a few
+ * stats per service root, and a store that appears after the first read (the owner's first write) must be found.
+ */
+export function ownerStoreRoots(owner: string, root?: string): string[] {
+  const safeOwner = assertServiceName(owner);
+  const own = projectRoot(root);
+  if (holdsStore(safeOwner, own)) return [own];
+  const data = typeof process === 'undefined' ? undefined : process.env[WORLD_DATA_ENV];
+  if (!data || dirname(own) !== resolve(data)) return [];
+  return getActiveWorldStore().list(dirname(own))
+    .map((name) => join(dirname(own), name))
+    .filter((candidate) => candidate !== own && holdsStore(safeOwner, candidate))
+    .sort();
+}
+
 function readJsonl<T>(path: string): T[] {
   const rows: T[] = [];
   for (const [index, line] of getActiveWorldStore().readLines(path).entries()) {

package/src/world-clock.ts

@@ -6,28 +6,31 @@
 // is the operator door (set / advance / show). No file, or no env → real wall-clock time,
 // exactly the pre-clock behavior; a world only has scripted time when its operator says so.
 //
-// File format: a single ISO-8601 line (a FROZEN instant). Every read returns exactly that
-// instant — deterministic by construction. Advancing time is an explicit operator act, never
-// a background drift.
-// Read through the ACTIVE WorldStore, not node:fs: the clock file is world state, and a
-// hydrated serverless namespace must carry its frozen instant with it (runtime contract R11–R14
-// — a MemoryWorldStore world that read the clock off the host filesystem would silently
-// serve the HOST's time, the exact two-services-disagreeing-about-now defect below).
+// File format (world-clock.cjs, the one home of it, shared with the injector that gives an application process the
+// same time): a FROZEN instant, one ISO-8601 line, every read returning exactly that instant; or a RUNNING clock,
+// `<instant> from <wall instant>`, the World's time at a moment of the machine's, running on at the machine's pace (a
+// World serving an application). Moving time is an explicit operator act either way, never a background drift.
 import { getActiveWorldStore } from './world-store.ts';
+import clockForm from '../world-clock.cjs';
 
 export const WORLD_CLOCK_ENV = 'TWIN_WORLD_CLOCK_FILE';
 
-/** The world's "now": the frozen instant in the clock file when one is configured and
- *  parseable; real wall-clock time otherwise. */
+/** The machine's own time: the real Date.now even where the injector gives the process the World's time (inject.cjs
+ *  leaves the original under this symbol), so a running clock's offset is applied once. */
+const machineNow = (): number => {
+  const real = (globalThis as Record<symbol, unknown>)[Symbol.for('volter.machineDateNow')];
+  return typeof real === 'function' ? (real as () => number)() : Date.now();
+};
+
+/** The world's "now": the clock file's time when one is configured (its frozen instant, or a running clock's time
+ *  now); real wall-clock time otherwise. */
 export function worldNow(): string {
   const file = process.env[WORLD_CLOCK_ENV];
   if (file && getActiveWorldStore().exists(file)) {
-    const raw = (getActiveWorldStore().read(file) ?? '').trim();
-    const parsed = Date.parse(raw);
-    if (!Number.isNaN(parsed)) return new Date(parsed).toISOString();
-    // A configured-but-corrupt clock is a WORLD defect — fail loudly, never silently drift
-    // back to wall-clock (two services disagreeing about now breaks the world).
-    throw new Error(`world clock: ${file} does not contain a parseable ISO-8601 instant (got ${JSON.stringify(raw.slice(0, 40))})`);
+    // A configured-but-corrupt clock is a WORLD defect — parseClock fails loudly, never silently drifting back to
+    // wall-clock (two services disagreeing about now breaks the world).
+    const clock = clockForm.parseClock(getActiveWorldStore().read(file) ?? '');
+    return new Date(clockForm.clockNowMs(clock, machineNow())).toISOString();
   }
-  return new Date().toISOString();
+  return new Date(machineNow()).toISOString();
 }

package/vendor-hosts.cjs

@@ -22,7 +22,7 @@
 //
 // THE SHARED-HOST RULE (Cal.com incident, 2026-08): a shared-host predicate must claim ONLY the
 // paths its twin actually serves — never "the rest of the host". Claiming the remainder is how
-// every `@googleapis/calendar` call (37 methods, all defaulting to www.googleapis.com) was routed
+// every `@googleapis/calendar` call (all of its methods default to www.googleapis.com) was routed
 // into the googleauth/gemini twin and answered with a plausible Google-shaped 404: a mis-route
 // that fails OPEN and PLAUSIBLE, strictly worse than a coverage gap. An UNCLAIMED path on a
 // claimed host is refused LOUDLY instead (see unclaimedTwinnedHostPathMessage below): the error
@@ -32,7 +32,7 @@
  * Exactly the routes gemini-twin.ts §googleauth models: `POST /token` (the oauth2.googleapis.com
  * path, also answered on the legacy host) and `POST /oauth2/v4/token` (the legacy
  * www.googleapis.com token path older google-auth-library versions default to). NOTHING else:
- * /calendar/v3/*, /drive/v3/*, … are other Google products with no twin in this repo, and
+ * /calendar/v3/* (the googlecalendar pack's), /drive/v3/*, … are other Google products, and
  * claiming them would mis-route those SDKs into an auth twin that answers with vendor-shaped
  * 404s (the Cal.com incident).
  */

package/world-clock.cjs

@@ -0,0 +1,40 @@
+'use strict';
+// THE WORLD CLOCK'S FORM — the one home of how a clock file reads (dependency-free, side-effect free), shared by the
+// twins' worldNow() (src/world-clock.ts, reading through the active WorldStore) and the injector, which gives an
+// application process the same time (inject.cjs, WORLD TIME).
+//
+// A clock file holds one line in one of two forms:
+//   · FROZEN:  `<ISO-8601 instant>` — every read answers exactly that instant (scripted time: lives, seeds, a story);
+//   · RUNNING: `<ISO-8601 instant> from <ISO-8601 wall instant>` — the World's time was <instant> when the machine's was
+//     <wall instant>, and runs on at the machine's pace from there: a World serving an application moves time this way
+//     (`volter-world clock <world> shift <N s|m|h|d>`), since a frozen instant would stop the application's time.
+// No file: the machine's time.
+
+/** The clock a file's text states, or throws on text that states neither form. */
+function parseClock(raw) {
+  const text = String(raw ?? '').trim();
+  const m = /^(\S+)\s+from\s+(\S+)$/.exec(text);
+  if (m) {
+    const at = Date.parse(m[1]);
+    const since = Date.parse(m[2]);
+    if (!Number.isNaN(at) && !Number.isNaN(since)) return { kind: 'running', at, since };
+  } else {
+    const at = Date.parse(text);
+    if (!Number.isNaN(at)) return { kind: 'frozen', at };
+  }
+  throw new Error(`world clock: expected an ISO-8601 instant, or "<instant> from <instant>", got ${JSON.stringify(text.slice(0, 60))}`);
+}
+
+/** The World's time in ms for a parsed clock, at the machine's time `wallMs`. */
+function clockNowMs(clock, wallMs) {
+  return clock.kind === 'running' ? clock.at + (wallMs - clock.since) : clock.at;
+}
+
+/** A clock's text: frozen at `atMs`, or running from `atMs` as of the machine's `sinceMs`. */
+function formatClock(clock) {
+  return clock.kind === 'running'
+    ? `${new Date(clock.at).toISOString()} from ${new Date(clock.since).toISOString()}`
+    : new Date(clock.at).toISOString();
+}
+
+module.exports = { parseClock, clockNowMs, formatClock };

package/world-clock.d.cts

@@ -0,0 +1,4 @@
+export type WorldClock = { kind: 'frozen'; at: number } | { kind: 'running'; at: number; since: number };
+export function parseClock(raw: string | null | undefined): WorldClock;
+export function clockNowMs(clock: WorldClock, wallMs: number): number;
+export function formatClock(clock: WorldClock): string;