@idleware/ringi 0.5.0 → 0.6.1

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

@@ -0,0 +1,95 @@
+// text: a message's text (core-1 §3) — decoding, the trailer block, and why a message is malformed.
+import { fail } from '../../../lib/index.js';
+import { CC_RE } from './files.js';
+import { HOP_RE, ID_RE, KNOWN, TEXT_MAX, TOKEN_RE, TRAILER_RE } from './model.js';
+const utf8 = new TextDecoder('utf-8', { fatal: true });
+// Invalid text is dangerous bytes: readers treat the message as absent.
+export const decodeText = (buf) => {
+    let s;
+    try {
+        s = utf8.decode(buf);
+    }
+    catch {
+        return { invalid: 'not valid UTF-8' };
+    }
+    s = s.replace(/\r\n/g, '\n');
+    if (/\r/.test(s))
+        return { invalid: 'a CR not followed by LF' };
+    if (CC_RE.test(s))
+        return { invalid: 'control characters in the text' };
+    return { text: s };
+};
+// The trailer block: the last paragraph, when every line of it is a trailer.
+const trailerBlock = (text) => {
+    const cut = text.lastIndexOf('\n\n');
+    const tail = cut < 0 ? [] : text.slice(cut + 2).split('\n');
+    const has = tail.length > 0 && tail.every(l => TRAILER_RE.test(l));
+    const trailers = {};
+    for (const l of has ? tail : []) {
+        const [, k, v] = TRAILER_RE.exec(l);
+        const key = k.toLowerCase();
+        trailers[key] = [...(trailers[key] ?? []), v.trim()];
+    }
+    return { head: has ? text.slice(0, cut) : text, trailers, has };
+};
+const ids = (v) => v === null ? null : [...new Set(v.split(',').map(x => x.trim()))];
+// Roles: `<id>=<label>, …`; the label `none` clears one.
+const rolePairs = (v) => v === null ? null : v.split(',').map(x => x.trim().split('=').map(y => y.trim()));
+const isRole = (p) => p.length === 2 && ID_RE.test(p[0]) && TOKEN_RE.test(p[1]);
+const allIds = (xs) => !xs || xs.every(x => ID_RE.test(x));
+// A trailer present but outside its grammar.
+const malformed = (v, ok) => v !== null && !ok(v);
+// Why the address makes a message route nowhere, if it does.
+const addressProblem = (has, to) => {
+    if (!has)
+        return 'no trailer block';
+    if (!to)
+        return 'no To';
+    return to[0] === '*' || allIds(to) ? null : 'malformed To';
+};
+// Why the message is malformed, each reason once, in a fixed order.
+const problems = ({ raw, subject, has, trailers }, f, isRef) => {
+    const address = addressProblem(has, f.to);
+    const found = [
+        [!!f.pairs && !f.pairs.every(isRole), 'malformed Roles'],
+        [!subject, 'empty subject'],
+        [Buffer.byteLength(raw) > TEXT_MAX, 'text over 64 KiB'],
+        [address !== null, address ?? ''],
+        [!allIds(f.assign), 'malformed Assign'],
+        [malformed(f.get('re'), isRef), 'malformed Re'],
+        [malformed(f.get('hop'), v => HOP_RE.test(v)), 'malformed Hop'],
+        // A state is a token; whether the room's profile knows it is the store's check.
+        [malformed(f.get('state'), v => TOKEN_RE.test(v)), 'malformed State'],
+        [malformed(f.get('kind'), v => TOKEN_RE.test(v)), 'malformed Kind'],
+    ];
+    const duplicates = [...KNOWN].filter(k => (trailers[k]?.length ?? 0) > 1).map(k => `duplicate ${k}`);
+    return [...duplicates, ...found.filter(([b]) => b).map(([, why]) => why)];
+};
+// A malformed message is read as if it had no trailers.
+const UNROUTED = { to: [], assign: null, roles: null, re: null, kind: null, state: null, hop: 0 };
+const routed = ({ get, to, assign, pairs }) => ({ to: to, assign, roles: pairs ? Object.fromEntries(pairs) : null,
+    re: get('re'), kind: get('kind'), state: get('state'), hop: get('hop') === null ? 0 : Number(get('hop')) });
+// Parses well-formed and malformed text alike; `bad` names why a message routes nowhere. `isRef` is the store's
+// grammar for message ids in `Re`.
+export const parse = (raw, isRef) => {
+    const { head, trailers, has } = trailerBlock(raw.replace(/\r\n/g, '\n').trimEnd());
+    const nl = head.indexOf('\n');
+    const subject = (nl < 0 ? head : head.slice(0, nl)).trim();
+    const get = (k) => trailers[k]?.[0] ?? null;
+    const f = { get, to: get('to') === '*' ? ['*'] : ids(get('to')), assign: ids(get('assign')), pairs: rolePairs(get('roles')) };
+    const bad = problems({ raw, subject, has, trailers }, f, isRef);
+    const body = nl < 0 ? '' : head.slice(nl + 1).replace(/^\n+/, '').trimEnd();
+    return { subject, body, trailers, bad: bad.join(', ') || null, ...(bad.length ? UNROUTED : routed(f)) };
+};
+export const compose = (text, trailers) => `${text}\n\n${trailers.filter(([, v]) => v).map(([k, v]) => `${k}: ${v}`).join('\n')}\n`;
+// A client refuses to write what readers would drop or ignore (§3).
+export const checkOutgoing = (text, isRef) => {
+    const d = decodeText(Buffer.from(text));
+    if (d.invalid !== undefined)
+        fail(`refusing to send: ${d.invalid}`);
+    const m = parse(d.text, isRef);
+    if (m.bad)
+        fail(`refusing to send a malformed message: ${m.bad}`);
+    return m;
+};
+//# sourceMappingURL=text.js.map

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

@@ -0,0 +1,52 @@
+// threads: Re links and effective hops, and reading a thread (core-1 §5); the order of messages is order.ts.
+import { fail } from '../../../lib/index.js';
+import { ordered } from './order.js';
+// The hop a message counts from its parent: one more than an answered message, one for an unresolved Re.
+const hopAfter = (m, eff) => m.reId ? eff.get(m.reId) + 1 : m.re ? 1 : 0;
+// Effective hops along a message's Re chain, from the nearest one already known.
+const settleHops = (all, eff, m) => {
+    const chain = [];
+    for (let x = m; x && !eff.has(x.id) && chain.length < 100000; x = x.reId ? all.get(x.reId) : undefined)
+        chain.push(x);
+    for (const c of chain.reverse())
+        eff.set(c.id, Math.max(c.hop, hopAfter(c, eff)));
+};
+// Resolves Re and computes effective hops. Invalid messages are absent: a Re naming one does not resolve.
+export const link = (logs) => {
+    const all = new Map();
+    for (const msgs of logs.values())
+        for (const m of msgs)
+            if (!m.invalid)
+                all.set(m.id, m);
+    for (const m of all.values())
+        m.reId = m.re && all.has(m.re) ? m.re : null;
+    const eff = new Map();
+    for (const m of all.values()) {
+        settleHops(all, eff, m);
+        m.hopEff = eff.get(m.id);
+    }
+    return all;
+};
+const chainHas = (all, m, top) => {
+    for (let x = m, i = 0; x && i < 10000; x = x.reId ? all.get(x.reId) : undefined, i++)
+        if (x === top)
+            return true;
+    return false;
+};
+export const rootOf = (all, m) => {
+    let x = m;
+    for (let i = 0; x.reId && all.has(x.reId) && i < 10000; i++)
+        x = all.get(x.reId);
+    return x;
+};
+export const under = (all, top) => ordered([...all.values()].filter(m => chainHas(all, m, top)));
+export const lookup = (all, ref) => {
+    const key = String(ref ?? '').toLowerCase();
+    if (all.has(key))
+        return all.get(key);
+    const hits = key.length >= 4 ? [...all.keys()].filter(k => k.startsWith(key)) : [];
+    if (hits.length === 1)
+        return all.get(hits[0]);
+    return fail(hits.length ? `ambiguous message id ${ref}` : `unknown message ${ref}`);
+};
+//# sourceMappingURL=threads.js.map

package/target/esm/core/hub/rooms/compat.js

@@ -0,0 +1,51 @@
+// compat: the gates a hub passes before ringi reads it, all in one place: this machine's descriptor of it, its
+// contract's schema and major version, the protocol major, the capabilities its rooms need, and how its store lays out
+// what it keeps. The home has its own gate (adapters/state-fs). Each gate fails closed and says what to do. ringi migrates nothing: a hub it cannot read stays as it is, and the operator makes a new hub
+// beside it, or a new root branch on a forge (docs/ARCHITECTURE.md, Evolution).
+import { unenforceable } from '../capabilities.js';
+import { hubPorts } from '../ports/index.js';
+import { fail, short, strictJson } from '../../../lib/index.js';
+import { HUB_MAJOR, PROTOCOL_MAJOR } from './index.js';
+const version = () => hubPorts().build.version;
+// What to do with a hub this ringi cannot read.
+const beside = 'make a new hub beside it (ringi hub create <name>), or a new root branch on a forge; ringi does not migrate';
+const newer = (major, mine) => major > mine ? 'upgrade ringi' : beside;
+// Why this ringi cannot read the hub's descriptor (hub.json), or nothing.
+const knownSchema = (d, name) => d.schema === 'ringi-hub/2' && d.name === name;
+const knownStore = (d) => ['signed', 'asserted'].includes(d.trust) && !!d.store?.type && !!d.store.path;
+export const descriptorRefusal = (d, name) => knownSchema(d, name) && knownStore(d) ? null : `hub ${name}: its descriptor is not one this ringi ${version()} reads; ${beside}`;
+// Why this ringi cannot read the contract, or nothing.
+const refusal = (c, name) => {
+    if (c.schema !== 'ringi-hub')
+        return `hub ${name} declares schema ${String(c.schema)}, not ringi-hub`;
+    const major = Number(String(c.version).split('.')[0]);
+    if (major !== HUB_MAJOR)
+        return `hub ${name} follows contract version ${c.version}; this ringi ${version()} supports ${HUB_MAJOR}.x: ${newer(major, HUB_MAJOR)}`;
+    if (c.protocol !== PROTOCOL_MAJOR)
+        return `hub ${name} speaks protocol ${String(c.protocol)}; this ringi ${version()} speaks ${PROTOCOL_MAJOR}: ${newer(Number(c.protocol), PROTOCOL_MAJOR)}`;
+    const why = unenforceable(c.capabilities ?? []);
+    return why && `hub ${name} ${why}, which this ringi ${version()} cannot enforce. Upgrade ringi`;
+};
+// Old contract snapshots stay immutable after an explicit transition. Only ancestors of a readable canonical
+// main may use the old filename; an old current head or a room's attachment is never accepted this way.
+const historicalContract = (store, name, rev) => {
+    const head = store.contractHead();
+    if (rev === head || !store.extends(rev, head))
+        return null;
+    contractAt(store, name, head);
+    return store.contractFile(rev, 'hub.json');
+};
+// The contract at `rev`, once it passes every gate.
+export const contractAt = (store, name, rev) => {
+    const text = store.contractFile(rev, 'contract.json') ?? historicalContract(store, name, rev) ?? fail(`hub ${name} has no contract at ${short(rev)}`);
+    const c = strictJson(text, `hub ${name}: contract`);
+    const why = refusal(c, name);
+    if (why)
+        fail(why);
+    const a = store.contractFile(rev, 'authority.json');
+    return { ...c, authority: a === null ? {} : strictJson(a, `hub ${name}: authority.json at ${short(rev)}`) };
+};
+// Why this ringi cannot read the hub's store as it is laid out (`shown`: what its contract names, or what its store
+// type finds there when the contract names nothing), or nothing; `reads` is what the store type reads.
+export const layoutRefusal = (name, shown, reads) => shown === reads ? null : `hub ${name} keeps its store as ${shown}; this ringi ${version()} reads ${reads}: upgrade ringi if the hub is newer, or ${beside}`;
+//# sourceMappingURL=compat.js.map

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

@@ -0,0 +1,92 @@
+// hubs: a hub's descriptor beside its store, the contract it carries, and opening it.
+import fs from 'node:fs';
+import path from 'node:path';
+import * as D from '../decisions/index.js';
+import { DEFAULT_PROFILE, PROFILES_CAPABILITY } from '../work/index.js';
+import { hubPorts } from '../ports/index.js';
+import { fail } from '../../../lib/index.js';
+import { compose } from '../protocol/index.js';
+import { contractAt, descriptorRefusal, layoutRefusal } from './compat.js';
+import { PROTOCOL_MAJOR } from './index.js';
+// A hub on this machine is a directory under `hub` with its descriptor (`hub`) in it.
+const has = (name) => hubPorts().state.list(['hub', name]).includes('hub');
+export const hubNames = () => hubPorts().state.list(['hub']).filter(has);
+const VERSION = () => hubPorts().build.version;
+const HUB_MD = `# ringi hub
+
+The shared contract of a ringi hub (docs/spec/hub-1.md): contract.json (schema, version, protocol, trust, capabilities, the
+default profile), authority.json (who may decide what, up to which budget; the root, \`operator\`, always may) and
+profiles/ (what a piece of work is in a room: its states, and who may move it). Use \`ringi\`; never edit by hand.
+`;
+export const readProfileResource = (name) => fs.readFileSync(path.join(hubPorts().build.resources, 'profiles', `${name}.json`), 'utf8');
+// A new hub: local (asserted senders), or signed, with the operator's root key generated on this machine and pinned.
+// The files of a new hub's first contract.
+const genesisFiles = (d, layout) => {
+    const contract = { schema: 'ringi-hub', version: '1.2', protocol: PROTOCOL_MAJOR, trust: d.trust, store: layout, capabilities: [D.CAPABILITY, PROFILES_CAPABILITY], profile: DEFAULT_PROFILE, ...(d.root ? { root: d.root } : {}) };
+    return {
+        'contract.json': JSON.stringify(contract, null, 2) + '\n',
+        'authority.json': JSON.stringify({ decide: {} }, null, 2) + '\n',
+        'HUB.md': HUB_MD,
+        [`profiles/${DEFAULT_PROFILE}.json`]: readProfileResource(DEFAULT_PROFILE),
+    };
+};
+const descriptor = (name, signed, url) => ({ schema: 'ringi-hub/2', name, trust: signed ? 'signed' : 'asserted', store: { type: hubPorts().store, path: 'store', ...(url ? { remote: url } : {}) } });
+// The store type a descriptor names, as this build registers it.
+export const transportOf = (name, type) => {
+    const t = hubPorts().transports;
+    return t[type] ?? fail(`hub ${name} uses a ${type} store; this ringi ${VERSION()} knows ${Object.keys(t).join(', ')}`);
+};
+// A new hub: its store made, then its descriptor written; a failure in between leaves no half-made hub. `custody`: where
+// a signed hub's new root key is kept.
+export const createHub = (name, { signed = false, url } = {}) => {
+    const st = hubPorts().state;
+    st.ensure();
+    if (st.list(['hub']).includes(name))
+        fail(`hub ${name} exists`);
+    if (url && !signed)
+        fail('--url publishes a hub; only a --signed hub may be published');
+    const d = descriptor(name, signed, url);
+    try {
+        const t = transportOf(name, d.store.type);
+        const made = t.create(st.place(['hub', name]), d, x => ({ files: genesisFiles(x, t.layout), text: compose(`hub ${name}`, [['To', '*'], ['Kind', 'hub']]) }));
+        st.write(['hub', name, 'hub'], d);
+        return { custody: made.custody };
+    }
+    catch (e) {
+        if (!has(name))
+            st.remove(['hub', name]);
+        throw e;
+    }
+};
+const readDescriptor = (name) => {
+    const d = hubPorts().state.read(['hub', name, 'hub'], null) ?? fail(`no hub ${name}; hubs: ${hubNames().join(', ') || 'none'}`);
+    const why = descriptorRefusal(d, name);
+    if (why)
+        fail(why);
+    return d;
+};
+// A hub is opened once per process; its store syncs then (a signed store fetches and verifies), and again on refresh.
+const opened = new Map();
+export const openHub = (name, { refresh = false } = {}) => {
+    hubPorts().state.ensure();
+    if (!/^[a-z0-9]+(?:[._-][a-z0-9]+)*$/.test(name))
+        fail(`bad hub name ${name}`);
+    if (opened.has(name) && !refresh)
+        return opened.get(name);
+    if (name === 'local' && !has(name))
+        createHub('local');
+    const d = readDescriptor(name);
+    const dir = hubPorts().state.place(['hub', name]);
+    const t = transportOf(name, d.store.type);
+    const store = t.open(dir, d);
+    store.sync();
+    const main = store.contractHead();
+    const contract = contractAt(store, name, main);
+    const why = layoutRefusal(name, contract.store ?? t.layoutOf?.(store) ?? t.layout, t.layout);
+    if (why)
+        fail(why);
+    const H = { name, dir, d, store, main, contract, signed: d.trust === 'signed' };
+    opened.set(name, H);
+    return H;
+};
+//# sourceMappingURL=hubs.js.map

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

@@ -0,0 +1,23 @@
+// hub: hubs and rooms on top of any store. A hub is a directory with a descriptor (hub.json: which store, where,
+// what this machine pins) beside its store. Its shared contract lives in the store (contract.json, authority.json,
+// profiles/*.json). hubs.ts reads descriptors and contracts, rooms.ts opens rooms with their profile and authority,
+// messages.ts turns stored records into messages and writes them (docs/spec/hub-1.md).
+import { CAPABILITIES } from '../capabilities.js';
+// The root principal of every hub and room (hub-1): the operator of the machine that made it.
+export const OPERATOR = 'operator';
+export const HUB_MAJOR = 1;
+export const PROTOCOL_MAJOR = 1;
+export const CAPS = new Set(Object.keys(CAPABILITIES));
+export const RESERVED_ROOMS = new Set(['main', 'archive']);
+// Whether the room's work has started: it has the quorum of agents its genesis asked for (`Quorum`), or asked for none.
+export const start = (R) => {
+    const agents = Object.values(R.members).filter(m => m.role !== 'root').length;
+    return { quorum: R.quorum, agents, started: R.quorum === null || agents >= R.quorum };
+};
+export * from './hubs.js';
+export * from './compat.js';
+export * from './rooms.js';
+export * from './messages.js';
+export * from '../usecases/config.js';
+export { HIDDEN } from '../protocol/index.js';
+//# sourceMappingURL=index.js.map

package/target/esm/core/hub/rooms/messages.js

@@ -0,0 +1,47 @@
+// messages: stored records read as messages, and a message written with the signals it made.
+import * as D from '../decisions/index.js';
+import { compose, decodeText, link, parse } from '../protocol/index.js';
+import { emit } from '../signals/write.js';
+export const toMessage = (R, from, x, seq) => {
+    const trust = R.hub.signed ? 'verified' : 'asserted';
+    const files = x.files.map(f => ({ path: f.path, size: null }));
+    const base = { id: x.id, from, trust, time: x.time, seq, files, refused: x.refused, reId: null, hopEff: 0 };
+    const d = decodeText(x.text);
+    if (d.invalid !== undefined) {
+        return { ...base, invalid: d.invalid, subject: '', body: '', to: [], re: null, kind: null, state: null, assign: null, roles: null, hop: 0, bad: d.invalid, trailers: {} };
+    }
+    const p = parse(d.text, s => R.hub.store.isRef(s));
+    // An extension's trailers and the room profile's states are part of a message's validity.
+    const ext = D.check(p, s => R.hub.store.isRef(s));
+    const state = p.state && !p.bad && !R.profile.states.includes(p.state) ? `State ${p.state} is not in profile ${R.profile.name}` : null;
+    return { ...base, invalid: null, ...p, bad: p.bad ?? ext ?? state };
+};
+// The room as stored, read without a reader's lock or state: for an author working out the signals of its own message
+// (append runs inside reader locks too). Readers check signals themselves.
+const asStored = (R) => {
+    const s = R.hub.store.room(R.name) ?? R.s;
+    return link(new Map(R.hub.store.logIds(s).map(id => [id, R.hub.store.messages(s, id, R.hub.store.logHead(s, id)).map((x, seq) => toMessage(R, id, x, seq))])));
+};
+// Whether a message can make signals: it opens, assigns or moves work, or it is a record of the decisions extension.
+const DECISION_KINDS = ['proposal', 'stamp', 'decision', 'usage'];
+const movesWork = (p, R) => p.kind === R.profile.opens || !!p.assign || !!p.state;
+const CARRIES = (p, R) => !p.bad && (movesWork(p, R) || DECISION_KINDS.includes(p.kind ?? ''));
+// A message on the author's log, and the signals it made (core/hub/signals/write.ts).
+export const append = (R, who, text, entries = []) => {
+    const id = R.hub.store.append(R.s, who, text, entries);
+    if (CARRIES(parse(text, s => R.hub.store.isRef(s)), R)) {
+        const all = asStored(R);
+        const m = all.get(id);
+        if (m)
+            emit(R, who, all, m);
+    }
+    return id;
+};
+export const withSizes = (R, m) => {
+    if (!m.files.length)
+        return [];
+    const sizes = R.hub.store.sizes(m.id, m.files.map(f => f.path));
+    return m.files.map(f => ({ ...f, size: sizes.get(f.path) ?? null }));
+};
+export const pongText = (me, m, what) => compose(`pong: ${me} ${what}`, [['To', m.from], ['Re', m.id], ['Kind', 'pong'], ['Hop', String(m.hopEff + 1)]]);
+//# sourceMappingURL=messages.js.map

package/target/esm/core/hub/rooms/rooms.js

@@ -0,0 +1,84 @@
+// rooms: a room opened with its contract, authority, profile, members and quorum; and the root's control changes.
+import { DEFAULT_PROFILE, parseProfile } from '../work/index.js';
+import { locked } from '../ports/index.js';
+import { fail, strictJson } from '../../../lib/index.js';
+import { compose } from '../protocol/index.js';
+import { readProfileResource } from './hubs.js';
+import { contractAt } from './compat.js';
+export const roomNames = (H, archived = false) => H.store.roomNames(archived);
+// No room by that name: quiet, or why, naming an archive it may have become.
+const missing = (H, name, quiet) => {
+    if (quiet)
+        return null;
+    const gone = roomNames(H, true).find(a => a.startsWith(`${name}@`));
+    return fail(gone ? `room ${name} is archived as ${gone}; read it with --room ${gone}` : `no room ${name} in hub ${H.name}; rooms: ${roomNames(H).join(', ') || 'none'}`);
+};
+// The genesis names its room, in the root's hand: a history offered under another name is not that room.
+const checkNamed = (s, name) => {
+    const named = s.archived ? name.slice(0, name.lastIndexOf('@')) : name;
+    const subject = s.control[0]?.rev === s.genesis ? s.control[0].text.split('\n')[0] : '(none)';
+    const archiveName = !s.archived || name === `${named}@${s.genesis.slice(0, 8)}`;
+    if (subject !== `room ${named}` || !archiveName)
+        fail(`room ${name}: its genesis is "${subject}"; refusing a room's history under another name`);
+};
+// The contract in effect at each control entry: the hub contract the room was created on, then each `Contract:` the
+// operator moved it to. A decision names the control entry it was made under (core/hub/decisions/proposal.ts).
+const contracts = (s) => {
+    const atControl = new Map();
+    let current = s.base;
+    for (const rec of s.control) {
+        current = /^Contract: ([0-9a-f]{40,64})$/m.exec(rec.text)?.[1] ?? current;
+        atControl.set(rec.rev, current);
+    }
+    return { atControl, current };
+};
+const authorityOf = (H, atControl) => {
+    const tables = new Map();
+    return control => {
+        const rev = control ? atControl.get(control) : undefined;
+        if (!rev)
+            return null;
+        if (!tables.has(rev))
+            tables.set(rev, contractAt(H.store, H.name, rev).authority);
+        return tables.get(rev);
+    };
+};
+// The room's profile is fixed when the room is made: its content is copied into the genesis control entry, so no
+// later change of the hub's profiles or contract reinterprets the room's history. Rooms made before this carry none
+// and use the default profile of the contract they were created on.
+const profileOf = (H, s, name) => {
+    const base = contractAt(H.store, H.name, s.base).profile ?? DEFAULT_PROFILE;
+    const fallback = () => base === DEFAULT_PROFILE ? readProfileResource(DEFAULT_PROFILE) : fail(`room ${name}: unknown profile ${base}`);
+    return H.store.controlFile(s, 'profile.json', s.genesis) ?? H.store.contractFile(s.base, `profiles/${base}.json`) ?? fallback();
+};
+const membersOf = (H, s, name) => H.store.roster(s)?.members ?? strictJson(H.store.controlFile(s, 'members.json') ?? '{}', `room ${name}: members.json`);
+// The root's control records set the quorum; the latest one counts.
+const quorumOf = (s) => s.control.reduce((q, rec) => Number(/^Quorum: ([1-9][0-9]?)$/m.exec(rec.text)?.[1] ?? NaN) || q, null);
+export const openRoom = (H, name, { quiet = false } = {}) => {
+    if (!name)
+        return fail('no room: the operator creates one with ringi room create <id>, or picks one with ringi room switch <id>');
+    const s = H.store.room(name);
+    if (!s)
+        return missing(H, name, quiet);
+    checkNamed(s, name);
+    const { atControl, current } = contracts(s);
+    const contract = current === H.main ? H.contract : contractAt(H.store, H.name, current);
+    return { hub: H, s, name, archived: s.archived, head: s.head, genesis: s.genesis, contractRev: current, contract,
+        authorityAt: authorityOf(H, atControl), profile: parseProfile(profileOf(H, s, name), `room ${name}: profile`),
+        members: membersOf(H, s, name), quorum: quorumOf(s) };
+};
+export const room = (H, name) => openRoom(H, name);
+export const ROOM_MD = (name) => `# room ${name}\n\nA ringi room: members.json lists who takes part; profile.json is what a piece of work is here, fixed when the room was made.\n`;
+export const profileText = (H, name) => H.store.contractFile(H.main, `profiles/${name}.json`) ?? (name === DEFAULT_PROFILE ? readProfileResource(DEFAULT_PROFILE) : null);
+// A control change under the hub lock. In a signed room membership changes only through `room admit`.
+export const controlChange = (R, who, subject, mutate, extra = []) => locked(`hub-${R.hub.name}`, () => {
+    const s = R.hub.store.room(R.name) ?? fail(`room ${R.name} is gone`);
+    const members = strictJson(R.hub.store.controlFile(s, 'members.json') ?? '{}', `room ${R.name}: members.json`);
+    const before = JSON.stringify(members);
+    mutate(members);
+    if (R.hub.signed && JSON.stringify(members) !== before)
+        fail('in a signed room, membership changes only by ringi room admit');
+    R.head = R.hub.store.updateControl(s, who, compose(subject, [['To', '*'], ['Kind', 'room'], ...extra]), { 'members.json': JSON.stringify(members, null, 2) + '\n' });
+    R.members = members;
+});
+//# sourceMappingURL=rooms.js.map

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

@@ -0,0 +1,33 @@
+// check: a signal holds when its author made it, it is named after and points at a message of its author in this room,
+// and that message made exactly this signal; a mark holds when it is possible.
+import { effective } from './effective.js';
+import { markWhy } from './marks.js';
+import { MARKS } from './model.js';
+const namedAfter = (id, target) => id.length === 12 && target.startsWith(id);
+const signalWhy = (R, all, actor, m, signal) => {
+    if (m.from !== actor)
+        return `points at a message of ${m.from}`;
+    return effective(R, all, m).includes(signal) ? undefined : `its message did not make ${signal}`;
+};
+const whyNot = (R, all, x, id, signal) => {
+    const m = all.get(x.target);
+    const shape = [
+        [!x.target, 'is not an annotated tag on a message'],
+        [x.tagger !== x.actor, `was made by ${x.tagger}, not ${x.actor}`],
+        [!namedAfter(id, x.target), 'is named after another message'],
+        [!m, 'points at no accepted message of this room'],
+    ];
+    const wrong = shape.find(([bad]) => bad);
+    if (wrong)
+        return wrong[1];
+    const meaning = MARKS.includes(signal) ? markWhy(R, x.actor, m, signal) : signalWhy(R, all, x.actor, m, signal);
+    // A signal is its name and its target; any text besides a signature is not one.
+    return meaning ?? (x.text === '' ? undefined : 'carries text; a signal has none');
+};
+export const check = (R, all, records) => records.map(x => {
+    const dot = x.name.lastIndexOf('.');
+    const signal = x.name.slice(0, dot);
+    const why = whyNot(R, all, x, x.name.slice(dot + 1), signal);
+    return { ref: x.ref, actor: x.actor, signal, target: x.target, ok: !why, why };
+});
+//# sourceMappingURL=check.js.map

package/target/esm/core/hub/signals/effective.js

@@ -0,0 +1,31 @@
+// effective: the signals a message made, judged on the room as it is now (thread order is fixed, so this does not
+// change).
+import * as D from '../decisions/index.js';
+import { taskFor, taskOf } from '../work/index.js';
+import { one } from '../protocol/index.js';
+const isWorkSignal = (fx) => fx === 'opened' || fx === 'assigned' || fx.startsWith('state.');
+// What the message did to its piece of work: opened, assigned, a state.
+const workSignals = (R, all, m) => {
+    const work = taskFor(all, m, R.profile);
+    return work ? (taskOf(all, work, R.profile).effects.get(m.id) ?? []).filter(isWorkSignal) : [];
+};
+// A proposal, and a usage receipt its grant's ledger counts.
+const ownSignals = (R, all, m) => [
+    ...m.kind === 'proposal' ? ['proposed'] : [],
+    ...m.kind === 'usage' && D.counted(all, R.authorityAt, m) ? [`usage.${one(m, 'usage')}`] : [],
+];
+// An answer to a proposal: a counted stamp, the decision, its revocation.
+const answerSignals = (R, all, m) => {
+    const p = m.reId ? all.get(m.reId) : undefined;
+    if (p?.kind !== 'proposal' || p.bad)
+        return [];
+    const info = D.proposalOf(all, p, R.authorityAt);
+    const decided = m.kind === 'decision';
+    return [
+        ...m.kind === 'stamp' && info.reviewers.includes(m.from) ? [`stamp.${one(m, 'stamp')}`] : [],
+        ...decided && info.decision?.id === m.id ? [`decision.${info.decision.decision}`] : [],
+        ...decided && info.revoked?.id === m.id ? ['decision.revoked'] : [],
+    ];
+};
+export const effective = (R, all, m) => m.bad || m.invalid ? [] : [...workSignals(R, all, m), ...ownSignals(R, all, m), ...answerSignals(R, all, m)];
+//# sourceMappingURL=effective.js.map

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

@@ -0,0 +1,23 @@
+// signals: explicit markers of what happens in a room, beside the messages that carry it. Every effective transition
+// (work opened, assigned, a state reached, a proposal, a counted stamp, the decision, a counted usage receipt) is also
+// a signal of its author on the message that made it: in a git store an annotated tag `<author>.<signal>.<message12>`
+// on that message's commit, with no text of its own, signed on a signed hub. The message's id keeps the name unique;
+// the name, target, author and time are the tag itself. Signals are visible and checkable with the store's own tools
+// (`git tag -v`, a forge's tag list and tag-push webhooks) and cheap to poll.
+//
+// The messages stay the truth. A signal is made only for a transition the fold actually counted (a State the author
+// had no right to makes none). A reader checks every signal against its message and pins the stored object it
+// accepted; a signal that disagrees, or an accepted one that changes or disappears, is an alarm. A signal missing
+// after a crash between message and tag changes nothing and is restored with `signals --repair`.
+//
+// Marks are the second layer, in the same namespace: where attention is, not what was decided. `read` says a message
+// reached its reader (made on delivery); `taken` says a member took a piece of work. A mark changes no state,
+// assignment or budget. It is checked only for being possible: its target is an accepted message of the room, its
+// actor a member; `read` only for a message addressed to the actor or to all, `taken` only for a message that opens
+// work.
+export * from './model.js';
+export * from './marks.js';
+export * from './effective.js';
+export * from './check.js';
+export * from './pins.js';
+//# sourceMappingURL=index.js.map

package/target/esm/core/hub/signals/marks.js

@@ -0,0 +1,30 @@
+// marks: where attention is — `read` on delivery, `taken` on demand — possible or not, and who put which on what.
+import { HIDDEN, visible } from '../protocol/index.js';
+import { MARKS } from './model.js';
+// Why each mark cannot be put on this message, or nothing when it can.
+const RULES = {
+    read: (_R, actor, m) => {
+        if (m.from === actor)
+            return 'one does not read one\'s own message';
+        return visible(m, actor, HIDDEN) ? undefined : `the message is not delivered to ${actor}`;
+    },
+    taken: (R, _actor, m) => m.kind !== R.profile.opens || m.bad ? `the message does not open work (${R.profile.opens})` : undefined,
+};
+// Why the actor cannot put this mark on this message, or nothing when it can.
+export const markWhy = (R, actor, m, mark) => {
+    if (!R.members[actor])
+        return `${actor} is not a member of ${R.name}`;
+    const rule = RULES[mark];
+    return rule ? rule(R, actor, m) : `unknown mark ${mark}`;
+};
+// The marks on each message that passed the check: target → mark → actors.
+export const marksOn = (checked) => {
+    const by = new Map();
+    for (const c of checked.filter(c => c.ok && MARKS.includes(c.signal))) {
+        const e = by.get(c.target) ?? {};
+        (e[c.signal] ??= []).push(c.actor);
+        by.set(c.target, e);
+    }
+    return by;
+};
+//# sourceMappingURL=marks.js.map

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

@@ -0,0 +1,5 @@
+// model: what the folds need of a room, and a signal as a store returns it.
+export const MARKS = ['read', 'taken'];
+// A signal's name after its actor: the signal and the message's short id.
+export const signalName = (id, signal) => `${signal}.${id.slice(0, 12)}`;
+//# sourceMappingURL=model.js.map

package/target/esm/core/hub/signals/pins.js

@@ -0,0 +1,21 @@
+// pins: a reader's pins, the stored object of each signal it accepted. A changed or vanished one is an alarm.
+// A signal's identity in any store and after an archive: its tag's name `<actor>.<signal>.<message12>`.
+const keyOf = (ref) => ref.split('/').at(-1);
+export const pins = (records, checked, accepted = {}) => {
+    const now = new Map(records.map(x => [`${x.actor}.${x.name}`, x]));
+    const alarms = [];
+    const next = {};
+    for (const [k, object] of Object.entries(accepted)) {
+        const key = keyOf(k), x = now.get(key);
+        next[key] = object;
+        if (!x)
+            alarms.push(`signal ${key} was removed after it was accepted`);
+        else if (x.object !== object)
+            alarms.push(`signal ${x.ref} was replaced after it was accepted`);
+    }
+    for (const c of checked)
+        if (c.ok && !next[keyOf(c.ref)])
+            next[keyOf(c.ref)] = now.get(keyOf(c.ref)).object;
+    return { accepted: next, alarms };
+};
+//# sourceMappingURL=pins.js.map

package/target/esm/{hub/signals.js → core/hub/signals/write.js}

@@ -1,7 +1,7 @@
 // signals (write side): an author stores the signals its message made and the marks it puts; readers check them
-// (domain/signals.ts).
-import { effective, markWhy, signalName } from '../domain/signals.js';
-import { fail } from '../lib/index.js';
+// (index.ts).
+import { effective, markWhy, signalName } from './index.js';
+import { fail } from '../../../lib/index.js';
 // Puts one of the actor's marks on a message; false if it was already there.
 export const mark = (R, who, m, name) => {
     const why = markWhy(R, who, m, name);
@@ -24,4 +24,4 @@ export const emit = (R, who, all, m) => {
     }
     return n;
 };
-//# sourceMappingURL=signals.js.map
+//# sourceMappingURL=write.js.map

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

@@ -0,0 +1,3 @@
+// actor: who acts, and in which room; every operation of a participant takes one.
+export const isRef = (R) => (x) => R.hub.store.isRef(x);
+//# sourceMappingURL=actor.js.map