@volter/world-runtime 2.0.49 → 2.0.51

package/dist/src/changeset.d.ts

@@ -48,7 +48,9 @@ export declare function createWorldChangeset(world: string, name: string, option
     verifiers?: ChangesetVerifier[];
     now?: Date;
     overwrite?: boolean;
-    message?: string;
+    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;
 /** Every changeset in every world under `root` (or one world with `world`), newest first. */
 export declare function listWorldChangesets(options?: WorldRootOptions & {

package/dist/src/changeset.js

@@ -1,3 +1,4 @@
+import { worldChangesetRules } from "./configs.js";
 import { blobDigest, captureHistory, captureParentHistory, getActiveBlobStore, getActiveWorldStore, withAncestryLock, worldPaths } 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
@@ -183,6 +184,8 @@ export function createWorldChangeset(world, name, options = {}) {
         ...(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
@@ -373,7 +376,7 @@ export function approveWorldChangeset(name, options) {
 export function statusWorldChangeset(name, options = {}) {
     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));
 }
 export async function pushWorldChangeset(name, options) {
     // PUSH (docs/concepts/the-model.md): the changeset goes to the served world's push door; its
@@ -541,7 +544,8 @@ export async function pushWorldChangeset(name, options) {
     const receipts = 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 = receipts.every((r) => r.status !== 'failed') ? 'applied' : receipts.some((r) => r.status === 'confirmed') ? 'partial' : 'refused';
     const application = { 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/dist/src/configs.d.ts

@@ -1,4 +1,4 @@
-import { type WorldConfig } from './schema.js';
+import { type WorldChangesetRules, type WorldConfig } from './schema.js';
 export declare function resolveConfigPath(config: string, root?: string): string;
 export declare function loadWorldConfig(config: string, root?: string): {
     path: string;
@@ -16,3 +16,6 @@ export type WorldConfigMigration = {
 };
 /** Explicit, backed-up, atomic format-1 → format-2 migration. Ordinary reads never call this. */
 export declare function migrateWorldConfig(config: string, root?: string): WorldConfigMigration;
+/** 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 declare function worldChangesetRules(root: string): WorldChangesetRules;

package/dist/src/configs.js

@@ -1,6 +1,6 @@
 import { copyFileSync, constants, existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { basename, dirname, resolve } from 'node:path';
-import { getActiveWorldStore } from '@volter/world-core';
+import { basename, dirname, join, resolve } from 'node:path';
+import { getActiveWorldStore, stateDirName } from '@volter/world-core';
 import { assertWorldConfig, LEGACY_WORLD_SELECTION, worldConfigDocument } from "./schema.js";
 export function resolveConfigPath(config, root = process.cwd()) {
     const candidates = config.includes('/') || config.endsWith('.json')
@@ -117,3 +117,16 @@ export function migrateWorldConfig(config, root = process.cwd()) {
         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) {
+    const path = join(root, stateDirName(), 'world.json');
+    if (!getActiveWorldStore().exists(path) && !existsSync(path))
+        return {};
+    try {
+        return loadWorldConfig(path, root).config.changesets ?? {};
+    }
+    catch {
+        return {};
+    }
+}

package/dist/src/fixture-env.js

@@ -194,6 +194,10 @@ const CREDENTIAL_SHAPES = [
     { 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/dist/src/index.d.ts

@@ -1,6 +1,7 @@
 export type { WorldConfig, WorldInstance, WorldIsolation, WorldMode, WorldServiceConfig, WorldServiceType, WorldExternalServiceConfig, WorldExternalDiscover, WorldExternalDiscoverSource, WorldExternalReadyWhen, WorldRunOutcome, WorldRunRecord, WorldResourceRequirements, WorldManifestV2, WorldSelection, WorldSelectionSelector, WorldUsage, } from './schema.js';
 export { DEFAULT_WORLD_SELECTION, LEGACY_WORLD_SELECTION, WORLD_SCHEMA_VERSION, WORLD_USAGES, worldConfigDocument, worldSelectionIncludes } from './schema.js';
-export { loadWorldConfig, migrateWorldConfig, resolveConfigPath, writeWorldConfig } from './configs.js';
+export type { WorldChangesetRules } from './schema.js';
+export { loadWorldConfig, migrateWorldConfig, resolveConfigPath, worldChangesetRules, writeWorldConfig } from './configs.js';
 export type { WorldConfigMigration } from './configs.js';
 export { upWorld, downWorld, pruneWorlds, listWorlds, statusWorld, doctorWorld, runWithWorldEnv, attachWorld, retireWorldConsumers, activateScript, shellWorld, worldShellEnv, ensureWorldProxy, runProxyDaemon, runWorld, shareWorld, shareWorldServices, unshareWorld, urlsWorld, urlWorld, } from './runtime.js';
 export type { WorldCleanupEntry } from './runtime.js';

package/dist/src/index.js

@@ -1,5 +1,5 @@
 export { DEFAULT_WORLD_SELECTION, LEGACY_WORLD_SELECTION, WORLD_SCHEMA_VERSION, WORLD_USAGES, worldConfigDocument, worldSelectionIncludes } from "./schema.js";
-export { loadWorldConfig, migrateWorldConfig, resolveConfigPath, writeWorldConfig } from "./configs.js";
+export { loadWorldConfig, migrateWorldConfig, resolveConfigPath, worldChangesetRules, writeWorldConfig } from "./configs.js";
 export { upWorld, downWorld, pruneWorlds, listWorlds, statusWorld, doctorWorld, runWithWorldEnv, attachWorld, retireWorldConsumers, activateScript, shellWorld, worldShellEnv, ensureWorldProxy, runProxyDaemon, runWorld, shareWorld, shareWorldServices, unshareWorld, urlsWorld, urlWorld, } from "./runtime.js";
 export { worldResourceReport } from "./resources.js";
 // `volter-world app-url` — the recorded, queryable app endpoint of an instance (see app-url.ts).

package/dist/src/root.js

@@ -12,7 +12,7 @@ import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join, relative, resolve } from 'node:path';
 import { authStrategyFor, currentSealer, destinationOf, sealsThroughVault, openSealedAt, getActiveWorldStore, getPack, buildRemoteExecute, clearRoot, readRoot, registerStateSystem, stateDirName, stateSystemFor, validateRemoteOrigin, writeRoot, } from '@volter/world-core';
-import { loadWorldConfig, writeWorldConfig } from "./configs.js";
+import { loadWorldConfig, worldChangesetRules, writeWorldConfig } from "./configs.js";
 import { changesetReadiness, collectObservations, foldObservations, loadChecks, openRootCredential, performEntries, rootCustody, protocolStanding } from '@volter/world-core';
 import { findWorldChangeset, listWorldChangesets } from "./changeset.js";
 import { importModule } from "./import-module.js";
@@ -577,7 +577,7 @@ export async function deployWorld(name, opts = {}) {
     const out = [];
     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)
@@ -589,7 +589,7 @@ export async function deployWorld(name, opts = {}) {
     const located = opts.changeset ? [findWorldChangeset(opts.changeset, { root: worldRoot, world: name })] : listWorldChangesets({ root: worldRoot, world: name });
     const ready = new Map();
     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)

package/dist/src/runtime.js

@@ -1342,7 +1342,7 @@ function versionSatisfies(actual, pin) {
  */
 async function startColocatedServices(config, colocated, isolation, worldEnv, paths, allocatedPorts, boot) {
     if (colocated.length === 0)
-        return [];
+        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 = [hostCli, '--isolation', isolation === 'colocated' ? 'shared' : 'worker', '--ready-file', readyFile];
@@ -1381,55 +1381,10 @@ async function startColocatedServices(config, colocated, isolation, worldEnv, pa
         exitState.value = { code, signal };
     });
     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;
-    const hostSettle = new Promise((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,
@@ -1448,6 +1403,55 @@ async function startColocatedServices(config, colocated, isolation, worldEnv, pa
             },
         };
     });
+    const ready = (async () => {
+        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');
+        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, options = {}, abort) {
     abort?.throwIfAborted();
@@ -1698,12 +1702,19 @@ export async function upWorld(configId, options = {}, abort) {
             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;
             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);
             }
@@ -1736,6 +1747,10 @@ export async function upWorld(configId, options = {}, abort) {
             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);
@@ -1744,6 +1759,8 @@ export async function upWorld(configId, options = {}, abort) {
                 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

package/dist/src/schema.d.ts

@@ -51,6 +51,7 @@ export type WorldManifestV2 = {
         share?: WorldShareConfig;
     };
     remotes?: Record<string, string>;
+    changesets?: WorldChangesetRules;
     scenario?: {
         actors?: Record<string, unknown>;
         fixtures?: Record<string, unknown>;
@@ -268,8 +269,17 @@ export type WorldServiceConfig = {
      *  catalog the world was born against. Exact version or `^major.minor` range. */
     version?: string;
 };
+/** How this World's changesets are made and readied (docs/reference/config.md, `changesets`): how many people must
+ *  approve one's current contents before it deploys, and whether a cut needs its author's summary or takes the one
+ *  generated from its changes. A team's rules, committed with the World, as a repository's are. */
+export type WorldChangesetRules = {
+    approvals?: number;
+    summary?: 'required' | 'generated';
+};
 export type WorldConfig = {
     id: string;
+    /** How changesets are made and readied here; omitted: one approval, a summary required. */
+    changesets?: WorldChangesetRules;
     /** Real external origins; omitted preserves legacy routing, [] explicitly closes egress. */
     network?: WorldNetwork;
     /** Internal normalized source format and saved discovery selection. */
@@ -452,3 +462,5 @@ export declare function assertWorldConfig(value: unknown, path: string): WorldCo
 export declare function worldSelectionIncludes(selection: WorldSelection, vendor: string, usage: WorldUsage): boolean;
 /** Serialize normalized intent as the committed format-2 manifest. */
 export declare function worldConfigDocument(config: WorldConfig, selection?: WorldSelection): WorldManifestV2 & Record<string, unknown>;
+/** A World's changeset rules, strictly: `approvals` a whole number 0–10, `summary` `required` or `generated`, nothing else. */
+export declare function assertChangesetRules(rules: unknown, path: string): asserts rules is WorldChangesetRules;

package/dist/src/schema.js

@@ -132,6 +132,8 @@ function assertLegacyWorldConfig(value, path) {
             if (typeof target !== 'string' || target === '' || !/^[A-Za-z0-9._-]+$/.test(name))
                 throw new Error(`World config remote "${name}" must be a non-empty url or path in ${path}`);
     }
+    if (config.changesets !== undefined)
+        assertChangesetRules(config.changesets, path);
     if (config.isolation !== undefined && config.isolation !== 'process' && config.isolation !== 'colocated' && config.isolation !== 'worker') {
         throw new Error(`World config isolation must be "process", "colocated", or "worker" in ${path}`);
     }
@@ -458,7 +460,7 @@ function serviceV2ToLegacy(value, path) {
     return legacy;
 }
 function normalizeV2(value, path) {
-    assertKeys(value, ['schemaVersion', 'metadata', 'discovery', 'services', 'runtime', 'serving', 'remotes', 'scenario', 'provenance'], 'World manifest', path, true);
+    assertKeys(value, ['schemaVersion', 'metadata', 'discovery', 'services', 'runtime', 'serving', 'remotes', 'changesets', 'scenario', 'provenance'], 'World manifest', path, true);
     for (const name of ['metadata', 'discovery', 'runtime', 'serving', 'scenario', 'provenance'])
         if (value[name] !== undefined && !record(value[name]))
             throw new Error(`${name} must be an object in ${path}`);
@@ -515,6 +517,7 @@ function normalizeV2(value, path) {
         ...(mode === 'bare' ? { bare: { name: serving.name } } : {}),
         ...(serving.share === undefined ? {} : { share: serving.share }),
         ...(value.remotes === undefined ? {} : { remotes: value.remotes }),
+        ...(value.changesets === undefined ? {} : { changesets: value.changesets }),
         ...(scenario.actors === undefined ? {} : { actors: scenario.actors }),
         ...(scenario.fixtures === undefined ? {} : { fixtures: scenario.fixtures }),
         ...(provenance.catalog === undefined ? {} : { catalog: provenance.catalog }),
@@ -604,6 +607,7 @@ export function worldConfigDocument(config, selection = config.selection ?? DEFA
                 ...(config.share === undefined ? {} : { share: config.share }),
             } }),
         ...(config.remotes === undefined ? {} : { remotes: config.remotes }),
+        ...(config.changesets === undefined ? {} : { changesets: config.changesets }),
         ...(config.actors === undefined && config.fixtures === undefined ? {} : { scenario: {
                 ...(config.actors === undefined ? {} : { actors: config.actors }),
                 ...(config.fixtures === undefined ? {} : { fixtures: config.fixtures }),
@@ -612,3 +616,16 @@ export function worldConfigDocument(config, selection = config.selection ?? DEFA
         ...Object.fromEntries(Object.entries(config).filter(([key]) => key.startsWith('//'))),
     };
 }
+/** A World's changeset rules, strictly: `approvals` a whole number 0–10, `summary` `required` or `generated`, nothing else. */
+export function assertChangesetRules(rules, path) {
+    if (typeof rules !== 'object' || rules === null || Array.isArray(rules))
+        throw new Error(`World config changesets must be an object in ${path}`);
+    for (const key of Object.keys(rules))
+        if (key !== 'approvals' && key !== 'summary')
+            throw new Error(`World config changesets has no "${key}" (approvals, summary) in ${path}`);
+    const { approvals, summary } = rules;
+    if (approvals !== undefined && !(Number.isInteger(approvals) && approvals >= 0 && approvals <= 10))
+        throw new Error(`World config changesets.approvals must be a whole number from 0 to 10 in ${path}`);
+    if (summary !== undefined && summary !== 'required' && summary !== 'generated')
+        throw new Error(`World config changesets.summary must be "required" or "generated" in ${path}`);
+}

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

@@ -3,7 +3,7 @@ import { type TwinStreamConnection, type TwinStreamSink } from '@volter/world-co
 import { type TrustedIssuer } from '@volter/world-access';
 import { type Changeset, type Receipt } from '@volter/world-core';
 import { rootForControlRoot } from './root.js';
-import type { WorldInstance } from './schema.js';
+import { type WorldInstance } from './schema.js';
 export declare const TOKEN_HEADER = "x-volter-token";
 /** The header the injector carries a hosted World's token in (inject.cjs, VOLTER_TWINS_KEY). */
 export declare const TWINS_KEY_HEADER = "x-twins-key";
@@ -63,7 +63,8 @@ export declare function mountWorld(name: string, opts?: {
     root?: string; /** the host's branches of this World, by its served name */
     branches?: (served: string) => BranchDoors | undefined; /** the origin a browser reaches this World at, when the host gives each World one */
     browserOrigin?: (served: string) => string | null; /** served on this machine's loopback: its own pages need no token (DoorHost.localTrust) */
-    localTrust?: boolean; /** DoorHost.serveBranch */
+    localTrust?: boolean; /** the person signed in on this machine: its own page acts as them (DoorHost.localPerson) */
+    localPerson?: string; /** DoorHost.serveBranch */
     serveBranch?: (branch: string) => Promise<void>;
 }): Promise<MountedWorld>;
 /** Boot the world (state kept) and serve it on its own port. Announces and returns after boot; `stop` downs the world. */
@@ -138,6 +139,8 @@ export type DoorHost = {
      *  loopback name, is given the World's session without a token (`localSession`). A remote host leaves it absent,
      *  and its pages sign in with a token. */
     localTrust?: () => boolean;
+    /** whom this machine's own page acts as: the person `volter login` signed in here, if any ("Who acted is recorded") */
+    localPerson?: () => string | undefined;
     /** The platforms whose passes open this World (docs/contributing/architecture.md, "The hosted product"): a person a
      *  trusted platform signed a pass for is given a session of the pass's scope. Absent, or empty, no pass opens it. */
     passIssuers?: () => TrustedIssuer[];
@@ -220,6 +223,9 @@ export declare 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. */
     private keyPerson;
+    /** 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). */
+    private keyName;
     /** 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. */
     private revokeKeys;
@@ -276,6 +282,10 @@ export declare class WorldDoors {
      *  (`person` when it names no one), `token` / `token:read` for the World's own tokens; null when it presented nothing
      *  this World issued. */
     private callerOf;
+    /** 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. */
+    private personOf;
+    private keyOf;
     /** 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. */