@idleware/ringi 0.0.0-stage → 0.1.0

package/target/esm/domain/profiles.js

@@ -0,0 +1,96 @@
+// profile: what a task is, as data. ringi is a point of coordination, not a methodology: the states of a piece of
+// work, which of them end it, and who may move it, assign it or label people in it are declared by a profile
+// that lives in the hub (`profiles/<name>.json` on main) and is chosen per room. The A2A task model is one such
+// profile (resources/profiles/a2a-1.json); a team or a framework brings its own (architect, reviewer, tester, …).
+// This file interprets any profile; it knows no state, role or rule by name.
+import { HEARTBEATS, ID_RE, TOKEN_RE, one, ordered } from '../protocol/index.js';
+import { fail, strictJson } from '../lib/index.js';
+export const PROFILE_SCHEMA = 'ringi-profile/1';
+export const DEFAULT_PROFILE = 'a2a-1';
+// A hub whose rooms may follow profiles other than the built-in A2A rules declares this capability, so that an older
+// client, which knows only those rules, refuses it instead of misreading it.
+export const PROFILES_CAPABILITY = 'profiles/1';
+const PRINCIPAL_RE = /^(?:requester|assignee|member|role:[a-z][a-z0-9-]*|agent:[a-z0-9]+(?:[._-][a-z0-9]+)*)$/;
+// A profile is refused, not guessed at, when it is not exactly what this schema describes.
+export const parseProfile = (text, label) => {
+    const p = strictJson(text, label);
+    const bad = (why) => fail(`${label}: ${why}`);
+    if (p.schema !== PROFILE_SCHEMA)
+        bad(`schema ${String(p.schema)} is not ${PROFILE_SCHEMA}; upgrade ringi or fix the profile`);
+    if (!ID_RE.test(p.name ?? ''))
+        bad('a profile needs a name like team-flow-1');
+    if (!TOKEN_RE.test(p.opens ?? ''))
+        bad('`opens` names the Kind that opens a piece of work');
+    if (!Array.isArray(p.states) || !p.states.length || !p.states.every(s => TOKEN_RE.test(s)) || new Set(p.states).size !== p.states.length)
+        bad('`states` must be distinct tokens');
+    if (!p.states.includes(p.initial))
+        bad('`initial` must be one of the states');
+    if (!Array.isArray(p.terminal) || !p.terminal.every(s => p.states.includes(s)))
+        bad('`terminal` must list states');
+    if (p.waiting !== undefined && (!p.states.includes(p.waiting) || p.terminal.includes(p.waiting)))
+        bad('`waiting` must be a state that does not end the work');
+    if (!p.rules || typeof p.rules !== 'object')
+        bad('`rules` is required');
+    for (const [k, v] of Object.entries(p.rules)) {
+        if (!/^(?:assign|roles|grant|state:(?:\*|[a-z][a-z0-9-]*))$/.test(k))
+            bad(`unknown rule ${k}`);
+        if (k.startsWith('state:') && k !== 'state:*' && !p.states.includes(k.slice(6)))
+            bad(`rule ${k} names an unknown state`);
+        if (!Array.isArray(v) || v.length > 64 || !v.every(x => PRINCIPAL_RE.test(x)))
+            bad(`rule ${k} must list principals: requester, assignee, member, role:<label>, agent:<id>`);
+    }
+    return p;
+};
+const allows = (rule, who, t) => !!rule?.some(p => p === 'requester' ? who === t.requester
+    : p === 'assignee' ? t.assignees.includes(who)
+        : p === 'member' ? true
+            : p.startsWith('role:') ? t.roles[who] === p.slice(5)
+                : p === `agent:${who}`);
+export const ruleFor = (profile, state) => profile.rules[`state:${state}`] ?? profile.rules['state:*'];
+// A message belongs to the nearest work item on its Re chain, itself included.
+export const taskFor = (all, m, profile) => {
+    for (let x = m, i = 0; x && i < 100000; x = x.reId ? all.get(x.reId) : undefined, i++)
+        if (x.kind === profile.opens && !x.bad)
+            return x;
+    return null;
+};
+// A work item folds over its messages in thread order. Every right is judged on the work as it was before the
+// message, so a label given in a message authorizes nothing in that same message, while its holder may still hand it
+// over and reassign in one reply. Opening sets the initial state and assignees (Assign, else To minus the opener; none
+// for To: *). The first terminal state is final; assignment and labels may still change after it.
+export const taskOf = (all, root, profile) => {
+    // Heartbeats never take part in work (§6), whatever trailers they carry.
+    const msgs = ordered([...all.values()].filter(m => !m.bad && !(m.kind && HEARTBEATS.has(m.kind)) && taskFor(all, m, profile) === root));
+    const t = { root, msgs, state: profile.initial, by: root.from, at: root.time, requester: root.from, roles: { ...root.roles },
+        assignees: root.assign ?? (root.to.includes('*') ? [] : root.to.filter(x => x !== root.from)), grant: one(root, 'grant'), effects: new Map() };
+    t.effects.set(root.id, ['opened', ...(root.assign ? ['assigned'] : [])]);
+    for (const m of msgs) {
+        if (m === root)
+            continue;
+        const before = { ...t, roles: { ...t.roles }, assignees: [...t.assignees] };
+        const fx = [];
+        if (one(m, 'grant') && allows(profile.rules.grant, m.from, before)) {
+            t.grant = one(m, 'grant');
+            fx.push('grant');
+        }
+        if (m.roles && allows(profile.rules.roles, m.from, before)) {
+            for (const [id, label] of Object.entries(m.roles))
+                label === 'none' ? delete t.roles[id] : t.roles[id] = label;
+            fx.push('roles');
+        }
+        if (m.assign && allows(profile.rules.assign, m.from, before)) {
+            t.assignees = m.assign;
+            fx.push('assigned');
+        }
+        if (m.state && !profile.terminal.includes(t.state) && profile.states.includes(m.state) && allows(ruleFor(profile, m.state), m.from, before)) {
+            Object.assign(t, { state: m.state, by: m.from, at: m.time });
+            fx.push(`state.${m.state}`);
+        }
+        if (fx.length)
+            t.effects.set(m.id, fx);
+    }
+    return t;
+};
+export const tasksIn = (all, profile) => [...all.values()].filter(m => m.kind === profile.opens && !m.bad).map(r => taskOf(all, r, profile));
+export const isOpen = (t, profile) => !profile.terminal.includes(t.state);
+//# sourceMappingURL=profiles.js.map

package/target/esm/domain/signals.js

@@ -0,0 +1,129 @@
+// 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 in its author's own namespace under the room's genesis, pointing at the message that made it: in a git
+// store an annotated tag `ringi/<genesis>/<author>/<message>.<signal>`, signed on a signed hub. 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.
+import * as D from './decisions.js';
+import { taskFor, taskOf } from './profiles.js';
+import { HIDDEN, one, visible } from '../protocol/index.js';
+export const MARKS = ['read', 'taken'];
+// The canonical text of a signal or mark: what its author stores and every reader compares.
+export const signalBody = (R, who, id, signal) => `${signal}\n\nRoom: ${R.name}\nGenesis: ${R.genesis}\nActor: ${who}\nMessage: ${id}\nSignal: ${signal}\n`;
+// Why the actor cannot put this mark on this message, or nothing when it can.
+export const markWhy = (R, actor, m, mark) => !R.members[actor] ? `${actor} is not a member of ${R.name}`
+    : mark === 'read' ? (m.from === actor ? 'one does not read one\'s own message' : !visible(m, actor, HIDDEN) ? `the message is not delivered to ${actor}` : undefined)
+        : mark === 'taken' ? (m.kind !== R.profile.opens || m.bad ? `the message does not open work (${R.profile.opens})` : undefined)
+            : `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) {
+        if (!c.ok || !MARKS.includes(c.signal))
+            continue;
+        const e = by.get(c.target) ?? {};
+        (e[c.signal] ??= []).push(c.actor);
+        by.set(c.target, e);
+    }
+    return by;
+};
+// The signals a message made, judged on the room as it is now (thread order is fixed, so this does not change).
+export const effective = (R, all, m) => {
+    if (m.bad || m.invalid)
+        return [];
+    const s = [];
+    const work = taskFor(all, m, R.profile);
+    if (work)
+        for (const fx of taskOf(all, work, R.profile).effects.get(m.id) ?? [])
+            if (fx === 'opened' || fx === 'assigned' || fx.startsWith('state.'))
+                s.push(fx);
+    if (m.kind === 'proposal')
+        s.push('proposed');
+    if (m.kind === 'usage' && D.counted(all, R.authorityAt, m))
+        s.push(`usage.${one(m, 'usage')}`);
+    const p = m.reId ? all.get(m.reId) : undefined;
+    if (p?.kind === 'proposal' && !p.bad) {
+        const info = D.proposalOf(all, p, R.authorityAt);
+        if (m.kind === 'stamp' && info.reviewers.includes(m.from))
+            s.push(`stamp.${one(m, 'stamp')}`);
+        if (m.kind === 'decision' && info.decision?.id === m.id)
+            s.push(`decision.${info.decision.decision}`);
+        if (m.kind === 'decision' && info.revoked?.id === m.id)
+            s.push('decision.revoked');
+    }
+    return s;
+};
+// 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.
+export const check = (R, all, records) => records.map(x => {
+    const dot = x.name.indexOf('.');
+    const id = x.name.slice(0, dot);
+    const signal = x.name.slice(dot + 1);
+    const m = all.get(x.target);
+    const what = () => {
+        if (!x.target)
+            return 'is not an annotated tag on a message';
+        if (x.tagger !== x.actor)
+            return `was made by ${x.tagger}, not ${x.actor}`;
+        if (id !== x.target)
+            return 'is named after another message';
+        if (!m)
+            return 'points at no accepted message of this room';
+        if (MARKS.includes(signal)) {
+            const why = markWhy(R, x.actor, m, signal);
+            if (why)
+                return why;
+        }
+        else {
+            if (m.from !== x.actor)
+                return `points at a message of ${m.from}`;
+            if (!effective(R, all, m).includes(signal))
+                return `its message did not make ${signal}`;
+        }
+        // Signals and marks alike carry exactly their canonical body (a signed one, its signature after it).
+        if (x.text.split('-----BEGIN SSH SIGNATURE-----')[0].trimEnd() !== signalBody({ ...R, name: R.name.split('@')[0] }, x.actor, x.target, signal).trimEnd())
+            return 'its trailers disagree with the signal';
+        return undefined;
+    };
+    const why = what();
+    return { ref: x.ref, actor: x.actor, signal, target: x.target, ok: !why, why };
+});
+// A signal's identity in any store and after an archive: `<actor>/<message>.<signal>`, the last two components of its
+// ref; pins an older reader kept under a full ref read the same way.
+const keyOf = (ref) => ref.split('/').slice(-2).join('/');
+// A reader's pins: the stored object of each signal it accepted. A changed or vanished one is an alarm.
+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);
+        // Two old pins of one signal (its live and its archived ref) that disagree: keep the first as accepted and the
+        // other under its own ref as evidence, so the conflict is reported on every read until it is resolved.
+        if (key in next && next[key] !== object) {
+            alarms.push(`signal ${key} has two different accepted objects (${next[key]} and ${object})`);
+            next[k] = object;
+            continue;
+        }
+        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=signals.js.map

package/target/esm/home/index.js

@@ -0,0 +1,88 @@
+// home: where ringi keeps its state on this machine. $RINGI_HOME holds hubs (each a descriptor and a store),
+// reader state, session records and locks. Reading state fails closed; a write the sandbox denies fails with one
+// fixed instruction.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { errno, fail, guardWrite, locked as lockFile, mkdirIn, note, writeJsonAtomic } from '../lib/index.js';
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+// This file sits in src/main/ts/home (source) or target/esm/home (build): three levels below the package root.
+export const ROOT = path.resolve(HERE, '..', '..', '..');
+export const RESOURCES = path.join(ROOT, 'src', 'main', 'resources');
+export const VERSION = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8')).version;
+export const HOME = path.resolve(process.env.RINGI_HOME || path.join(os.homedir(), '.ringi'));
+export const HOME_VERSION = 3;
+export const OPERATOR = 'operator';
+// --- writing safely ---
+export const guard = (fn) => guardWrite(HOME, fn);
+export const mkdir = (d) => mkdirIn(HOME, d);
+export const writeJson = (f, v) => guard(() => {
+    mkdir(path.dirname(f));
+    writeJsonAtomic(f, v);
+});
+// State fails closed: unreadable JSON is an error, never a silent fresh start.
+export const readJson = (f, dflt) => {
+    let raw;
+    try {
+        raw = fs.readFileSync(f, 'utf8');
+    }
+    catch (e) {
+        if (errno(e) === 'ENOENT')
+            return dflt;
+        throw e;
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (e) {
+        return fail(`${f} is not valid JSON (${e.message}); refusing to continue with lost state`);
+    }
+};
+// --- the home ---
+export const hubsDir = () => path.join(HOME, 'hub');
+export const hubHome = (name) => path.join(hubsDir(), name);
+// The home is created on first use; anything else at that path is refused. A home of the previous layout (each hub a
+// bare repository `hub/<name>.git` with its settings in git config) is moved into descriptor and store.
+export const ensureHome = () => {
+    const marker = path.join(HOME, 'home.json');
+    if (fs.existsSync(marker)) {
+        const h = readJson(marker, {});
+        if (h.version === 2)
+            return migrate2(marker);
+        if (h.version !== HOME_VERSION)
+            fail(`${HOME} is a ringi home of version ${h.version}; this ringi ${VERSION} needs version ${HOME_VERSION}`);
+        return;
+    }
+    if (fs.existsSync(HOME) && fs.readdirSync(HOME).length)
+        fail(`${HOME} exists and is not a ringi home (no home.json); move it away or set RINGI_HOME`);
+    mkdir(HOME);
+    writeJson(marker, { version: HOME_VERSION });
+};
+const migrate2 = (marker) => {
+    for (const f of fs.existsSync(hubsDir()) ? fs.readdirSync(hubsDir()).filter(f => f.endsWith('.git')) : []) {
+        const name = f.slice(0, -4);
+        const old = path.join(hubsDir(), f);
+        const cfg = (k) => String(spawnSync('git', ['--git-dir', old, 'config', '--get', k], { encoding: 'utf8' }).stdout ?? '').trim();
+        const signed = cfg('ringi.type') === 'remote';
+        const descriptor = { schema: 'ringi-hub/2', name, trust: signed ? 'signed' : 'asserted',
+            ...(signed ? { root: cfg('ringi.rootKey') || undefined, genesis: cfg('ringi.genesis') || undefined } : {}),
+            store: { type: 'git', path: 'store', ...(cfg('remote.origin.url') ? { remote: cfg('remote.origin.url') } : {}) } };
+        mkdir(path.join(hubHome(name), 'store'));
+        guard(() => fs.renameSync(old, path.join(hubHome(name), 'store', '.git')));
+        writeJson(path.join(hubHome(name), 'hub.json'), descriptor);
+        note(`moved hub ${name} to ${hubHome(name)} (descriptor hub.json, store/.git)`);
+    }
+    writeJson(marker, { version: HOME_VERSION });
+};
+export const locked = (name, fn) => {
+    ensureHome();
+    const dir = path.join(HOME, 'locks');
+    mkdir(dir);
+    return guard(() => lockFile(path.join(dir, `${name}.lock`), fn));
+};
+export const configFile = () => path.join(HOME, 'config.json');
+export const config = () => ({ hub: 'local', room: null, ...readJson(configFile(), {}) });
+export const setConfig = (patch) => writeJson(configFile(), { ...config(), ...patch });
+//# sourceMappingURL=index.js.map

package/target/esm/hub/index.js

@@ -0,0 +1,212 @@
+// 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). This file reads contracts, opens rooms with their profile and authority, and decides what a reader
+// accepts: only history that extends what it accepted before, from members the store verifies (docs/spec/hub-1.md, Trust).
+import fs from 'node:fs';
+import path from 'node:path';
+import * as D from '../domain/decisions.js';
+import { CAPABILITIES, unenforceable } from '../domain/index.js';
+import { GitStore } from '../store/git/index.js';
+import { HOME, OPERATOR, RESOURCES, VERSION, ensureHome, hubHome, hubsDir, locked, mkdir, writeJson } from '../home/index.js';
+import { DEFAULT_PROFILE, PROFILES_CAPABILITY, parseProfile } from '../domain/profiles.js';
+import { HIDDEN, compose, decodeText, link, parse } from '../protocol/index.js';
+import { emit } from './signals.js';
+import { STORES } from '../store/index.js';
+import { fail, short, strictJson } from '../lib/index.js';
+export const HUB_MAJOR = 1;
+export const CAPS = new Set(Object.keys(CAPABILITIES));
+export const RESERVED_ROOMS = new Set(['main', 'archive']);
+// --- hubs ---
+export const hubNames = () => {
+    try {
+        return fs.readdirSync(hubsDir()).filter(n => fs.existsSync(path.join(hubsDir(), n, 'hub.json'))).sort();
+    }
+    catch {
+        return [];
+    }
+};
+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.
+`;
+const readProfileResource = (name) => fs.readFileSync(path.join(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.
+export const createHub = (name, { signed = false, url } = {}) => {
+    ensureHome();
+    const dir = hubHome(name);
+    if (fs.existsSync(dir))
+        fail(`hub ${name} exists`);
+    if (url && !signed)
+        fail('--url publishes a hub; only a --signed hub may be published');
+    const d = { schema: 'ringi-hub/2', name, trust: signed ? 'signed' : 'asserted', store: { type: 'git', path: 'store', ...(url ? { remote: url } : {}) } };
+    try {
+        mkdir(dir);
+        if (signed)
+            d.root = GitStore.rootFor(dir, d, HOME);
+        const contract = { schema: 'ringi-hub', version: '1.1', protocol: 1, trust: d.trust, capabilities: [D.CAPABILITY, PROFILES_CAPABILITY], profile: DEFAULT_PROFILE, ...(d.root ? { root: d.root } : {}) };
+        const store = GitStore.create(dir, d, HOME, {
+            '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),
+        }, compose(`hub ${name}`, [['To', '*'], ['Kind', 'hub']]));
+        if (signed)
+            d.genesis = store.contractHead();
+        writeJson(path.join(dir, 'hub.json'), d);
+    }
+    catch (e) {
+        if (!fs.existsSync(path.join(dir, 'hub.json')))
+            fs.rmSync(dir, { recursive: true, force: true });
+        throw e;
+    }
+};
+export const readDescriptor = (name) => {
+    const f = path.join(hubHome(name), 'hub.json');
+    if (!fs.existsSync(f))
+        fail(`no hub ${name}; hubs: ${hubNames().join(', ') || 'none'}`);
+    const d = strictJson(fs.readFileSync(f, 'utf8'), f);
+    if (d.schema !== 'ringi-hub/2' || d.name !== name || !['signed', 'asserted'].includes(d.trust) || !d.store?.type || !d.store.path)
+        fail(`${f} is not a ringi hub descriptor this ringi ${VERSION} reads`);
+    return d;
+};
+// The contract a tool must understand before it touches a hub or a room: known schema, major and capabilities.
+export const contractAt = (store, name, rev) => {
+    const text = store.contractFile(rev, 'contract.json') ?? store.contractFile(rev, 'hub.json') ?? fail(`hub ${name} has no contract at ${short(rev)}`);
+    const c = strictJson(text, `hub ${name}: contract`);
+    if (c.schema !== 'ringi-hub')
+        fail(`hub ${name} declares schema ${String(c.schema)}, not ringi-hub`);
+    const major = Number(String(c.version).split('.')[0]);
+    if (major !== HUB_MAJOR)
+        fail(`hub ${name} follows contract version ${c.version}; this ringi ${VERSION} supports ${HUB_MAJOR}.x. Upgrade ringi`);
+    const why = unenforceable(c.capabilities ?? []);
+    if (why)
+        fail(`hub ${name} ${why}, which this ringi ${VERSION} cannot enforce. Upgrade ringi`);
+    const a = store.contractFile(rev, 'authority.json');
+    return { ...c, authority: a === null ? {} : strictJson(a, `hub ${name}: authority.json at ${short(rev)}`) };
+};
+// 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 } = {}) => {
+    ensureHome();
+    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' && !fs.existsSync(path.join(hubHome(name), 'hub.json')))
+        createHub('local');
+    const d = readDescriptor(name);
+    const factory = STORES[d.store.type] ?? fail(`hub ${name} uses a ${d.store.type} store; this ringi ${VERSION} knows ${Object.keys(STORES).join(', ')}`);
+    const store = factory(hubHome(name), d, HOME);
+    store.sync();
+    const main = store.contractHead();
+    const H = { name, dir: hubHome(name), d, store, main, contract: contractAt(store, name, main), signed: d.trust === 'signed' };
+    opened.set(name, H);
+    return H;
+};
+// --- rooms ---
+export const roomNames = (H, archived = false) => H.store.roomNames(archived);
+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) {
+        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 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)';
+    if (subject !== `room ${named}` || (s.archived && name !== `${named}@${s.genesis.slice(0, 8)}`))
+        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 (decide.ts).
+    const atControl = new Map();
+    let current = s.base;
+    for (const rec of s.control) {
+        const m = /^Contract: ([0-9a-f]{40,64})$/m.exec(rec.text);
+        if (m)
+            current = m[1];
+        atControl.set(rec.rev, current);
+    }
+    const contract = current === H.main ? H.contract : contractAt(H.store, H.name, current);
+    const tables = new Map();
+    const authorityAt = (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 baseProfile = contractAt(H.store, H.name, s.base).profile ?? DEFAULT_PROFILE;
+    const profileText = H.store.controlFile(s, 'profile.json', s.genesis)
+        ?? H.store.contractFile(s.base, `profiles/${baseProfile}.json`)
+        ?? (baseProfile === DEFAULT_PROFILE ? readProfileResource(DEFAULT_PROFILE) : fail(`room ${name}: unknown profile ${baseProfile}`));
+    const roster = H.store.roster(s);
+    const members = roster?.members ?? strictJson(H.store.controlFile(s, 'members.json') ?? '{}', `room ${name}: members.json`);
+    return { hub: H, s, name, archived: s.archived, head: s.head, genesis: s.genesis, contractRev: current, contract, authorityAt,
+        profile: parseProfile(profileText, `room ${name}: profile`), members };
+};
+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;
+});
+// --- messages and what a reader accepts ---
+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.bad && p.state && !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.
+export 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))])));
+};
+const CARRIES = (p, R) => !p.bad && (p.kind === R.profile.opens || !!p.assign || !!p.state || ['proposal', 'stamp', 'decision', 'usage'].includes(p.kind ?? ''));
+// A message on the author's log, and the signals it made (signals.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)]]);
+export { OPERATOR, HIDDEN };
+//# sourceMappingURL=index.js.map

package/target/esm/hub/signals.js

@@ -0,0 +1,27 @@
+// 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, signalBody as body } from '../domain/signals.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);
+    if (why)
+        fail(`cannot mark ${m.id.slice(0, 12)} ${name}: ${why}`);
+    if (R.hub.store.signals(R.s).some(x => x.actor === who && x.name === `${m.id}.${name}`))
+        return false;
+    R.hub.store.signal(R.s, who, m.id, `${m.id}.${name}`, body(R, who, m.id, name));
+    return true;
+};
+// Writes the signals of one of the author's own messages that are not stored yet.
+export const emit = (R, who, all, m) => {
+    const have = new Set(R.hub.store.signals(R.s).filter(x => x.actor === who).map(x => x.name));
+    let n = 0;
+    for (const signal of effective(R, all, m)) {
+        if (have.has(`${m.id}.${signal}`))
+            continue;
+        R.hub.store.signal(R.s, who, m.id, `${m.id}.${signal}`, body(R, who, m.id, signal));
+        n++;
+    }
+    return n;
+};
+//# sourceMappingURL=signals.js.map

package/target/esm/index.js

@@ -0,0 +1,9 @@
+// The library: the message protocol, profiles, decisions, signals and the Store port, for programs that coordinate
+// through ringi without its command line (a framework's own runner, another store, another client).
+export * from './protocol/index.js';
+export * from './domain/profiles.js';
+export * as decide from './domain/decisions.js';
+export * as signals from './domain/signals.js';
+export { STORES } from './store/index.js';
+export { openHub, openRoom, createHub, contractAt } from './hub/index.js';
+//# sourceMappingURL=index.js.map