@idleware/ringi 0.7.2 → 0.8.1

package/target/esm/core/agents/overview.js

@@ -1,44 +1,32 @@
 // overview: where things stand for the operator: the hub, the room, who is in, open work, the latest
-// messages, and new ones as they land; and the sessions of this machine.
-import { hubPorts, locked } from '../hub/ports/index.js';
+// messages, and new ones as they land; and the rooms of this machine.
 import { HIDDEN, OPERATOR, openHub, room as roomOf } from '../hub/rooms/index.js';
-import { fail } from '../../lib/index.js';
 import { ordered } from '../hub/protocol/index.js';
 import { linked } from '../hub/history/index.js';
-import { allSessions, dropSession, liveness, readSession } from './sessions/index.js';
+import { allSessions, liveness } from './sessions/index.js';
 import { tasks } from '../hub/usecases/room.js';
-import { rooms } from '../hub/usecases/rooms.js';
+import { roomNamed, rooms } from '../hub/usecases/rooms.js';
 const sessionView = (s) => ({ ...s, liveness: liveness(s) });
-export const where = (H, name) => {
+export const where = (name) => {
     if (!name)
-        return { hub: H, room: null, sessions: [], work: [], all: new Map(), messages: [] };
-    const R = roomOf(H, name);
+        return { room: null, sessions: [], work: [], all: new Map(), messages: [] };
+    const R = roomNamed(name);
     const { all } = linked(R, OPERATOR);
-    return { hub: H, room: R, sessions: allSessions().filter(s => s.hub === H.name && s.genesis === R.genesis).map(sessionView),
+    return { room: R, sessions: allSessions().filter(s => s.genesis === R.genesis).map(sessionView),
         work: tasks({ R, me: OPERATOR }).views,
         all, messages: ordered([...all.values()].filter(m => !(m.kind && HIDDEN.has(m.kind)))) };
 };
 // The visible messages that landed since `seen` (which it extends), read afresh from the store.
-export const arrived = (H, R, seen) => {
-    const { all } = linked(roomOf(openHub(H.name, { refresh: true }), R.name), OPERATOR);
+export const arrived = (R, seen) => {
+    const { all } = linked(roomOf(openHub(R.hub.name, { refresh: true }), R.name), OPERATOR);
     const messages = ordered([...all.values()].filter(m => !seen.has(m.id) && !(m.kind && HIDDEN.has(m.kind))));
     for (const m of messages)
         seen.add(m.id);
     return { all, messages };
 };
-// The hub's rooms, each with how many of its sessions on this machine are active.
-export const roomsActive = (H) => {
-    const ss = allSessions().filter(s => s.hub === H.name && liveness(s) === 'active');
-    return rooms(H).map(v => ({ ...v, active: ss.filter(s => s.genesis === v.genesis).length }));
+// The rooms on this machine, each with how many of its sessions here are active.
+export const roomsActive = () => {
+    const ss = allSessions().filter(s => liveness(s) === 'active');
+    return rooms().map(v => ({ ...v, active: ss.filter(s => s.genesis === v.genesis).length }));
 };
-export const sessions = () => {
-    hubPorts().state.ensure();
-    return allSessions().map(sessionView);
-};
-// The seat a session held becomes free.
-export const forgetSession = (handle) => locked('sessions', () => {
-    if (!readSession(handle))
-        fail(`no session ${handle}`);
-    dropSession(handle);
-});
 //# sourceMappingURL=overview.js.map

package/target/esm/core/agents/sessions/binding.js

@@ -8,7 +8,7 @@ import { dropSession, readSession, saveSession, whoAmI } from './index.js';
 export const bound = () => {
     const me = whoAmI();
     const s = readSession(me.handle) ?? fail(`this session is not in a room. Take part only when the operator says so in this chat:
-  "join <room> as <id>" runs ringi join local <room> --as <id> --scope "<what they delegate>";
+  "join <room> as <id>" runs ringi join <room> --as <id> --scope "<what they delegate>" (<room>: its name, or the invitation);
   after a restart, "continue" runs ringi continue.`);
     if (s.state === 'stopped')
         fail('this session is stopped: the operator paused it. It reacts to nothing until the operator says "continue" (ringi continue)');

package/target/esm/core/agents/sessions/index.js

@@ -48,8 +48,9 @@ export const liveness = (s) => s.state === 'stopped' ? 'stopped'
     : Date.now() - Date.parse(s.lastSeen) < LEASE && (!s.pid || pidAlive(s.pid)) ? 'active' : 'gone';
 export const seatHolder = (hub, genesis, agent, except) => allSessions().find(s => s.hub === hub && s.genesis === genesis && s.agent === agent && s.handle !== except);
 export const ownSession = (handle) => readSession(handle);
+// A seat is named by its room and agent: a room's name is unique on a machine, whatever hub keeps it.
 export const parseSelector = (sel) => {
-    const m = /^(?:([a-z0-9._-]+):)?([^/]+)\/([^/]+)$/.exec(sel ?? '');
-    return m ? { hub: m[1] ?? null, room: m[2], agent: m[3] } : fail('a session is named <room>/<agent> or <hub>:<room>/<agent>');
+    const m = /^([^/]+)\/([^/]+)$/.exec(sel ?? '');
+    return m ? { room: m[1], agent: m[2] } : fail('a session is named <room>/<agent>');
 };
 //# sourceMappingURL=index.js.map

package/target/esm/core/agents/sessions/join.js

@@ -1,19 +1,27 @@
 // join: a chat takes a seat in a room as an agent, one room per chat; on a signed hub its key must be admitted first.
 import { locked } from '../../hub/ports/index.js';
-import { OPERATOR, controlChange, openHub, room as roomOf } from '../../hub/rooms/index.js';
+import { OPERATOR, attachRoom, adoptHub, controlChange } from '../../hub/rooms/index.js';
+import { roomNamed } from '../../hub/usecases/rooms.js';
+import { readInvite } from '../../hub/usecases/invite.js';
 import { fail, note, stamp } from '../../../lib/index.js';
-import { AGENT_RE } from '../../hub/protocol/index.js';
+import { agentId } from '../../hub/usecases/roster.js';
 import { dropSession, liveness, ownSession, readSession, saveSession, seatHolder, whoAmI } from './index.js';
-export const join = ({ hub, room, agent: id, scope }) => {
+// The room an invitation names, attached on first use; or the one room of that name on this machine.
+const roomFor = (target) => {
+    const x = readInvite(target);
+    if (x)
+        return attachRoom(adoptHub({ trust: x.trust, root: x.root, genesis: x.hubGenesis }), x.room, { schema: 'ringi-room/1', name: x.room, hubGenesis: x.hubGenesis, genesis: x.genesis, store: { path: 'store', remote: x.address } });
+    return roomNamed(target);
+};
+export const join = ({ room: target, agent: id, scope }) => {
     const me = whoAmI();
     const agent = id ?? me.product ?? fail('--as <id> is required: this session\'s product is unknown');
-    if (!AGENT_RE.test(agent) || agent === OPERATOR)
-        fail(`bad agent id ${agent}: lowercase letters, digits, - and _, no dot`);
-    const H = openHub(hub), R = roomOf(H, room);
+    agentId(agent);
+    const R = roomFor(target), H = R.hub, room = R.name;
     if (H.signed) {
-        if (!H.store.joinKey)
+        if (!R.store.joinKey)
             fail(`hub ${H.name}: its store cannot make keys`);
-        const key = H.store.joinKey(R.s, agent);
+        const key = R.store.joinKey(R.s, agent);
         if (!key.admitted)
             return { agent, hub: H.name, room: R.name, session: null, key };
     }
@@ -26,7 +34,7 @@ const claimSession = (c) => {
     const same = !!mine && mine.hub === H.name && mine.genesis === R.genesis && mine.agent === agent;
     ensureMember(c);
     if (mine && !same)
-        note(`left ${mine.hub}/${mine.room} as ${mine.agent}: one room per session`);
+        note(`left ${mine.room} as ${mine.agent}: one room per session`);
     saveSession({
         handle: me.handle, product: me.product, hub: H.name, room: R.name, genesis: R.genesis, agent,
         scope: scope ?? (same ? mine.scope : null), state: 'active', since: same ? mine.since : stamp(), lastSeen: stamp(), pid: me.pid

package/target/esm/core/agents/sessions/resume.js

@@ -19,10 +19,7 @@ const selectTarget = (me, selector) => {
     }
     else {
         const sel = parseSelector(selector);
-        const hits = allSessions().filter(s => s.room === sel.room && s.agent === sel.agent && (!sel.hub || s.hub === sel.hub));
-        if (hits.length > 1)
-            fail(`several hubs have ${sel.room}/${sel.agent}; name one: <hub>:${sel.room}/${sel.agent}`);
-        return hits[0] ?? fail(`no session holds ${selector}; the operator joins this chat with ringi join`);
+        return allSessions().find(s => s.room === sel.room && s.agent === sel.agent) ?? fail(`no session holds ${selector}; the operator joins this chat with ringi join`);
     }
 };
 const ownTarget = (me) => {
@@ -31,7 +28,7 @@ const ownTarget = (me) => {
         const cands = allSessions().filter(s => liveness(s) !== 'active').sort((a, b) => Number(b.product === me.product) - Number(a.product === me.product));
         if (!cands.length)
             fail('nothing to continue: this chat was never joined, and no paused or gone session waits. The operator says "join <room> as <id>"');
-        fail(`this chat has no binding of its own. Say which one to take over:\n${cands.map(s => `  ringi continue ${s.hub}:${s.room}/${s.agent}   (${liveness(s)}, ${s.product ?? '?'}, ${s.handle}${s.scope ? `, scope: ${s.scope}` : ''})`).join('\n')}`);
+        fail(`this chat has no binding of its own. Say which one to take over:\n${cands.map(s => `  ringi continue ${s.room}/${s.agent}   (${liveness(s)}, ${s.product ?? '?'}, ${s.handle}${s.scope ? `, scope: ${s.scope}` : ''})`).join('\n')}`);
     }
     return mine;
 };
@@ -40,7 +37,7 @@ const takeOver = (me, target) => {
         if (liveness(target) === 'active')
             fail(`${target.room}/${target.agent} is held by a live session (${target.handle}); it is not taken over`);
         dropSession(target.handle);
-        note(`took over ${target.hub}/${target.room}/${target.agent} from ${target.handle}`);
+        note(`took over ${target.room}/${target.agent} from ${target.handle}`);
     }
 };
 const resumed = (me, target) => {

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

@@ -2,10 +2,7 @@
 // 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 profiles from './work/index.js';
-// decisions/1 (proposals, grants, budgets) is retired: nothing in this build creates, decides or spends what it
-// governs, so a contract that still names it restricts nothing here and is read.
-const RETIRED = {};
-export const CAPABILITIES = { [profiles.PROFILES_CAPABILITY]: profiles, 'decisions/1': RETIRED };
+export const CAPABILITIES = { [profiles.PROFILES_CAPABILITY]: profiles };
 // Why a contract's capability list cannot be enforced by this build, or nothing.
 export const unenforceable = (ids) => {
     const names = ids.map(id => id.split('/')[0]);

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

@@ -6,20 +6,20 @@ 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);
+const readerKey = (R, reader) => ['readers', R.hub.d.genesis, R.genesis, reader];
+export const readerLock = (R, reader, fn) => locked(`reader-${R.hub.d.genesis}-${R.genesis}-${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)) {
+    if (st.control && !R.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;
+    const store = R.store;
     if (!cur)
         return `log ${id} was deleted after ${short(acc)}`;
     if (acc && !store.extends(acc, cur))
@@ -31,7 +31,7 @@ const logProblem = (R, id, acc, cur) => {
 };
 // 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 store = R.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];
@@ -49,19 +49,28 @@ const acceptLogs = (R, reader, st, alarms) => {
     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 acceptSignals = (R, logs, st, alarms, reader) => {
+    const records = R.store.signals(R.s);
     const checked = Signals.check(R, link(logs), records);
     const signalPins = Signals.pins(records, checked, st.signals);
+    const heads = new Map(R.store.signalHeads(R.s).map(x => [x.actor, x.head]));
+    for (const [actor, old] of Object.entries(st.signals ?? {})) {
+        const head = heads.get(actor);
+        if (!head || !R.store.extends(old, head)) {
+            alarms.push(`signal stream ${actor} was deleted or rewritten after ${short(old)}`);
+            signalPins.accepted[actor] = old;
+        }
+    }
+    for (const [actor, head] of Object.entries(signalPins.accepted))
+        if (st.signals?.[actor] !== head)
+            R.store.pinSignals(R.s, reader, actor, head);
     st.signals = signalPins.accepted;
-    alarms.push(...signalPins.alarms, ...checked.filter(x => !x.ok).map(x => `signal ${x.ref}: ${x.why}`));
+    alarms.push(...signalPins.alarms, ...checked.filter(x => !x.ok && !x.pending).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 alarm.endsWith('was removed after it was accepted')
-            ? 'the messages stay the truth; its author restores it with ringi agent signals --repair'
-            : 'the messages stay the truth; the signal is ignored';
+        return 'the affected stream stops at its accepted prefix; messages stay the truth; the operator decides';
     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>`;
@@ -73,9 +82,10 @@ const remedy = (R, alarm) => {
 export const loadRoomUnlocked = (R, reader) => {
     const st = loadState(R, reader);
     acceptControl(R, st);
-    const alarms = [...R.hub.store.alarms?.(R.s) ?? []];
+    const alarms = [...R.store.alarms?.(R.s) ?? []];
     const logs = acceptLogs(R, reader, st, alarms);
-    acceptSignals(R, logs, st, alarms);
+    acceptSignals(R, logs, st, alarms, reader);
+    alarms.push(...R.store.alarms?.(R.s) ?? []);
     const reported = new Set(st.alarms ?? []);
     for (const a of alarms)
         if (!reported.has(a))

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

@@ -1,9 +1,9 @@
-// store: the port every storage type implements, each an adapter (adapters/transport-<type>) that composition/
+// store: the port every storage type implements, each an adapter (adapters/store-<type>) that composition/
 // registers. Rooms, accepted history, profiles 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, 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, …).
+// (append-only actor facts about 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 {};

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

@@ -0,0 +1,18 @@
+// A storage address names its implementation explicitly; adapters receive only the locator they understand.
+import { fail } from '../../../lib/index.js';
+import { hubPorts } from '../ports/index.js';
+export const storeOf = (address) => {
+    const m = typeof address === 'string' && !/[\r\n\0]/.test(address)
+        && /^([a-z][a-z0-9.-]*)(?:\+([a-z][a-z0-9.-]*))?:\/\/(.+)$/i.exec(address);
+    if (!m)
+        return fail('a room address must name its store scheme, such as git+ssh://, git+https:// or git+file://');
+    const type = m[1].toLowerCase();
+    if (['ssh', 'http', 'https', 'file'].includes(type))
+        fail('address has no explicit store type; use git+ssh://, git+https:// or git+file://');
+    return { type, locator: m[2] ? `${m[2].toLowerCase()}://${m[3]}` : address };
+};
+export const transportOf = (name, type) => {
+    const { transports, build } = hubPorts();
+    return transports[type] ?? fail(`hub ${name} uses a ${type} store; this ringi ${build.version} knows ${Object.keys(transports).join(', ')}`);
+};
+//# sourceMappingURL=address.js.map

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

@@ -0,0 +1,32 @@
+// Invitation pins adopted as a catalogue, without a contract source or a membership grant.
+import { hubPorts, locked } from '../ports/index.js';
+import { fail } from '../../../lib/index.js';
+import { descriptorRefusal } from './compat.js';
+import { hubNames, openHub } from './hubs.js';
+// An invitation supplies pins, never credentials or a default repository. Adoption grants no room membership.
+const matchingHub = (d) => {
+    for (const existing of hubNames()) {
+        const H = openHub(existing), known = H.d;
+        if (known.genesis !== d.genesis)
+            continue;
+        if (known.trust !== d.trust || known.root !== d.root)
+            fail('invitation changes the trust or root of an existing hub genesis');
+        return H;
+    }
+    return null;
+};
+export const adoptHub = ({ trust, root, genesis }) => locked('hub-catalogue', () => {
+    const st = hubPorts().state, name = genesis.slice(0, 12);
+    const d = { schema: 'ringi-hub/3', name, trust, genesis, store: { type: hubPorts().store }, ...(root ? { root } : {}) };
+    const why = descriptorRefusal(d, name);
+    if (why)
+        fail(why);
+    const known = matchingHub(d);
+    if (known)
+        return known;
+    if (st.list(['hub']).includes(name))
+        fail('hub genesis prefix conflicts with an existing catalogue name; nothing is replaced');
+    st.write(['hub', name, 'hub'], d);
+    return openHub(name);
+});
+//# sourceMappingURL=adoption.js.map

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

@@ -8,14 +8,25 @@ 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 beside = 'make a new hub beside it (ringi hub create <name>), or a new space 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;
+const oid = (s) => typeof s === 'string' && /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(s);
+const localPath = (s) => typeof s === 'string' && /^[a-zA-Z0-9._-]+(?:\/[a-zA-Z0-9._-]+)*$/.test(s) && s.split('/').every(p => p !== '.' && p !== '..');
+const knownSchema = (d, name) => d?.schema === 'ringi-hub/3' && d.name === name;
+const knownTrust = (d) => d.trust === 'signed'
+    ? typeof d.root === 'string' && !!d.root : d.trust === 'asserted' && !d.root;
+const knownStore = (d) => {
+    const type = typeof d.store?.type === 'string' && !!d.store.type;
+    const pins = oid(d.genesis) && knownTrust(d);
+    const source = !d.contract || localPath(d.contract.path);
+    return type && pins && source;
+};
 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) => {
+const contractIdentity = (c, name) => {
+    if (!c || typeof c !== 'object')
+        return `hub ${name}: contract must be an object`;
     if (c.schema !== 'ringi-hub')
         return `hub ${name} declares schema ${String(c.schema)}, not ringi-hub`;
     const major = Number(String(c.version).split('.')[0]);
@@ -23,23 +34,37 @@ const refusal = (c, name) => {
         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)}`;
+    return null;
+};
+const contractFields = (c, name) => {
+    if (typeof c.store !== 'string' || !c.store)
+        return `hub ${name}: contract must name an explicit store layout`;
+    if (c.trust !== 'signed' && c.trust !== 'asserted')
+        return `hub ${name}: unknown contract trust`;
+    if (c.capabilities === undefined)
+        return null;
+    const list = Array.isArray(c.capabilities);
+    if (!list || c.capabilities.some(x => typeof x !== 'string'))
+        return `hub ${name}: capabilities must be a list of names`;
+    return null;
+};
+export const contractRefusal = (c, name) => {
+    const shape = contractIdentity(c, name) ?? contractFields(c, name);
+    if (shape)
+        return shape;
     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');
+export const endpointRefusal = (d, name, e) => {
+    const identity = e?.schema === 'ringi-room/1' && e.name === name && e.hubGenesis === d.genesis;
+    const storage = oid(e?.genesis) && localPath(e?.store?.path);
+    return identity && storage ? null : `room ${name}: its endpoint or genesis pins do not match hub ${d.name}; refusing another room's history`;
 };
 // 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 text = store.contractFile(rev, 'contract.json') ?? fail(`hub ${name} has no contract at ${short(rev)}`);
     const c = strictJson(text, `hub ${name}: contract`);
-    const why = refusal(c, name);
+    const why = contractRefusal(c, name);
     if (why)
         fail(why);
     return c;

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

@@ -0,0 +1,62 @@
+// The operator's explicit contract source, distinct from frozen room copies.
+import fs from 'node:fs';
+import path from 'node:path';
+import { DEFAULT_PROFILE, PROFILES_CAPABILITY } from '../work/index.js';
+import { hubPorts, locked } from '../ports/index.js';
+import { fail, strictJson } from '../../../lib/index.js';
+import { contractAt, contractRefusal, layoutRefusal } from './compat.js';
+import { PROTOCOL_MAJOR } from './index.js';
+import { transportOf } from './address.js';
+const HUB_MD = `# ringi hub
+
+The shared contract of a ringi hub (docs/spec/hub-2.md): contract.json (schema, version, protocol, trust, capabilities, the
+default profile) 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.
+export const genesisFiles = (d, layout) => {
+    const contract = { schema: 'ringi-hub', version: '2.0', protocol: PROTOCOL_MAJOR, trust: d.trust, store: layout, capabilities: [PROFILES_CAPABILITY], profile: DEFAULT_PROFILE, ...(d.root ? { root: d.root } : {}) };
+    return {
+        'contract.json': JSON.stringify(contract, null, 2) + '\n',
+        'HUB.md': HUB_MD,
+        [`profiles/${DEFAULT_PROFILE}.json`]: readProfileResource(DEFAULT_PROFILE),
+    };
+};
+export const checkedContract = (H, store) => {
+    const main = store.contractHead();
+    if (!store.extends(H.d.genesis, main))
+        fail(`hub ${H.name}: main does not descend from its pinned genesis`);
+    const contract = contractAt(store, H.name, main);
+    const t = transportOf(H.name, store.type);
+    const why = layoutRefusal(H.name, contract.store, t.layout);
+    if (why)
+        fail(why);
+    if (contract.trust !== H.d.trust || (H.signed && contract.root !== H.d.root))
+        fail(`hub ${H.name}: contract changes its pinned trust or root`);
+    return { main, contract };
+};
+export const openContract = (H, { refresh = false } = {}) => {
+    if (!H.d.contract)
+        fail(`hub ${H.name}: no operator contract source; open a named room instead`);
+    const store = transportOf(H.name, H.d.store.type).open(H.dir, H.d);
+    // Each handle syncs once; refreshing explicitly reads the source again, never an arbitrary room.
+    void refresh;
+    store.sync();
+    return { store, ...checkedContract(H, store) };
+};
+export const amendContract = (H, who, text, files) => locked(`hub-${H.name}`, () => {
+    const { store } = openContract(H, { refresh: true });
+    if (files['contract.json'] !== undefined) {
+        const candidate = strictJson(files['contract.json'].toString(), `hub ${H.name}: proposed contract`);
+        const why = contractRefusal(candidate, H.name) ?? layoutRefusal(H.name, candidate.store, transportOf(H.name, H.d.store.type).layout);
+        if (why)
+            fail(why);
+        if (candidate.trust !== H.d.trust || candidate.root !== H.d.root)
+            fail('contract amendment must retain the pinned trust and root');
+    }
+    const rev = store.amendContract(who, text, files);
+    checkedContract(H, store);
+    return rev;
+});
+//# sourceMappingURL=contracts.js.map

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

@@ -1,60 +1,48 @@
 // 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 { DEFAULT_PROFILE, PROFILES_CAPABILITY } from '../work/index.js';
-import { hubPorts } from '../ports/index.js';
+import { hubPorts, locked } 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';
+import { descriptorRefusal } from './compat.js';
+import { storeOf, transportOf } from './address.js';
+import { genesisFiles } from './contracts.js';
+export { storeOf, transportOf } from './address.js';
+export { checkedContract, openContract, amendContract, readProfileResource } from './contracts.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) 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: [PROFILES_CAPABILITY], profile: DEFAULT_PROFILE, ...(d.root ? { root: d.root } : {}) };
-    return {
-        'contract.json': JSON.stringify(contract, 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(', ')}`);
-};
+const descriptor = (name, signed, url) => ({ schema: 'ringi-hub/3', name, trust: signed ? 'signed' : 'asserted', genesis: '', store: { type: url ? storeOf(url).type : hubPorts().store }, contract: { path: 'contract', ...(url ? { remote: url } : {}) } });
 // 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))
+const makeHub = (name, d) => {
+    const st = hubPorts().state, 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']]) }));
+    d.genesis = made.store.contractHead();
+    const why = descriptorRefusal(d, name);
+    if (why)
+        fail(why);
+    st.write(['hub', name, 'hub'], d);
+    return { custody: made.custody };
+};
+const newHub = (name, signed, url) => {
+    if (!/^[a-z0-9]+(?:[._-][a-z0-9]+)*$/.test(name))
+        fail(`bad hub name ${name}`);
+    if (hubPorts().state.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);
+    return descriptor(name, signed, url);
+};
+export const createHub = (name, { signed = false, url } = {}) => locked('hub-catalogue', () => {
+    const d = newHub(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 };
+        return makeHub(name, d);
     }
     catch (e) {
         if (!has(name))
-            st.remove(['hub', name]);
+            hubPorts().state.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);
@@ -62,28 +50,17 @@ const readDescriptor = (name) => {
         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();
+// Opening a catalogue never chooses a repository or requires an operator contract source.
 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;
+    // Descriptors are cheap local reads. Refresh has no implicit fan-out to rooms.
+    void refresh;
+    return { name, dir: hubPorts().state.place(['hub', name]), d, signed: d.trust === 'signed' };
 };
+export { adoptHub } from './adoption.js';
 //# sourceMappingURL=hubs.js.map

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

@@ -5,10 +5,10 @@
 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 HUB_MAJOR = 2;
 export const PROTOCOL_MAJOR = 1;
 export const CAPS = new Set(Object.keys(CAPABILITIES));
-export const RESERVED_ROOMS = new Set(['main']);
+export const RESERVED_ROOMS = new Set(['main', 'chat']);
 // 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;