@volter/world-core 3.0.164 → 3.0.166

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.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/checkout.d.ts

@@ -0,0 +1,4 @@
+/** The checkout a directory is in: the nearest ancestor of the path as given that holds `.git` (a directory, or a
+ *  worktree's file), or undefined outside every checkout. It walks the spelling it is handed; a caller whose base may
+ *  be a symlink passes its physical path. What a checkout tracks, and what a failed Git query means, is each caller's. */
+export declare function checkoutOf(dir: string): string | undefined;

package/dist/src/checkout.js

@@ -0,0 +1,13 @@
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+/** The checkout a directory is in: the nearest ancestor of the path as given that holds `.git` (a directory, or a
+ *  worktree's file), or undefined outside every checkout. It walks the spelling it is handed; a caller whose base may
+ *  be a symlink passes its physical path. What a checkout tracks, and what a failed Git query means, is each caller's. */
+export function checkoutOf(dir) {
+    for (let d = resolve(dir);; d = dirname(d)) {
+        if (existsSync(join(d, '.git')))
+            return d;
+        if (dirname(d) === d)
+            return undefined;
+    }
+}

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?: {
@@ -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. */
@@ -903,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;
@@ -911,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 });
 }
@@ -1574,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`).
@@ -1038,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/executor.d.ts

@@ -132,8 +132,8 @@ export declare function validateRemoteOrigin(origin: string, opts?: {
 /** `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

package/dist/src/executor.js

@@ -224,6 +224,8 @@ function direct(origin, credential, auth, vendorHosts, now = () => new Date()) {
         let target;
         // the vendor's own URL, where a loopback root stands in for it: what a signature is made over
         let vendorUrl;
+        // the user a host that takes the token as HTTP Basic's password names it under (HostRule.basic)
+        let basicUser;
         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);
@@ -235,6 +237,7 @@ function direct(origin, credential, auth, vendorHosts, now = () => new Date()) {
             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)) {
@@ -258,6 +261,16 @@ function direct(origin, credential, auth, vendorHosts, now = () => new Date()) {
         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);

package/dist/src/git/index.d.ts

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

package/dist/src/git/index.js

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

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

@@ -0,0 +1,28 @@
+import { type GitObjectStore } from './objects.js';
+import { type Service } from './smart-http.js';
+/** 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 declare function lsRemote(transport: SmartHttpTransport, service: Service): Promise<RemoteRefs>;
+/** `POST git-upload-pack` with `done`: every object `wants` reach and `haves` do not, read into `store`. */
+export declare function fetchPack(transport: SmartHttpTransport, store: GitObjectStore, wants: string[], haves: string[]): Promise<void>;
+/** 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 declare function sendPack(transport: SmartHttpTransport, store: GitObjectStore, commands: PushCommand[], haves: string[], atomic?: boolean): Promise<Map<string, string | null>>;

package/dist/src/git/smart-http-client.js

@@ -0,0 +1,95 @@
+// 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 } from "./objects.js";
+import { readPack } from "./pack.js";
+import { FLUSH, ZERO_SHA, packObjects, pktLine, readPktLines } from "./smart-http.js";
+const DEC = new TextDecoder();
+const SHA = /^[0-9a-f]{40}$/;
+/** `GET info/refs?service=<service>`, read. */
+export async function lsRemote(transport, service) {
+    let { lines, rest } = readPktLines(await transport({ service }));
+    if (lines[0]?.startsWith('# service='))
+        ({ lines, rest } = readPktLines(rest));
+    const refs = new Map();
+    let head = null;
+    let caps = [];
+    for (const raw of lines) {
+        const [line, offered] = raw.replace(/\n$/, '').split('\0');
+        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, at) => 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, store, wants, haves) {
+    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);
+}
+/** `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, store, commands, haves, atomic = false) {
+    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(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/dist/src/git/smart-http.d.ts

@@ -16,6 +16,9 @@ export declare function readAllPktLines(bytes: Uint8Array): {
 export type Service = 'git-upload-pack' | 'git-receive-pack';
 /** `GET info/refs?service=<service>`: the ref advertisement, HEAD first as a symref. */
 export declare function advertisement(service: Service, refs: GitRefs): Uint8Array;
+/** 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 declare function packObjects(store: GitObjectStore, wants: string[], haves: string[]): Promise<Uint8Array>;
 /** `POST git-upload-pack`: wants and haves in, NAK and (once `done`) the pack out. A request with `deepen <n>` is shallow:
  *  its answer opens with the shallow-update section (`shallow <sha>` for each boundary commit, `unshallow <sha>` for a
  *  commit the client held shallow whose parents it now receives, then a flush), and its pack stops at the boundary. */