@lapxo/head 0.1.0 → 0.1.4

package/dist/src/ports/access/person.js

@@ -6,8 +6,9 @@ import { open } from "./page.js";
 /**
  * The person at this device, asked through the richest channel the client declares, in the order head's lock lines name:
  * the client's own form; head's one-time page, sent by the client as an address; the same page opened by this device's
- * browser. A secret goes only through the page — never a form the model could see — and a yes only through what the
- * client can ask, else it is the person's to sign. A visit to a provider comes back to such a page.
+ * browser. A secret goes only through the page — never a form the model could see — and a yes is the person's answer on
+ * any of them, never the model's: where none reaches the person, nothing was asked and the lines are theirs to sign.
+ * A visit to a provider comes back to such a page.
  */
 export const personOf = (lock, client) => {
     const wait = Number(valueOf(lock, 'access/wait').split('..')[1]);
@@ -18,9 +19,15 @@ export const personOf = (lock, client) => {
     const paged = async (title, fields, how) => offered(fill(aboutOf(lock, fields.some((f) => f.secret) ? 'said/enter' : 'said/answer'), { title }), await open(title, fields, wait), how);
     const form = async (message, properties) => ((got) => (got.action === 'accept' ? Object.fromEntries(Object.entries(got.content ?? {}).map(([k, v]) => [k, String(v)])) : undefined))(await client.elicit({ message, requestedSchema: { type: 'object', properties, required: Object.keys(properties) } }));
     return {
-        consent: async (message, word) => ((how) => (how === undefined ? Promise.resolve('none')
-            : (how === 'form' ? form(message, { yes: { type: 'boolean', title: word } }) : paged(message, [{ name: 'yes', label: word, secret: false, options: [{ value: 'true', label: word }, { value: 'false', label: 'No' }] }], how))
-                .then((got) => (got?.['yes'] === 'true' ? 'yes' : 'no'))))(channel('ask/consent-channels')),
+        consent: async (message, word) => {
+            const how = channel('ask/consent-channels'), said = (got) => (got?.['yes'] === 'true' ? 'yes' : 'no');
+            if (how === undefined)
+                return 'none';
+            if (how === 'form')
+                return said(await form(message, { yes: { type: 'boolean', title: word } }));
+            const page = await open(message, [{ name: 'yes', label: word, secret: false, options: [{ value: 'true', label: word }, { value: 'false', label: 'No' }] }], wait);
+            return (await offer(fill(aboutOf(lock, 'said/answer'), { title: message }), page.url, how)) ? said(await page.held) : (page.close(), 'none');
+        },
         enter: async (title, fields) => paged(title, fields, channel('ask/secret-channels')),
         choose: async (message, choices) => ((how) => (how === 'form'
             ? form(message, Object.fromEntries(choices.map((c) => [c.name, { type: 'string', title: c.label ?? c.name, ...(c.options ? { oneOf: c.options.map((o) => ({ const: o.value, title: o.label })) } : {}) }])))

package/dist/src/ports/adapters/request.d.ts

@@ -6,6 +6,8 @@ export type Fetched = {
     readonly status: number;
     readonly bytes: Uint8Array;
     readonly type: string;
+    readonly location?: string;
+    readonly authenticate?: string;
 } | {
     readonly kind: 'over';
 } | {
@@ -21,6 +23,7 @@ export type Prepared = {
     readonly refused: string;
 };
 export declare const published: (url: string, digest: string, most: number, wait: number) => Promise<Uint8Array | undefined>;
+export declare const fetched: (url: string, attachment: Attachment | undefined, accept: string | undefined, most: number, wait: number) => Promise<Fetched>;
 export declare const get: (url: string, wait: number) => Promise<{
     readonly bytes: Uint8Array;
     readonly type: string;

package/dist/src/ports/adapters/request.js

@@ -17,16 +17,18 @@ const requestCapped = async (method, url, headers, body, most, wait, redirect =
                 break;
             chunks.push(chunk);
         }
-        return size > most ? { kind: 'over' } : { kind: 'got', status: response.status, bytes: Buffer.concat(chunks), type: response.headers.get('content-type') ?? '' };
+        return size > most ? { kind: 'over' } : { kind: 'got', status: response.status, bytes: Buffer.concat(chunks), type: response.headers.get('content-type') ?? '', ...((at) => (at ? { location: at } : {}))(response.headers.get('location')), ...((asks) => (asks ? { authenticate: asks } : {}))(response.headers.get('www-authenticate')) };
     }
     catch {
         return { kind: 'failed' };
     }
 };
 const loopback = new Set(['127.0.0.1', 'localhost', '[::1]']);
-export const published = async (url, digest, most, wait) => (URL.canParse(url) && new URL(url).protocol === 'https:'
+export const published = async (url, digest, most, wait) => (URL.canParse(url) && ((at) => at.protocol === 'https:' || loopback.has(at.hostname))(new URL(url))
     ? ((got) => (got.kind === 'got' && got.status < 300 && `sha256:${createHash('sha256').update(got.bytes).digest('hex')}` === digest ? got.bytes : undefined))(await requestCapped('GET', url, {}, undefined, most, wait, 'follow')) : undefined);
-export const get = async (url, wait) => (URL.canParse(url) && new URL(url).protocol === 'https:' ? ((got) => (got.kind === 'got' && got.status < 300 ? got : undefined))(await requestCapped('GET', url, {}, undefined, 16_777_216, wait)) : undefined);
+export const fetched = async (url, attachment, accept, most, wait) => (!URL.canParse(url) || !((at) => at.protocol === 'https:' || loopback.has(at.hostname))(new URL(url)) ? { kind: 'failed' }
+    : requestCapped('GET', ((extra) => (extra.size ? `${url}${url.includes('?') ? '&' : '?'}${extra}` : url))(new URLSearchParams(Object.entries(attachment?.query ?? {}))), { ...(attachment?.headers ?? {}), ...(accept ? { accept } : {}) }, undefined, most, wait));
+export const get = async (url, wait) => (URL.canParse(url) && ((at) => at.protocol === 'https:' || loopback.has(at.hostname))(new URL(url)) ? ((got) => (got.kind === 'got' && got.status < 300 ? got : undefined))(await requestCapped('GET', url, {}, undefined, 16_777_216, wait)) : undefined);
 /** A body posted to an address a declaration names — as a form, or as JSON where the declaration's protocol asks it — as one request under the same rules: encrypted unless it is this device, capped, never redirected. */
 export const post = async (url, body, most, wait, as = 'form') => {
     if (!URL.canParse(url) || !((at) => at.protocol === 'https:' || loopback.has(at.hostname))(new URL(url)))

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

@@ -1,28 +1,36 @@
 import type { Said } from '../core/lock.ts';
 import type { Outcome } from '../core/answer.ts';
+import { cooled } from './warm.ts';
 import type { Printed } from './process.ts';
 export type { Printed };
 export declare const limits: {
     wait: number;
     most: number;
 };
-/** 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. */
+/** 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 declare const run: (name: string, cwd: string, args: readonly string[], env?: Readonly<Record<string, string>>, signal?: AbortSignal) => Promise<Printed | undefined>;
+/** 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 declare const warm: (name: string) => Promise<unknown>;
+export { cooled };
 export type Folded = {
     readonly lines: readonly Said[];
 } | {
     readonly refused: string;
 };
 /**
- * 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 declare const policyAt: (name: string, place: string, signal?: AbortSignal) => Promise<Folded>;
 export declare const standingAt: (name: string, place: string, devicesOf: (lines: readonly Said[]) => readonly string[], isHistory: (line: Said) => boolean, signal?: AbortSignal) => Promise<Folded>;
 export declare const sign: (name: string, place: string, lot: readonly string[], key: string, signer: string, env: Readonly<Record<string, string>>, signal?: AbortSignal) => Promise<Outcome>;
 /** 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 declare const closing: (name: string, place: string, signal?: AbortSignal) => Promise<string | undefined>;
 export declare const landAct: (name: string, place: string, lot: readonly string[], key: string, signer: string, env: Readonly<Record<string, string>>, signal?: AbortSignal) => Promise<Outcome>;
 export declare const land: (name: string, place: string, signed: readonly string[], signal?: AbortSignal) => Promise<Outcome>;
 export declare const told: (name: string, place: string, signed: readonly string[], view: string, signal?: AbortSignal) => Promise<readonly string[]>;
@@ -47,5 +55,7 @@ export declare const words: {
     evidence: string;
     act: string;
     profile: string;
+    receipts: string;
+    refusal: string;
 };
 export declare const settledView: (name: string, place: string, view: string, signal?: AbortSignal) => Promise<Folded>;

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,130 @@
+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 catalogue: readonly Tool[];
+    readonly resources: readonly Resource[];
+    readonly prompts: readonly Prompt[];
+}
+/**
+ * Everything a client is offered, read off the lock alone, each with the words a model sees: the tools surface/tools
+ * names, out of the catalogue the tool lines are (every one of them where it names none), its resources and prompts.
+ */
+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;
+            };
+        };
+    };
+};