@volter/world-core 3.0.163 → 3.0.165

package/pack-facts.cjs

@@ -1,8 +1,8 @@
 // THE PACK FACTS a process routes by (docs/contributing/architecture.md, "The catalog: where twins come from"): the facts
-// this kernel was built with (generated/pack-facts.json, compiled from the packs of its checkout), overlaid by the facts
-// of the packs the World resolved from installed packages. Each released pack carries its own
-// (`generated/pack-facts.json`), and the World's instance file (VOLTER_WORLD_INSTANCE, which every World process already
-// has) names them as `packFacts`. A pack's own facts replace the built-in ones for its vendor. Plain CommonJS, no
+// the platform owns (generated/pack-facts.json: its server backings, scripts/pack-facts.ts), overlaid by the facts of the
+// packs the World installs (ADR 0034, decision 2). Each pack carries its own (`generated/pack-facts.json`), and the
+// World's instance file (VOLTER_WORLD_INSTANCE, which every World process already has) names them as `packFacts`; a
+// pack the World has not installed is unknown to it. Plain CommonJS, no
 // dependency: the injector preloads it. Read once per process.
 'use strict';
 const fs = require('fs');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-core",
-  "version": "3.0.163",
+  "version": "3.0.165",
   "description": "The kernel of Volter World: one log per twin, branches as pointers, checkpoints, the fold that keeps a twin current, the head that performs a write against the vendor, references, and the git plane. A twin package builds on it; the runtime serves it.",
   "keywords": [
     "twin",
@@ -169,6 +169,7 @@
     "zod": "^4.4.2"
   },
   "devDependencies": {
+    "@volter/twin-stripe": "3.0.6",
     "@types/bun": "^1.2.20",
     "@types/node": "^24.0.0",
     "typescript": "^5.9.0",
@@ -181,7 +182,8 @@
     "node": ">=22.3"
   },
   "optionalDependencies": {
-    "@xmldom/xmldom": "0.9.12"
+    "@xmldom/xmldom": "0.9.12",
+    "parse5": "7.3.0"
   },
   "packageManager": "pnpm@12.15.0",
   "devEngines": {

package/src/browser-session.ts

@@ -1,19 +1,31 @@
 // A vendor's browser session: the bookkeeping used by its own sign-in and sign-out pages.
 import type { HandlerContext } from './derived-core.ts';
+import { personOf, type Person } from './people.ts';
 
 type Writer = Pick<HandlerContext, 'record' | 'secret' | 'occurredAt'>;
 
-/** The named cookie, without interpreting any other vendor's cookie. */
-export function browserSessionToken(request: Request, name: string): string | undefined {
+/** The value of the cookie `name` the request carries, as a browser sends it back. */
+export function cookieOf(request: Request, name: string): string | undefined {
   for (const part of (request.headers.get('cookie') ?? '').split(';')) {
     const at = part.indexOf('=');
-    if (at > 0 && part.slice(0, at).trim() === name) {
-      try { return decodeURIComponent(part.slice(at + 1).trim()); } catch { return undefined; }
-    }
+    if (at > 0 && part.slice(0, at).trim() === name) return decodeURIComponent(part.slice(at + 1).trim());
   }
   return undefined;
 }
 
+/** The named session cookie; malformed encodings do not name a session. */
+export function browserSessionToken(request: Request, name: string): string | undefined {
+  try { return cookieOf(request, name); } catch { return undefined; }
+}
+
+/** The person the request's session cookie names, or undefined when nobody is signed in; with `scope`, only a session
+ *  begun in it (a vendor's sandbox dashboard and its production one sign a person in apart). */
+export function signedIn(ctx: HandlerContext, cookie: string, scope?: string): Person | undefined {
+  const token = cookieOf(ctx.call.request, cookie);
+  const session = token ? ctx.rowsRaw('_web_session').find((s) => s.token === token && (scope === undefined || s.scope === scope)) : undefined;
+  return session ? personOf(ctx, String(session.email)) : undefined;
+}
+
 /** A new, independent sign-in, returning the cookie the vendor places on its response. */
 export async function startBrowserSession(ctx: Writer, email: string, cookie: string, scope?: string): Promise<string> {
   const issued = await ctx.record('_web_session_issue', { email, ...(scope !== undefined ? { scope } : {}) });

package/src/browser.ts

@@ -60,6 +60,16 @@ function vendorResponse(response: Response, vendor: URL, twin: URL, mount: strin
   return changed ? new Response(response.body, { status: response.status, statusText: response.statusText, headers }) : response;
 }
 
+/** The one password of an address in this World (ADR 0033 §5): `worldSecret('_world', <data>/_world,
+ *  'password:<address>')`, retained World state, so a seed signs a person up with it and a twin keeps only its hash. A
+ *  seed reads it beside `browser(name)`; it is never a literal in a committed file. */
+export async function password(address: string): Promise<string> {
+  const data = process.env.VOLTER_WORLD_DATA;
+  if (!process.env.VOLTER_WORLD || !data) throw new Error('password(address) runs in a World seed, with its data directory');
+  const { worldSecret } = await import('./derived-core.ts');
+  return worldSecret('_world', nodeBuiltin<typeof import('node:path')>('path').join(data, '_world'), `password:${address}`);
+}
+
 /** A seed's named browser. Every state write goes through the World's single HTTP loader. */
 export async function browser(name: string): Promise<SeedBrowser> {
   assertBrowserName(name);

package/src/derived-core.ts

@@ -11,7 +11,7 @@ import { parseExactJson, compareExactNumbers, exactInteger, isExactIntegerValue
 import { applyTwinWrite, applyTwinWriteAtomic, applyTwinWrites, twinResources, type TwinResource } from './serve.ts';
 import { copyResource, foldLocalWrite, heldSubject, ownFields, parentStamp, subjectHistory, treeChangesSince, treeResources, treeStamp, type Subject } from './log.ts';
 import { performsAtHeadNow } from './head.ts';
-import { getActiveWorldStore } from './world-store.ts';
+import { getActiveWorldStore, type WorldStore } from './world-store.ts';
 import { getActiveBlobStore } from './blob-store.ts';
 import { worldPaths } from './storage.ts';
 import { GitObjectStore } from './git/objects.ts';
@@ -31,7 +31,7 @@ import { readResourceBlob, readResourceBlobRange, removeResourceBlob, resourceBl
 import { managedDatabase, unboundDatabase, type ManagedDatabase } from './managed-database.ts';
 import { redisServiceTimes } from './redis/service-times.ts';
 import { execRedisRun, type RedisDialect, type RunItem } from './redis/engine.ts';
-import { sendMail, type Mail, type SmtpRoute } from './smtp.ts';
+import { sendMail, type Mail, type MailReply } from './smtp.ts';
 import { ownField, parseBracketForm } from './form.ts';
 export { ownField, parseBracketForm } from './form.ts';
 import { multipartBoundary, multipartParts, type MultipartPart } from './multipart.ts';
@@ -340,6 +340,45 @@ export type PerformHookArgs = {
 };
 export type PerformHook = (args: PerformHookArgs) => Promise<import('./head.ts').PushOutcome>;
 
+export type GitRepositoryDecl = { resource: string; name: string; remote: string };
+export type GitPushDecl = { resource: string; repository: string; remote: string; ref: string; before: string; after: string };
+
+/** A template over a row's fields (`{field}`, a dotted path read through objects), every name filled or refused. */
+export function fillTemplate(template: string, row: Record<string, unknown>): string {
+  return template.replace(/\{([^}]+)\}/g, (_, name: string) => {
+    const value = name.split('.').reduce<unknown>((at, k) => (at !== null && typeof at === 'object' ? (at as Record<string, unknown>)[k] : undefined), row);
+    if (value === undefined || value === null || typeof value === 'object') throw new Error(`template ${template}: no value for ${name}`);
+    return String(value);
+  });
+}
+
+/** A pack's git repository `name` in a World (the store and refs `ctx.git(name)` answers), under the twin's state and,
+ *  for a namespaced account, that account's. */
+export function gitRepositoryOf(m: DerivedManifest, name: string, root?: string): { store: GitObjectStore; refs: GitRefs } {
+  if (!/^[A-Za-z0-9_.-]+(\/[A-Za-z0-9_.-]+)*$/.test(name) || name.split('/').some((seg) => seg === '.' || seg === '..')) throw new Error(`semantics: ${name} is not a git repository name`);
+  const account = accountScope(m);
+  const plane = `${worldPaths(m.service, root).dir}/git${account && account !== 'default' ? `/accounts/${encodeURIComponent(account)}` : ''}`;
+  return { store: new GitObjectStore(getActiveBlobStore(), `${plane}/repos/${name}`), refs: new GitRefs(getActiveWorldStore(), `${plane}/repos/${name}`) };
+}
+
+/** The name a repository row's code is kept under: the manifest's `git.repository.name` (a template over `{id}` alone)
+ *  filled with the row's first World id, the one an adoption rebound to the vendor's (walked back through the aliases),
+ *  so the screen, a refresh, a deploy and a waiting push's protection name one repository before and after adoption. */
+export function gitNameOf(m: DerivedManifest, id: string, root?: string): string {
+  const decl = m.git?.repository;
+  if (!decl) throw new Error(`${m.vendor}: the manifest declares no git repositories`);
+  if (decl.name.replace(/\{id\}/g, '').includes('{')) throw new Error(`${m.vendor}: git.repository.name is a template over {id} alone`);
+  const type = `${storedType(m, decl.resource)}:`;
+  const aliases = aliasesNow(m.service, root);
+  let first = id;
+  for (let hops = 0; hops < 8; hops++) {
+    const from = [...aliases].find(([local, vendor]) => vendor === first && local.startsWith(type))?.[0];
+    if (from === undefined) break;
+    first = from.slice(type.length);
+  }
+  return decl.name.replace(/\{id\}/g, first);
+}
+
 export type DerivedManifest = {
   /** Vendor data-plane hosts mapped to an already-running customer guest. */
   machineRoutes?: ReadonlyArray<{ host: string; resource: string; where: Record<string, string>; name: string; port: number | string }>;
@@ -409,6 +448,12 @@ export type DerivedManifest = {
   ingest?: IngestDecl;
   /** the vendor's documented limits, charged by the executor on every live call (D8) */
   rateBudget?: RateBudgetDeclaration;
+  /** where the vendor's repositories' code lives, as templates over a row's fields (`{field}`) (architecture, "The
+   *  real-system adapters"; ADR 0031): the resource whose rows are the vendor's repositories, the name each is kept under
+   *  (over `{id}` alone: the row's first World id, `gitNameOf`) and its remote (the vendor's absolute git URL), which a
+   *  refresh fetches; and the resource a push to a World repository records, one row per ref, with the World id of the
+   *  repository row it pushed to, which a deploy pushes */
+  git?: { repository: GitRepositoryDecl; push: GitPushDecl };
   /** a pack whose wire has no derived perform (a socket, a line protocol, a managed database): binding a root is refused
    *  with this reason */
   vendorBacked?: { none: string };
@@ -937,7 +982,7 @@ export type CoreScope = {
   root?: string; clock?: () => string; database?: string; readOnly?: boolean;
   /** `semantics/tenant.ts`: the tenant the caller acts in (the manifest's `tenant`), or undefined for none */
   tenant?: (ctx: HandlerContext) => string | undefined | Promise<string | undefined>;
-  /** the application a walk stands in for: what the vendor asks it (`ctx.ask`) is answered by it (events.ts) */
+  /** the application a walk stands in for: vendor requests and declared events are answered by it (events.ts) */
   application?: ApplicationStandIn;
 };
 
@@ -1138,9 +1183,9 @@ function mintId(m: DerivedManifest, resource: string, root: string | undefined,
  *  increment. One space over every snowflake resource of the vendor, as its one generator's: the instant's first, or one
  *  past the greatest the World holds when that is later (a frozen clock, or several ids in one millisecond), so ids
  *  rise with time and never repeat. */
-/** The last snowflake minted per vendor and World in this process: two mints before the first is written (a message
+/** The last snowflake minted per store, vendor and World: two mints before the first is written (a message
  *  and its attachment) must not meet. */
-const lastSnowflake = new Map<string, bigint>();
+const lastSnowflake = new WeakMap<WorldStore, Map<string, bigint>>();
 function mintSnowflake(m: DerivedManifest, epoch: bigint, root: string | undefined, at: string, snapshot?: readonly TwinResource[]): string {
   const ms = BigInt(Date.parse(at) || 0);
   const base = ms > epoch ? (ms - epoch) << 22n : 0n;
@@ -1149,11 +1194,13 @@ function mintSnowflake(m: DerivedManifest, epoch: bigint, root: string | undefin
     if (!/^\{snowflake:\d+\}$/.test(decl.ids ?? m.ids.template)) continue;
     for (const r of mintRows(m, name, root, snapshot)) if (/^\d+$/.test(r.id)) { const v = BigInt(r.id); if (v > max) max = v; }
   }
+  const store = getActiveWorldStore();
+  const reservations = lastSnowflake.get(store) ?? lastSnowflake.set(store, new Map()).get(store)!;
   const key = `${m.service}\0${root ?? ''}`;
-  const last = lastSnowflake.get(key) ?? -1n;
+  const last = reservations.get(key) ?? -1n;
   const floor = max > last ? max : last;
   const id = base > floor ? base : floor + 1n;
-  lastSnowflake.set(key, id);
+  reservations.set(key, id);
   return String(id);
 }
 
@@ -1397,6 +1444,17 @@ const scopeOfCall = new WeakMap<DerivedCall, CoreScope>();
 /** The intact copy contextFor already keeps for core(), before a handler can consume its request. */
 const requestOfCall = new WeakMap<DerivedCall, Request>();
 
+/** A row of the manifest's `git.push.resource` a screen writes (a client's push to a World repository) records the push
+ *  it is, which a deploy sends to the vendor as a git push (head.ts settlingEntries offers it; derived-real.ts performs
+ *  it). One an operation of the surface writes (an API commit, a ref the API creates) is that operation's, which a
+ *  deploy sends again. */
+function pushedInput(m: DerivedManifest, resource: string, fields: Record<string, unknown>, input: Record<string, unknown>, root: string | undefined): Record<string, unknown> {
+  const push = m.git?.push;
+  if (!push || push.resource !== resource || typeof input.door !== 'string') return input;
+  const fill = (template: string): string => fillTemplate(template, fields);
+  return { ...input, git: { name: gitNameOf(m, fill(push.repository), root), remote: fill(push.remote), ref: fill(push.ref), before: fill(push.before), after: fill(push.after) } };
+}
+
 async function writeDetailed(m: DerivedManifest, call: DerivedCall, resource: string, id: string, fields: Record<string, unknown>, operation: string, params: Record<string, unknown>, root: string | undefined, occurredAt: string, checks?: StateChecks): Promise<{ body: Record<string, unknown>; id: string; vendorData?: unknown }> {
   const before = stateBeforeWrite(m, resource, id, root);
   const prior = counted(m, resource) ? stored(m, resource, root).find((r) => r.id === id) as Record<string, unknown> | undefined : undefined;
@@ -1406,7 +1464,7 @@ async function writeDetailed(m: DerivedManifest, call: DerivedCall, resource: st
     // a vendor's own move (ctx.asVendor, the clock) is the World's, as the clock's writes are: no API call a head performs
     inVendorMove()
       ? { operation, subjectType: storedType(m, resource), subjectId: id, fields, input: { clock: true }, occurredAt, actor: { kind: 'system' } }
-      : { operation, subjectType: storedType(m, resource), subjectId: id, fields, input: await withFiles(recordedInput(m, call, params)), occurredAt, actor: { kind: 'agent' } },
+      : { operation, subjectType: storedType(m, resource), subjectId: id, fields, input: pushedInput(m, resource, fields, await withFiles(recordedInput(m, call, params)), root), occurredAt, actor: { kind: 'agent' } },
     root,
   );
   observeStateWrite(m, result, before, root, checks);
@@ -1452,7 +1510,7 @@ async function finishWrite(m: DerivedManifest, call: DerivedCall, resource: stri
     const endpoint = (kind: import('./events.ts').EndpointsDecl): import('./events.ts').EndpointsDecl => ({ ...kind, storedAs: storedType(m, kind.storedAs), ...(kind.joins ? { joins: Object.fromEntries(Object.entries(kind.joins).map(([name, join]) => [name, { ...join, storedAs: storedType(m, join.storedAs) }])) } : {}) });
     const events = { ...m.events, ...(m.events.store ? { store: storedType(m, m.events.store) } : {}), endpoints: 'storedAs' in m.events.endpoints ? endpoint(m.events.endpoints) : m.events.endpoints.map(endpoint) };
     const write = { operation, storedType: m.resources[resource]?.storedAs ?? resource, body, ...(root !== undefined ? { root } : {}), occurredAt, request: request.clone() };
-    await deliverEvents(m.service, events, write, async (type) => (events.render ? events.render(await context(), write, type) : body), undefined, events.values ? async (type) => events.values!(await context(), write, type) : undefined);
+    await deliverEvents(m.service, events, write, async (type) => (events.render ? events.render(await context(), write, type) : body), undefined, events.values ? async (type) => events.values!(await context(), write, type) : undefined, scopeOfCall.get(call)?.application);
   }
   if (m.sockets?.length) socketWrite(m.service, root, { operation, storedType: m.resources[resource]?.storedAs ?? resource, body, ...(root !== undefined ? { root } : {}), occurredAt, request: request.clone() });
   // a read held until the World writes (held-reads.ts) hears it
@@ -1507,7 +1565,7 @@ function decodeOffset(cursor: unknown): number {
 
 /** What a coverage measurement sees of a pack's declared state logic: each move a request made and each refusal a
  *  guard gave, by the transition that decided it. Nothing is observed unless a measurement installs an observer
- *  (scripts/life-coverage.ts); serving never depends on it. */
+ *  (`twin-standard coverage`); serving never depends on it. */
 export type TransitionEntry = { action: TwinAction; field: string; actor: Actor };
 export type TransitionObserver = (decl: StateField, transition: Transition, outcome: 'moved' | 'refused', from: string, entry?: TransitionEntry) => void;
 let transitionObserver: TransitionObserver | undefined;
@@ -1979,15 +2037,18 @@ export type SemanticsContext = {
    *  World's repository-scoped content-addressed object store, its refs in the World's store. Served over smart HTTP
    *  (`git.serveSmartHttp`), read and written through the library's codecs. */
   git(name: string): { store: GitObjectStore; refs: GitRefs };
+  /** The git repository of a row of the manifest's `git.repository.resource`, under the one name it keeps through
+   *  adoption (`gitNameOf`). */
+  gitRepository(row: Record<string, unknown>): { store: GitObjectStore; refs: GitRefs };
   /** A value the World set for its application (world-env.ts): what the app was given and the vendor must agree with (a
    *  webhook signing secret the app verifies with), never the caller's own shell; undefined when the World sets none. */
   worldEnv(name: string): string | undefined;
   /** Runs `fn` as the vendor's own move, not the caller's: what time makes due (a renewal a read catches up) is
    *  recorded with no caller, wherever a handler reaches it. */
   asVendor<T>(fn: () => Promise<T>): Promise<T>;
-  /** A mail the vendor sends a person, over SMTP to the route its settings name (smtp.ts), under the World's egress rule;
-   *  throws when it cannot be delivered. */
-  mail(route: SmtpRoute, mail: Mail, headers?: Record<string, string>): Promise<void>;
+  /** A mail the vendor hands on, over SMTP to the World's twin that receives each recipient's domain (smtp.ts, ADR 0032
+   *  §3): each recipient's reply, `250` delivered and `5xx` refused; a domain no twin receives is refused by the kernel. */
+  mail(mail: Mail): Promise<MailReply[]>;
   now(): unknown;
   /** Render a stored row or vendor view using its resource declaration, retaining the stored subject id fallback. */
   render(row: Record<string, unknown>, resource?: string): Record<string, unknown>;
@@ -2252,12 +2313,9 @@ export async function contextFor(m: DerivedManifest, call: DerivedCall, scope: C
     ask: (url, init, within) => askApplication(url, init, within, scope.application),
     worldEnv: (name) => worldEnvValue(name),
     asVendor: (fn) => runAsVendorMove(fn),
-    git: (name) => {
-      if (!/^[A-Za-z0-9_.-]+(\/[A-Za-z0-9_.-]+)*$/.test(name) || name.split('/').some((seg) => seg === '.' || seg === '..')) throw new Error(`semantics: ${name} is not a git repository name`);
-      const plane = `${worldPaths(m.service, root).dir}/git${accountScope(m) && accountScope(m) !== 'default' ? `/accounts/${encodeURIComponent(accountScope(m)!)}` : ''}`;
-      return { store: new GitObjectStore(getActiveBlobStore(), `${plane}/repos/${name}`), refs: new GitRefs(getActiveWorldStore(), `${plane}/repos/${name}`) };
-    },
-    mail: (route, mail, headers) => sendMail(route, mail, headers),
+    git: (name) => gitRepositoryOf(m, name, root),
+    gitRepository: (row) => gitRepositoryOf(m, gitNameOf(m, String(row.id), root), root),
+    mail: (mail) => sendMail(mail),
     now: () => now(m, at),
     render: (row, resource) => {
       const raw = rawResources.has(row);

package/src/derived-real.ts

@@ -5,12 +5,13 @@ import { parseExactJson, exactInteger, compareExactNumbers } from './exact-json.
 // reaches here, only its keyed fingerprint (`PerformContext.credential`, for the idempotency key).
 import type { TwinAction } from './actions.ts';
 import { aliasesFrom, parentEntries, readParentTreeMap, readTree, wholeLog } from './log.ts';
-import { storedType, type DerivedManifest, type IngestDecl, type ResourceDecl, type VendorManifest } from './derived-core.ts';
+import { fillTemplate, gitNameOf, gitRepositoryOf, storedType, type DerivedManifest, type IngestDecl, type ResourceDecl, type VendorManifest } from './derived-core.ts';
 import type { DerivedOperation, DerivedSurface } from './derived.ts';
 import { verifyEvent, type EventScheme } from './events.ts';
 import { hashFieldValue } from './hash.ts';
 import { readResourceBlob, writeResourceBlob } from './resource-blob.ts';
-import { RefusedWriteError, type PerformAction, type PerformContext, type PushOutcome } from './head.ts';
+import { RefusedWriteError, settlingEntries, type PerformAction, type PerformContext, type PushOutcome } from './head.ts';
+import { ZERO_SHA, fetchPack, isAncestor, lsRemote, sendPack, type SmartHttpTransport } from './git/index.ts';
 import { observeResources, type Completed, type ObservedResource } from './observe.ts';
 import type { RemoteExecute, RemoteExecuteResponse } from './remote-execute.ts';
 import { readRoot, type StateSystemAdapters } from './state-system.ts';
@@ -411,6 +412,7 @@ function performOf(units: Unit[]): PerformAction {
   return async (execute: RemoteExecute, group: TwinAction[], ctx: PerformContext): Promise<PushOutcome> => {
     await adoptAccount(units, execute, ctx);
     const input = (group[0]!.input ?? {}) as Row;
+    if (object(input.git)) return pushOf(units, execute, group, ctx);
     const unit = unitOf(units, input);
     // a protocol one request cannot express is the pack's hook, which composes the derived perform ("Protocols a
     // request cannot express")
@@ -426,6 +428,113 @@ function performOf(units: Unit[]): PerformAction {
   };
 }
 
+// ── git: a root's repositories over git's own smart HTTP (architecture, "The real-system adapters"; ADR 0031) ──
+
+type PushInput = { name: string; remote: string; ref: string; before: string; after: string };
+const pushInputOf = (e: TwinAction): PushInput | undefined => object((e.input as Row | undefined)?.git) as PushInput | undefined;
+
+/** A 4xx other than 408 and 429 from the vendor's git: a refusal, as a REST answer's is ("Perform", 3). */
+class GitAnswer extends Error { constructor(readonly status: number, message: string) { super(message); } }
+
+/** Git smart HTTP to a remote (the vendor's absolute git URL) over the root's executor, which applies the credential
+ *  (HostRule.basic) and charges the vendor's budget. */
+function gitTransport(execute: RemoteExecute, remote: string): SmartHttpTransport {
+  return async ({ service, body }) => {
+    const answer = await execute({
+      method: body === undefined ? 'GET' : 'POST',
+      path: body === undefined ? `${remote}/info/refs?service=${service}` : `${remote}/${service}`,
+      headers: {
+        'user-agent': 'git/2.0 (volter-twin)',
+        accept: body === undefined ? `application/x-${service}-advertisement` : `application/x-${service}-result`,
+        ...(body === undefined ? {} : { 'content-type': `application/x-${service}-request` }),
+      },
+      ...(body === undefined ? {} : { body }),
+      responseType: 'bytes',
+    });
+    if (answer.status !== 200) throw new GitAnswer(answer.status, `${answer.status}: git ${service} at ${remote}${answer.body ? `: ${answer.body.slice(0, 300)}` : ''}`);
+    return answer.bodyBytes ?? new TextEncoder().encode(answer.body);
+  };
+}
+
+/** DEPLOY a receive-pack's group (its push rows, one per ref): each ref's latest target decided on its own, the rest
+ *  sent in one push against the root's refs (atomic when the root offers it), never forced. Each entry settles as its
+ *  ref did (`PushOutcome.refused`); every ref refused refuses the group. */
+async function pushOf(units: Unit[], execute: RemoteExecute, group: TwinAction[], ctx: PerformContext): Promise<PushOutcome> {
+  const first = group[0]!;
+  const m = units.find((u) => u.manifest.git)?.manifest;
+  const pushes = group.map((e) => ({ entry: e, push: pushInputOf(e) }));
+  const refuseAll = (reason: string): never => { throw new RefusedWriteError('vendor', reason, first.id); };
+  if (!m || pushes.some((p) => p.push === undefined)) refuseAll('the push names no repository of the vendor\'s');
+  const { name, remote } = pushes[0]!.push!;
+  if (pushes.some((p) => p.push!.name !== name || p.push!.remote !== remote)) refuseAll('one push names one repository');
+  const { store } = gitRepositoryOf(m!, name, ctx.root);
+  const transport = gitTransport(execute, remote);
+  const answered = <T>(work: Promise<T>): Promise<T> => work.catch((error: unknown) => {
+    if (error instanceof GitAnswer && error.status >= 400 && error.status < 500 && error.status !== 408 && error.status !== 429) refuseAll(error.message);
+    throw error;
+  });
+  const root = await answered(lsRemote(transport, 'git-receive-pack'));
+  // each ref's latest target in the group, and why the root may not take it
+  const targets = new Map<string, string>();
+  for (const p of pushes) targets.set(p.push!.ref, p.push!.after);
+  const refused = new Map<string, string>();
+  const commands: Array<{ name: string; old: string; new: string }> = [];
+  for (const [ref, target] of targets) {
+    const old = root.refs.get(ref) ?? ZERO_SHA;
+    if (old === target) continue;
+    if (target !== ZERO_SHA && old !== ZERO_SHA) {
+      if (ref.startsWith('refs/tags/')) { refused.set(ref, 'the tag already exists on the root'); continue; }
+      if (!(await store.has(old))) { refused.set(ref, 'the root holds work this World has not fetched (fetch first)'); continue; }
+      if (!(await isAncestor(store, old, target))) { refused.set(ref, `not a fast-forward of the root's ${old.slice(0, 7)}`); continue; }
+    }
+    commands.push({ name: ref, old, new: target });
+  }
+  if (commands.length) {
+    const report = await answered(sendPack(transport, store, commands, [...new Set(root.refs.values())], root.caps.includes('atomic')));
+    for (const c of commands) { const reason = report.get(c.name); if (reason !== null) refused.set(c.name, `the root refused it: ${reason}`); }
+  }
+  const took = pushes.filter((p) => !refused.has(p.push!.ref));
+  if (!took.length) refuseAll([...refused].map(([ref, reason]) => `${ref}: ${reason}`).join('; '));
+  return {
+    externalId: '', actionId: took[0]!.entry.id,
+    ...(refused.size ? { refused: pushes.filter((p) => refused.has(p.push!.ref)).map((p) => ({ actionId: p.entry.id, reason: `${p.push!.ref}: ${refused.get(p.push!.ref)}` })) } : {}),
+  };
+}
+
+/** A repository's refs a refresh will publish: the root's branches and tags, its HEAD, and the World's refs as they
+ *  stood when the refresh read them. */
+type StagedMirror = { m: DerivedManifest; name: string; theirs: Map<string, string>; head: string | null; held: Map<string, string>; heldHead: string };
+
+/** REFRESH a repository's code, read: the root's advertisement and the objects of its branches and tags the World's
+ *  repository lacks (immutable: kept as they arrive). Its refs are staged, published by `publishMirror` once every read of
+ *  the refresh succeeded. */
+async function readMirror(m: DerivedManifest, execute: RemoteExecute, root: string | undefined, name: string, remote: string): Promise<StagedMirror> {
+  const { store, refs } = gitRepositoryOf(m, name, root);
+  const transport = gitTransport(execute, remote);
+  const advertised = await lsRemote(transport, 'git-upload-pack');
+  const theirs = new Map([...advertised.refs].filter(([ref]) => mirrored(ref)));
+  const held = new Map(refs.list().map((r) => [r.name, r.sha]));
+  const wants: string[] = [];
+  for (const sha of new Set(theirs.values())) if (!(await store.has(sha))) wants.push(sha);
+  await fetchPack(transport, store, wants, [...new Set(held.values())]);
+  return { m, name, theirs, head: advertised.head, held, heldHead: refs.head() };
+}
+const mirrored = (ref: string): boolean => ref.startsWith('refs/heads/') || ref.startsWith('refs/tags/');
+
+/** REFRESH a repository's code, published: by compare-and-set under the repository's ref lock, the lock receive-pack
+ *  holds. A ref takes the root's value, or is deleted when the root holds it no more, only while it still holds what the
+ *  refresh read and no offered push names it (read inside the lock); HEAD follows the root's only while unchanged. */
+function publishMirror(service: string, root: string | undefined, staged: StagedMirror): void {
+  const { refs } = gitRepositoryOf(staged.m, staged.name, root);
+  refs.withLock(() => {
+    const waiting = new Set(settlingEntries(service, root).offered.map(pushInputOf).filter((p): p is PushInput => p?.name === staged.name).map((p) => p.ref));
+    const untouched = (ref: string): boolean => !waiting.has(ref) && (refs.get(ref) ?? undefined) === staged.held.get(ref);
+    for (const [ref, sha] of staged.theirs) if (untouched(ref)) refs.set(ref, sha);
+    for (const ref of staged.held.keys()) if (mirrored(ref) && !staged.theirs.has(ref) && untouched(ref)) refs.delete(ref);
+    if (staged.head?.startsWith('refs/heads/') && refs.head() === staged.heldHead) refs.setHead(staged.head);
+  });
+}
+
 /** Path parameters that name a subject by a field rather than its id, sent as the vendor's value of that field, read
  *  from the adopted landed copy ("Perform", step 1): a parent found by `parent.where` (a repository addressed as
  *  `{owner}/{repo}`), and a subject named by the number it counts per parent (`number`, an issue's `issue_number`).
@@ -583,8 +692,8 @@ function refreshOf(units: Unit[], service: string): NonNullable<StateSystemAdapt
             const sent = asked.length ? `${target}${target.includes('?') ? '&' : '?'}${new URLSearchParams(asked)}` : target;
             const answer = await execute({ method: op.method.toUpperCase(), path: sentTo(m, sent, subject), ...onLane, headers: fixedHeaders(op) });
             // a door's subject the vendor does not show the root (another bot's private chat) stays as the World holds it
-            if (!rooted.has(key) && answer.status >= 400 && answer.status !== 429) continue;
             if (answer.status === 401) throw new Error(`401: the vendor refused the root's credential (${op.method.toUpperCase()} ${path}); nothing folded`);
+            if (!rooted.has(key) && answer.status >= 400 && answer.status !== 429) continue;
             if (answer.status === 403) { unread.push({ type, path, status: 403 }); refused = true; break; }
             if (answer.status === 429) throw new Error(`429: rate limited${answer.headers['retry-after'] ? `, retry after ${answer.headers['retry-after']}s` : ''}`);
             read.push(String(subject.id));
@@ -592,7 +701,15 @@ function refreshOf(units: Unit[], service: string): NonNullable<StateSystemAdapt
             // the vendor's answer for a subject it no longer has: a 404, or the scope's `gone` (Telegram's 400 `chat not found`)
             if (answer.status === 404 || (scope.gone && answer.status === scope.gone.status && refusalWords(m, parse(answer)).includes(scope.gone.says))) continue;
             if (answer.status >= 400 || refusedIn(m, parse(answer))) throw new Error(`${m.vendor}: ${resource} refresh ${op.id} (${op.method.toUpperCase()} ${op.path}): ${answer.status}: ${refusalWords(m, parse(answer))}`);
-            const full = object(op.answers?.key ? at(parse(answer), op.answers.key) : parse(answer)) ?? {};
+            const parsed = parse(answer);
+            let full: Row;
+            if (op.answers?.list) {
+              const items = itemsOf(op, parsed);
+              const matching = items.find((item) => (scopeIdOf(scope, item) ?? storedIdOf(decl, item)) === vendorId);
+              if (!matching && items.length) throw new Error(`${m.vendor}: ${resource} refresh ${op.id} omitted the requested subject; nothing folded`);
+              if (!matching) continue;
+              full = matching;
+            } else full = object(op.answers?.key ? at(parsed, op.answers.key) : parsed) ?? {};
             const local = (m as { worldFields?: Record<string, Record<string, unknown>> }).worldFields?.[resource] ?? {};
             const fields = Object.fromEntries(Object.entries(full).filter(([k]) => !(k in local)));
             if (decl.parent) {
@@ -853,7 +970,17 @@ function refreshOf(units: Unit[], service: string): NonNullable<StateSystemAdapt
         }
       }
     }
+    // the code of each repository observed, read over git; its refs are published with the blobs, once every read succeeded
+    const mirrors: StagedMirror[] = [];
+    for (const { manifest: m } of units) {
+      if (!m.git) continue;
+      const { resource, remote } = m.git.repository;
+      for (const row of observed.filter((o) => o.type === storedType(m, resource) && o.deleted !== true)) {
+        mirrors.push(await readMirror(m, execute, opts.root, gitNameOf(m, row.id, opts.root), fillTemplate(remote, { ...row.fields, id: row.id })));
+      }
+    }
     for (const download of downloads) await writeResourceBlob(service, download.key, download.bytes, opts.root);
+    for (const staged of mirrors) publishMirror(service, opts.root, staged);
     adopt(service, opts.root, units, observed);
     const report = observeResources(service, observed, { ...(opts.root !== undefined ? { root: opts.root } : {}), complete });
     return unread.length ? { ...(report as object), unread } : report;

package/src/derived.ts

@@ -1,6 +1,6 @@
 import { parseExactJson } from './exact-json.ts';
 // THE DERIVED DISPATCH — the generated wire's router (docs/contributing/architecture.md, "The derived
-// pack"). A derived pack's surface (`src/generated/surface.gen.json`, written by scripts/derive-pack.ts)
+// pack"). A derived pack's surface (`src/generated/surface.gen.json`, written by `twin-standard derive`)
 // names every operation the vendor publishes. This matches a request to one of them and hands it to its
 // owner: the pack's semantics handler for that operationId when there is one, otherwise the pack's
 // existing fetch, which keeps serving everything not yet moved (and every route outside the spec, such
@@ -24,7 +24,7 @@ export type DerivedOperation = {
   headers?: Record<string, string | null>;
   /** the status the vendor answers success with (201 for a create, 204 for an empty answer) */
   successStatus?: number;
-  /** how the spec says the request body is encoded (derive-pack: json, form, multipart, none) */
+  /** how the spec says the request body is encoded (the derivation: json, form, multipart, none) */
   bodyEncoding?: string;
   /** the success is documented with no content (a setting's update answered 200 and nothing else) */
   emptySuccess?: boolean;

package/src/events.ts

@@ -7,11 +7,12 @@
 // Imports stay free of side effects: the delivery's transport (Node's http, the World's egress policy) is loaded when a
 // delivery is made, never when a browser client imports the kernel.
 import { createHash, createHmac } from 'node:crypto';
+import { resolve } from 'node:path';
 import { applyTwinWrite, applyTwinWriteAtomic, twinResources } from './serve.ts';
 import { equalSecrets as same, ksuidFrom } from './signing.ts';
 import { deliveryTraceHeaders } from './trace-context.ts';
 import { sendRecordedEvent } from './event-delivery.ts';
-import { getActiveWorldStore, withWorldStore } from './world-store.ts';
+import { getActiveWorldStore, withWorldStore, type WorldStore } from './world-store.ts';
 import { worldPaths } from './storage.ts';
 
 /** How the vendor signs a delivery. */
@@ -306,6 +307,26 @@ const worldTransport: EventTransport = async (url, body, headers) => {
   try { return ((await appFetch(url, { method: 'POST', headers: { 'content-type': 'application/json', ...headers }, body })) as { status: number }).status; } catch { return 0; }
 };
 
+const pendingDeliveries = new WeakMap<WorldStore, Map<string, Set<Promise<void>>>>();
+
+function forgetDeliveries(store: WorldStore, root: string, deliveries: Iterable<Promise<void>>): void {
+  const roots = pendingDeliveries.get(store), pending = roots?.get(root);
+  if (!pending) return;
+  for (const delivery of deliveries) pending.delete(delivery);
+  if (!pending.size) roots!.delete(root);
+  if (!roots!.size) pendingDeliveries.delete(store);
+}
+
+/** Await already-scheduled first dispatches and consume their retained persistence failures. */
+export async function settleEventDeliveries(root: string): Promise<void> {
+  const store = getActiveWorldStore(), path = resolve(root);
+  const deliveries = [...(pendingDeliveries.get(store)?.get(path) ?? [])];
+  const outcomes = await Promise.allSettled(deliveries);
+  forgetDeliveries(store, path, deliveries);
+  const failures = outcomes.flatMap((outcome) => outcome.status === 'rejected' ? [outcome.reason] : []);
+  if (failures.length) throw new AggregateError(failures, 'Declared-event dispatch failed');
+}
+
 /** Who watches signed packets before dispatch (a walk reading each as its receiver would). This is not evidence of
  *  transport or acceptance. Set and restored by the walk, as its World store is; unset, nothing watches. */
 export type DeliveryObserver = (delivery: EventDelivery & { service: string }) => void;
@@ -321,13 +342,14 @@ export function setDeliveryObserver(observer: DeliveryObserver | undefined): Del
  *  (`unreachable`), or it did not answer in time (`timeout`). */
 export type ApplicationAnswer = { status: number; headers: Record<string, string>; body: string; missed?: 'timeout' | 'unreachable' };
 
-/** Who answers what the vendor asks the application (`ctx.ask`) before the World's application route does, given to a
+/** Who answers a vendor's requests to the application before the World's application route does, given to a
  *  pack's fetch (`PackFetchOptions.application`) and belonging to that fetch alone: an answer it gives is the
  *  application's; `'unreachable'` is a question nobody answers (a walk's life, a sealed World, takes no other); undefined
  *  is a question it does not take, which goes on as any other does: the application route, the World's egress rule, the
  *  network. A walk's stand-in answers every question (its life's answers, else unreachable); a hosted World's router
  *  answers only what it can answer truthfully (WorldDoors.askInWorld) and leaves the rest. `bodyError` models a
- *  disconnect after the response headers; a caller needing the complete body receives no complete answer. */
+ *  disconnect after the response headers; a caller needing the complete body receives no complete answer, while an
+ *  event dispatch acknowledges the response status without reading its body. */
 export type ApplicationStandIn = (url: string, init: RequestInit) => Promise<{ status: number; headers?: Record<string, string>; body: string; bodyError?: string } | 'unreachable' | undefined>;
 
 /** A message the vendor sends the application's server and decides by its answer (Stripe's real-time authorization
@@ -367,10 +389,15 @@ export async function deliverEvents(
   data: (type: string) => Promise<Record<string, unknown>>,
   transport: EventTransport = worldTransport,
   values?: (type: string) => Promise<Record<string, unknown>>,
+  application?: ApplicationStandIn,
 ): Promise<EventDelivery[]> {
   if (write.storedType === decl.store) return [];
+  const dispatch: EventTransport = application ? async (url, body, headers) => {
+    const answer = await application(url, { method: 'POST', headers: { 'content-type': 'application/json', ...headers }, body });
+    return answer === undefined ? transport(url, body, headers) : answer === 'unreachable' ? 0 : answer.status;
+  } : transport;
   const sent: EventDelivery[] = [];
-  for (const type of eventTypesOf(decl, write.operation)) sent.push(...(await deliverEventType(service, decl, write, data, transport, values, type)));
+  for (const type of eventTypesOf(decl, write.operation)) sent.push(...(await deliverEventType(service, decl, write, data, dispatch, values, type)));
   return sent;
 }
 
@@ -466,10 +493,28 @@ async function deliverEventType(
   // active before it runs. Transport completion writes to the same retained state.
   const store = getActiveWorldStore(), deliveryRoot = worldPaths(service, write.root).root;
   for (const d of sent) deliveryObserver?.({ ...d, service });
-  for (const packet of recorded) setTimeout(() => {
-    // Persistence failure leaves a queued/sending claim for explicit recovery;
-    // it must not fail the already-committed vendor write or cause a blind resend.
-    void withWorldStore(store, () => sendRecordedEvent(service, packet.type, packet.id, deliveryRoot, transport, trace)).catch(() => {});
-  }, 0);
+  const roots = pendingDeliveries.get(store) ?? new Map<string, Set<Promise<void>>>();
+  pendingDeliveries.set(store, roots);
+  const pending = roots.get(deliveryRoot) ?? new Set<Promise<void>>();
+  roots.set(deliveryRoot, pending);
+  for (const packet of recorded) {
+    let finish!: () => void;
+    let fail!: (reason: unknown) => void;
+    const dispatched = new Promise<void>((done, reject) => { finish = done; fail = reject; });
+    // Live writes return before dispatch; an explicit settlement reports persistence failures.
+    void dispatched.catch(() => {});
+    pending.add(dispatched);
+    setTimeout(async () => {
+      try {
+        await withWorldStore(store, () => sendRecordedEvent(service, packet.type, packet.id, deliveryRoot, transport, trace));
+        finish();
+        forgetDeliveries(store, deliveryRoot, [dispatched]);
+      } catch (error) {
+        // Keep the rejection until explicit settlement consumes it. The queued/sending claim remains for
+        // native recovery; this must not fail the already-committed vendor write or cause a blind resend.
+        fail(error);
+      }
+    }, 0);
+  }
   return sent;
 }