@volter/world 3.0.146 → 3.0.148

package/dist/examples/customer-onboarding/README.md

@@ -13,7 +13,7 @@ You need Node 22.6+, npm and registry access during installation. The browser pa
 Copy this starter into a new folder:
 
 ```console
-$ npx @volter/world@3.0.146 example customer-onboarding --dir onboarding
+$ npx @volter/world@3.0.148 example customer-onboarding --dir onboarding
 $ cd onboarding
 $ npm install
 ```

package/dist/examples/customer-onboarding/package.json

@@ -11,10 +11,10 @@
     "pg": "8.16.3"
   },
   "devDependencies": {
-    "@volter/world": "3.0.146",
-    "@volter/world-core": "3.0.146",
-    "@volter/world-runtime": "3.0.146",
-    "@volter/world-console": "3.0.141",
+    "@volter/world": "3.0.148",
+    "@volter/world-core": "3.0.147",
+    "@volter/world-runtime": "3.0.147",
+    "@volter/world-console": "3.0.142",
     "@volter/twin-stripe": "3.0.2",
     "@volter/twin-resend": "1.0.1"
   }

package/dist/examples/integration-branches/README.md

@@ -13,7 +13,7 @@ Give two workers the same Stripe baseline, let them change different existing cu
 Use an empty parent folder. Create the baseline starter there:
 
 ```console
-$ npx @volter/world@3.0.146 example integration-branches --dir baseline
+$ npx @volter/world@3.0.148 example integration-branches --dir baseline
 $ cd baseline
 $ npm install
 $ ./node_modules/.bin/volter world init --name baseline --twins stripe
@@ -38,9 +38,9 @@ The stopped baseline retains its history and can supply local path remotes. Defa
 Create three more copies in the same parent folder:
 
 ```console
-$ npx @volter/world@3.0.146 example integration-branches --dir integration
-$ npx @volter/world@3.0.146 example integration-branches --dir worker-a
-$ npx @volter/world@3.0.146 example integration-branches --dir worker-b
+$ npx @volter/world@3.0.148 example integration-branches --dir integration
+$ npx @volter/world@3.0.148 example integration-branches --dir worker-a
+$ npx @volter/world@3.0.148 example integration-branches --dir worker-b
 ```
 
 In `integration`, then `worker-a`, then `worker-b`, install dependencies and initialize with the folder's name. Before a first boot or app write, link and pull the baseline:

package/dist/examples/integration-branches/package.json

@@ -9,10 +9,10 @@
     "stripe": "17.7.0"
   },
   "devDependencies": {
-    "@volter/world": "3.0.146",
-    "@volter/world-core": "3.0.146",
-    "@volter/world-runtime": "3.0.146",
-    "@volter/world-console": "3.0.141",
+    "@volter/world": "3.0.148",
+    "@volter/world-core": "3.0.147",
+    "@volter/world-runtime": "3.0.147",
+    "@volter/world-console": "3.0.142",
     "@volter/twin-stripe": "3.0.2"
   }
 }

package/dist/examples/workplace-agent/README.md

@@ -13,7 +13,7 @@ You need Node 22.6+, npm and registry access during installation. No platform ac
 ## Prepare an ordinary workplace
 
 ```console
-$ npx @volter/world@3.0.146 example workplace-agent --dir workplace
+$ npx @volter/world@3.0.148 example workplace-agent --dir workplace
 $ cd workplace
 $ npm install
 $ ./node_modules/.bin/volter world init --name workplace --twins github,linear,slack

package/dist/examples/workplace-agent/package.json

@@ -11,10 +11,10 @@
     "@slack/web-api": "7.19.0"
   },
   "devDependencies": {
-    "@volter/world": "3.0.146",
-    "@volter/world-core": "3.0.146",
-    "@volter/world-runtime": "3.0.146",
-    "@volter/world-console": "3.0.141",
+    "@volter/world": "3.0.148",
+    "@volter/world-core": "3.0.147",
+    "@volter/world-runtime": "3.0.147",
+    "@volter/world-console": "3.0.142",
     "@volter/twin-github": "3.0.6",
     "@volter/twin-linear": "3.0.4",
     "@volter/twin-slack": "3.0.5"

package/dist/src/world.d.ts

@@ -105,6 +105,8 @@ export declare class World {
         seed?: boolean;
         cwd?: string;
     }): Promise<WorldInstance>;
+    /** Product startup completes its seed sequence; the runtime owns only the boot. */
+    private finishStartup;
     /** Stop the twins; the branch's state stays (`up` resumes). `purge` forgets it. */
     down(opts?: {
         purge?: boolean;

package/dist/src/world.js

@@ -125,12 +125,17 @@ export class World {
             ...(opts.mode ? { mode: opts.mode } : existing ? { mode: existing.mode } : {}),
             ...(existing ? { keepState: true } : {}),
         });
+        await this.finishStartup(instance, existing === null, opts);
+        return instance;
+    }
+    /** Product startup completes its seed sequence; the runtime owns only the boot. */
+    async finishStartup(instance, fresh, opts = {}) {
         try {
-            if (!existing && opts.seed !== false && existsSync(worldSeedPath(this.root))) {
+            if (fresh && opts.seed !== false && existsSync(worldSeedPath(this.root))) {
                 // a story that fails is a loud failure: the world is up, but not the world the app expects
                 const seeded = await seedWorld(this.name, { root: this.root, cwd: opts.cwd ?? this.root });
                 if (seeded.exitCode !== 0)
-                    throw new Error(`the story failed (${seeded.entry} exited ${seeded.exitCode}); the world is up without it — fix the seed and \`volter world seed\``);
+                    throw new Error(`the story failed (${seeded.entry} exited ${seeded.exitCode}); state may be partially seeded — fix the seed, start this World and run \`volter world seed\``);
             }
         }
         finally {
@@ -138,7 +143,6 @@ export class World {
             // fresh boot runs simulated), where the deploy reads it — also when the seed failed
             materializeRoots(loadWorldConfig(this.configRef(), this.root).config, instance.dirs.data, this.root);
         }
-        return instance;
     }
     /** Stop the twins; the branch's state stays (`up` resumes). `purge` forgets it. */
     down(opts = {}) { return downWorld(this.name, this.root, opts); }
@@ -150,12 +154,9 @@ export class World {
     shell() { return shellWorld(this.name, this.root); }
     /** The kernel's instance record, or null before the first `up`. */
     instance() {
-        try {
-            return statusWorld(this.name, this.root);
-        }
-        catch {
+        if (!existsSync(join(instanceDir(this.root, this.name), 'instance.json')))
             return null;
-        }
+        return statusWorld(this.name, this.root);
     }
     /** The world, the branch, the origin, what is unpushed, what is running. */
     status() {
@@ -379,7 +380,35 @@ export class World {
     /** Serve this world on a port under `/<org>/<world>/`; returns when listening. */
     serve(opts = {}) { return serveWorld(this.name, { root: this.root, ...opts }); }
     /** `volter world view`: this World, its twins' screens, its branches and the console on one origin (docs/contributing/architecture.md, "Viewing a World"). */
-    view(opts = {}) { const person = platformPerson(); return serveWorldView(this.name, { root: this.root, ...(person ? { localPerson: person } : {}), ...opts }); }
+    async view(opts = {}) {
+        const fresh = this.instance() === null;
+        const person = platformPerson();
+        const announced = [];
+        let ready = false;
+        const view = await serveWorldView(this.name, { root: this.root, ...(person ? { localPerson: person } : {}), ...opts, announce: line => { if (ready)
+                opts.announce?.(line);
+            else
+                announced.push(line); } });
+        try {
+            const instance = this.instance();
+            if (!instance)
+                throw new Error('the viewer started without a recorded World instance');
+            await this.finishStartup(instance, fresh);
+            for (const line of announced)
+                opts.announce?.(line);
+            ready = true;
+            return view;
+        }
+        catch (error) {
+            try {
+                await view.stop();
+            }
+            catch (stopError) {
+                throw new AggregateError([error, stopError], 'World viewer startup failed and teardown was not confirmed; retained lifecycle evidence needs inspection');
+            }
+            throw error;
+        }
+    }
     // ── remotes ─────────────────────────────────────────────────────────────────────────────
     /** The vendors this world has a twin of, as world.json names them (a twin service's package, else its id). */
     vendors() {

package/examples/customer-onboarding/README.md

@@ -13,7 +13,7 @@ You need Node 22.6+, npm and registry access during installation. The browser pa
 Copy this starter into a new folder:
 
 ```console
-$ npx @volter/world@3.0.146 example customer-onboarding --dir onboarding
+$ npx @volter/world@3.0.148 example customer-onboarding --dir onboarding
 $ cd onboarding
 $ npm install
 ```

package/examples/customer-onboarding/package.json

@@ -11,10 +11,10 @@
     "pg": "8.16.3"
   },
   "devDependencies": {
-    "@volter/world": "3.0.146",
-    "@volter/world-core": "3.0.146",
-    "@volter/world-runtime": "3.0.146",
-    "@volter/world-console": "3.0.141",
+    "@volter/world": "3.0.148",
+    "@volter/world-core": "3.0.147",
+    "@volter/world-runtime": "3.0.147",
+    "@volter/world-console": "3.0.142",
     "@volter/twin-stripe": "3.0.2",
     "@volter/twin-resend": "1.0.1"
   }

package/examples/integration-branches/README.md

@@ -13,7 +13,7 @@ Give two workers the same Stripe baseline, let them change different existing cu
 Use an empty parent folder. Create the baseline starter there:
 
 ```console
-$ npx @volter/world@3.0.146 example integration-branches --dir baseline
+$ npx @volter/world@3.0.148 example integration-branches --dir baseline
 $ cd baseline
 $ npm install
 $ ./node_modules/.bin/volter world init --name baseline --twins stripe
@@ -38,9 +38,9 @@ The stopped baseline retains its history and can supply local path remotes. Defa
 Create three more copies in the same parent folder:
 
 ```console
-$ npx @volter/world@3.0.146 example integration-branches --dir integration
-$ npx @volter/world@3.0.146 example integration-branches --dir worker-a
-$ npx @volter/world@3.0.146 example integration-branches --dir worker-b
+$ npx @volter/world@3.0.148 example integration-branches --dir integration
+$ npx @volter/world@3.0.148 example integration-branches --dir worker-a
+$ npx @volter/world@3.0.148 example integration-branches --dir worker-b
 ```
 
 In `integration`, then `worker-a`, then `worker-b`, install dependencies and initialize with the folder's name. Before a first boot or app write, link and pull the baseline:

package/examples/integration-branches/package.json

@@ -9,10 +9,10 @@
     "stripe": "17.7.0"
   },
   "devDependencies": {
-    "@volter/world": "3.0.146",
-    "@volter/world-core": "3.0.146",
-    "@volter/world-runtime": "3.0.146",
-    "@volter/world-console": "3.0.141",
+    "@volter/world": "3.0.148",
+    "@volter/world-core": "3.0.147",
+    "@volter/world-runtime": "3.0.147",
+    "@volter/world-console": "3.0.142",
     "@volter/twin-stripe": "3.0.2"
   }
 }

package/examples/workplace-agent/README.md

@@ -13,7 +13,7 @@ You need Node 22.6+, npm and registry access during installation. No platform ac
 ## Prepare an ordinary workplace
 
 ```console
-$ npx @volter/world@3.0.146 example workplace-agent --dir workplace
+$ npx @volter/world@3.0.148 example workplace-agent --dir workplace
 $ cd workplace
 $ npm install
 $ ./node_modules/.bin/volter world init --name workplace --twins github,linear,slack

package/examples/workplace-agent/package.json

@@ -11,10 +11,10 @@
     "@slack/web-api": "7.19.0"
   },
   "devDependencies": {
-    "@volter/world": "3.0.146",
-    "@volter/world-core": "3.0.146",
-    "@volter/world-runtime": "3.0.146",
-    "@volter/world-console": "3.0.141",
+    "@volter/world": "3.0.148",
+    "@volter/world-core": "3.0.147",
+    "@volter/world-runtime": "3.0.147",
+    "@volter/world-console": "3.0.142",
     "@volter/twin-github": "3.0.6",
     "@volter/twin-linear": "3.0.4",
     "@volter/twin-slack": "3.0.5"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world",
-  "version": "3.0.146",
+  "version": "3.0.148",
   "description": "Run your app against a world of twins. `World` and `Repo` — one method per verb: init, up, run, log, diff, reset, branch, checkout, clone, fetch, changeset, push — and the `volter` command, one client of them.",
   "keywords": [
     "volter",
@@ -31,12 +31,12 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.1",
-    "@volter/world-core": "3.0.146",
-    "@volter/world-runtime": "3.0.146",
+    "@volter/world-core": "3.0.147",
+    "@volter/world-runtime": "3.0.147",
     "zod": "^4.6.5"
   },
   "peerDependencies": {
-    "@volter/world-console": "3.0.141"
+    "@volter/world-console": "3.0.142"
   },
   "peerDependenciesMeta": {
     "@volter/world-console": {
@@ -44,7 +44,7 @@
     }
   },
   "devDependencies": {
-    "@volter/world-console": "3.0.141"
+    "@volter/world-console": "3.0.142"
   },
   "bin": {
     "volter": "dist/src/cli.js"

package/src/world.ts

@@ -138,18 +138,22 @@ export class World {
       ...(opts.mode ? { mode: opts.mode } : existing ? { mode: existing.mode } : {}),
       ...(existing ? { keepState: true } : {}),
     });
+    await this.finishStartup(instance, existing === null, opts);
+    return instance;
+  }
+  /** Product startup completes its seed sequence; the runtime owns only the boot. */
+  private async finishStartup(instance: WorldInstance, fresh: boolean, opts: { seed?: boolean; cwd?: string } = {}): Promise<void> {
     try {
-      if (!existing && opts.seed !== false && existsSync(worldSeedPath(this.root))) {
+      if (fresh && opts.seed !== false && existsSync(worldSeedPath(this.root))) {
         // a story that fails is a loud failure: the world is up, but not the world the app expects
         const seeded = await seedWorld(this.name, { root: this.root, cwd: opts.cwd ?? this.root });
-        if (seeded.exitCode !== 0) throw new Error(`the story failed (${seeded.entry} exited ${seeded.exitCode}); the world is up without it — fix the seed and \`volter world seed\``);
+        if (seeded.exitCode !== 0) throw new Error(`the story failed (${seeded.entry} exited ${seeded.exitCode}); state may be partially seeded — fix the seed, start this World and run \`volter world seed\``);
       }
     } finally {
       // a root set while the world was stopped reaches the twins' state after the default data (which a
       // fresh boot runs simulated), where the deploy reads it — also when the seed failed
       materializeRoots(loadWorldConfig(this.configRef(), this.root).config, instance.dirs.data, this.root);
     }
-    return instance;
   }
   /** Stop the twins; the branch's state stays (`up` resumes). `purge` forgets it. */
   down(opts: { purge?: boolean } = {}): ReturnType<typeof downWorld> { return downWorld(this.name, this.root, opts); }
@@ -162,7 +166,8 @@ export class World {
 
   /** The kernel's instance record, or null before the first `up`. */
   instance(): ReturnType<typeof statusWorld> | null {
-    try { return statusWorld(this.name, this.root); } catch { return null; }
+    if (!existsSync(join(instanceDir(this.root, this.name), 'instance.json'))) return null;
+    return statusWorld(this.name, this.root);
   }
   /** The world, the branch, the origin, what is unpushed, what is running. */
   status(): WorldStatus {
@@ -351,7 +356,25 @@ export class World {
   /** Serve this world on a port under `/<org>/<world>/`; returns when listening. */
   serve(opts: { port?: number; host?: string; consolePort?: number; announce?: (info: { name: string; base: string; token: string; readToken: string; console: string | null }) => void } = {}): Promise<ServedWorld> { return serveWorld(this.name, { root: this.root, ...opts }); }
   /** `volter world view`: this World, its twins' screens, its branches and the console on one origin (docs/contributing/architecture.md, "Viewing a World"). */
-  view(opts: { port?: number; host?: string; console?: ViewConsole; announce?: (line: string) => void; origins?: boolean; origin?: string } = {}): Promise<WorldView> { const person = platformPerson(); return serveWorldView(this.name, { root: this.root, ...(person ? { localPerson: person } : {}), ...opts }); }
+  async view(opts: { port?: number; host?: string; console?: ViewConsole; announce?: (line: string) => void; origins?: boolean; origin?: string } = {}): Promise<WorldView> {
+    const fresh = this.instance() === null;
+    const person = platformPerson();
+    const announced: string[] = [];
+    let ready = false;
+    const view = await serveWorldView(this.name, { root: this.root, ...(person ? { localPerson: person } : {}), ...opts, announce: line => { if (ready) opts.announce?.(line); else announced.push(line); } });
+    try {
+      const instance = this.instance();
+      if (!instance) throw new Error('the viewer started without a recorded World instance');
+      await this.finishStartup(instance, fresh);
+      for (const line of announced) opts.announce?.(line);
+      ready = true;
+      return view;
+    } catch (error) {
+      try { await view.stop(); }
+      catch (stopError) { throw new AggregateError([error, stopError], 'World viewer startup failed and teardown was not confirmed; retained lifecycle evidence needs inspection'); }
+      throw error;
+    }
+  }
 
   // ── remotes ─────────────────────────────────────────────────────────────────────────────
   /** The vendors this world has a twin of, as world.json names them (a twin service's package, else its id). */