@lapxo/bound 0.1.0

package/dist/fold/signers.d.ts

@@ -0,0 +1,24 @@
+import type { Published, Signer, SignerVerdict } from '@lapxo/topos/wire';
+/** A lock line about the signers: the authority fold reads it. */
+export declare function isSignerLock(line: string): boolean;
+/** The authority view of a ledger: which signers the lock admits from its root, and what each line carries. */
+export declare function authorityFor(lines: readonly string[], root: Signer, admitted: readonly string[], published?: Published): {
+    readonly admitted: readonly Signer[];
+    readonly potential: readonly string[];
+    readonly of: (line: string) => SignerVerdict;
+};
+/** The key this lock admits for a class of writing: the fold is kept by whoever runs it, and the lock says who that is. */
+export declare function writerFor(standing: readonly string[], kind: string): string | undefined;
+export declare function publicKeyOf(root: string, keyId: string): string | undefined;
+export declare function releaseSigner(lines: readonly string[]): Signer;
+export declare function rootSigner(root: string): {
+    id: string;
+    keyClass: 'authorize';
+    publicKey: string;
+    coverage: string[];
+    depth: {
+        lo: number;
+        hi: number;
+    };
+    admittedBy: string[];
+};

package/dist/fold/signers.js

@@ -0,0 +1,58 @@
+import { existsSync, join } from "../host/io.js";
+import { authorityOf, isKeyClaim, parse, signersOf } from '@lapxo/topos/wire';
+import { verifiesFields } from "../land/sign.js";
+import { fieldOf, selfName } from "./claims.js";
+import { keyFor, lockStanding } from "./keys.js";
+import { storeRoot } from "../host/ports/store.js";
+import { storeOf } from "../land/ledger.js";
+import { observeText } from "../observe/files.js";
+/** A lock line about the signers: the authority fold reads it. */
+export function isSignerLock(line) {
+    const got = parse(line);
+    return got.kind === 'fact' && isKeyClaim(got.value.fields);
+}
+/** The authority view of a ledger: which signers the lock admits from its root, and what each line carries. */
+export function authorityFor(lines, root, admitted, published) {
+    const fields = lines
+        .map((line) => parse(line))
+        .flatMap((got) => (got.kind === 'fact' ? [got.value.fields] : []));
+    const lock = signersOf(fields, root, (f, key) => verifiesFields(f, key, admitted));
+    return {
+        admitted: lock.admitted,
+        potential: lock.potential,
+        of: (line) => {
+            const got = parse(line);
+            return got.kind === 'fact'
+                ? authorityOf(got.value.fields, lock.admitted, (f, key) => verifiesFields(f, key, admitted), published)
+                : { kind: 'grey', why: `not a claim line: ${got.why}` };
+        },
+    };
+}
+/** The key this lock admits for a class of writing: the fold is kept by whoever runs it, and the lock says who that is. */
+export function writerFor(standing, kind) {
+    for (const line of standing) {
+        const key = /^keys\/([^/]+)$/.exec(fieldOf(line, 'scope'))?.[1];
+        if (key && fieldOf(line, 'measure') === 'class' && fieldOf(line, 'value') === kind)
+            return key;
+    }
+    return undefined;
+}
+export function publicKeyOf(root, keyId) {
+    const at = [join(storeRoot(root), `${selfName()}.keys`), join(storeOf(root), `${selfName()}.keys`)].find((one) => existsSync(one));
+    const keys = at === undefined ? {} : JSON.parse(observeText(at) ?? '{}');
+    const anchored = keys[keyId]?.publicKey;
+    if (anchored !== undefined)
+        return anchored;
+    const said = lockStanding(storeOf(root))
+        .find((line) => fieldOf(line, 'scope') === `keys/${keyId}` && fieldOf(line, 'measure') === 'public-key' && fieldOf(line, 'value') !== 'withdraw');
+    return said === undefined ? undefined : fieldOf(said, 'value');
+}
+export function releaseSigner(lines) {
+    const said = (id, measure) => fieldOf(lines.find((line) => fieldOf(line, 'scope') === `keys/${id}` && fieldOf(line, 'measure') === measure && fieldOf(line, 'value') !== 'withdraw') ?? '', 'value') || undefined;
+    const id = writerFor(lines, 'authorize') ?? '';
+    return { id, keyClass: 'authorize', publicKey: said(id, 'public-key') ?? '', coverage: ['*'], depth: { lo: 1, hi: 16 }, admittedBy: [] };
+}
+export function rootSigner(root) {
+    const id = keyFor(storeOf(root), 'authorize');
+    return { id, keyClass: 'authorize', publicKey: publicKeyOf(root, id) ?? '', coverage: ['*'], depth: { lo: 1, hi: 16 }, admittedBy: [] };
+}

package/dist/fold/stranger.d.ts

@@ -0,0 +1,3 @@
+/** A clone that holds a lock and no ledger: receipts none, one place opened, the needs the lock names, each uses/ pin still open, and README.md to render. Nothing is folded and nothing is written. */
+export declare function emptyLedger(store: string): boolean;
+export declare function sayStranger(root: string): void;

package/dist/fold/stranger.js

@@ -0,0 +1,24 @@
+import { existsSync, join, readdirSync } from "../host/io.js";
+import { LOCK } from '@lapxo/topos/wire';
+import { fieldOf, isWire } from "./claims.js";
+import { observeText } from "../observe/files.js";
+/** A clone that holds a lock and no ledger: receipts none, one place opened, the needs the lock names, each uses/ pin still open, and README.md to render. Nothing is folded and nothing is written. */
+export function emptyLedger(store) {
+    const dir = join(store, 'ledger');
+    return !existsSync(dir) || readdirSync(dir).length === 0;
+}
+export function sayStranger(root) {
+    const lines = (observeText(join(root, LOCK)) ?? '').split('\n').filter(isWire);
+    const needs = [...new Set(lines.flatMap((line) => fieldOf(line, 'needs').split('|').filter(Boolean)))].sort();
+    const uses = lines.filter((line) => {
+        const scope = fieldOf(line, 'scope');
+        return scope.startsWith('uses/') && !scope.slice('uses/'.length).includes('/') && fieldOf(line, 'value') !== 'withdraw';
+    }).map((line) => fieldOf(line, 'scope'));
+    const shape = fieldOf(lines.find((line) => fieldOf(line, 'scope').startsWith('view/') && fieldOf(line, 'shape') !== '' && fieldOf(line, 'value') !== 'withdraw') ?? '', 'shape');
+    process.stdout.write('RECEIPTS 0 read · 1 opened\n');
+    process.stdout.write(`NEEDS    ${needs.join(' ')}\n`);
+    for (const scope of uses)
+        process.stdout.write(`OPEN     ${scope}/\n`);
+    if (shape)
+        process.stdout.write(`RENDER   ${shape}\n`);
+}

package/dist/fold/views.d.ts

@@ -0,0 +1,27 @@
+interface Asked {
+    readonly name: string;
+    readonly at: number;
+    readonly called?: boolean;
+}
+export interface View {
+    readonly name: string;
+    readonly regions: readonly Asked[];
+    readonly shape: string;
+}
+/**
+ * A view is a signed line `view/<name>` whose value lists regions in the order they are written, each at the resolution
+ * it asks for (`region@n`, the steps of each line it keeps, three when it asks for none, and the one the view is called
+ * at for `region@*`), and whose shape, when it has one, names the coordinate the view renders into. What renders a region is
+ * read where the fold is known, and a view asking one nothing renders is refused there, by name.
+ */
+export declare function viewsOf(standing: readonly string[]): ReadonlyMap<string, View>;
+/**
+ * A view the wire's views/world list names writes at a world that holds no view of that name of its own: the tree's line
+ * of the name, at the shape it names. A place's own view of a shape shadows the list at that shape: own over root, one
+ * writer. Two views naming the same shape in one place is a refuse at rank, before any render.
+ */
+export declare const defaulted: (standing: readonly string[], view: View, own: readonly string[], tree: ReadonlyMap<string, View>) => boolean;
+/** Shapes two standing views of one place both name: rank refuses before a render, one path, one writer. */
+export declare function sharedShapes(standing: readonly string[]): readonly string[];
+export declare function placesOf(standing: readonly string[], view: View): readonly string[];
+export {};

package/dist/fold/views.js

@@ -0,0 +1,66 @@
+import { fieldOf } from "./claims.js";
+import { wordOf, wordsOf } from "./wire.js";
+/**
+ * A view is a signed line `view/<name>` whose value lists regions in the order they are written, each at the resolution
+ * it asks for (`region@n`, the steps of each line it keeps, three when it asks for none, and the one the view is called
+ * at for `region@*`), and whose shape, when it has one, names the coordinate the view renders into. What renders a region is
+ * read where the fold is known, and a view asking one nothing renders is refused there, by name.
+ */
+export function viewsOf(standing) {
+    const held = wordsOf(standing, 'families');
+    const family = `${held.includes('view') || !held.length ? 'view' : wordOf(standing, 'families', 'view')}/`;
+    const views = new Map();
+    for (const line of standing) {
+        const scope = fieldOf(line, 'scope');
+        if (!scope.startsWith(family) || fieldOf(line, 'role') !== 'demands' || fieldOf(line, 'value') === 'withdraw')
+            continue;
+        const name = scope.slice(family.length);
+        if (views.has(name))
+            continue;
+        const regions = fieldOf(line, 'value').split('|').filter(Boolean)
+            .map((token) => ({ name: token.split('@')[0], at: token.includes('@') && Number.isFinite(Number(token.split('@')[1])) ? Number(token.split('@')[1]) : 3, ...(token.endsWith('@*') ? { called: true } : {}) }));
+        views.set(name, { name, regions, shape: fieldOf(line, 'shape') });
+    }
+    return views;
+}
+/**
+ * A view the wire's views/world list names writes at a world that holds no view of that name of its own: the tree's line
+ * of the name, at the shape it names. A place's own view of a shape shadows the list at that shape: own over root, one
+ * writer. Two views naming the same shape in one place is a refuse at rank, before any render.
+ */
+export const defaulted = (standing, view, own, tree) => {
+    const family = `${wordOf(standing, 'families', 'view')}/`;
+    const owns = (name) => own.some((line) => fieldOf(line, 'scope') === `${family}${name}` && fieldOf(line, 'value') !== 'withdraw');
+    const writes = (shape) => shape !== '' && own.some((line) => fieldOf(line, 'scope').startsWith(family) && fieldOf(line, 'shape') === shape && fieldOf(line, 'value') !== 'withdraw');
+    return !writes(view.shape) && wordsOf(standing, 'views/world').includes(view.name) && tree.get(view.name)?.shape === view.shape && !owns(view.name);
+};
+/** Shapes two standing views of one place both name: rank refuses before a render, one path, one writer. */
+export function sharedShapes(standing) {
+    const named = new Map();
+    for (const line of standing) {
+        const scope = fieldOf(line, 'scope');
+        if (!scope.startsWith('view/') || fieldOf(line, 'role') !== 'demands' || fieldOf(line, 'value') === 'withdraw')
+            continue;
+        const shape = fieldOf(line, 'shape');
+        if (!shape)
+            continue;
+        named.set(shape, [...(named.get(shape) ?? []), scope.slice('view/'.length)]);
+    }
+    return [...named].filter(([, names]) => new Set(names).size > 1).map(([shape, names]) => `${shape} · view/${[...new Set(names)].join(' · view/')}`);
+}
+;
+const placed = new WeakMap();
+export function placesOf(standing, view) {
+    const known = placed.get(standing) ?? new Map();
+    placed.set(standing, known);
+    const asked = known.get(`${view.name} ${view.shape}`);
+    if (asked !== undefined)
+        return asked;
+    const scope = `${wordOf(standing, 'families', 'view')}/${view.name}`;
+    const lines = standing.filter((one) => fieldOf(one, 'scope') === scope && fieldOf(one, 'value') !== 'withdraw');
+    const same = lines.filter((one) => fieldOf(one, 'value') === fieldOf(lines[0] ?? '', 'value') && fieldOf(one, 'shape') === view.shape);
+    const places = !view.shape ? [] : [...new Set(same.flatMap((one) => fieldOf(one, 'needs').split('|'))
+            .filter((need) => need === view.shape || need.endsWith(`/${view.shape}`)).map((need) => need.slice(0, need.length - view.shape.length)))];
+    known.set(`${view.name} ${view.shape}`, places);
+    return places;
+}

package/dist/fold/wire.d.ts

@@ -0,0 +1,19 @@
+import type { RoleClaim } from '@lapxo/topos/wire';
+export type CoordinateRole = 'source' | 'derived' | 'observed' | 'foreign';
+export declare const namesAt: (at: string, name: string) => boolean;
+export declare const roleAt: (at: string, claims: readonly RoleClaim[]) => CoordinateRole;
+/** The standing line that names a wire list, under `wire/`, else the older `audit/wire/` for one era. A word the wire names is read from the lock by the list it belongs to: the instrument asks for one and refuses if the lock no longer lists it, so an alphabet is never frozen here and a family that moves is a refusal, not a silence. */
+export declare const wireLine: (standing: readonly string[], list: string) => string | undefined;
+export declare function wordsOf(standing: readonly string[], list: string): readonly string[];
+/**
+ * A word asked in its eras, newest first, is read in the lock it is asked of: the first era that lock's own wire lists
+ * is the word there, so a place published under an older wire is read in the word it was written in, and none is a
+ * refusal. A list that names exactly one word is read as that word; a list that names none, or more than one, is a
+ * refusal. The older `audit/wire/` prefix is one era of `wire/`, not a fall-back to another lock.
+ */
+export declare function wordOf(standing: readonly string[], list: string, name: string | readonly string[]): string;
+export declare function theWord(standing: readonly string[], list: string): string;
+export declare const wordOn: (standing: readonly string[], list: string, fallback: readonly string[]) => string;
+/** A named word, read from the standing that lists it, else from the fallback lock. */
+export declare function wordFrom(standing: readonly string[], list: string, name: string | readonly string[], fallback: readonly string[]): string;
+export declare const said: (lines: readonly string[], scope: string) => readonly string[];

package/dist/fold/wire.js

@@ -0,0 +1,41 @@
+import * as topos from '@lapxo/topos/wire';
+import { fieldOf, selfName } from "./claims.js";
+const spoken = topos;
+export const namesAt = (spoken['namesAt'] ?? spoken['namesLeaf']);
+export const roleAt = (spoken['roleAt'] ?? spoken['leafRoleOf']);
+/** The standing line that names a wire list, under `wire/`, else the older `audit/wire/` for one era. A word the wire names is read from the lock by the list it belongs to: the instrument asks for one and refuses if the lock no longer lists it, so an alphabet is never frozen here and a family that moves is a refusal, not a silence. */
+export const wireLine = (standing, list) => standing.find((line) => fieldOf(line, 'scope') === `wire/${list}` && fieldOf(line, 'value') !== 'withdraw')
+    ?? standing.find((line) => fieldOf(line, 'scope') === `audit/wire/${list}` && fieldOf(line, 'value') !== 'withdraw');
+export function wordsOf(standing, list) {
+    const said = wireLine(standing, list);
+    return (said === undefined ? [] : fieldOf(said, 'value').split('|')).filter(Boolean);
+}
+/**
+ * A word asked in its eras, newest first, is read in the lock it is asked of: the first era that lock's own wire lists
+ * is the word there, so a place published under an older wire is read in the word it was written in, and none is a
+ * refusal. A list that names exactly one word is read as that word; a list that names none, or more than one, is a
+ * refusal. The older `audit/wire/` prefix is one era of `wire/`, not a fall-back to another lock.
+ */
+export function wordOf(standing, list, name) {
+    const held = wordsOf(standing, list);
+    const eras = typeof name === 'string' ? [name] : name;
+    const found = eras.find((one) => held.includes(one));
+    if (found !== undefined)
+        return found;
+    throw new Error(`${selfName()}: REFUSE·wire \`${eras.join('|')}\` is not one of \`wire/${list}\`: ${held.join('|') || 'the lock lists none'}`);
+}
+export function theWord(standing, list) {
+    const held = wordsOf(standing, list);
+    if (held.length !== 1) {
+        throw new Error(`${selfName()}: REFUSE·wire \`wire/${list}\` names ${held.length} words, not one: ${held.join('|') || 'the lock lists none'}`);
+    }
+    return wordOf(standing, list, held);
+}
+export const wordOn = (standing, list, fallback) => theWord(wordsOf(standing, list).length ? standing : fallback, list);
+/** A named word, read from the standing that lists it, else from the fallback lock. */
+export function wordFrom(standing, list, name, fallback) {
+    const eras = typeof name === 'string' ? [name] : name;
+    return wordOf(eras.some((one) => wordsOf(standing, list).includes(one)) ? standing : fallback, list, name);
+}
+export const said = (lines, scope) => lines
+    .filter((line) => fieldOf(line, 'scope') === scope && fieldOf(line, 'value') !== 'withdraw').flatMap((line) => fieldOf(line, 'value').split('|').filter(Boolean));

package/dist/fold/zoom.d.ts

@@ -0,0 +1,16 @@
+/**
+ * A line of the tree seen from inside a place: every path it names under the place is read from the place's root, and
+ * a path outside it is dropped, since the place alone cannot read it. The place's name drops out of the scope, the condition
+ * and the policy a line is held at, and a cone names the coordinates it covers the same way; the place itself is `./`. In a
+ * scope the name drops out of the step after the family, or after the one word that qualifies it (prose/en, hazard/<kind>,
+ * source/<measure>); a deeper step that spells it is inside a name, such as a package a module imports, and stays.
+ */
+export declare function zoomed(line: string, place: string): string;
+/** The lines of each place's own lock that still name the place: seen from inside a place, no scope carries its name. */
+export declare function namingTheirPlace(root: string): number;
+/**
+ * What a zoom rewrote that is not the place: over each place the lock publishes, every scope and condition of the tree
+ * and of the place's receipts that spells the place as a step, zoomed from inside it. Losing the place's step after the
+ * family, or after the one word qualifying it, is the zoom; any other rewrite took a value for the place.
+ */
+export declare function zoomedOutsideThePlace(root: string, standing: readonly string[]): number;

package/dist/fold/zoom.js

@@ -0,0 +1,80 @@
+import { join } from "../host/io.js";
+import { canonical, LOCK, parse, RECEIPTS } from '@lapxo/topos/wire';
+import { fieldOf, foldClaims, isWire } from "./claims.js";
+import { entriesIn, observeText } from "../observe/files.js";
+/**
+ * A line of the tree seen from inside a place: every path it names under the place is read from the place's root, and
+ * a path outside it is dropped, since the place alone cannot read it. The place's name drops out of the scope, the condition
+ * and the policy a line is held at, and a cone names the coordinates it covers the same way; the place itself is `./`. In a
+ * scope the name drops out of the step after the family, or after the one word that qualifies it (prose/en, hazard/<kind>,
+ * source/<measure>); a deeper step that spells it is inside a name, such as a package a module imports, and stays.
+ */
+export function zoomed(line, place) {
+    const got = parse(line);
+    if (got.kind !== 'fact')
+        return line;
+    const fields = { ...got.value.fields };
+    const under = `${place}/`;
+    const paths = (value) => value.split('|').filter(Boolean)
+        .flatMap((one) => (one === under ? ['./'] : one.startsWith(under) ? [one.slice(under.length)] : [])).join('|');
+    const scope = (value) => {
+        if (value === under)
+            return './';
+        if (value.startsWith(under))
+            return value.slice(under.length);
+        const steps = value.split('/');
+        const at = steps.findIndex((step, i) => step === place && (i === 1 || i === 2) && i < steps.length - 1);
+        return at < 0 ? value : [...steps.slice(0, at), ...steps.slice(at + 1)].join('/');
+    };
+    if (fields['needs'] !== undefined) {
+        const kept = paths(fields['needs']);
+        if (kept)
+            fields['needs'] = kept;
+        else
+            delete fields['needs'];
+    }
+    for (const name of ['scope', 'condition'])
+        if (fields[name])
+            fields[name] = scope(fields[name]);
+    const at = fields['at'] ?? '';
+    const colon = at.indexOf(':');
+    if (colon > 0 && at.startsWith(under, colon + 1))
+        fields['at'] = `${at.slice(0, colon + 1)}${at.slice(colon + 1 + under.length)}`;
+    if (fields['measure'] === 'cone' && fields['value'])
+        fields['value'] = paths(fields['value']);
+    return canonical(fields);
+}
+/** The lines of each place's own lock that still name the place: seen from inside a place, no scope carries its name. */
+export function namingTheirPlace(root) {
+    return entriesIn(root).filter((entry) => entry.dir && !entry.name.startsWith('.')).flatMap((entry) => {
+        const own = (observeText(join(root, entry.name, LOCK)) ?? '').split('\n').filter(isWire);
+        return foldClaims(own).standing.filter((line) => fieldOf(line, 'value') !== 'withdraw')
+            .map((line) => fieldOf(line, 'scope')).filter((scope) => scope.startsWith(`${entry.name}/`) || scope.includes(`/${entry.name}/`));
+    }).length;
+}
+/**
+ * What a zoom rewrote that is not the place: over each place the lock publishes, every scope and condition of the tree
+ * and of the place's receipts that spells the place as a step, zoomed from inside it. Losing the place's step after the
+ * family, or after the one word qualifying it, is the zoom; any other rewrite took a value for the place.
+ */
+export function zoomedOutsideThePlace(root, standing) {
+    const places = standing.filter((line) => /^publish\/[^/]+\/bootstrap$/.test(fieldOf(line, 'scope')) && fieldOf(line, 'value') !== 'withdraw')
+        .map((line) => fieldOf(line, 'scope').split('/')[1]);
+    const lost = (before, after, place) => {
+        if (after === before)
+            return false;
+        if (before === `${place}/`)
+            return after !== './';
+        if (before.startsWith(`${place}/`))
+            return after !== before.slice(place.length + 1);
+        const steps = before.split('/');
+        return ![1, 2].some((i) => steps[i] === place && i < steps.length - 1 && after === [...steps.slice(0, i), ...steps.slice(i + 1)].join('/'));
+    };
+    return places.reduce((count, place) => {
+        const text = observeText(join(root, place, RECEIPTS));
+        const receipts = text === undefined ? [] : text.split('\n').filter(isWire);
+        return count + [...standing, ...receipts].flatMap((line) => ['scope', 'condition']
+            .filter((field) => fieldOf(line, field).split('/').includes(place))
+            .filter((field) => lost(fieldOf(line, field), fieldOf(zoomed(line, place), field), place))).length;
+    }, 0);
+}

package/dist/host/adapters/keys/ed25519.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The act of signing: canonical bytes, a private key and the algorithm the wire names for this era in; a signature
+ * value out, whose form is the algebra's. The host runs the act and knows no name: which algorithms a signature may
+ * carry, this era's and the ones the lines before it were signed under, is told by whoever read the lock.
+ */
+export declare const signBytes: (bytes: string, privateKeyPem: string, algorithm: string) => string;
+export declare function verifyBytes(bytes: string, publicKeyPem: string, signature: string, admitted: readonly string[]): boolean;

package/dist/host/adapters/keys/ed25519.js

@@ -0,0 +1,30 @@
+import { createPrivateKey, createPublicKey, sign, verify } from 'node:crypto';
+import { formatSignature, parseSignature } from '@lapxo/topos/wire';
+/**
+ * The act of signing: canonical bytes, a private key and the algorithm the wire names for this era in; a signature
+ * value out, whose form is the algebra's. The host runs the act and knows no name: which algorithms a signature may
+ * carry, this era's and the ones the lines before it were signed under, is told by whoever read the lock.
+ */
+export const signBytes = (bytes, privateKeyPem, algorithm) => formatSignature(algorithm, sign(null, Buffer.from(bytes, 'utf8'), createPrivateKey(privateKeyPem)).toString('base64'));
+/** A public key as the lock carries it: base64 SPKI. A PEM is accepted where a tree still holds one. */
+function publicKeyOf(publicKey) {
+    return publicKey.startsWith('-----')
+        ? createPublicKey(publicKey)
+        : createPublicKey({ key: Buffer.from(publicKey, 'base64'), format: 'der', type: 'spki' });
+}
+export function verifyBytes(bytes, publicKeyPem, signature, admitted) {
+    const value = parseSignature(signature);
+    if (!value || !admitted.includes(value.algorithm))
+        return false;
+    const raw = Buffer.from(value.raw, 'base64');
+    if (raw.length === 0)
+        return false;
+    try {
+        return verify(null, Buffer.from(bytes, 'utf8'), publicKeyOf(publicKeyPem), raw);
+    }
+    catch (err) {
+        if (err instanceof Error)
+            return false;
+        throw err;
+    }
+}

package/dist/host/archive.d.ts

@@ -0,0 +1,11 @@
+export interface Member {
+    readonly name: string;
+    readonly bytes: Uint8Array;
+}
+/** POSIX archive coordinates; normalization cannot make two members share one destination. */
+export declare function archiveCoordinate(name: string): string;
+/** The gzip/POSIX tar adapter reads regular files, directories and PAX attributes, or rejects the whole archive. */
+export declare function members(archive: Uint8Array): readonly Member[];
+/** Existing links or files are never followed or overwritten by extraction. */
+export declare function archiveDestination(into: string, name: string): string;
+export declare function unpack(archive: Uint8Array, into: string): readonly string[];

package/dist/host/archive.js

@@ -0,0 +1,152 @@
+import { lstatSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { gunzipSync } from 'node:zlib';
+const BLOCK = 512; // POSIX tar record size.
+const refuse = (why) => { throw new Error(`REFUSE·archive ${why}`); };
+/** POSIX archive coordinates; normalization cannot make two members share one destination. */
+export function archiveCoordinate(name) {
+    if (!name || name.startsWith('/') || /^[A-Za-z]:/.test(name) || name.includes('\\') || name.includes('\0'))
+        refuse(`invalid coordinate ${JSON.stringify(name)}`);
+    const parts = name.replace(/\/+$/, '').split('/');
+    while (parts[0] === '.')
+        parts.shift();
+    if (!parts.length || parts.some((part) => !part || part === '.' || part === '..'))
+        refuse(`invalid coordinate ${JSON.stringify(name)}`);
+    return parts.join('/');
+}
+function pax(bytes) {
+    const fields = {};
+    for (let at = 0; at < bytes.length;) {
+        const space = bytes.indexOf(32, at);
+        if (space < 0)
+            refuse('malformed PAX record length');
+        const lengthText = new TextDecoder().decode(bytes.subarray(at, space));
+        if (!/^\d+$/.test(lengthText))
+            refuse('malformed PAX record length');
+        const length = Number(lengthText);
+        const end = at + length;
+        if (!Number.isSafeInteger(length) || length <= space - at + 1 || end > bytes.length || bytes[end - 1] !== 10)
+            refuse('truncated PAX record');
+        const record = new TextDecoder().decode(bytes.subarray(space + 1, end - 1));
+        const equals = record.indexOf('=');
+        if (equals < 1)
+            refuse('malformed PAX attribute');
+        const key = record.slice(0, equals);
+        if (key.startsWith('GNU.sparse') || key.startsWith('SCHILY.realsize'))
+            refuse('sparse PAX members are unsupported');
+        fields[key] = record.slice(equals + 1);
+        at = end;
+    }
+    return fields;
+}
+/** The gzip/POSIX tar adapter reads regular files, directories and PAX attributes, or rejects the whole archive. */
+export function members(archive) {
+    const bytes = gunzipSync(archive);
+    const text = (at, length) => bytes.subarray(at, at + length).toString('utf8').replace(/\0[\s\S]*$/, '');
+    const octal = (at, length) => {
+        const raw = text(at, length).trim();
+        if (!/^[0-7]+$/.test(raw))
+            refuse(`invalid octal field at ${at}`);
+        const n = Number.parseInt(raw, 8);
+        if (!Number.isSafeInteger(n) || n < 0)
+            refuse(`unrepresentable field at ${at}`);
+        return n;
+    };
+    const out = [];
+    const files = new Set();
+    const directories = new Set();
+    let global = {};
+    let local;
+    for (let at = 0;;) {
+        if (at + BLOCK > bytes.length)
+            refuse('missing complete end records');
+        const header = bytes.subarray(at, at + BLOCK);
+        if (header.every((byte) => byte === 0)) {
+            if (local !== undefined)
+                refuse('PAX attributes have no following member');
+            if (at + 2 * BLOCK > bytes.length || !bytes.subarray(at).every((byte) => byte === 0))
+                refuse('invalid end records or trailing data');
+            return out;
+        }
+        const checksum = header.reduce((sum, byte, i) => sum + (i >= 148 && i < 156 ? 32 : byte), 0);
+        if (octal(at + 148, 8) !== checksum)
+            refuse(`header checksum mismatch at ${at}`);
+        const magic = text(at + 257, 6);
+        if (magic && magic !== 'ustar' && magic !== 'ustar ')
+            refuse(`unsupported tar format ${magic}`);
+        const type = text(at + 156, 1);
+        const attrs = { ...global, ...local };
+        let size = octal(at + 124, 12);
+        if (type !== 'x' && type !== 'g' && attrs['size'] !== undefined) {
+            if (!/^\d+$/.test(attrs['size']))
+                refuse('invalid PAX size');
+            size = Number(attrs['size']);
+            if (!Number.isSafeInteger(size))
+                refuse('unrepresentable PAX size');
+        }
+        const next = at + BLOCK + Math.ceil(size / BLOCK) * BLOCK;
+        if (next > bytes.length)
+            refuse(`truncated member at ${at}`);
+        const body = bytes.subarray(at + BLOCK, at + BLOCK + size);
+        if (type === 'x' || type === 'g') {
+            const fields = pax(body);
+            if (type === 'g')
+                global = { ...global, ...fields };
+            else
+                local = { ...local, ...fields };
+        }
+        else {
+            const rawName = attrs['path'] ?? [magic ? text(at + 345, 155) : '', text(at, 100)].filter(Boolean).join('/');
+            local = undefined;
+            if (type === '5' && /^\.\/?$/.test(rawName) && size === 0) {
+                at = next;
+                continue;
+            }
+            const name = archiveCoordinate(rawName);
+            if (!['', '0', '5'].includes(type))
+                refuse(`unsupported member type ${type} at ${name}`);
+            const steps = name.split('/');
+            if (steps.slice(0, -1).some((_, i) => files.has(steps.slice(0, i + 1).join('/'))))
+                refuse(`file is an ancestor of ${name}`);
+            if (type === '5') {
+                if (size !== 0 || files.has(name))
+                    refuse(`invalid directory ${name}`);
+                directories.add(name);
+            }
+            else {
+                if (files.has(name) || directories.has(name))
+                    refuse(`duplicate or conflicting member ${name}`);
+                files.add(name);
+                steps.slice(0, -1).forEach((_, i) => directories.add(steps.slice(0, i + 1).join('/')));
+                out.push({ name, bytes: body });
+            }
+        }
+        at = next;
+    }
+}
+/** Existing links or files are never followed or overwritten by extraction. */
+export function archiveDestination(into, name) {
+    const root = resolve(into);
+    const parts = archiveCoordinate(name).split('/');
+    let at = root;
+    const base = lstatSync(at, { throwIfNoEntry: false });
+    if (base !== undefined && !base.isDirectory())
+        refuse(`destination is not a directory: ${root}`);
+    for (let i = 0; i < parts.length; i += 1) {
+        at = join(at, parts[i]);
+        const st = lstatSync(at, { throwIfNoEntry: false });
+        if (st !== undefined && (i === parts.length - 1 || !st.isDirectory()))
+            refuse(`destination already occupied: ${at}`);
+    }
+    return at;
+}
+export function unpack(archive, into) {
+    const files = members(archive);
+    const destinations = files.map((one) => archiveDestination(into, one.name));
+    for (const [i, one] of files.entries()) {
+        const at = destinations[i];
+        mkdirSync(dirname(at), { recursive: true });
+        writeFileSync(at, one.bytes, { flag: 'wx' });
+    }
+    return files.map((one) => one.name);
+}

package/dist/host/capsule-process.d.ts

@@ -0,0 +1,20 @@
+import type { SpawnSyncOptionsWithStringEncoding } from 'node:child_process';
+import type { Request, Response } from '@lapxo/topos/contract';
+/** Operational process failure, distinct from a valid contract refusal or abstention. */
+export declare class CapsuleProcessError extends Error {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly status: number | null;
+    readonly signal: NodeJS.Signals | null;
+    readonly cause: unknown;
+    constructor(reason: string, result: {
+        stdout?: string;
+        stderr?: string;
+        status: number | null;
+        signal: NodeJS.Signals | null;
+        error?: unknown;
+    });
+}
+export declare function validResponse(value: unknown, request: Request): value is Response;
+/** Last-line JSON is the wire framing. No partial batch, failed exit or synthetic missing response is accepted. */
+export declare function executeCapsule(command: string, args: readonly string[], requests: readonly Request[], limits?: Pick<SpawnSyncOptionsWithStringEncoding, 'timeout' | 'maxBuffer'>): readonly Response[];