@lapxo/head 0.1.0 → 0.1.3

package/dist/src/flows/read.js

@@ -1,10 +1,12 @@
-import { planRead } from "../core/read.js";
+import { under } from "../core/lock.js";
+import { observedAt, planRead } from "../core/read.js";
 import { basisOf, draftOf, receiptsOf, scopeOf, spentOf } from "../core/receipt.js";
 import { redIn, sayIn } from "../core/surface.js";
-import { grantedOf, isOpen } from "../core/act.js";
+import { grantedOf, isOpen, untilOf } from "../core/act.js";
 import { canonical } from '@lapxo/topos/wire';
 import { called } from "./call.js";
 import { principalOf } from "../access/obtain.js";
+import { jsonOf } from "../access/contract.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);
@@ -28,7 +30,12 @@ export const readSource = (asked, context) => ((started) => called(asked, contex
     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 allowed = (key, measure) => lines.find((l) => l.scope === `${word(key)}/${source}` && l.measure === measure)?.value;
+    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}`);
+        const signed = newest && lines.find((l) => l.scope === newest.scope && l.value === newest.digest && l.at === `${at}:${newest.at}`), worlds = lines.filter((l) => l.scope?.startsWith('uses/') && (!l.needs || under(context.lock, 'place/worlds', l.needs))).map((l) => `${l.scope.slice('uses/'.length)} ${l.value}`);
+        return newest === undefined ? say('why-none', { source, operation }) : say('why', { source, operation, origin: plan.origin, at: newest.at, by: signed?.by ?? '', epoch: signed?.epoch ?? '', digest: newest.digest, pin: pin?.value ?? '', pinned: pin?.epoch ?? '', worlds: worlds.join(', ') });
+    }
     if (asked['history'] === 'true') {
         const asOf = principalOf(context, plan, false);
         if (allowed('history/family', 'status') !== 'present')
@@ -47,15 +54,15 @@ export const readSource = (asked, context) => ((started) => called(asked, contex
         return stopped;
     if (!grantedOf(lines, word('grant/family'), source, context.now())) {
         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 = new Date(context.now() + Number(word('access/period')) * 86_400_000).toISOString().slice(0, 10);
+        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)]);
         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]);
-    if (principal !== undefined && newest !== undefined && context.now() - Date.parse(newest.at) <= reuse * 1000) {
+    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)
@@ -80,6 +87,9 @@ export const readSource = (asked, context) => ((started) => called(asked, contex
         return say(got.kind === 'over' ? 'too-large' : 'unreachable-source', { source });
     const digest = context.cache.keep(Buffer.concat([Buffer.from(`${got.status}\n`), got.bytes]));
     const answer = await typed(String(got.status), got.bytes);
-    const landed = await lands(draftOf(family, at, scope, digest, when), ...(attached.principal === undefined ? [] : keeping(kept, answer)));
-    return [...answer, ...('lines' in landed ? [...landed.lines, ...(await closing(digest))] : say('not-landed', { why: landed.refused }))];
+    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] }) : [])];
 }))(context.machine());

package/dist/src/flows/world.js

@@ -1,5 +1,5 @@
 import { join } from 'node:path';
-import { valueOf } from "../core/lock.js";
+import { under, valueOf } from "../core/lock.js";
 import { sayIn } from "../core/surface.js";
 import { pinnedOf } from "../core/worlds.js";
 import { adoptsIn } from "../adopt/adopt.js";
@@ -9,14 +9,14 @@ import { adoptsIn } from "../adopt/adopt.js";
  * is no standing. A place that pins a lock as its parent stands on nothing head may read: composing the two is bound's, never head's. A place that pins none and names a view has bound compile it, asked once; a fold bound refused is no standing either.
  */
 export const standingFor = async (context, place) => {
-    const [held, view, compiled] = [await context.standing(place), valueOf(context.lock, 'place/view'), valueOf(context.lock, 'place/compiled')];
+    const [held, view] = [await context.standing(place), valueOf(context.lock, 'place/view')];
     if ('refused' in held)
         return { unsettled: held.refused };
     const own = held.lines;
     const parent = adoptsIn(context.lock, own);
     if (parent !== undefined)
         return { unsettled: sayIn(context.lock)('parent-lock', { place, parent }) };
-    const pins = own.filter((l) => l.scope?.startsWith('uses/') && l.needs?.startsWith(`${compiled}/`)).map((l) => [l, pinnedOf(context.lock, context.files.take(join(place, l.needs)))]);
+    const pins = own.filter((l) => l.scope?.startsWith('uses/') && under(context.lock, 'place/compiled', l.needs)).map((l) => [l, pinnedOf(context.lock, context.files.take(join(place, l.needs)))]);
     const moved = pins.find(([l, p]) => p?.pin !== l.value);
     if (moved)
         return { unsettled: sayIn(context.lock)('compiled-moved', { file: moved[0].needs }) };

package/dist/src/index.js

@@ -14,22 +14,28 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { answerOf } from "./core/answer.js";
 import { valueOf } from "./core/lock.js";
-import { fill, matchTemplate, refusedOn, surfaceOf } from "./core/surface.js";
-import { founded, land, landAct, limits, pinnedAt, run, settledView, sign, standingAt, told, words } from "./ports/bound.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 { warmth } from "./ports/warm.js";
 import { held, keep } from "./ports/cache.js";
 import { registryFor } from "./ports/signers.js";
-import { dropAt, folderOf, hasAt, layAt, lockAt, takeAt } from "./ports/place.js";
+import { dropAt, folderOf, hasAt, layAt, listAt, lockAt, takeAt } from "./ports/place.js";
+import * as documents from "./ports/documents.js";
 import { keychain } from "./ports/keychain.js";
 import { algorithmOf, deviceOf, idIn } from "./core/device.js";
-import { publicOf } from "./core/keys.js";
+import { publicOf } from "./ports/keys.js";
 import { personOf } from "./ports/access/person.js";
 import { inTurn } from "./flows/call.js";
 const [ext, root] = ((self) => [self.slice(self.lastIndexOf('.')), fileURLToPath(new URL(self.endsWith('.ts') ? '..' : '../..', self))])(import.meta.url);
 const lock = lockAt(root);
 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'].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'].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(warmth, { spares: Number(valueOf(lock, 'bound/spares').split('..')[1]), boot: valueOf(lock, 'bound/spare-env').split('|') });
+/** One call at a time, with bound started ahead for it and nothing of it kept once it is answered. */
+const turn = (act) => inTurn('', () => { void warm(runs); return act().finally(cooled); });
 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) } });
 /** 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. */
@@ -52,26 +58,40 @@ const device = (role) => devices.get(role) ?? ((secret) => (secret === undefined
 const asRoot = (account) => ((device, key) => [key, device.signer, { BOUND_SIGNERS: registryFor(device.signer, service, account, key, valueOf(lock, 'founding/algorithm'), store) }])(deviceOf(lock), valueOf(lock, 'founding/root').split('/')[1]);
 /** What a call is answered with, one call at a time as when bound blocked head: every bound process it starts is stopped when the client cancels it, and a call cancelled while it waits its turn is never begun. */
 const contextOf = (signal) => {
+    /** One call's folds of a place, kept until something lands in it or is laid there; and the places its root acted in, whose receipts close once, when the call ends. */
+    const [folds, touched] = [new Map(), new Set()], forget = (place) => { for (const k of [...folds.keys()])
+        if (k.endsWith(`\0${place}`))
+            folds.delete(k); };
+    const once = (key, place, fold) => (folds.get(`${key}\0${place}`) ?? ((p) => (folds.set(`${key}\0${place}`, p), p))(fold()));
+    const acted = (place, root, done) => done.finally(() => { forget(place); if (root)
+        touched.add(place); });
     const signRoot = (place, lot, account) => sign(runs, place, lot, ...asRoot(account), signal);
     const signAs = (place, lot, role, lines) => ((one, id) => sign(runs, place, lot, id, one.signer, { BOUND_SIGNERS: registryFor(one.signer, service, one.account, id, algorithmOf(lines), store) }, signal))(deviceOf(lock, role), idIn(lines, device(role)) ?? deviceOf(lock, role).account);
     return {
         lock,
         bound: (cwd, args) => run(runs, cwd, args, {}, signal),
-        standing: (place) => standingAt(runs, place, (lines) => ['head', 'person'].flatMap((role) => ((id) => (id === undefined ? [] : [id]))(idIn(lines, device(role)))), (line) => line.at?.startsWith(`${valueOf(lock, 'receipt/at')}:`) === true, signal),
-        world: (place, view) => settledView(runs, place, view, signal),
+        standing: (place) => once('standing', place, () => standingAt(runs, place, (lines) => ['head', 'person'].flatMap((role) => ((id) => (id === undefined ? [] : [id]))(idIn(lines, device(role)))), (line) => line.at?.startsWith(`${valueOf(lock, 'receipt/at')}:`) === true, signal)),
+        policy: (place) => once('policy', place, () => policyAt(runs, place, signal)),
+        world: (place, view) => once(`world/${view}`, place, () => settledView(runs, place, view, signal)),
         adapter: async (origin) => ((name) => (!/^[a-z-]+$/.test(name) ? undefined : import(__rewriteRelativeImportExtension(new URL(`./ports/adapters/${name}${ext}`, import.meta.url).href))))(URL.canParse(origin) ? valueOf(lock, `adapter/${new URL(origin).protocol.slice(0, -1)}`) : ''),
-        files: { lay: layAt, drop: dropAt, has: hasAt, take: takeAt, own: (rel) => takeAt(join(root, rel)) },
+        files: { lay: (place, rel, bytes) => { forget(place); layAt(place, rel, bytes); }, drop: (place, rel) => { forget(place); dropAt(place, rel); }, has: hasAt, list: listAt, read: documents, take: takeAt, own: (rel) => takeAt(join(root, rel)) },
         home: () => home,
-        found: (place, account) => founded(runs, place, ...asRoot(account), signal),
+        personal: () => process.env[valueOf(lock, `platform/${process.platform}/home`)] ?? '',
+        found: (place, account) => acted(place, true, founded(runs, place, ...asRoot(account), signal)),
         signRoot,
-        landRoot: (place, lot, account) => landAct(runs, place, lot, ...asRoot(account), signal),
+        landRoot: (place, lot, account) => acted(place, true, landAct(runs, place, lot, ...asRoot(account), signal)),
+        settle: async () => { const red = []; for (const place of touched) {
+            const why = await closing(runs, place, signal);
+            if (why !== undefined)
+                red.push(sayIn(lock)('receipts-open', { place, why }));
+        } touched.clear(); return red; },
         pinned: (place, file) => pinnedAt(runs, place, file, signal),
         access: async (kind) => (kind !== valueOf(lock, 'access/adapter') || !/^[a-z0-9-]+$/.test(kind) ? undefined : import(__rewriteRelativeImportExtension(new URL(`./ports/access/${kind}${ext}`, import.meta.url).href)).then((m) => m.adapter)),
         person,
         cache: { keep, held },
         signAs,
-        landAs: (place, lot, role, lines) => ((one, id) => landAct(runs, place, lot, id, one.signer, { BOUND_SIGNERS: registryFor(one.signer, service, one.account, id, algorithmOf(lines), store) }, signal))(deviceOf(lock, role), idIn(lines, device(role)) ?? deviceOf(lock, role).account),
-        land: (place, signed) => land(runs, place, signed, signal),
+        landAs: (place, lot, role, lines) => acted(place, false, ((one, id) => landAct(runs, place, lot, id, one.signer, { BOUND_SIGNERS: registryFor(one.signer, service, one.account, id, algorithmOf(lines), store) }, signal))(deviceOf(lock, role), idIn(lines, device(role)) ?? deviceOf(lock, role).account)),
+        land: (place, signed) => acted(place, true, land(runs, place, signed, signal)),
         told: (place, signed) => told(runs, place, signed, words.standing, signal),
         elicit: (message) => person.consent(message, valueOf(lock, 'said/elicit/yes')),
         now: () => Date.now(),
@@ -86,23 +106,22 @@ const schemaOf = (fields) => ({ type: 'object',
     properties: Object.fromEntries(fields.map((f) => [f.name, { type: f.type, description: f.about }])), required: fields.filter((f) => f.required).map((f) => f.name) });
 if (surface.tools.length)
     server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: surface.tools.map((tool) => ({ name: tool.name, description: tool.about,
-            inputSchema: schemaOf([...tool.fields]), annotations: Object.fromEntries(tool.hints.map((hint) => [`${hint}Hint`, true])) })) }));
+            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) => inTurn('', async () => {
+    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => 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);
-        if (refused !== undefined)
-            return { content: [{ type: 'text', text: refused }] };
-        return { content: [{ type: 'text', text: extra.signal.aborted ? '' : (await (await answerOf('tools', tool.name))(askedOf(request.params.arguments), contextOf(extra.signal))).join('\n') }] };
+        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()];
+        return { content: [{ type: 'text', text: answer.join('\n') }], structuredContent: shapeOf(answer) };
     }));
 if (surface.resources.length)
     server.setRequestHandler(ListResourcesRequestSchema, () => ({ resources: [] }));
 if (surface.resources.length)
     server.setRequestHandler(ListResourceTemplatesRequestSchema, () => ({ resourceTemplates: surface.resources.map((r) => ({ name: r.name, uriTemplate: r.template, description: r.about, mimeType: r.mime })) }));
 if (surface.resources.length)
-    server.setRequestHandler(ReadResourceRequestSchema, async (request, extra) => inTurn('', async () => {
+    server.setRequestHandler(ReadResourceRequestSchema, async (request, extra) => turn(async () => {
         const found = surface.resources.flatMap((r) => ((vars) => (vars === undefined ? [] : [{ r, vars }]))(matchTemplate(r.template, request.params.uri)))[0];
         if (found === undefined)
             return { contents: [] };

package/dist/src/onboard/first.d.ts

@@ -0,0 +1,7 @@
+import { type Asked, type Context } from '../core/answer.ts';
+/**
+ * The first source a person connects with no place named and none to read from: their place is founded in the folder
+ * the lock names under their own home, and the source connected to it, on one yes for both. A folder that already holds
+ * a place is used as it stands, never founded again, and its connect asks its own yes.
+ */
+export declare const firstRun: (asked: Asked, context: Context, then: (place: string, covered: boolean) => Promise<readonly string[]>) => Promise<readonly string[]>;

package/dist/src/onboard/first.js

@@ -0,0 +1,21 @@
+import { basename, join } from 'node:path';
+import { LOCK } from '@lapxo/topos/wire';
+import { unless } from "../core/answer.js";
+import { valueOf } from "../core/lock.js";
+import { sayIn } from "../core/surface.js";
+import { bornAt } from "../places/found.js";
+/**
+ * The first source a person connects with no place named and none to read from: their place is founded in the folder
+ * the lock names under their own home, and the source connected to it, on one yes for both. A folder that already holds
+ * a place is used as it stands, never founded again, and its connect asks its own yes.
+ */
+export const firstRun = async (asked, context, then) => {
+    const say = sayIn(context.lock), dir = join(context.personal(), valueOf(context.lock, 'first-run/folder')), name = basename(dir);
+    if (context.files.has(dir, LOCK))
+        return then(dir, false);
+    const refused = await unless(context, say('elicit-first-run', { dir, source: asked['source'] ?? '', document: asked['document'] ?? '' }));
+    if (refused)
+        return refused;
+    const born = await bornAt(context, dir, name);
+    return born[0] === say('born', { name, dir }) ? [...born, ...(await then(dir, true))] : born;
+};

package/dist/src/places/admit.js

@@ -15,7 +15,7 @@ export const admitted = (asked, context) => inPlace(asked, context, async (place
     const key = (asked['key'] ?? '').split('\n').map((line) => parse(line.trim())).flatMap((got) => (got.kind === 'fact' && got.value.fields['measure'] === 'public-key' ? [got.value.fields['value'] ?? ''] : []))[0];
     if (!name || !key)
         return [say('no-key')];
-    const [root, held] = [rootIn(context, place), await standingOr(context, place)];
+    const [root, held] = [rootIn(context, place), await standingOr(context, place, context.policy)];
     if ('said' in root)
         return root.said;
     if ('said' in held)

package/dist/src/places/found.d.ts

@@ -4,3 +4,4 @@ import type { Asked, Context } from '../core/answer.ts';
  * and named in head's own index of places — itself a place, founded the first time — by a line its root signs.
  */
 export declare const bornPlace: (asked: Asked, context: Context) => Promise<readonly string[]>;
+export declare const bornAt: (context: Context, dir: string, name: string) => Promise<readonly string[]>;

package/dist/src/places/found.js

@@ -2,7 +2,6 @@ import { isAbsolute, basename } from 'node:path';
 import { canonical, LOCK } from '@lapxo/topos/wire';
 import { unless } from "../core/answer.js";
 import { admissionOf } from "../core/device.js";
-import { newKey } from "../core/keys.js";
 import { valueOf } from "../core/lock.js";
 import { deviceKey } from "../flows/device.js";
 import { walkable } from "../walk/context.js";
@@ -25,9 +24,10 @@ const founded = async (context, dir, name) => {
         return { refused: 'no-keychain' };
     if (context.keys.read(account) !== undefined)
         return { refused: 'place-taken' };
-    const root = newKey();
-    context.keys.write(account, root.secret);
-    context.files.lay(dir, LOCK, new TextEncoder().encode(`${birthOf(context.lock, root.publicKey, head, person, name).join('\n')}\n`));
+    const root = context.keys.made?.(account);
+    if (root === undefined)
+        return { refused: 'no-keychain' };
+    context.files.lay(dir, LOCK, new TextEncoder().encode(`${birthOf(context.lock, root, head, person, name).join('\n')}\n`));
     const born = await context.found(dir, account);
     return ((got) => ('refused' in got ? { refused: 'not-landed', why: got.refused } : got))('refused' in born ? born : await walkable(context, dir, account));
 };
@@ -44,9 +44,10 @@ export const bornPlace = async (asked, context) => {
     if (context.files.has(dir, LOCK))
         return [say('place-exists', { dir })];
     const refused = await unless(context, say('elicit-place', { name, dir }));
-    if (refused)
-        return refused;
-    const born = await founded(context, dir, name);
+    return refused ?? bornAt(context, dir, name);
+};
+export const bornAt = async (context, dir, name) => {
+    const say = sayIn(context.lock), born = await founded(context, dir, name);
     if ('refused' in born)
         return [say(born.refused, { name, dir, why: born.why ?? '' })];
     const home = context.home();

package/dist/src/ports/access/authorizer.d.ts

@@ -0,0 +1,10 @@
+import type { Fields } from '../../access/contract.ts';
+/**
+ * The authorizer a resource names when it refuses a request: its protected resource metadata (RFC 9728) at the address
+ * its challenge gives, which must name the very origin that refused; the authorization server's metadata (RFC 8414),
+ * which must name the issuer the resource named and take S256; and from them the oauth2 authorization-code flow a
+ * document would have declared — the same steps, PKCE through head's page, a client registered (RFC 7591) only where
+ * the server offers registration and the person's own where it does not, the token and its refresh, renewed at the
+ * token endpoint. Every one of these reads goes with nothing attached; what does not hold is no authorizer.
+ */
+export declare const discovered: (resource: string, challenge: string, get: (url: string) => Promise<unknown>) => Promise<Readonly<Record<string, Fields>> | undefined>;

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

@@ -0,0 +1,34 @@
+const text = (json, key) => ((v) => (typeof v === 'string' && v ? v : undefined))(json?.[key]);
+const texts = (json, key) => ((v) => (Array.isArray(v) ? v.filter((x) => typeof x === 'string') : []))(json?.[key]);
+const fields = (pairs) => Object.fromEntries(Object.entries(pairs).map(([k, v]) => [k, [v].flat()]));
+/**
+ * The authorizer a resource names when it refuses a request: its protected resource metadata (RFC 9728) at the address
+ * its challenge gives, which must name the very origin that refused; the authorization server's metadata (RFC 8414),
+ * which must name the issuer the resource named and take S256; and from them the oauth2 authorization-code flow a
+ * document would have declared — the same steps, PKCE through head's page, a client registered (RFC 7591) only where
+ * the server offers registration and the person's own where it does not, the token and its refresh, renewed at the
+ * token endpoint. Every one of these reads goes with nothing attached; what does not hold is no authorizer.
+ */
+export const discovered = async (resource, challenge, get) => {
+    const at = /resource_metadata="([^"]+)"/.exec(challenge)?.[1];
+    if (at === undefined || !URL.canParse(at, resource))
+        return undefined;
+    const named = await get(new URL(at, resource).href), [issuer] = texts(named, 'authorization_servers'), own = text(named, 'resource');
+    if (own === undefined || !URL.canParse(own) || new URL(own).origin !== new URL(resource).origin || issuer === undefined || !URL.canParse(issuer))
+        return undefined;
+    const server = await get(`${new URL(issuer).origin}/.well-known/oauth-authorization-server${new URL(issuer).pathname.replace(/\/$/, '')}`);
+    const [authorize, token, register, methods] = [text(server, 'authorization_endpoint'), text(server, 'token_endpoint'), text(server, 'registration_endpoint'), texts(server, 'code_challenge_methods_supported')];
+    if (text(server, 'issuer') !== issuer || authorize === undefined || token === undefined || (methods.length > 0 && !methods.includes('S256')))
+        return undefined;
+    const [client, scopes] = [register ? '$steps.register.outputs.client' : '$client', texts(named, 'scopes_supported').join(' ')];
+    const sent = (step, pairs) => Object.fromEntries(Object.entries(pairs).filter(([, v]) => v).map(([k, v]) => [`${step}/payload/${k}`, fields({ value: v })]));
+    return {
+        '': fields({ type: 'oauth2/authorizationCode', issuer, 'attach-in': 'header', 'attach-name': 'Authorization', 'attach-template': 'Bearer {token}', token: '$steps.exchange.outputs.token', expires: '$steps.exchange.outputs.expires', refresh: '$steps.exchange.outputs.refresh', renew: token }),
+        ...(register ? { 'steps/0': fields({ id: 'register', url: register, encoding: 'json' }), 'steps/0/payload/redirect_uris': fields({ items: '$callback' }), 'steps/0/payload/grant_types': fields({ items: ['authorization_code', 'refresh_token'] }),
+            'steps/0/payload/response_types': fields({ items: 'code' }), ...sent('steps/0', { client_name: 'head', token_endpoint_auth_method: "'none'" }), 'steps/0/outputs/client': fields({ value: '$response.body#/client_id' }) } : {}),
+        'steps/1': fields({ id: 'authorize', page: authorize }), 'steps/1/outputs/code': fields({ value: '$response.body#/code' }),
+        ...sent('steps/1', { client_id: client, redirect_uri: '$callback', response_type: 'code', scope: scopes, state: '$state', code_challenge: 's256($verifier)', code_challenge_method: 'S256', resource: new URL(resource).origin }),
+        'steps/2': fields({ id: 'exchange', url: token, encoding: 'form' }), ...sent('steps/2', { grant_type: 'authorization_code', code: '$steps.authorize.outputs.code', redirect_uri: '$callback', client_id: client, code_verifier: '$verifier', resource: new URL(resource).origin }),
+        'steps/2/outputs/token': fields({ value: '$response.body#/access_token' }), 'steps/2/outputs/expires': fields({ value: '$response.body#/expires_in' }), 'steps/2/outputs/refresh': fields({ value: '$response.body#/refresh_token' }),
+    };
+};

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

@@ -1,4 +1,6 @@
 import { createHash, randomBytes } from 'node:crypto';
+import { jsonOf } from "../../access/contract.js";
+import { discovered } from "./authorizer.js";
 const one = (f, measure) => f?.[measure]?.[0];
 const pointed = (json, pointer) => pointer.split('/').slice(1).map((s) => s.replaceAll('~1', '/').replaceAll('~0', '~'))
     .reduce((at, step) => at.flatMap((v) => (v === null || typeof v !== 'object' ? [] : step === '*' ? Object.values(v) : [v[step]])), [json])
@@ -18,9 +20,16 @@ const originOf = (url) => (URL.canParse(url) ? new URL(url).origin : '');
  * the token is kept, and it rides a request as the flow's template says.
  */
 export const adapter = {
+    discover: discovered,
     attach: (secret, params) => ((into, name, value) => (into === 'header' ? { headers: { [name]: value }, query: {} } : into === 'query' ? { headers: {}, query: { [name]: value } } : { headers: {}, query: {} }))(one(params, 'attach-in'), one(params, 'attach-name') ?? '', (one(params, 'attach-template') ?? '{token}').split('{token}').join(secret)),
     obtain: async (want) => {
-        const [d, gen, inputs, outputs] = [want.declared, { state: randomBytes(24).toString('base64url'), verifier: randomBytes(32).toString('base64url') }, new Map(), new Map()];
+        const [d, renewed] = [want.declared, ((r) => (r && typeof r === 'object' ? r : undefined))(jsonOf(want.renew ?? ''))];
+        if (renewed?.refresh && one(d[''], 'renew')) {
+            const got = await want.post(one(d[''], 'renew'), { grant_type: 'refresh_token', refresh_token: renewed.refresh, ...(renewed.client ? { client_id: renewed.client } : {}) }, 'form'), [secret, lasts, refresh] = ['/access_token', '/expires_in', '/refresh_token'].map((at) => pointed(got?.json, at)[0]);
+            if (got !== undefined && got.status < 300 && secret)
+                return { secret, ...(Number.isFinite(Number(lasts)) && lasts ? { expires: want.now + Number(lasts) * 1000 } : {}), renew: JSON.stringify({ ...renewed, refresh: refresh ?? renewed.refresh }) };
+        }
+        const [gen, inputs, outputs] = [{ state: randomBytes(24).toString('base64url'), verifier: randomBytes(32).toString('base64url') }, new Map(), new Map()];
         let [callback, secrets, refused] = ['', 0, undefined];
         const stop = (why) => { refused ??= why; return undefined; };
         const ask = async (name) => {
@@ -110,11 +119,12 @@ export const adapter = {
         for (const k of page >= 0 ? steps.slice(page + 1) : steps)
             if (refused || !(await run(k)))
                 break;
-        const [token, expires] = [(await Promise.all((d['']?.['token'] ?? []).map((e) => resolve(e)))).find((v) => !empty(v)), (await Promise.all((d['']?.['expires'] ?? []).map((e) => resolve(e)))).find((v) => !empty(v))];
+        const [token, expires, refresh] = await Promise.all(['token', 'expires', 'refresh'].map(async (k) => (await Promise.all((d['']?.[k] ?? []).map((e) => resolve(e)))).find((v) => !empty(v))));
         if (refused)
             return refused;
         if (typeof token !== 'string' || !token)
             return { refused: 'login-refused' };
-        return { secret: token, ...(typeof expires === 'string' && Number.isFinite(Number(expires)) ? { expires: want.now + Number(expires) * 1000 } : {}), ...(steps.length ? {} : { manual: true }) };
+        return { secret: token, ...(typeof expires === 'string' && Number.isFinite(Number(expires)) ? { expires: want.now + Number(expires) * 1000 } : {}), ...(steps.length ? {} : { manual: true }),
+            ...(typeof refresh === 'string' && refresh ? { renew: JSON.stringify({ refresh, client: outputs.get('register')?.get('client') ?? one(d[''], 'client') }) } : {}) };
     },
 };

package/dist/src/ports/access/person.d.ts

@@ -14,8 +14,9 @@ export interface Client {
 /**
  * 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 declare const personOf: (lock: readonly Said[], client: Client) => {
     consent: (message: string, word: string) => Promise<"yes" | "no" | "none">;

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>;