@volter/world-runtime 2.0.49 → 2.0.51

package/src/schema.ts

@@ -32,6 +32,7 @@ export type WorldManifestV2 = {
   runtime?: { isolation?: WorldIsolation; environment?: { values?: Record<string, string>; strip?: string[] }; network?: WorldNetwork };
   serving?: { mode?: 'app' | 'bare'; name?: string; share?: WorldShareConfig };
   remotes?: Record<string, string>;
+  changesets?: WorldChangesetRules;
   scenario?: { actors?: Record<string, unknown>; fixtures?: Record<string, unknown> };
   provenance?: { catalog?: { sha: string; protocol?: string } };
 };
@@ -238,8 +239,15 @@ export type WorldServiceConfig = {
   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. */
@@ -512,6 +520,7 @@ function assertLegacyWorldConfig(value: unknown, path: string): WorldConfig {
     if (typeof config.remotes !== 'object' || Array.isArray(config.remotes)) throw new Error(`World config remotes must be an object of name → url|path in ${path}`);
     for (const [name, target] of Object.entries(config.remotes as Record<string, unknown>)) 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}`);
   }
@@ -789,7 +798,7 @@ function serviceV2ToLegacy(value: unknown, path: string): WorldServiceConfig {
 }
 
 function normalizeV2(value: Record<string, unknown>, path: string): WorldConfig {
-  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'] as const) if (value[name] !== undefined && !record(value[name])) throw new Error(`${name} must be an object in ${path}`);
   const metadata = value.metadata as Record<string, unknown> | undefined;
   if (!metadata) throw new Error(`World manifest must define metadata in ${path}`);
@@ -830,6 +839,7 @@ function normalizeV2(value: Record<string, unknown>, path: string): WorldConfig
     ...(mode === 'bare' ? { bare: { name: serving.name as string } } : {}),
     ...(serving.share === undefined ? {} : { share: serving.share as WorldShareConfig }),
     ...(value.remotes === undefined ? {} : { remotes: value.remotes as Record<string, string> }),
+    ...(value.changesets === undefined ? {} : { changesets: value.changesets as WorldChangesetRules }),
     ...(scenario.actors === undefined ? {} : { actors: scenario.actors as Record<string, unknown> }),
     ...(scenario.fixtures === undefined ? {} : { fixtures: scenario.fixtures as Record<string, unknown> }),
     ...(provenance.catalog === undefined ? {} : { catalog: provenance.catalog as WorldConfig['catalog'] }),
@@ -922,6 +932,7 @@ export function worldConfigDocument(config: WorldConfig, selection: WorldSelecti
       ...(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 }),
@@ -930,3 +941,12 @@ export function worldConfigDocument(config: WorldConfig, selection: WorldSelecti
     ...Object.fromEntries(Object.entries(config as Record<string, unknown>).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: unknown, path: string): asserts rules is WorldChangesetRules {
+  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 as Record<string, unknown>;
+  if (approvals !== undefined && !(Number.isInteger(approvals) && (approvals as number) >= 0 && (approvals as number) <= 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/src/served-world.ts

@@ -32,16 +32,16 @@ import { grantOf, presentedSecrets, sameSecret, spentPasses, verifyPass, type Tr
 import { createHash } from 'node:crypto';
 import { dirname, join, resolve } from 'node:path';
 import {
-  appendActionIfAbsent, branchEntries, branchLogPath, branchMetaPath, changesetContentHash, confirmAction, parentLogPath, readTree, stateDirName, wholeLog, worldNow,
+  appendActionIfAbsent, branchEntries, branchLogPath, branchMetaPath, changesetContentHash, changesetReadiness, confirmAction, parentLogPath, readTree, stateDirName, wholeLog, worldNow,
   parentEntries, readBranchMeta, rebaseBranch, type Changeset, type Entry, type Receipt, type RootConfig,
 } from '@volter/world-core';
 import { approveWorldChangeset, createWorldChangeset, diffWorld, findWorldChangeset, listWorldChangesets, pushWorldChangeset, verifyWorldChangeset, worldChangesetsDir } from './changeset.ts';
 import { fetchFromOrigin } from './origin.ts';
 import { CONSOLE_BASE, consoleRedirect, serveConsoleApart, type ConsoleMount } from './console-apart.ts';
-import { loadWorldConfig } from './configs.ts';
+import { loadWorldConfig, worldChangesetRules, writeWorldConfig } from './configs.ts';
 import { adaptersFor, credentialPath, packMirror, type PackMirror, credentialPayloadFrom, deployTwin, deployWorld, loadWorldChecks, twinSigningSecret, materializeRoots, refreshPosture, refreshTwin, rootForControlRoot, rewrapTwinCredentials, sealTwinCredential, sealedCredentialInfo, bindLegacyCredentials, setTwinRoot, spanMs } from './root.ts';
 import { clockFile, downWorld, listWorlds, statusWorld, upWorld } from './runtime.ts';
-import type { WorldInstance } from './schema.ts';
+import { assertChangesetRules, type WorldChangesetRules, type WorldInstance } from './schema.ts';
 
 export const TOKEN_HEADER = 'x-volter-token';
 /** The header the injector carries a hosted World's token in (inject.cjs, VOLTER_TWINS_KEY). */
@@ -83,8 +83,10 @@ export function keysFile(worldRoot: string): string { return join(worldRoot, sta
 type HeldKey = { id: string; name: string; scope: 'read' | 'write'; hash: string; createdAt: string; lastUsedAt?: string;
   /** who made it: the World's token, or a person's session (the subject a pass named, and its platform) */
   createdBy?: { via: 'token' } | { via: 'session'; sub?: string; who?: string; issuer?: string } | { via: 'key'; keyId: string };
-  /** the person it was made for, when the World's token made it on their behalf (a platform, for a command) */
+  /** the person it was made for, when the World's token made it on their behalf (a platform, for a command): their subject */
   for?: string;
+  /** that person as attribution names them (their email), beside the subject `for` revocation matches */
+  forName?: string;
   /** after this it opens nothing */
   expiresAt?: string;
   /** the branch this key is the parent's key of: the branch reaches its parent with it, and goes when it goes */
@@ -114,9 +116,9 @@ function configRefFor(worldRoot: string, name: string): string {
  *  with the call — and keeps them beside the world like `boot` does. */
 export type MountedWorld = { name: string; served: string; root: string; readonly token: string; readonly readToken: string; twins: () => string[]; rotate: () => { token: string; readToken: string }; handle: (request: Request) => Promise<Response>; boot: (url: string) => Promise<void>; stop: () => Promise<void> };
 /** A browser session a World keeps: its scope, when it ends, and the person a pass named, when one did. */
-type HeldSession = { scope: 'read' | 'write'; until: number; who?: string; /** the platform whose pass opened it */ issuer?: string; /** the person's subject there */ sub?: string; /** the read key a shared link opened it with: it lasts only while that key does */ key?: string };
+type HeldSession = { scope: 'read' | 'write'; until: number; /** opened by this machine's own page (localSession) */ local?: true; who?: string; /** the platform whose pass opened it */ issuer?: string; /** the person's subject there */ sub?: string; /** the read key a shared link opened it with: it lasts only while that key does */ key?: string };
 
-export async function mountWorld(name: string, opts: { /** the platforms whose passes open this World */ passIssuers?: TrustedIssuer[]; 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 */ serveBranch?: (branch: string) => Promise<void> } = {}): Promise<MountedWorld> {
+export async function mountWorld(name: string, opts: { /** the platforms whose passes open this World */ passIssuers?: TrustedIssuer[]; 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; /** 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> {
   const worldRoot = resolve(opts.root ?? process.cwd());
   const configRef = configRefFor(worldRoot, name);
   if (loadWorldConfig(configRef, worldRoot).config.resources) {
@@ -148,7 +150,7 @@ export async function mountWorld(name: string, opts: { /** the platforms whose p
     clockPath: () => clockFile(worldRoot, name),
     ...(opts.branches?.(served) ? { branches: opts.branches(served)! } : {}),
     ...(opts.browserOrigin ? { browserOrigin: () => opts.browserOrigin!(served), originOf: (other: string) => 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
@@ -334,6 +336,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[];
@@ -415,13 +419,13 @@ 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. */
-  private openSession(scope: 'read' | 'write', person?: { who: string; ttlMs: number; issuer: string; sub?: string }, key?: { id: string; until: number }): string {
+  private openSession(scope: 'read' | 'write', person?: { who: string; ttlMs: number; issuer?: string; sub?: string }, key?: { id: string; until: number }, local?: boolean): string {
     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
     if (person) { const theirs = Object.entries(held).filter(([, x]) => x.who === person.who).sort(([, a], [, b]) => b.until - a.until); if (theirs.length >= 5) { const drop = new Set(theirs.slice(4).map(([k]) => k)); held = Object.fromEntries(Object.entries(held).filter(([k]) => !drop.has(k))); } }
     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 as const } : {}), ...(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
@@ -443,6 +447,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. */
   private keyPerson(k: HeldKey): string | undefined { 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). */
+  private keyName(k: HeldKey): string | undefined { 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. */
   private async revokeKeys(pick: (k: HeldKey) => boolean): Promise<string[]> {
@@ -462,21 +469,24 @@ export class WorldDoors {
     if (via === 'key') 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 = (): HeldKey[] => this.keys().filter((k) => !k.expiresAt || Date.parse(k.expiresAt) > now);
-    const view = (k: HeldKey) => ({ 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: HeldKey) => ({ 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: HeldKey): string | undefined => this.keyPerson(k);
     if (!id && request.method === 'GET') return Response.json({ keys: live().map(view) });
     if (!id && request.method === 'POST') {
-      const body = (await request.json().catch(() => ({}))) as { name?: unknown; scope?: unknown; for?: unknown; expiresAt?: unknown; replace?: unknown };
+      const body = (await request.json().catch(() => ({}))) as { name?: unknown; scope?: unknown; for?: unknown; forName?: unknown; expiresAt?: unknown; replace?: unknown };
       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.
       const opener = via === 'session' && session ? this.sessions()[session] : undefined;
       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') return Response.json({ error: 'for and replace are the World token\'s' }, { status: 403 });
+      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: string | undefined;
       if (body.expiresAt !== undefined) { const t = typeof body.expiresAt === 'string' ? Date.parse(body.expiresAt) : NaN; if (!(t > now)) return Response.json({ error: 'expiresAt: an ISO instant in the future' }, { status: 400 }); expiresAt = new Date(t).toISOString(); }
       // replace: the key of the same name for the same person goes (one command, one key: asking again does not pile them up)
@@ -485,7 +495,7 @@ export class WorldDoors {
       const opened = via === 'session' && session ? this.sessions()[session] : undefined;
       const createdBy: HeldKey['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: HeldKey = { 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: HeldKey = { 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' } });
     }
@@ -627,10 +637,22 @@ export class WorldDoors {
   private callerOf(request: Request): string | null {
     const cred = this.credential(request);
     if (cred.scope === null) return null;
-    if (cred.via === 'session') return cred.who ? `person:${cred.who}` : 'person';
-    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'; }
+    // 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}` : 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 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. */
+  private personOf(request: Request): string | undefined {
+    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;
+  }
+  private keyOf(token: string | null): HeldKey | undefined { 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. */
@@ -1066,10 +1088,12 @@ export class WorldDoors {
     }
     if (kind === 'changesets' && request.method === 'GET') {
       // 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] }); }
+      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], 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 }));
@@ -1083,7 +1107,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 } : {}) }));
     }
@@ -1189,11 +1214,40 @@ 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)) as { changesets?: unknown } | 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 as WorldChangesetRules;
+        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(() => ({}))) as { name?: string; message?: string };
       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
@@ -1339,7 +1393,9 @@ export class WorldDoors {
   private localSession(url: URL): Response {
     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))! } });
   }
 
   private session(request: Request, url: URL, scope: 'read' | 'write', key?: { id: string; until: number }): Response {
@@ -1571,9 +1627,17 @@ export class WorldDoors {
 
   /** PUSH: see `landChangeset` — the door hands the body to it. */
   private async push(request: Request): Promise<Response> {
+    // 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()) as Changeset | { changeset: Changeset; expect?: Record<string, HistoryReference> };
-    const changeset = 'changeset' in body && !('actions' in body) ? body.changeset : (body as Changeset);
-    if (!changeset || !Array.isArray(changeset.actions)) return Response.json({ error: 'push: a changeset object' }, { status: 400 });
+    const sent = 'changeset' in body && !('actions' in body) ? body.changeset : (body as Changeset);
+    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: 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
@@ -1583,7 +1647,9 @@ 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 = ((): Changeset | null => { try { return JSON.parse(getActiveWorldStore().read(join(worldChangesetsDir(this.name, this.worldRoot), `${changeset.name}.json`)) ?? 'null') as Changeset | 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/src/world-view.ts

@@ -28,7 +28,7 @@ function branchRoots(dir: string): string[] {
   return out.sort();
 }
 
-export async function serveWorldView(name: string, opts: { root?: string; port?: number; host?: string; console?: ViewConsole; announce?: (line: string) => void; /** each World a browser steps into at an origin of its own (on by default on loopback) */ origins?: boolean; /** the World's own origin as a browser reaches it through a proxy on this machine (a desktop serving it as an app):
+export async function serveWorldView(name: string, opts: { /** the person signed in on this machine (`volter login`): this World's own page acts as them */ localPerson?: string; root?: string; port?: number; host?: string; console?: ViewConsole; announce?: (line: string) => void; /** each World a browser steps into at an origin of its own (on by default on loopback) */ origins?: boolean; /** the World's own origin as a browser reaches it through a proxy on this machine (a desktop serving it as an app):
    *  a request the proxy forwards from that host (X-Forwarded-Host) is answered as at that origin, its local session included */ origin?: string } = {}): Promise<WorldView> {
   const root = resolve(opts.root ?? process.cwd());
   const host = opts.host ?? '127.0.0.1';
@@ -49,7 +49,7 @@ export async function serveWorldView(name: string, opts: { root?: string; port?:
   // (the first World mounted is the World; every later one is a branch of it)
   let base: string | null = null;
   const browserOrigin = origins ? (served: string) => (proxied && (base === null || served === base) ? proxied.origin : port ? localWorldOrigin(served, port) : null) : undefined;
-  const mountAt = (at: string): Promise<MountedWorld> => 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: string): Promise<MountedWorld> => 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: LocalBranches = 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
@@ -80,7 +80,7 @@ export async function serveWorldView(name: string, opts: { root?: string; port?:
       if (branch === loadWorldConfig(join(root, stateDirName(), 'world.json'), root).config.id) rmSync(current, { force: true }); else writeFileSync(current, `${branch}\n`);
     } finally { switching = false; }
   };
-  const mountOpts = { root, branches: (served: string) => branches.doorsFor(served), ...(browserOrigin ? { browserOrigin } : {}), ...(local ? { localTrust: true } : {}), serveBranch };
+  const mountOpts = { root, branches: (served: string) => 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);