@volter/world-core 2.0.0

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

@@ -0,0 +1,223 @@
+// SMART HTTP (gitprotocol-http, protocol v0): what `git clone|fetch|push` speak to a server. The
+// twin answers the advertisement (`info/refs?service=`), upload-pack (wants, haves, done → NAK
+// and a pack of the closure the client lacks) and receive-pack (ref commands, a pack, a
+// report-status) with nothing but the object store, the refs and a push policy. Protocol v2 is
+// not advertised; a client that asks for it falls back to v0 on this answer, as git specifies.
+import { decodeCommit, decodeTag, decodeTree } from "./objects.js";
+import { readPack, writePack } from "./pack.js";
+const ENC = new TextEncoder();
+const DEC = new TextDecoder();
+export const ZERO_SHA = '0'.repeat(40);
+export const FLUSH = new Uint8Array([0x30, 0x30, 0x30, 0x30]);
+export function pktLine(s) {
+    const body = typeof s === 'string' ? ENC.encode(s) : s;
+    const len = (body.length + 4).toString(16).padStart(4, '0');
+    const out = new Uint8Array(body.length + 4);
+    out.set(ENC.encode(len), 0);
+    out.set(body, 4);
+    return out;
+}
+/** Pkt-lines up to and including the first flush; `rest` is what follows (a pack, on push). */
+export function readPktLines(bytes) {
+    const lines = [];
+    let at = 0;
+    while (at + 4 <= bytes.length) {
+        const len = parseInt(DEC.decode(bytes.subarray(at, at + 4)), 16);
+        if (Number.isNaN(len))
+            return { lines, rest: bytes.subarray(at) };
+        if (len === 0)
+            return { lines, rest: bytes.subarray(at + 4) };
+        if (len < 4) {
+            at += 4;
+            continue;
+        } // v2 delimiter/response-end packets: no payload
+        lines.push(DEC.decode(bytes.subarray(at + 4, at + len)));
+        at += len;
+    }
+    return { lines, rest: bytes.subarray(at) };
+}
+/** Every pkt-line in the body across all flushes (stateless clients batch haves between flushes); `rest` follows the first flush. */
+export function readAllPktLines(bytes) {
+    const first = readPktLines(bytes);
+    const lines = [...first.lines];
+    let cur = first.rest;
+    while (cur.length >= 4 && /^[0-9a-f]{4}$/.test(DEC.decode(cur.subarray(0, 4))) && !cur.subarray(0, 4).every((b, i) => b === 'PACK'.charCodeAt(i))) {
+        const n = readPktLines(cur);
+        lines.push(...n.lines);
+        if (n.rest.length === cur.length)
+            break;
+        cur = n.rest;
+    }
+    return { lines, rest: first.rest };
+}
+const SHA = /^[0-9a-f]{40}$/;
+function cat(...parts) { const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0)); let o = 0; for (const p of parts) {
+    out.set(p, o);
+    o += p.length;
+} return out; }
+const CAPS = { 'git-upload-pack': 'ofs-delta no-progress agent=volter-twin', 'git-receive-pack': 'report-status delete-refs ofs-delta agent=volter-twin' };
+/** `GET info/refs?service=<service>`: the ref advertisement, HEAD first as a symref. */
+export function advertisement(service, refs) {
+    const all = refs.list();
+    const head = refs.head();
+    const headSha = refs.get(head);
+    const caps = `${CAPS[service]} symref=HEAD:${head}`;
+    const lines = [pktLine(`# service=${service}\n`), FLUSH];
+    if (headSha)
+        lines.push(pktLine(`${headSha} HEAD\0${caps}\n`));
+    const rest = all;
+    if (!headSha && rest.length === 0)
+        lines.push(pktLine(`${ZERO_SHA} capabilities^{}\0${caps}\n`));
+    let first = headSha === null;
+    for (const r of rest) {
+        lines.push(pktLine(first ? `${r.sha} ${r.name}\0${caps}\n` : `${r.sha} ${r.name}\n`));
+        first = false;
+    }
+    lines.push(FLUSH);
+    return cat(...lines);
+}
+/** Every object reachable from `roots`, stopping at `seen`. */
+async function closure(store, roots, seen) {
+    const out = [];
+    const stack = [...roots];
+    while (stack.length) {
+        const sha = stack.pop();
+        if (seen.has(sha))
+            continue;
+        seen.add(sha);
+        const obj = await store.read(sha);
+        if (!obj)
+            continue;
+        out.push({ ...obj, sha });
+        if (obj.type === 'commit') {
+            const c = decodeCommit(obj.payload);
+            stack.push(c.tree, ...c.parents);
+        }
+        else if (obj.type === 'tree') {
+            for (const e of decodeTree(obj.payload))
+                if (e.mode !== '160000')
+                    stack.push(e.sha);
+        }
+        else if (obj.type === 'tag')
+            stack.push(decodeTag(obj.payload).object);
+    }
+    return out;
+}
+async function reachable(store, roots) { const seen = new Set(); await closure(store, roots, seen); return seen; }
+/** `POST git-upload-pack`: wants and haves in, NAK and (once `done`) the pack out. */
+export async function uploadPack(body, store) {
+    const { lines } = readAllPktLines(body);
+    const wants = lines.filter((l) => l.startsWith('want ')).map((l) => l.slice(5, 45)).filter((s) => SHA.test(s));
+    const haves = lines.filter((l) => l.startsWith('have ')).map((l) => l.slice(5, 45)).filter((s) => SHA.test(s));
+    const done = lines.some((l) => l.trim() === 'done');
+    const known = [];
+    for (const h of haves)
+        if (await store.has(h))
+            known.push(h);
+    for (const w of wants)
+        if (!(await store.has(w)))
+            return pktLine(`ERR upload-pack: not our ref ${w}\n`);
+    if (!done)
+        return pktLine('NAK\n');
+    const seen = await reachable(store, known);
+    const objects = await closure(store, wants, seen);
+    return cat(pktLine('NAK\n'), await writePack(objects));
+}
+/** Bounded ancestry walk: is `ancestor` reachable from `sha` through parents? */
+export async function isAncestor(store, ancestor, sha, limit = 5000) {
+    const seen = new Set();
+    const stack = [sha];
+    while (stack.length && seen.size < limit) {
+        const s = stack.pop();
+        if (s === ancestor)
+            return true;
+        if (seen.has(s))
+            continue;
+        seen.add(s);
+        const o = await store.read(s);
+        if (o?.type === 'commit')
+            stack.push(...decodeCommit(o.payload).parents);
+    }
+    return false;
+}
+/** `POST git-receive-pack`: commands and a pack in, refs updated under `policy`, report-status out. */
+export async function receivePack(body, store, refs, policy = () => null) {
+    const { lines, rest } = readPktLines(body);
+    const commands = lines.map((l) => l.split('\0')[0].trim()).filter(Boolean).map((l) => { const [o, n, name] = l.split(' '); return { old: o, new: n, name: name, fastForward: true }; }).filter((c) => SHA.test(c.old) && SHA.test(c.new) && /^refs\/[^\s]+$/.test(c.name));
+    const report = [];
+    let unpack = 'ok';
+    if (rest.length >= 12) {
+        try {
+            await readPack(rest, store);
+        }
+        catch (e) {
+            unpack = e.message;
+        }
+    }
+    report.push(pktLine(`unpack ${unpack}\n`));
+    const applied = [];
+    const existing = refs.list().map((r) => r.name);
+    const verdicts = [];
+    for (const cmd of commands) {
+        const current = refs.get(cmd.name) ?? ZERO_SHA;
+        let reason = unpack === 'ok' ? null : 'unpacker error';
+        if (!reason && current !== cmd.old)
+            reason = 'fetch first';
+        if (!reason && current === ZERO_SHA && existing.some((n) => n.startsWith(`${cmd.name}/`) || cmd.name.startsWith(`${n}/`)))
+            reason = 'ref name conflict';
+        if (!reason && cmd.new !== ZERO_SHA && !(await store.has(cmd.new)))
+            reason = 'missing necessary objects';
+        if (!reason && cmd.old !== ZERO_SHA && cmd.new !== ZERO_SHA)
+            cmd.fastForward = await isAncestor(store, cmd.old, cmd.new);
+        if (!reason)
+            reason = await policy(cmd);
+        verdicts.push({ cmd, reason });
+    }
+    // Apply under the refs lock, re-reading each old value: a racing push that won in between is
+    // told `fetch first` rather than silently overwritten.
+    refs.withLock(() => {
+        for (const v of verdicts) {
+            if (!v.reason && (refs.get(v.cmd.name) ?? ZERO_SHA) !== v.cmd.old)
+                v.reason = 'fetch first';
+            if (v.reason) {
+                report.push(pktLine(`ng ${v.cmd.name} ${v.reason}\n`));
+                continue;
+            }
+            if (v.cmd.new === ZERO_SHA)
+                refs.delete(v.cmd.name);
+            else
+                refs.set(v.cmd.name, v.cmd.new);
+            applied.push(v.cmd);
+            report.push(pktLine(`ok ${v.cmd.name}\n`));
+        }
+    });
+    report.push(FLUSH);
+    return { response: cat(...report), applied };
+}
+/** Route one request under a repo: returns null when the path is not a smart-HTTP endpoint. */
+export async function serveSmartHttp(req, repo, tailPath) {
+    const url = new URL(req.url);
+    if (req.method === 'GET' && tailPath === 'info/refs') {
+        const service = url.searchParams.get('service');
+        if (service !== 'git-upload-pack' && service !== 'git-receive-pack')
+            return new Response('smart HTTP only', { status: 403 });
+        return new Response(advertisement(service, repo.refs), { headers: { 'content-type': `application/x-${service}-advertisement`, 'cache-control': 'no-cache' } });
+    }
+    if (req.method === 'POST' && (tailPath === 'git-upload-pack' || tailPath === 'git-receive-pack')) {
+        return serveSmartHttpPost(new Uint8Array(await req.arrayBuffer()), req.headers.get('content-encoding') ?? '', repo, tailPath);
+    }
+    return null;
+}
+/** The POST half of `serveSmartHttp` for a caller that already holds the body: a push pack is
+ *  the size of the repository, so re-wrapping it in a Request only to read it back is a full copy. */
+export async function serveSmartHttpPost(body, contentEncoding, repo, tailPath) {
+    if (contentEncoding.includes('gzip'))
+        body = new Uint8Array(await new Response(new Response(body).body.pipeThrough(new DecompressionStream('gzip'))).arrayBuffer());
+    const headers = { 'content-type': `application/x-${tailPath}-result`, 'cache-control': 'no-cache' };
+    if (tailPath === 'git-upload-pack')
+        return new Response((await uploadPack(body, repo.store)), { headers });
+    const { response, applied } = await receivePack(body, repo.store, repo.refs, repo.policy);
+    if (applied.length && repo.onPush)
+        await repo.onPush(applied);
+    return new Response(response, { headers });
+}

package/dist/src/hash.d.ts

@@ -0,0 +1,38 @@
+import type { WorldServiceEvent } from './types.js';
+export declare const DELTA_TYPE_SUFFIX = ".delta";
+export type SubjectFields = Record<string, unknown>;
+/**
+ * Maps a world event to the subject fields it observes, or null when the
+ * event says nothing about remote subject state (comments, egress records, …).
+ * Extractors are provider-specific; the shadow engine is not.
+ */
+export type SubjectFieldExtractor = (event: WorldServiceEvent) => SubjectFields | null;
+export type FieldChange = {
+    before: unknown;
+    after: unknown;
+};
+/** Deterministic JSON: object keys sorted, `undefined` entries dropped, arrays in order.
+ *  The one canonicalizer in this package — `hashFieldValue` (action-id content hashing) and
+ *  `changesetContentHash` (approval binds to exact bytes) must agree on what "same content"
+ *  means, so they share this function rather than each rolling their own. */
+export declare function canonicalJson(value: unknown): string;
+export declare function hashFieldValue(value: unknown): string;
+export declare function subjectKey(subject: {
+    type: string;
+    id: string;
+}): string;
+/** Field-level diff of freshly observed subject fields against a shadow of them. */
+export type SubjectShadow = {
+    subject: {
+        type: string;
+        id: string;
+    };
+    fields: SubjectFields;
+    fieldHashes: Record<string, string>;
+    latestEventId: string;
+    updatedAt: string;
+};
+export declare function diffSubjectFields(shadow: SubjectShadow | undefined, observed: SubjectFields): Record<string, FieldChange>;
+export declare function isDeltaEvent(event: WorldServiceEvent): boolean;
+/** THE canonical delta reader: a v1 delta row's `changed.<field>.after` values. */
+export declare function deltaAfterFields(event: WorldServiceEvent): SubjectFields;

package/dist/src/hash.js

@@ -0,0 +1,48 @@
+// HASHING AND THE DELTA READER — the one canonicalizer in this package, the content hash every
+// id and every changeset hash is built on, and the reader of a v1 delta row's `after` values.
+// (What else shadow.ts held — refs, bases, observed deltas as a row kind — left with v1.)
+import { createHash } from 'node:crypto';
+export const DELTA_TYPE_SUFFIX = '.delta';
+/** Deterministic JSON: object keys sorted, `undefined` entries dropped, arrays in order.
+ *  The one canonicalizer in this package — `hashFieldValue` (action-id content hashing) and
+ *  `changesetContentHash` (approval binds to exact bytes) must agree on what "same content"
+ *  means, so they share this function rather than each rolling their own. */
+export function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    if (value && typeof value === 'object') {
+        const entries = Object.entries(value)
+            .filter(([, item]) => item !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`);
+        return `{${entries.join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}
+export function hashFieldValue(value) {
+    return createHash('sha256').update(canonicalJson(value)).digest('hex').slice(0, 16);
+}
+export function subjectKey(subject) {
+    return `${subject.type}:${subject.id}`;
+}
+export function diffSubjectFields(shadow, observed) {
+    const changed = {};
+    for (const [field, after] of Object.entries(observed)) {
+        if (after === undefined)
+            continue;
+        const beforeHash = shadow?.fieldHashes[field];
+        if (beforeHash !== undefined && beforeHash === hashFieldValue(after))
+            continue;
+        changed[field] = { before: shadow?.fields[field], after };
+    }
+    return changed;
+}
+export function isDeltaEvent(event) { return typeof event.type === 'string' && event.type.endsWith(DELTA_TYPE_SUFFIX); }
+/** THE canonical delta reader: a v1 delta row's `changed.<field>.after` values. */
+export function deltaAfterFields(event) {
+    const changed = event.data.changed ?? {};
+    const fields = {};
+    for (const [field, change] of Object.entries(changed))
+        fields[field] = change.after;
+    return fields;
+}

package/dist/src/head.d.ts

@@ -0,0 +1,140 @@
+import { type TwinAction } from './actions.js';
+import { type CredentialPayload } from './credential.js';
+import { type CredentialCustody } from './executor.js';
+import type { RemoteExecute } from './remote-execute.js';
+import { type Check, type DeployPolicy, type RootConfig, type StateSystemAdapters } from './state-system.js';
+/** What a perform answers: the id the vendor minted (the local id when it kept ours), its URL, and
+ *  the vendor's answer as fields for the landed copy. */
+export type PushOutcome = {
+    externalId: string;
+    url?: string;
+    data?: Record<string, unknown>;
+};
+/** What a perform is handed beside the executor: a resolver from a local id to the vendor's (an
+ *  entry authored against `twin-1` crosses against `REAL-42` once that subject's landing adopted it). */
+/** `credential`: the sealed credential's keyed fingerprint (credential.ts — an HMAC under the user's key,
+ *  never the secret and no offline oracle for it), so a pack keys its budget ledger per real credential:
+ *  every World and branch performing with one vendor key then shares that key's one allowance. */
+export type PerformContext = {
+    resolve: (type: string, localId: string) => string;
+    service?: string;
+    root?: string;
+    credential?: string;
+};
+export type PerformAction = (execute: RemoteExecute, action: TwinAction, ctx: PerformContext) => Promise<PushOutcome>;
+export declare function performContext(service: string, root?: string, credential?: string): PerformContext;
+/** The user's key-encryption key: `$XDG_CONFIG_HOME/volter/kek` (created on first use). */
+export declare function userKekPath(): string;
+export declare function userKek(): string;
+export declare function setSealingKeySource(source: (() => string) | null): void;
+export declare function sealingKey(): string;
+/** A root as a world materializes it: the config plus the path of the sealed credential. */
+export type BoundRoot = RootConfig & {
+    credential: string;
+};
+/** Open the credential a root names, under the user's key. */
+export declare function openRootCredential(root: BoundRoot, vendor?: string): Promise<CredentialPayload>;
+/** Seal a credential the vendor rotated (an `exchange` with `rotate`) where the root's was, under the same key and
+ *  slot. It is the same credential: its placedAt and fingerprint stay (a pack's budget keys its ledger by the
+ *  fingerprint, and a new one per grant would start the ledger over), and rotatedAt says when. */
+export declare function resealRootCredential(root: BoundRoot, payload: CredentialPayload, vendor?: string): Promise<void>;
+/** The root's custody for an exchange that rotates: the credential as sealed now, and the seal of a rotated one. */
+export declare function rootCustody(root: BoundRoot, vendor?: string): CredentialCustody;
+/** The vendor a root belongs to: its credential is sealed under the vendor's name. */
+export declare function vendorOf(root: BoundRoot): string;
+/** The world a root belongs to: the credential sits at `<world>/.volter/credentials/<vendor>.json`. */
+export declare function worldRootOf(root: BoundRoot): string;
+/** The checks a world runs before any entry is performed: the shipped no-secrets check, then every
+ *  file under `.volter/checks/` exporting `{ name, run }`. */
+export declare function loadChecks(worldRoot: string): Promise<Check[]>;
+/** How a check file becomes a Check. Locally the file is imported; a hosted World's host supplies a
+ *  loader that runs the check in an isolate of its own, with no network and nothing of the World's. */
+export type CheckLoader = (path: string, name: string) => Promise<Check>;
+export declare function setCheckLoader(loader: CheckLoader | null): void;
+/** One check file through the host's loader: what placing a check validates with. */
+export declare function loadCheck(path: string, name: string): Promise<Check>;
+export type Head = {
+    kind: 'simulated';
+} | {
+    kind: 'real';
+    deploy: DeployPolicy;
+    root: BoundRoot;
+};
+/** The root a state service under `root` is bound to — its own root.json, else a sibling state's
+ *  (slack records under `chat`; the root was written under `slack`). */
+export declare function boundRoot(service: string, root?: string): BoundRoot | null;
+/** What this twin's head does with a write. */
+export declare function headOf(service: string, root?: string): Head;
+/** A check refused the write: the entry is in the log as refused; the pack answers in the vendor's error shape. */
+export declare class RefusedWriteError extends Error {
+    readonly check: string;
+    readonly reason: string;
+    readonly actionId: string;
+    constructor(check: string, reason: string, actionId: string);
+}
+/** The head could not be bound for a write that needed it (no credential sealed, no adapter registered,
+ *  no root): a server-side fault, answered as one. */
+export declare class HeadError extends Error {
+    constructor(message: string);
+}
+/** The vendor refused or failed the write: the entry is in the log as failed, with the vendor's words. */
+export declare class VendorWriteError extends Error {
+    readonly actionId: string;
+    constructor(message: string, actionId: string);
+}
+export type DeployReport = {
+    /** entries performed by this call */
+    pushed: number;
+    deployed: Array<{
+        actionId: string;
+        externalId?: string;
+        at: string; /** what the vendor answered, as the adapter returned it */
+        data?: unknown;
+    }>;
+    /** the first refusal; nothing after it was attempted */
+    refused?: {
+        actionId: string;
+        check: string;
+        reason: string;
+    };
+    /** the first failure, with the vendor's words; nothing after it was attempted */
+    failed?: {
+        actionId: string;
+        error: string;
+    };
+    /** entries after the refusal or failure, not attempted */
+    skipped: string[];
+    /** entries whose landed copy already said `deployed` — not performed again */
+    replayed: string[];
+};
+/** The branch entries a root twin still has to perform: `set` rows, not reverted, whose landed copy
+ *  is absent or says `failed`/`skipped` (a `deployed` or `refused` copy settles the entry). */
+export declare function deployableEntries(service: string, root?: string): TwinAction[];
+/**
+ * PERFORM this twin's deployable entries against its root, in order, checks in front of every one,
+ * stopping at the first refusal or failure. Each outcome lands as the entry's copy with its receipt
+ * on the parent log. `actionIds` narrows to a changeset's (or one write's) entries.
+ */
+export declare function performEntries(opts: {
+    service: string;
+    root?: string;
+    actionIds?: string[];
+    at?: string;
+    checks?: Check[];
+    adapters?: StateSystemAdapters;
+    execute?: RemoteExecute;
+}): Promise<DeployReport>;
+/**
+ * The write path's second half (serve.ts): a write just appended to a twin whose head is real and
+ * `auto` is performed now. Returns the vendor's id when it minted one, so the answer carries it.
+ * Raises `RefusedWriteError` / `VendorWriteError` for the pack to answer in the vendor's shape.
+ */
+export declare function performAtHead(service: string, action: Pick<TwinAction, 'id'>, root?: string): Promise<{
+    performed: boolean;
+    externalId?: string;
+    data?: unknown;
+}>;
+/** Wrap a pack's fetch: a `RefusedWriteError` or `VendorWriteError` the head raised becomes the
+ *  vendor's own error body (the pack's `shape`), so an app under live use sees what the vendor
+ *  would have said. Anything else propagates. */
+export declare function answerVendorErrors(fetch: (request: Request) => Promise<Response>, shape: (error: RefusedWriteError | VendorWriteError) => Response): (request: Request) => Promise<Response>;