@lapxo/head 0.1.4 → 0.1.6

package/dist/src/ahead/budget.d.ts

@@ -0,0 +1,6 @@
+import type { Asked } from '../core/answer.ts';
+import type { Said } from '../core/lock.ts';
+/** Whether a read would spend past what the place allows: a question, past the place's rate; a read ahead, past the share of what the questions leave of it that reads ahead may spend. A read ahead is told by the mark beside its receipt, and counted once. */
+export declare const overOf: (lines: readonly Said[], [family, at, mark]: readonly [string, string, string], source: string, now: number, rate: number, share: number, asked: Asked) => boolean;
+/** The mark a read made ahead lands beside its receipt, under the receipt's own at, so what reads ahead spent is counted apart from what questions spent. */
+export declare const markOf: (asked: Asked, [at, mark]: readonly [string, string], scope: string, digest: string, when: string) => readonly string[];

package/dist/src/ahead/budget.js

@@ -0,0 +1,11 @@
+import { canonical } from '@lapxo/topos/wire';
+import { spentOf } from "../core/receipt.js";
+const early = (asked) => asked['ahead'] === 'true';
+/** Whether a read would spend past what the place allows: a question, past the place's rate; a read ahead, past the share of what the questions leave of it that reads ahead may spend. A read ahead is told by the mark beside its receipt, and counted once. */
+export const overOf = (lines, [family, at, mark], source, now, rate, share, asked) => {
+    const ahead = lines.filter((l) => l.scope?.startsWith(`${family}/${source}/`) && l.scope.endsWith(`/${mark}`) && l.at?.startsWith(`${at}:`) && now - Date.parse(l.at.slice(at.length + 1)) < 3_600_000).length;
+    const calls = spentOf(lines, family, at, source, now) - ahead;
+    return calls >= rate || (early(asked) && ahead + 1 > ((rate - (calls - ahead)) * share) / 100);
+};
+/** The mark a read made ahead lands beside its receipt, under the receipt's own at, so what reads ahead spent is counted apart from what questions spent. */
+export const markOf = (asked, [at, mark], scope, digest, when) => early(asked) ? [canonical({ at: `${at}:${when}`, by: 'target', form: 'alphabet', measure: 'digest', role: 'writes', scope: `${scope}/${mark}`, value: digest })] : [];

package/dist/src/ahead/fold.d.ts

@@ -0,0 +1,2 @@
+/** A refused identity cannot validate an old answer. The reader binds new text to the expected identity. */
+export declare const folded: <T>(kind: string, place: string, identity: () => Promise<string | undefined>, read: (expected?: string) => Promise<T>) => Promise<T>;

package/dist/src/ahead/fold.js

@@ -0,0 +1,19 @@
+/** Cached projections are indexed only by identities returned by the instrument. */
+const kept = new Map();
+/** A refused identity cannot validate an old answer. The reader binds new text to the expected identity. */
+export const folded = async (kind, place, identity, read) => {
+    const key = `${kind}\0${place}`, current = await identity(), held = kept.get(key);
+    if (current === undefined) {
+        kept.delete(key);
+        return read();
+    }
+    if (held?.identity === current)
+        return held.folded;
+    const reading = read(current);
+    kept.set(key, { identity: current, folded: reading });
+    const forget = () => { if (kept.get(key)?.folded === reading)
+        kept.delete(key); };
+    reading.then((result) => { if (result && typeof result === 'object' && 'refused' in result)
+        forget(); }, forget);
+    return reading;
+};

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

@@ -0,0 +1,10 @@
+import type { Context } from '../core/answer.ts';
+import type { Cell } from '../ports/surface.ts';
+/**
+ * What an answer leaves to do before the next call, done after it is answered; another call coming gives up what is not
+ * begun, never what is, so no land is cut halfway:
+ * the reads a known next asks for, read in a context that asks the person nothing — a read only, never an act, nothing it
+ * would need a yes or a secret for — and then every place the answer names folded again where it moved, so the next
+ * question finds it folded. A fold calls no source, so it spends nothing of a place's rate.
+ */
+export declare const readAhead: (cells: readonly Cell[], context: Context, signal: AbortSignal) => Promise<void>;

package/dist/src/ahead/read.js

@@ -0,0 +1,18 @@
+import { readSource } from "../flows/read.js";
+const none = async () => 'none', nothing = async () => undefined;
+/**
+ * What an answer leaves to do before the next call, done after it is answered; another call coming gives up what is not
+ * begun, never what is, so no land is cut halfway:
+ * the reads a known next asks for, read in a context that asks the person nothing — a read only, never an act, nothing it
+ * would need a yes or a secret for — and then every place the answer names folded again where it moved, so the next
+ * question finds it folded. A fold calls no source, so it spends nothing of a place's rate.
+ */
+export const readAhead = async (cells, context, signal) => {
+    const quiet = { ...context, elicit: none, person: { consent: none, enter: nothing, choose: nothing, visit: nothing } };
+    for (const { next } of cells)
+        if (!signal.aborted && 'tool' in next && next.tool === 'ask' && next.args['source'] && next.args['operation'] && !next.args['why'] && !next.args['history'])
+            await readSource({ ...next.args, ahead: 'true' }, quiet);
+    await quiet.settle();
+    for (const place of new Set(cells.flatMap((c) => [c.fields['place'] ?? '', 'tool' in c.next ? c.next.args['place'] ?? '' : '']).filter((p) => p && !signal.aborted)))
+        await Promise.all([context.standing(place), context.policy(place)]).catch(() => undefined);
+};

package/dist/src/answers/answered.d.ts

@@ -0,0 +1,4 @@
+import type { Asked, Context } from '../core/answer.ts';
+import type { Frame } from '../flows/call.ts';
+/** Distinguish an empty response from missing transport bytes; only the latter leaves a named need. */
+export declare const answering: (context: Context, place: string, asked: Asked, frame: Frame) => Frame;

package/dist/src/answers/answered.js

@@ -0,0 +1,22 @@
+import { canonical } from '@lapxo/topos/wire';
+import { valueOf } from "../core/lock.js";
+import { rootIn } from "../flows/device.js";
+/** A body that answers nothing: no byte of it, or a list with no member. */
+const nothing = (bytes) => ((text) => text === '' || /^\[\s*\]$/.test(text))(new TextDecoder().decode(bytes).trim());
+/** Distinguish an empty response from missing transport bytes; only the latter leaves a named need. */
+export const answering = (context, place, asked, frame) => {
+    const need = `${valueOf(context.lock, 'place/needs')}/bytes/${frame.source}/${frame.operation}`, held = frame.lines.find((l) => l.scope === need && l.role === 'demands' && l.value !== 'withdraw');
+    const owe = (line) => ((root) => ('said' in root ? undefined : context.landRoot(place, [line], root.account)))(rootIn(context, place));
+    const withdrawn = ({ about: _about, sig: _sig, epoch: _epoch, ...l }) => canonical({ ...l, by: 'target', value: 'withdraw' });
+    return { ...frame,
+        typed: (status, bytes) => (nothing(bytes) ? Promise.resolve(frame.say('answered-nothing', { source: frame.source, operation: frame.operation, status, at: new Date(context.now()).toISOString() })) : frame.typed(status, bytes)),
+        send: async (attachment) => {
+            const got = await frame.send(attachment);
+            if (asked['ahead'] !== 'true' && got.kind === 'failed' && held === undefined)
+                await owe(canonical({ at: `policy:head/owed/${new Date(context.now()).toISOString()}`, by: 'target', form: 'alphabet', measure: 'id', role: 'demands', scope: need, value: frame.plan.origin }));
+            if (got.kind === 'got' && held !== undefined)
+                await owe(withdrawn(held));
+            return got;
+        },
+    };
+};

package/dist/src/claims/claim.d.ts

@@ -0,0 +1,9 @@
+import { type Asked, type Context } from '../core/answer.ts';
+/**
+ * What the person states, kept as theirs: a line their own key attests, their words exactly as given, in the place named;
+ * asked once a conversation whether what they state there is kept, and each statement said back as it goes in, so they see
+ * it, with who carried it here as the client says it is. Taken back by the same words: what a person attests is evidence, and
+ * stands for good, so taking it back is attesting that, beside it. A place whose lines admit no carrier is handed the line that does.
+ * Only this action keeps one, never a cell, an answer or a read ahead, so nothing the model concluded becomes the person's.
+ */
+export declare const claimed: (asked: Asked, context: Context) => Promise<readonly string[]>;

package/dist/src/claims/claim.js

@@ -0,0 +1,40 @@
+import { createHash } from 'node:crypto';
+import { canonical } from '@lapxo/topos/wire';
+import { inPlace, standingOr, unless } from "../core/answer.js";
+import { uncoveredIn } from "../core/device.js";
+import { aboutOf, members, valueOf } from "../core/lock.js";
+import { fill, sayIn } from "../core/surface.js";
+/** Whether the person said, in this conversation, that what they state in a place is kept as theirs: asked once a place, a no kept as a yes is. */
+const answered = new Map();
+/**
+ * What the person states, kept as theirs: a line their own key attests, their words exactly as given, in the place named;
+ * asked once a conversation whether what they state there is kept, and each statement said back as it goes in, so they see
+ * it, with who carried it here as the client says it is. Taken back by the same words: what a person attests is evidence, and
+ * stands for good, so taking it back is attesting that, beside it. A place whose lines admit no carrier is handed the line that does.
+ * Only this action keeps one, never a cell, an answer or a read ahead, so nothing the model concluded becomes the person's.
+ */
+export const claimed = (asked, context) => inPlace(asked, context, async (place) => {
+    const [say, word, said, held] = [sayIn(context.lock), (k) => valueOf(context.lock, k), (asked['said'] ?? '').trim(), await standingOr(context, place)];
+    if ('said' in held)
+        return held.said;
+    if (!said)
+        return [say('missing-param', { operation: 'claim', param: 'said' })];
+    const [family, withdraw, back] = [`${word('claim/family')}/${createHash('sha256').update(said).digest('hex').slice(0, 16)}`, asked['withdraw'] === 'true', word('claim/withdrawn')];
+    const standing = held.lines.filter((l) => l.scope?.startsWith(`${family}/`) && !l.scope.endsWith(`/${back}`) && !held.lines.some((w) => w.scope === `${l.scope}/${back}`)).map((l) => l.scope);
+    if (withdraw && !standing.length)
+        return [say('claim-none', { place, said })];
+    const wire = held.lines.find((l) => l.scope === 'wire/fields'), via = word('claim/via');
+    const bare = wire && Object.fromEntries(Object.entries(wire).filter(([k]) => !['sig', 'epoch', 'about'].includes(k)));
+    if (bare && !members(wire.value ?? '').includes(via))
+        return [say('claims-unadmitted', { place, lines: [canonical({ ...bare, by: 'target', value: 'withdraw' }), canonical({ ...bare, by: 'target', at: `policy:head/wire/${new Date(context.now()).toISOString()}`, value: `${wire.value}|${via}` })].join('\n') })];
+    const line = (scope) => canonical({ about: said, at: word('claim/at'), by: 'target', form: 'alphabet', measure: 'text', role: 'writes', scope, value: 'lock', [via]: context.client() ?? word('claim/via-unknown') });
+    const lot = withdraw ? standing.map((scope) => line(`${scope}/${back}`)) : [line(`${family}/${new Date(context.now()).toISOString().replace(/\D/g, '')}`)], outside = uncoveredIn(context.lock, held.lines, context.device('person'), place, lot);
+    if (outside)
+        return outside;
+    if (!withdraw && !answered.has(place))
+        answered.set(place, (await unless(context, fill(aboutOf(context.lock, 'said/elicit-claims'), { place }))) === undefined);
+    if (!withdraw && !answered.get(place))
+        return [say('claims-declined', { place, said })];
+    const landed = await context.landAs(place, lot, 'person', held.lines);
+    return 'refused' in landed ? [say('not-landed', { why: landed.refused })] : [say(withdraw ? 'unclaimed' : 'claimed', { place, said }), ...landed.lines];
+});

package/dist/src/compile/pin.js

@@ -4,11 +4,7 @@ import { members, under, valueOf } from "../core/lock.js";
 import { fieldsOf, vocabOf } from "../core/read.js";
 import { sayIn } from "../core/surface.js";
 import { digestIn, linesOf, pinnedOf } from "../core/worlds.js";
-/**
- * One compile, by the fold: the place view asked once, this source's lines kept with a region of its own — and the flow
- * of each issuer the source declares, so a flow is pinned once, by whoever declares it — and the standing bound selects
- * from them pinned and laid where its input names it.
- */
+/** Pin the compiled source and adopt only the declared outputs. */
 const compiledOf = async (context, place, source, file) => {
     const say = sayIn(context.lock), v = vocabOf(context.lock);
     const compiled = await context.world(place, valueOf(context.lock, 'place/view'));
@@ -53,7 +49,7 @@ export const pinIn = (context, place, lands, line) => async (source, read) => {
     if ('said' in pinned || (old?.needs === file && old.value === pinned.pin))
         return pinned;
     const withdraw = old === undefined ? [] : [canonical({ ...Object.fromEntries(Object.entries(old).filter(([k]) => !['sig', 'epoch'].includes(k))), by: 'target', value: 'withdraw' })];
-    const landed = await lands([...withdraw, line(`uses/${source}`, 'digest', pinned.pin, { needs: file, at: `policy:head/connect/${new Date(context.now()).toISOString()}` })]);
+    const landed = await lands([...withdraw, line(`uses/${source}`, 'digest', pinned.pin, { needs: file, at: `policy:person/connect/${new Date(context.now()).toISOString()}` })]);
     return 'refused' in landed ? { said: [say('not-landed', { why: landed.refused })] } : pinned;
 };
 /**

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

@@ -15,6 +15,7 @@ export interface Context {
     readonly lock: readonly Said[];
     readonly bound: (cwd: string, args: readonly string[]) => Promise<Printed | undefined>;
     readonly roots: () => Promise<readonly string[]>;
+    readonly client: () => string | undefined;
     readonly keys: KeyStore;
     readonly device: (role: string) => string | undefined;
     readonly standing: (place: string) => Promise<{

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

@@ -5,10 +5,7 @@ export interface Device {
     readonly signer: string;
 }
 export declare const deviceOf: (lock: readonly Said[], role?: string) => Device;
-/**
- * The drafted lines a place signs to admit a key: each device/<role>/<measure> line of head-s lock, said of keys/<id>, and
- * its public half. The id is the role's own unless whoever admits names it; so is the coverage, unless they give it.
- */
+/** Derive device authority from the admitted lock. */
 export declare const admissionOf: (lock: readonly Said[], publicKey: string, role?: string, as?: {
     readonly id?: string;
     readonly coverage?: string;

package/dist/src/core/device.js

@@ -3,14 +3,11 @@ import { members, said, valueOf } from "./lock.js";
 import { sayIn } from "./surface.js";
 const HEAD = 'head';
 export const deviceOf = (lock, role = HEAD) => ({ account: valueOf(lock, `device/${role}/account`), service: valueOf(lock, 'device/service'), signer: valueOf(lock, `device/${role}/signer`) });
-/**
- * The drafted lines a place signs to admit a key: each device/<role>/<measure> line of head-s lock, said of keys/<id>, and
- * its public half. The id is the role's own unless whoever admits names it; so is the coverage, unless they give it.
- */
+/** Derive device authority from the admitted lock. */
 export const admissionOf = (lock, publicKey, role = HEAD, as = {}) => ((id, at) => [
     ...['class', 'coverage', 'resolution', 'signer'].flatMap((measure) => ((line) => (line === undefined ? [] : [canonical({ at, by: 'target', form: line.form ?? 'alphabet', measure, role: 'writes', scope: `keys/${id}`, value: measure === 'coverage' && as.coverage ? as.coverage : line.value ?? '' })]))(said(lock, `device/${role}/${measure}`))),
     canonical({ at, by: 'target', form: 'alphabet', measure: 'public-key', role: 'writes', scope: `keys/${id}`, value: publicKey }),
-])(as.id ?? valueOf(lock, `device/${role}/account`), as.at ?? 'policy:head/device');
+])(as.id ?? valueOf(lock, `device/${role}/account`), as.at ?? 'policy:person/device');
 export const algorithmOf = (lines) => ((era) => (lines.find((l) => l.scope === 'wire/signature-algorithms')?.value ?? '').split('|').find((one) => one.endsWith(`:${era}`)) ?? '')(valueOf(lines, 'wire/era'));
 /** The id a place admits a public key under, as its own lines say: a key is who the place says it is, and a key it never admitted is no one there. */
 export const idIn = (lines, publicKey) => publicKey === undefined ? undefined : lines.find((l) => l.scope?.startsWith('keys/') && l.measure === 'public-key' && l.value === publicKey)?.scope.slice('keys/'.length);

package/dist/src/core/package.js

@@ -5,6 +5,7 @@ import { members, under, valueOf } from "./lock.js";
 import { fieldsOf, vocabOf } from "./read.js";
 import { sayIn } from "./surface.js";
 import { digestIn, linesOf } from "./worlds.js";
+import { linkOf } from "../links/link.js";
 /** A line no package carries: one that is not a world, or a source's document, overlay or pin, said once by digest — with, beside a digest that names bytes, the encrypted address they are read at. */
 export const foreignIn = (lines) => lines.find((l) => !/^(sources\/[a-z0-9-]+(\/overlay)?|uses\/[a-z0-9-]+)$/.test(l.scope ?? '') || lines.some((o) => o !== l && o.scope === l.scope && o.measure === l.measure)
     || (l.measure !== 'digest' && !(l.measure === 'id' && URL.canParse(l.value ?? '') && lines.some((o) => o.scope === l.scope && o.measure === 'digest' && o.needs))));
@@ -27,13 +28,13 @@ export const shared = (asked, context) => inPlace(asked, context, async (place)
         return [say('share-to', { place, to })];
     if ('said' in held)
         return held.said;
-    const pack = packed(context, place, held.lines, ((u) => (u && typeof u === 'object' ? u : {}))((() => { try {
+    const urls = ((u) => (u && typeof u === 'object' ? u : {}))((() => { try {
         return JSON.parse(asked['urls'] || '{}');
     }
     catch {
         return {};
-    } })())), bytes = new TextEncoder().encode(`${pack.lines.join('\n')}\n`);
-    return !pack.names.length ? [say('share-none', { place })] : ([...pack.files, [LOCK, bytes]].forEach(([at, laid]) => context.files.lay(to, at, laid)), [say('shared', { place, to, sources: pack.names.join(', '), digest: digestIn(context.lock)(bytes) }), ...pack.lines]);
+    } })()), pack = packed(context, place, held.lines, urls), bytes = new TextEncoder().encode(`${pack.lines.join('\n')}\n`);
+    return !pack.names.length ? [say('share-none', { place })] : ([...pack.files, [LOCK, bytes]].forEach(([at, laid]) => context.files.lay(to, at, laid)), [say('shared', { place, to, sources: pack.names.join(', '), digest: digestIn(context.lock)(bytes) }), ...linkOf(context, to, pack.lines, urls), ...pack.lines]);
 });
 /** What a package names, checked whole before anything is asked: every line a world or a source's document, overlay or pin, by digest; each world the one this head pins; an order its pins rest in. A source whose bytes did not arrive, or did not hash to their line, is open, and so is every source resting on it: absence is not a refusal, and the rest arrives. */
 export const unpacked = (context, document, bytes, read) => {

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

@@ -1,7 +1,3 @@
 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.
- */
+/** Run one action within its declared authority, with the person's approval when required. */
 export declare const act: (asked: Asked, context: Context) => Promise<readonly string[]>;

package/dist/src/flows/act.js

@@ -4,11 +4,7 @@ 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.
- */
+/** Run one action within its declared authority, with the person's approval when required. */
 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);

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

@@ -3,10 +3,7 @@ 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.
- */
+/** Ask for one declared origin when the source offers several. */
 export declare const pickedOrigin: (context: Context, place: string, lines: readonly Said[], source: string, plan: Call | Plan) => Promise<{
     readonly lines: readonly Said[];
 } | {
@@ -40,9 +37,5 @@ export interface Frame {
     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, 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.
- */
+/** Prepare one call, authorize its access and pass its frame to the read or action flow. */
 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

@@ -5,13 +5,12 @@ import { sayIn } from "../core/surface.js";
 import { valueOf } from "../core/lock.js";
 import { uncoveredIn } from "../core/device.js";
 import { widening } from "./device.js";
+import { namedIn } from "../use/named.js";
+import { answering } from "../answers/answered.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.
- */
+/** Ask for one declared origin when the source offers several. */
 export const pickedOrigin = async (context, place, lines, source, plan) => {
     if (plan.kind !== 'said' || plan.key !== 'pick-origin')
         return { lines };
@@ -27,18 +26,18 @@ export const pickedOrigin = async (context, place, lines, source, plan) => {
     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)] };
 };
-/**
- * The steps a read and an act share: the place, 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.
- */
+/** Prepare one call, authorize its access and pass its frame to the read or action flow. */
 export const called = async (asked, context, planOf, then) => {
     const say = (key, fields = {}) => [sayIn(context.lock)(key, fields)];
-    const [source, operation] = [asked['source'] ?? '', asked['operation'] ?? ''];
+    const source = asked['source'] ?? '';
     return inPlace(asked, context, async (place) => {
         const held = await standingFor(context, place);
         if ('unsettled' in held)
             return say('unsettled', { source, why: held.unsettled });
+        const named = await namedIn(context, held.lines, source, asked['operation'] ?? '', asked['ahead'] === 'true');
+        if ('said' in named)
+            return named.said;
+        const operation = named.operation;
         const widen = async (message, lot) => {
             const by = widening(context, place, held.lines, lot);
             if ('said' in by)
@@ -64,10 +63,11 @@ export const called = async (asked, context, planOf, then) => {
         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 typed = async (status, bytes) => ((got, at) => ['lines' in got ? say('answered', { source, operation, status, at })[0] : say('untyped', { source, operation, status, at, why: got.untyped })[0], ...('lines' in got ? got.lines : [])])(await typedAnswer(context, place, lines, source, operation, prepared.key, bytes), new Date(context.now()).toISOString());
         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 });
+        let use = named.use !== undefined && uncovered('head', [named.scope]) === undefined ? [named.use] : [];
+        const lands = (...lot) => { const once = use; use = []; return context.landAs(place, [...once, ...lot], 'head', lines).then((out) => ('lines' in out ? { lines: out.lines.filter((l) => !l.includes(` scope=${valueOf(context.lock, 'use/family')}/`)) } : out)); };
+        return then(answering(context, place, asked, { 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/read.d.ts

@@ -1,9 +1,3 @@
 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.
- */
+/** Read one permitted offer, reuse only under its policy and land the signed receipt. */
 export declare const readSource: (asked: Asked, context: Context) => Promise<readonly string[]>;

package/dist/src/flows/read.js

@@ -1,6 +1,6 @@
 import { under } from "../core/lock.js";
 import { observedAt, planRead } from "../core/read.js";
-import { basisOf, draftOf, receiptsOf, scopeOf, spentOf } from "../core/receipt.js";
+import { basisOf, draftOf, receiptsOf, scopeOf } from "../core/receipt.js";
 import { redIn, sayIn } from "../core/surface.js";
 import { grantedOf, isOpen, untilOf } from "../core/act.js";
 import { canonical } from '@lapxo/topos/wire';
@@ -8,6 +8,8 @@ import { called } from "./call.js";
 import { principalOf } from "../access/obtain.js";
 import { jsonOf } from "../access/contract.js";
 import { refusedAccess } from "../sources/refused.js";
+import { hand, keptOf } from "../kept/kept.js";
+import { markOf, overOf } from "../ahead/budget.js";
 /** An intent an earlier act left open, closed by the read that looked at what it would have changed: a line naming that read-s digest, signed by head. */
 const closeWith = async (intent, source, digest, { word, lines, lands }, context) => {
     const say = sayIn(context.lock);
@@ -18,19 +20,13 @@ const closeWith = async (intent, source, digest, { word, lines, lands }, context
     const landed = await lands(draftOf('', word('receipt/at'), `${intent}/${word('act/closed')}`, digest, new Date(context.now()).toISOString()));
     return 'refused' in landed ? [say('not-landed', { why: landed.refused })] : [...landed.lines, say('closed', { intent, digest })];
 };
-/**
- * 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.
- */
+/** Read one permitted offer, reuse only under its policy and land the signed receipt. */
 export const readSource = (asked, context) => called(asked, context, planRead, async ({ word, say, place, lines, source, operation, plan, prepared, most, typed, attach, send, lands, widen, uncovered }) => {
     const [family, at, when] = [word('receipt/family'), word('receipt/at'), new Date(context.now()).toISOString()];
     const closing = (digest) => closeWith(asked['closes'], source, digest, { word, lines, lands }, context);
     const scopes = (principal) => [scopeOf(family, source, operation, prepared.key, principal), `${scopeOf(word('receipt/kept'), source, operation, prepared.key, principal)}/${basisOf(lines, word, source)}`];
     const held = (digest) => ((bytes) => (bytes === undefined || digest === undefined ? undefined : { digest, bytes }))(digest === undefined ? undefined : context.cache.held(digest));
-    const keeping = (kept, answer) => (answer.length > 1 ? [draftOf(word('receipt/kept'), at, kept, context.cache.keep(Buffer.from(answer.join('\n'))), when)] : []);
+    const keeping = (kept, answer) => (answer.length > 1 ? [draftOf(word('receipt/kept'), at, kept, (asked['ahead'] === 'true' ? String : hand)(context.cache.keep(Buffer.from(answer.join('\n')))), when)] : []);
     const allowed = (key, measure) => (lines.find((l) => l.scope === `${word(key)}/${source}` && l.measure === measure) ?? lines.find((l) => l.scope === word(key) && l.measure === measure))?.value;
     if (asked['why'] === 'true') {
         const asOf = principalOf(context, plan, false), [newest] = asOf === undefined ? [] : receiptsOf(lines, at, scopes(asOf)[0]), pin = lines.find((l) => l.scope === `uses/${source}`);
@@ -54,38 +50,37 @@ export const readSource = (asked, context) => called(asked, context, planRead, a
     if (stopped)
         return stopped;
     if (!grantedOf(lines, word('grant/family'), source, context.now())) {
+        if (asked['ahead'] === 'true')
+            return [];
         const sources = [...new Set(lines.filter((l) => l.scope?.startsWith(`${word('vocab/region')}/`) && l.measure === word('vocab/origins')).map((l) => l.scope.split('/')[1]))].sort();
         const until = untilOf(word('access/period'), context.now());
-        const line = (measure, value) => canonical({ at: 'policy:person/grants', by: 'target', form: 'alphabet', measure, role: 'writes', scope: word('grant/family'), value });
-        const granted = await widen(say('grant', { sources: sources.join(', '), place, until })[0], [line('sources', sources.join('|')), line('until', until)]);
+        const line = (measure, value) => canonical({ at: `policy:person/grants/${new Date(context.now()).toISOString()}`, by: 'target', form: 'alphabet', measure, role: 'writes', scope: word('grant/family'), value });
+        const before = [...new Set(lines.filter((l) => l.scope === word('grant/family')).map(({ about: _about, sig: _sig, epoch: _epoch, ...l }) => canonical({ ...l, by: 'target', value: 'withdraw' })))];
+        const granted = await widen(say('grant', { sources: sources.join(', '), place, until })[0], [...before, line('sources', sources.join('|')), line('until', until)]);
         if ('said' in granted)
             return granted.said;
     }
-    const reuse = Number(/^\d+\.\.(\d+)$/.exec(allowed('reuse/family', 'seconds') ?? '')?.[1] ?? Number.NaN);
-    const [newest] = principal === undefined ? [] : receiptsOf(lines, at, scopes(principal)[0]), stood = ((b) => b !== undefined && Number(Buffer.from(b.bytes.subarray(0, b.bytes.indexOf(10))).toString('utf8')) < 300)(held(newest?.digest));
-    if (principal !== undefined && newest !== undefined && stood && context.now() - Date.parse(newest.at) <= reuse * 1000) {
-        const [scope, kept] = scopes(principal);
-        const answered = held(receiptsOf(lines, at, kept).find((k) => k.at >= newest.at)?.digest);
-        if (answered !== undefined)
-            return [...new TextDecoder().decode(answered.bytes).split('\n'), ...say('reused', { scope: kept, digest: answered.digest, at: newest.at }), ...(await closing(newest.digest)), ...redIn(context.lock)('answer/kept', `answer/${source}/${operation}`, context.begun, context.machine())];
-        const body = held(newest.digest);
-        if (body !== undefined) {
-            const cut = body.bytes.indexOf(10);
-            const answer = await typed(Buffer.from(body.bytes.subarray(0, cut)).toString('utf8'), body.bytes.subarray(cut + 1));
-            const keptLines = keeping(kept, answer);
-            const landed = keptLines.length ? await lands(...keptLines) : { lines: [] };
-            return [...answer, ...say('reread', { scope, digest: body.digest, at: newest.at }), ...('lines' in landed ? landed.lines : []), ...(await closing(body.digest))];
-        }
+    const was = principal === undefined ? undefined : keptOf(lines, at, scopes(principal), grantedOf(lines, word('grant/family'), source, context.now()), allowed('reuse/family', 'seconds'), context.now(), held);
+    if (was?.kind === 'kept')
+        return [...(was.bytes ? [...new TextDecoder().decode(was.bytes).split('\n'), ...say('reused', { scope: scopes(principal)[1], digest: hand(was.digest), at: was.at, receipt: was.receipt })] : say('kept', { source, operation, at: was.at, digest: was.digest, receipt: was.receipt })),
+            ...(await closing(was.receipt)), ...redIn(context.lock)('answer/kept', `answer/${source}/${operation}`, context.begun, context.machine())];
+    if (was?.kind === 'reread') {
+        const answer = await typed(Buffer.from(was.bytes.subarray(0, was.bytes.indexOf(10))).toString('utf8'), was.bytes.subarray(was.bytes.indexOf(10) + 1)), keptLines = keeping(scopes(principal)[1], answer);
+        const landed = keptLines.length ? await lands(...keptLines) : { lines: [] };
+        return [...answer, ...say('reread', { scope: scopes(principal)[0], digest: was.digest, at: was.at, receipt: was.digest }), ...('lines' in landed ? landed.lines : []), ...(await closing(was.digest))];
     }
-    if (spentOf(lines, family, at, source, context.now()) >= most('read/rate'))
-        return say('rate', { source });
+    const again = was?.kind === 'again' ? say(`kept-${was.why}`, { source, operation, at: was.at }) : [];
+    if (overOf(lines, [family, at, word('ahead/mark')], source, context.now(), most('read/rate'), Number(word('ahead/share').split('..')[1]), asked))
+        return asked['ahead'] === 'true' ? [] : say('rate', { source });
     const attached = await attach();
     if ('said' in attached)
         return attached.said;
     const [scope, kept] = scopes(attached.principal ?? '');
     const got = await send(attached.attachment);
+    if (asked['ahead'] === 'true' && (got.kind !== 'got' || got.status >= 300))
+        return [];
     if (got.kind !== 'got')
-        return say(got.kind === 'over' ? 'too-large' : 'unreachable-source', { source });
+        return say(got.kind === 'over' ? 'too-large' : 'unreachable-source', { source, why: got.kind === 'failed' ? got.why : '' });
     if (got.status === 401 && attached.principal !== 'anonymous')
         return refusedAccess(context, place, lines, plan, operation);
     const digest = context.cache.keep(Buffer.concat([Buffer.from(`${got.status}\n`), got.bytes]));
@@ -93,6 +88,6 @@ export const readSource = (asked, context) => called(asked, context, planRead, a
     const observed = plan.access.probe && got.status < 300 ? [canonical({ at: `${at}:${when}`, by: 'target', form: 'alphabet', measure: word('vocab/access'), role: 'writes', scope: observedAt(context.lock, source, operation), value: word('vocab/anonymous') })] : [];
     const found = plan.access.probe && got.status === 401 && got.authenticate ? await (await context.access(word('access/adapter')))?.discover?.(plan.origin, got.authenticate, async (url) => jsonOf((await context.files.read.documentOf(context, place, url))?.bytes ?? new Uint8Array())) : undefined;
     const by = `${word('access/family')}/${source}/${word('access/authorizer')}`, authorizer = Object.entries(found ?? {}).flatMap(([k, f]) => Object.entries(f).map(([measure, all]) => canonical({ at: `${at}:${when}`, by: 'target', form: 'alphabet', measure, role: 'writes', scope: k ? `${by}/${k}` : by, value: all.join('|') })));
-    const landed = await lands(draftOf(family, at, scope, digest, when), ...(attached.principal === undefined ? [] : keeping(kept, answer)), ...observed, ...authorizer);
-    return [...answer, ...('lines' in landed ? [...landed.lines, ...(await closing(digest))] : say('not-landed', { why: landed.refused })), ...(found?.['']?.['issuer'] && 'lines' in landed ? say('authorizer-observed', { source, issuer: found['']['issuer'][0] }) : [])];
+    const landed = await lands(draftOf(family, at, scope, digest, when), ...markOf(asked, [at, word('ahead/mark')], scope, digest, when), ...(attached.principal === undefined ? [] : keeping(kept, answer)), ...observed, ...authorizer);
+    return [...again, ...answer, ...('lines' in landed ? [...landed.lines, ...(await closing(digest))] : say('not-landed', { why: landed.refused })), ...(found?.['']?.['issuer'] && 'lines' in landed ? say('authorizer-observed', { source, issuer: found['']['issuer'][0] }) : [])];
 });

package/dist/src/index.js

@@ -17,7 +17,7 @@ import { parse } from '@lapxo/topos/wire';
 import { aboutOf, valueOf } from "./core/lock.js";
 import { fill, sayIn } from "./core/surface.js";
 import { matchTemplate, refusedOn, shapeOf, shapeSchema, surfaceOf } from "./ports/surface.js";
-import { closing, cooled, founded, land, landAct, limits, pinnedAt, policyAt, run, settledView, sign, standingAt, told, warm, words } from "./ports/bound.js";
+import { birth, closing, cooled, founded, land, landAct, limits, pinnedAt, policyAt, run, settledView, sign, standingAt, told, warm, words } from "./ports/bound.js";
 import { warmth } from "./ports/warm.js";
 import { held, keep } from "./ports/cache.js";
 import { registryFor } from "./ports/signers.js";
@@ -27,18 +27,26 @@ import { keychain } from "./ports/keychain.js";
 import { algorithmOf, deviceOf, idIn } from "./core/device.js";
 import { publicOf } from "./ports/keys.js";
 import { personOf } from "./ports/access/person.js";
+import { readAhead } from "./ahead/read.js";
 const [ext, root] = ((self) => [self.slice(self.lastIndexOf('.')), fileURLToPath(new URL(self.endsWith('.ts') ? '..' : '../..', self))])(import.meta.url);
 const lock = lockAt(root);
+if (process.argv[2] !== valueOf(lock, 'cli/run')) {
+    process.stdout.write(`${aboutOf(lock, 'cli/help')}\n`);
+    process.exit(0);
+}
 const surface = surfaceOf(lock);
 const runs = valueOf(lock, 'runs');
-Object.assign(words, Object.fromEntries(['read', 'view', 'sign', 'land', 'key', 'signer', 'pin', 'topos', 'standing', 'evidence', 'act', 'profile', 'receipts', 'refusal'].map((w) => [w, valueOf(lock, `bound/${w}`)])));
+Object.assign(words, Object.fromEntries(['read', 'view', 'sign', 'land', 'key', 'signer', 'pin', 'topos', 'standing', 'evidence', 'act', 'profile', 'receipts', 'refusal', 'identity'].map((w) => [w, valueOf(lock, `bound/${w}`)])));
 Object.assign(limits, { wait: Number(valueOf(lock, 'bound/wait').split('..')[1]), most: Number(valueOf(lock, 'bound/printed').split('..')[1]) });
+Object.assign(birth, { at: valueOf(lock, 'founding/person-at'), file: valueOf(lock, 'founding/birth-file') });
 Object.assign(warmth, { spares: Number(valueOf(lock, 'bound/spares').split('..')[1]), boot: valueOf(lock, 'bound/spare-env').split('|') });
 /** One call at a time, each after the one before it and never on a timer, so one asked while another lands sees its receipt; bound started ahead for it, and nothing of it kept once it is answered. */
-let last = Promise.resolve();
+let [last, ahead] = [Promise.resolve(), new AbortController()];
 const turn = (act) => ((next) => { last = next.catch(() => undefined); return next; })(last.then(() => { void warm(runs); return act().finally(cooled); }));
+for (const end of ['SIGTERM', 'SIGINT'])
+    process.once(end, () => void last.finally(() => process.exit(0)));
 const offered = (n) => (n ? { listChanged: false } : undefined);
-const server = new Server({ name: surface.name, version: surface.version }, { capabilities: { tools: offered(surface.tools.length), resources: offered(surface.resources.length), prompts: offered(surface.prompts.length) } });
+const server = new Server({ name: surface.name, version: surface.version }, { capabilities: { tools: offered(surface.tools.length), resources: offered(surface.resources.length), prompts: offered(surface.prompts.length) }, instructions: aboutOf(lock, 'prose/en/instructions') });
 /** The person, asked as the client lets head ask; every wait on them is counted, so a time ceiling measures head's work and never the person's. */
 let waited = 0;
 const timed = (ask) => async (...args) => { const t = Date.now(); try {
@@ -103,7 +111,7 @@ const contextOf = (signal) => {
         begun: Date.now() - waited,
         keys,
         device,
-        roots: async () => (server.getClientCapabilities()?.roots ? (await server.listRoots()).roots.flatMap((root) => folderOf(root.uri) ?? []) : []),
+        roots: async () => (server.getClientCapabilities()?.roots ? (await server.listRoots()).roots.flatMap((root) => folderOf(root.uri) ?? []) : []), client: () => ((c) => (c ? `${c.name}@${c.version}` : undefined))(server.getClientVersion()),
     };
 };
 const askedOf = (raw) => Object.fromEntries(Object.entries(raw ?? {}).map(([k, v]) => [k, v === undefined ? undefined : typeof v === 'object' ? JSON.stringify(v) : String(v)]));
@@ -113,14 +121,15 @@ if (surface.tools.length)
     server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: surface.tools.map((tool) => ({ name: tool.name, description: tool.about,
             inputSchema: schemaOf([...tool.fields]), outputSchema: shapeSchema(lock), annotations: Object.fromEntries(tool.hints.map((hint) => [`${hint}Hint`, true])) })) }));
 if (surface.tools.length)
-    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => turn(async () => {
+    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => (ahead.abort(), turn(async () => {
         const tool = surface.tools.find((one) => one.name === request.params.name);
         if (tool === undefined)
             return { isError: true, content: [] };
         const refused = refusedOn(lock, process.platform);
         const context = contextOf(extra.signal), answer = refused !== undefined ? [refused] : extra.signal.aborted ? [] : [...await (await answerOf('tools', tool.name))(askedOf(request.params.arguments), context), ...await context.settle()];
+        void ((early) => turn(() => readAhead(shapeOf(answer).cells, contextOf(), early.signal)))(ahead = new AbortController());
         return { content: [{ type: 'text', text: answer.join('\n') }], structuredContent: shapeOf(answer) };
-    }));
+    })));
 if (surface.resources.length)
     server.setRequestHandler(ListResourcesRequestSchema, () => ({ resources: [] }));
 if (surface.resources.length)

package/dist/src/kept/kept.d.ts

@@ -0,0 +1,30 @@
+import type { Said } from '../core/lock.ts';
+export declare const hand: (digest: string) => string;
+type Held = (digest: string | undefined) => {
+    readonly digest: string;
+    readonly bytes: Uint8Array;
+} | undefined;
+export type Was = {
+    readonly kind: 'kept';
+    readonly at: string;
+    readonly digest: string;
+    readonly receipt: string;
+    readonly bytes?: Uint8Array;
+} | {
+    readonly kind: 'reread';
+    readonly at: string;
+    readonly digest: string;
+    readonly bytes: Uint8Array;
+} | {
+    readonly kind: 'again';
+    readonly at: string;
+    readonly why: 'withdrawn' | 'changed' | 'expired';
+};
+/**
+ * A question read before, as its receipts and the place stand now. Where the place declares a reuse and the newest read
+ * stood, it is kept — its bytes only where this conversation does not hold them yet — or typed again from its receipt if
+ * nothing typed was kept; but read again, and why, where the person's grant had to be given again, the source is pinned
+ * otherwise than when it was read, or the read is older than the reuse allows. Never read, or no reuse: nothing is said.
+ */
+export declare const keptOf: (lines: readonly Said[], at: string, [read, kept]: readonly [string, string], granted: boolean, reuse: string | undefined, now: number, held: Held) => Was | undefined;
+export {};