@volter/world-core 3.0.164 → 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.164",
+  "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.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

@@ -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 };
@@ -1399,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;
@@ -1408,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);
@@ -1509,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;
@@ -1981,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>;
@@ -2254,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`).
@@ -861,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/executor.ts

@@ -248,8 +248,8 @@ async function awsSigV4Headers(input: {
 /** `vendorHosts`: the pack's declared vendor host rules (its descriptor's `hosts`). An absolute https URL
  *  on one of them — an exact `host` rule whose `pathPattern` the path matches — is a second host of the
  *  same vendor that takes the credential (LinkedIn's image uploads on www.linkedin.com/dms-uploads,
- *  Instagram's rupload host); it is sent credentialed like an anchored call. Any other absolute URL is
- *  refused, as before. */
+ *  Instagram's rupload host); it is sent credentialed like an anchored call, as HTTP Basic when a rule naming
+ *  it names a `basic` user. Any other absolute URL is refused. */
 /** Where a credential is kept (the head's and refresh's root: head.ts rootCustody): `key` names the credential stably
  *  across rotations and anew when another is sealed in its place (the token cache is keyed by it, not by the secret's value), `open` reads it as sealed now, `seal` keeps a rotated one. */
 /** `unsealed`: where a rotation the seal failed to keep is recorded durably (the field and the cause, never a value), since
@@ -326,6 +326,8 @@ function direct(origin: URL, credential: CredentialPayload, auth?: Exclude<TwinA
     let target: URL;
     // the vendor's own URL, where a loopback root stands in for it: what a signature is made over
     let vendorUrl: URL | undefined;
+    // the user a host that takes the token as HTTP Basic's password names it under (HostRule.basic)
+    let basicUser: string | undefined;
     if (/^https:\/\//i.test(path) && vendorHosts?.length) {
       // a second host the pack declares for this vendor, on a path its rule names: validated as the root is
       target = new URL(path);
@@ -335,6 +337,7 @@ function direct(origin: URL, credential: CredentialPayload, auth?: Exclude<TwinA
         && (r.pathPattern === undefined || new RegExp(r.pathPattern).test(target.pathname));
       const declared = vendorHosts.some((r) => !r.exclude && named(r)) && !vendorHosts.some((r) => r.exclude && named(r));
       if (!declared) throw new Error(`remote execute: ${target.host}${target.pathname.slice(0, 64)} is not a host this vendor's pack declares for this path`);
+      basicUser = vendorHosts.find((r) => !r.exclude && r.basic !== undefined && named(r))?.basic;
       // A loopback root is the vendor substitute. Preserve the vendor Host while retaining
       // the already-validated root's mounted path; an absolute URL never escapes that root.
       if (isLoopbackHost(origin.hostname)) {
@@ -352,6 +355,14 @@ function direct(origin: URL, credential: CredentialPayload, auth?: Exclude<TwinA
     // a credential the vendor issued in this perform is the request's authorization; the sealed one stays home
     if (issued !== undefined) outbound.set('authorization', issued);
     else for (const [name, value] of Object.entries(credential.headers)) outbound.set(name, value);
+    // A HOST THAT TAKES THE TOKEN AS HTTP BASIC: the sealed authorization header's credentials, after its scheme, are
+    // Basic's password under the rule's user; one sealed as Basic goes as it is, and none sealed refuses before egress
+    if (issued === undefined && basicUser !== undefined) {
+      const sealed = outbound.get('authorization') ?? '';
+      const token = /^\S+\s+(\S.*)$/.exec(sealed)?.[1];
+      if (token === undefined) throw new Error(`remote execute: ${target.host} takes the credential as HTTP Basic, and the sealed credential carries no authorization header`);
+      if (!/^basic\s/i.test(sealed)) outbound.set('authorization', `Basic ${btoa(`${basicUser}:${token}`)}`);
+    }
     // the vendor's host, kept over any the credential carries (a loopback twin routes by it, as the World's proxy's)
     if (vendorUrl) { outbound.set('host', vendorUrl.host); outbound.set('x-volter-twin-original-host', vendorUrl.host); }
 

package/src/git/index.ts

@@ -6,3 +6,4 @@ export * from './smart-http.ts';
 export * from './history.ts';
 export * from './lfs.ts';
 export * from './format.ts';
+export * from './smart-http-client.ts';

package/src/git/smart-http-client.ts

@@ -0,0 +1,99 @@
+// THE CLIENT HALF OF SMART HTTP (gitprotocol-http, protocol v0): what `git fetch` and `git push` send to a server,
+// over a transport the caller supplies. The library opens no socket, holds no credential and names no host; a root's
+// refresh and deploy reach the vendor's git through it over the kernel executor (derived-real.ts, ADR 0031). It asks
+// only for what it reads: no side-band (the pack arrives bare), no multi_ack (one answer), no thin pack (every delta
+// base is in the pack or the store), ofs-delta (readPack resolves both delta kinds), and on a push report-status, with
+// atomic when the server offers it.
+import { concat, type GitObjectStore } from './objects.ts';
+import { readPack } from './pack.ts';
+import { FLUSH, ZERO_SHA, packObjects, pktLine, readPktLines, type Service } from './smart-http.ts';
+
+const DEC = new TextDecoder();
+const SHA = /^[0-9a-f]{40}$/;
+
+/** One exchange: `GET info/refs?service=<service>` when there is no body, `POST <service>` when there is. It answers
+ *  the response's bytes, and throws when the server did not answer 200. */
+export type SmartHttpTransport = (request: { service: Service; body?: Uint8Array }) => Promise<Uint8Array>;
+
+/** What a server advertises: its refs (peeled `^{}` lines dropped), the ref its HEAD names, and its capabilities. */
+export type RemoteRefs = { refs: Map<string, string>; head: string | null; caps: string[] };
+
+/** `GET info/refs?service=<service>`, read. */
+export async function lsRemote(transport: SmartHttpTransport, service: Service): Promise<RemoteRefs> {
+  let { lines, rest } = readPktLines(await transport({ service }));
+  if (lines[0]?.startsWith('# service=')) ({ lines, rest } = readPktLines(rest));
+  const refs = new Map<string, string>(); let head: string | null = null; let caps: string[] = [];
+  for (const raw of lines) {
+    const [line, offered] = raw.replace(/\n$/, '').split('\0') as [string, string | undefined];
+    if (line.startsWith('ERR ')) throw new Error(`git ${service}: ${line.slice(4)}`);
+    if (offered !== undefined) {
+      caps = offered.split(' ').filter(Boolean);
+      const symref = caps.find((c) => c.startsWith('symref=HEAD:'));
+      if (symref) head = symref.slice('symref=HEAD:'.length);
+    }
+    const sha = line.slice(0, 40); const name = line.slice(41);
+    if (!SHA.test(sha) || sha === ZERO_SHA || name === 'HEAD' || name.endsWith('^{}')) continue;
+    refs.set(name, sha);
+  }
+  return { refs, head, caps };
+}
+
+const isPack = (bytes: Uint8Array, at: number): boolean => DEC.decode(bytes.subarray(at, at + 4)) === 'PACK';
+
+/** `POST git-upload-pack` with `done`: every object `wants` reach and `haves` do not, read into `store`. */
+export async function fetchPack(transport: SmartHttpTransport, store: GitObjectStore, wants: string[], haves: string[]): Promise<void> {
+  if (wants.length === 0) return;
+  const answer = await transport({
+    service: 'git-upload-pack',
+    body: concat(
+      pktLine(`want ${wants[0]} ofs-delta no-progress agent=volter-twin\n`),
+      ...wants.slice(1).map((w) => pktLine(`want ${w}\n`)),
+      FLUSH,
+      ...haves.map((h) => pktLine(`have ${h}\n`)),
+      pktLine('done\n'),
+    ),
+  });
+  // the negotiation's ACK / NAK lines, then the pack
+  let at = 0;
+  while (at + 4 <= answer.length && !isPack(answer, at)) {
+    const len = parseInt(DEC.decode(answer.subarray(at, at + 4)), 16);
+    if (Number.isNaN(len)) break;
+    if (len < 4) { at += 4; continue; }
+    const line = DEC.decode(answer.subarray(at + 4, at + len));
+    if (line.startsWith('ERR ')) throw new Error(`git upload-pack: ${line.slice(4).trim()}`);
+    at += len;
+  }
+  if (!isPack(answer, at)) throw new Error('git upload-pack: the server answered no pack');
+  await readPack(answer.subarray(at), store);
+}
+
+/** One ref update a push asks for: `old` is the server's value as advertised (ZERO_SHA to create), `new` the object
+ *  to point it at (ZERO_SHA to delete). */
+export type PushCommand = { name: string; old: string; new: string };
+
+/** `POST git-receive-pack`: the commands and the pack of what they need beyond `haves`, atomic when `atomic` (the
+ *  server offered it). Answers each command's outcome by ref name: null when the server took it, else its reason. */
+export async function sendPack(transport: SmartHttpTransport, store: GitObjectStore, commands: PushCommand[], haves: string[], atomic = false): Promise<Map<string, string | null>> {
+  const updates = commands.filter((c) => c.new !== ZERO_SHA).map((c) => c.new);
+  const caps = `report-status${atomic ? ' atomic' : ''} agent=volter-twin`;
+  const answer = await transport({
+    service: 'git-receive-pack',
+    body: concat(
+      ...commands.map((c, i) => pktLine(`${c.old} ${c.new} ${c.name}${i === 0 ? `\0${caps}` : ''}\n`)),
+      FLUSH,
+      // a push of deletions alone sends no pack (gitprotocol-pack, "Pushing data to a server")
+      ...(updates.length ? [await packObjects(store, updates, haves)] : []),
+    ),
+  });
+  const report = readPktLines(answer).lines.map((l) => l.replace(/\n$/, ''));
+  const failure = report.find((l) => l.startsWith('ERR '));
+  if (failure) throw new Error(`git receive-pack: ${failure.slice(4)}`);
+  const unpack = report.find((l) => l.startsWith('unpack '))?.slice('unpack '.length);
+  if (unpack === undefined) throw new Error('git receive-pack: the server sent no report');
+  const out = new Map<string, string | null>(commands.map((c) => [c.name, unpack === 'ok' ? 'the server reported nothing for it' : `unpacker error: ${unpack}`]));
+  for (const l of report) {
+    if (l.startsWith('ok ')) out.set(l.slice(3), null);
+    else if (l.startsWith('ng ')) { const rest = l.slice(3); const sp = rest.indexOf(' '); out.set(sp === -1 ? rest : rest.slice(0, sp), sp === -1 ? 'refused' : rest.slice(sp + 1)); }
+  }
+  return out;
+}

package/src/git/smart-http.ts

@@ -68,6 +68,13 @@ async function closure(store: GitObjectStore, roots: string[], seen: Set<string>
 }
 async function reachable(store: GitObjectStore, roots: string[]): Promise<Set<string>> { const seen = new Set<string>(); await closure(store, roots, seen); return seen; }
 
+/** The pack of every object `wants` reach that the `haves` the store holds do not: what a push sends (a client's
+ *  send-pack, smart-http-client.ts). */
+export async function packObjects(store: GitObjectStore, wants: string[], haves: string[]): Promise<Uint8Array> {
+  const known: string[] = []; for (const h of haves) if (await store.has(h)) known.push(h);
+  return writePack(await closure(store, wants, await reachable(store, known)));
+}
+
 /**
  * A shallow request's commits (gitprotocol-pack, "Shallow requests"): every commit within `depth` of a want (a want is
  * depth 1), and the boundary, the commits whose parents the client will not have. The client's own shallow commits it