@idleware/ringi 0.0.0-stage → 0.1.0

package/target/esm/cli/operator.js

@@ -0,0 +1,147 @@
+// operator: what the human runs in a terminal: where things stand, sessions, hubs and rooms. Each command parses its
+// arguments, calls app operations and prints the result.
+import fs from 'node:fs';
+import * as Hubs from '../app/hubs.js';
+import * as Overview from '../app/overview.js';
+import * as Rooms from '../app/rooms.js';
+import { oneLine, render } from '../app/view.js';
+import { config } from '../app/context.js';
+import { withSizes } from '../app/room.js';
+import { fail, short, sleep } from '../lib/index.js';
+import { attachments, dump, flag, list, opt, out, textOf } from './args.js';
+import { taskLine } from './shared.js';
+// --- where things stand, sessions, forget ---
+export const sessionLine = (s) => `${s.agent.padEnd(12)} ${s.liveness.padEnd(8)} ${(s.product ?? '?').padEnd(7)} ${s.handle}${s.scope ? `  scope: ${s.scope}` : ''}`;
+export const where = async (o) => {
+    const H = Hubs.hubOf(opt(o, 'hub'));
+    const w = Overview.where(H, opt(o, 'room') ?? config().room);
+    out(`hub ${H.name}: ${H.d.store.type} store, ${H.contract.trust} senders, contract ${H.contract.version}, protocol ${H.contract.protocol}${H.contract.capabilities?.length ? `, ${H.contract.capabilities.join(' ')}` : ''}`);
+    const R = w.room;
+    if (!R)
+        return out('no current room: ringi room create <id> | ringi room switch <id>');
+    out(`room ${R.name}${R.archived ? ' (archived, read-only)' : ''}, genesis ${short(R.genesis)}, profile ${R.profile.name}; members: ${Object.entries(R.members).map(([id, i]) => i.role === 'root' ? `${id} (root)` : id).join(', ')}`);
+    out(w.sessions.length ? `sessions:\n${w.sessions.map(s => `  ${sessionLine(s)}`).join('\n')}` : 'sessions: none joined');
+    out(w.work.length ? `open work:\n${w.work.map(t => `  ${taskLine(t)}`).join('\n')}` : 'open work: none');
+    if (w.proposals.length)
+        out(`open proposals:\n${w.proposals.map(x => `  ${short(x.proposal.id)} ${x.state} → ${x.decider}  ${x.proposal.subject}`).join('\n')}`);
+    const n = Number(opt(o, 'n') ?? (flag(o, 'short') ? 10 : 5));
+    out(`last ${Math.min(n, w.messages.length)} of ${w.messages.length} messages:`);
+    const show = (all, m) => out(flag(o, 'short') ? `  ${oneLine(m)}` : `\n${render(all, m, { max: 2000, files: () => withSizes(R, m) })}`);
+    for (const m of w.messages.slice(-n))
+        show(w.all, m);
+    if (!flag(o, 'follow'))
+        return;
+    out('following; new messages appear as they land (Ctrl-C to stop)');
+    const seen = new Set(w.all.keys());
+    for (;;) {
+        await sleep(Number(opt(o, 'interval') ?? 2) * 1000);
+        const now = Overview.arrived(H, R, seen);
+        for (const m of now.messages)
+            show(now.all, m);
+    }
+};
+export const sessions = (o) => {
+    if (o._[0] === 'forget') {
+        const handle = o._[1] ?? fail('usage: ringi sessions forget <handle>');
+        Overview.forgetSession(handle);
+        return out(`forgot session ${handle}; its seat is free`);
+    }
+    const ss = Overview.sessions();
+    if (flag(o, 'json'))
+        return dump(ss);
+    if (!ss.length)
+        return out('no sessions');
+    for (const s of ss)
+        out(`${s.hub}/${s.room}  ${sessionLine(s)}`);
+};
+export const forget = (o) => {
+    const [name, id] = (o._[0] ?? '').split('/');
+    if (!name || !id)
+        fail('usage: ringi forget <room>/<log>');
+    const H = Hubs.hubOf(opt(o, 'hub'));
+    const n = Rooms.forgetLog(H, Rooms.roomIn(H, name), id);
+    out(`forgot the accepted history of ${name}/${id} for ${n} reader(s); the next read accepts what is there now`);
+};
+// --- hubs and rooms ---
+export const hub = (o) => {
+    const [sub, arg] = o._;
+    if (!sub || sub === 'list') {
+        for (const h of Hubs.hubs())
+            out(`${h.current ? '*' : ' '} ${h.name.padEnd(12)} ${h.store}, ${h.trust}, contract ${h.contract}, ${h.rooms} room(s)${h.remote ? `  remote ${h.remote}` : ''}  ${h.dir}`);
+        return;
+    }
+    if (sub === 'create') {
+        const r = Hubs.create(arg ?? '', { signed: flag(o, 'signed'), url: opt(o, 'url') });
+        if (!r.add)
+            return out(`created hub ${arg} (${r.H.dir})`);
+        return out(`created signed hub ${arg}${r.H.d.store.remote ? `, published to ${r.H.d.store.remote}` : ''}. Its root key stays on this machine (${r.rootKey}).
+Give every machine that joins it, out of band:
+  ${r.add}`);
+    }
+    if (sub === 'switch') {
+        Hubs.use(arg ?? fail('usage: ringi hub switch <name>'));
+        return out(`current hub: ${arg}; agents keep their own rooms`);
+    }
+    if (sub === 'add') {
+        const H = Hubs.add(arg ?? '', o._[2] ?? '', { root: opt(o, 'root'), genesis: opt(o, 'genesis') });
+        return out(`added signed hub ${arg} from ${o._[2]}: contract ${H.contract.version}, ${Rooms.rooms(H).length} room(s), root pinned`);
+    }
+    if (sub === 'amend') {
+        const H = Hubs.hubOf(opt(o, 'hub'));
+        const files = list(o, 'attach').flatMap(attachments).map(e => ({ path: e.path, content: fs.readFileSync(e.file) }));
+        const r = Hubs.amend(H, { text: textOf(o), set: list(o, 'set'), authority: opt(o, 'authority'), files });
+        return out(`amended hub ${H.name}: contract ${r.version}; rooms keep their base until ringi room rebase-contract <room>`);
+    }
+    fail(`unknown: hub ${sub}`);
+};
+export const roomCmd = (o) => {
+    const [sub, arg] = o._;
+    const H = Hubs.hubOf(opt(o, 'hub'));
+    if (!sub || sub === 'list') {
+        const rs = Rooms.rooms(H, { archived: flag(o, 'archived') });
+        for (const r of rs.filter(r => !r.archived))
+            out(`${r.current ? '*' : ' '} ${r.name.padEnd(16)} ${r.members} member(s), ${r.active} active session(s), profile ${r.profile}  genesis ${short(r.genesis)}`);
+        for (const r of rs.filter(r => r.archived))
+            out(`  ${r.name.padEnd(16)} archived, read-only`);
+        if (!rs.length && !flag(o, 'archived'))
+            out(`no rooms in hub ${H.name}: ringi room create <id>`);
+        return;
+    }
+    if (sub === 'create') {
+        const r = Rooms.create(H, arg ?? '', { profile: opt(o, 'profile') });
+        return out(`created room ${arg} in hub ${H.name} with profile ${r.profile}; it is the current room. In each chat that should take part, say: "join ${arg} as <id>; <what to accept>"`);
+    }
+    if (sub === 'switch') {
+        const R = Rooms.use(H, arg ?? fail('usage: ringi room switch <id>'));
+        return out(`current room: ${H.name}/${R.name}; agents keep their own rooms`);
+    }
+    if (sub === 'admit') {
+        const R = Rooms.roomIn(H, opt(o, 'room'));
+        Rooms.admit(H, R, arg ?? fail('usage: ringi room admit <agent> <public key|file>'), o._[2] ?? fail('usage: ringi room admit <agent> <public key|file>'));
+        return out(`admitted ${arg} to ${H.name}/${R.name}: its signed messages are accepted from now on; it can join`);
+    }
+    if (sub === 'remove') {
+        const R = Rooms.roomIn(H, opt(o, 'room'));
+        Rooms.remove(H, R, arg ?? fail('usage: ringi room remove <agent>'));
+        return out(`removed ${arg} from ${R.name}: it can no longer write or be woken there; returning needs a fresh join`);
+    }
+    if (sub === 'archive') {
+        const R = Rooms.roomIn(H, arg ?? fail('usage: ringi room archive <id>'));
+        const name = Rooms.archive(H, R);
+        return out(`archived ${R.name} as ${name}: read-only, wakes nobody; its sessions end. Read it with --room ${name}`);
+    }
+    if (sub === 'delete') {
+        const R = Rooms.roomIn(H, arg ?? fail('usage: ringi room delete <id> --yes'));
+        if (!flag(o, 'yes'))
+            fail(`deleting ${R.name} removes its history from the hub for good. Run again with --yes, or archive it instead`);
+        Rooms.erase(H, R);
+        return out(`deleted room ${R.name}; sessions bound to it will be told it no longer exists`);
+    }
+    if (sub === 'rebase-contract') {
+        const R = Rooms.roomIn(H, arg ?? fail('usage: ringi room rebase-contract <id>'));
+        Rooms.rebase(H, R);
+        return out(`room ${R.name} now follows the hub contract at ${short(H.main)} (${H.contract.version})`);
+    }
+    fail(`unknown: room ${sub}`);
+};
+//# sourceMappingURL=operator.js.map

package/target/esm/cli/session.js

@@ -0,0 +1,39 @@
+// Session interface: the operator's words become typed app requests.
+import * as Session from '../app/session.js';
+import { fail } from '../lib/index.js';
+import { opt, out } from './args.js';
+import { showInbox } from './agent.js';
+import { taskLine } from './shared.js';
+export const briefing = (s) => {
+    const r = Session.briefing(s);
+    out(`${s.agent} in ${s.hub}/${s.room}; scope: ${s.scope ?? 'none recorded; ask the operator what to accept'}`);
+    out('agent commands: ringi agent inbox | reply <id> … | send … | tasks | proposals | whoami. A turn: inbox, your part, replies, end the turn. Never block on a peer.');
+    if (!r.tasks.length)
+        out(`no open work (profile ${r.actor.R.profile.name}; tasks --all for everything)`);
+    for (const task of r.tasks)
+        out(taskLine(task));
+    showInbox(r.actor, r.inbox, { _: [] });
+};
+export const join = (o) => {
+    const [hub, room] = o._;
+    if (!hub || !room)
+        fail('usage: ringi join <hub> <room> [--as <id>] [--scope "<what the operator delegates>"]');
+    const r = Session.join({ hub, room, agent: opt(o, 'as'), scope: opt(o, 'scope') });
+    if (r.key) {
+        out(`${r.agent}'s key on this machine (${r.key.fingerprint}). Ask the root to admit it, then join again:\n  ringi room admit ${r.agent} '${r.key.publicKey}' --hub ${r.hub} --room ${r.room}`);
+        process.exitCode = 3;
+        return;
+    }
+    out(`joined ${r.hub}/${r.room} as ${r.agent}`);
+    briefing(r.session);
+};
+export const resume = (o) => briefing(Session.resume(o._[0]));
+export const stop = () => {
+    const s = Session.stop();
+    out(`stopped: ${s.agent} keeps its seat in ${s.hub}/${s.room} and reacts to nothing until the operator says "continue"`);
+};
+export const leave = () => {
+    const s = Session.leave();
+    out(`left ${s.hub}/${s.room}: the seat of ${s.agent} is free; ${s.agent} stays a member until the operator removes it`);
+};
+//# sourceMappingURL=session.js.map

package/target/esm/cli/shared.js

@@ -0,0 +1,143 @@
+// shared: commands the operator and agents both run: messages, threads, work, signals, proposals and grants. Each
+// parses its arguments, calls one app operation and prints the result.
+import fs from 'node:fs';
+import path from 'node:path';
+import * as Budget from '../app/budget.js';
+import * as Room from '../app/room.js';
+import { checkPath, withSizes } from '../app/room.js';
+import { asJson, oneLine, render } from '../app/view.js';
+import { fail, note, short, when, words } from '../lib/index.js';
+import { attachments, dump, flag, list, opt, out, textOf } from './args.js';
+const sendInput = (o) => ({ text: textOf(o), to: words(opt(o, 'to')), all: flag(o, 'all'), task: flag(o, 'task'),
+    state: opt(o, 'state'), assign: opt(o, 'assign') ? words(opt(o, 'assign')) : undefined, roles: opt(o, 'roles'), grant: opt(o, 'grant'),
+    files: list(o, 'attach').flatMap(attachments) });
+const sent = (r) => out(`sent ${short(r.id)} to ${r.to.join(', ')}${r.files ? ` with ${r.files} file(s)` : ''}`);
+export const send = (a, o) => sent(Room.send(a, { ...sendInput(o), re: opt(o, 're') }));
+export const reply = (a, o) => sent(Room.send(a, { ...sendInput(o), re: o._[0] ?? fail('usage: reply <msg> -m <text> …'), reply: true }));
+export const read = (a, o) => {
+    const { all, m, replies, marks } = Room.message(a, o._[0] ?? fail('usage: read <msg>'));
+    if (flag(o, 'json'))
+        return dump(asJson(m));
+    out(render(all, m, { files: () => withSizes(a.R, m) }));
+    if (replies.length)
+        out(`replies: ${replies.map(x => `${short(x.id)} (${x.from})`).join(', ')}`);
+    if (marks)
+        out(Object.entries(marks).map(([mark, who]) => `${mark} by: ${who.join(', ')}`).join('; '));
+};
+export const thread = (a, o) => {
+    const { all, msgs } = Room.thread(a, o._[0] ?? fail('usage: thread <msg>'));
+    if (flag(o, 'json'))
+        return dump(msgs.map(asJson));
+    out(msgs.map(m => render(all, m, { files: () => withSizes(a.R, m) })).join('\n\n'));
+};
+export const taskLine = (t) => {
+    const roles = Object.keys(t.roles).length ? ` [${Object.entries(t.roles).map(([id, label]) => `${id}=${label}`).join(' ')}]` : '';
+    return `${short(t.id)}  ${t.state.padEnd(14)} ${t.requester} → ${t.assignees.join(',') || '(open)'}${roles}${t.taken.length ? ` taken by ${t.taken.join(',')}` : ''}${t.grant ? ` grant ${short(t.grant)}` : ''}  ${when(Date.parse(t.at) / 1000).slice(5)} by ${t.by}  ${t.subject}`;
+};
+export const tasks = (a, o) => {
+    const { views } = Room.tasks(a, { all: flag(o, 'all') });
+    if (flag(o, 'json'))
+        return dump(views);
+    if (!views.length)
+        return out(flag(o, 'all') ? 'no work' : `no open work (profile ${a.R.profile.name}; tasks --all for everything)`);
+    for (const t of views)
+        out(taskLine(t));
+};
+export const log = (a, o) => {
+    const msgs = Room.log(a, { agent: opt(o, 'agent'), all: flag(o, 'all'), n: Number(opt(o, 'n') ?? 20) });
+    if (flag(o, 'json'))
+        return dump(msgs.map(asJson));
+    for (const m of msgs)
+        out(oneLine(m));
+};
+export const cat = (a, o) => {
+    const ref = o._[0] ?? fail('usage: cat <msg> [<path>]');
+    const p = o._[1] ?? (() => {
+        const { m } = Room.files(a, ref);
+        return m.files.length === 1 ? m.files[0].path : fail(`${short(m.id)} has ${m.files.length} files; name one: ${m.files.map(f => f.path).join(', ')}`);
+    })();
+    process.stdout.write(Room.files(a, ref, p).files[0].content);
+};
+export const get = (a, o) => {
+    const { m, files } = Room.files(a, o._[0] ?? fail('usage: get <msg> [-o <dir>]'));
+    const dir = path.resolve(opt(o, 'out') ?? short(m.id));
+    for (const f of files) {
+        const dest = path.join(dir, checkPath(f.path));
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.writeFileSync(dest, f.content);
+        out(dest);
+    }
+};
+export const who = (a) => {
+    for (const x of Room.members(a))
+        out(`${x.id.padEnd(12)} ${x.role.padEnd(7)} ${String(x.messages).padStart(4)} msg${x.card ? `  ${x.card}` : ''}`);
+};
+export const signals = (a, o) => {
+    const res = Room.signals(a, { repair: flag(o, 'repair') });
+    if (res.repaired !== null)
+        out(`restored ${res.repaired} signal(s) of ${a.me}`);
+    for (const x of res.alarms)
+        note(`ALARM ${x}`);
+    if (flag(o, 'json'))
+        return dump(res.checked);
+    const at = (c) => res.all.get(c.target)?.time ?? 0;
+    const sorted = [...res.checked].sort((x, y) => at(x) - at(y));
+    const shown = flag(o, 'all') ? sorted : sorted.slice(-Number(opt(o, 'n') ?? 20));
+    if (!shown.length)
+        return out('no signals');
+    for (const c of shown)
+        out(`${short(c.target)}  ${when(at(c)).slice(5)}  ${c.actor.padEnd(10)} ${c.signal.padEnd(20)} ${c.ok ? res.all.get(c.target)?.subject ?? '' : `MISMATCH: ${c.why}`}`);
+};
+export const profileCmd = ({ R }, o) => {
+    if (flag(o, 'json'))
+        return dump(R.profile);
+    const P = R.profile;
+    out(`room ${R.name} follows profile ${P.name}${P.description ? `: ${P.description}` : ''}`);
+    out(`opens with Kind: ${P.opens}; states: ${P.states.join(', ')}; initial ${P.initial}; terminal ${P.terminal.join(', ')}${P.waiting ? `; waiting ${P.waiting}` : ''}`);
+    for (const [k, v] of Object.entries(P.rules))
+        out(`  ${k.padEnd(18)} ${(v ?? []).join(', ')}`);
+};
+// --- decisions and budgets ---
+export const propose = (a, o) => {
+    const decider = opt(o, 'decider') ?? fail('--decider <id> is required: who decides (operator, or someone with authority in the hub contract)');
+    const r = Budget.propose(a, { text: textOf(o), decider, reviewers: words(opt(o, 'reviewers')), budget: opt(o, 'budget'), due: opt(o, 'due'),
+        supersedes: opt(o, 'supersedes'), files: list(o, 'attach').flatMap(attachments) });
+    out(`proposed ${short(r.id)} to ${r.to.join(', ') || 'the room'}; decider ${decider}${r.budget ? `, budget ${Budget.budgetText(r.budget)}` : ''}`);
+};
+export const stamp_ = (a, o) => {
+    const s = o._[1] ?? '';
+    if (!Budget.STAMPS.includes(s))
+        fail(`usage: stamp <proposal> ${Budget.STAMPS.join('|')} -m <reason>`);
+    const r = Budget.stamp(a, o._[0] ?? fail('name the proposal'), s, textOf(o));
+    out(`stamped ${short(r.proposal.id)} ${s}: ${short(r.id)}`);
+};
+export const decide = (a, o) => {
+    const d = o._[1] ?? '';
+    if (!Budget.DECISIONS.includes(d))
+        fail(`usage: decide <proposal> ${Budget.DECISIONS.join('|')} -m <reason>`);
+    const r = Budget.decide(a, o._[0] ?? fail('name the proposal'), d, textOf(o));
+    out(`${d} ${short(r.proposal.id)}: ${short(r.id)}${r.budget ? `; grant ${short(r.id)} with ${Budget.budgetText(r.budget)}. Work spends it with --grant ${short(r.id)}` : ''}`);
+};
+export const proposals = (a, o) => {
+    const { proposals: ps, views } = Budget.proposals(a, { all: flag(o, 'all') });
+    if (flag(o, 'json'))
+        return dump(views);
+    if (!ps.length)
+        return out(flag(o, 'all') ? 'no proposals' : 'no open proposals (proposals --all for everything)');
+    for (const x of ps) {
+        const st = x.reviewers.map(r => `${r}:${x.stamps[r]?.stamp ?? '-'}`).join(' ');
+        out(`${short(x.proposal.id)}  ${x.state.padEnd(10)} ${x.proposal.from} → ${x.decider}${x.budget ? `  [${Budget.budgetText(x.budget)}]` : ''}${st ? `  ${st}` : ''}  ${x.proposal.subject}`);
+    }
+};
+export const grants = (a, o) => {
+    const gs = Budget.grants(a);
+    if (flag(o, 'json'))
+        return dump(gs);
+    if (!gs.length)
+        return out('no grants');
+    for (const g of gs) {
+        const u = g.usage;
+        out(`${short(g.grant)}  ${g.revoked ? 'revoked ' : u.left ? 'active  ' : 'spent   '} runs ${u.runs}/${g.budget.runs}, open ${u.open}${u.uncertain ? `, uncertain ${u.uncertain}` : ''}, ${u.seconds}s used, ≤${g.budget['run-seconds']}s a run, concurrency ${g.budget.concurrency}  ${g.subject}`);
+    }
+};
+//# sourceMappingURL=shared.js.map

package/target/esm/cli/skill.js

@@ -0,0 +1,54 @@
+// skill: installs the agent skill for Claude Code, Codex and Cursor.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { about } from '../app/context.js';
+import { fail } from '../lib/index.js';
+import { flag, out } from './args.js';
+// --- skill ---
+export const SKILL = path.join(about().resources, 'skill', 'ringi');
+export const skillTargets = (project) => {
+    const base = project ? process.cwd() : os.homedir();
+    return [path.join(base, '.claude', 'skills', 'ringi'), path.join(base, '.agents', 'skills', 'ringi')];
+};
+export const skill = (o) => {
+    const sub = o._[0];
+    const same = (dir) => {
+        try {
+            return fs.readFileSync(path.join(dir, 'SKILL.md'), 'utf8') === fs.readFileSync(path.join(SKILL, 'SKILL.md'), 'utf8');
+        }
+        catch {
+            return false;
+        }
+    };
+    if (sub === 'install') {
+        for (const dir of skillTargets(flag(o, 'project'))) {
+            fs.mkdirSync(dir, { recursive: true });
+            fs.cpSync(SKILL, dir, { recursive: true });
+            out(`installed ${dir}`);
+        }
+        return out(`ringi's home is ${about().home}. A sandboxed agent must be allowed to write it; for Codex, the narrowest grant is:
+  [sandbox_workspace_write]
+  writable_roots = ["${about().home}"]
+in ~/.codex/config.toml. Otherwise agents re-run ringi commands with sandbox escalation, which you approve.`);
+    }
+    if (sub === 'status') {
+        for (const p of [false, true])
+            for (const dir of skillTargets(p))
+                out(`${same(dir) ? 'ok      ' : fs.existsSync(dir) ? 'outdated' : 'missing '} ${dir}`);
+        return;
+    }
+    if (sub === 'uninstall') {
+        for (const dir of skillTargets(flag(o, 'project'))) {
+            if (!fs.existsSync(dir))
+                continue;
+            fs.rmSync(dir, { recursive: true });
+            out(`removed ${dir}`);
+        }
+        return;
+    }
+    if (sub === 'show')
+        return void process.stdout.write(fs.readFileSync(path.join(SKILL, 'SKILL.md'), 'utf8'));
+    fail('usage: ringi skill install [--project] | uninstall [--project] | status | show');
+};
+//# sourceMappingURL=skill.js.map

package/target/esm/cli.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+// The `ringi` executable. The interface itself is cli/; this file only runs it when started as a program.
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { main } from './cli/index.js';
+import { Fail } from './lib/index.js';
+export { main };
+if (process.argv[1] && fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    main().catch(e => {
+        process.stderr.write(`ringi: ${e instanceof Fail ? e.message : e.stack}\n`);
+        process.exitCode = 1;
+    });
+}
+//# sourceMappingURL=cli.js.map

package/target/esm/domain/decisions.js

@@ -0,0 +1,178 @@
+// decide: the extension for decisions and budgets (capability `decisions/1`, docs/spec/decisions-1.md). A proposal circulates
+// to named reviewers, who stamp it; only the named decider, holding authority from the hub's contract, decides. An
+// approval that carries a budget is a grant; work spends against it, and the runner that starts model runs writes
+// the usage receipts. Everything here is a pure fold over messages; nothing trusts a model's own report.
+import { ID_RE, one, ordered } from '../protocol/index.js';
+import { fail } from '../lib/index.js';
+export const CAPABILITY = 'decisions/1';
+export const ROOT = 'operator';
+export const BUDGET_KEYS = ['runs', 'run-seconds', 'concurrency'];
+export const STAMPS = ['approve', 'object', 'abstain'];
+export const DECISIONS = ['approved', 'rejected', 'revoked'];
+const ids = (v) => v === null ? [] : [...new Set(v.split(',').map(x => x.trim()).filter(Boolean))];
+// `runs=5, run-seconds=600, concurrency=1`; undefined if malformed. `runs` is required: a budget without a run count
+// bounds nothing; a zero run time or concurrency would disable the bound it names.
+export const parseBudget = (s) => {
+    if (s === null || s === undefined)
+        return null;
+    const b = {};
+    for (const part of String(s).split(',').map(x => x.trim()).filter(Boolean)) {
+        const m = /^([a-z][a-z-]*)=(\d{1,9})$/.exec(part);
+        if (!m || !BUDGET_KEYS.includes(m[1]) || m[1] in b)
+            return undefined;
+        b[m[1]] = Number(m[2]);
+    }
+    if (!('runs' in b) || b['run-seconds'] === 0 || b.concurrency === 0)
+        return undefined;
+    return { 'run-seconds': 1800, concurrency: 1, ...b };
+};
+export const budgetText = (b) => BUDGET_KEYS.map(k => `${k}=${b[k]}`).join(', ');
+// Relative (`90m`, `2h`, `3d`) or an ISO 8601 time → ISO UTC to the second.
+export const parseDue = (s) => {
+    const rel = /^(\d{1,6})([mhd])$/.exec(s);
+    const t = rel ? Date.now() + Number(rel[1]) * { m: 60e3, h: 3600e3, d: 86400e3 }[rel[2]] : Date.parse(s);
+    if (!Number.isFinite(t))
+        fail(`--due takes 90m, 2h, 3d or an ISO time, not ${s}`);
+    return new Date(t).toISOString().slice(0, 19) + 'Z';
+};
+// Extension trailers are part of a record's validity: a malformed decision record routes nowhere. Returns the reason.
+export const check = (m, isRef) => {
+    if (m.bad)
+        return null;
+    for (const k of ['decider', 'reviewers', 'due', 'budget', 'supersedes', 'stamp', 'decision', 'control', 'grant', 'usage', 'run', 'seconds', 'exit']) {
+        if ((m.trailers[k]?.length ?? 0) > 1)
+            return `duplicate ${k}`;
+    }
+    const ref = (k) => one(m, k) === null || isRef(one(m, k));
+    if (!ref('grant'))
+        return 'malformed Grant';
+    if (!ref('control'))
+        return 'malformed Control';
+    if (one(m, 'budget') !== null && !parseBudget(one(m, 'budget')))
+        return 'malformed Budget';
+    if (m.kind === 'proposal') {
+        if (!ID_RE.test(one(m, 'decider') ?? ''))
+            return 'proposal without a valid Decider';
+        if (!ids(one(m, 'reviewers')).every(x => ID_RE.test(x)))
+            return 'malformed Reviewers';
+        if (one(m, 'due') !== null && !Number.isFinite(Date.parse(one(m, 'due'))))
+            return 'malformed Due';
+        if (!ref('supersedes'))
+            return 'malformed Supersedes';
+    }
+    if (m.kind === 'stamp' && (!m.re || !STAMPS.includes(one(m, 'stamp') ?? '')))
+        return 'stamp without Re or a valid Stamp';
+    if (m.kind === 'decision' && (!m.re || !DECISIONS.includes(one(m, 'decision') ?? '')))
+        return 'decision without Re or a valid Decision';
+    if (m.kind === 'usage') {
+        if (!isRef(one(m, 'grant') ?? '') || !['reserve', 'settle'].includes(one(m, 'usage') ?? '') || !/^[A-Za-z0-9._:-]{1,128}$/.test(one(m, 'run') ?? ''))
+            return 'malformed usage receipt';
+        if (one(m, 'usage') === 'settle' && !/^\d{1,9}$/.test(one(m, 'seconds') ?? ''))
+            return 'usage settle without Seconds';
+    }
+    return null;
+};
+// The root always may; anyone else only within the authority table, and never on their own proposal.
+export const mayDecide = (authority, decider, proposer, budget) => {
+    if (decider === ROOT)
+        return true;
+    if (decider === proposer)
+        return false;
+    const cap = authority?.decide?.[decider];
+    if (!cap)
+        return false;
+    if (!budget)
+        return true;
+    return BUDGET_KEYS.every(k => Number.isFinite(cap[k]) && budget[k] <= cap[k]);
+};
+// A decision names the room's control commit it was made under (`Control`); its authority is the table in effect
+// there. A commit that does not exist yet cannot be named, so a later contract never promotes or demotes a decision.
+const authorized = (m, p, decider, budget, authorityAt) => {
+    if (m.from === ROOT)
+        return true;
+    const table = authorityAt(one(m, 'control'));
+    return m.from === decider && !!table && mayDecide(table, decider, p.from, budget);
+};
+// Everything about one proposal, folded over the messages that answer it, in thread order.
+export const proposalOf = (all, p, authorityAt, now = Date.now() / 1000) => {
+    const decider = one(p, 'decider');
+    const reviewers = ids(one(p, 'reviewers'));
+    const budget = parseBudget(one(p, 'budget')) ?? null;
+    const due = one(p, 'due') ? Date.parse(one(p, 'due')) / 1000 : null;
+    // A revision supersedes only when its author is the proposer or the root.
+    const revisions = ordered([...all.values()].filter(m => !m.bad && m.kind === 'proposal' && one(m, 'supersedes') === p.id && (m.from === p.from || m.from === ROOT)));
+    const answers = ordered([...all.values()].filter(m => !m.bad && m.reId === p.id && (m.kind === 'stamp' || m.kind === 'decision')));
+    const stamps = {};
+    let decision = null;
+    let revoked = null;
+    const superseded = revisions[0] ?? null;
+    const revocation = (m) => !revoked && one(m, 'decision') === 'revoked' && (m.from === decider || m.from === ROOT);
+    // A record after the superseding revision in thread order no longer applies to this revision.
+    for (const m of ordered([...answers, ...(superseded ? [superseded] : [])])) {
+        if (m === superseded)
+            break;
+        // A reviewer's latest stamp counts; its position relative to the decision is only a same-second tie.
+        if (m.kind === 'stamp' && reviewers.includes(m.from))
+            stamps[m.from] = { stamp: one(m, 'stamp'), id: m.id, reason: m.subject };
+        if (m.kind !== 'decision')
+            continue;
+        const d = one(m, 'decision');
+        if (!decision && d !== 'revoked' && m.from === decider && authorized(m, p, decider, budget, authorityAt))
+            decision = { decision: d, id: m.id, by: m.from, time: m.time };
+        else if (decision?.decision === 'approved' && revocation(m))
+            revoked = { id: m.id, by: m.from, time: m.time };
+    }
+    // After a superseding revision, only a revocation of an earlier approval still applies to this one.
+    if (superseded && decision?.decision === 'approved')
+        for (const m of answers)
+            if (revocation(m))
+                revoked = { id: m.id, by: m.from, time: m.time };
+    const missing = reviewers.filter(r => !stamps[r]);
+    const state = revoked ? 'revoked' : decision ? decision.decision : superseded ? 'superseded' : due && now > due ? 'overdue' : 'open';
+    const grant = decision?.decision === 'approved' && budget ? { id: decision.id, budget, proposal: p, revoked: !!revoked } : null;
+    return { proposal: p, decider, reviewers, budget, due, stamps, missing, decision, revoked, superseded, state, grant };
+};
+export const proposals = (all, authorityAt) => [...all.values()].filter(m => !m.bad && m.kind === 'proposal').map(p => proposalOf(all, p, authorityAt));
+export const grantOf = (all, authorityAt, id) => {
+    const d = all.get(id);
+    if (!d || d.bad || d.kind !== 'decision' || !d.reId || !all.get(d.reId))
+        return null;
+    const g = proposalOf(all, all.get(d.reId), authorityAt).grant;
+    return g?.id === id ? g : null;
+};
+// The receipts a grant's ledger counts, in thread order: every reservation, and for each run (its runner and Run id)
+// the first settlement after its reservation, as the first decision counts. A settlement of no reserved run counts
+// nothing.
+const ledger = (all, grant) => {
+    const reserves = [], settled = new Map(), reserved = new Set();
+    for (const m of ordered([...all.values()].filter(m => !m.bad && m.kind === 'usage' && one(m, 'grant') === grant.id))) {
+        const run = `${m.from}/${one(m, 'run')}`;
+        if (one(m, 'usage') === 'reserve') {
+            reserves.push(m);
+            reserved.add(run);
+        }
+        else if (reserved.has(run) && !settled.has(run))
+            settled.set(run, m);
+    }
+    return { reserves, settled };
+};
+// Whether a receipt counts: its Grant names a grant, and that grant's ledger holds it.
+export const counted = (all, authorityAt, m) => {
+    const g = !m.bad && m.kind === 'usage' ? grantOf(all, authorityAt, one(m, 'grant') ?? '') : null;
+    if (!g)
+        return false;
+    const { reserves, settled } = ledger(all, g);
+    return reserves.includes(m) || [...settled.values()].includes(m);
+};
+// Usage from the runners' receipts: every reservation is a run, settled or not; an unsettled one is open while its
+// run could still be going, and uncertain after that.
+export const usageOf = (all, grant, now = Date.now() / 1000) => {
+    const { reserves, settled } = ledger(all, grant);
+    let seconds = 0;
+    for (const m of settled.values())
+        seconds += Number(one(m, 'seconds'));
+    const unsettled = reserves.filter(m => !settled.has(`${m.from}/${one(m, 'run')}`));
+    const open = unsettled.filter(m => now - m.time <= grant.budget['run-seconds'] + 60);
+    return { runs: reserves.length, open: open.length, uncertain: unsettled.length - open.length, seconds, left: Math.max(0, grant.budget.runs - reserves.length) };
+};
+//# sourceMappingURL=decisions.js.map

package/target/esm/domain/index.js

@@ -0,0 +1,16 @@
+// The capabilities this build enforces: `<name>/<major>` → the module whose folds apply it. A new major is a new module
+// registered beside the old one. A hub contract selects at most one major of each name; a room applies what its
+// contract base selects (docs/ARCHITECTURE.md, Evolution).
+import * as decisions from './decisions.js';
+import * as profiles from './profiles.js';
+export const CAPABILITIES = { [decisions.CAPABILITY]: decisions, [profiles.PROFILES_CAPABILITY]: profiles };
+// Why a contract's capability list cannot be enforced by this build, or nothing.
+export const unenforceable = (ids) => {
+    const names = ids.map(id => id.split('/')[0]);
+    const twice = names.find((n, i) => names.indexOf(n) !== i);
+    if (twice)
+        return `selects two majors of ${twice}`;
+    const unknown = ids.filter(id => !CAPABILITIES[id]);
+    return unknown.length ? `requires ${unknown.join(', ')}` : null;
+};
+//# sourceMappingURL=index.js.map