@prestack/thread 0.0.1

package/dist/operations/generators/trial.js

@@ -0,0 +1,376 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { argv, stdout } from 'node:process';
+import { pathToFileURL } from 'node:url';
+import { ANONYMOUS } from "../../core/actor.js";
+import { ROOT, TREE, descend } from "../../core/descend.js";
+import { exit, invoked } from "../../core/invoked.js";
+import { recordingHttp } from "../http.js";
+import { inMemorySeams } from "../memory.js";
+import { TRIALS_AT } from "../operations.js";
+import { PERMITS_AT } from "../access.js";
+import { operations, types } from "./seed.js";
+export { TRIALS_AT };
+const DISPATCH_AT = 'operations/_dispatch.ts';
+const ENTITIES_AT = `${TREE}entities.ts`;
+const ACCESS_AT = '_threads/access.ts';
+const WHEN = 1_767_225_600_000;
+const compare = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+function stable(value) {
+    if (Array.isArray(value))
+        return value.map(stable);
+    if (value instanceof Map)
+        return stable(Object.fromEntries(value));
+    if (value instanceof Set)
+        return [...value].map(stable);
+    if (typeof value === 'object' && value !== null) {
+        const found = {};
+        for (const key of Object.keys(value).sort(compare)) {
+            found[key] = stable(value[key]);
+        }
+        return found;
+    }
+    if (typeof value === 'bigint')
+        return String(value);
+    if (typeof value === 'function')
+        return '[function]';
+    if (value === undefined)
+        return null;
+    return value;
+}
+const printed = (value) => `${JSON.stringify(stable(value), null, 2)}\n`;
+const asking = (scenario) => ({
+    ...(scenario.actor ?? ANONYMOUS),
+    run: 'trial',
+    replay: `trial_${scenario.id}`,
+});
+function seamsFor(one, scenario, stood, gate, known) {
+    const made = inMemorySeams({
+        secrets: stood,
+        ...(scenario.views === undefined ? {} : { views: scenario.views }),
+        ...(known === undefined ? {} : { entities: known.entities, keys: known.keys }),
+    });
+    const found = made.seams;
+    found['permits'] = gate ?? {
+        check() {
+            return Promise.resolve({ allow: true, because: 'this app derives no gate, so nothing here can refuse' });
+        },
+    };
+    found['clock'] = { now: () => WHEN };
+    let drawn = 0;
+    found['random'] = {
+        next: () => {
+            drawn += 1;
+            return drawn / 100;
+        },
+        uuid: () => {
+            drawn += 1;
+            return `00000000-0000-4000-8000-${String(drawn).padStart(12, '0')}`;
+        },
+    };
+    const recorder = recordingHttp(scenario.answers ?? {});
+    found['http'] = recorder;
+    return { seams: made.seams, sink: made.sink, kept: () => made.store, calls: () => recorder.calls };
+}
+function entered(sink) {
+    return sink.logs.some((one) => {
+        const data = one.data;
+        return data !== undefined && 'observability' in data;
+    });
+}
+function denied(result) {
+    if (typeof result !== 'object' || result === null)
+        return false;
+    const held = result;
+    return held.ok === false && held.code === 'denied';
+}
+export async function runScenario(one, scenario, dispatch, stood = {}, gate, known) {
+    const made = seamsFor(one, scenario, stood, gate, known);
+    const actor = asking(scenario);
+    for (const seeded of scenario.rows ?? []) {
+        await made.seams.store.insert(actor, seeded.entity, seeded.row);
+    }
+    let result;
+    try {
+        result = await dispatch(one, scenario.input, actor, made.seams);
+    }
+    catch (thrown) {
+        result = { threw: thrown instanceof Error ? thrown.message : String(thrown) };
+    }
+    return {
+        operation: one.id,
+        scenario: scenario.id,
+        refused: denied(result),
+        measured: entered(made.sink),
+        result,
+        kept: made.kept(),
+        observed: made.sink,
+        called: made.calls(),
+    };
+}
+export async function scenariosFor(one, takes, granted = []) {
+    const from = resolve(ROOT, takes);
+    if (existsSync(from)) {
+        const made = (await import(__rewriteRelativeImportExtension(pathToFileURL(from).href)));
+        const found = made.SCENARIOS;
+        if (found !== undefined) {
+            if (found.length === 0) {
+                return `${takes} states an empty \`SCENARIOS\`, so nothing would be measured — remove it, or state one`;
+            }
+            const named = new Set(found.map((each) => each.id));
+            if (named.size !== found.length) {
+                return `${takes} states two scenarios with the same id, and a trial is named after the one it ran`;
+            }
+            return [...found].sort((a, b) => compare(a.id, b.id));
+        }
+    }
+    if (granted.length > 0) {
+        return (`\`${one.id}\` is granted to ${granted.join(', ')}, and no scenario says who runs it. A caller is not ` +
+            `something to derive — a trial run as somebody the grant must allow proves nothing about access. State one ` +
+            `with \`thread run trial ${one.id}\`, which asks for the roles it arrives wearing, and export \`SCENARIOS\` ` +
+            `from ${takes}`);
+    }
+    const empty = one.input.safeParse({});
+    if (empty.success) {
+        return [{ id: 'empty', describes: `runs ${one.id} with no input, as whoever arrives having said nothing`, input: {} }];
+    }
+    return (`\`${one.id}\` takes an input that no empty object satisfies, and states no scenario to try it ` +
+        `with. Export \`SCENARIOS\` from ${takes} — until then this operation is not proven`);
+}
+export function compared(was, now) {
+    const before = new Map(was.map((one) => [`${one.operation}/${one.scenario}`, one]));
+    const outcomes = [];
+    for (const one of now) {
+        const id = `${one.operation}/${one.scenario}`;
+        const failures = [];
+        const older = before.get(id);
+        if (!one.refused && !one.measured) {
+            failures.push('the run never entered the operation and nothing denied it, so nothing about the operation was ' +
+                `measured and no refusal was proven either. What it answered was ${JSON.stringify(one.result)}`);
+        }
+        if (one.refused && one.measured) {
+            failures.push('this app\'s own gate denied the caller and the run REACHED THE OPERATION anyway — dispatch let a ' +
+                'denied request through to the compiled function, which is the gate not holding rather than a trial drifting');
+        }
+        if (older === undefined) {
+            failures.push('no trial holds this scenario. Run `thread trials` and commit the result');
+        }
+        else {
+            for (const part of ['result', 'kept', 'observed']) {
+                const then = printed(older[part]);
+                const said = printed(one[part]);
+                if (then === said)
+                    continue;
+                failures.push(`${part} is not what was recorded — the operation's behaviour has changed.\n    was: ${then.trim().slice(0, 400)}\n    now: ${said.trim().slice(0, 400)}`);
+            }
+        }
+        outcomes.push({
+            id,
+            operation: one.operation,
+            passed: failures.length === 0,
+            refused: one.refused,
+            measured: one.measured,
+            failures,
+        });
+    }
+    for (const one of was) {
+        const id = `${one.operation}/${one.scenario}`;
+        if (now.some((each) => `${each.operation}/${each.scenario}` === id))
+            continue;
+        outcomes.push({
+            id,
+            operation: one.operation,
+            passed: false,
+            refused: one.refused,
+            measured: false,
+            failures: ['this scenario is recorded and no longer runs — an operation or a scenario was removed without the trials being regenerated'],
+        });
+    }
+    return {
+        outcomes,
+        passed: outcomes.filter((one) => one.passed).length,
+        failed: outcomes.filter((one) => !one.passed).length,
+        measured: outcomes.filter((one) => one.measured).length,
+    };
+}
+export function unproven(run) {
+    const each = new Map();
+    for (const one of run.outcomes) {
+        const held = each.get(one.operation);
+        if (held === undefined)
+            each.set(one.operation, [one]);
+        else
+            held.push(one);
+    }
+    const said = [];
+    for (const [operation, outcomes] of [...each].sort((one, two) => compare(one[0], two[0]))) {
+        if (outcomes.some((one) => one.measured))
+            continue;
+        const denied = outcomes.filter((one) => one.refused).length;
+        const neither = outcomes.length - denied;
+        const how = [
+            denied === 0
+                ? ''
+                : `${String(denied)} were denied by this app's own gate, which proves the gate turns somebody away and nothing whatever about the operation`,
+            neither === 0 ? '' : `${String(neither)} neither reached it nor were denied`,
+        ].filter((one) => one !== '');
+        said.push(`\`${operation}\` is UNPROVEN — ${String(outcomes.length)} scenario(s) ran and not one of them reached it: ${how.join(', and ')}. ` +
+            'Grant a caller the trial can run as, or give it a scenario the gate admits');
+    }
+    return said;
+}
+async function standing() {
+    const at = resolve(ROOT, '_threads/secrets.ts');
+    if (!existsSync(at))
+        return {};
+    let held;
+    try {
+        const taken = (await import(__rewriteRelativeImportExtension(pathToFileURL(at).href)));
+        held = taken.SECRETS ?? [];
+    }
+    catch {
+        return {};
+    }
+    const found = {};
+    for (const one of held) {
+        found[one.id] = one.sends === undefined ? `https://${one.id.replace(/_/g, '-')}.invalid` : `${one.id}-stood-in-for`;
+    }
+    return found;
+}
+export async function record() {
+    const pass = descend();
+    const known = types(pass);
+    const refusals = [];
+    const trials = [];
+    const declared = [...operations(pass, known)].filter(([, one]) => one.body !== undefined);
+    if (declared.length === 0)
+        return { trials: [], refusals: [] };
+    const stood = await standing();
+    const at = resolve(ROOT, DISPATCH_AT);
+    if (!existsSync(at)) {
+        return {
+            trials: [],
+            refusals: [
+                `this app has no ${DISPATCH_AT}. Run \`thread compile\` — an operation runs through dispatch and there is nothing here to run it with`,
+            ],
+        };
+    }
+    const made = (await import(__rewriteRelativeImportExtension(pathToFileURL(at).href)));
+    const dispatch = made.dispatch;
+    if (dispatch === undefined) {
+        return { trials: [], refusals: [`${DISPATCH_AT} exports no \`dispatch\`, so nothing here can run an operation`] };
+    }
+    const kept = resolve(ROOT, ENTITIES_AT);
+    const entities = new Map();
+    const keys = new Map();
+    if (existsSync(kept)) {
+        const sheet = (await import(__rewriteRelativeImportExtension(pathToFileURL(kept).href)));
+        for (const one of sheet.ENTITIES ?? []) {
+            entities.set(one.id, new Set([...(one.holds ?? []).map((each) => each.id), ...(one.links ?? []).map((each) => `${each.id}_id`)]));
+            const named = (one.must ?? []).flatMap((each) => (each.unique?.length === 1 ? [each.unique[0]] : []));
+            if (named.length === 1)
+                keys.set(one.id, named[0]);
+        }
+    }
+    const permitted = resolve(ROOT, ACCESS_AT);
+    const may = new Map();
+    if (existsSync(permitted)) {
+        const sheet = (await import(__rewriteRelativeImportExtension(pathToFileURL(permitted).href)));
+        for (const one of sheet.GRANTS ?? []) {
+            for (const id of one.may ?? []) {
+                may.set(id, [...new Set([...(may.get(id) ?? []), ...(one.to?.roles ?? [])])]);
+            }
+        }
+    }
+    const compiled = resolve(ROOT, PERMITS_AT);
+    const permits = existsSync(compiled)
+        ? (await import(__rewriteRelativeImportExtension(pathToFileURL(compiled).href))).permits
+        : undefined;
+    if (existsSync(compiled) && permits === undefined) {
+        return {
+            trials: [],
+            refusals: [`${PERMITS_AT} exports no \`permits\`, so a trial cannot be answered by the gate this app derives`],
+        };
+    }
+    const gate = permits === undefined
+        ? undefined
+        : { check: (actor, action, resource) => Promise.resolve(permits(actor, action, resource)) };
+    for (const [id, one] of [...declared].sort((a, b) => compare(a[0], b[0]))) {
+        if (one.body === undefined)
+            continue;
+        const from = resolve(ROOT, one.body);
+        if (!existsSync(from)) {
+            refusals.push(`\`${id}\` derives ${one.body} and that file is not there. Run \`thread compile\``);
+            continue;
+        }
+        const held = (await import(__rewriteRelativeImportExtension(pathToFileURL(from).href)));
+        const operation = held.operation;
+        if (operation === undefined) {
+            refusals.push(`${one.body} exports no \`operation\`, so \`${id}\` cannot be run`);
+            continue;
+        }
+        const takes = one.takes[0]?.at;
+        if (takes === undefined) {
+            refusals.push(`\`${id}\` names nothing it takes, so nothing states its input or what to try it with`);
+            continue;
+        }
+        const scenarios = await scenariosFor(operation, takes, may.get(id) ?? []);
+        if (typeof scenarios === 'string') {
+            refusals.push(scenarios);
+            continue;
+        }
+        for (const scenario of scenarios) {
+            trials.push(await runScenario(operation, scenario, dispatch, stood, gate, { entities, keys }));
+        }
+    }
+    return { trials, refusals };
+}
+function kept() {
+    const at = resolve(ROOT, TRIALS_AT);
+    if (!existsSync(at))
+        return [];
+    return JSON.parse(readFileSync(at, 'utf8'));
+}
+if (invoked(import.meta.url)) {
+    const { trials, refusals } = await record();
+    for (const one of refusals)
+        console.error(`trial: ${one}`);
+    if (argv.includes('--check')) {
+        const run = compared(kept(), trials);
+        for (const outcome of run.outcomes) {
+            if (outcome.passed)
+                continue;
+            for (const failure of outcome.failures)
+                console.error(`trial: ${outcome.id} — ${failure}`);
+        }
+        if (run.outcomes.length === 0 && refusals.length === 0) {
+            console.log('trial: this app declares no operation, so there is nothing to prove.');
+            exit(0);
+        }
+        const short = unproven(run);
+        for (const one of short)
+            console.error(`trial: ${one}`);
+        console.log(`trial: ${String(run.passed)} of ${String(run.outcomes.length)} passed, ${String(run.measured)} measured, ` +
+            `${String(short.length)} operation(s) unproven.`);
+        exit(run.failed === 0 && refusals.length === 0 && short.length === 0 ? 0 : 1);
+    }
+    if (refusals.length > 0) {
+        console.error(`trial: ${String(refusals.length)} refusal(s) above, so ${TRIALS_AT} is left as it was — ` +
+            'a run that was refused has nothing to record, and recording it would erase what does');
+        exit(1);
+    }
+    const at = resolve(ROOT, TRIALS_AT);
+    mkdirSync(dirname(at), { recursive: true });
+    writeFileSync(at, printed(trials));
+    const measured = trials.filter((one) => one.measured).length;
+    stdout.write(`trial: wrote ${TRIALS_AT} — ${String(trials.length)} trial(s) from ${String(measured)} run(s) that reached an operation.\n`);
+    exit(0);
+}

package/dist/operations/http.d.ts

@@ -0,0 +1,30 @@
+import type { Http } from './seams.ts';
+export declare const HTTP_CALL_ACTION = "http.call";
+export declare class HttpNotConfiguredError extends Error {
+    constructor();
+}
+export declare class OutwardTransportError extends Error {
+    readonly target: string;
+    constructor(target: string, cause: unknown);
+}
+export declare function outwardUrl(target: string, address: string, path: string): URL;
+export interface HttpSeamOptions {
+    readonly transport?: typeof fetch;
+    readonly timeoutMs?: number;
+}
+export declare function httpSeam(options?: HttpSeamOptions): Http;
+export interface RecordedCall {
+    readonly target: string;
+    readonly method: string;
+    readonly path: string;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: string;
+}
+export interface ScriptedAnswer {
+    readonly status: number;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly body?: string;
+}
+export declare function recordingHttp(script?: Readonly<Record<string, ScriptedAnswer>>): Http & {
+    readonly calls: readonly RecordedCall[];
+};

package/dist/operations/http.js

@@ -0,0 +1,121 @@
+import { payloadBytes } from "./metering.js";
+import { ValidationError } from "./result.js";
+export const HTTP_CALL_ACTION = 'http.call';
+export class HttpNotConfiguredError extends Error {
+    constructor() {
+        super('no outward seam is configured. `http.call` needs `seams.http`, which is the transport an app ' +
+            'wires — which hosts it may reach is declared in its tree and is not this seam\'s business.');
+        this.name = 'HttpNotConfiguredError';
+    }
+}
+export class OutwardTransportError extends Error {
+    target;
+    constructor(target, cause) {
+        super(`outward call to "${target}" never reached it: ${cause instanceof Error ? cause.message : String(cause)}`);
+        this.target = target;
+        this.name = 'OutwardTransportError';
+    }
+}
+export function outwardUrl(target, address, path) {
+    let base;
+    try {
+        base = new URL(address);
+    }
+    catch {
+        throw new ValidationError(`the address resolved for "${target}" is not an absolute URL: ${JSON.stringify(address)}`);
+    }
+    if (base.protocol !== 'https:') {
+        throw new ValidationError(`outward calls go over https only, and "${target}" resolved to ${base.protocol.replace(':', '')}`);
+    }
+    if (base.search !== '' || base.hash !== '') {
+        throw new ValidationError(`the address for "${target}" carries a query or a fragment — those belong to the call`);
+    }
+    if (!path.startsWith('/')) {
+        throw new ValidationError(`an outward path starts with "/", and "${path}" does not`);
+    }
+    if (path.startsWith('//')) {
+        throw new ValidationError(`the path "${path}" is protocol-relative, which points at another host`);
+    }
+    const url = new URL(`${base.origin}${base.pathname.replace(/\/$/, '')}${path}`);
+    if (url.origin !== base.origin) {
+        throw new ValidationError(`the path "${path}" resolves to ${url.origin}, which is not where "${target}" is`);
+    }
+    return url;
+}
+function requestBytes(headers, body) {
+    return payloadBytes(headers) + (body === undefined ? 0 : body.byteLength);
+}
+function wireBody(body) {
+    const copy = new ArrayBuffer(body.byteLength);
+    new Uint8Array(copy).set(body);
+    return copy;
+}
+const DEFAULT_TIMEOUT_MS = 10_000;
+export function httpSeam(options = {}) {
+    const send = options.transport ?? fetch;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    return {
+        async call(request) {
+            const url = outwardUrl(request.target, request.address, request.path);
+            const headers = { ...request.headers };
+            if (request.contentType !== undefined)
+                headers['content-type'] = request.contentType;
+            if (request.idempotencyKey !== undefined)
+                headers['idempotency-key'] = request.idempotencyKey;
+            const bytesSent = requestBytes(headers, request.body);
+            const startedAt = Date.now();
+            let response;
+            try {
+                response = await send(url.toString(), {
+                    method: request.method,
+                    headers,
+                    ...(request.body === undefined ? {} : { body: wireBody(request.body) }),
+                    signal: AbortSignal.timeout(timeoutMs),
+                });
+            }
+            catch (error) {
+                throw new OutwardTransportError(request.target, error);
+            }
+            const body = new Uint8Array(await response.arrayBuffer());
+            const responseHeaders = Object.fromEntries(response.headers.entries());
+            return {
+                status: response.status,
+                headers: responseHeaders,
+                body,
+                bytesSent,
+                bytesReceived: payloadBytes(responseHeaders) + body.byteLength,
+                durationMs: Date.now() - startedAt,
+            };
+        },
+    };
+}
+const REDACTED = '(sent)';
+export function recordingHttp(script = {}) {
+    const calls = [];
+    const decoder = new TextDecoder();
+    return {
+        calls,
+        async call(request) {
+            outwardUrl(request.target, request.address, request.path);
+            const body = request.body === undefined ? '' : decoder.decode(request.body);
+            calls.push({
+                target: request.target,
+                method: request.method,
+                path: request.path,
+                headers: Object.fromEntries(Object.keys(request.headers ?? {}).map((one) => [one, REDACTED])),
+                body,
+            });
+            const answer = script[`${request.method} ${request.path}`] ?? { status: 404, body: '{"message":"not scripted"}' };
+            const answered = new TextEncoder().encode(answer.body ?? '');
+            const headers = answer.headers ?? {};
+            return {
+                status: answer.status,
+                headers,
+                body: answered,
+                bytesSent: requestBytes({ ...request.headers }, request.body),
+                bytesReceived: payloadBytes(headers) + answered.byteLength,
+                durationMs: 0,
+            };
+        },
+    };
+}

package/dist/operations/makers/capability.d.ts

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

package/dist/operations/makers/capability.js

@@ -0,0 +1,117 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { argv, exit, stdout } from 'node:process';
+import { RECEIPT, answer, asking, given, issue, only, refuse, spend, wordsIn } from "../../core/asking.js";
+import { findTree } from "../../core/tree.js";
+import { CAPABILITIES_AT, SURFACES, isSurface } from "../capabilities.js";
+const TREE = findTree();
+const at = resolve(TREE.at, CAPABILITIES_AT);
+if (!existsSync(at)) {
+    refuse(`${CAPABILITIES_AT} is not there, so this app has nothing reachable to switch. Declare an operation with ` +
+        '`thread create operation` — it writes this table on its way out — or run `thread capabilities`.');
+}
+let table;
+try {
+    table = JSON.parse(readFileSync(at, 'utf8'));
+}
+catch (thrown) {
+    refuse(`${CAPABILITIES_AT} could not be read: ${thrown instanceof Error ? thrown.message : String(thrown)}. ` +
+        'Run `thread capabilities` — it is derived, so it can always be written again.');
+}
+if (table.length === 0) {
+    refuse('this app declares no operation, so there is nothing to switch on or off yet.');
+}
+const mark = (one) => [
+    `  ${one.operation} — ${one.describes}`,
+    `      ${SURFACES.map((each) => `${one.live.includes(each) ? '[on] ' : '[off]'} ${each}`).join('   ')}`,
+    `      ${one.browsable ? 'may be called from a page' : 'server only — it reaches a target that needs a server secret'}`,
+];
+const listing = [`${String(table.length)} operation(s):`, ...table.flatMap(mark)].join('\n');
+const words = wordsIn(['edit']);
+const verb = words[0];
+stdout.write(`${listing}\n`);
+const ASKS = [
+    {
+        key: 'live',
+        says: [
+            'which surfaces are on, comma-separated. Answering nothing switches every',
+            'one of them off, which leaves the operation declared, compiled and proven',
+            'and reachable by nobody — a real thing to want, and said out loud rather',
+            'than refused.',
+        ],
+    },
+];
+const TAKES = ASKS.map((one) => one.key);
+const ASKED = ASKS.flatMap((one) => one.says.map((line, at) => `  ${at === 0 ? `${one.key}:`.padEnd(8) : ' '.repeat(8)}${line}`));
+const method = (nonce) => [
+    '',
+    'what this changes:',
+    '',
+    `  thread create capability edit <operation> ${RECEIPT} ${nonce}`,
+    '',
+    `  ${RECEIPT} is spent by one run and refused if the table moved after it was issued.`,
+    '',
+    `a surface is a way this app is CALLED, and there are ${String(SURFACES.length)}: ${SURFACES.join(', ')}.`,
+    '',
+    '  cli   a command a terminal runs',
+    '  api   a route a request arrives on, and the OpenAPI document written from it',
+    '  mcp   a tool an agent is offered. Switch this off and an AI actor cannot call the operation,',
+    '        while everything else about it goes on working',
+    '',
+    '`edit` asks, one answer per line:',
+    '',
+    ...ASKED,
+    '',
+    'It writes the flag and runs `thread capabilities`, which carries every flag across and rewrites',
+    'the tool list, the OpenAPI document and the client bundle from them.',
+].join('\n');
+const flagged = argv.indexOf(RECEIPT);
+if (verb === undefined && flagged === -1) {
+    const nonce = issue(TREE.at, listing);
+    stdout.write(`${method(nonce)}\n`);
+    stdout.write(`\ncapability: receipt ${nonce} — spent on use, and stale the moment ${CAPABILITIES_AT} changes.\n`);
+    exit(0);
+}
+spend(TREE.at, listing, argv[flagged + 1], CAPABILITIES_AT);
+if (verb !== 'edit') {
+    refuse(`there is nothing called "${verb ?? ''}" to do here — say edit. A capability is derived, so there is none to add`);
+}
+const which = words[1];
+if (which === undefined) {
+    refuse('`edit` takes the name of an operation this app declares');
+}
+const one = table.find((each) => each.operation === which);
+if (one === undefined) {
+    refuse(`\`${which}\` is not an operation this app declares. What is here is ${table.map((each) => each.operation).join(', ')}`);
+}
+const piped = given();
+only(piped, TAKES, 'editing a capability');
+const { ask, shut } = asking(piped);
+const said = (piped.length > 0
+    ? (answer(piped, 'live') ?? '')
+    : await ask('live', `which surfaces are on — ${SURFACES.join(', ')} (now: ${one.live.join(', ') || 'none'}): `)).trim();
+shut();
+const wanted = said
+    .split(',')
+    .map((each) => each.trim().toLowerCase())
+    .filter((each) => each !== '');
+const wrong = wanted.filter((each) => !isSurface(each));
+if (wrong.length > 0) {
+    refuse(`there is no surface called ${wrong.map((each) => `"${each}"`).join(', ')}. There are ${String(SURFACES.length)}: ` +
+        `${SURFACES.join(', ')}. Nothing was written.`);
+}
+const live = SURFACES.filter((each) => wanted.includes(each));
+writeFileSync(at, `${JSON.stringify(table.map((each) => (each.operation === one.operation ? { ...each, live } : each)), null, 2)}\n`);
+const off = SURFACES.filter((each) => !live.includes(each));
+stdout.write(`capability: ${one.operation} is live on ${live.join(', ') || 'nothing'}` +
+    `${off.length === 0 ? '' : `, and off for ${off.join(', ')}`}.\n`);
+for (const what of [['capabilities'], ['docs']]) {
+    const made = spawnSync('npx', ['thread', ...what], { cwd: TREE.at, encoding: 'utf8' });
+    stdout.write(`${`${made.stdout ?? ''}${made.stderr ?? ''}`.trim()}\n`);
+    if (made.status !== 0) {
+        stdout.write(`capability: the flag is written and stands; \`thread ${what.join(' ')}\` refused above.\n`);
+        exit(1);
+    }
+}
+exit(0);

package/dist/operations/makers/trial.d.ts

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