@volter/world-runtime 2.0.49 → 2.0.51

package/dist/src/served-world.js

@@ -31,13 +31,14 @@ import { APP_READ_ENDPOINT_ENV } from "./init.js";
 import { grantOf, presentedSecrets, sameSecret, spentPasses, verifyPass } from '@volter/world-access';
 import { createHash } from 'node:crypto';
 import { dirname, join, resolve } from 'node:path';
-import { appendActionIfAbsent, branchEntries, branchLogPath, branchMetaPath, changesetContentHash, confirmAction, parentLogPath, readTree, stateDirName, wholeLog, worldNow, parentEntries, readBranchMeta, rebaseBranch, } from '@volter/world-core';
+import { appendActionIfAbsent, branchEntries, branchLogPath, branchMetaPath, changesetContentHash, changesetReadiness, confirmAction, parentLogPath, readTree, stateDirName, wholeLog, worldNow, parentEntries, readBranchMeta, rebaseBranch, } from '@volter/world-core';
 import { approveWorldChangeset, createWorldChangeset, diffWorld, findWorldChangeset, listWorldChangesets, pushWorldChangeset, verifyWorldChangeset, worldChangesetsDir } from "./changeset.js";
 import { fetchFromOrigin } from "./origin.js";
 import { CONSOLE_BASE, consoleRedirect, serveConsoleApart } from "./console-apart.js";
-import { loadWorldConfig } from "./configs.js";
+import { loadWorldConfig, worldChangesetRules, writeWorldConfig } from "./configs.js";
 import { adaptersFor, credentialPath, packMirror, credentialPayloadFrom, deployTwin, deployWorld, loadWorldChecks, twinSigningSecret, materializeRoots, refreshPosture, refreshTwin, rootForControlRoot, rewrapTwinCredentials, sealTwinCredential, sealedCredentialInfo, bindLegacyCredentials, setTwinRoot, spanMs } from "./root.js";
 import { clockFile, downWorld, listWorlds, statusWorld, upWorld } from "./runtime.js";
+import { assertChangesetRules } from "./schema.js";
 export const TOKEN_HEADER = 'x-volter-token';
 /** The header the injector carries a hosted World's token in (inject.cjs, VOLTER_TWINS_KEY). */
 export const TWINS_KEY_HEADER = 'x-twins-key';
@@ -142,7 +143,7 @@ export async function mountWorld(name, opts = {}) {
         clockPath: () => clockFile(worldRoot, name),
         ...(opts.branches?.(served) ? { branches: opts.branches(served) } : {}),
         ...(opts.browserOrigin ? { browserOrigin: () => opts.browserOrigin(served), originOf: (other) => opts.browserOrigin(other) } : {}),
-        ...(opts.localTrust ? { localTrust: () => true } : {}),
+        ...(opts.localTrust ? { localTrust: () => true, ...(opts.localPerson ? { localPerson: () => opts.localPerson } : {}) } : {}),
         ...(opts.serveBranch ? { serveBranch: opts.serveBranch } : {}),
         ...(opts.passIssuers?.length ? { passIssuers: () => opts.passIssuers } : {}),
         // a local twin is its own process: the wire forwards to the port it listens on
@@ -423,7 +424,7 @@ export class WorldDoors {
     }
     /** A new session of `scope`: its id, the cookie's value. A token's lasts 30 days; a person's from a pass, `who`,
      *  lasts as long as the pass's platform says (twelve hours), so a person removed there loses it within the day. */
-    openSession(scope, person, key) {
+    openSession(scope, person, key, local) {
         const id = mintToken('ses_');
         let held = this.sessions();
         // a person holds at most five sessions here: passes (anyone's with one) never crowd out everyone else's
@@ -435,7 +436,7 @@ export class WorldDoors {
             }
         }
         const until = Math.min(Date.now() + (person?.ttlMs ?? 30 * 86_400_000), key?.until ?? Infinity);
-        this.keepSessions({ ...held, [id]: { scope, until, ...(person ? { who: person.who, issuer: person.issuer, ...(person.sub ? { sub: person.sub } : {}) } : {}), ...(key ? { key: key.id } : {}) } });
+        this.keepSessions({ ...held, [id]: { scope, until, ...(local ? { local: true } : {}), ...(person ? { who: person.who, ...(person.issuer ? { issuer: person.issuer } : {}), ...(person.sub ? { sub: person.sub } : {}) } : {}), ...(key ? { key: key.id } : {}) } });
         return id;
     }
     /** NAMED KEYS: what an app or a script holds (docs/contributing/architecture.md, "The hosted product"), each named
@@ -466,6 +467,9 @@ export class WorldDoors {
      *  revoke every key made by or for a person (their leaving the org). */
     /** The person a key is for: whom it was made for, else the person whose session made it. */
     keyPerson(k) { return k.for ?? (k.createdBy?.via === 'session' ? k.createdBy.sub : undefined); }
+    /** The person a key acts for, as attribution names them ("Who acted is recorded"): the name it was made for, else the
+     *  person whose session made it, as their session names them (a pass's email, this machine's person). */
+    keyName(k) { return k.forName ?? k.for ?? (k.createdBy?.via === 'session' ? k.createdBy.who ?? k.createdBy.sub : undefined); }
     /** Revoke the keys `pick` names, and what they reach: the branches whose parent key goes, and the branches (with their
      *  keys) a revoked key made. Answers the revoked keys' ids. */
     async revokeKeys(pick) {
@@ -491,7 +495,7 @@ export class WorldDoors {
             return Response.json({ error: 'a key manages no keys: use the World\'s token, or its page' }, { status: 403 });
         const now = Date.now();
         const live = () => this.keys().filter((k) => !k.expiresAt || Date.parse(k.expiresAt) > now);
-        const view = (k) => ({ id: k.id, name: k.name, scope: k.scope, createdAt: k.createdAt, lastUsedAt: k.lastUsedAt ?? null, expiresAt: k.expiresAt ?? null, for: k.for ?? null, person: this.keyPerson(k) ?? null, branch: k.branch ?? null, createdBy: k.createdBy?.via === 'session' ? (k.createdBy.who ?? k.createdBy.sub ?? 'a person') : k.createdBy?.via === 'key' ? `the key ${k.createdBy.keyId}` : k.createdBy ? 'the World\'s token' : null });
+        const view = (k) => ({ id: k.id, name: k.name, scope: k.scope, createdAt: k.createdAt, lastUsedAt: k.lastUsedAt ?? null, expiresAt: k.expiresAt ?? null, for: k.for ?? null, person: this.keyName(k) ?? null, branch: k.branch ?? null, createdBy: k.createdBy?.via === 'session' ? (k.createdBy.who ?? k.createdBy.sub ?? 'a person') : k.createdBy?.via === 'key' ? `the key ${k.createdBy.keyId}` : k.createdBy ? 'the World\'s token' : null });
         const person = (k) => this.keyPerson(k);
         if (!id && request.method === 'GET')
             return Response.json({ keys: live().map(view) });
@@ -500,6 +504,9 @@ export class WorldDoors {
             const name = typeof body.name === 'string' ? body.name.trim().slice(0, 80) : '';
             if (!name)
                 return Response.json({ error: 'a key needs a name: what holds it (an app, a CI job, a laptop)' }, { status: 400 });
+            // a key's name is what holds it, never whom it is for: the caller a World records reads `key:<name> for:<person>`
+            if (/\sfor:/i.test(name))
+                return Response.json({ error: 'a key\'s name says what holds it; whom it is for is its own field' }, { status: 400 });
             const keyScope = body.scope === 'read' ? 'read' : 'write';
             // a session a platform's pass opened makes no keys: a key outlives the session, and a script on this origin (a
             // stored page) could make one in the person's name. Keys for a platform's Worlds are made on the platform.
@@ -507,9 +514,10 @@ export class WorldDoors {
             if (opener?.issuer)
                 return Response.json({ error: 'a key for this World is made on the platform it was opened from, not from a browser session here', platform: opener.issuer }, { status: 403 });
             // `for`, `replace` and an end are the token's to give (a platform making a command's key for a person)
-            if ((body.for !== undefined || body.replace !== undefined) && via !== 'token')
+            if ((body.for !== undefined || body.forName !== undefined || body.replace !== undefined) && via !== 'token')
                 return Response.json({ error: 'for and replace are the World token\'s' }, { status: 403 });
             const forWhom = typeof body.for === 'string' && /^[A-Za-z0-9:._@-]{1,160}$/.test(body.for) ? body.for : undefined;
+            const forName = forWhom && typeof body.forName === 'string' && /^[A-Za-z0-9:._@+ -]{1,160}$/.test(body.forName) ? body.forName : undefined;
             let expiresAt;
             if (body.expiresAt !== undefined) {
                 const t = typeof body.expiresAt === 'string' ? Date.parse(body.expiresAt) : NaN;
@@ -526,7 +534,7 @@ export class WorldDoors {
             const opened = via === 'session' && session ? this.sessions()[session] : undefined;
             const createdBy = via === 'session' ? { via: 'session', ...(opened?.sub ? { sub: opened.sub } : {}), ...(opened?.who ? { who: opened.who } : {}), ...(opened?.issuer ? { issuer: opened.issuer } : {}) } : { via: 'token' };
             const key = mintToken('tok_k_');
-            const held = { id: mintToken('key_').slice(0, 20), name, scope: keyScope, hash: keyHash(key), createdAt: new Date(now).toISOString(), createdBy, ...(forWhom ? { for: forWhom } : {}), ...(expiresAt ? { expiresAt } : {}) };
+            const held = { id: mintToken('key_').slice(0, 20), name, scope: keyScope, hash: keyHash(key), createdAt: new Date(now).toISOString(), createdBy, ...(forWhom ? { for: forWhom } : {}), ...(forName ? { forName } : {}), ...(expiresAt ? { expiresAt } : {}) };
             this.keepKeys([...kept, held]);
             return Response.json({ ...view(held), key }, { status: 201, headers: { 'cache-control': 'no-store' } });
         }
@@ -692,15 +700,32 @@ export class WorldDoors {
         const cred = this.credential(request);
         if (cred.scope === null)
             return null;
+        // this machine's own page with no one signed in here is this machine; another session with no name is just that
         if (cred.via === 'session')
-            return cred.who ? `person:${cred.who}` : 'person';
+            return cred.who ? `person:${cred.who}` : cred.session && this.sessions()[cred.session]?.local ? 'machine' : 'person';
+        // a key acts as itself, for its person (docs/contributing/architecture.md, "Who acted is recorded")
         if (cred.via === 'key') {
-            const token = cred.token;
-            const held = token ? this.keys().find((k) => sameSecret(keyHash(token), k.hash)) : undefined;
-            return held ? `key:${held.name}` : 'key';
+            const held = this.keyOf(cred.token);
+            const person = held ? this.keyName(held) : undefined;
+            return held ? `key:${held.name}${person ? ` for:${person}` : ''}` : 'key';
         }
         return cred.scope === 'read' ? 'token:read' : 'token';
     }
+    /** The person a request acts for: a session's person, or the person a key is for; none for this machine's page or a
+     *  World's own token. What lands in a World others read must name one. */
+    personOf(request) {
+        const cred = this.credential(request);
+        if (cred.scope === null)
+            return undefined;
+        if (cred.via === 'session')
+            return cred.who;
+        if (cred.via === 'key') {
+            const held = this.keyOf(cred.token);
+            return held ? this.keyName(held) : undefined;
+        }
+        return undefined;
+    }
+    keyOf(token) { return token ? this.keys().find((k) => sameSecret(keyHash(token), k.hash)) : undefined; }
     /** The session cookie's name where `url` reached this World, or null where a session opens nothing:
      *  on the World's own origin a host-only cookie (`__Host-` over https); without an origin of its own,
      *  the path-scoped cookie a shared origin has always carried. */
@@ -1225,11 +1250,13 @@ export class WorldDoors {
             // with the body's hash as it stands, so a reader sees an approval or a verification made on other bytes as stale
             if (name) {
                 const l = findWorldChangeset(name, { root: this.worldRoot, world: this.name });
-                return Response.json({ ...l.changeset, currentHash: changesetContentHash(l.changeset), deployed: this.deployedOf([l.changeset])[0] });
+                return Response.json({ ...l.changeset, currentHash: changesetContentHash(l.changeset), deployed: this.deployedOf([l.changeset])[0], readiness: changesetReadiness(l.changeset, worldChangesetRules(this.worldRoot)) });
             }
             const all = listWorldChangesets({ root: this.worldRoot, world: this.name }).map((l) => l.changeset);
             const deployed = this.deployedOf(all);
-            return Response.json({ changesets: all.map((c, i) => ({ ...c, currentHash: changesetContentHash(c), deployed: deployed[i] })) });
+            const rules = worldChangesetRules(this.worldRoot);
+            // readiness under this World's rules, as deploy reads it: the console says what the kernel decides
+            return Response.json({ changesets: all.map((c, i) => ({ ...c, currentHash: changesetContentHash(c), deployed: deployed[i], readiness: changesetReadiness(c, rules) })) });
         }
         if (kind === 'changesets' && name && verb === 'verify' && request.method === 'POST') {
             const outcome = await this.serialized('changesets', () => verifyWorldChangeset(name, { root: this.worldRoot, world: this.name, ephemeral: true }));
@@ -1243,7 +1270,8 @@ export class WorldDoors {
             const held = via === 'session' ? this.sessions()[this.credential(request).session ?? ''] : undefined;
             const named = typeof body.as === 'string' && body.as.trim() ? body.as.trim().slice(0, 80) : undefined;
             const tokenSession = held !== undefined && !held.who && held.key === undefined && held.scope === 'write';
-            const principal = via === 'session' ? held?.who ?? (this.host.localTrust?.() ? 'this machine' : tokenSession ? named : undefined) : named;
+            // a key approves as itself, for its person, whatever it says: it cannot be several approvers by naming several
+            const principal = via === 'session' ? held?.who ?? (this.host.localTrust?.() ? 'this machine' : tokenSession ? named : undefined) : via === 'key' ? this.callerOf(request) ?? undefined : named;
             if (!principal)
                 return Response.json({ error: via === 'session' && !tokenSession ? 'this session names no person to sign as: open the World from its platform, or approve with its token' : 'approve: { as, note? } — name who approves' }, { status: via === 'session' && !tokenSession ? 403 : 400 });
             return Response.json(approveWorldChangeset(name, { root: this.worldRoot, world: this.name, principal, ...(body.note ? { note: body.note } : {}) }));
@@ -1381,11 +1409,53 @@ export class WorldDoors {
                 }));
             }
         }
+        // THE RULES DOOR: how this World's changesets are made and readied (`changesets` in its committed config). Read with any
+        // access; changed by a person, this machine or the World's token, never by a key: a key's holder (an app, an agent)
+        // does not relax the review its own changes go through
+        if (kind === 'rules' && !name) {
+            const path = join(this.worldRoot, stateDirName(), 'world.json');
+            if (request.method === 'GET')
+                return Response.json({ world: this.served, changesets: worldChangesetRules(this.worldRoot) });
+            if (request.method === 'PUT') {
+                if (scope !== 'write')
+                    return Response.json({ error: 'the rules are changed with write access' }, { status: 403 });
+                if (via === 'key')
+                    return Response.json({ error: 'a key changes no rules: a person sets them, or the World\'s token' }, { status: 403 });
+                const body = (await request.json().catch(() => null));
+                try {
+                    assertChangesetRules(body?.changesets, path);
+                }
+                catch (error) {
+                    return Response.json({ error: error instanceof Error ? error.message.replace(` in ${path}`, '') : String(error) }, { status: 400 });
+                }
+                const { config } = loadWorldConfig(path, this.worldRoot);
+                const rules = body.changesets;
+                const next = { ...config, changesets: { ...(rules.approvals === undefined ? {} : { approvals: rules.approvals }), ...(rules.summary === undefined ? {} : { summary: rules.summary }) } };
+                writeWorldConfig(path, next);
+                return Response.json({ world: this.served, changesets: next.changesets });
+            }
+        }
         if (kind === 'changesets' && !name && request.method === 'POST') {
             const body = (await request.json().catch(() => ({})));
             const slug = body.message ? body.message.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 48) : '';
-            const cut = body.name ?? (slug || `changeset-${Date.now()}`);
-            return Response.json(await this.serialized('push', async () => createWorldChangeset(this.name, cut, { root: this.worldRoot, ...(body.message ? { message: body.message } : {}) })));
+            // with no summary to name it, the next free `changeset-<n>`, as the command names one
+            const taken = new Set(listWorldChangesets({ root: this.worldRoot, world: this.name }).map((l) => l.changeset.name));
+            let n = taken.size + 1;
+            while (taken.has(`changeset-${n}`))
+                n += 1;
+            const cut = body.name ?? (slug || `changeset-${n}`);
+            // a cut says what it does and why, unless this World's rules take the summary generated from its changes
+            if (!body.message?.trim() && worldChangesetRules(this.worldRoot).summary !== 'generated')
+                return Response.json({ error: 'a cut needs its summary: what it does and why' }, { status: 400 });
+            const cutBy = this.callerOf(request) ?? undefined;
+            const owner = this.personOf(request);
+            return await this.serialized('push', async () => {
+                // with no summary, a cut must have something to say: an empty one is a slip, refused as the command refuses it
+                // (inside the lock, so two cuts at once never both take the same changes)
+                if (!body.message?.trim() && diffWorld(this.name, { root: this.worldRoot }).actions.length === 0)
+                    return Response.json({ error: 'nothing to cut: every change is already in a changeset' }, { status: 400 });
+                return Response.json(createWorldChangeset(this.name, cut, { root: this.worldRoot, ...(body.message?.trim() ? { message: body.message.trim() } : {}), ...(cutBy ? { cutBy } : {}), ...(owner ? { owner } : {}) }));
+            });
         }
         // THE BLOBS DOOR: a twin's resource payloads (uploaded media, file bytes) by their key under its
         // resources directory. A push sends the ones its branch holds and this World lacks before the
@@ -1573,7 +1643,9 @@ export class WorldDoors {
         const own = this.host.browserOrigin?.() ?? null;
         if (this.sessionCookieName(url) === null)
             return Response.json({ error: `${this.served}'s browser session lives at its own origin`, origin: own }, { status: 409 });
-        return Response.json({ world: this.served, scope: 'write', local: true, ...(own ? { origin: own } : {}) }, { headers: { 'set-cookie': this.sessionCookie(url, this.openSession('write')) } });
+        // this machine's page acts as the person signed in here, when one is (`volter login`); else as this machine
+        const person = this.host.localPerson?.();
+        return Response.json({ world: this.served, scope: 'write', local: true, ...(person ? { who: person } : {}), ...(own ? { origin: own } : {}) }, { headers: { 'set-cookie': this.sessionCookie(url, this.openSession('write', person ? { who: person, ttlMs: 30 * 86_400_000 } : undefined, undefined, true)) } });
     }
     session(request, url, scope, key) {
         const own = this.host.browserOrigin?.() ?? null;
@@ -1859,10 +1931,18 @@ export class WorldDoors {
     }
     /** PUSH: see `landChangeset` — the door hands the body to it. */
     async push(request) {
+        // who pushed it is recorded, a person or a service (a key, the World's token): an automation pushes as itself
+        // (docs/contributing/architecture.md, "Who acted is recorded")
+        const person = this.personOf(request);
         const body = (await request.json());
-        const changeset = 'changeset' in body && !('actions' in body) ? body.changeset : body;
-        if (!changeset || !Array.isArray(changeset.actions))
+        const sent = 'changeset' in body && !('actions' in body) ? body.changeset : body;
+        if (!sent || !Array.isArray(sent.actions))
             return Response.json({ error: 'push: a changeset object' }, { status: 400 });
+        // who pushed it, and its owner when it came with none and the pusher names a person: outside its hash, so nothing an
+        // approval bound to moves
+        const pushedBy = this.callerOf(request) ?? undefined;
+        const owner = sent.owner ?? person;
+        const changeset = { ...sent, ...(owner ? { owner } : {}), ...(pushedBy ? { pushedBy } : {}) };
         this.refresh();
         // fast-forward only: the client says where it last saw each twin's log (its fetch cursor); a
         // twin that moved past it refuses with the drift — fetch, rebase, push again
@@ -1872,7 +1952,14 @@ export class WorldDoors {
             const receipts = await landChangeset(this.name, this.worldRoot, this.up(), changeset, expect);
             const position = Object.fromEntries([...new Set(changeset.actions.map((a) => a.service))].map((twin) => [twin, positionOf(twin)]));
             const snapshots = Object.fromEntries(Object.keys(position).map(twin => { const head = captureHistory(this.stateOf(twin), this.controlRoot(twin)); return [twin, { view: head.view, position: head.position }]; }));
-            return Response.json({ world: this.served, changeset: changeset.name, receipts, position, snapshots });
+            // who owns and pushed it, as this World keeps it: a changeset landed before keeps its first record
+            const kept = (() => { try {
+                return JSON.parse(getActiveWorldStore().read(join(worldChangesetsDir(this.name, this.worldRoot), `${changeset.name}.json`)) ?? 'null');
+            }
+            catch {
+                return null;
+            } })();
+            return Response.json({ world: this.served, changeset: changeset.name, receipts, position, snapshots, ...(kept?.owner ? { owner: kept.owner } : {}), ...(kept?.pushedBy ? { pushedBy: kept.pushedBy } : {}) });
         }
         catch (error) {
             return Response.json({ error: error instanceof Error ? error.message : String(error) }, { status: 409 });

package/dist/src/world-view.d.ts

@@ -16,6 +16,7 @@ export type WorldView = {
     stop: () => Promise<void>;
 };
 export declare function serveWorldView(name: string, opts?: {
+    localPerson?: string;
     root?: string;
     port?: number;
     host?: string;

package/dist/src/world-view.js

@@ -48,7 +48,7 @@ export async function serveWorldView(name, opts = {}) {
     // (the first World mounted is the World; every later one is a branch of it)
     let base = null;
     const browserOrigin = origins ? (served) => (proxied && (base === null || served === base) ? proxied.origin : port ? localWorldOrigin(served, port) : null) : undefined;
-    const mountAt = (at) => mountWorld(loadWorldConfig(join(at, stateDirName(), 'world.json'), at).config.id, { root: at, branches: (served) => branches.doorsFor(served), ...(browserOrigin ? { browserOrigin } : {}), ...(local ? { localTrust: true } : {}) });
+    const mountAt = (at) => mountWorld(loadWorldConfig(join(at, stateDirName(), 'world.json'), at).config.id, { root: at, branches: (served) => branches.doorsFor(served), ...(browserOrigin ? { browserOrigin } : {}), ...(local ? { localTrust: true, ...(opts.localPerson ? { localPerson: opts.localPerson } : {}) } : {}) });
     const branches = new LocalBranches({ dir: join(root, stateDirName(), 'branches'), origin: () => loopback, worlds, mount: mountAt, ...(opts.announce ? { announce: opts.announce } : {}) });
     // THE WORLD'S OWN BRANCHES, one served at a time: serving another stops this one's twins and starts that one's under the
     // same served name (its tokens and sessions are the World's, so the page stays open); `.volter/current` follows, as
@@ -90,7 +90,7 @@ export async function serveWorldView(name, opts = {}) {
             switching = false;
         }
     };
-    const mountOpts = { root, branches: (served) => branches.doorsFor(served), ...(browserOrigin ? { browserOrigin } : {}), ...(local ? { localTrust: true } : {}), serveBranch };
+    const mountOpts = { root, branches: (served) => branches.doorsFor(served), ...(browserOrigin ? { browserOrigin } : {}), ...(local ? { localTrust: true, ...(opts.localPerson ? { localPerson: opts.localPerson } : {}) } : {}), serveBranch };
     let world = await mountWorld(name, mountOpts);
     base = world.served;
     worlds.set(world.served, world);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "2.0.49",
+  "version": "2.0.51",
   "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",
@@ -67,14 +67,14 @@
     "node": ">=22.3"
   },
   "peerDependencies": {
-    "@volter/world-core": "2.0.31",
-    "@volter/world-console": "2.0.13"
+    "@volter/world-core": "2.0.33",
+    "@volter/world-console": "2.0.14"
   },
   "dependencies": {
     "@electric-sql/pglite": "0.5.8",
     "@electric-sql/pglite-pgvector": "0.0.9",
     "@volter/world-access": "2.0.2",
-    "@volter/world-core": "2.0.31",
+    "@volter/world-core": "2.0.33",
     "pg-gateway": "0.3.0-beta.4",
     "smol-toml": "^1.8.0"
   },
@@ -84,6 +84,6 @@
     }
   },
   "optionalDependencies": {
-    "@volter/twin-mongodb": "0.1.31"
+    "@volter/twin-mongodb": "0.1.33"
   }
 }

package/src/changeset.ts

@@ -1,3 +1,4 @@
+import { worldChangesetRules } from './configs.ts';
 import { blobDigest, captureHistory, captureParentHistory, getActiveBlobStore, getActiveWorldStore, originHead, withAncestryLock, worldPaths, type HistoryReference } from '@volter/world-core';
 // `volter-world mark` / `diff` / `changeset` — the WORLD-side verbs over the changeset
 // primitive (docs/concepts/the-model.md v0). Thin, exactly like `covers` and `tail` are thin: all
@@ -202,7 +203,7 @@ export type ChangesetLocation = { changeset: Changeset; world: string; path: str
 export function createWorldChangeset(
   world: string,
   name: string,
-  options: WorldRootOptions & { base?: string; verifiers?: ChangesetVerifier[]; now?: Date; overwrite?: boolean; message?: string } = {},
+  options: WorldRootOptions & { base?: string; verifiers?: ChangesetVerifier[]; now?: Date; overwrite?: boolean; message?: string; /** who cuts it and the person it is owned by, from the cutting grant (a served World's door) */ cutBy?: string; owner?: string } = {},
 ): Changeset {
   const root = resolveRoot(options.root);
   assertSafeChangesetName(name);
@@ -227,6 +228,8 @@ export function createWorldChangeset(
     ...(options.verifiers ? { verifiers: options.verifiers } : {}),
     ...(options.now ? { createdAt: options.now.toISOString() } : {}),
     ...(options.message === undefined ? {} : { message: options.message }),
+    ...(options.cutBy === undefined ? {} : { cutBy: options.cutBy }),
+    ...(options.owner === undefined ? {} : { owner: options.owner }),
   });
   getActiveWorldStore().write(path, `${JSON.stringify(changeset, null, 2)}\n`);
   // a changeset records where the log was cut (contract "The model"): the next one starts here
@@ -447,7 +450,7 @@ export function statusWorldChangeset(
 ): ChangesetReadiness {
   const root = resolveRoot(options.root);
   const located = findWorldChangeset(name, { root, ...(options.world ? { world: options.world } : {}) });
-  return changesetReadiness(located.changeset);
+  return changesetReadiness(located.changeset, worldChangesetRules(root));
 }
 
 // ── governed push: `volter-world changeset push` ─────────────────────────────────────────
@@ -481,7 +484,7 @@ export async function pushWorldChangeset(name: string, options: PushWorldOptions
   const namespace = options.namespace ?? instance.origin?.namespace;
   if (!url || !namespace) throw new Error(`World "${located.world}" has no origin to push to — \`volter remote add origin <url> --token <token>\` names one`);
   // over http to a served world's push door, or straight into a world at a path (git's file transport)
-  let res: { ok: boolean; status: number }; let body: { receipts?: Array<{ actionId: string; twin: string } & Receipt>; error?: string; refusal?: string[]; position?: Record<string, number>; snapshots?: Record<string, HistoryReference> };
+  let res: { ok: boolean; status: number }; let body: { receipts?: Array<{ actionId: string; twin: string } & Receipt>; error?: string; refusal?: string[]; position?: Record<string, number>; snapshots?: Record<string, HistoryReference>; /** whom the remote records as its owner and as who pushed it */ owner?: string; pushedBy?: string };
   const expect: Record<string, HistoryReference> = {};
   for (const a of located.changeset.actions) {
     const meta = readBranchMeta(a.stateService ?? a.service, join(instance.dirs.data, a.service));
@@ -597,7 +600,8 @@ export async function pushWorldChangeset(name: string, options: PushWorldOptions
   const receipts: ApplyReceipt[] = body.receipts.map((r) => ({ actionId: r.actionId, service: r.twin, stateService: located.changeset.actions.find((e) => e.service === r.twin)?.stateService ?? r.twin, status: statusOf(r.status), ...(r.externalId ? { externalId: r.externalId } : {}), ...(r.reason ? { error: r.reason } : {}) }));
   const outcome: ChangesetApplication['outcome'] = receipts.every((r) => r.status !== 'failed') ? 'applied' : receipts.some((r) => r.status === 'confirmed') ? 'partial' : 'refused';
   const application: ChangesetApplication = { at, contentHash: located.changeset.contentHash, outcome, receipts, compensation: [], ...(outcome === 'refused' ? { refusal: receipts.filter((r) => r.error).map((r) => r.error!) } : {}) };
-  const changeset = withApplication(located.changeset, application);
+  // the remote's record of who pushed it and who owns it, kept on this copy too (outside the hash)
+  const changeset = { ...withApplication(located.changeset, application), ...(body.owner && !located.changeset.owner ? { owner: body.owner } : {}), ...(body.pushedBy ? { pushedBy: body.pushedBy } : {}) };
   writeChangesetFile(located.path, changeset);
   const unsent = namedFailure ? `records the landed entries name did not reach the origin (${namedFailure instanceof Error ? namedFailure.message : String(namedFailure)}); the next push from this branch that touches ${twins.map(([t]) => t).join(', ')} sends them` : undefined;
   return { ...(unsent ? { unsent } : {}), application, changeset, world: located.world, path: located.path, remote: { url, namespace } };

package/src/configs.ts

@@ -1,7 +1,7 @@
 import { copyFileSync, constants, existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { basename, dirname, resolve } from 'node:path';
-import { getActiveWorldStore } from '@volter/world-core';
-import { assertWorldConfig, LEGACY_WORLD_SELECTION, worldConfigDocument, type WorldConfig } from './schema.ts';
+import { basename, dirname, join, resolve } from 'node:path';
+import { getActiveWorldStore, stateDirName } from '@volter/world-core';
+import { assertWorldConfig, LEGACY_WORLD_SELECTION, worldConfigDocument, type WorldChangesetRules, type WorldConfig } from './schema.ts';
 
 export function resolveConfigPath(config: string, root = process.cwd()): string {
   const candidates = config.includes('/') || config.endsWith('.json')
@@ -108,3 +108,11 @@ export function migrateWorldConfig(config: string, root = process.cwd()): WorldC
     dropped: normalized.resources === undefined ? [] : ['resources (deprecated; retained in backup)'],
   };
 }
+
+/** The changeset rules of the World rooted at `root` (its committed `.volter/world.json`, `changesets`); none when it
+ *  has no config or names none, which readiness reads as one approval and a required summary. */
+export function worldChangesetRules(root: string): WorldChangesetRules {
+  const path = join(root, stateDirName(), 'world.json');
+  if (!getActiveWorldStore().exists(path) && !existsSync(path)) return {};
+  try { return loadWorldConfig(path, root).config.changesets ?? {}; } catch { return {}; }
+}

package/src/fixture-env.ts

@@ -210,6 +210,10 @@ const CREDENTIAL_SHAPES: Array<{ match: RegExp; value: (name: string) => string;
   { match: /(^|_)STRIPE_[A-Z0-9_]*WEBHOOK_SECRET$/, value: () => 'whsec_twinfake0000000000000000000000000000', source: 'https://docs.stripe.com/webhooks#verify-events' },
   { match: /(^|_)STRIPE_[A-Z0-9_]*(SECRET|PRIVATE|API)(_API)?_KEY$/, value: () => 'sk_test_twinfake000000000000000000000000000000', source: 'https://docs.stripe.com/keys (sk_test_)' },
   { match: /(^|_)STRIPE_[A-Z0-9_]*(PUBLISHABLE|PUBLIC)(_API)?_KEY$/, value: () => 'pk_test_twinfake000000000000000000000000000000', source: 'https://docs.stripe.com/keys (pk_test_)' },
+  // The slack twin answers a bearer that is none of Slack's token kinds with `invalid_auth`, as Slack does; any `xoxb-`
+  // acts as the workspace bot, and an app-level token is `xapp-`.
+  { match: /(^|_)SLACK_[A-Z0-9_]*APP_TOKEN$/, value: () => 'xapp-1-twinfake', source: 'packages/twin/slack/src/slack-server.ts (bearer /^(xox|xapp-)/)' },
+  { match: /(^|_)SLACK_([A-Z0-9_]*_)?BOT_TOKEN$|(^|_)SLACK_TOKEN$/, value: () => 'xoxb-twinfake', source: 'packages/twin/slack/src/slack-server.ts (bearer /^(xox|xapp-)/); GET /twin identity (any other xoxb-* is the workspace bot)' },
   // tavily-auth.ts and firecrawl-auth.ts refuse a key without the vendor's prefix with the vendor's 401
   { match: /(^|_)TAVILY_[A-Z0-9_]*(KEY|TOKEN)$/, value: () => 'tvly-twinfake00000000000000000000', source: 'packages/twin/tavily/src/tavily-auth.ts' },
   { match: /(^|_)FIRECRAWL_[A-Z0-9_]*(KEY|TOKEN)$/, value: () => 'fc-twinfake00000000000000000000000', source: 'packages/twin/firecrawl/src/firecrawl-auth.ts FIRECRAWL_KEY_PREFIX' },

package/src/index.ts

@@ -18,7 +18,8 @@ export type {
   WorldUsage,
 } from './schema.ts';
 export { DEFAULT_WORLD_SELECTION, LEGACY_WORLD_SELECTION, WORLD_SCHEMA_VERSION, WORLD_USAGES, worldConfigDocument, worldSelectionIncludes } from './schema.ts';
-export { loadWorldConfig, migrateWorldConfig, resolveConfigPath, writeWorldConfig } from './configs.ts';
+export type { WorldChangesetRules } from './schema.ts';
+export { loadWorldConfig, migrateWorldConfig, resolveConfigPath, worldChangesetRules, writeWorldConfig } from './configs.ts';
 export type { WorldConfigMigration } from './configs.ts';
 export {
   upWorld,

package/src/root.ts

@@ -14,7 +14,7 @@ import { basename, dirname, join, relative, resolve } from 'node:path';
 import {
   NO_SECRETS_CHECK, authStrategyFor, currentSealer, destinationOf, sealsThroughVault, openSealedAt, getActiveWorldStore, getPack, buildRemoteExecute, clearRoot, observeAppends, readRoot, registerStateSystem, stateDirName, stateSystemFor, type Check, type CredentialPayload, type PerformAction, type PushReport, type RemoteExecute, type RootConfig, type SealedCredential, type TwinAction, validateRemoteOrigin, writeRoot,
 } from '@volter/world-core';
-import { loadWorldConfig, writeWorldConfig } from './configs.ts';
+import { loadWorldConfig, worldChangesetRules, writeWorldConfig } from './configs.ts';
 import { changesetReadiness, collectObservations, type Observation, foldObservations, loadChecks, openRootCredential, performEntries, rootCustody, protocolStanding, userKek, type DeployReport, type ObserveReport } from '@volter/world-core';
 import { findWorldChangeset, listWorldChangesets } from './changeset.ts';
 import { importModule } from './import-module.ts';
@@ -501,7 +501,7 @@ export async function deployWorld(name: string, opts: { root?: string; changeset
   const out: DeployTwinOutcome[] = [];
   if (!opts.changeset) {
     // no name: every ready changeset, by name, in order — so each outcome says which it was for
-    const ready = listWorldChangesets({ root: worldRoot, world: name }).filter((l) => changesetReadiness(l.changeset).ready && !l.changeset.actions.every((e) => { const r = rootForControlRoot(join(inst.dirs.data, e.service), e.service); return r === null; })).sort((a, b) => a.changeset.createdAt.localeCompare(b.changeset.createdAt));
+    const ready = listWorldChangesets({ root: worldRoot, world: name }).filter((l) => changesetReadiness(l.changeset, worldChangesetRules(worldRoot)).ready && !l.changeset.actions.every((e) => { const r = rootForControlRoot(join(inst.dirs.data, e.service), e.service); return r === null; })).sort((a, b) => a.changeset.createdAt.localeCompare(b.changeset.createdAt));
     const anyGated = Object.keys(inst.services).some((s) => rootForControlRoot(join(inst.dirs.data, s), s)?.deploy === 'gated');
     if (anyGated || ready.length) {
       for (const l of ready) out.push(...(await deployWorld(name, { ...opts, changeset: l.changeset.name })).map((o) => ({ ...o, changeset: l.changeset.name })));
@@ -511,7 +511,7 @@ export async function deployWorld(name: string, opts: { root?: string; changeset
   const located = opts.changeset ? [findWorldChangeset(opts.changeset, { root: worldRoot, world: name })] : listWorldChangesets({ root: worldRoot, world: name });
   const ready = new Map<string, string[]>();
   for (const l of located) {
-    const readiness = changesetReadiness(l.changeset);
+    const readiness = changesetReadiness(l.changeset, worldChangesetRules(worldRoot));
     if (!readiness.ready) {
       const gated = [...new Set(l.changeset.actions.map((e) => e.service))].some((s) => rootForControlRoot(join(inst.dirs.data, s), s)?.deploy === 'gated');
       if (opts.changeset && gated) throw new Error(`changeset ${opts.changeset} is not ready: ${readiness.reasons.join('; ')}`);

package/src/runtime.ts

@@ -1347,8 +1347,8 @@ async function startColocatedServices(
   paths: { root: string; instance: string; logs: string; data: string },
   allocatedPorts: Set<number>,
   boot: BootContext,
-): Promise<WorldServiceInstance[]> {
-  if (colocated.length === 0) return [];
+): Promise<{ services: WorldServiceInstance[]; ready: Promise<void> }> {
+  if (colocated.length === 0) return { services: [], ready: Promise.resolve() };
   const hostCli = siblingScript(import.meta.url, 'host-cli');
   const readyFile = join(paths.instance, `host-ready-${boot.bootId}.json`);
   const args: string[] = [hostCli, '--isolation', isolation === 'colocated' ? 'shared' : 'worker', '--ready-file', readyFile];
@@ -1389,42 +1389,10 @@ async function startColocatedServices(
   });
 
   const command = [process.execPath, ...args];
-  const hostTimeoutMs = allocated.reduce((timeout, { service }) => Math.max(timeout, typeof service.ready === 'object' ? service.ready.timeoutMs ?? 15_000 : 15_000), 15_000);
-  await untilReadyOrEnded((abort) => waitForHostReady(readyFile, boot.bootId, new Map(allocated.map(({ service, port }) => [service.id, port])), hostTimeoutMs, abort), ended, boot, 'the co-located host', log).catch((error) => {
-    if (undeadPids([child.pid!]).length) recordWorldStop([log], 'world.service.stop', 'up (host startup incomplete)', 'SIGTERM');
-    try { process.kill(-child.pid!, 'SIGTERM'); } catch { /* best effort cleanup */ }
-    throw new Error(`Co-located host failed to complete startup (isolation=${isolation}): ${error instanceof Error ? error.message : String(error)}\nLog: ${log}`);
-  });
-  await parallelStartup(allocated, async ({ service, port }) => {
-    const bindTimeoutMs = typeof service.ready === 'object' && service.ready.timeoutMs !== undefined ? Math.max(service.ready.timeoutMs, 15_000) : 15_000;
-    await untilReadyOrEnded((abort) => waitForTcp(port, bindTimeoutMs, abort), ended, boot, 'the co-located host', log).catch((error) => {
-      if (undeadPids([child.pid!]).length) recordWorldStop([log], 'world.service.stop', 'up (startup failed)', 'SIGTERM');
-      try { process.kill(-child.pid!, 'SIGTERM'); } catch { /* best effort cleanup */ }
-      throw new Error(`Co-located twin "${service.id}" failed to start (host isolation=${isolation}): ${error instanceof Error ? error.message : String(error)}\nLog: ${log}`);
-    });
-  });
-  let hostSettleTimer: ReturnType<typeof setTimeout> | undefined;
-  const hostSettle = new Promise<'alive'>((resolveAlive) => { hostSettleTimer = setTimeout(() => resolveAlive('alive'), 300); });
-  try {
-    await parallelStartup(allocated, async ({ service, port }) => {
-      // The host has completed every start. Each matching boot answer can now
-      // end its own settle; legacy twins share one full host guard.
-      await confirmOwnPort(port, boot, ended, true, `Co-located twin "${service.id}"`, log, true, hostSettle).catch((error) => {
-        if (undeadPids([child.pid!]).length) recordWorldStop([log], 'world.service.stop', 'up (port not its own)', 'SIGTERM');
-        try { process.kill(-child.pid!, 'SIGTERM'); } catch { /* best effort cleanup */ }
-        throw error;
-      });
-    });
-  } finally { if (hostSettleTimer !== undefined) clearTimeout(hostSettleTimer); }
-  if (exitState.value !== null) {
-    throw new Error(
-      `The co-located host ended during startup even though its ports answer, so other/stale processes probably hold them: the host ${endedAccount(log)}\n`
-      + `Stop leftover services (e.g. \`volter-world down\`) and retry.\nLog: ${log}`,
-    );
-  }
-
   const host = '127.0.0.1';
-  return allocated.map(({ service, port, mounted }) => {
+  // Every twin's address is known once its port is allocated: the records and
+  // the environment they inject exist before the host reports its starts.
+  const services = allocated.map(({ service, port, mounted }) => {
     const url = `http://${host}:${port}`;
     return {
       id: service.id,
@@ -1443,6 +1411,45 @@ async function startColocatedServices(
       },
     };
   });
+  const ready = (async (): Promise<void> => {
+    const hostTimeoutMs = allocated.reduce((timeout, { service }) => Math.max(timeout, typeof service.ready === 'object' ? service.ready.timeoutMs ?? 15_000 : 15_000), 15_000);
+    await untilReadyOrEnded((abort) => waitForHostReady(readyFile, boot.bootId, new Map(allocated.map(({ service, port }) => [service.id, port])), hostTimeoutMs, abort), ended, boot, 'the co-located host', log).catch((error) => {
+      if (undeadPids([child.pid!]).length) recordWorldStop([log], 'world.service.stop', 'up (host startup incomplete)', 'SIGTERM');
+      try { process.kill(-child.pid!, 'SIGTERM'); } catch { /* best effort cleanup */ }
+      throw new Error(`Co-located host failed to complete startup (isolation=${isolation}): ${error instanceof Error ? error.message : String(error)}\nLog: ${log}`);
+    });
+    await parallelStartup(allocated, async ({ service, port }) => {
+      const bindTimeoutMs = typeof service.ready === 'object' && service.ready.timeoutMs !== undefined ? Math.max(service.ready.timeoutMs, 15_000) : 15_000;
+      await untilReadyOrEnded((abort) => waitForTcp(port, bindTimeoutMs, abort), ended, boot, 'the co-located host', log).catch((error) => {
+        if (undeadPids([child.pid!]).length) recordWorldStop([log], 'world.service.stop', 'up (startup failed)', 'SIGTERM');
+        try { process.kill(-child.pid!, 'SIGTERM'); } catch { /* best effort cleanup */ }
+        throw new Error(`Co-located twin "${service.id}" failed to start (host isolation=${isolation}): ${error instanceof Error ? error.message : String(error)}\nLog: ${log}`);
+      });
+    });
+    // The host's receipt (this boot, every requested port) is published only
+    // after every factory bound its own port; a port another process held fails
+    // its bind and leaves no receipt. The receipt is the host's ownership proof
+    // for each port, so no twin waits out a settle (ADR-0008). A port that
+    // answers with another boot's identity is still refused.
+    const hostSettle = Promise.resolve('alive' as const);
+    await parallelStartup(allocated, async ({ service, port }) => {
+      await confirmOwnPort(port, boot, ended, true, `Co-located twin "${service.id}"`, log, true, hostSettle).catch((error) => {
+        if (undeadPids([child.pid!]).length) recordWorldStop([log], 'world.service.stop', 'up (port not its own)', 'SIGTERM');
+        try { process.kill(-child.pid!, 'SIGTERM'); } catch { /* best effort cleanup */ }
+        throw error;
+      });
+    });
+    if (exitState.value !== null) {
+      throw new Error(
+        `The co-located host ended during startup even though its ports answer, so other/stale processes probably hold them: the host ${endedAccount(log)}\n`
+        + `Stop leftover services (e.g. \`volter-world down\`) and retry.\nLog: ${log}`,
+      );
+    }
+  })();
+  // Observed here so a failure before the caller awaits it is not unhandled;
+  // the caller awaits `ready` before the World is up.
+  ready.catch(() => undefined);
+  return { services, ready };
 }
 
 export async function upWorld(configId: string, options: UpWorldOptions = {}, abort?: AbortSignal): Promise<WorldInstance> {
@@ -1669,12 +1676,19 @@ export async function upWorld(configId: string, options: UpWorldOptions = {}, ab
       const allocatedPorts = new Set(loaded.config.services.flatMap((service) => typeof service.port === 'number' ? [service.port] : []));
       // Non-'process' isolation: boot every colocate-declaring service inside ONE host child
       // first; anything without `colocate` (and externals) still goes through the spawn path.
+      // The co-located host's twins are known by address once their ports are
+      // allocated. A twin serves and calls no other service while it starts,
+      // so a later twin declaration starts beside the host's startup; any other
+      // service waits until every earlier one is ready, as declared (ADR-0009).
+      let colocatedReady: Promise<void> | undefined;
       if (isolation !== 'process') {
         const colocated = loaded.config.services.filter((service) => service.colocate && service.type !== 'external');
-        for (const started of await startColocatedServices(loaded.config, colocated, isolation, env, { root, instance, logs, data }, allocatedPorts, boot)) {
+        const host = await startColocatedServices(loaded.config, colocated, isolation, env, { root, instance, logs, data }, allocatedPorts, boot);
+        for (const started of host.services) {
           services[started.id] = started;
           Object.assign(env, started.env);
         }
+        colocatedReady = host.ready;
         recordPidsSoFar();
         writeProxyEnv(root, name, env);
       }
@@ -1706,6 +1720,7 @@ export async function upWorld(configId: string, options: UpWorldOptions = {}, ab
       };
       for (const service of loaded.config.services) {
         if (services[service.id]) continue; // already up co-located
+        if (colocatedReady && (service.type ?? 'twin') !== 'twin') { await colocatedReady; colocatedReady = undefined; }
         attemptProxy();
         boot.signal.throwIfAborted();
         const started = await startService(loaded.config, service, env, { root, instance, logs, data }, allocatedPorts, boot);
@@ -1714,6 +1729,7 @@ export async function upWorld(configId: string, options: UpWorldOptions = {}, ab
         Object.assign(env, started.env);
         writeProxyEnv(root, name, env);
       }
+      if (colocatedReady) await colocatedReady;
       detachBootSignals();
       // Re-evaluate once more after the LAST service: a single/last-twin world's OWN vendor twin
       // only lands in `env` once IT has started, so a check that only runs "before starting the