@volter/world-core 3.0.163 → 3.0.165

package/dist/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/dist/src/browser-session.d.ts

@@ -1,7 +1,13 @@
 import type { HandlerContext } from './derived-core.js';
+import { type Person } from './people.js';
 type Writer = Pick<HandlerContext, 'record' | 'secret' | 'occurredAt'>;
-/** The named cookie, without interpreting any other vendor's cookie. */
+/** The value of the cookie `name` the request carries, as a browser sends it back. */
+export declare function cookieOf(request: Request, name: string): string | undefined;
+/** The named session cookie; malformed encodings do not name a session. */
 export declare function browserSessionToken(request: Request, name: string): string | 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 declare function signedIn(ctx: HandlerContext, cookie: string, scope?: string): Person | undefined;
 /** A new, independent sign-in, returning the cookie the vendor places on its response. */
 export declare function startBrowserSession(ctx: Writer, email: string, cookie: string, scope?: string): Promise<string>;
 /** End the session the request holds, then clear its cookie. Unknown cookies create no rows. */

package/dist/src/browser-session.js

@@ -1,18 +1,29 @@
-/** The named cookie, without interpreting any other vendor's cookie. */
-export function browserSessionToken(request, name) {
+import { personOf } from "./people.js";
+/** The value of the cookie `name` the request carries, as a browser sends it back. */
+export function cookieOf(request, name) {
     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, name) {
+    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, cookie, scope) {
+    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, email, cookie, scope) {
     const issued = await ctx.record('_web_session_issue', { email, ...(scope !== undefined ? { scope } : {}) });

package/dist/src/browser.d.ts

@@ -9,5 +9,9 @@ export type SeedBrowser = {
     context(options: BrowserContext): Promise<void>;
     state(): Promise<BrowserState>;
 };
+/** 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 declare function password(address: string): Promise<string>;
 /** A seed's named browser. Every state write goes through the World's single HTTP loader. */
 export declare function browser(name: string): Promise<SeedBrowser>;

package/dist/src/browser.js

@@ -64,6 +64,16 @@ function vendorResponse(response, vendor, twin, mount) {
     }
     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) {
+    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.js");
+    return worldSecret('_world', nodeBuiltin('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) {
     assertBrowserName(name);

package/dist/src/derived-core.d.ts

@@ -9,7 +9,7 @@ import type { RateBudgetDeclaration } from './rateBudget.js';
 import { type HandlerCrypto } from './signing.js';
 import { type ManagedDatabase } from './managed-database.js';
 import { type RedisDialect, type RunItem } from './redis/engine.js';
-import { type Mail, type SmtpRoute } from './smtp.js';
+import { type Mail, type MailReply } from './smtp.js';
 export { ownField, parseBracketForm } from './form.js';
 import { type MultipartPart } from './multipart.js';
 import type { CorsDecl } from './cors.js';
@@ -450,6 +450,31 @@ export type PerformHookArgs = {
     blob: (key: string) => Promise<Uint8Array | null>;
 };
 export type PerformHook = (args: PerformHookArgs) => Promise<import('./head.js').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 declare function fillTemplate(template: string, row: Record<string, unknown>): string;
+/** 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 declare function gitRepositoryOf(m: DerivedManifest, name: string, root?: string): {
+    store: GitObjectStore;
+    refs: GitRefs;
+};
+/** 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 declare function gitNameOf(m: DerivedManifest, id: string, root?: string): string;
 export type DerivedManifest = {
     /** Vendor data-plane hosts mapped to an already-running customer guest. */
     machineRoutes?: ReadonlyArray<{
@@ -562,6 +587,15 @@ 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?: {
@@ -914,7 +948,7 @@ export type CoreScope = {
     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;
 };
 /** World-owned generated values use the same private seed and log as pack secrets. */
@@ -937,7 +971,7 @@ type VendorNameRule = {
 export declare const LANE_HEADER = "x-volter-lane";
 /** 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;
@@ -994,15 +1028,21 @@ export type SemanticsContext = {
         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>;

package/dist/src/derived-core.js

@@ -61,6 +61,44 @@ export function stateOf(decl, value) {
     }
     return value === undefined || value === null ? String(decl.initial) : String(value);
 }
+/** A template over a row's fields (`{field}`, a dotted path read through objects), every name filled or refused. */
+export function fillTemplate(template, row) {
+    return template.replace(/\{([^}]+)\}/g, (_, name) => {
+        const value = name.split('.').reduce((at, k) => (at !== null && typeof at === 'object' ? at[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, name, root) {
+    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, id, root) {
+    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);
+}
 // ── request parsing ──────────────────────────────────────────────────────────────────────────
 /** A body's fields as a strict vendor checks them (`ctx.fields`, the manifest's `body.strict`). Without `strict`, every
  *  field passes. An object or array field is not typed here: its own shape is the handler's. */
@@ -623,9 +661,9 @@ function mintId(m, resource, root, at, snapshot) {
  *  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();
+const lastSnowflake = new WeakMap();
 function mintSnowflake(m, epoch, root, at, snapshot) {
     const ms = BigInt(Date.parse(at) || 0);
     const base = ms > epoch ? (ms - epoch) << 22n : 0n;
@@ -640,11 +678,13 @@ function mintSnowflake(m, epoch, root, at, snapshot) {
                     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);
 }
 /** The next KSUID for a resource (Clerk's and Svix's ids, `ksuidFrom`): the World's instant, then the type's mint
@@ -901,6 +941,17 @@ function recordedInput(m, call, merged) {
 const scopeOfCall = new WeakMap();
 /** The intact copy contextFor already keeps for core(), before a handler can consume its request. */
 const requestOfCall = new WeakMap();
+/** 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, resource, fields, input, root) {
+    const push = m.git?.push;
+    if (!push || push.resource !== resource || typeof input.door !== 'string')
+        return input;
+    const fill = (template) => 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, call, resource, id, fields, operation, params, root, occurredAt, checks) {
     const before = stateBeforeWrite(m, resource, id, root);
     const prior = counted(m, resource) ? stored(m, resource, root).find((r) => r.id === id) : undefined;
@@ -909,7 +960,7 @@ async function writeDetailed(m, call, resource, id, fields, operation, params, r
     // 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' } }, root);
+        : { 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);
     return finishWrite(m, call, resource, row, result, operation, params, root, occurredAt, prior && { ...prior });
 }
@@ -947,7 +998,7 @@ async function finishWrite(m, call, resource, row, result, operation, params, ro
         const endpoint = (kind) => ({ ...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() });
@@ -1572,13 +1623,9 @@ export async function contextFor(m, call, scope) {
         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/dist/src/derived-real.js

@@ -1,10 +1,11 @@
 import { parseExactJson, exactInteger, compareExactNumbers } from "./exact-json.js";
 import { aliasesFrom, parentEntries, readParentTreeMap, readTree, wholeLog } from "./log.js";
-import { storedType } from "./derived-core.js";
+import { fillTemplate, gitNameOf, gitRepositoryOf, storedType } from "./derived-core.js";
 import { verifyEvent } from "./events.js";
 import { hashFieldValue } from "./hash.js";
 import { readResourceBlob, writeResourceBlob } from "./resource-blob.js";
-import { RefusedWriteError } from "./head.js";
+import { RefusedWriteError, settlingEntries } from "./head.js";
+import { ZERO_SHA, fetchPack, isAncestor, lsRemote, sendPack } from "./git/index.js";
 import { observeResources } from "./observe.js";
 import { readRoot } from "./state-system.js";
 /** A JSON path's value: `a.b`, `a[0].b`, `$body.a` (the leading `$body.` read as the root). */
@@ -490,6 +491,8 @@ function performOf(units) {
     return async (execute, group, ctx) => {
         await adoptAccount(units, execute, ctx);
         const input = (group[0].input ?? {});
+        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")
@@ -505,6 +508,133 @@ function performOf(units) {
         });
     };
 }
+const pushInputOf = (e) => object(e.input?.git);
+/** 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 {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+/** 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, remote) {
+    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, execute, group, ctx) {
+    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) => { 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 = (work) => work.catch((error) => {
+        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();
+    for (const p of pushes)
+        targets.set(p.push.ref, p.push.after);
+    const refused = new Map();
+    const commands = [];
+    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)}` })) } : {}),
+    };
+}
+/** 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, execute, root, name, remote) {
+    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 = [];
+    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) => 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, root, staged) {
+    const { refs } = gitRepositoryOf(staged.m, staged.name, root);
+    refs.withLock(() => {
+        const waiting = new Set(settlingEntries(service, root).offered.map(pushInputOf).filter((p) => p?.name === staged.name).map((p) => p.ref));
+        const untouched = (ref) => !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`).
@@ -682,10 +812,10 @@ function refreshOf(units, service) {
                         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;
@@ -700,7 +830,19 @@ function refreshOf(units, service) {
                             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;
+                        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.worldFields?.[resource] ?? {};
                         const fields = Object.fromEntries(Object.entries(full).filter(([k]) => !(k in local)));
                         if (decl.parent) {
@@ -1026,8 +1168,20 @@ function refreshOf(units, service) {
                         }
                     }
             }
+        // the code of each repository observed, read over git; its refs are published with the blobs, once every read succeeded
+        const mirrors = [];
+        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, unread } : report;

package/dist/src/derived.d.ts

@@ -13,7 +13,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/dist/src/events.d.ts

@@ -164,6 +164,8 @@ export declare function eventTypeOf(decl: Pick<EventsDecl, 'types' | 'known'>, o
 /** Whether an endpoint's list of event types takes a type: every type when the list is empty, `*` or `<family>.*`
  *  its patterns, else the type itself. */
 export declare function takesEvent(list: unknown, type: string): boolean;
+/** Await already-scheduled first dispatches and consume their retained persistence failures. */
+export declare function settleEventDeliveries(root: string): Promise<void>;
 /** 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 & {
@@ -179,13 +181,14 @@ export type ApplicationAnswer = {
     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>;
@@ -198,4 +201,4 @@ export type ApplicationStandIn = (url: string, init: RequestInit) => Promise<{
 export declare function askApplication(url: string, init: RequestInit, within: number, standIn?: ApplicationStandIn): Promise<ApplicationAnswer>;
 /** Every event a write sends, rendered, stored when the vendor keeps its events, signed, delivered to each endpoint
  *  that takes it, and recorded. */
-export declare function deliverEvents(service: string, decl: EventsDecl, write: EventWrite, data: (type: string) => Promise<Record<string, unknown>>, transport?: EventTransport, values?: (type: string) => Promise<Record<string, unknown>>): Promise<EventDelivery[]>;
+export declare function deliverEvents(service: string, decl: EventsDecl, write: EventWrite, data: (type: string) => Promise<Record<string, unknown>>, transport?: EventTransport, values?: (type: string) => Promise<Record<string, unknown>>, application?: ApplicationStandIn): Promise<EventDelivery[]>;