@idleware/ringi 0.5.0 → 0.6.0

package/target/esm/core/agents/turns/plan.js

@@ -0,0 +1,29 @@
+// plan: one loop's turns: what arrived, grouped and reserved; planning and dispatch take locks in the order grant,
+// reader, sessions.
+import { locked } from '../../hub/ports/index.js';
+import { link } from '../../hub/protocol/index.js';
+import { loadRoomUnlocked, loadState, readerLock, saveState } from '../../hub/history/index.js';
+import { reserveGroups } from './budgets.js';
+import { collectMessages, groupMessages } from './messages.js';
+import { answerWatchPings } from './pings.js';
+const planUnlocked = (c, R) => {
+    const { logs, st } = loadRoomUnlocked(R, c.me);
+    if (st.inflight) {
+        st.seen = st.inflight.seen;
+        st.inflight = undefined;
+        saveState(R, c.me, st);
+    }
+    const all = link(logs), heartbeatSeen = answerWatchPings(c, R, logs, st);
+    const { retry, cursors, go } = collectMessages(c, R, logs, st, all);
+    const p = reserveGroups(c, R, all, groupMessages(R, all, go), st);
+    if (p.lost)
+        return { runs: [], hold: true, lost: true };
+    const pending = [...new Set([...retry.map(m => m.id), ...p.runs.flatMap(r => r.msgs.map(m => m.id))])];
+    saveState(R, c.me, {
+        ...loadState(R, c.me), heartbeatSeen, exhausted: p.exhausted, pending, runs: p.ownRuns,
+        ...(p.hold ? {} : { watched: cursors })
+    });
+    return { runs: p.runs, hold: p.hold, lost: false };
+};
+export const planTurns = (c, R) => locked(`grant-${R.hub.name}`, () => readerLock(R, c.me, () => planUnlocked(c, R)));
+//# sourceMappingURL=plan.js.map

package/target/esm/core/agents/turns/poll.js

@@ -0,0 +1,48 @@
+// poll: each loop renews the watcher's seat and finds its room still there, the same, with its agent a member.
+import { locked } from '../../hub/ports/index.js';
+import { openHub, openRoom, start } from '../../hub/rooms/index.js';
+import { stamp } from '../../../lib/index.js';
+import { dropSession, readSession, saveSession } from '../sessions/index.js';
+const refreshSeat = (c) => locked('sessions', () => {
+    const cur = readSession(c.handle);
+    if (cur?.state === 'active')
+        saveSession({ ...cur, lastSeen: stamp(), pid: process.pid });
+    return cur;
+});
+const currentRoom = (c) => {
+    const H = openHub(c.H0.name, { refresh: true }), R = openRoom(H, c.R0.name, { quiet: true });
+    if (!R || R.genesis !== c.R0.genesis) {
+        locked('sessions', () => { if (readSession(c.handle)?.genesis === c.R0.genesis)
+            dropSession(c.handle); });
+        c.log(`watch: ${c.R0.name} is gone, recreated or archived; ${c.me} left it`);
+        return null;
+    }
+    if (!R.members[c.me]) {
+        c.log(`watch: ${c.me} was removed from ${c.R0.name}; stopping`);
+        return null;
+    }
+    return R;
+};
+const quorum = (c, R) => {
+    const st = start(R);
+    if (st.started)
+        return { done: false, R };
+    if (c.w.once)
+        c.log(`watch: ${c.R0.name} waits for a quorum of ${st.quorum} agents and has ${st.agents}; nothing to do yet`);
+    return { done: !!c.w.once };
+};
+export const pollWatcher = (c) => {
+    const s = refreshSeat(c);
+    if (!s) {
+        c.log(`watch: the seat of ${c.me} was released or taken over; stopping`);
+        return { done: true };
+    }
+    if (s.state === 'stopped') {
+        if (c.w.once)
+            c.log('watch: stopped by the operator');
+        return { done: !!c.w.once };
+    }
+    const R = currentRoom(c);
+    return R ? quorum(c, R) : { done: true };
+};
+//# sourceMappingURL=poll.js.map

package/target/esm/core/agents/turns/results.js

@@ -0,0 +1,40 @@
+// results: a turn's end: its usage receipt settled, and its messages delivered or kept for a retry.
+import { OPERATOR, append } from '../../hub/rooms/index.js';
+import { note } from '../../../lib/index.js';
+import { compose } from '../../hub/protocol/index.js';
+import { loadState, readerLock, saveState } from '../../hub/history/index.js';
+import { dispatch } from './dispatch.js';
+const settle = (c, R, run, result) => append(R, c.me, compose(`usage: settle a run of ${c.me}${result.why ? ` (${result.why})` : ''}`, [['To', OPERATOR], ['Kind', 'usage'], ['Grant', run.grant], ['Usage', 'settle'], ['Run', run.run], ['Seconds', String(result.seconds)], ['Exit', String(result.exit)]]));
+const delivered = (c, R, run, r) => readerLock(R, c.me, () => {
+    const st = loadState(R, c.me), ids = new Set(run.msgs.map(m => m.id));
+    const success = r.code === 0 || r.timedOut;
+    saveState(R, c.me, {
+        ...st, inflight: undefined, ...(success
+            ? { pending: (st.pending ?? []).filter(id => !ids.has(id)) }
+            : { seen: st.inflight?.seen ?? st.seen })
+    });
+});
+const ended = (c, R, run, r) => {
+    note(`watch: exit ${r.code ?? r.signal}${r.timedOut ? ' (stopped at the grant\'s run-seconds)' : ''} after ${r.seconds}s`);
+    if (run.run)
+        settle(c, R, run, { seconds: r.seconds, exit: r.code ?? 128 });
+    delivered(c, R, run, r);
+};
+export const runTurns = async (c, R, runs) => {
+    let exitCode = 0;
+    for (const run of runs) {
+        const next = dispatch(c, R, run);
+        if (next.why) {
+            note(`watch: not starting the next turn: ${next.why}`);
+            if (run.run)
+                settle(c, R, run, { seconds: 0, exit: 125, why: `not started: ${next.why}` });
+            continue;
+        }
+        const r = await next.done;
+        ended(c, R, run, r);
+        if (r.code !== 0 || r.timedOut)
+            exitCode ||= r.code || 128;
+    }
+    return exitCode;
+};
+//# sourceMappingURL=results.js.map

package/target/esm/core/agents/turns/seat.js

@@ -0,0 +1,44 @@
+// seat: the watcher takes its agent's seat, from a dead watcher or by an explicit handoff from the agent's own chat.
+import { locked } from '../../hub/ports/index.js';
+import { config, openHub, openRoom } from '../../hub/rooms/index.js';
+import { fail, stamp } from '../../../lib/index.js';
+import { dropSession, liveness, parseSelector, pidAlive, saveSession, seatHolder, whoAmI } from '../sessions/index.js';
+import { validateWatch } from './limits.js';
+const handoff = (c, holder) => {
+    const own = c.w.handoff && holder?.product !== 'watch' && holder?.handle === whoAmI().handle;
+    if (c.w.handoff && !own)
+        fail('watch --handoff needs the invoking chat to own this seat');
+    if (own && holder.state === 'stopped')
+        fail('this chat is stopped; continue it before a handoff');
+    const live = holder && (holder.product !== 'watch' || (holder.pid && pidAlive(holder.pid)));
+    if (holder && !own && live)
+        fail(`${c.R0.name}/${c.me} is held by session ${holder.handle} (${liveness(holder)}); one seat per agent. Its chat may use watch --handoff`);
+    return !!own;
+};
+const claim = (c) => locked('sessions', () => {
+    const { w, H0, R0, me, handle } = c;
+    const holder = seatHolder(H0.name, R0.genesis, me, handle), handed = handoff(c, holder);
+    if (holder)
+        dropSession(holder.handle);
+    saveSession({
+        handle, product: 'watch', hub: H0.name, room: R0.name, genesis: R0.genesis, agent: me, scope: w.scope ?? holder?.scope ?? null,
+        state: holder?.state === 'stopped' ? 'stopped' : 'active', since: stamp(), lastSeen: stamp(), pid: process.pid,
+        takenFrom: handed ? holder.handle : holder?.takenFrom
+    });
+});
+export const createWatcher = (w, log) => {
+    validateWatch(w);
+    const sel = parseSelector(w.seat), H0 = openHub(sel.hub ?? w.hub ?? config().hub), R0 = openRoom(H0, sel.room), me = sel.agent;
+    if (R0.archived)
+        fail(`${R0.name} is archived`);
+    if (!R0.members[me])
+        fail(`${me} is not a member of ${R0.name}; the operator adds it with a join, or watch another agent`);
+    const raw = `watch-${H0.name}-${R0.genesis.slice(0, 8)}-${me}-${process.pid}`, handle = `env:${raw}`;
+    const c = {
+        w, H0, R0, me, raw, handle, cmd: w.exec, log, interval: (w.interval ?? 5) * 1000,
+        allow: w.from ? new Set(w.from) : null, maxHop: w.maxHop ?? 8, maxRuns: w.maxRuns ?? 10, span: w.window ?? 86400, runSeq: 0
+    };
+    claim(c);
+    return c;
+};
+//# sourceMappingURL=seat.js.map

package/target/esm/core/agents/turns/types.js

@@ -0,0 +1,3 @@
+// types: what the watcher's modules share: its options and context, groups of messages, runs and reservations.
+export {};
+//# sourceMappingURL=types.js.map

package/target/esm/{domain/index.js → core/hub/capabilities.js}

@@ -1,8 +1,8 @@
 // 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';
+import * as decisions from './decisions/index.js';
+import * as profiles from './work/index.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) => {
@@ -13,4 +13,4 @@ export const unenforceable = (ids) => {
     const unknown = ids.filter(id => !CAPABILITIES[id]);
     return unknown.length ? `requires ${unknown.join(', ')}` : null;
 };
-//# sourceMappingURL=index.js.map
+//# sourceMappingURL=capabilities.js.map

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

@@ -0,0 +1,40 @@
+// budget: what a decision grants (a budget), until when a proposal waits (its due time), and who may decide it.
+import { fail } from '../../../lib/index.js';
+export const ROOT = 'operator';
+const BUDGET_KEYS = ['runs', 'run-seconds', 'concurrency'];
+export const ids = (v) => v === null ? [] : [...new Set(v.split(',').map(x => x.trim()).filter(Boolean))];
+const PART = /^([a-z][a-z-]*)=(\d{1,9})$/;
+// `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 = PART.exec(part);
+        if (!m || !BUDGET_KEYS.includes(m[1]) || m[1] in b)
+            return undefined;
+        b[m[1]] = Number(m[2]);
+    }
+    return bounded(b) ? { 'run-seconds': 1800, concurrency: 1, ...b } : undefined;
+};
+const bounded = (b) => 'runs' in b && b['run-seconds'] !== 0 && b.concurrency !== 0;
+export const budgetText = (b) => BUDGET_KEYS.map(k => `${k}=${b[k]}`).join(', ');
+const UNIT = { m: 60e3, h: 3600e3, d: 86400e3 };
+// 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]) * UNIT[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';
+};
+const within = (cap, budget) => BUDGET_KEYS.every(k => Number.isFinite(cap[k]) && budget[k] <= cap[k]);
+// 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;
+    const cap = decider === proposer ? undefined : authority?.decide?.[decider];
+    return !!cap && (!budget || within(cap, budget));
+};
+//# sourceMappingURL=budget.js.map

package/target/esm/core/hub/decisions/check.js

@@ -0,0 +1,43 @@
+// check: the extension's trailers are part of a record's validity; a malformed decision record routes nowhere.
+import { ID_RE, one } from '../protocol/index.js';
+import { ids, parseBudget } from './budget.js';
+export const STAMPS = ['approve', 'object', 'abstain'];
+export const DECISIONS = ['approved', 'rejected', 'revoked'];
+const SINGLE = ['decider', 'reviewers', 'due', 'budget', 'supersedes', 'stamp', 'decision', 'control', 'grant', 'usage', 'run', 'seconds', 'exit'];
+const RUN = /^[A-Za-z0-9._:-]{1,128}$/;
+// A trailer absent, or a message id.
+const refOk = (m, k, isRef) => one(m, k) === null || isRef(one(m, k));
+const answers = (m, values, k) => !!m.re && values.includes(one(m, k) ?? '');
+const receipt = (m, isRef) => isRef(one(m, 'grant') ?? '') && ['reserve', 'settle'].includes(one(m, 'usage') ?? '') && RUN.test(one(m, 'run') ?? '');
+const dueOk = (v) => v === null || Number.isFinite(Date.parse(v));
+// What each kind of record must carry, as (wrong, why) in the order the reasons are reported.
+const BY_KIND = {
+    proposal: (m, isRef) => [
+        [() => !ID_RE.test(one(m, 'decider') ?? ''), 'proposal without a valid Decider'],
+        [() => !ids(one(m, 'reviewers')).every(x => ID_RE.test(x)), 'malformed Reviewers'],
+        [() => !dueOk(one(m, 'due')), 'malformed Due'],
+        [() => !refOk(m, 'supersedes', isRef), 'malformed Supersedes'],
+    ],
+    stamp: m => [[() => !answers(m, STAMPS, 'stamp'), 'stamp without Re or a valid Stamp']],
+    decision: m => [[() => !answers(m, DECISIONS, 'decision'), 'decision without Re or a valid Decision']],
+    usage: (m, isRef) => [
+        [() => !receipt(m, isRef), 'malformed usage receipt'],
+        [() => one(m, 'usage') === 'settle' && !/^\d{1,9}$/.test(one(m, 'seconds') ?? ''), 'usage settle without Seconds'],
+    ],
+};
+// Why a record is malformed for this extension, or null.
+export const check = (m, isRef) => {
+    if (m.bad)
+        return null;
+    const twice = SINGLE.find(k => (m.trailers[k]?.length ?? 0) > 1);
+    if (twice)
+        return `duplicate ${twice}`;
+    const rules = [
+        [() => !refOk(m, 'grant', isRef), 'malformed Grant'],
+        [() => !refOk(m, 'control', isRef), 'malformed Control'],
+        [() => one(m, 'budget') !== null && !parseBudget(one(m, 'budget')), 'malformed Budget'],
+        ...BY_KIND[m.kind ?? '']?.(m, isRef) ?? [],
+    ];
+    return rules.find(([wrong]) => wrong())?.[1] ?? null;
+};
+//# sourceMappingURL=check.js.map

package/target/esm/core/hub/decisions/index.js

@@ -0,0 +1,10 @@
+// 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.
+export const CAPABILITY = 'decisions/1';
+export * from './budget.js';
+export * from './check.js';
+export * from './proposal.js';
+export * from './usage.js';
+//# sourceMappingURL=index.js.map

package/target/esm/core/hub/decisions/proposal.js

@@ -0,0 +1,73 @@
+// proposal: one proposal folded over the messages that answer it, in thread order: its stamps, its decision, a
+// revocation, a superseding revision; and the grant an approval with a budget makes.
+import { one, ordered } from '../protocol/index.js';
+import { ROOT, ids, mayDecide, parseBudget } from './budget.js';
+const byOwner = (m, p) => m.from === p.from || m.from === ROOT;
+// A revision supersedes only when its author is the proposer or the root.
+const revises = (m, p) => m.kind === 'proposal' && one(m, 'supersedes') === p.id && byOwner(m, p);
+const answers = (m, p) => m.reId === p.id && (m.kind === 'stamp' || m.kind === 'decision');
+const among = (all, keep) => ordered([...all.values()].filter(m => !m.bad && keep(m)));
+// 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 = (c, m) => {
+    if (m.from === ROOT)
+        return true;
+    const table = c.authorityAt(one(m, 'control'));
+    return !!table && mayDecide(table, c.decider, c.p.from, c.budget);
+};
+const decides = (c, m) => one(m, 'decision') !== 'revoked' && m.from === c.decider && authorized(c, m);
+const revokes = (c, m) => one(m, 'decision') === 'revoked' && (m.from === c.decider || m.from === ROOT);
+const approved = (f) => f.decision?.decision === 'approved';
+// One answer applied: a reviewer's latest stamp counts (its position relative to the decision is only a same-second
+// tie); the first decision of the decider with authority; then the first revocation of an approval.
+const take = (c, f, m) => {
+    if (m.kind === 'stamp' && c.reviewers.includes(m.from))
+        f.stamps[m.from] = { stamp: one(m, 'stamp'), id: m.id, reason: m.subject };
+    if (m.kind !== 'decision')
+        return;
+    if (!f.decision && decides(c, m))
+        f.decision = { decision: one(m, 'decision'), id: m.id, by: m.from, time: m.time };
+    else if (approved(f) && !f.revoked && revokes(c, m))
+        f.revoked = { id: m.id, by: m.from, time: m.time };
+};
+// The answers in thread order; one after the superseding revision no longer applies to this revision, except a
+// revocation of an earlier approval.
+const fold = (c, list, superseded) => {
+    const f = { stamps: {}, decision: null, revoked: null };
+    for (const m of ordered([...list, ...(superseded ? [superseded] : [])])) {
+        if (m === superseded)
+            break;
+        take(c, f, m);
+    }
+    const late = superseded && approved(f) && !f.revoked ? list.find(m => revokes(c, m)) : undefined;
+    if (late)
+        f.revoked = { id: late.id, by: late.from, time: late.time };
+    return f;
+};
+const stateOf = (f, superseded, due, now) => {
+    if (f.revoked)
+        return 'revoked';
+    if (f.decision)
+        return f.decision.decision;
+    if (superseded)
+        return 'superseded';
+    return due && now > due ? 'overdue' : 'open';
+};
+export const proposalOf = (all, p, authorityAt, now = Date.now() / 1000) => {
+    const c = { p, decider: one(p, 'decider'), reviewers: ids(one(p, 'reviewers')), budget: parseBudget(one(p, 'budget')) ?? null, authorityAt };
+    const due = one(p, 'due') ? Date.parse(one(p, 'due')) / 1000 : null;
+    const superseded = among(all, m => revises(m, p))[0] ?? null;
+    const f = fold(c, among(all, m => answers(m, p)), superseded);
+    const grant = approved(f) && c.budget ? { id: f.decision.id, budget: c.budget, proposal: p, revoked: !!f.revoked } : null;
+    return { proposal: p, decider: c.decider, reviewers: c.reviewers, budget: c.budget, due, ...f,
+        missing: c.reviewers.filter(r => !f.stamps[r]), superseded, state: stateOf(f, superseded, due, now), grant };
+};
+export const proposals = (all, authorityAt) => [...all.values()].filter(m => !m.bad && m.kind === 'proposal').map(p => proposalOf(all, p, authorityAt));
+const decision = (d) => !!d && !d.bad && d.kind === 'decision';
+export const grantOf = (all, authorityAt, id) => {
+    const d = all.get(id);
+    const p = decision(d) && d.reId ? all.get(d.reId) : undefined;
+    const g = p ? proposalOf(all, p, authorityAt).grant : null;
+    return g?.id === id ? g : null;
+};
+//# sourceMappingURL=proposal.js.map

package/target/esm/core/hub/decisions/usage.js

@@ -0,0 +1,39 @@
+// usage: what a grant's runs spent, from the usage receipts the runners write.
+import { one, ordered } from '../protocol/index.js';
+import { grantOf } from './proposal.js';
+// 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=usage.js.map

package/target/esm/core/hub/history/index.js

@@ -0,0 +1,90 @@
+// reader: what one reader on this machine accepted of a room: heads, signals, cursors, alarms. Only history that
+// extends what it accepted before, verified by the store, is delivered (docs/spec/hub-1.md, Trust).
+import * as Signals from '../signals/index.js';
+import { hubPorts, locked } from '../ports/index.js';
+import { toMessage } from '../rooms/index.js';
+import { fail, note, short } from '../../../lib/index.js';
+import { link } from '../protocol/index.js';
+// What one reader accepted of one room: a record of the machine's state.
+const readerKey = (R, reader) => ['readers', R.hub.name, R.genesis, reader];
+export const readerLock = (R, reader, fn) => locked(`reader-${R.hub.name}-${R.genesis.slice(0, 12)}-${reader}`, fn);
+export const loadState = (R, reader) => hubPorts().state.read(readerKey(R, reader), {});
+export const saveState = (R, reader, st) => hubPorts().state.write(readerKey(R, reader), st);
+// The control history must extend what this reader accepted; a rewritten one delivers nothing.
+const acceptControl = (R, st) => {
+    if (st.control && !R.hub.store.extends(st.control, R.head)) {
+        fail(`ALARM room ${R.name}: its control history was rewritten (accepted ${short(st.control)}, now ${short(R.head)}). Nothing is delivered; the operator decides`);
+    }
+    st.control = R.head;
+};
+// Why a log's current head cannot be accepted after `acc`, if it cannot.
+const logProblem = (R, id, acc, cur) => {
+    const store = R.hub.store;
+    if (!cur)
+        return `log ${id} was deleted after ${short(acc)}`;
+    if (acc && !store.extends(acc, cur))
+        return `log ${id} was rewritten: ${short(cur)} does not extend the accepted ${short(acc)}`;
+    if (!store.extends(R.genesis, cur))
+        return `log ${id} does not descend from the room's genesis`;
+    const why = store.verifyLog(R.s, id, cur);
+    return why && `log ${id}: ${why}`;
+};
+// Every log that still extends its accepted head, pinned at its new head; the others become alarms.
+const acceptLogs = (R, reader, st, alarms) => {
+    const store = R.hub.store, heads = st.heads ??= {};
+    const logs = new Map();
+    for (const id of new Set([...store.logIds(R.s), ...Object.keys(heads)])) {
+        const cur = store.logHead(R.s, id), acc = heads[id];
+        const why = logProblem(R, id, acc, cur);
+        if (why) {
+            alarms.push(why);
+            continue;
+        }
+        if (acc !== cur) {
+            heads[id] = cur;
+            store.pin(R.s, reader, id, cur);
+        }
+        logs.set(id, store.messages(R.s, id, cur).map((x, seq) => toMessage(R, id, x, seq)));
+    }
+    return logs;
+};
+// The signals that agree with their messages are pinned; the rest become alarms.
+const acceptSignals = (R, logs, st, alarms) => {
+    const records = R.hub.store.signals(R.s);
+    const checked = Signals.check(R, link(logs), records);
+    const signalPins = Signals.pins(records, checked, st.signals);
+    st.signals = signalPins.accepted;
+    alarms.push(...signalPins.alarms, ...checked.filter(x => !x.ok).map(x => `signal ${x.ref}: ${x.why}`));
+};
+// What follows from an alarm, by what it is about.
+const remedy = (R, alarm) => {
+    if (alarm.startsWith('signal '))
+        return 'the messages stay the truth; the author restores a missing signal with ringi agent signals --repair';
+    if (alarm.startsWith('commit '))
+        return 'it is skipped; the room reads on without it';
+    return `it is quarantined and withheld. Restore it, or the operator runs ringi forget ${R.name}/<log>`;
+};
+// Every log must keep extending what this reader accepted, and the store must verify it (a signed store: every entry
+// signed by the key the room admitted). A log that lost, rewrote or forked accepted history, or fails verification,
+// is quarantined: withheld, its accepted head pinned as evidence. Only `ringi forget` by the operator accepts a new
+// baseline. Each alarm is told once.
+export const loadRoomUnlocked = (R, reader) => {
+    const st = loadState(R, reader);
+    acceptControl(R, st);
+    const alarms = [...R.hub.store.alarms?.(R.s) ?? []];
+    const logs = acceptLogs(R, reader, st, alarms);
+    acceptSignals(R, logs, st, alarms);
+    const reported = new Set(st.alarms ?? []);
+    for (const a of alarms)
+        if (!reported.has(a))
+            note(`ALARM ${a}; ${remedy(R, a)}`);
+    st.alarms = alarms;
+    saveState(R, reader, st);
+    return { logs, st };
+};
+export const loadRoom = (R, reader) => readerLock(R, reader, () => loadRoomUnlocked(R, reader));
+export const linked = (R, reader) => {
+    const { logs } = loadRoom(R, reader);
+    return { logs, all: link(logs) };
+};
+//# sourceMappingURL=index.js.map

package/target/esm/core/hub/ports/index.js

@@ -0,0 +1,10 @@
+// ports (hub): what the hub needs from the world it runs in — this build, the machine's state, the store types — and
+// where an implementation plugs in. Code asks `hubPorts()` and never imports an adapter; composition/ wires them in
+// when a program starts. The agents' own ports are apart (core/agents/ports).
+import { fail } from '../../../lib/fail.js';
+let wired = null;
+export const wireHub = (p) => { wired = p; };
+export const hubPorts = () => wired ?? fail('ringi is not wired: a program starts it through composition/');
+// Exclusive across the processes of this machine (LocalState.locked).
+export const locked = (name, fn) => hubPorts().state.locked(name, fn);
+//# sourceMappingURL=index.js.map

package/target/esm/core/hub/ports/state.js

@@ -0,0 +1,5 @@
+// state: what ringi keeps on this machine — the operator's terminal context, what each reader accepted, the sessions,
+// a hub's descriptor and its store's own files — as a port. A record is named by a key path; the adapter decides where
+// it lives (adapters/state-fs: $RINGI_HOME). Reading fails closed: an unreadable record is an error, never a fresh start.
+export {};
+//# sourceMappingURL=state.js.map

package/target/esm/core/hub/ports/store.js

@@ -0,0 +1,10 @@
+// store: the port every storage type implements, each an adapter (adapters/transport-<type>: git, kafka and temporal
+// planned) that composition/ registers. Rooms, accepted history, profiles, decisions and signals use only this
+// interface; git is the first implementation, and a hub's descriptor names which one it uses (`store.type`). A store
+// keeps the shared contract (versioned files the participants agree on: contract.json, authority.json, profiles), the
+// rooms (a control record with versioned files, members and roster, and one append-only log per member) and signals
+// (named markers on log entries); the port is split by what each part does (Log, Attachments, …).
+// Revisions are opaque, store-assigned ids. A store says whether one revision extends another; ringi builds the
+// trust rules on that (core/hub/history).
+export {};
+//# sourceMappingURL=store.js.map

package/target/esm/{protocol → core/hub/protocol}/files.js

@@ -1,7 +1,9 @@
 // files: the paths a message may attach (core-1 §4).
-import { fail } from '../lib/index.js';
+import { fail } from '../../../lib/index.js';
 export const CC_RE = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/;
-const COMPONENT_BAD = (c) => !c || c === '.' || c === '..' || c === '.git' || Buffer.byteLength(c) > 255 || CC_RE.test(c) || /[\n\t]/.test(c);
+// A path component that is empty, a directory alias or git's own, too long, or holds control characters.
+const RESERVED_COMPONENTS = new Set(['', '.', '..', '.git']);
+const COMPONENT_BAD = (c) => RESERVED_COMPONENTS.has(c) || Buffer.byteLength(c) > 255 || CC_RE.test(c) || /[\n\t]/.test(c);
 export const checkPath = (p) => {
     if (p.startsWith('/') || p.split('/').some(COMPONENT_BAD))
         fail(`bad file path ${p}`);

package/target/esm/core/hub/protocol/index.js

@@ -0,0 +1,9 @@
+// protocol: the message protocol, docs/spec/core-1.md (§3, §5–§7), independent of storage and of any task model. A store
+// turns its records into messages and hands them here: the text (text.ts), threads and order (threads.ts), inboxes and
+// waking (reading.ts). What a task is, which states it has and who may move it, is a profile, not part of the protocol.
+export * from './model.js';
+export * from './text.js';
+export * from './threads.js';
+export * from './order.js';
+export * from './reading.js';
+//# sourceMappingURL=index.js.map

package/target/esm/core/hub/protocol/model.js

@@ -0,0 +1,15 @@
+// model: what the protocol is made of — ids, trailers, messages — with no behaviour (docs/spec/core-1.md).
+export const ID_RE = /^(?=.{1,64}$)[a-z0-9]+(?:[._-][a-z0-9]+)*(?<!\.lock)$/;
+// An agent's id has no dot: it starts the name of its signals, `<agent>.<signal>.<message12>`.
+export const AGENT_RE = /^(?=.{1,64}$)[a-z0-9]+(?:[_-][a-z0-9]+)*$/;
+export const TOKEN_RE = /^[a-z][a-z0-9-]*$/;
+export const HOP_RE = /^(?:0|[1-9]\d{0,5})$/;
+export const TRAILER_RE = /^([A-Za-z][A-Za-z0-9-]*):[ \t]*(.*)$/;
+export const TEXT_MAX = 64 * 1024;
+// Trailers the protocol itself interprets; any other trailer belongs to an extension or a profile.
+export const KNOWN = new Set(['to', 're', 'kind', 'state', 'hop', 'assign', 'roles']);
+export const HEARTBEATS = new Set(['ping', 'pong']);
+// Kinds that are bookkeeping, never delivered to an inbox: heartbeats, usage receipts, cards, room records.
+export const HIDDEN = new Set(['ping', 'pong', 'usage', 'card', 'room']);
+export const one = (m, k) => m.trailers[k]?.[0] ?? null;
+//# sourceMappingURL=model.js.map

package/target/esm/core/hub/protocol/order.js

@@ -0,0 +1,39 @@
+// order: the order of messages (core-1 §5).
+// The order's edges: each log in sequence, and each answer after what it answers.
+const graph = (list) => {
+    const byId = new Map(list.map(m => [m.id, m]));
+    const next = new Map(list.map(m => [m.id, []]));
+    const indeg = new Map(list.map(m => [m.id, 0]));
+    const edge = (a, b) => {
+        next.get(a.id).push(b);
+        indeg.set(b.id, indeg.get(b.id) + 1);
+    };
+    const last = new Map();
+    for (const m of [...list].sort((a, b) => a.seq - b.seq)) {
+        if (last.has(m.from))
+            edge(last.get(m.from), m);
+        last.set(m.from, m);
+        if (m.reId && byId.has(m.reId))
+            edge(byId.get(m.reId), m);
+    }
+    return { next, indeg };
+};
+const earliest = (a, b) => a.time - b.time || (a.id < b.id ? -1 : 1);
+// Kahn's order: the answered message before the answer, earlier before later within one log; among the ready ones,
+// the smallest (time, id) goes first.
+export const ordered = (list) => {
+    const { next, indeg } = graph(list);
+    const ready = list.filter(m => !indeg.get(m.id));
+    const res = [];
+    while (ready.length) {
+        const m = ready.sort(earliest).shift();
+        res.push(m);
+        for (const n of next.get(m.id)) {
+            indeg.set(n.id, indeg.get(n.id) - 1);
+            if (!indeg.get(n.id))
+                ready.push(n);
+        }
+    }
+    return res;
+};
+//# sourceMappingURL=order.js.map

package/target/esm/core/hub/protocol/reading.js

@@ -0,0 +1,29 @@
+// reading: what is delivered to whom (core-1 §6) and what wakes it (§7).
+import { ordered } from './order.js';
+const addressed = (m, id) => m.to.includes(id) || m.to.includes('*');
+const hiddenKind = (m, hidden) => !!m.kind && hidden.has(m.kind);
+// Delivered: well-formed, not a hidden kind, addressed to `id` by name or `*`.
+export const visible = (m, id, hidden) => !m.invalid && !m.bad && !hiddenKind(m, hidden) && addressed(m, id);
+// Wakes: only a direct address. Broadcasts are read when the agent is awake for another reason.
+export const wakes = (m, id, hidden) => visible(m, id, hidden) && m.to.includes(id);
+const after = (msgs, cursor) => msgs.slice(msgs.findIndex(m => m.id === cursor) + 1);
+const others = (logs, id) => [...logs].filter(([log]) => log !== id);
+// Each log's cursor moves past what was shown and what is not for `id`, up to the first message held back.
+const advance = (logs, id, cursors, seen, hidden) => {
+    const next = { ...cursors };
+    for (const [log, msgs] of others(logs, id)) {
+        for (const m of after(msgs, cursors[log])) {
+            if (visible(m, id, hidden) && !seen.has(m.id))
+                break;
+            next[log] = m.id;
+        }
+    }
+    return next;
+};
+// Messages for `id` after the per-log cursors; cursors advance only past what was shown.
+export const unread = (logs, id, cursors, limit = Infinity, hidden) => {
+    const queue = ordered(others(logs, id).flatMap(([log, msgs]) => after(msgs, cursors[log]).filter(m => visible(m, id, hidden))));
+    const shown = queue.slice(0, limit);
+    return { msgs: shown, rest: queue.length - shown.length, cursors: advance(logs, id, cursors, new Set(shown.map(m => m.id)), hidden) };
+};
+//# sourceMappingURL=reading.js.map