@volter/world-core 3.0.38 → 3.0.39

package/dist/src/executor.js

@@ -1,4 +1,27 @@
 import { RateBudget } from "./rateBudget.js";
+async function oauth1SignedHeader(credential, method, target, headers, body) {
+    const field = (name) => {
+        const value = credential[name];
+        if (typeof value !== 'string' || !value)
+            throw new Error(`remote execute: oauth1-hmac-sha1 needs sealed ${name}`);
+        return value;
+    };
+    const consumerKey = field('consumerKey'), consumerSecret = field('consumerSecret');
+    const token = field('token'), tokenSecret = field('tokenSecret');
+    const encode = (value) => encodeURIComponent(value).replace(/[!\x27()*]/g, c => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+    const protocol = [
+        ['oauth_consumer_key', consumerKey], ['oauth_token', token], ['oauth_signature_method', 'HMAC-SHA1'],
+        ['oauth_timestamp', String(Math.floor(Date.now() / 1000))], ['oauth_nonce', crypto.randomUUID()], ['oauth_version', '1.0'],
+    ];
+    const form = typeof body === 'string' && /^application\/x-www-form-urlencoded/i.test(headers.get('content-type') ?? '') ? [...new URLSearchParams(body)] : [];
+    const pairs = [...protocol, ...target.searchParams, ...form].filter(([name]) => name !== 'oauth_signature').map(([name, value]) => [encode(name), encode(value)]);
+    pairs.sort(([a, av], [b, bv]) => a < b ? -1 : a > b ? 1 : av < bv ? -1 : av > bv ? 1 : 0);
+    const base = `${method.toUpperCase()}&${encode(`${target.protocol}//${target.host.toLowerCase()}${target.pathname}`)}&${encode(pairs.map(([name, value]) => `${name}=${value}`).join('&'))}`;
+    const key = await crypto.subtle.importKey('raw', new TextEncoder().encode(`${encode(consumerSecret)}&${encode(tokenSecret)}`), { name: 'HMAC', hash: 'SHA-1' }, false, ['sign']);
+    const bytes = new Uint8Array(await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(base)));
+    const signature = btoa(Array.from(bytes, byte => String.fromCharCode(byte)).join(''));
+    return `OAuth ${[...protocol, ['oauth_signature', signature]].map(([name, value]) => `${encode(name)}="${encode(value)}"`).join(', ')}`;
+}
 const MAX_ORIGIN_LENGTH = 2048;
 function isLoopbackHost(hostname) {
     return hostname === '127.0.0.1' || hostname === 'localhost' || hostname === '[::1]' || hostname === '::1';
@@ -138,7 +161,13 @@ export function buildRemoteExecute(origin, credential, auth, vendorHosts, option
         const execute = (request) => (byLane.get(request.lane ?? '') ?? headers)(request);
         return options.vendor === undefined ? execute : budgeted(options.vendor, execute, options.custody?.key ?? JSON.stringify(credential.headers));
     }
-    const execute = auth?.in === 'exchange' ? exchangeExecute(origin, credential, auth, vendorHosts, options.custody) : direct(origin, credential, auth, vendorHosts);
+    if (auth?.in === 'choice') {
+        const picked = auth.choices.find(c => typeof credential[c.credential] === 'string' && credential[c.credential] !== '');
+        if (!picked)
+            throw new Error('remote execute: no credential matches the declared strategy choices');
+        return buildRemoteExecute(origin, credential, picked.strategy, vendorHosts, options);
+    }
+    const execute = auth?.in === 'exchange' ? exchangeExecute(origin, credential, auth, vendorHosts, options.custody) : direct(origin, credential, auth, vendorHosts, options.now);
     return options.vendor === undefined ? execute : budgeted(options.vendor, execute, options.custody?.key ?? JSON.stringify(credential.headers));
 }
 /** Every live call charged to the vendor's rate budget (rateBudget.ts, D8): a call the budget refuses is never made;
@@ -155,7 +184,7 @@ function budgeted(vendor, execute, token) {
     };
 }
 /** The call made as the root's credential is applied by the strategy (header replacement when none). */
-function direct(origin, credential, auth, vendorHosts) {
+function direct(origin, credential, auth, vendorHosts, now = () => new Date()) {
     return async ({ method, path, headers, body, responseType, presigned, issued }) => {
         // A PRESIGNED UPLOAD URL the vendor returned: its own signature is its authorization, so the
         // sealed credential never goes with it, whatever host it names. A host other than the root's
@@ -193,15 +222,25 @@ function direct(origin, credential, auth, vendorHosts) {
         // the origin into USERINFO and ships the credential to evil.com. A path is a path:
         // it starts with '/', and the parse must land on the validated origin, asserted.
         let target;
+        // the vendor's own URL, where a loopback root stands in for it: what a signature is made over
+        let vendorUrl;
         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);
             if (target.username || target.password)
                 throw new Error('remote execute: a vendor URL carries no userinfo');
             validateRemoteOrigin(target.origin);
-            const declared = vendorHosts.some((r) => 'host' in r && !r.exclude && r.host === target.hostname && (r.pathPattern === undefined || new RegExp(r.pathPattern).test(target.pathname)));
+            const named = (r) => ('host' in r ? r.host === target.hostname : 'suffix' in r ? target.hostname.endsWith(r.suffix) : new RegExp(r.hostPattern).test(target.hostname))
+                && (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`);
+            // 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)) {
+                vendorUrl = target;
+                target = new URL(origin.href.replace(/\/+$/, '') + target.pathname + target.search);
+            }
         }
         else {
             if (!path.startsWith('/'))
@@ -219,6 +258,11 @@ function direct(origin, credential, auth, vendorHosts) {
         else
             for (const [name, value] of Object.entries(credential.headers))
                 outbound.set(name, value);
+        // 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);
+        }
         // ── THE STRATEGIES BEYOND HEADER REPLACEMENT ──────────────────────────────────────────────
         // Applied AFTER the anchoring check above, so nothing here can move the request off the
         // validated origin: `searchParams.set` only ever touches the query, and a header is a header.
@@ -226,35 +270,52 @@ function direct(origin, credential, auth, vendorHosts) {
         // FAIL CLOSED. A strategy with no secret must never send a request that merely LOOKS
         // authenticated — that silence is the whole defect this exists to remove. The refusals name the
         // strategy and the parameter, never the secret.
-        if (auth !== undefined && issued === undefined) {
-            const secret = credential.secret;
-            if (typeof secret !== 'string' || secret === '') {
-                throw new Error(`remote execute: the ${auth.in} credential strategy needs \`secret\` on the sealed credential, and it is absent`);
+        // an issued credential is the authorization: nothing of the sealed one signs the request
+        if (issued === undefined) {
+            if (auth?.in === 'signature' && auth.algorithm === 'oauth1-hmac-sha1') {
+                outbound.set('authorization', await oauth1SignedHeader(credential, method, target, outbound, body));
             }
-            if (auth.in === 'query') {
-                // `set`, not `append`: it REPLACES whatever placeholder the pack put in its own path,
-                // exactly as `outbound.set` replaces a placeholder authorization header.
-                target.searchParams.set(auth.name, secret);
-            }
-            else if (auth.algorithm === 'aws-sigv4') {
-                const keyId = credential.keyId;
-                if (typeof keyId !== 'string' || keyId === '') {
-                    throw new Error('remote execute: the aws-sigv4 credential strategy needs `keyId` on the sealed credential, and it is absent');
+            else if (auth !== undefined) {
+                const secret = credential.secret;
+                if (typeof secret !== 'string' || secret === '') {
+                    throw new Error(`remote execute: the ${auth.in} credential strategy needs \`secret\` on the sealed credential, and it is absent`);
+                }
+                if (auth.in === 'query') {
+                    // `set`, not `append`: it REPLACES whatever placeholder the pack put in its own path,
+                    // exactly as `outbound.set` replaces a placeholder authorization header.
+                    target.searchParams.set(auth.name, secret);
+                }
+                else if (auth.in === 'path') {
+                    // the key's place in the path, filled after the origin is validated; a secret that could end the segment or
+                    // the path (a slash, a query, a fragment, an escape) is refused, so the request cannot leave the validated root
+                    if (/[/?#%\\]/.test(secret))
+                        throw new Error('remote execute: the path credential strategy refuses a secret that is not one path segment');
+                    const place = new RegExp(auth.pattern, 'd').exec(target.pathname)?.indices?.[1];
+                    if (!place)
+                        throw new Error(`remote execute: the path credential strategy's pattern does not name the key's place in ${target.pathname.slice(0, 64)}`);
+                    target.pathname = target.pathname.slice(0, place[0]) + secret + target.pathname.slice(place[1]);
+                }
+                else if (auth.algorithm === 'aws-sigv4') {
+                    const keyId = credential.keyId;
+                    if (typeof keyId !== 'string' || keyId === '') {
+                        throw new Error('remote execute: the aws-sigv4 credential strategy needs `keyId` on the sealed credential, and it is absent');
+                    }
+                    // the HOST goes with it: an AWS endpoint names its own region, and only the pack knows how
+                    const signedUrl = vendorUrl ?? target;
+                    const { region, service } = typeof auth.scope === 'function' ? auth.scope({ method, path, host: signedUrl.host, headers: Object.fromEntries(outbound.entries()), ...(body === undefined ? {} : { body }) }) : auth.scope;
+                    const signed = await awsSigV4Headers({ method, url: signedUrl, ...(body === undefined ? {} : { body }), keyId, secret, region, service, headers: outbound, at: now() });
+                    for (const [name, value] of Object.entries(signed))
+                        outbound.set(name, value);
+                }
+                else {
+                    // `null` is the vendor's own exemption, declared by the pack — not an error, and not a
+                    // reason to send an unsigned header.
+                    if (body instanceof Uint8Array)
+                        throw new Error('remote execute: this signature canonicalizer accepts text bodies only');
+                    const payload = auth.canonical({ method, path, ...(body === undefined ? {} : { body }) });
+                    if (payload !== null)
+                        outbound.set(auth.header, await hmacSha256(secret, payload, auth.encoding));
                 }
-                // the HOST goes with it: an AWS endpoint names its own region, and only the pack knows how
-                const { region, service } = typeof auth.scope === 'function' ? auth.scope({ method, path, host: target.host, headers: Object.fromEntries(outbound.entries()), ...(body === undefined ? {} : { body }) }) : auth.scope;
-                const signed = await awsSigV4Headers({ method, url: target, ...(body === undefined ? {} : { body }), keyId, secret, region, service, headers: outbound, at: new Date() });
-                for (const [name, value] of Object.entries(signed))
-                    outbound.set(name, value);
-            }
-            else {
-                // `null` is the vendor's own exemption, declared by the pack — not an error, and not a
-                // reason to send an unsigned header.
-                if (body instanceof Uint8Array)
-                    throw new Error('remote execute: this signature canonicalizer accepts text bodies only');
-                const payload = auth.canonical({ method, path, ...(body === undefined ? {} : { body }) });
-                if (payload !== null)
-                    outbound.set(auth.header, await hmacSha256(secret, payload, auth.encoding));
             }
         }
         const response = await fetch(target, {

package/dist/src/file-response.js

@@ -32,7 +32,7 @@ export function bytesResponse(request, bytes, contentType, cacheControl = 'publi
     const range = /^bytes=(\d*)-(\d*)$/.exec((request.headers.get('range') ?? '').trim());
     let start = 0;
     let end = total - 1;
-    const valid = range !== null && (range[1] !== '' || range[2] !== '') && !(range[1] !== '' && range[2] !== '' && Number(range[1]) > Number(range[2]));
+    const valid = range !== null && (range[1] !== '' || range[2] !== '') && !(range[1] !== '' && range[2] !== '' && BigInt(range[1]) > BigInt(range[2]));
     if (valid) {
         if (range[1] === '') {
             start = Math.max(0, total - Number(range[2]));

package/dist/src/form.d.ts

@@ -0,0 +1,8 @@
+/** A field set as the object's own, whatever its name (`__proto__`, `constructor` and `prototype` are data a caller
+ *  may name: Stripe's metadata keys are the caller's), never through what the object inherits. */
+export declare function ownField(node: Record<string, unknown> | unknown[], key: string, value: unknown): void;
+/** A form body's bracket notation (`a[b][0][c]=v`, `expand[]=x`) as nested objects and arrays. A form carries only
+ *  text: a field the operation's spec types as a number or a boolean (`scalars`, by bracket path, written by
+ *  world-tooling's formScalarsOf) is read as one when its text is that literal; every other field stays the text sent
+ *  (`metadata[order]=007`, `name=2024`). */
+export declare function parseBracketForm(text: string, scalars?: Readonly<Record<string, string | undefined>>): Record<string, unknown>;

package/dist/src/form.js

@@ -0,0 +1,76 @@
+import { exactInteger } from "./exact-json.js";
+// Side-effect-free URL-encoded form reading, shared by requests and published examples.
+/** A field set as the object's own, whatever its name (`__proto__`, `constructor` and `prototype` are data a caller
+ *  may name: Stripe's metadata keys are the caller's), never through what the object inherits. */
+export function ownField(node, key, value) {
+    Object.defineProperty(node, key, { value, writable: true, enumerable: true, configurable: true });
+}
+/** A field the object holds as its own, never one it inherits (`constructor` is every object's). */
+const ownValue = (node, key) => (Object.hasOwn(node, key) ? node[key] : undefined);
+/** A form body's bracket notation (`a[b][0][c]=v`, `expand[]=x`) as nested objects and arrays. A form carries only
+ *  text: a field the operation's spec types as a number or a boolean (`scalars`, by bracket path, written by
+ *  world-tooling's formScalarsOf) is read as one when its text is that literal; every other field stays the text sent
+ *  (`metadata[order]=007`, `name=2024`). */
+export function parseBracketForm(text, scalars) {
+    const out = {};
+    for (const [rawKey, raw] of new URLSearchParams(text)) {
+        const parts = rawKey.replace(/\]/g, '').split('[');
+        const kind = scalars && scalarAt(scalars, parts);
+        const value = kind === 'boolean' ? (raw === 'true' ? true : raw === 'false' ? false : raw)
+            : kind === 'integer' ? (/^-?\d+$/.test(raw) ? exactInteger(raw) : raw)
+                : kind === 'number' ? (/^-?\d+$/.test(raw) ? exactInteger(raw) : /^-?\d+\.\d+$/.test(raw) ? Number(raw) : raw)
+                    : raw;
+        // every field is the node's own, read and written as such: a key naming an object's machinery (`__proto__[x]`,
+        // `constructor[prototype][x]`) is a field of that name, never a walk into what every object inherits
+        let node = out;
+        for (const [i, key] of parts.entries()) {
+            // an array holds its items by index (`a[]`, `a[0]`): a named key under one (`a[]=1&a[length]=-1`) has nowhere to
+            // go, as a key under text has none (`a=1&a[b]=2`): the first shape stands
+            if (Array.isArray(node) && key !== '' && !/^\d+$/.test(key))
+                break;
+            if (i === parts.length - 1) {
+                if (key === '') {
+                    if (Array.isArray(node))
+                        node.push(value);
+                }
+                else {
+                    const held = ownValue(node, key);
+                    if (held === undefined)
+                        ownField(node, key, value);
+                    else if (Array.isArray(held))
+                        held.push(value);
+                    else
+                        ownField(node, key, [held, value]);
+                }
+                break;
+            }
+            const next = parts[i + 1];
+            if (key === '')
+                break;
+            let child = ownValue(node, key);
+            if (child === undefined) {
+                child = next === '' || /^\d+$/.test(next) ? [] : {};
+                ownField(node, key, child);
+            }
+            if (child === null || typeof child !== 'object')
+                break;
+            node = child;
+        }
+    }
+    return out;
+}
+/** The type `scalars` gives a form key's parts: a segment is a property name, `[]` an array's item (an index or empty),
+ *  `*` a map's key. */
+function scalarAt(scalars, parts) {
+    let paths = [''];
+    for (const [i, part] of parts.entries()) {
+        const segs = part === '' || /^\d+$/.test(part) ? ['[]', '*'] : [part, '*'];
+        paths = paths.flatMap((p) => segs.map((seg) => (i === 0 ? seg : `${p}.${seg}`)));
+        if (paths.length > 64)
+            paths = paths.filter((p) => Object.keys(scalars).some((k) => k === p || k.startsWith(`${p}.`)));
+    }
+    for (const p of paths)
+        if (scalars[p])
+            return scalars[p];
+    return undefined;
+}

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

@@ -0,0 +1,16 @@
+import { type GitObjectStore } from './objects.js';
+/** A complete unified diff between two trees or commits, with null as the empty preimage. */
+export declare function diffText(store: GitObjectStore, from: string | null, to: string): Promise<string>;
+/** One commit as an email patch; series metadata numbers the subject for a comparison's commits. */
+export declare function formatPatch(store: GitObjectStore, sha: string, series?: {
+    number: number;
+    total: number;
+}): Promise<string | null>;
+/** Submodule paths and URLs declared by a .gitmodules file (git configuration syntax). */
+export declare function parseSubmodules(text: string): Array<{
+    name: string;
+    path: string;
+    url: string;
+}>;
+/** A repository-relative symbolic-link target; targets escaping the repository have no local path. */
+export declare function symlinkPath(path: string, target: string): string | undefined;

package/dist/src/git/format.js

@@ -0,0 +1,110 @@
+// Git text representations over the object store (architecture, The engine slot).
+import { decodeCommit } from "./objects.js";
+import { diffTrees, lineDiff, unifiedPatch } from "./history.js";
+const decoder = new TextDecoder();
+const binary = (bytes) => bytes.slice(0, 8000).includes(0);
+const pathName = (path) => /[\s"\\\x00-\x1f]/.test(path) ? JSON.stringify(path) : path;
+async function bytesOf(store, sha, mode) {
+    if (!sha)
+        return new Uint8Array();
+    if (mode === '160000')
+        return new TextEncoder().encode(`Subproject commit ${sha}\n`);
+    return (await store.read(sha))?.payload ?? new Uint8Array();
+}
+async function fileDiff(store, change) {
+    const oldBytes = await bytesOf(store, change.oldSha, change.oldMode);
+    const newBytes = await bytesOf(store, change.newSha, change.newMode);
+    const left = pathName(`a/${change.path}`), right = pathName(`b/${change.path}`);
+    let text = `diff --git ${left} ${right}\n`;
+    if (!change.oldSha)
+        text += `new file mode ${change.newMode}\n`;
+    else if (!change.newSha)
+        text += `deleted file mode ${change.oldMode}\n`;
+    else if (change.oldMode !== change.newMode)
+        text += `old mode ${change.oldMode}\nnew mode ${change.newMode}\n`;
+    if (change.oldSha === change.newSha)
+        return { text, additions: 0, deletions: 0 };
+    text += `index ${(change.oldSha ?? '0000000').slice(0, 7)}..${(change.newSha ?? '0000000').slice(0, 7)}${change.oldSha && change.newSha && change.oldMode === change.newMode ? ` ${change.newMode}` : ''}\n`;
+    if (binary(oldBytes) || binary(newBytes))
+        return { text: `${text}Binary files ${change.oldSha ? left : '/dev/null'} and ${change.newSha ? right : '/dev/null'} differ\n`, additions: 0, deletions: 0 };
+    const oldText = decoder.decode(oldBytes), newText = decoder.decode(newBytes);
+    const edits = lineDiff(oldText, newText);
+    text += `--- ${change.oldSha ? left : '/dev/null'}\n+++ ${change.newSha ? right : '/dev/null'}\n${unifiedPatch(oldText, newText)}\n`;
+    return { text, additions: edits.filter((edit) => edit.kind === '+').length, deletions: edits.filter((edit) => edit.kind === '-').length };
+}
+/** A complete unified diff between two trees or commits, with null as the empty preimage. */
+export async function diffText(store, from, to) {
+    const changes = await diffTrees(store, from, to);
+    return (await Promise.all(changes.map((change) => fileDiff(store, change)))).map((file) => file.text).join('');
+}
+function mailDate(author) {
+    const sign = author.tz.startsWith('-') ? -1 : 1;
+    const offset = sign * (Number(author.tz.slice(1, 3)) * 60 + Number(author.tz.slice(3, 5)));
+    const date = new Date((author.time + offset * 60) * 1000);
+    const weekdays = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+    const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${weekdays[date.getUTCDay()]}, ${date.getUTCDate()} ${months[date.getUTCMonth()]} ${date.getUTCFullYear()} ${pad(date.getUTCHours())}:${pad(date.getUTCMinutes())}:${pad(date.getUTCSeconds())} ${author.tz}`;
+}
+/** One commit as an email patch; series metadata numbers the subject for a comparison's commits. */
+export async function formatPatch(store, sha, series) {
+    const object = await store.read(sha);
+    if (!object || object.type !== 'commit')
+        return null;
+    const commit = decodeCommit(object.payload);
+    const changes = await diffTrees(store, commit.parents[0] ?? null, sha);
+    const files = await Promise.all(changes.map((change) => fileDiff(store, change)));
+    const width = Math.max(0, ...changes.map((change) => change.path.length));
+    const stats = changes.map((change, i) => {
+        const file = files[i];
+        return ` ${change.path.padEnd(width)} | ${file.additions + file.deletions} ${'+'.repeat(file.additions)}${'-'.repeat(file.deletions)}\n`;
+    }).join('');
+    const additions = files.reduce((sum, file) => sum + file.additions, 0), deletions = files.reduce((sum, file) => sum + file.deletions, 0);
+    const summary = `${changes.length} file${changes.length === 1 ? '' : 's'} changed${additions ? `, ${additions} insertion${additions === 1 ? '' : 's'}(+)` : ''}${deletions ? `, ${deletions} deletion${deletions === 1 ? '' : 's'}(-)` : ''}`;
+    const [title = '', ...rest] = commit.message.trimEnd().split('\n');
+    const body = rest.join('\n').trim();
+    const numbered = series && series.total > 1 ? ` ${series.number}/${series.total}` : '';
+    return `From ${sha} Mon Sep 17 00:00:00 2001\nFrom: ${commit.author.name} <${commit.author.email}>\nDate: ${mailDate(commit.author)}\nSubject: [PATCH${numbered}] ${title}\n\n${body ? `${body}\n\n` : ''}---\n${stats} ${summary}\n\n${files.map((file) => file.text).join('')}`;
+}
+/** Submodule paths and URLs declared by a .gitmodules file (git configuration syntax). */
+export function parseSubmodules(text) {
+    const modules = [];
+    let current;
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        const section = /^\[submodule\s+"((?:[^"\\]|\\.)*)"\]\s*(?:[#;].*)?$/.exec(line);
+        if (section) {
+            current = { name: section[1].replace(/\\(.)/g, '$1'), path: '', url: '' };
+            modules.push(current);
+            continue;
+        }
+        if (line.startsWith('[')) {
+            current = undefined;
+            continue;
+        }
+        const field = /^(path|url)\s*=\s*(.*)$/i.exec(line);
+        if (!current || !field)
+            continue;
+        const value = field[2].replace(/\s+[#;].*$/, '').trim();
+        current[field[1].toLowerCase()] = value.startsWith('"') && value.endsWith('"') ? value.slice(1, -1).replace(/\\(.)/g, '$1') : value;
+    }
+    return modules.filter((module) => module.path && module.url);
+}
+/** A repository-relative symbolic-link target; targets escaping the repository have no local path. */
+export function symlinkPath(path, target) {
+    if (target.startsWith('/'))
+        return undefined;
+    const segments = path.split('/').slice(0, -1);
+    for (const part of target.split('/')) {
+        if (!part || part === '.')
+            continue;
+        if (part === '..') {
+            if (!segments.length)
+                return undefined;
+            segments.pop();
+        }
+        else
+            segments.push(part);
+    }
+    return segments.join('/');
+}

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

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

package/dist/src/git/index.js

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

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

@@ -1,7 +1,7 @@
 export declare const LFS_TYPE = "application/vnd.git-lfs+json";
 export type LfsObject = {
     oid: string;
-    size: number;
+    size: number | string;
 };
 /** Where a pack keeps its objects: by oid. */
 export type LfsStore = {

package/dist/src/git/lfs.js

@@ -1,3 +1,4 @@
+import { exactInteger } from "../exact-json.js";
 // GIT LFS (architecture, "The tree contract": Git LFS is the git library's too): the batch API git-lfs speaks
 // (https://github.com/git-lfs/git-lfs/blob/main/docs/api/batch.md, the basic transfer), a pointer file read
 // (https://github.com/git-lfs/git-lfs/blob/main/docs/spec.md), and an upload accepted only when its bytes hash to the
@@ -15,7 +16,7 @@ export function parseLfsPointer(file) {
         return null;
     const oid = /^oid sha256:([0-9a-f]{64})$/m.exec(text)?.[1];
     const size = /^size (\d+)$/m.exec(text)?.[1];
-    return oid && size ? { oid, size: Number(size) } : null;
+    return oid && size ? { oid, size: exactInteger(size) } : null;
 }
 /** A pointer file's text for an object. */
 export const lfsPointer = (o) => `version https://git-lfs.github.com/spec/v1\noid sha256:${o.oid}\nsize ${o.size}\n`;
@@ -39,9 +40,9 @@ export async function lfsBatch(body, opts) {
     const operation = b.operation;
     const objects = [];
     for (const raw of b.objects) {
-        const o = { oid: String(raw?.oid ?? ''), size: Number(raw?.size) };
+        const o = { oid: String(raw?.oid ?? ''), size: /^-?\d+$/.test(String(raw?.size)) ? exactInteger(String(raw?.size)) : Number(raw?.size) };
         // source: https://github.com/git-lfs/git-lfs/blob/main/docs/api/batch.md "The object is invalid (for example, an invalid oid or size)."
-        if (!OID.test(o.oid) || !Number.isSafeInteger(o.size) || o.size < 0) {
+        if (!OID.test(o.oid) || !Number.isSafeInteger(o.size) || Number(o.size) < 0) {
             objects.push({ ...o, error: { code: 422, message: 'Invalid object' } });
             continue;
         }

package/dist/src/graphql-wire.d.ts

@@ -2,6 +2,12 @@
 export type GraphqlResolver<C = unknown> = (source: Record<string, unknown>, args: Record<string, unknown>, ctx: C) => unknown;
 /** What a pack's `semantics/graphql.ts` exports as `graphql`. */
 export type GraphqlPart<C = unknown> = {
+    /** The root operations derived from the SDL, for dispatch ownership and gap reporting. */
+    operations?: ReadonlyArray<{
+        id: string;
+        kind: 'query' | 'mutation';
+        field: string;
+    }>;
     /** resolvers by `Type.field` (`Query.repository`, `PullRequest.state`) */
     resolvers: Record<string, GraphqlResolver<C>>;
     /** per type, a GraphQL field name → the object's field that holds it (`nameWithOwner` → `full_name`) */

package/dist/src/graphql-wire.js

@@ -45,7 +45,10 @@ function connection(items, args) {
 export function graphqlEndpoint(options) {
     let schema;
     const { resolvers, aliases, stored } = options.part;
-    const modeled = (type, field) => field === '__typename' || `${type}.${field}` in resolvers || !!aliases?.[type]?.[field] || !!stored?.[type]?.includes(field) || !!stored?.[type]?.includes(snake(field));
+    // introspection (`__typename`, `__type`, `__schema` and the `__Type`/`__Field`/… meta types) is the vendor's schema
+    // describing itself, answered by graphql-js from the SDL: modeled as the schema is (gh asks `__type(name:"PullRequest")`
+    // before it merges)
+    const modeled = (type, field) => field.startsWith('__') || type.startsWith('__') || `${type}.${field}` in resolvers || !!aliases?.[type]?.[field] || !!stored?.[type]?.includes(field) || !!stored?.[type]?.includes(snake(field));
     return async (request) => {
         const g = await graphqlLib();
         schema ??= g.buildSchema(options.sdl, { assumeValidSDL: true });
@@ -80,10 +83,10 @@ export function graphqlEndpoint(options) {
         const ctx = await options.context(request);
         const result = await g.execute({
             schema, document, variableValues: payload.variables ?? {}, ...(payload.operationName ? { operationName: payload.operationName } : {}), contextValue: ctx,
-            fieldResolver: (source, args, context, info) => {
+            fieldResolver: async (source, args, context, info) => {
                 const own = resolvers[`${info.parentType.name}.${info.fieldName}`];
                 const obj = (source ?? {});
-                let value = own ? own(obj, args, context) : (obj[aliases?.[info.parentType.name]?.[info.fieldName] ?? info.fieldName] ?? obj[snake(info.fieldName)] ?? null);
+                let value = own ? await own(obj, args, context) : (obj[aliases?.[info.parentType.name]?.[info.fieldName] ?? info.fieldName] ?? obj[snake(info.fieldName)] ?? null);
                 const named = g.getNamedType(info.returnType);
                 if (Array.isArray(value) && g.isObjectType(named) && named.name.endsWith('Connection'))
                     value = connection(value, args);

package/dist/src/grpc-wire.js

@@ -1,3 +1,4 @@
+import { parseExactJson } from "./exact-json.js";
 // THE gRPC WIRE (architecture, "Other wires": gRPC): unary gRPC calls over the kernel's HTTP/2 server (./h2.ts), each
 // request's one length-prefixed message decoded by the proto unit's schema (./protobuf.ts) and handed to the pack's
 // handler for its operation, whose JSON answer is encoded back with the status trailers
@@ -144,7 +145,7 @@ export function grpcOverFetch(fetch) {
         const text = await res.text();
         let body;
         try {
-            body = text ? JSON.parse(text) : {};
+            body = text ? parseExactJson(text) : {};
         }
         catch {
             body = undefined;

package/dist/src/head.d.ts

@@ -15,6 +15,7 @@ export type PushOutcome = {
     also?: Array<{
         actionId: string;
         externalId: string;
+        data?: Record<string, unknown>;
     }>;
 };
 /** What a perform is handed beside the executor: a resolver from a local id to the vendor's (an

package/dist/src/head.js

@@ -363,6 +363,15 @@ async function performNow(opts) {
             report.skipped.push(...group.map((a) => a.id));
             continue;
         }
+        // a write of a unit the pack sends nowhere (`vendorBacked.none` beside vendor-backed lanes) is the World's alone
+        const unsent = adapters.unsent?.(group[0].input);
+        if (unsent) {
+            const at = opts.at ?? worldNow();
+            for (const action of group)
+                settle(action, at, { status: 'landed', reason: unsent });
+            report.worldOnly.push(...group.map((a) => a.id));
+            continue;
+        }
         if (named(group[0]).some((v) => refusedIds.has(v))) {
             const at = opts.at ?? worldNow();
             for (const action of group) {
@@ -396,12 +405,14 @@ async function performNow(opts) {
             // the vendor's answer, when the adapter returned one as fields, is what the primary entry's landed copy holds
             const answered = outcome.data !== null && typeof outcome.data === 'object' && !Array.isArray(outcome.data) ? outcome.data : {};
             const primary = resolved.find((a) => a.id === outcome.actionId) ?? resolved[0];
-            const also = new Map((outcome.also ?? []).map((a) => [a.actionId, a.externalId]));
+            const also = new Map((outcome.also ?? []).map((a) => [a.actionId, a]));
             for (const action of resolved) {
-                const externalId = action === primary ? outcome.externalId : also.get(action.id);
-                settle(action, at, { status: 'deployed', ...(action === primary && outcome.url ? { url: outcome.url } : {}) }, action === primary ? { ...action.fields, ...answered } : action.fields ?? {}, externalId || undefined);
+                const answeredId = action === primary ? outcome.externalId : also.get(action.id)?.externalId;
+                const externalId = answeredId || aliases.get(`${action.subject.type}:${action.subject.id}`);
+                settle(action, at, { status: 'deployed', ...(action === primary && outcome.url ? { url: outcome.url } : {}) }, { ...action.fields, ...(action === primary ? answered : also.get(action.id)?.data ?? {}) }, externalId || undefined);
+                const data = action === primary ? outcome.data : also.get(action.id)?.data;
                 report.pushed += 1;
-                report.deployed.push({ actionId: action.id, at, ...(externalId ? { externalId } : {}), ...(action === primary && outcome.data !== undefined ? { data: outcome.data } : {}) });
+                report.deployed.push({ actionId: action.id, at, ...(externalId ? { externalId } : {}), ...(data !== undefined ? { data } : {}) });
             }
         }
         catch (error) {

package/dist/src/held-reads.d.ts

@@ -0,0 +1,6 @@
+/** Tell every read held in this World that a subject of `storedType` was written. */
+export declare function heldReadsWrite(service: string, root: string | undefined, storedType: string): void;
+/** Wait until a write of one of `storedTypes` lands in this World (true), or `ms` pass or `signal` aborts (false). */
+export declare function awaitWrite(service: string, root: string | undefined, storedTypes: ReadonlyArray<string>, ms: number, signal?: AbortSignal): Promise<boolean>;
+/** Hold a read until its condition holds, within the caller's timeout. The kernel owns elapsed time. */
+export declare function awaitCondition(service: string, root: string | undefined, storedTypes: ReadonlyArray<string>, ms: number, pollMs: number, condition: () => Promise<boolean>, signal?: AbortSignal): Promise<boolean>;

package/dist/src/held-reads.js

@@ -0,0 +1,60 @@
+// A read held until the World writes (architecture, "Other wires": a read held until the World writes): HTTP long
+// polling, as Telegram's getUpdates is, where a client asks again at once on an empty answer. A handler that finds
+// nothing to answer awaits `ctx.awaitWrite(types, ms)`: it settles true when a write of one of the stored types lands in
+// the same World (the derived core's one write path tells it, as it tells the open sockets), false when the time runs
+// out or the client hangs up. The wait is the connection's, never World state: the handler reads the tree again and
+// answers what it holds. Nothing here runs at module scope beyond the empty registry.
+const waiting = new Map();
+const keyOf = (service, root) => `${service}\0${root ?? ''}`;
+/** Tell every read held in this World that a subject of `storedType` was written. */
+export function heldReadsWrite(service, root, storedType) {
+    const held = waiting.get(keyOf(service, root));
+    if (!held?.size)
+        return;
+    for (const w of [...held])
+        if (w.types.has(storedType))
+            w.settle(true);
+}
+/** Wait until a write of one of `storedTypes` lands in this World (true), or `ms` pass or `signal` aborts (false). */
+export function awaitWrite(service, root, storedTypes, ms, signal) {
+    if (!(ms > 0) || signal?.aborted)
+        return Promise.resolve(false);
+    const key = keyOf(service, root);
+    return new Promise((resolve) => {
+        let held = waiting.get(key);
+        if (!held) {
+            held = new Set();
+            waiting.set(key, held);
+        }
+        const set = held;
+        const waiter = {
+            types: new Set(storedTypes),
+            settle: (wrote) => {
+                clearTimeout(timer);
+                signal?.removeEventListener('abort', onAbort);
+                set.delete(waiter);
+                if (!set.size)
+                    waiting.delete(key);
+                resolve(wrote);
+            },
+        };
+        const onAbort = () => waiter.settle(false);
+        const timer = setTimeout(() => waiter.settle(false), ms);
+        signal?.addEventListener('abort', onAbort, { once: true });
+        set.add(waiter);
+    });
+}
+/** Hold a read until its condition holds, within the caller's timeout. The kernel owns elapsed time. */
+export async function awaitCondition(service, root, storedTypes, ms, pollMs, condition, signal) {
+    if (!(pollMs > 0))
+        throw new Error('a held condition requires a positive observation cadence');
+    const deadline = Date.now() + Math.max(0, ms);
+    for (;;) {
+        if (await condition())
+            return true;
+        const remaining = deadline - Date.now();
+        if (remaining <= 0 || signal?.aborted)
+            return false;
+        await awaitWrite(service, root, storedTypes, Math.min(remaining, pollMs), signal);
+    }
+}