@volter/world-runtime 3.0.88 → 3.0.90

package/dist/src/cli-commands.js

@@ -4,10 +4,10 @@ import { optionValue, ownerOption } from "./cli-args.js";
 import { printReady } from "./up-cli.js";
 import { spawn, spawnSync } from 'node:child_process';
 import { createRequire } from 'node:module';
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { activateScript, branchWorld, checkoutWorld, fetchFromOrigin, pushWorldChangeset, rebaseWorldChangeset, resetWorld, seedWorld, worldOrigin, approveWorldChangeset, checkPrerequisites, coverWorld, createWorldChangeset, diffWorld, doctorWorld, downWorld, findWorldChangeset, formatCoverageReport, formatInitReport, formatPrerequisiteChecks, formatProjectInspection, initWorld, inspectProject, isRemoteWorldRef, listWorldChangesets, listWorlds, markWorld, migrateWorldConfig, readReflectRoutes, reflectRoutesPath, replayWorldChangeset, resolveWorldRef, attachWorld, retireWorldConsumers, runWorld, shareWorldServices, shellWorld, startReflectFront, startReflectResolver, statusWorld, statusWorldChangeset, tailWorldActions, unshareWorld, urlsWorld, urlWorld, verifyWorldChangeset, worldManifest, writeReflectRoutes, readReflectManifest, writeReflectManifest, clearReflectManifest, composeOverrideForReflect, splitDockerComposeArgs, dockerComposeWithOverride, ATTACHED_CA_PATH } from "./index.js";
+import { join, resolve } from 'node:path';
+import { activateScript, branchWorld, checkoutWorld, fetchFromOrigin, pushWorldChangeset, rebaseWorldChangeset, resetWorld, seedWorld, worldOrigin, approveWorldChangeset, writeWorldClock, checkPrerequisites, coverWorld, createWorldChangeset, diffWorld, doctorWorld, downWorld, findWorldChangeset, formatCoverageReport, formatInitReport, formatPrerequisiteChecks, formatProjectInspection, initWorld, inspectProject, isRemoteWorldRef, listWorldChangesets, listWorlds, markWorld, migrateWorldConfig, readReflectRoutes, reflectRoutesPath, replayWorldChangeset, resolveWorldRef, attachWorld, retireWorldConsumers, runWorld, shareWorldServices, shellWorld, startReflectFront, startReflectResolver, statusWorld, statusWorldChangeset, tailWorldActions, unshareWorld, urlsWorld, urlWorld, verifyWorldChangeset, worldManifest, writeReflectRoutes, readReflectManifest, writeReflectManifest, clearReflectManifest, composeOverrideForReflect, splitDockerComposeArgs, dockerComposeWithOverride, ATTACHED_CA_PATH } from "./index.js";
 import { formatApplication, formatChangeset, formatRebaseReport, formatChangesetStatus, formatLedgerDelta, formatReplayReport, formatVerification, parseVerifierExpression } from '@volter/world-core/runtime';
 import { advertiseWorldManifest, fetchRemoteManifest, MANIFEST_PATH, remoteAttachEnv, startManifestServer } from "./serve.js";
 import { clockFile, instanceDir, pruneWorlds, withoutVaultSignIn } from "./runtime.js";
@@ -539,8 +539,7 @@ export async function main() {
         const file = clockFile(rootDir, name);
         const current = existsSync(file) ? clockForm.parseClock(readFileSync(file, 'utf8')) : null;
         const write = (clock) => {
-            mkdirSync(dirname(file), { recursive: true });
-            writeFileSync(file, `${clockForm.formatClock(clock)}\n`);
+            writeWorldClock(name, rootDir, clock);
             // the World's time now, bare, as scripts read it (`show` says which form)
             console.log(new Date(clockForm.clockNowMs(clock, Date.now())).toISOString());
         };

package/dist/src/clock.d.ts

@@ -0,0 +1,3 @@
+import type { WorldClock } from '@volter/world-core/world-clock';
+export declare function writeWorldClock(name: string, root: string, clock: WorldClock): void;
+export declare function setWorldClock(name: string, root: string, at: string): void;

package/dist/src/clock.js

@@ -0,0 +1,18 @@
+// The programmatic counterpart of the operator's clock command. Callers own their World root; only invoked
+// operations read or write it. Formatting belongs to the kernel's shared clock contract.
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname } from 'node:path';
+import { clockFile } from "./runtime.js";
+const clockForm = createRequire(import.meta.url)('@volter/world-core/world-clock');
+export function writeWorldClock(name, root, clock) {
+    const file = clockFile(root, name);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, `${clockForm.formatClock(clock)}\n`);
+}
+export function setWorldClock(name, root, at) {
+    const parsed = Date.parse(at);
+    if (Number.isNaN(parsed))
+        throw new Error(`clock set: ${JSON.stringify(at)} is not an ISO-8601 instant`);
+    writeWorldClock(name, root, { kind: 'frozen', at: parsed });
+}

package/dist/src/index.d.ts

@@ -22,6 +22,7 @@ export type { CoverageReport, CoverageRow, CoverageStatus, CoverageOptions, Repo
 export { formatInitReport, initWorld, packCatalog, planWorldInit, renderEnvFile, writeWorldInit } from './init.js';
 export { STATE_GITIGNORE } from './init.js';
 export { clockFile, instanceDir } from './runtime.js';
+export { setWorldClock, writeWorldClock } from './clock.js';
 export { checkoutCatalog, findInstalledPackage, installedCatalog, resolveCatalog, resolveServicePackage, twinPackageName, TWIN_PACKAGE_PREFIX, type Catalog, type CatalogKind, packCli, packEntry } from './catalog.js';
 export { ISSUE_ENV_PREFIX, MINT_ENV } from './schema.js';
 export type { EnvDisposition, InitEnvRow, InitInfraStub, InitOptions, InitPlan, InitResult, InitVendorPlan, InitWiring, } from './init.js';

package/dist/src/index.js

@@ -20,6 +20,7 @@ export { coverWorld, detectRepoVendors, envNameVendor, formatCoverageReport, inj
 export { formatInitReport, initWorld, packCatalog, planWorldInit, renderEnvFile, writeWorldInit } from "./init.js";
 export { STATE_GITIGNORE } from "./init.js";
 export { clockFile, instanceDir } from "./runtime.js";
+export { setWorldClock, writeWorldClock } from "./clock.js";
 export { checkoutCatalog, findInstalledPackage, installedCatalog, resolveCatalog, resolveServicePackage, twinPackageName, TWIN_PACKAGE_PREFIX, packCli, packEntry } from "./catalog.js";
 export { ISSUE_ENV_PREFIX, MINT_ENV } from "./schema.js";
 export { deriveWorldManifest, findWorldRefFile, isRemoteWorldRef, resolveWorldRef, WORLD_REF_FILE, worldManifest, } from "./attach.js";

package/dist/src/runtime.d.ts

@@ -67,7 +67,7 @@ export type WorldUrlInfo = {
  * the instance dir — one layout owner, no duplicated path knowledge. */
 /** THE WORLD CLOCK file (TWIN-PROGRAMMING-MODEL P3): a single frozen ISO instant every twin
  *  stamps from (kernel worldNow()); absent → real wall-clock. Written only by the
- *  `volter-world clock` operator door — time is physics, advanced explicitly, never drifting. */
+ *  `volter-world clock` operator door or its runtime API — time is physics, advanced explicitly, never drifting. */
 export declare function clockFile(root: string, name: string): string;
 export declare function instanceDir(root: string, name: string): string;
 export type SharingClaim = {

package/dist/src/runtime.js

@@ -290,7 +290,7 @@ function assertSafeWorldName(name) {
  * the instance dir — one layout owner, no duplicated path knowledge. */
 /** THE WORLD CLOCK file (TWIN-PROGRAMMING-MODEL P3): a single frozen ISO instant every twin
  *  stamps from (kernel worldNow()); absent → real wall-clock. Written only by the
- *  `volter-world clock` operator door — time is physics, advanced explicitly, never drifting. */
+ *  `volter-world clock` operator door or its runtime API — time is physics, advanced explicitly, never drifting. */
 export function clockFile(root, name) {
     return join(instanceDir(root, name), 'clock');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "3.0.88",
+  "version": "3.0.90",
   "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",
@@ -69,14 +69,14 @@
     "node": ">=22.3"
   },
   "peerDependencies": {
-    "@volter/world-core": "3.0.88",
-    "@volter/world-console": "3.0.83"
+    "@volter/world-core": "3.0.90",
+    "@volter/world-console": "3.0.85"
   },
   "dependencies": {
     "@electric-sql/pglite": "0.5.8",
     "@electric-sql/pglite-pgvector": "0.0.9",
     "@volter/world-access": "3.0.1",
-    "@volter/world-core": "3.0.88",
+    "@volter/world-core": "3.0.90",
     "mongodb": "~6.20.0",
     "pg-gateway": "0.3.0-beta.4",
     "smol-toml": "^1.8.0",

package/src/cli-commands.ts

@@ -7,7 +7,7 @@ import { createRequire } from 'node:module';
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve, resolve as resolvePath } from 'node:path';
-import { activateScript, branchWorld, checkoutWorld, fetchFromOrigin, pushWorldChangeset, rebaseWorldChangeset, resetWorld, seedWorld, worldOrigin, approveWorldChangeset, checkPrerequisites, coverWorld, createWorldChangeset, diffWorld, doctorWorld, downWorld, findWorldChangeset, formatCoverageReport, formatInitReport, formatPrerequisiteChecks, formatProjectInspection, initWorld, inspectProject, isRemoteWorldRef, listWorldChangesets, listWorlds, markWorld, migrateWorldConfig, readReflectRoutes, reflectRoutesPath, replayWorldChangeset, resolveWorldRef, attachWorld, retireWorldConsumers, runWorld, shareWorldServices, shellWorld, startReflectFront, startReflectResolver, statusWorld, statusWorldChangeset, tailWorldActions, unshareWorld, upWorld, urlsWorld, urlWorld, verifyWorldChangeset, worldManifest, writeReflectRoutes, readReflectManifest, writeReflectManifest, clearReflectManifest, composeOverrideForReflect, splitDockerComposeArgs, dockerComposeWithOverride, ATTACHED_CA_PATH } from './index.ts';
+import { activateScript, branchWorld, checkoutWorld, fetchFromOrigin, pushWorldChangeset, rebaseWorldChangeset, resetWorld, seedWorld, worldOrigin, approveWorldChangeset, writeWorldClock, checkPrerequisites, coverWorld, createWorldChangeset, diffWorld, doctorWorld, downWorld, findWorldChangeset, formatCoverageReport, formatInitReport, formatPrerequisiteChecks, formatProjectInspection, initWorld, inspectProject, isRemoteWorldRef, listWorldChangesets, listWorlds, markWorld, migrateWorldConfig, readReflectRoutes, reflectRoutesPath, replayWorldChangeset, resolveWorldRef, attachWorld, retireWorldConsumers, runWorld, shareWorldServices, shellWorld, startReflectFront, startReflectResolver, statusWorld, statusWorldChangeset, tailWorldActions, unshareWorld, upWorld, urlsWorld, urlWorld, verifyWorldChangeset, worldManifest, writeReflectRoutes, readReflectManifest, writeReflectManifest, clearReflectManifest, composeOverrideForReflect, splitDockerComposeArgs, dockerComposeWithOverride, ATTACHED_CA_PATH } from './index.ts';
 import { formatApplication, formatChangeset, formatRebaseReport, formatChangesetStatus, formatLedgerDelta, formatReplayReport, formatVerification, parseVerifierExpression } from '@volter/world-core/runtime';
 import { advertiseWorldManifest, fetchRemoteManifest, MANIFEST_PATH, remoteAttachEnv, startManifestServer } from './serve.ts';
 import type { WorldManifest } from './attach.ts';
@@ -491,8 +491,7 @@ export async function main(): Promise<void> {
     const file = clockFile(rootDir, name);
     const current = existsSync(file) ? clockForm.parseClock(readFileSync(file, 'utf8')) : null;
     const write = (clock: Parameters<typeof clockForm.formatClock>[0]) => {
-      mkdirSync(dirname(file), { recursive: true });
-      writeFileSync(file, `${clockForm.formatClock(clock)}\n`);
+      writeWorldClock(name, rootDir, clock);
       // the World's time now, bare, as scripts read it (`show` says which form)
       console.log(new Date(clockForm.clockNowMs(clock, Date.now())).toISOString());
     };

package/src/clock.ts

@@ -0,0 +1,21 @@
+// The programmatic counterpart of the operator's clock command. Callers own their World root; only invoked
+// operations read or write it. Formatting belongs to the kernel's shared clock contract.
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname } from 'node:path';
+import type { WorldClock } from '@volter/world-core/world-clock';
+import { clockFile } from './runtime.ts';
+
+const clockForm = createRequire(import.meta.url)('@volter/world-core/world-clock') as typeof import('@volter/world-core/world-clock');
+
+export function writeWorldClock(name: string, root: string, clock: WorldClock): void {
+  const file = clockFile(root, name);
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, `${clockForm.formatClock(clock)}\n`);
+}
+
+export function setWorldClock(name: string, root: string, at: string): void {
+  const parsed = Date.parse(at);
+  if (Number.isNaN(parsed)) throw new Error(`clock set: ${JSON.stringify(at)} is not an ISO-8601 instant`);
+  writeWorldClock(name, root, { kind: 'frozen', at: parsed });
+}

package/src/index.ts

@@ -100,6 +100,7 @@ export type { CoverageReport, CoverageRow, CoverageStatus, CoverageOptions, Repo
 export { formatInitReport, initWorld, packCatalog, planWorldInit, renderEnvFile, writeWorldInit } from './init.ts';
 export { STATE_GITIGNORE } from './init.ts';
 export { clockFile, instanceDir } from './runtime.ts';
+export { setWorldClock, writeWorldClock } from './clock.ts';
 export { checkoutCatalog, findInstalledPackage, installedCatalog, resolveCatalog, resolveServicePackage, twinPackageName, TWIN_PACKAGE_PREFIX, type Catalog, type CatalogKind, packCli, packEntry } from './catalog.ts';
 export { ISSUE_ENV_PREFIX, MINT_ENV } from './schema.ts';
 export type {

package/src/runtime.ts

@@ -315,7 +315,7 @@ function assertSafeWorldName(name: string): void {
  * the instance dir — one layout owner, no duplicated path knowledge. */
 /** THE WORLD CLOCK file (TWIN-PROGRAMMING-MODEL P3): a single frozen ISO instant every twin
  *  stamps from (kernel worldNow()); absent → real wall-clock. Written only by the
- *  `volter-world clock` operator door — time is physics, advanced explicitly, never drifting. */
+ *  `volter-world clock` operator door or its runtime API — time is physics, advanced explicitly, never drifting. */
 export function clockFile(root: string, name: string): string {
   return join(instanceDir(root, name), 'clock');
 }