@lapxo/head 0.0.0-stage → 0.1.0

package/dist/src/core/read.d.ts

@@ -0,0 +1,51 @@
+import type { Said } from './lock.ts';
+export type Plan = {
+    readonly kind: 'said';
+    readonly key: string;
+    readonly fields: Readonly<Record<string, string>>;
+};
+export type Fields = Readonly<Record<string, readonly string[]>>;
+export interface Access {
+    readonly kind: string;
+    readonly scheme: string;
+    readonly params: Fields;
+    readonly account: string | undefined;
+    readonly flow: string;
+}
+export interface Call {
+    readonly kind: 'call';
+    readonly source: string;
+    readonly operation: string;
+    readonly origin: string;
+    readonly carry: Fields;
+    readonly form: Fields;
+    readonly classes: readonly string[];
+    readonly access: Access;
+}
+export declare const fieldsOf: (lines: readonly Said[], scope: string) => Fields;
+export declare const vocabOf: (lock: readonly Said[]) => {
+    offers: string;
+    keys: string;
+    region: string;
+    class: string;
+    access: string;
+    origin: string;
+    origins: string;
+    issuers: string;
+    unresolved: string;
+    unparsed: string;
+    unsupported: string;
+    collision: string;
+    scheme: string;
+    form: string;
+    carry: string;
+    anonymous: string;
+    unstated: string;
+    callable: string;
+    split: string;
+    pick: string;
+};
+export type Vocab = ReturnType<typeof vocabOf>;
+export declare const stepOf: (lines: readonly Said[], lock: readonly Said[], source: string, operation: string) => Call | Plan;
+export declare const planRead: (lines: readonly Said[], lock: readonly Said[], source: string, operation: string, place: string) => Call | Plan;
+export declare const planAct: (lines: readonly Said[], lock: readonly Said[], source: string, operation: string, place: string) => Call | Plan;

package/dist/src/core/read.js

@@ -0,0 +1,60 @@
+import { alphabet } from '@lapxo/topos/wire';
+import { valueOf } from "./lock.js";
+const said = (key, fields = {}) => ({ kind: 'said', key, fields });
+const membersOf = (line) => (line === undefined ? undefined : alphabet(line.value ?? '').members);
+export const fieldsOf = (lines, scope) => Object.fromEntries(lines.filter((l) => l.scope === scope && l.measure).map((l) => [l.measure, membersOf(l) ?? []]));
+export const vocabOf = (lock) => ((w) => ({
+    offers: w('offers'), keys: w('keys'), region: w('region'), class: w('class'), access: w('access'), origin: w('origin'), origins: w('origins'), issuers: w('issuers'), unresolved: w('unresolved'), unparsed: w('unparsed'), unsupported: w('unsupported'), collision: w('collision'),
+    scheme: w('scheme'), form: w('form'), carry: w('carry'), anonymous: w('anonymous'), unstated: w('unstated'), callable: w('callable'), split: w('split'), pick: w('pick'),
+}))((k) => valueOf(lock, `vocab/${k}`));
+/** Where a source is reached: the origin the person picked, or the one its document declares when it declares one; several and none picked is no call, and none is ever a default. */
+const originOf = (lines, v, source) => {
+    const at = fieldsOf(lines, `${v.region}/${source}`);
+    const picked = lines.find((l) => l.scope === `${v.pick}/${source}`)?.value;
+    if (picked !== undefined)
+        return picked;
+    const declared = at[v.origins] ?? [];
+    return declared.length === 1 ? declared[0] : said(declared.length ? 'pick-origin' : 'no-origin', { source, origins: declared.join(', ') });
+};
+/** How access is proven for an offer: its first declared alternative that says how what it obtains rides a request — anonymous, or a scheme whose flow the one adapter runs, its own or its issuer's, kept once per issuer; unstated, or none that says, is no call, named. */
+const accessOf = (lines, lock, v, source, operation, place) => {
+    const ways = fieldsOf(lines, `${v.offers}/${source}/${operation}`)[v.access] ?? [v.unstated];
+    if (ways.includes(v.unstated))
+        return said('access-unstated', { source, operation });
+    const kindOf = (way) => {
+        if (way === v.anonymous)
+            return [way, v.anonymous, {}, '', undefined];
+        const issuer = fieldsOf(lines, `${v.keys}/${source}/${way}`)['issuer']?.[0];
+        const flow = issuer ?? `${source}/${way}`;
+        const params = fieldsOf(lines, `${v.keys}/${flow}`);
+        return [way, params[v.scheme] ? valueOf(lock, 'access/adapter') : '', params, flow, issuer];
+    };
+    const kinds = ways.map(kindOf);
+    const usable = kinds.find(([, kind]) => kind !== '');
+    if (usable === undefined)
+        return said('no-adapter', { source, operation, kinds: ways.join(', ') });
+    const [scheme, kind, params, flow, issuer] = usable;
+    return { kind, scheme, params, flow, account: kind === v.anonymous ? undefined : valueOf(lock, issuer ? 'access/issuer-account' : 'access/account').split('{place}').join(place).split('{source}').join(source).split('{issuer}').join(issuer ?? '') };
+};
+export const stepOf = (lines, lock, source, operation) => {
+    const v = vocabOf(lock);
+    const offer = `${v.offers}/${source}/${operation}`;
+    const classes = fieldsOf(lines, offer)[v.class];
+    if (classes === undefined)
+        return said('unknown-operation', { source, operation });
+    const origin = originOf(lines, v, source);
+    return typeof origin !== 'string' ? origin : { kind: 'call', source, operation, origin, carry: fieldsOf(lines, `${offer}/${v.carry}`), form: fieldsOf(lines, `${offer}/${v.form}`), classes, access: { kind: v.anonymous, scheme: '', params: {}, account: undefined, flow: '' } };
+};
+/** The call an offer would make, from the place's lines alone, with the access it is proven by; or why there is none. An offer read two ways is never called. */
+const callOf = (lines, lock, source, operation, place) => {
+    const step = stepOf(lines, lock, source, operation);
+    if (step.kind === 'said')
+        return step;
+    if (step.classes.includes(vocabOf(lock).split))
+        return said('split-offer', { source, operation });
+    const access = accessOf(lines, lock, vocabOf(lock), source, operation, place);
+    return 'key' in access ? access : { ...step, access };
+};
+const isCallable = (lock, classes) => classes.length === 1 && classes[0] === vocabOf(lock).callable;
+export const planRead = (lines, lock, source, operation, place) => ((call) => (call.kind === 'call' && !isCallable(lock, call.classes) ? said('not-callable', { source, operation, class: call.classes.join(', ') }) : call))(callOf(lines, lock, source, operation, place));
+export const planAct = (lines, lock, source, operation, place) => ((call) => (call.kind === 'call' && isCallable(lock, call.classes) ? said('is-read', { source, operation }) : call))(callOf(lines, lock, source, operation, place));

package/dist/src/core/receipt.d.ts

@@ -0,0 +1,13 @@
+import type { Said } from './lock.ts';
+/** The scope a read is kept under: the source, the operation, and the first steps of the digest of the request and whom it was made as, so only the same request made as the same principal finds it again. The drafted receipt of one read names what was asked, the digest of what came back, and when; the device key signs it. */
+export declare const scopeOf: (family: string, api: string, operation: string, request: string, principal: string) => string;
+export declare const draftOf: (family: string, at: string, scope: string, digest: string, when: string) => string;
+/** What a typed answer stands on besides its body: the worlds the place uses and the code that interprets them, and what the source compiles to; what is kept under it holds only while these stand. */
+export declare const basisOf: (lines: readonly Said[], word: (scope: string) => string, source: string) => string;
+/** Head's own receipts under a scope, or under any scope below it, newest first: each once, by when it was made and what it names; a duplicate delivery is the same receipt. */
+export declare const receiptsOf: (lines: readonly Said[], at: string, scope: string, below?: boolean) => readonly {
+    readonly scope: string;
+    readonly at: string;
+    readonly digest: string;
+}[];
+export declare const spentOf: (lines: readonly Said[], family: string, at: string, api: string, now: number) => number;

package/dist/src/core/receipt.js

@@ -0,0 +1,12 @@
+import { createHash } from 'node:crypto';
+import { canonical } from '@lapxo/topos/wire';
+/** The scope a read is kept under: the source, the operation, and the first steps of the digest of the request and whom it was made as, so only the same request made as the same principal finds it again. The drafted receipt of one read names what was asked, the digest of what came back, and when; the device key signs it. */
+export const scopeOf = (family, api, operation, request, principal) => `${family}/${api}/${operation}/${createHash('sha256').update(`${request}\n${principal}`).digest('hex').slice(0, 16)}`;
+export const draftOf = (family, at, scope, digest, when) => canonical({ at: `${at}:${when}`, by: 'target', form: 'alphabet', measure: 'digest', role: 'writes', scope, value: digest });
+/** What a typed answer stands on besides its body: the worlds the place uses and the code that interprets them, and what the source compiles to; what is kept under it holds only while these stand. */
+export const basisOf = (lines, word, source) => createHash('sha256').update(lines.filter((l) => l.scope?.startsWith('uses/') || l.scope?.startsWith('dep/')
+    || l.scope === `${word('vocab/region')}/${source}` || [word('vocab/offers'), word('vocab/keys')].some((family) => l.scope?.startsWith(`${family}/${source}/`))).map((l) => canonical(l)).sort().join('\n')).digest('hex').slice(0, 16);
+/** Head's own receipts under a scope, or under any scope below it, newest first: each once, by when it was made and what it names; a duplicate delivery is the same receipt. */
+export const receiptsOf = (lines, at, scope, below = false) => [...new Map(lines.filter((l) => (l.scope === scope || (below && l.scope?.startsWith(`${scope}/`))) && l.measure === 'digest' && l.at?.startsWith(`${at}:`) && l.value?.startsWith('sha256:'))
+        .map((l) => [`${l.at} ${l.value}`, { scope: l.scope, at: l.at.slice(at.length + 1), digest: l.value }])).values()].sort((a, b) => (a.at < b.at ? 1 : a.at > b.at ? -1 : 0));
+export const spentOf = (lines, family, at, api, now) => lines.filter((l) => l.scope?.startsWith(`${family}/${api}/`) && l.at?.startsWith(`${at}:`) && now - Date.parse(l.at.slice(at.length + 1)) < 3_600_000).length;

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

@@ -0,0 +1,45 @@
+import type { Said } from './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 fill: (text: string, asked: Readonly<Record<string, string | undefined>>) => string;
+export declare const sayIn: (lock: readonly Said[]) => (key: string, fields?: Readonly<Record<string, string | undefined>>) => string;
+export declare const refusedOn: (lock: readonly Said[], platform: string) => string | undefined;
+/** A red, when what head measured ran past a ceiling of its lock in whole seconds: said with the coordinate it ran at; within it, nothing. */
+export declare const redIn: (lock: readonly Said[]) => (scope: string, coordinate: string, started: number, now: number) => readonly string[];
+/**
+ * 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;

package/dist/src/core/surface.js

@@ -0,0 +1,32 @@
+import { aboutOf, below, members, valueOf } from "./lock.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 fill = (text, asked) => Object.entries(asked).reduce((at, [name, value]) => (value === undefined ? at : at.split(`{${name}}`).join(value)), text);
+export const sayIn = (lock) => (key, fields = {}) => fill(aboutOf(lock, `said/${key}`), fields);
+export const refusedOn = (lock, platform) => ((supported) => (supported.includes(platform) ? undefined : sayIn(lock)('platform', { platform, supported: supported.join('|') })))(members(valueOf(lock, 'platform/supported')));
+/** A red, when what head measured ran past a ceiling of its lock in whole seconds: said with the coordinate it ran at; within it, nothing. */
+export const redIn = (lock) => (scope, coordinate, started, now) => ((seconds, ceiling) => (seconds > Number(ceiling.split('..')[1]) ? [sayIn(lock)('red', { coordinate, seconds: String(seconds), scope, ceiling })] : []))(Math.floor((now - started) / 1000), valueOf(lock, scope));
+/**
+ * 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)))) };
+};

package/dist/src/core/worlds.d.ts

@@ -0,0 +1,10 @@
+import type { Said } from './lock.ts';
+/** The facts bytes hold, in their order. */
+export declare const linesOf: (bytes: Uint8Array) => readonly Said[];
+/** Bytes named by their digest, under the algorithm the wire names: a pinned standing is exactly the bytes its pin hashes. */
+export declare const digestIn: (lock: readonly Said[]) => (bytes: Uint8Array | string) => string;
+/** A compiled standing as a place holds it: its pin, the digest of its bytes, and its lines; none when the place holds no such file. */
+export declare const pinnedOf: (lock: readonly Said[], bytes: Uint8Array | undefined) => {
+    readonly pin: string;
+    readonly lines: readonly Said[];
+} | undefined;

package/dist/src/core/worlds.js

@@ -0,0 +1,9 @@
+import { createHash } from 'node:crypto';
+import { parse } from '@lapxo/topos/wire';
+import { valueOf } from "./lock.js";
+/** The facts bytes hold, in their order. */
+export const linesOf = (bytes) => new TextDecoder().decode(bytes).split('\n').flatMap((line) => ((got) => (got.kind === 'fact' ? [got.value.fields] : []))(parse(line)));
+/** Bytes named by their digest, under the algorithm the wire names: a pinned standing is exactly the bytes its pin hashes. */
+export const digestIn = (lock) => (bytes) => ((algorithm) => `${algorithm}:${createHash(algorithm).update(bytes).digest('hex')}`)(valueOf(lock, 'wire/digest-algorithms'));
+/** A compiled standing as a place holds it: its pin, the digest of its bytes, and its lines; none when the place holds no such file. */
+export const pinnedOf = (lock, bytes) => (bytes === undefined ? undefined : { pin: digestIn(lock)(bytes), lines: linesOf(bytes) });

package/dist/src/flows/act.d.ts

@@ -0,0 +1,7 @@
+import type { Asked, Context } from '../core/answer.ts';
+/**
+ * One offer that is not of the class head reads: within a cap the person signed it is called as far as the cap goes;
+ * without one, each call asks the person once, and their yes is signed for exactly that request. The intent lands before
+ * the call, the receipt after; a call that never answered stays open until a look of what it would have changed closes it.
+ */
+export declare const act: (asked: Asked, context: Context) => Promise<readonly string[]>;

package/dist/src/flows/act.js

@@ -0,0 +1,43 @@
+import { actsOf, allowedOf, askedOf, cappedOf } from "../core/act.js";
+import { planAct } from "../core/read.js";
+import { draftOf } from "../core/receipt.js";
+import { sayIn } from "../core/surface.js";
+import { canonical } from '@lapxo/topos/wire';
+import { called } from "./call.js";
+/**
+ * One offer that is not of the class head reads: within a cap the person signed it is called as far as the cap goes;
+ * without one, each call asks the person once, and their yes is signed for exactly that request. The intent lands before
+ * the call, the receipt after; a call that never answered stays open until a look of what it would have changed closes it.
+ */
+export const act = (asked, context) => called(asked, context, planAct, async ({ word, say, lines, source, operation, prepared, typed, attach, send, lands, widen, uncovered }) => {
+    const [family, done] = [word('act/family'), word('act/done')];
+    const allowed = allowedOf(lines, word('allow/family'), source, operation);
+    const scope = `${family}/${source}/${operation}/${prepared.key.slice(0, 16)}`;
+    const acts = actsOf(lines, family, [done, word('act/closed')], source, operation, prepared.key);
+    if (acts.open)
+        return say('open', { source, operation, intent: scope });
+    const stopped = uncovered('head', [scope, `${scope}/${done}`]);
+    if (stopped)
+        return stopped;
+    const capped = cappedOf(lines, word('allow/family'), source, operation);
+    if (capped && acts.done >= allowed)
+        return say('not-allowed', { source, operation, allowed: String(allowed), done: String(acts.done) });
+    if (!capped || askedOf(lines, word('ask/family'), source, operation)) {
+        const yes = await widen(sayIn(context.lock)('elicit-act', { source, operation, call: prepared.describe }), [canonical({ at: 'policy:person/allows', by: 'target', form: 'alphabet', measure: 'status', role: 'writes', scope: `${word('allow/family')}/${source}/${operation}/${prepared.key.slice(0, 16)}`, value: 'present' })]);
+        if ('said' in yes)
+            return yes.said;
+    }
+    const attached = await attach();
+    if ('said' in attached)
+        return attached.said;
+    const when = () => new Date(context.now()).toISOString();
+    const intended = await lands(canonical({ at: `${word('receipt/at')}:${when()}`, by: 'target', form: 'alphabet', measure: 'status', role: 'writes', scope, value: 'present' }));
+    if ('refused' in intended)
+        return say('not-landed', { why: intended.refused });
+    const got = await send(attached.attachment);
+    if (got.kind !== 'got')
+        return say('act-failed', { source, operation, intent: scope });
+    const landed = await lands(draftOf(family, word('receipt/at'), `${scope}/${done}`, context.cache.keep(Buffer.concat([Buffer.from(`${got.status}\n`), got.bytes])), when()));
+    const answer = await typed(String(got.status), got.bytes);
+    return 'refused' in landed ? [...answer, ...say('not-landed', { why: landed.refused })] : [...answer, ...intended.lines, ...landed.lines];
+});

package/dist/src/flows/answer.d.ts

@@ -0,0 +1,12 @@
+import type { Context } from '../core/answer.ts';
+import type { Said } from '../core/lock.ts';
+/**
+ * What a source answered, as the world types it: the body is laid in the place's answers for as long as bound reads it,
+ * then taken away, and only the lines the world answers for this request come back — a value of each declared field, the
+ * counts, what it held back. A place that names no view to type it gets no answer at all, never the body.
+ */
+export declare const typedAnswer: (context: Context, place: string, lines: readonly Said[], source: string, operation: string, key: string, body: Uint8Array) => Promise<{
+    readonly lines: readonly string[];
+} | {
+    readonly untyped: string;
+}>;

package/dist/src/flows/answer.js

@@ -0,0 +1,25 @@
+import { canonical } from '@lapxo/topos/wire';
+import { valueOf } from "../core/lock.js";
+/**
+ * What a source answered, as the world types it: the body is laid in the place's answers for as long as bound reads it,
+ * then taken away, and only the lines the world answers for this request come back — a value of each declared field, the
+ * counts, what it held back. A place that names no view to type it gets no answer at all, never the body.
+ */
+export const typedAnswer = async (context, place, lines, source, operation, key, body) => {
+    const view = valueOf(context.lock, 'place/answer');
+    if (!lines.some((line) => line.scope === `view/${view}`))
+        return { untyped: '' };
+    const [request, family] = [key.slice(0, 16), valueOf(context.lock, 'vocab/answer')];
+    const at = `${valueOf(context.lock, 'place/answers')}/${source}/${encodeURIComponent(operation).replaceAll('.', '%2E')}/${request}.json`;
+    context.files.lay(place, at, body);
+    try {
+        const got = await context.world(place, view);
+        if ('refused' in got)
+            return { untyped: got.refused };
+        const mine = got.lines.filter((line) => line.scope === `${family}/${request}` || line.scope?.startsWith(`${family}/${request}/`));
+        return mine.length ? { lines: mine.map((line) => canonical(line)).sort() } : { untyped: '' };
+    }
+    finally {
+        context.files.drop(place, at);
+    }
+};

package/dist/src/flows/call.d.ts

@@ -0,0 +1,50 @@
+import type { Asked, Context, Outcome } from '../core/answer.ts';
+import type { Said } from '../core/lock.ts';
+import type { Call, Plan } from '../core/read.ts';
+import type { Attachment } from '../access/contract.ts';
+import type { Fetched, Prepared } from '../ports/adapters/request.ts';
+/**
+ * The origin of a source a person picks once for a place, when its document declares several: offered as a choice among
+ * them, none a default, and kept as the person's line; the lines a call stands on, with it.
+ */
+export declare const pickedOrigin: (context: Context, place: string, lines: readonly Said[], source: string, plan: Call | Plan) => Promise<{
+    readonly lines: readonly Said[];
+} | {
+    readonly said: readonly string[];
+}>;
+/** Calls of one place take turns, so one asked while another lands sees its receipt; nothing waits on a timer. */
+export declare const inTurn: <T>(place: string, act: () => Promise<T>) => Promise<T>;
+export interface Frame {
+    readonly say: (key: string, fields?: Readonly<Record<string, string | undefined>>) => readonly string[];
+    readonly lands: (...lot: readonly string[]) => Promise<Outcome>;
+    readonly most: (scope: string) => number;
+    readonly place: string;
+    readonly lines: readonly Said[];
+    readonly source: string;
+    readonly operation: string;
+    readonly plan: Call;
+    readonly prepared: Extract<Prepared, {
+        key: string;
+    }>;
+    readonly widen: (message: string, lot: readonly string[]) => Promise<{
+        readonly lines: readonly string[];
+    } | {
+        readonly said: readonly string[];
+    }>;
+    readonly word: (scope: string) => string;
+    readonly typed: (status: string, bytes: Uint8Array) => Promise<readonly string[]>;
+    readonly attach: () => Promise<{
+        readonly attachment: Attachment | undefined;
+        readonly principal: string | undefined;
+    } | {
+        readonly said: readonly string[];
+    }>;
+    readonly send: (attachment: Attachment | undefined) => Promise<Fetched>;
+    readonly uncovered: (role: string, scopes: readonly string[]) => readonly string[] | undefined;
+}
+/**
+ * The steps a read and an act share: the place, its turn, the lines it stands on once bound settled them, the offer's
+ * plan, the transport its origin names and the request it prepares; then what is particular, given a frame that says
+ * by the lock, attaches access when asked, types what came back and lands a line under head's key.
+ */
+export declare const called: (asked: Asked, context: Context, planOf: (lines: readonly Said[], lock: readonly Said[], source: string, operation: string, place: string) => Call | Plan, then: (frame: Frame) => Promise<readonly string[]>) => Promise<readonly string[]>;

package/dist/src/flows/call.js

@@ -0,0 +1,76 @@
+import { inPlace, placeNameOf, unless } from "../core/answer.js";
+import { fieldsOf, vocabOf } from "../core/read.js";
+import { canonical } from '@lapxo/topos/wire';
+import { sayIn } from "../core/surface.js";
+import { valueOf } from "../core/lock.js";
+import { uncoveredIn } from "../core/device.js";
+import { widening } from "./device.js";
+import { attachmentFor } from "../access/obtain.js";
+import { typedAnswer } from "./answer.js";
+import { standingFor } from "./world.js";
+/**
+ * The origin of a source a person picks once for a place, when its document declares several: offered as a choice among
+ * them, none a default, and kept as the person's line; the lines a call stands on, with it.
+ */
+export const pickedOrigin = async (context, place, lines, source, plan) => {
+    if (plan.kind !== 'said' || plan.key !== 'pick-origin')
+        return { lines };
+    const v = vocabOf(context.lock);
+    const origins = fieldsOf(lines, `${v.region}/${source}`)[v.origins] ?? [];
+    const line = (value) => ({ at: 'policy:person/picks', by: 'target', form: 'alphabet', measure: 'id', role: 'writes', scope: `${v.pick}/${source}`, value });
+    const by = widening(context, place, lines, origins.map((o) => canonical(line(o))));
+    if ('said' in by)
+        return { said: by.said };
+    const chosen = (await context.person.choose(sayIn(context.lock)('pick', { source }), [{ name: v.origin, options: origins.map((o) => ({ value: o, label: o })) }]))?.[v.origin];
+    if (chosen === undefined || !origins.includes(chosen))
+        return { said: [sayIn(context.lock)(plan.key, plan.fields)] };
+    const landed = await by.land([canonical(line(chosen))]);
+    return 'refused' in landed ? { said: [sayIn(context.lock)('not-landed', { why: landed.refused })] } : { lines: [...lines, line(chosen)] };
+};
+const turns = new Map();
+/** Calls of one place take turns, so one asked while another lands sees its receipt; nothing waits on a timer. */
+export const inTurn = (place, act) => { const next = (turns.get(place) ?? Promise.resolve()).then(act, act); turns.set(place, next.catch(() => undefined)); return next; };
+/**
+ * The steps a read and an act share: the place, its turn, the lines it stands on once bound settled them, the offer's
+ * plan, the transport its origin names and the request it prepares; then what is particular, given a frame that says
+ * by the lock, attaches access when asked, types what came back and lands a line under head's key.
+ */
+export const called = async (asked, context, planOf, then) => {
+    const say = (key, fields = {}) => [sayIn(context.lock)(key, fields)];
+    const [source, operation] = [asked['source'] ?? '', asked['operation'] ?? ''];
+    return inPlace(asked, context, (place) => inTurn(place, async () => {
+        const held = await standingFor(context, place);
+        if ('unsettled' in held)
+            return say('unsettled', { source, why: held.unsettled });
+        const widen = async (message, lot) => {
+            const by = widening(context, place, held.lines, lot);
+            if ('said' in by)
+                return { said: by.said };
+            const refused = await unless(context, message);
+            if (refused)
+                return { said: refused };
+            const landed = await by.land(lot);
+            return 'refused' in landed ? { said: say('not-landed', { why: landed.refused }) } : { lines: landed.lines };
+        };
+        const picked = await pickedOrigin(context, place, held.lines, source, planOf(held.lines, context.lock, source, operation, placeNameOf(place)));
+        if ('said' in picked)
+            return picked.said;
+        const lines = picked.lines;
+        const plan = planOf(lines, context.lock, source, operation, placeNameOf(place));
+        if (plan.kind === 'said')
+            return say(plan.key, plan.fields);
+        const prepared = ((transport) => transport?.prepare(plan, JSON.parse(asked['args'] || '{}'), context.lock))(await context.adapter(plan.origin));
+        if (prepared === undefined)
+            return say('no-transport', { source, origin: plan.origin });
+        if ('missing' in prepared)
+            return say('missing-param', { operation, param: prepared.missing });
+        if ('refused' in prepared)
+            return say(prepared.refused, { source, origin: plan.origin });
+        const most = (scope) => Number((lines.find((l) => l.scope === scope)?.value ?? '0..0').split('..')[1]);
+        const typed = async (status, bytes) => ((got) => ['lines' in got ? say('answered', { source, operation, status })[0] : say('untyped', { source, operation, status, why: got.untyped })[0], ...('lines' in got ? got.lines : [])])(await typedAnswer(context, place, lines, source, operation, prepared.key, bytes));
+        const lands = (...lot) => context.landAs(place, lot, 'head', lines);
+        const attach = async () => ((got) => ('said' in got ? { said: say(got.said, { source, operation, kinds: plan.access.kind, input: got.input }) } : got))(await attachmentFor(context, place, lines, plan));
+        const uncovered = (role, scopes) => uncoveredIn(context.lock, lines, context.device(role), place, [], scopes);
+        return then({ widen, word: (scope) => valueOf(context.lock, scope), say, place, lines, source, operation, plan, prepared, most, typed, attach, send: (attachment) => prepared.send(attachment, most('read/response-bytes')), lands, uncovered });
+    }));
+};

package/dist/src/flows/device.d.ts

@@ -0,0 +1,26 @@
+import type { Context, Outcome } from '../core/answer.ts';
+import type { Said } from '../core/lock.ts';
+/** A key of this device by its role: read from the keychain, or made there once; only its public half is ever handed on. */
+export declare const deviceKey: (context: Context, role?: string) => string | undefined;
+/** The keychain account of a place's root, when this keychain holds it — who configures the place is here; else what head says of that. */
+export declare const rootIn: (context: Context, place: string) => {
+    readonly account: string;
+} | {
+    readonly said: readonly string[];
+};
+/**
+ * Who signs a widening of a place: its root, when this keychain holds it and the place admits this device's person to
+ * witness it — the line is then the place's own policy, in its lock, binding every device it admits, and names as its
+ * witness the person who said yes, by the key the place knows them by; else this device's person key, when the place
+ * admits it for every line — an attestation only this device reads, once per scope and measure the place does not state,
+ * since a second needs a fold bound does not publish; else no one here, and the lines are handed on. A place that pins a
+ * lock as its parent has nothing signed here: what the parent would cut is bound's to judge.
+ */
+type By = {
+    readonly sign: (lot: readonly string[]) => Promise<Outcome>;
+    readonly land: (lot: readonly string[]) => Promise<Outcome>;
+};
+export declare const widening: (context: Context, place: string, lines: readonly Said[], lot: readonly string[]) => By | {
+    readonly said: readonly string[];
+};
+export {};

package/dist/src/flows/device.js

@@ -0,0 +1,37 @@
+import { placeNameOf } from "../core/answer.js";
+import { canonical, parse } from '@lapxo/topos/wire';
+import { deviceOf, idIn, uncoveredIn } from "../core/device.js";
+import { newKey, publicOf } from "../core/keys.js";
+import { members, valueOf } from "../core/lock.js";
+import { fill, sayIn } from "../core/surface.js";
+import { adoptsIn } from "../adopt/adopt.js";
+/** A key of this device by its role: read from the keychain, or made there once; only its public half is ever handed on. */
+export const deviceKey = (context, role) => ((account) => {
+    const held = context.keys.read(account);
+    const secret = held ?? ((made) => { context.keys.write(account, made.secret); return context.keys.read(account) === made.secret ? made.secret : undefined; })(newKey());
+    return secret === undefined ? undefined : publicOf(secret);
+})(deviceOf(context.lock, role).account);
+/** The keychain account of a place's root, when this keychain holds it — who configures the place is here; else what head says of that. */
+export const rootIn = (context, place) => ((account) => (context.keys.read(account) === undefined ? { said: [sayIn(context.lock)('no-root', { place })] } : { account }))(fill(valueOf(context.lock, 'founding/root-account'), { place: placeNameOf(place) }));
+export const widening = (context, place, lines, lot) => {
+    const parent = adoptsIn(context.lock, lines);
+    if (parent !== undefined)
+        return { said: [sayIn(context.lock)('parent-lock', { place, parent })] };
+    const [root, witness, field] = [rootIn(context, place), idIn(lines, context.device('person')), valueOf(context.lock, 'widening/witness')];
+    const wire = lines.filter((l) => l.scope === 'wire/fields');
+    const witnessed = (signed) => signed.map((line) => ((got) => (got.kind === 'fact' ? canonical({ ...got.value.fields, [field]: witness }) : line))(parse(line)));
+    if ('account' in root && witness !== undefined) {
+        if (wire.some((l) => members(l.value ?? '').includes(field)))
+            return { sign: (signed) => context.signRoot(place, witnessed(signed), root.account), land: (signed) => context.landRoot(place, witnessed(signed), root.account) };
+        if (lot.every((line) => / scope=wire\/fields /.test(line)))
+            return { sign: (signed) => context.signRoot(place, signed, root.account), land: (signed) => context.landRoot(place, signed, root.account) };
+        const [named, bare] = [[...new Set([...wire.flatMap((l) => members(l.value ?? '')), field])].join('|'), (l) => Object.fromEntries(Object.entries(l).filter(([k]) => !['sig', 'epoch'].includes(k)))];
+        return { said: [sayIn(context.lock)('unwitnessed', { place }), ...wire.map((l) => canonical({ ...bare(l), by: 'target', value: 'withdraw' })),
+                canonical({ at: `policy:head/wire/${new Date(context.now()).toISOString()}`, by: 'target', form: 'alphabet', measure: 'id', role: 'reads', scope: 'wire/fields', value: named })] };
+    }
+    const stopped = uncoveredIn(context.lock, lines, context.device('person'), place, lot);
+    if (stopped)
+        return { said: stopped };
+    const again = lot.flatMap((line) => ((got) => (got.kind === 'fact' && lines.some((l) => l.scope === got.value.fields.scope && l.measure === got.value.fields.measure) ? [got.value.fields.scope ?? ''] : []))(parse(line)))[0];
+    return again !== undefined ? { said: [sayIn(context.lock)('attested-again', { place, scope: again })] } : { sign: (signed) => context.signAs(place, signed, 'person', lines), land: (signed) => context.landAs(place, signed, 'person', lines) };
+};

package/dist/src/flows/plan.d.ts

@@ -0,0 +1,8 @@
+import type { Asked, Context } from '../core/answer.ts';
+/**
+ * A proposal the person signs: drafted lines shown to the person with the place and the base they are made against; on
+ * their yes to exactly those, signed by their key; what bound prints folding it as if landed comes back as it printed it. Nothing lands; the lot is kept by its digest.
+ */
+export declare const planLot: (asked: Asked, context: Context) => Promise<readonly string[]>;
+/** A planned lot landed by its digest, only while the place stands on the base it was planned against. */
+export declare const landLot: (asked: Asked, context: Context) => Promise<readonly string[]>;

package/dist/src/flows/plan.js

@@ -0,0 +1,51 @@
+import { baseOf, inPlace, standingOr } from "../core/answer.js";
+import { sayIn } from "../core/surface.js";
+import { widening } from "./device.js";
+import { parse } from '@lapxo/topos/wire';
+/**
+ * A proposal the person signs: drafted lines shown to the person with the place and the base they are made against; on
+ * their yes to exactly those, signed by their key; what bound prints folding it as if landed comes back as it printed it. Nothing lands; the lot is kept by its digest.
+ */
+export const planLot = (asked, context) => inPlace(asked, context, async (place) => {
+    const say = sayIn(context.lock);
+    const lot = (asked['lines'] ?? '').split('\n').filter(Boolean);
+    if (!lot.length || lot.some((line) => ((got) => got.kind !== 'fact' || got.value.fields['sig'] !== undefined || got.value.fields['by'] !== 'target')(parse(line))))
+        return [say('bad-lot')];
+    const held = await standingOr(context, place);
+    if ('said' in held)
+        return held.said;
+    const base = baseOf(held.lines);
+    const by = widening(context, place, held.lines, lot);
+    if ('said' in by)
+        return by.said;
+    const consent = await context.elicit(say('elicit', { count: String(lot.length), place, base, lines: lot.join('\n') }));
+    if (consent === 'none')
+        return [say('sign-yourself', { place }), ...lot];
+    if (consent === 'no')
+        return [say('no-yes')];
+    const signed = await by.sign(lot);
+    if ('refused' in signed)
+        return [signed.refused];
+    const now = await standingOr(context, place);
+    if ('said' in now)
+        return now.said;
+    if (baseOf(now.lines) !== base)
+        return [say('base-moved', { base })];
+    const kept = context.cache.keep(Buffer.from(JSON.stringify({ place, base, signed: signed.lines })));
+    return [say('planned', { lot: kept, base }), ...(await context.told(place, signed.lines))];
+});
+/** A planned lot landed by its digest, only while the place stands on the base it was planned against. */
+export const landLot = async (asked, context) => {
+    const say = sayIn(context.lock);
+    const bytes = context.cache.held(asked['lot'] ?? '');
+    if (bytes === undefined)
+        return [say('no-lot', { lot: asked['lot'] ?? '' })];
+    const kept = JSON.parse(Buffer.from(bytes).toString('utf8'));
+    const now = await standingOr(context, kept.place);
+    if ('said' in now)
+        return now.said;
+    if (baseOf(now.lines) !== kept.base)
+        return [say('base-moved', { base: kept.base })];
+    const landed = await context.land(kept.place, kept.signed);
+    return 'refused' in landed ? [landed.refused] : [say('landed', { count: String(landed.lines.length) }), ...landed.lines];
+};

package/dist/src/flows/read.d.ts

@@ -0,0 +1,9 @@
+import type { Asked, Context } from '../core/answer.ts';
+/**
+ * A read of one offer the place declares of the class head reads: the response comes back once, typed by the world,
+ * and both are kept — the body's digest and the typed answer's, receipts the device key signs. Asked again as the same
+ * principal, while the place stands on what typed it, the person's grant holds now and the newest read is younger than
+ * the reuse the place allows, it answers from what was kept: nothing called. Asked for history, it shows what was kept
+ * of that request as of when it was read — evidence of that read, never a current answer — where the place allows it.
+ */
+export declare const readSource: (asked: Asked, context: Context) => Promise<readonly string[]>;