@lapxo/head 0.1.0 → 0.1.3

package/dist/src/ports/bound.js

@@ -4,6 +4,7 @@ import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { parse } from '@lapxo/topos/wire';
 import { spawned } from "./process.js";
+import { cooled, kept, warmed } from "./warm.js";
 const binOf = (name) => {
     try {
         const manifest = createRequire(import.meta.url).resolve(join(name, 'package.json'));
@@ -15,24 +16,38 @@ const binOf = (name) => {
     }
 };
 export const limits = { wait: 0, most: 0 };
-/** bound run as a process in a folder, beside head and never blocking it, within the wait and the bytes head's lock gives it and stopped when the asker cancels. */
-export const run = async (name, cwd, args, env = {}, signal) => ((bin) => (bin === undefined ? undefined
-    : spawned(process.execPath, [bin, ...args], { cwd, env: { ...process.env, ...env } }, { wait: limits.wait, most: limits.most || Number.MAX_SAFE_INTEGER, ...(signal ? { signal } : {}) })))(binOf(name));
+/** bound run as a process in a folder, beside head and never blocking it, within the wait and the bytes head's lock gives it and stopped when the asker cancels: one started ahead when head holds one, else one started now. */
+export const run = async (name, cwd, args, env = {}, signal) => ((bin, at, bounds) => (bin === undefined ? undefined
+    : (warmed(bin, args, at, bounds) ?? spawned(process.execPath, [bin, ...args], at, bounds)).then(apart)))(binOf(name), { cwd, env: { ...process.env, ...env } }, { wait: limits.wait, most: limits.most || Number.MAX_SAFE_INTEGER, ...(signal ? { signal } : {}) });
+/** The record bound prints after a refusal's diagnostic, read apart from it: what bound printed is kept whole, the record beside it, and why bound refused is the diagnostic's last line, never the record. */
+const recordOf = (line) => { try {
+    return ((got) => (got?.profile === words.refusal ? got : undefined))(JSON.parse(line));
+}
+catch {
+    return undefined;
+} };
+const isRecord = (line) => line.startsWith('{') && recordOf(line) !== undefined;
+const apart = (printed) => ((record) => (record === undefined ? printed : { ...printed, refusal: recordOf(record) }))([...printed.err].reverse().find(isRecord));
+const why = (printed) => printed?.err.filter((line) => !isRecord(line)).at(-1);
+/** bound started ahead of the first ask of a call, as many times as head's lock keeps it started; resolved once each is ready. */
+export const warm = (name) => ((bin) => (bin === undefined ? Promise.resolve() : kept(bin)))(binOf(name));
+export { cooled };
 const facts = (out) => out.flatMap((line) => ((got) => (got.kind === 'fact' ? [got.value.fields] : []))(parse(line)));
-const readOf = (printed) => (printed === undefined || printed.code !== 0 ? { refused: printed?.err.at(-1) ?? '' } : { lines: facts(printed.out) });
+const readOf = (printed) => (printed === undefined || printed.code !== 0 ? { refused: why(printed) ?? '' } : { lines: facts(printed.out) });
 /**
- * The lines a place stands on, from bound's public views alone: its folded normative standing (the lines view), and from
+ * The lines a place stands on, from bound's public views alone: its folded normative standing (the lines view) — its
+ * policy, all that a reader of its pins, keys and views needs, read alone where nothing else is — and from
  * its authenticated evidence what this device's own keys signed. Receipts are history, each kept as it was made; any other
  * line of a device key, the person's own attestation, stands only while it is the one line of its scope and measure,
  * unwithdrawn and beside no line of the place's own: anything else needs a fold bound does not publish, and is refused by
  * name. A place whose land prints no act result is refused before anything lands in it. Any refusal of bound is no standing.
  */
+export const policyAt = async (name, place, signal) => ((folded) => ('refused' in folded || folded.lines.some((line) => line.scope === words.profile) ? folded
+    : { refused: `REFUSE·act the place declares no ${words.profile}: land would print nothing of what it admits, so head lands nothing there; its root can land the local-act@1 profile and view/act` }))(readOf(await run(name, place, [words.read, words.view, words.standing], {}, signal)));
 export const standingAt = async (name, place, devicesOf, isHistory, signal) => {
-    const folded = readOf(await run(name, place, [words.read, words.view, words.standing], {}, signal));
+    const folded = await policyAt(name, place, signal);
     if ('refused' in folded)
         return folded;
-    if (!folded.lines.some((line) => line.scope === words.profile))
-        return { refused: `REFUSE·act the place declares no ${words.profile}: land would print nothing of what it admits, so head lands nothing there; its root can land the local-act@1 profile and view/act` };
     const evidence = readOf(await run(name, place, [words.read, words.view, words.evidence], {}, signal));
     if ('refused' in evidence)
         return evidence;
@@ -43,16 +58,18 @@ export const standingAt = async (name, place, devicesOf, isHistory, signal) => {
         : { refused: `REFUSE·standing ${unfolded.by} attests ${key(unfolded)} more than once, withdrawn, or beside the place's own line: folding a device key's lines is bound's, and bound publishes no view of it` };
 };
 const lotFile = (lines) => ((at) => { writeFileSync(at, `${lines.join('\n')}\n`); return at; })(join(mkdtempSync(join(tmpdir(), 'head-lot-')), 'lot.bound'));
-export const sign = async (name, place, lot, key, signer, env, signal) => ((got) => (got !== undefined && got.code === 0 ? { lines: got.out.filter((line) => parse(line).kind === 'fact') } : { refused: got?.err.at(-1) ?? '' }))(await run(name, place, [words.sign, lotFile(lot), words.key, key, words.signer, signer], env, signal));
+export const sign = async (name, place, lot, key, signer, env, signal) => ((got) => (got !== undefined && got.code === 0 ? { lines: got.out.filter((line) => parse(line).kind === 'fact') } : { refused: why(got) ?? '' }))(await run(name, place, [words.sign, lotFile(lot), words.key, key, words.signer, signer], env, signal));
 /** A lot signed and landed in one process, its result read from what bound printed of the committed act: the records it admitted, never the receipt beside them; a place that declares no act result is refused by name. */
+/** A place's receipts rendered beside its lock, so bound alone checks the place: nothing when they closed, else why they did not. */
+export const closing = async (name, place, signal) => ((got) => (got !== undefined && got.code === 0 ? undefined : why(got) ?? 'nothing printed'))(await run(name, place, [words.read, words.view, words.receipts], {}, signal));
 export const landAct = async (name, place, lot, key, signer, env, signal) => ((got) => {
     if (got === undefined || got.code !== 0)
-        return { refused: got?.err.at(-1) ?? '' };
+        return { refused: why(got) ?? '' };
     const at = got.out.findIndex((line) => line.startsWith(words.act));
     return at < 0 ? { refused: `REFUSE·act bound printed no act result, and the place declares ${words.profile}: what was admitted is bound's to say` }
         : { lines: got.out.slice(at + 1).filter((line) => parse(line).kind === 'fact').slice(0, -1) };
 })(await run(name, place, [words.land, lotFile(lot), words.key, key, words.signer, signer], env, signal));
-export const land = async (name, place, signed, signal) => ((got) => (got !== undefined && got.code === 0 ? { lines: signed } : { refused: got?.err.at(-1) ?? '' }))(await run(name, place, [words.land, lotFile(signed)], {}, signal));
+export const land = async (name, place, signed, signal) => ((got) => (got !== undefined && got.code === 0 ? { lines: signed } : { refused: why(got) ?? '' }))(await run(name, place, [words.land, lotFile(signed)], {}, signal));
 export const told = async (name, place, signed, view, signal) => ((got) => [...(got?.out ?? []), ...(got?.err ?? [])])(await run(name, place, [words.read, words.view, view, lotFile(signed)], {}, signal));
 export const pinnedAt = async (name, place, file, signal) => {
     const printed = await run(name, place, [words.read, file], {}, signal);
@@ -63,6 +80,6 @@ export const pinnedAt = async (name, place, file, signal) => {
     const bytes = printed.out.filter((line) => line.startsWith(words.topos)).map((line) => `${line.slice(words.topos.length)}\n`).join('');
     return pin === undefined || !bytes ? undefined : { pin, bytes, lines: read.lines };
 };
-export const founded = async (name, place, key, signer, env, signal) => ((got) => (got !== undefined && got.code === 0 ? { lines: got.out } : { refused: got?.err.at(-1) ?? '' }))(await run(name, place, [words.land, words.key, key, words.signer, signer], env, signal));
-export const words = { read: '', view: '', sign: '', land: '', key: '', signer: '', pin: '', topos: '', standing: '', evidence: '', act: '', profile: '' };
+export const founded = async (name, place, key, signer, env, signal) => ((got) => (got !== undefined && got.code === 0 ? { lines: got.out } : { refused: why(got) ?? '' }))(await run(name, place, [words.land, words.key, key, words.signer, signer], env, signal));
+export const words = { read: '', view: '', sign: '', land: '', key: '', signer: '', pin: '', topos: '', standing: '', evidence: '', act: '', profile: '', receipts: '', refusal: '' };
 export const settledView = async (name, place, view, signal) => readOf(await run(name, place, [words.read, words.view, view], {}, signal));

package/dist/src/ports/documents.d.ts

@@ -0,0 +1,34 @@
+import type { Attachment } from '../access/contract.ts';
+import type { Context } from '../core/answer.ts';
+import type { Said } from '../core/lock.ts';
+import type { Call } from '../core/read.ts';
+export type Read = {
+    readonly bytes: Uint8Array;
+    readonly kind: string;
+};
+export declare const kindOf: (at: string, type?: string) => string;
+/**
+ * A document the person names: a file inside the place or a folder the client shares, or an encrypted address read with
+ * nothing attached — signed or expiring as it may be — and, when its digest is named, followed wherever it moves to the
+ * bytes that digest names, and only to them. Anything else is not read. Its kind is named, never read for: its file's
+ * extension, its address's, or the media type it was served as; bytes that say none are octet-stream.
+ */
+export declare const documentOf: (context: Context, place: string, at: string, named?: string) => Promise<Read | undefined>;
+/** A document read with the access a source the place connected holds: sent to that source's own origin alone, never redirected with it; a move is followed with nothing attached, only to the bytes its named digest names. */
+export declare const fetchedAs: (context: Context, at: string, via: string, got: {
+    readonly plan: Call;
+    readonly attachment: Attachment | undefined;
+}, named: string, accept: string | undefined) => Promise<Read | {
+    readonly said: readonly string[];
+}>;
+/**
+ * Every byte a package's lines name, by the path each names: read where a line of the same scope says — an encrypted
+ * address, signed or expiring, read with nothing attached and only to the bytes its digest names — or else beside the
+ * package's lock, in its folder or at its address. A path outside the package is never read. And what a place laid
+ * for a source it connected — its document and the overlay beside it — by the path the place keeps them at. And where
+ * an origin says its documents are: the catalog it publishes at its well-known address (RFC 9727), then the paths head's
+ * lock names, each once.
+ */
+export declare const besideOf: (context: Context, document: string, lines: readonly Said[]) => Promise<ReadonlyMap<string, Uint8Array | undefined>>;
+export declare const describedAt: (context: Context, origin: string) => Promise<readonly string[]>;
+export declare const laidOf: (context: Context, place: string, source: string) => readonly (readonly [string, Uint8Array])[];

package/dist/src/ports/documents.js

@@ -0,0 +1,64 @@
+import { dirname, extname, join } from 'node:path';
+import { within } from "../core/answer.js";
+import { members, valueOf } from "../core/lock.js";
+import { sayIn } from "../core/surface.js";
+const limits = (context) => ['adapter/request/wait', 'adapter/request/document-bytes'].map((k) => Number(valueOf(context.lock, k).split('..')[1]));
+export const kindOf = (at, type = '') => (extname(URL.canParse(at) ? new URL(at).pathname : at).slice(1)
+    || (type.split(';')[0].split('/')[1] ?? '').split('+').at(-1).replace(/^x-/, '') || 'octet-stream').toLowerCase();
+/**
+ * A document the person names: a file inside the place or a folder the client shares, or an encrypted address read with
+ * nothing attached — signed or expiring as it may be — and, when its digest is named, followed wherever it moves to the
+ * bytes that digest names, and only to them. Anything else is not read. Its kind is named, never read for: its file's
+ * extension, its address's, or the media type it was served as; bytes that say none are octet-stream.
+ */
+export const documentOf = async (context, place, at, named = '') => {
+    const [wait, most] = limits(context), transport = URL.canParse(at) ? await context.adapter(at) : undefined;
+    if (URL.canParse(at))
+        return named ? ((bytes) => bytes && { bytes, kind: kindOf(at) })(await transport?.published(at, named, most, wait)) : ((got) => got && { bytes: got.bytes, kind: kindOf(at, got.type) })(await transport?.get(at, wait));
+    return ((bytes) => bytes && { bytes, kind: kindOf(at) })((await within(context, place, at)) ? context.files.take(at) : undefined);
+};
+/** A document read with the access a source the place connected holds: sent to that source's own origin alone, never redirected with it; a move is followed with nothing attached, only to the bytes its named digest names. */
+export const fetchedAs = async (context, at, via, got, named, accept) => {
+    const [say, [wait, most]] = [sayIn(context.lock), limits(context)];
+    if (!URL.canParse(at))
+        return { said: [say('document-unread', { document: at })] };
+    if (new URL(at).origin !== new URL(got.plan.origin).origin)
+        return { said: [say('fetch-cross-origin', { document: at, via })] };
+    const transport = await context.adapter(at), answer = transport ? await transport.fetched(at, got.attachment, accept, most, wait) : undefined;
+    if (answer?.kind !== 'got')
+        return { said: [say('document-unread', { document: at })] };
+    if (answer.status >= 300 && answer.status < 400 && answer.location !== undefined) {
+        if (!named)
+            return { said: [say('fetch-redirect', { document: at })] };
+        return ((bytes) => (bytes ? { bytes, kind: kindOf(at) } : { said: [say('document-unread', { document: at })] }))(await transport.published(new URL(answer.location, at).href, named, most, wait));
+    }
+    return answer.status < 300 ? { bytes: answer.bytes, kind: kindOf(at, answer.type) } : { said: [say('fetch-status', { document: at, via, status: String(answer.status) })] };
+};
+/**
+ * Every byte a package's lines name, by the path each names: read where a line of the same scope says — an encrypted
+ * address, signed or expiring, read with nothing attached and only to the bytes its digest names — or else beside the
+ * package's lock, in its folder or at its address. A path outside the package is never read. And what a place laid
+ * for a source it connected — its document and the overlay beside it — by the path the place keeps them at. And where
+ * an origin says its documents are: the catalog it publishes at its well-known address (RFC 9727), then the paths head's
+ * lock names, each once.
+ */
+export const besideOf = async (context, document, lines) => {
+    const [wait, most] = limits(context), read = new Map();
+    for (const l of lines.filter((one) => one.needs && one.measure === 'digest' && !one.needs.split('/').includes('..') && !one.needs.startsWith('/'))) {
+        const at = lines.find((o) => o.scope === l.scope && o.measure === 'id')?.value ?? (URL.canParse(document) ? new URL(l.needs, document).href : join(dirname(document), l.needs));
+        read.set(l.needs, URL.canParse(at) ? await (await context.adapter(at))?.published(at, l.value ?? '', most, wait) : context.files.take(at));
+    }
+    return read;
+};
+export const describedAt = async (context, origin) => {
+    const [wait] = limits(context), catalog = await (await context.adapter(origin))?.get(new URL(valueOf(context.lock, 'use/catalog'), origin).href, wait), rel = valueOf(context.lock, 'use/catalog-rel');
+    const listed = (() => { try {
+        return JSON.parse(new TextDecoder().decode(catalog?.bytes ?? new Uint8Array())).linkset?.flatMap((l) => (l[rel] ?? []).flatMap((d) => d.href ?? [])) ?? [];
+    }
+    catch {
+        return [];
+    } })();
+    return [...new Set([...listed, ...members(valueOf(context.lock, 'use/documents'))].flatMap((at) => (URL.canParse(at, origin) ? [new URL(at, origin).href] : [])))];
+};
+export const laidOf = (context, place, source) => ((at) => context.files.list(place, at).filter((f) => new RegExp(`^${source}\\.(overlay\\.)?[^.]+$`).test(f))
+    .map((f) => [`${at}/${f}`, context.files.take(join(place, at, f)) ?? new Uint8Array()]))(valueOf(context.lock, 'place/connected'));

package/dist/src/ports/keychain.d.ts

@@ -1,7 +1,8 @@
 export interface KeyStore {
     readonly read: (account: string) => string | undefined;
     readonly write: (account: string, secret: string) => void;
+    readonly made?: (account: string) => string | undefined;
 }
 export declare const plain: (word: string) => string;
-/** The secret store this host keeps head's keys in, by the name its lock gives the platform's: one adapter each, every secret crossing a command's stdin and stdout only. */
+/** The secret store this host keeps head's keys in, by the name its lock gives the platform's: one adapter each, every secret crossing a command's stdin and stdout only; a key it is asked for by its account is made there once, and only its public half handed on. */
 export declare const keychain: (service: string, kind: string) => KeyStore;

package/dist/src/ports/keychain.js

@@ -1,11 +1,12 @@
 import { store as credentialManager } from "./stores/credential-manager.js";
 import { store as keychainOfMac } from "./stores/keychain.js";
 import { store as secretTool } from "./stores/secret-tool.js";
+import { newKey, publicOf } from "./keys.js";
 export const plain = (word) => { if (!/^[\w.@/+=-]+$/.test(word))
     throw Error('REFUSE·keychain a name holds more than word characters'); return word; };
-/** The secret store this host keeps head's keys in, by the name its lock gives the platform's: one adapter each, every secret crossing a command's stdin and stdout only. */
+/** The secret store this host keeps head's keys in, by the name its lock gives the platform's: one adapter each, every secret crossing a command's stdin and stdout only; a key it is asked for by its account is made there once, and only its public half handed on. */
 export const keychain = (service, kind) => ((made) => {
     if (made === undefined)
         throw Error(`REFUSE·keychain ${kind} is no store head carries`);
-    return made(service);
+    return ((store) => ({ ...store, made: (account) => ((secret) => secret && publicOf(secret))(store.read(account) ?? ((key) => { store.write(account, key.secret); return store.read(account) === key.secret ? key.secret : undefined; })(newKey())) }))(made(service));
 })({ keychain: keychainOfMac, 'secret-tool': secretTool, 'credential-manager': credentialManager }[kind]);

package/dist/src/ports/place.d.ts

@@ -8,3 +8,4 @@ export declare const layAt: (place: string, rel: string, bytes: Uint8Array) => v
 export declare const takeAt: (path: string) => Uint8Array | undefined;
 export declare const hasAt: (place: string, rel: string) => boolean;
 export declare const dropAt: (place: string, rel: string) => void;
+export declare const listAt: (place: string, rel: string) => readonly string[];

package/dist/src/ports/place.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { LOCK } from '@lapxo/topos/wire';
@@ -24,3 +24,9 @@ catch {
 } };
 export const hasAt = (place, rel) => existsSync(resolve(place, rel));
 export const dropAt = (place, rel) => rmSync(inside(place, rel), { force: true });
+export const listAt = (place, rel) => { try {
+    return readdirSync(inside(place, rel));
+}
+catch {
+    return [];
+} };

package/dist/src/ports/process.d.ts

@@ -1,13 +1,20 @@
+import type { ChildProcess } from 'node:child_process';
 export interface Printed {
     readonly code: number;
     readonly out: readonly string[];
     readonly err: readonly string[];
+    readonly refusal?: Readonly<Record<string, string>>;
 }
 export interface Bounds {
     readonly wait: number;
     readonly most: number;
     readonly signal?: AbortSignal;
 }
+/** A process head starts in a group of its own, so stopping it stops everything it started. */
+export declare const grouped: (command: string, args: readonly string[], at: {
+    readonly cwd?: string;
+    readonly env?: NodeJS.ProcessEnv;
+}, pipes?: number) => ChildProcess;
 /**
  * A process run beside head, never blocking it: what it printed, out and err, line by line, and its exit, which is
  * transport and never the verdict. Its whole group is stopped when the wait runs out, when it prints more bytes than it
@@ -18,3 +25,5 @@ export declare const spawned: (command: string, args: readonly string[], at: {
     readonly env?: NodeJS.ProcessEnv;
     readonly input?: string;
 }, bounds: Bounds) => Promise<Printed>;
+/** What a process head already started prints from now on, within the same bounds. */
+export declare const watched: (child: ChildProcess, bounds: Bounds) => Promise<Printed>;

package/dist/src/ports/process.js

@@ -2,13 +2,16 @@ import { spawn } from 'node:child_process';
 const running = new Set();
 process.once('exit', () => { for (const stop of running)
     stop(); });
+/** A process head starts in a group of its own, so stopping it stops everything it started. */
+export const grouped = (command, args, at, pipes = 3) => spawn(command, [...args], { cwd: at.cwd, env: at.env, stdio: Array(pipes).fill('pipe'), detached: process.platform !== 'win32', windowsHide: true });
 /**
  * A process run beside head, never blocking it: what it printed, out and err, line by line, and its exit, which is
  * transport and never the verdict. Its whole group is stopped when the wait runs out, when it prints more bytes than it
  * may, when the asker cancels or when head exits; the exit is then -1 and the cause is err's last line.
  */
-export const spawned = (command, args, at, bounds) => new Promise((resolve) => {
-    const child = spawn(command, [...args], { cwd: at.cwd, env: at.env, stdio: ['pipe', 'pipe', 'pipe'], detached: process.platform !== 'win32', windowsHide: true });
+export const spawned = (command, args, at, bounds) => ((child) => { child.stdin.on('error', () => undefined).end(at.input ?? ''); return watched(child, bounds); })(grouped(command, args, at));
+/** What a process head already started prints from now on, within the same bounds. */
+export const watched = (child, bounds) => new Promise((resolve) => {
     const [out, err] = [[], []];
     let [printed, cause, done] = [0, undefined, false];
     const kill = () => { try {
@@ -41,7 +44,6 @@ export const spawned = (command, args, at, bounds) => new Promise((resolve) => {
     child.stderr.on('data', take(err));
     child.on('error', (error) => { cause ??= error.message; finish(-1); });
     child.on('close', (code) => finish(code ?? -1));
-    child.stdin.on('error', () => undefined).end(at.input ?? '');
     if (signal.aborted)
         cancel();
     else

package/dist/src/ports/spare.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/ports/spare.js

@@ -0,0 +1,33 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { readFileSync } from 'node:fs';
+import { Socket } from 'node:net';
+import { pathToFileURL } from 'node:url';
+/**
+ * A process started before it is asked: it loads what the program it will run imports, says it is ready on its fourth
+ * pipe, and waits there for one ask, the folder, the arguments and the variables a process started then would have been
+ * given. It takes them as its own, closes that pipe and runs the program once, as that process would have. An ask that
+ * never comes ends it.
+ */
+const [program] = process.argv.slice(2);
+const url = pathToFileURL(program), pipe = new Socket({ fd: 3, readable: true, writable: true });
+const asked = new Promise((resolve) => { let text = ''; pipe.setEncoding('utf8').on('data', (chunk) => { text += chunk; }).on('error', () => undefined).on('close', () => resolve(text)); });
+await Promise.all([...readFileSync(program, 'utf8').matchAll(/^import [^'"]*['"](\.{1,2}\/[^'"]+)['"];?$/gm)].map(([, path]) => import(__rewriteRelativeImportExtension(new URL(path, url).href)).catch(() => undefined)));
+pipe.write('ready\n');
+const text = await asked;
+if (!text)
+    process.exit(0);
+const { cwd, args, env } = JSON.parse(text);
+for (const name of Object.keys(process.env))
+    if (!(name in env))
+        delete process.env[name];
+Object.assign(process.env, env);
+process.chdir(cwd);
+process.argv = [process.argv[0], program, ...args];
+await import(__rewriteRelativeImportExtension(url.href));

package/dist/src/ports/surface.d.ts

@@ -0,0 +1,126 @@
+import type { Said } from '../core/lock.ts';
+export interface Field {
+    readonly name: string;
+    readonly about: string;
+    readonly type: string;
+    readonly required: boolean;
+}
+export interface Tool {
+    readonly name: string;
+    readonly about: string;
+    readonly fields: readonly Field[];
+    readonly hints: readonly string[];
+}
+export interface Resource {
+    readonly name: string;
+    readonly about: string;
+    readonly template: string;
+    readonly mime: string;
+}
+export interface Prompt {
+    readonly name: string;
+    readonly about: string;
+    readonly text: string;
+    readonly line: string;
+    readonly fields: readonly Field[];
+}
+export interface Surface {
+    readonly name: string;
+    readonly version: string;
+    readonly tools: readonly Tool[];
+    readonly resources: readonly Resource[];
+    readonly prompts: readonly Prompt[];
+}
+/** Everything a client is offered, read off the lock alone: its tools, resources and prompts, each with the words a model sees. */
+export declare const surfaceOf: (lock: readonly Said[]) => Surface;
+export declare const refusedOn: (lock: readonly Said[], platform: string) => string | undefined;
+/**
+ * The fields a URI gives a resource template, or none when it is not one of its URIs: {name} matches one path step,
+ * {?a,b} names query fields any of which may be absent, in any order, each decoded.
+ */
+export declare const matchTemplate: (template: string, uri: string) => Readonly<Record<string, string>> | undefined;
+export interface Cell {
+    readonly code: string;
+    readonly state: string;
+    readonly next: {
+        readonly tool: string;
+        readonly args: Readonly<Record<string, string>>;
+    } | {
+        readonly none: string;
+    };
+    readonly fields: Readonly<Record<string, string>>;
+    readonly head?: string;
+}
+/** A said code as the cell head answers with: its state and next from the lock, the next's arguments read from the cell's own fields; a bound refusal a field carries keeps bound's code, head's own beside it. */
+export declare const cellOf: (lock: readonly Said[], key: string, given: Readonly<Record<string, string | undefined>>) => Cell;
+export declare const cellLine: (cell: Cell) => string;
+/** An answer as cells and the lines bound printed beside them, read back from what head said: the shape every tool result has. */
+export declare const shapeOf: (answer: readonly string[]) => {
+    readonly cells: readonly Cell[];
+    readonly lines: readonly string[];
+};
+/** The one output schema every tool declares: cells in the states the lock names, and the lines bound printed. */
+export declare const shapeSchema: (lock: readonly Said[]) => {
+    type: "object";
+    required: string[];
+    properties: {
+        cells: {
+            type: string;
+            items: {
+                type: string;
+                required: string[];
+                properties: {
+                    code: {
+                        type: string;
+                    };
+                    state: {
+                        enum: string[];
+                    };
+                    head: {
+                        type: string;
+                    };
+                    next: {
+                        oneOf: ({
+                            type: string;
+                            required: string[];
+                            properties: {
+                                tool: {
+                                    type: string;
+                                };
+                                args: {
+                                    type: string;
+                                    additionalProperties: {
+                                        type: string;
+                                    };
+                                };
+                                none?: undefined;
+                            };
+                        } | {
+                            type: string;
+                            required: string[];
+                            properties: {
+                                none: {
+                                    type: string;
+                                };
+                                tool?: undefined;
+                                args?: undefined;
+                            };
+                        })[];
+                    };
+                    fields: {
+                        type: string;
+                        additionalProperties: {
+                            type: string;
+                        };
+                    };
+                };
+            };
+        };
+        lines: {
+            type: string;
+            items: {
+                type: string;
+            };
+        };
+    };
+};

package/dist/src/ports/surface.js

@@ -0,0 +1,48 @@
+import { aboutOf, below, members, valueOf } from "../core/lock.js";
+import { sayIn } from "../core/surface.js";
+const nameOf = (line) => line.scope.split('/')[1];
+const fieldsOf = (lock, scope) => ((required) => members(valueOf(lock, scope)).map((name) => ({
+    name, about: aboutOf(lock, `${scope}/${name}`), type: valueOf(lock, `${scope}/${name}`), required: required.includes(name)
+})))(members(valueOf(lock, `${scope}/required`)));
+/** Everything a client is offered, read off the lock alone: its tools, resources and prompts, each with the words a model sees. */
+export const surfaceOf = (lock) => ({
+    name: valueOf(lock, 'name'), version: valueOf(lock, 'version'),
+    tools: below(lock, 'tool').map((line) => ({ name: nameOf(line), about: line.about ?? '', fields: fieldsOf(lock, line.scope), hints: members(valueOf(lock, `${line.scope}/hints`)) })),
+    resources: below(lock, 'resource').map((line) => ({ name: nameOf(line), about: line.about ?? '', template: line.value ?? '', mime: valueOf(lock, `${line.scope}/mime`) })),
+    prompts: below(lock, 'prompt').map((line) => ({ name: nameOf(line), about: line.about ?? '', text: aboutOf(lock, `${line.scope}/text`), line: aboutOf(lock, `${line.scope}/line`), fields: fieldsOf(lock, line.scope) })),
+});
+export const refusedOn = (lock, platform) => ((supported) => (supported.includes(platform) ? undefined : sayIn(lock)('platform', { platform, supported: supported.join('|') })))(members(valueOf(lock, 'platform/supported')));
+/**
+ * The fields a URI gives a resource template, or none when it is not one of its URIs: {name} matches one path step,
+ * {?a,b} names query fields any of which may be absent, in any order, each decoded.
+ */
+export const matchTemplate = (template, uri) => {
+    const [path = '', query = ''] = template.split('{?');
+    const names = [...path.matchAll(/\{(\w+)\}/g)].map((m) => m[1]);
+    const pattern = new RegExp(`^${path.split(/\{\w+\}/).map((part) => part.replace(/[.*+?^$()|[\]\\]/g, '\\$&')).join('([^/?#]+)')}(?:\\?(.*))?$`);
+    const got = pattern.exec(uri);
+    if (got === null)
+        return undefined;
+    const params = new URLSearchParams(got[names.length + 1] ?? '');
+    return { ...Object.fromEntries(names.map((name, i) => [name, decodeURIComponent(got[i + 1])])),
+        ...Object.fromEntries(query.replace('}', '').split(',').filter(Boolean).flatMap((name) => ((v) => (v === null ? [] : [[name, v]]))(params.get(name)))) };
+};
+/** A said code as the cell head answers with: its state and next from the lock, the next's arguments read from the cell's own fields; a bound refusal a field carries keeps bound's code, head's own beside it. */
+export const cellOf = (lock, key, given) => {
+    const fields = Object.fromEntries(Object.entries(given).filter((e) => e[1] !== undefined)), bound = Object.values(fields).map((v) => /^REFUSE·[\w-]+/.exec(v)?.[0]).find(Boolean);
+    const [tool, args] = [valueOf(lock, `said/${key}/next`), members(valueOf(lock, `said/${key}/next/args`)).map((a) => ((k, v) => [k, v.startsWith('$') ? fields[v.slice(1)] ?? '' : v])(a.split(':')[0], a.slice(a.indexOf(':') + 1)))];
+    return { code: bound ?? `head/${key}`, state: valueOf(lock, `said/${key}/state`), next: tool === 'none' ? { none: aboutOf(lock, `said/${key}/next`) } : { tool, args: Object.fromEntries(args) }, fields, ...(bound ? { head: `head/${key}` } : {}) };
+};
+export const cellLine = (cell) => [`said/${cell.code} state=${cell.state}`, ...('tool' in cell.next ? [`next=${cell.next.tool}`, ...Object.entries(cell.next.args).map(([k, v]) => `next.${k}=${JSON.stringify(v)}`)] : ['next=none', `next.why=${JSON.stringify(cell.next.none)}`]),
+    ...(cell.head ? [`head=${JSON.stringify(cell.head)}`] : []), ...Object.entries(cell.fields).map(([k, v]) => `${k}=${JSON.stringify(v)}`)].join(' ');
+/** An answer as cells and the lines bound printed beside them, read back from what head said: the shape every tool result has. */
+export const shapeOf = (answer) => ({ lines: answer.filter((l) => !l.startsWith('said/')),
+    cells: answer.filter((l) => l.startsWith('said/')).map((l) => ((code, rest) => ((t) => ({ code, state: t['state'] ?? '', next: t['next'] === 'none' || t['next'] === undefined ? { none: t['next.why'] ?? '' } : { tool: t['next'], args: Object.fromEntries(Object.entries(t).filter(([k]) => k.startsWith('next.')).map(([k, v]) => [k.slice(5), v])) },
+        fields: Object.fromEntries(Object.entries(t).filter(([k]) => !['state', 'next', 'head'].includes(k) && !k.startsWith('next.'))), ...(t['head'] ? { head: t['head'] } : {}) }))(Object.fromEntries([...rest.matchAll(/(\S+?)=("(?:[^"\\]|\\.)*"|\S+)/g)].map((m) => [m[1], m[2].startsWith('"') ? JSON.parse(m[2]) : m[2]]))))(l.slice('said/'.length, l.indexOf(' ')), l.slice(l.indexOf(' ') + 1))) });
+/** The one output schema every tool declares: cells in the states the lock names, and the lines bound printed. */
+export const shapeSchema = (lock) => ({ type: 'object', required: ['cells', 'lines'], properties: {
+        cells: { type: 'array', items: { type: 'object', required: ['code', 'state', 'next', 'fields'], properties: { code: { type: 'string' }, state: { enum: [...members(valueOf(lock, 'shape/states'))] }, head: { type: 'string' },
+                    next: { oneOf: [{ type: 'object', required: ['tool', 'args'], properties: { tool: { type: 'string' }, args: { type: 'object', additionalProperties: { type: 'string' } } } }, { type: 'object', required: ['none'], properties: { none: { type: 'string' } } }] },
+                    fields: { type: 'object', additionalProperties: { type: 'string' } } } } },
+        lines: { type: 'array', items: { type: 'string' } }
+    } });

package/dist/src/ports/warm.d.ts

@@ -0,0 +1,19 @@
+import type { Bounds, Printed } from './process.ts';
+/** How many processes head keeps started ahead of each program while it answers a call, and the variables node reads as it starts: a process started under other values of them is never asked. */
+export declare const warmth: {
+    spares: number;
+    boot: readonly string[];
+};
+/** Keeps as many processes started ahead of a program as head's lock says; resolved when each has loaded what it runs. */
+export declare const kept: (program: string) => Promise<unknown>;
+/** Every process still waiting to be asked is stopped: head keeps none past the call it started them for. */
+export declare const cooled: () => void;
+/**
+ * A program run in a process started ahead under the same starting variables, handed the folder, arguments and
+ * variables a process started now would get, and watched within the same bounds; undefined when none is held ready,
+ * so the caller starts one as before and never waits on one still loading. Each process answers one ask and ends.
+ */
+export declare const warmed: (program: string, args: readonly string[], at: {
+    readonly cwd: string;
+    readonly env: NodeJS.ProcessEnv;
+}, bounds: Bounds) => Promise<Printed> | undefined;

package/dist/src/ports/warm.js

@@ -0,0 +1,46 @@
+import { fileURLToPath } from 'node:url';
+import { grouped, watched } from "./process.js";
+/** How many processes head keeps started ahead of each program while it answers a call, and the variables node reads as it starts: a process started under other values of them is never asked. */
+export const warmth = { spares: 0, boot: [] };
+const spares = new Map();
+const alive = (one) => one.child.exitCode === null && one.child.signalCode === null;
+const entry = fileURLToPath(new URL(`./spare${import.meta.url.slice(import.meta.url.lastIndexOf('.'))}`, import.meta.url));
+const bootOf = (env) => JSON.stringify(Object.entries(env).filter(([name]) => warmth.boot.some((p) => name.startsWith(p))).sort(([a], [b]) => (a < b ? -1 : 1)));
+const stop = (one) => { try {
+    process.kill(-one.child.pid, 'SIGKILL');
+}
+catch {
+    one.child.kill('SIGKILL');
+} };
+const started = (program) => {
+    const env = { ...process.env }, child = grouped(process.execPath, [entry, program], { env }, 4);
+    child.stdin.on('error', () => undefined).end('');
+    const spare = { child, boot: bootOf(env), ready: new Promise((resolve) => { child.stdio[3].on('error', () => undefined).once('data', () => { spare.loaded = true; resolve(); }); child.once('close', () => resolve()); }), loaded: false };
+    return spare;
+};
+/** Keeps as many processes started ahead of a program as head's lock says; resolved when each has loaded what it runs. */
+export const kept = (program) => {
+    const live = (spares.get(program) ?? []).filter(alive);
+    while (live.length < warmth.spares)
+        live.push(started(program));
+    spares.set(program, live);
+    return Promise.all(live.map((one) => one.ready));
+};
+/** Every process still waiting to be asked is stopped: head keeps none past the call it started them for. */
+export const cooled = () => { for (const one of [...spares.values()].flat())
+    stop(one); spares.clear(); };
+process.once('exit', cooled);
+/**
+ * A program run in a process started ahead under the same starting variables, handed the folder, arguments and
+ * variables a process started now would get, and watched within the same bounds; undefined when none is held ready,
+ * so the caller starts one as before and never waits on one still loading. Each process answers one ask and ends.
+ */
+export const warmed = (program, args, at, bounds) => {
+    const live = spares.get(program) ?? [], index = live.findIndex((one) => one.loaded && alive(one) && one.boot === bootOf(at.env));
+    const spare = index < 0 ? undefined : live.splice(index, 1)[0];
+    if (spare === undefined)
+        return undefined;
+    void kept(program);
+    spare.child.stdio[3].end(`${JSON.stringify({ cwd: at.cwd, args, env: at.env })}\n`);
+    return watched(spare.child, bounds);
+};

package/dist/src/signer.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { readFileSync } from 'node:fs';
-import { signLot } from "./core/keys.js";
+import { signLot } from "./ports/keys.js";
 import { keychain } from "./ports/keychain.js";
 const [service = '', account = '', key = '', algorithm = '', store = 'keychain'] = process.argv.slice(2);
 const secret = keychain(service, store).read(account);

package/dist/src/sources/access.d.ts

@@ -1,8 +1,17 @@
 import type { Asked, Context } from '../core/answer.ts';
+import type { Call } from '../core/read.ts';
+import type { Attachment } from '../access/contract.ts';
 /**
  * Access to a source obtained ahead of any call, at the origin the person picked once where several are declared: the
  * way its document says access is proven, run by the adapter of
  * that kind — the person's own page, or the provider they are sent to with a client registered for the visit — its
- * secret kept in this keychain and its obtaining landed as a receipt the device key signs. Nothing is called.
+ * secret kept in this keychain and its obtaining landed as a receipt the device key signs. Nothing is called. What it
+ * attaches is what a fetch made as that source carries, to that source's own origin alone.
  */
 export declare const accessed: (asked: Asked, context: Context) => Promise<readonly string[]>;
+export declare const attachedFor: (context: Context, place: string, source: string, asked?: string) => Promise<{
+    readonly plan: Call;
+    readonly attachment: Attachment | undefined;
+} | {
+    readonly said: readonly string[];
+}>;