@prestack/thread 0.0.1

package/dist/operations/attach.js

@@ -0,0 +1,414 @@
+import { named } from "../core/scope.js";
+import { quoted } from "../core/rows.js";
+import { PERMITS_AT } from "./access.js";
+import { CAPABILITIES_AT, CLIENT_AT, DECLARED_SEAMS_AT, DISPATCHING_AT, MCP_AT, OPENAPI_AT, SEAMS_AT } from "./capabilities.js";
+import { DISPATCH_AT } from "./dispatch.js";
+import { TRIALS_AT } from "./operations.js";
+import { MEMBERS_LIST, NODES_FILE, OPERATIONS_FILE } from "./operations.js";
+import { SUPPLIES } from "./seams.js";
+const HOME = `node_modules/${named('operations')}/dist`;
+const LISTS = ['declares', 'derives', 'seeds'];
+const VERSION = 1;
+const ROOT = 'operations';
+const NODES_AT = '_threads/nodes.ts';
+const OPERATIONS_AT = '_threads/operations.ts';
+const DESCRIBES = 'Everything this app can be asked to do. Each operation is a named job built from steps, and every one of them runs the same way. Add one with `thread create operation`.';
+export const TAKES = 'What one operation needs before it will run: the shape of its input, what it is expected to cost, and who is allowed to ask for it. Written once when the operation is created, then yours to change.';
+export const WOVEN = 'The operation written out as one function. `thread compile` builds it from the steps declared for it, so nothing here is edited by hand — anything added here is gone the next time it is compiled.';
+const NODES = 'Every kind of step an operation can be built from — a read, a branch, a loop. A step holds no code of its own: the work goes in a file written beside the operation that uses it.';
+const HANDS = 'What each kind of step hands the code inside it to work with. These live in the package rather than in this app, so a step of the same kind means the same thing in every tree.';
+const DISPATCH = 'Every operation runs through here and nowhere else. `thread compile` writes it for this app: before a run starts it checks who is asking, what the run may cost and whether the input is valid, then runs the operation and records what happened.';
+const PROGRAM = 'Every row this package adds to an app, listed in one place so what it put there can be read rather than guessed at. `thread attach` writes back anything missing or edited.';
+const TRIALS = 'What each operation actually did when it was run, recorded rather than written by hand. `thread trials` runs them against their example inputs and keeps the results; `thread trials --check` runs them again and refuses anything that has changed since.';
+const CAPABILITIES = 'Which of this app\'s operations can be reached from outside, and how — as an MCP tool, a terminal command, or a web route. Everything here is worked out from the operations themselves except whether a surface is switched on, which is yours to set.';
+const OPENAPI = 'This app\'s web API written as an OpenAPI document: the route, the verb and the input shape of every operation that answers on the web. Generated rather than written, so it cannot describe a route that is not there.';
+const TOOLS = 'The tools an MCP client is offered: every operation switched on for that surface, with its own sentence and the shape of its input. Switching `mcp` off for an operation is how an agent is told it may not call it.';
+const CLIENT = 'Every operation a page in this app may call. An operation that is switched off is absent from this file rather than listed and disabled, as is any operation needing a credential a browser must not hold.';
+const SAID = {
+    sm_store: 'Reading and writing rows. An operation that requires it is handed get, list, insert, update and remove already bound to whoever asked, so every row it touches is written under the caller the log names.',
+    sm_search: 'Indexing a row and querying an index. Required by an operation that has to find something it cannot address by id.',
+    sm_queue: 'Handing work to something else to run later. Required by an operation that finishes before its effect does.',
+    sm_events: 'Announcing that something happened, to whoever is listening. Required by an operation other parts of an app react to.',
+    sm_clock: 'The current time. Required rather than read off the runtime, because an operation that reads the wall clock directly cannot be replayed and its trial cannot be trusted.',
+    sm_random: 'Randomness. Required for the same reason as the clock: a run nobody can reproduce is a run nobody can check.',
+    sm_vault: 'Resolving a secret by name, for the rare thing that is not a call — signing a webhook, checking a shared token. An operation that reaches a target does not need this: requiring the target hands its nodes calls with the credential already in them, which is the whole point of declaring one.',
+    sm_views: 'Reading through a declared view rather than a table. Required by an operation that reads what somebody else composed.',
+    sm_files: 'Putting a file somewhere, fetching one back, or handing out a signed link to one. Required rather than reached for, because a node that opens a path directly is doing work no record names.',
+};
+const OFFERED = SUPPLIES.map((id) => ({
+    id,
+    at: NODES_AT,
+    describes: SAID[id],
+    version: VERSION,
+}));
+const valued = (one) => {
+    if (typeof one === 'string')
+        return quoted(one);
+    if (Array.isArray(one))
+        return `[${one.map((each) => valued(each)).join(', ')}]`;
+    if (typeof one === 'object' && one !== null) {
+        return `{ ${Object.entries(one).map(([key, held]) => `${key}: ${valued(held)}`).join(', ')} }`;
+    }
+    return String(one);
+};
+export const said = (one, pad) => {
+    const { declares, derives, seeds, ...plain } = one;
+    const lines = [`${pad}{`];
+    for (const [key, held] of Object.entries(plain))
+        lines.push(`${pad}  ${key}: ${valued(held)},`);
+    for (const list of LISTS) {
+        const held = one[list];
+        if (held === undefined)
+            continue;
+        lines.push(`${pad}  ${list}: [`);
+        for (const child of held)
+            lines.push(said(child, `${pad}    `));
+        lines.push(`${pad}  ],`);
+    }
+    return [...lines, `${pad}},`].join('\n');
+};
+const ACCESS = 'Who may ask this app to do what. A row says which operations it permits, on what, to whom, and under what condition. Nothing is permitted by default: an operation no row grants here cannot be run at all.';
+const PERMITS = 'The check compiled from the grants in _threads/access.ts: one branch per grant, so who may ask for what comes from one statement. Nobody edits it, because an edit here widens or narrows access nobody granted. An app that grants nothing permits nothing.';
+const SEAMS = 'What this app hands its operations, written once and then yours. It starts by handing on everything src/_generated/seams.ts settles from your declarations. Replace a seam or add one by naming it in SEAMS: the queue, the events, telemetry, whatever a real deployment needs.';
+const DECLARED_SEAMS = 'The seams your declarations settle. Rows go to the store each target derived, or to memory until one does; who is calling is read off the entity that names the caller; calls leave through http with credentials the vault opens. Nobody edits it: `thread capabilities` writes it again from the rows.';
+const ACCESS_SOURCE = `import type { Grant } from './access.ts'
+
+export const GRANTS: readonly Grant[] = []
+`;
+const shipped = () => ({
+    id: 'shipped',
+    at: `${HOME}/attach.js`,
+    describes: PROGRAM,
+    version: VERSION,
+    declares: [
+        {
+            id: 'operations',
+            at: OPERATIONS_AT,
+            describes: DESCRIBES,
+            version: VERSION,
+        },
+        {
+            id: 'nodes',
+            at: NODES_AT,
+            describes: NODES,
+            version: VERSION,
+        },
+        {
+            id: 'access',
+            at: '_threads/access.ts',
+            describes: ACCESS,
+            version: VERSION,
+        },
+        {
+            id: 'permits',
+            at: PERMITS_AT,
+            describes: PERMITS,
+            version: VERSION,
+            by: 'thread permits',
+            runs: 'thread permits --check',
+        },
+        {
+            id: 'dispatch',
+            at: DISPATCH_AT,
+            describes: DISPATCH,
+            version: VERSION,
+            by: 'thread compile',
+            runs: 'thread compile --check',
+        },
+        {
+            id: 'hands',
+            at: `${HOME}/nodes.js`,
+            describes: HANDS,
+            version: VERSION,
+        },
+        {
+            id: 'trials',
+            at: TRIALS_AT,
+            describes: TRIALS,
+            version: VERSION,
+            by: 'thread trials',
+            runs: 'thread trials --check',
+        },
+        {
+            id: 'capabilities',
+            at: CAPABILITIES_AT,
+            describes: CAPABILITIES,
+            version: VERSION,
+            by: 'thread capabilities',
+            runs: 'thread capabilities --check',
+        },
+        {
+            id: 'openapi',
+            at: OPENAPI_AT,
+            describes: OPENAPI,
+            version: VERSION,
+            by: 'thread capabilities',
+            runs: 'thread capabilities --check',
+        },
+        {
+            id: 'tools',
+            at: MCP_AT,
+            describes: TOOLS,
+            version: VERSION,
+            by: 'thread capabilities',
+            runs: 'thread capabilities --check',
+        },
+        {
+            id: 'client',
+            at: CLIENT_AT,
+            describes: CLIENT,
+            version: VERSION,
+            by: 'thread capabilities',
+            runs: 'thread capabilities --check',
+        },
+        {
+            id: 'dispatching',
+            at: DISPATCHING_AT,
+            describes: 'The operations this app declares, named wherever something reaches one. The framework ships an empty list and each app widens it, so a name written at a call site is accepted only when this app declared an operation by it.',
+            version: VERSION,
+            by: 'thread capabilities',
+            runs: 'thread capabilities --check',
+        },
+        {
+            id: 'seams',
+            at: SEAMS_AT,
+            describes: SEAMS,
+            version: VERSION,
+            by: 'thread capabilities',
+        },
+        {
+            id: 'declared-seams',
+            at: DECLARED_SEAMS_AT,
+            describes: DECLARED_SEAMS,
+            version: VERSION,
+            by: 'thread capabilities',
+            runs: 'thread capabilities --check',
+        },
+        {
+            id: 'nd_read',
+            at: NODES_AT,
+            describes: 'A node that only reads. It is handed the store and the search and nothing else, so it cannot write — the fetch an operation does before it decides anything.',
+            version: VERSION,
+        },
+        {
+            id: 'nd_action',
+            at: NODES_AT,
+            describes: 'A node that changes something — a write, a call out, a spend. It is handed everything, and it is where an operation keeps its effects rather than spreading them across the flow.',
+            version: VERSION,
+        },
+        {
+            id: 'nd_branch',
+            at: NODES_AT,
+            describes: 'A node that chooses. Its first block returns a name, and the way with that name is what runs, so a fork in the flow is visible in the declaration instead of buried in an if.',
+            version: VERSION,
+        },
+        {
+            id: 'nd_each',
+            at: NODES_AT,
+            describes: 'A node that runs once per item, in order, one at a time. Its block is handed a single item and never the collection, so it cannot reorder them or batch them behind your back.',
+            version: VERSION,
+        },
+        {
+            id: 'nd_parallel',
+            at: NODES_AT,
+            describes: 'A step that runs several blocks at once and answers when all of them have. They cannot see each other, so use it for work that does not depend on itself.',
+            version: VERSION,
+        },
+        {
+            id: 'nd_repeat',
+            at: NODES_AT,
+            describes: 'A step that runs its block again until the block says it is done — a retry, or an agent loop. A limit is required, so it cannot run forever.',
+            version: VERSION,
+        },
+        {
+            id: 'nd_stop',
+            at: NODES_AT,
+            describes: 'A step that ends the operation early with an answer. Whatever its block returns becomes the result, and nothing after it runs.',
+            version: VERSION,
+        },
+        ...OFFERED,
+    ],
+});
+const SHIPS = shipped();
+const WHERE = {
+    nodes: { into: OPERATIONS_FILE, list: 'declares' },
+    dispatch: { into: OPERATIONS_FILE, list: 'declares' },
+    access: { into: OPERATIONS_FILE, list: 'declares' },
+    permits: { into: OPERATIONS_FILE, list: 'declares' },
+    'declared-seams': { into: OPERATIONS_FILE, list: 'declares' },
+    trials: { into: OPERATIONS_FILE, list: 'declares' },
+    capabilities: { into: OPERATIONS_FILE, list: 'declares' },
+    openapi: { into: OPERATIONS_FILE, list: 'declares' },
+    tools: { into: OPERATIONS_FILE, list: 'declares' },
+    client: { into: OPERATIONS_FILE, list: 'declares' },
+    dispatching: { into: OPERATIONS_FILE, list: 'declares' },
+    seams: { into: OPERATIONS_FILE, list: 'declares' },
+    hands: { into: NODES_FILE, list: 'declares' },
+};
+const placed = (id) => WHERE[id] ?? { into: NODES_FILE, list: MEMBERS_LIST };
+const NODES_SOURCE = `import type { Threaded } from '../core/thread.ts'
+import type { Node } from './nodes.ts'
+
+export const NODES: Threaded = {
+  id: 'nodes',
+  at: ${quoted(NODES_AT)},
+  describes: ${quoted(NODES)},
+  version: ${String(VERSION)},
+  declares: [],
+}
+
+export const ${MEMBERS_LIST}: readonly Node[] = []
+`;
+const OPERATIONS_SOURCE = `import type { Member, Threaded } from '../core/thread.ts'
+
+export const OPERATIONS: Threaded = {
+  id: 'operations',
+  at: ${quoted(OPERATIONS_AT)},
+  describes: ${quoted(DESCRIBES)},
+  version: ${String(VERSION)},
+  declares: [],
+}
+
+export const ${MEMBERS_LIST}: readonly Member[] = []
+`;
+const SEEDED = {
+    attaches: ['@prestack/thread/derivation/attach'],
+    id: 'operations',
+    declares: [
+        '    {',
+        '      id: \'operations\',',
+        '      at: \'_threads/operations.ts\',',
+        '      describes: \'Everything this app can be asked to do. Each operation is a named job built from steps, and every one of them runs the same way. Add one with `thread create operation`.\',',
+        '      version: 1,',
+        '    },',
+    ].join('\n'),
+};
+const SHIPPED = [
+    {
+        into: 'derivation.ts',
+        list: 'GENERATORS',
+        id: 'capability-generator',
+        source: "  {\n    id: 'capability-generator',\n    at: 'node_modules/@prestack/thread/dist/operations/generators/capability.js',\n    describes: 'Writes what can be reached and how, and refuses it once it has drifted. It reads each operation for its name, what it does and the shape of its input, so adding or renaming one changes what is reachable without anybody editing a list.',\n    version: 1,\n    by: 'thread capabilities',\n    runs: 'thread capabilities --check',\n  },",
+    },
+    {
+        into: 'derivation.ts',
+        list: 'GENERATORS',
+        id: 'capability-noun',
+        source: "  {\n    id: 'capability-noun',\n    at: 'node_modules/@prestack/thread/dist/operations/makers/capability.js',\n    describes: 'Reads and changes what this app exposes. `thread create capability` lists every operation with the surfaces it answers on, and `edit` switches one on or off.',\n    version: 1,\n    by: 'thread create capability',\n  },",
+    },
+    {
+        into: 'derivation.ts',
+        list: 'GENERATORS',
+        id: 'trial-noun',
+        source: "  {\n    id: 'trial-noun',\n    at: 'node_modules/@prestack/thread/dist/operations/makers/trial.js',\n    describes: 'Runs one operation against an input you supply, and records what happened. `thread run trial <operation>` asks for that input, because what to run an operation on is the one thing nothing else can work out for you.',\n    version: 1,\n    by: 'thread run trial',\n  },",
+    },
+    {
+        into: 'derivation.ts',
+        list: 'GENERATORS',
+        id: 'seed-generator',
+        source: "  {\n    id: 'seed-generator',\n    at: 'node_modules/@prestack/thread/dist/operations/generators/seed.js',\n    describes: 'Writes every file an operation puts on disk. The wrapper around each step comes from the rows; the code inside it is yours and is put back untouched. Anything that no longer matches what it writes is refused, so a step cannot be added by editing the file.',\n    version: 1,\n    by: 'thread seed',\n    runs: 'thread seed --check',\n  },",
+    },
+    {
+        into: 'derivation.ts',
+        list: 'GENERATORS',
+        id: 'compile-generator',
+        source: "  {\n    id: 'compile-generator',\n    at: 'node_modules/@prestack/thread/dist/operations/generators/compile.js',\n    describes: 'Turns an operation\\'s steps into one function: each block bound where it is used, and each branch or loop written out as the real thing. What it writes imports nothing from this framework, so what ships is plain code.',\n    version: 1,\n    by: 'thread compile',\n    runs: 'thread compile --check',\n  },",
+    },
+    {
+        into: 'derivation.ts',
+        list: 'GENERATORS',
+        id: 'permits-generator',
+        source: "  {\n    id: 'permits-generator',\n    at: 'node_modules/@prestack/thread/dist/operations/generators/permits.js',\n    describes: 'Writes the check this app runs before any operation — one branch per grant, so who may ask for what comes from one statement rather than being repeated in every handler. It refuses a grant it cannot check honestly, such as one that would admit a caller nobody authenticated.',\n    version: 1,\n    by: 'thread permits',\n    runs: 'thread permits --check',\n  },",
+    },
+    {
+        into: 'derivation.ts',
+        list: 'GENERATORS',
+        id: 'grant-generator',
+        source: "  {\n    id: 'grant-generator',\n    at: 'node_modules/@prestack/thread/dist/operations/generators/grant.js',\n    describes: 'Records who may ask this app to do what. Run with nothing, it lists every operation and every grant already written. It builds the condition one answer at a time, offering only what the answer before it allows, so an impossible comparison is refused as it is typed.',\n    version: 1,\n    by: 'thread grant',\n  },",
+    },
+    {
+        into: 'derivation.ts',
+        list: 'GENERATORS',
+        id: 'operation-noun',
+        source: "  {\n    id: 'operation-noun',\n    at: 'node_modules/@prestack/thread/dist/operations/generators/operation.js',\n    describes: 'Declares something this app can be asked to do, and the steps it is done in. This row is what makes `operation` one of the things `thread create` offers — the nouns are not a list inside the command, but rows like this one.',\n    version: 1,\n    by: 'thread create operation',\n  },",
+    },
+    {
+        into: 'derivation.ts',
+        list: 'GENERATORS',
+        id: 'trial-generator',
+        source: "  {\n    id: 'trial-generator',\n    at: 'node_modules/@prestack/thread/dist/operations/generators/trial.js',\n    describes: 'Records what an operation does, and refuses it once it has changed. It runs the compiled operation through this app\\'s own dispatch, so what is checked is the code that ships. Time and randomness are pinned, so a run can be repeated.',\n    version: 1,\n    by: 'thread trials',\n    runs: 'thread trials --check',\n  },",
+    },
+];
+export const ATTACH = {
+    attaches: SEEDED.attaches,
+    id: SEEDED.id,
+    declares: SEEDED.declares,
+    writes: [
+        { file: OPERATIONS_FILE, source: OPERATIONS_SOURCE },
+        { file: NODES_FILE, source: NODES_SOURCE },
+        { file: 'access.ts', source: ACCESS_SOURCE },
+    ],
+    retires: [
+        {
+            into: 'operations.ts',
+            list: 'declares',
+            id: 'reference',
+            made: `${ROOT}/_docs.md`,
+            why: `the page stating what this app declares is written by \`${named('knowledge')}\` now, at docs.md, and it states every node rather than operations alone — a package documenting what another package declares would be one package authoring another's`,
+        },
+        {
+            into: 'derivation.ts',
+            list: 'GENERATORS',
+            id: 'create-generator',
+            why: '`thread create` is a command of the CLI itself now, so no row declares it. This package still makes operations, through the `operation-noun` row beside this one',
+        },
+        {
+            into: 'operations.ts',
+            list: 'declares',
+            id: 'identity',
+            made: `src/identity.${'ts'}`,
+            why: 'who is calling is answered in `src/seams.ts` now, beside the store it reads the caller\'s row from. One derived file says both, because both are read off the same rows',
+        },
+        {
+            into: 'operations.ts',
+            list: 'declares',
+            id: 'store',
+            made: `src/store.${'ts'}`,
+            why: 'where rows go is decided in `src/seams.ts` now, read off the targets this app declares. A second file that only re-exported one name said nothing the seams did not',
+        },
+        {
+            into: 'operations.ts',
+            list: 'declares',
+            id: 'rules-gate',
+            made: `src/rules.${'ts'}`,
+            why: '`rules` is what this app refuses, declared in _threads/rules.ts with `thread create rule`. Who may ask for what is `permits`, compiled from the grants and handed to dispatch by src/_generated/seams.ts, so a second file wearing the word said nothing the grants did not',
+        },
+        {
+            into: 'derivation.ts',
+            list: 'GENERATORS',
+            id: 'rules-generator',
+            why: 'the check compiled from the grants is `permits`, and `thread permits` writes it now, through the `permits-generator` row beside this one. A generator called `rules` read as the app\'s own rules, which are declared in _threads/rules.ts with `thread create rule`',
+        },
+        {
+            into: NODES_FILE,
+            list: MEMBERS_LIST,
+            id: 'sm_http',
+            why: 'a call goes to a place, and a place is a target — declare it with `thread create target` and require that instead. Asking for a bare transport is what made an operation impossible to try, because nothing said where it went',
+        },
+        {
+            into: NODES_FILE,
+            list: MEMBERS_LIST,
+            id: 'sm_llm',
+            why: 'a model is reached over https like any other vendor, so it is an `ht_` target with its calls declared beside it. Nothing was lost: its address and its key are now under the same rules as every other credential, and an operation that asks a model can now be tried',
+        },
+    ],
+    rows: [
+        ...(SHIPS.declares ?? [])
+            .filter((one) => one.id !== ROOT)
+            .map((one) => {
+            const where = placed(one.id);
+            return { into: where.into, list: where.list, id: one.id, source: said(one, where.list === 'declares' ? '    ' : '  ') };
+        }),
+        ...SHIPPED,
+    ],
+};

package/dist/operations/capabilities.d.ts

@@ -0,0 +1,37 @@
+export declare const SURFACES: readonly ["cli", "api", "mcp"];
+export type Surface = (typeof SURFACES)[number];
+export declare const isSurface: (one: string) => one is Surface;
+export declare const CAPABILITIES_AT = "operations/_capabilities.json";
+export declare const CLIENT_AT = "operations/_client.ts";
+export declare const DISPATCHING_AT = "app/_generated/dispatching.ts";
+export declare const routeAt: (operation: string) => string;
+export declare const ROUTE = "The file that answers a request for this one operation. It imports the operation by name, hands it to this app's own dispatch with the seams and the caller its seams file supplies, and answers with the result \u2014 or with the status matching whatever dispatch refused it for. One per operation rather than one for all of them: a route that looked its operation up by a name off the path would hand dispatch something no check had ever seen, which reads exactly like a name that was checked. Switching the `api` surface off in the capabilities table stops this file being written at all, so the operation stops being served rather than being served and turned away.";
+export declare const SEAMS_AT = "src/seams.ts";
+export declare const DECLARED_SEAMS_AT = "src/_generated/seams.ts";
+export declare const OPENAPI_AT = "operations/_openapi.json";
+export declare const MCP_AT = "operations/_mcp.json";
+export interface Capability {
+    readonly operation: string;
+    readonly describes: string;
+    readonly requires: readonly string[];
+    readonly nodes: readonly string[];
+    readonly input: unknown;
+    readonly live: readonly Surface[];
+    readonly browsable: boolean;
+    readonly local: boolean;
+    readonly mcp: {
+        readonly name: string;
+        readonly description: string;
+        readonly inputSchema: unknown;
+    };
+    readonly cli: {
+        readonly invocation: string;
+        readonly describes: string;
+    };
+    readonly api: {
+        readonly method: 'GET' | 'POST';
+        readonly path: string;
+    };
+}
+export declare const reachable: (one: Capability, surface: Surface) => boolean;
+export declare function switched(text: string | undefined): ReadonlyMap<string, readonly Surface[]>;

package/dist/operations/capabilities.js

@@ -0,0 +1,35 @@
+export const SURFACES = ['cli', 'api', 'mcp'];
+export const isSurface = (one) => SURFACES.includes(one);
+export const CAPABILITIES_AT = 'operations/_capabilities.json';
+export const CLIENT_AT = 'operations/_client.ts';
+export const DISPATCHING_AT = 'app/_generated/dispatching.ts';
+export const routeAt = (operation) => `app/operations/${operation}/route.ts`;
+export const ROUTE = 'The file that answers a request for this one operation. It imports the operation by name, hands it to this app\'s own dispatch with the seams and the caller its seams file supplies, and answers with the result — or with the status matching whatever dispatch refused it for. One per operation rather than one for all of them: a route that looked its operation up by a name off the path would hand dispatch something no check had ever seen, which reads exactly like a name that was checked. Switching the `api` surface off in the capabilities table stops this file being written at all, so the operation stops being served rather than being served and turned away.';
+export const SEAMS_AT = 'src/seams.ts';
+export const DECLARED_SEAMS_AT = 'src/_generated/seams.ts';
+export const OPENAPI_AT = 'operations/_openapi.json';
+export const MCP_AT = 'operations/_mcp.json';
+export const reachable = (one, surface) => one.live.includes(surface);
+export function switched(text) {
+    const found = new Map();
+    if (text === undefined || text.trim() === '')
+        return found;
+    let held;
+    try {
+        held = JSON.parse(text);
+    }
+    catch {
+        return found;
+    }
+    if (!Array.isArray(held))
+        return found;
+    for (const one of held) {
+        if (typeof one !== 'object' || one === null)
+            continue;
+        const row = one;
+        if (typeof row.operation !== 'string' || !Array.isArray(row.live))
+            continue;
+        found.set(row.operation, row.live.filter((each) => typeof each === 'string' && isSurface(each)));
+    }
+    return found;
+}

package/dist/operations/cost.d.ts

@@ -0,0 +1,14 @@
+export interface CostAmount {
+    readonly usdMicroCents: number;
+    readonly chargedMicroCents: number;
+    readonly currency: string;
+    readonly meter: string;
+}
+export declare class InvalidCostError extends Error {
+    constructor(message: string);
+}
+export declare function assertValidCost(cost: CostAmount): void;
+export declare const MICRO_CENTS_PER_CENT = 1000000;
+export declare const MICRO_CENTS_PER_UNIT = 100000000;
+export declare function toMicroCents(amount: number): number;
+export declare function fromMicroCents(microCents: number): number;

package/dist/operations/cost.js

@@ -0,0 +1,37 @@
+export class InvalidCostError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidCostError';
+    }
+}
+function assertIntegerMicroCents(value, field) {
+    if (!Number.isFinite(value) || !Number.isInteger(value)) {
+        throw new InvalidCostError(`${field} must be an integer number of micro-cents, received ${value}. ` +
+            'Convert before recording — never round.');
+    }
+    if (value < 0)
+        throw new InvalidCostError(`${field} must not be negative, received ${value}`);
+}
+export function assertValidCost(cost) {
+    assertIntegerMicroCents(cost.usdMicroCents, 'usdMicroCents');
+    assertIntegerMicroCents(cost.chargedMicroCents, 'chargedMicroCents');
+    if (typeof cost.currency !== 'string' || cost.currency.trim() === '') {
+        throw new InvalidCostError('cost.currency is required and has no default — resolve it from real data (DATA.md §8)');
+    }
+    if (!/^[A-Z]{3}$/.test(cost.currency)) {
+        throw new InvalidCostError(`cost.currency must be an ISO-4217 code, received "${cost.currency}"`);
+    }
+    if (typeof cost.meter !== 'string' || cost.meter.trim() === '') {
+        throw new InvalidCostError('cost.meter is required — a cost with no meter cannot be quota-checked');
+    }
+}
+export const MICRO_CENTS_PER_CENT = 1_000_000;
+export const MICRO_CENTS_PER_UNIT = 100_000_000;
+export function toMicroCents(amount) {
+    if (!Number.isFinite(amount))
+        throw new InvalidCostError(`cannot convert ${amount} to micro-cents`);
+    return Math.round(amount * MICRO_CENTS_PER_UNIT);
+}
+export function fromMicroCents(microCents) {
+    return microCents / MICRO_CENTS_PER_UNIT;
+}

package/dist/operations/dispatch.d.ts

@@ -0,0 +1,14 @@
+export declare const DISPATCH_AT = "operations/_dispatch.ts";
+export declare const dispatched: (reached: Readonly<Record<string, {
+    readonly reach: string;
+    readonly address: string | null;
+    readonly sends: readonly {
+        readonly secret: string;
+        readonly header: string;
+        readonly prefix: string;
+    }[];
+    readonly calls: Readonly<Record<string, {
+        readonly method: string;
+        readonly path: string;
+    }>>;
+}>>) => string;