@idleware/ringi 0.5.0 → 0.6.0

package/target/esm/core/hub/usecases/budget.js

@@ -0,0 +1,78 @@
+// budget: proposals, reviewers' stamps, the decider's decision, and the grants it makes (decisions/1). Each operation
+// takes who acts and typed input, and returns data; interfaces print it.
+import * as D from '../decisions/index.js';
+import { locked } from '../ports/index.js';
+import { OPERATOR, append } from '../rooms/index.js';
+import { fail, note, short } from '../../../lib/index.js';
+import { checkOutgoing, compose, lookup } from '../protocol/index.js';
+import { linked } from '../history/index.js';
+import { isRef } from './actor.js';
+import { grantView, proposalView } from './view.js';
+const proposalAt = (all, ref) => {
+    const p = lookup(all, ref);
+    if (p.kind !== 'proposal' || p.bad)
+        fail(`${short(p.id)} is not a proposal`);
+    return p;
+};
+export const stamp = ({ R, me }, ref, s, text) => {
+    const { all } = linked(R, me);
+    const p = proposalAt(all, ref);
+    if (!D.STAMPS.includes(s))
+        fail(`usage: stamp <proposal> ${D.STAMPS.join('|')} -m <reason>`);
+    const info = D.proposalOf(all, p, R.authorityAt);
+    if (!info.reviewers.includes(me))
+        fail(`you are not a named reviewer of ${short(p.id)} (reviewers: ${info.reviewers.join(', ') || 'none'})`);
+    if (info.decision)
+        fail(`${short(p.id)} is already ${info.decision.decision}`);
+    const out = compose(text, [['To', [...new Set([p.from, info.decider])].filter(x => x !== me).join(', ') || p.from], ['Re', p.id], ['Kind', 'stamp'], ['Stamp', s], ['Hop', String(p.hopEff + 1)]]);
+    checkOutgoing(out, isRef(R));
+    return { proposal: p, id: append(R, me, out) };
+};
+// Why the actor may not revoke the proposal's approval: only its decider or the operator revokes, and only an approval.
+const revokeProblem = (info, p, me) => {
+    if (info.state !== 'approved')
+        return `${short(p.id)} is ${info.state}; only an approval can be revoked`;
+    return me !== info.decider && me !== OPERATOR ? `only ${info.decider} or the operator revokes it` : null;
+};
+// Why the actor may not decide the proposal: only its named decider with authority, once, on its latest revision.
+const decideProblem = ({ R, me }, info, p) => {
+    if (me !== info.decider)
+        return `only the named decider, ${info.decider}, decides ${short(p.id)}`;
+    if (!D.mayDecide(R.contract.authority, me, p.from, info.budget))
+        return `${me} has no authority to decide this${info.budget ? ` budget (${D.budgetText(info.budget)})` : ''} in hub ${R.hub.name}, or it is your own proposal`;
+    if (info.decision)
+        return `${short(p.id)} is already ${info.decision.decision}`;
+    return info.superseded ? `${short(p.id)} was superseded by ${short(info.superseded.id)}; decide that revision` : null;
+};
+// The decision names the control entry, and so the authority, it was made under (decisions/1).
+export const decide = ({ R, me }, ref, d, text) => locked(`grant-${R.hub.name}`, () => {
+    const { all } = linked(R, me);
+    const p = proposalAt(all, ref);
+    if (!D.DECISIONS.includes(d))
+        fail(`usage: decide <proposal> ${D.DECISIONS.join('|')} -m <reason>`);
+    const info = D.proposalOf(all, p, R.authorityAt);
+    const why = d === 'revoked' ? revokeProblem(info, p, me) : decideProblem({ R, me }, info, p);
+    if (why)
+        fail(why);
+    const to = [...new Set([p.from, ...info.reviewers])].filter(x => x !== me);
+    const out = compose(text, [['To', to.join(', ') || '*'], ['Re', p.id], ['Kind', 'decision'], ['Decision', d], ['Control', R.head], ['Hop', String(p.hopEff + 1)]]);
+    checkOutgoing(out, isRef(R));
+    const id = append(R, me, out);
+    const approved = d === 'approved';
+    if (approved && info.missing.length)
+        note(`decided without stamps from ${info.missing.join(', ')}`);
+    return { proposal: p, id, budget: approved ? info.budget : null };
+});
+// Open proposals (with `all`, every one).
+export const proposals = ({ R, me }, { all: everything = false } = {}) => {
+    const { all } = linked(R, me);
+    const ps = D.proposals(all, R.authorityAt).filter(x => everything || ['open', 'overdue'].includes(x.state));
+    return { proposals: ps, views: ps.map(proposalView) };
+};
+export const grants = ({ R, me }) => {
+    const { all } = linked(R, me);
+    return D.proposals(all, R.authorityAt).filter(x => x.grant).map(x => grantView(x, D.usageOf(all, x.grant)));
+};
+export { propose } from './propose.js';
+export { DECISIONS, STAMPS, budgetText } from '../decisions/index.js';
+//# sourceMappingURL=budget.js.map

package/target/esm/core/hub/usecases/config.js

@@ -0,0 +1,5 @@
+// config: the operator's terminal context on this machine: the hub and the room a command means when it names none.
+import { hubPorts } from '../ports/index.js';
+export const config = () => ({ hub: 'local', room: null, ...hubPorts().state.read(['config'], {}) });
+export const setConfig = (patch) => hubPorts().state.write(['config'], { ...config(), ...patch });
+//# sourceMappingURL=config.js.map

package/target/esm/core/hub/usecases/context.js

@@ -0,0 +1,13 @@
+// context: who acts as the operator and where (its terminal context, unless a command names a hub or a room), and what
+// this build is. An agent acts through its session (core/agents/sessions/context.ts).
+import { hubPorts } from '../ports/index.js';
+import { CAPS, HUB_MAJOR, OPERATOR, config, openHub, room as roomOf } from '../rooms/index.js';
+// The operator, in the named hub and room, else in the terminal's current ones.
+export const operator = ({ hub, room } = {}) => {
+    const H = openHub(hub ?? config().hub);
+    const name = room ?? (hub && hub !== config().hub ? null : config().room);
+    return { R: roomOf(H, name), me: OPERATOR };
+};
+export const about = () => ({ version: hubPorts().build.version, home: hubPorts().state.root, resources: hubPorts().build.resources, contract: `${HUB_MAJOR}.x`, capabilities: [...CAPS] });
+export { config };
+//# sourceMappingURL=context.js.map

package/target/esm/core/hub/usecases/hubs.js

@@ -0,0 +1,95 @@
+// hubs: the operator's hubs on this machine: list, create, switch, add a signed replica, amend the shared contract.
+import fs from 'node:fs';
+import { DEFAULT_PROFILE, PROFILES_CAPABILITY, parseProfile } from '../work/index.js';
+import { OPERATOR, config, createHub, hubNames, openHub, roomNames, setConfig, transportOf } from '../rooms/index.js';
+import { hubPorts } from '../ports/index.js';
+import { fail, strictJson, words } from '../../../lib/index.js';
+import { ID_RE, compose } from '../protocol/index.js';
+// The operator's terminal context picks the hub unless one is named.
+export const hubOf = (name) => openHub(name ?? config().hub);
+export const hubs = () => {
+    hubPorts().state.ensure();
+    if (!hubNames().length)
+        openHub('local');
+    const cur = config().hub;
+    return hubNames().map(n => {
+        const H = openHub(n);
+        return { name: H.name, current: H.name === cur, store: H.d.store.type, trust: H.contract.trust, contract: H.contract.version,
+            rooms: roomNames(H).length, remote: H.d.store.remote ?? null, dir: H.dir };
+    });
+};
+// A new hub; a signed one makes its root key here and returns what other machines need to pin it.
+export const create = (name, { signed = false, url } = {}) => {
+    if (!ID_RE.test(name))
+        fail('usage: ringi hub create <name> [--signed [--url <git url>]]');
+    const { custody } = createHub(name, { signed, url });
+    const H = openHub(name);
+    return { H, rootKey: custody,
+        add: H.signed ? `ringi hub add ${name} ${H.d.store.remote ?? '<url>'} --root '${H.d.root}' --genesis ${H.d.genesis}` : null };
+};
+export const use = (name) => {
+    openHub(name);
+    setConfig({ hub: name, room: null });
+};
+// A replica of a signed hub. The root key comes from the operator, out of band: a key the hub advertises proves nothing.
+export const add = (name, url, { root, genesis }) => {
+    if (!ID_RE.test(name) || !url)
+        fail('usage: ringi hub add <name> <git url> --root <public key|file> [--genesis <sha>]');
+    hubPorts().state.ensure();
+    const t = transportOf(name, hubPorts().store);
+    if (!t.attach)
+        return fail(`a ${hubPorts().store} store cannot replicate a published hub`);
+    t.attach(name, url, { root, genesis });
+    return openHub(name);
+};
+const SETTABLE = ['version', 'capabilities', 'protocol', 'profile'];
+const json = (x) => JSON.stringify(x, null, 2) + '\n';
+// `key=value` pairs on the contract: capabilities are words, protocol a number, the rest strings.
+const setKeys = (contract, set) => {
+    for (const kv of set) {
+        const [k, v] = kv.split(/=(.*)/s);
+        if (!SETTABLE.includes(k))
+            fail(`contract keys that can be set: ${SETTABLE.join(', ')} (not ${k})`);
+        contract[k] = k === 'capabilities' ? words(v) : k === 'protocol' ? Number(v) : v;
+    }
+};
+// The files the amendment brings besides the contract; a profile is checked before it reaches the contract.
+const extraFiles = (x) => {
+    const files = {};
+    if (x.authority)
+        files['authority.json'] = json(strictJson(fs.readFileSync(x.authority, 'utf8'), x.authority));
+    for (const f of x.files ?? []) {
+        if (/^profiles\/[^/]+\.json$/.test(f.path))
+            parseProfile(f.content.toString('utf8'), f.path);
+        files[f.path] = f.content;
+    }
+    return files;
+};
+// The default profile must be built in, or in the hub after this amendment.
+const checkDefault = (H, contract, files) => {
+    const p = contract.profile;
+    if (typeof p !== 'string' || p === DEFAULT_PROFILE || files[`profiles/${p}.json`])
+        return;
+    if (H.store.contractFile(H.main, `profiles/${p}.json`) === null)
+        fail(`the default profile ${p} is not in the hub; attach it: --attach <file>:profiles/${p}.json`);
+};
+// Profiles other than the built-in A2A rules need clients that read them: the contract says so.
+const needsProfiles = (contract, files, set) => {
+    if (!Object.keys(files).some(f => f.startsWith('profiles/')) && !set.some(kv => kv.startsWith('profile=')))
+        return;
+    const caps = Array.isArray(contract.capabilities) ? contract.capabilities : [];
+    if (!caps.includes(PROFILES_CAPABILITY))
+        contract.capabilities = [...caps, PROFILES_CAPABILITY];
+};
+// A new version of the shared contract on `main`. Rooms keep their base until moved (rooms.rebase).
+export const amend = (H, x) => {
+    const name = 'contract.json';
+    const contract = strictJson(H.store.contractFile(H.main, name), name);
+    setKeys(contract, x.set ?? []);
+    const files = extraFiles(x);
+    checkDefault(H, contract, files);
+    needsProfiles(contract, files, x.set ?? []);
+    H.store.amendContract(OPERATOR, compose(x.text, [['To', '*'], ['Kind', 'hub']]), { [name]: json(contract), ...files });
+    return { version: String(contract.version) };
+};
+//# sourceMappingURL=hubs.js.map

package/target/esm/core/hub/usecases/propose.js

@@ -0,0 +1,39 @@
+// propose: a proposal for the decider and its reviewers, its budget and revision checked before it is written
+// (decisions/1).
+import * as D from '../decisions/index.js';
+import { OPERATOR, append } from '../rooms/index.js';
+import { fail, note, short } from '../../../lib/index.js';
+import { ID_RE, checkOutgoing, compose, lookup } from '../protocol/index.js';
+import { linked } from '../history/index.js';
+import { isRef } from './actor.js';
+// Named reviewers, the proposer never among them.
+const reviewersOf = (me, x) => {
+    if (!ID_RE.test(x.decider))
+        fail(`bad decider ${x.decider}`);
+    const reviewers = [...new Set(x.reviewers ?? [])].filter(r => r !== me);
+    for (const r of reviewers)
+        if (!ID_RE.test(r))
+            fail(`bad reviewer ${r}`);
+    return reviewers;
+};
+const budgetOf = (x) => x.budget ? D.parseBudget(x.budget) ?? fail('--budget takes runs=<n>[, run-seconds=<n>][, concurrency=<n>]') : null;
+// A revision supersedes the actor's own proposal; the operator may revise anyone's.
+const supersededOf = (all, me, ref) => {
+    const sup = ref ? lookup(all, ref) : null;
+    const mine = sup?.kind === 'proposal' && (sup.from === me || me === OPERATOR);
+    return !sup || mine ? sup : fail(`${short(sup.id)} is not your proposal`);
+};
+export const propose = ({ R, me }, x) => {
+    const { all } = linked(R, me);
+    const reviewers = reviewersOf(me, x), budget = budgetOf(x), sup = supersededOf(all, me, x.supersedes);
+    if (budget && !D.mayDecide(R.contract.authority, x.decider, me, budget))
+        note(`${x.decider} has no authority for this budget in hub ${R.hub.name}; only operator could approve it`);
+    const to = [...new Set([...reviewers, x.decider])].filter(t => t !== me);
+    const text = compose(x.text, [['To', to.join(', ') || '*'], ['Kind', 'proposal'], ['Decider', x.decider], ['Reviewers', reviewers.join(', ')],
+        ['Due', x.due && D.parseDue(x.due)], ['Budget', budget && D.budgetText(budget)], ['Supersedes', sup?.id]]);
+    const bad = D.check(checkOutgoing(text, isRef(R)), isRef(R));
+    if (bad)
+        fail(`refusing to send: ${bad}`);
+    return { id: append(R, me, text, x.files ?? []), to, budget };
+};
+//# sourceMappingURL=propose.js.map

package/target/esm/core/hub/usecases/room.js

@@ -0,0 +1,82 @@
+// room: what any participant (the operator or an agent) does in a room: write messages and read them, follow work,
+// check signals. Each operation takes who acts and typed input, and returns data; interfaces print it.
+import * as Signals from '../signals/index.js';
+import { isOpen, tasksIn } from '../work/index.js';
+import { HIDDEN, OPERATOR } from '../rooms/index.js';
+import * as HubSignals from '../signals/write.js';
+import { fail, short } from '../../../lib/index.js';
+import { link, lookup, ordered, rootOf, under } from '../protocol/index.js';
+import { linked, loadRoomUnlocked, loadState, readerLock, saveState } from '../history/index.js';
+import { taskView } from './view.js';
+export * from './actor.js';
+export * from './staging.js';
+export * from './send.js';
+// --- reading ---
+// Who marked a message how (read, taken), from the marks that pass their check.
+export const marks = (R, all) => Signals.marksOn(Signals.check(R, all, R.hub.store.signals(R.s)));
+export const message = ({ R, me }, ref) => {
+    const { all } = linked(R, me);
+    const m = lookup(all, ref);
+    return { all, m, replies: [...all.values()].filter(x => x.reId === m.id), marks: marks(R, all).get(m.id) };
+};
+export const thread = ({ R, me }, ref) => {
+    const { all } = linked(R, me);
+    return { all, msgs: under(all, rootOf(all, lookup(all, ref))) };
+};
+// Work concerns the operator, its requester and assignees, and, while nobody is assigned, whom its root names.
+const concerns = (t, me) => {
+    if (me === OPERATOR || t.requester === me || t.assignees.includes(me))
+        return true;
+    return !t.assignees.length && (t.root.to.includes(me) || t.root.to.includes('*'));
+};
+// Open work that concerns the actor (the operator: all open work); with `all`, every piece of work.
+export const tasks = ({ R, me }, { all: everything = false } = {}) => {
+    const P = R.profile;
+    const { all } = linked(R, me);
+    let ts = tasksIn(all, P);
+    if (!everything)
+        ts = ts.filter(t => isOpen(t, P) && concerns(t, me));
+    ts.sort((a, b) => a.at - b.at);
+    const m = marks(R, all);
+    return { tasks: ts, views: ts.map(t => taskView(t, m.get(t.root.id)?.taken ?? [])) };
+};
+export const log = ({ R, me }, { agent, all: everything = false, n = 20 } = {}) => {
+    const { all } = linked(R, me);
+    return ordered([...all.values()].filter(m => (!agent || m.from === agent) && (everything || !(m.kind && HIDDEN.has(m.kind))))).slice(-n);
+};
+// The files of a message: one named path, or all of them.
+export const files = ({ R, me }, ref, path) => {
+    const { all } = linked(R, me);
+    const m = lookup(all, ref);
+    if (path && !m.files.some(f => f.path === path))
+        fail(`no ${path} in ${short(m.id)}`);
+    return { m, files: m.files.filter(f => !path || f.path === path).map(f => ({ path: f.path, content: R.hub.store.file(m.id, f.path) })) };
+};
+export const members = ({ R, me }) => {
+    const { logs, all } = linked(R, me);
+    const cards = new Map(ordered([...all.values()].filter(m => m.kind === 'card' && !m.bad)).map(m => [m.from, m]));
+    return Object.entries(R.members).map(([id, info]) => ({ id, role: info.role ?? 'member',
+        messages: (logs.get(id) ?? []).filter(m => !(m.kind && HIDDEN.has(m.kind))).length, card: cards.get(id)?.subject ?? null }));
+};
+// --- signals ---
+// The room's signals, each checked against its message and against what this reader accepted before; `repair` first
+// restores the missing signals of the actor's own messages.
+export const signals = ({ R, me }, { repair = false } = {}) => readerLock(R, me, () => {
+    const { logs, st } = loadRoomUnlocked(R, me);
+    const all = link(logs);
+    let repaired = null;
+    if (repair) {
+        repaired = 0;
+        for (const m of logs.get(me) ?? [])
+            repaired += HubSignals.emit(R, me, all, m);
+    }
+    const records = R.hub.store.signals(R.s);
+    const checked = Signals.check(R, all, records);
+    const p = Signals.pins(records, checked, st.signals);
+    saveState(R, me, { ...loadState(R, me), signals: p.accepted });
+    return { all, checked, alarms: [...p.alarms, ...checked.filter(c => !c.ok).map(c => `signal ${c.ref}: ${c.why}`)], repaired };
+});
+// What interfaces need to show and store a message's files: their sizes, and a path safe to write under.
+export { withSizes } from '../rooms/index.js';
+export { checkPath } from '../protocol/files.js';
+//# sourceMappingURL=room.js.map

package/target/esm/{app → core/hub/usecases}/rooms.js

@@ -1,15 +1,13 @@
 // rooms: the operator's rooms in a hub: list, create, switch, admit and remove members, archive, delete, move to a
 // newer contract, and accept a new baseline for a log after reviewing an alarm.
 import crypto from 'node:crypto';
-import fs from 'node:fs';
-import path from 'node:path';
-import { DEFAULT_PROFILE, parseProfile } from '../domain/profiles.js';
-import { HOME, OPERATOR, config, guard, locked, setConfig } from '../home/index.js';
-import { RESERVED_ROOMS, ROOM_MD, controlChange, profileText, room as roomOf, roomNames } from '../hub/index.js';
-import { Fail, fail, note } from '../lib/index.js';
-import { AGENT_RE, ID_RE, compose } from '../protocol/index.js';
-import { loadState, readerLock, saveState } from '../runtime/reader.js';
-import { allSessions, liveness } from '../runtime/session.js';
+import { DEFAULT_PROFILE, parseProfile } from '../work/index.js';
+import { hubPorts, locked } from '../ports/index.js';
+import { OPERATOR, RESERVED_ROOMS, ROOM_MD, config, controlChange, profileText, room as roomOf, roomNames, setConfig } from '../rooms/index.js';
+import { Fail, fail, note } from '../../../lib/index.js';
+import { ID_RE, compose } from '../protocol/index.js';
+import { notSigned } from './roster.js';
+export { admit, forgetLog, remove } from './roster.js';
 // The operator's terminal context picks the room unless one is named.
 export const roomIn = (H, name) => roomOf(H, name ?? config().room);
 // A room the store offers but that does not open (a history under another name) is an alarm, not a row.
@@ -26,11 +24,8 @@ const opens = (H, n) => {
 };
 export const rooms = (H, { archived = false } = {}) => {
     const cur = config().room;
-    const view = (n, R) => {
-        const ss = allSessions().filter(s => s.hub === H.name && s.genesis === R.genesis);
-        return { name: n, current: n === cur && !R.archived, archived: R.archived, members: Object.keys(R.members).length,
-            active: ss.filter(s => liveness(s) === 'active').length, profile: R.profile.name, genesis: R.genesis };
-    };
+    const view = (n, R) => ({ name: n, current: n === cur && !R.archived, archived: R.archived,
+        members: Object.keys(R.members).length, profile: R.profile.name, genesis: R.genesis });
     const live = roomNames(H).flatMap(n => { const R = opens(H, n); return R ? [view(n, R)] : []; });
     const gone = archived ? roomNames(H, true).flatMap(n => { const R = opens(H, n); return R ? [view(n, R)] : []; }) : [];
     return [...live, ...gone];
@@ -62,29 +57,6 @@ export const use = (H, name) => {
     setConfig({ hub: H.name, room: R.name });
     return R;
 };
-export const migrate = (H, name) => {
-    if (!H.store.migrateRoom)
-        fail(`store ${H.store.type} cannot migrate rooms`);
-    return locked(`hub-${H.name}`, () => H.store.migrateRoom(name));
-};
-// Removing, archiving or deleting in a signed hub needs revocation published to every replica: not in this version.
-const notSigned = (H, what) => { if (H.signed)
-    fail(`room ${what} is not supported on signed hubs yet: a local change would come back with the next fetch`); };
-export const admit = (H, R, who, key) => {
-    if (!H.signed || !H.store.admit)
-        fail('room admit is for signed hubs; on a local hub the operator\'s join adds members');
-    if (!AGENT_RE.test(who))
-        fail(`bad agent id ${who}: lowercase letters, digits, - and _, no dot`);
-    locked(`hub-${H.name}`, () => H.store.admit(R.s, who, key));
-};
-export const remove = (H, R, who) => {
-    notSigned(H, 'remove');
-    if (!R.members[who])
-        fail(`${who} is not a member of ${R.name}`);
-    if (who === OPERATOR)
-        fail('the operator stays in every room');
-    controlChange(R, OPERATOR, `remove ${who}`, m => { delete m[who]; });
-};
 export const archive = (H, R) => {
     notSigned(H, 'archive');
     if (R.archived)
@@ -96,38 +68,14 @@ export const archive = (H, R) => {
     return name;
 };
 // The room and everything kept for it: in the store (deleteRoom) and its readers' state. The sessions bound to it,
-// on this machine or another, leave it on their own when they find its branch gone (runtime/session.ts).
+// on this machine or another, leave it on their own when they find its branch gone (core/agents/sessions).
 export const erase = (H, R) => {
     notSigned(H, 'delete');
     locked(`hub-${H.name}`, () => H.store.deleteRoom(R.s));
-    guard(() => fs.rmSync(path.join(HOME, 'readers', H.name, R.genesis), { recursive: true, force: true }));
+    hubPorts().state.remove(['readers', H.name, R.genesis]);
     if (config().room === R.name)
         setConfig({ room: null });
 };
 // The room follows the hub's current contract from now on; nothing written before is reinterpreted.
 export const rebase = (H, R) => controlChange(R, OPERATOR, `contract ${H.contract.version}`, () => { }, [['Contract', H.main]]);
-// The operator accepts a new baseline for one log, for every reader of the room, after reviewing an alarm. A signed
-// store resets its transport pin too, keeping the displaced head as evidence; signatures are never waived.
-export const forgetLog = (H, R, id) => {
-    if (!ID_RE.test(id))
-        fail('usage: ringi forget <room>/<log>');
-    if (H.signed)
-        H.store.forgetLog?.(R.s, id);
-    const dir = path.join(HOME, 'readers', H.name, R.genesis);
-    let n = 0;
-    for (const f of fs.existsSync(dir) ? fs.readdirSync(dir).filter(f => f.endsWith('.json')) : []) {
-        const reader = f.slice(0, -5);
-        readerLock(R, reader, () => {
-            const st = loadState(R, reader);
-            if (st.heads?.[id]) {
-                delete st.heads[id];
-                st.alarms = (st.alarms ?? []).filter(a => !a.startsWith(`log ${id} `) && !a.startsWith(`log ${id}:`));
-                saveState(R, reader, st);
-                n++;
-            }
-            H.store.unpin(R.s, reader, id);
-        });
-    }
-    return n;
-};
 //# sourceMappingURL=rooms.js.map

package/target/esm/core/hub/usecases/roster.js

@@ -0,0 +1,47 @@
+// roster: who belongs to a room and whose history its readers accept: admit a signed member, remove one, and accept a
+// new baseline for a log after an alarm.
+import { hubPorts, locked } from '../ports/index.js';
+import { OPERATOR, controlChange } from '../rooms/index.js';
+import { fail } from '../../../lib/index.js';
+import { AGENT_RE, ID_RE } from '../protocol/index.js';
+import { loadState, readerLock, saveState } from '../history/index.js';
+// Removing, archiving or deleting in a signed hub needs revocation published to every replica: not in this version.
+export const notSigned = (H, what) => { if (H.signed)
+    fail(`room ${what} is not supported on signed hubs yet: a local change would come back with the next fetch`); };
+export const admit = (H, R, who, key) => {
+    if (!H.signed || !H.store.admit)
+        fail('room admit is for signed hubs; on a local hub the operator\'s join adds members');
+    if (!AGENT_RE.test(who))
+        fail(`bad agent id ${who}: lowercase letters, digits, - and _, no dot`);
+    locked(`hub-${H.name}`, () => H.store.admit(R.s, who, key));
+};
+export const remove = (H, R, who) => {
+    notSigned(H, 'remove');
+    if (!R.members[who])
+        fail(`${who} is not a member of ${R.name}`);
+    if (who === OPERATOR)
+        fail('the operator stays in every room');
+    controlChange(R, OPERATOR, `remove ${who}`, m => { delete m[who]; });
+};
+// One reader forgets the log's accepted head and the alarms about it; whether it had accepted any.
+const forgetIn = (R, reader, id) => readerLock(R, reader, () => {
+    const st = loadState(R, reader);
+    const heads = st.heads ?? {}, had = !!heads[id];
+    if (had) {
+        delete heads[id];
+        st.alarms = (st.alarms ?? []).filter(a => !a.startsWith(`log ${id} `) && !a.startsWith(`log ${id}:`));
+        saveState(R, reader, st);
+    }
+    R.hub.store.unpin(R.s, reader, id);
+    return had;
+});
+// The operator accepts a new baseline for one log, for every reader of the room, after reviewing an alarm. A signed
+// store resets its transport pin too, keeping the displaced head as evidence; signatures are never waived.
+export const forgetLog = (H, R, id) => {
+    if (!ID_RE.test(id))
+        fail('usage: ringi forget <room>/<log>');
+    if (H.signed)
+        H.store.forgetLog?.(R.s, id);
+    return hubPorts().state.list(['readers', H.name, R.genesis]).filter(reader => forgetIn(R, reader, id)).length;
+};
+//# sourceMappingURL=roster.js.map

package/target/esm/core/hub/usecases/send.js

@@ -0,0 +1,78 @@
+// send: a message from the actor, its recipients, trailers and files checked before it is written.
+import * as D from '../decisions/index.js';
+import { OPERATOR, append } from '../rooms/index.js';
+import { fail, note, short } from '../../../lib/index.js';
+import { ID_RE, TOKEN_RE, checkOutgoing, compose, lookup } from '../protocol/index.js';
+import { linked, readerLock } from '../history/index.js';
+import { isRef } from './actor.js';
+import { outgoing, shrink, staged } from './staging.js';
+// A reply without `to` goes back to the sender (with `all`, to everyone the message named); one's own, to its recipients.
+const replyTo = (me, x, re) => {
+    if (!x.reply || !re)
+        return [];
+    if (re.from === me)
+        return re.to;
+    return [re.from, ...(x.all ? re.to.filter(t => t !== me) : [])];
+};
+// Without `to`: a reply goes back, an assignment to the assignees, the operator's message to the room.
+const recipients = (me, x, re, assign) => {
+    const to = [...new Set(x.to ?? [])];
+    if (to.length)
+        return to;
+    const back = replyTo(me, x, re);
+    if (back.length)
+        return back;
+    if (assign)
+        return assign;
+    return me === OPERATOR ? ['*'] : fail('--to is required: agent ids, comma-separated, or *');
+};
+const role = (r) => {
+    const parts = r.split('=').map(v => v.trim());
+    return parts.length === 2 && ID_RE.test(parts[0]) && TOKEN_RE.test(parts[1]);
+};
+const checkTrailers = (P, x, to, assign, re) => {
+    for (const t of to)
+        if (t !== '*' && !ID_RE.test(t))
+            fail(`bad recipient ${t}`);
+    if (x.state && !P.states.includes(x.state))
+        fail(`--state must be one of profile ${P.name}: ${P.states.join(', ')}`);
+    if (x.state && !re)
+        fail('--state belongs to a reply inside a piece of work; pass --re <message>');
+    for (const a of assign ?? [])
+        if (!ID_RE.test(a))
+            fail(`bad assignee ${a}`);
+    if (x.roles && !x.roles.split(',').every(role))
+        fail('--roles takes "<id>=<label>, …"; labels mean what the room profile says');
+};
+// The grant a piece of work spends: an approved decision with a budget, not revoked.
+const grantOf = (R, all, ref) => {
+    if (!ref)
+        return null;
+    const d = lookup(all, ref);
+    const g = D.grantOf(all, R.authorityAt, d.id) ?? fail(`${short(d.id)} is not an approved decision with a budget`);
+    return g.revoked ? fail(`grant ${short(g.id)} was revoked`) : g.id;
+};
+// A message from the actor. The operator may omit `to`: the room, or the assignees when there are any.
+export const send = ({ R, me }, x) => {
+    const P = R.profile;
+    const { all } = linked(R, me);
+    const re = x.re ? lookup(all, x.re) : null;
+    const assign = x.assign ? [...new Set(x.assign)] : null;
+    const to = recipients(me, x, re, assign);
+    checkTrailers(P, x, to, assign, re);
+    const grant = grantOf(R, all, x.grant);
+    const stagedNow = staged({ R, me });
+    const entries = outgoing(stagedNow, x.files ?? []);
+    const text = compose(x.text, [
+        ['To', to.join(', ')], ['Re', re?.id], ['Kind', x.task && P.opens], ['State', x.state], ['Assign', assign?.join(', ')],
+        ['Roles', x.roles], ['Grant', grant], ['Hop', re && String(re.hopEff + 1)],
+    ]);
+    checkOutgoing(text, isRef(R));
+    const id = append(R, me, text, entries);
+    if (stagedNow.length)
+        readerLock(R, me, () => shrink({ R, me }, s => !stagedNow.some(t => t.path === s.path && t.blob === s.blob)));
+    if (to.length === 1 && to[0] === '*')
+        note(`addressed to the whole room: this ${x.task ? P.opens : 'message'} wakes nobody; name recipients (--to or --assign) to start work`);
+    return { id, to, files: entries.length };
+};
+//# sourceMappingURL=send.js.map

package/target/esm/core/hub/usecases/staging.js

@@ -0,0 +1,60 @@
+// staging, like git's index: add takes a file's content into the store now, and the actor's next message carries it,
+// whatever happens to the file meanwhile. Results and state travel only so, never through a shared directory. The store
+// keeps staged contents reachable (`retain`); it grows before the list does and shrinks after, so a crash in between
+// leaks an object rather than loses one.
+import fs from 'node:fs';
+import { fail } from '../../../lib/index.js';
+import { checkCollisions } from '../protocol/files.js';
+import { loadState, readerLock, saveState } from '../history/index.js';
+const FILE_MAX = 64 << 20;
+const tooBig = (path, size) => size > FILE_MAX && fail(`${path} is ${Math.ceil(size / (1 << 20))} MiB; an attachment is at most ${FILE_MAX >> 20} MiB`);
+// What retain keeps: each staged content once, named by its id, so two snapshots of one path both stay.
+const kept = (all) => [...new Set(all.map(s => s.blob))].map(blob => ({ path: blob, blob, mode: '100644' }));
+export const staged = ({ R, me }) => loadState(R, me).staged ?? [];
+export const stage = ({ R, me }, files) => {
+    const taken = files.map(e => {
+        if (!e.file)
+            fail(`${e.path}: add takes files`);
+        tooBig(e.path, fs.statSync(e.file).size);
+        const b = R.hub.store.blob(e.file);
+        tooBig(e.path, b.size);
+        return { path: e.path, blob: b.id, mode: e.mode, size: b.size };
+    });
+    return readerLock(R, me, () => {
+        const st = loadState(R, me);
+        const next = new Map((st.staged ?? []).map(s => [s.path, s]));
+        for (const s of taken)
+            next.set(s.path, s);
+        const all = [...next.values()];
+        checkCollisions(all.map(s => s.path));
+        R.hub.store.retain(R.s, me, kept([...all, ...st.staged ?? []]));
+        saveState(R, me, { ...st, staged: all });
+        R.hub.store.retain(R.s, me, kept(all));
+        return all;
+    });
+};
+export const shrink = ({ R, me }, keep) => {
+    const st = loadState(R, me);
+    const left = (st.staged ?? []).filter(keep);
+    saveState(R, me, { ...st, staged: left });
+    R.hub.store.retain(R.s, me, kept(left));
+    return left;
+};
+// Unstages the given paths, or everything.
+export const unstage = (a, paths) => readerLock(a.R, a.me, () => {
+    const missing = (paths ?? []).filter(p => !staged(a).some(s => s.path === p));
+    if (missing.length)
+        fail(`not staged: ${missing.join(', ')}`);
+    return shrink(a, s => paths !== null && !paths.includes(s.path));
+});
+// What the actor staged goes along, an explicit attachment of the same path in its place.
+export const outgoing = (stagedNow, explicit) => {
+    for (const e of explicit)
+        if (e.file)
+            tooBig(e.path, fs.statSync(e.file).size);
+    const named = new Set(explicit.map(e => e.path));
+    const entries = [...stagedNow.filter(s => !named.has(s.path)).map(s => ({ path: s.path, blob: s.blob, mode: s.mode })), ...explicit];
+    checkCollisions(entries.map(e => e.path));
+    return entries;
+};
+//# sourceMappingURL=staging.js.map