@idleware/ringi 0.0.0-stage → 0.1.0

package/target/dts/store/git/index.d.ts

@@ -0,0 +1,64 @@
+import * as Remote from './remote.ts';
+import type { Descriptor, JoinKey, Roster, SignalRecord, Store, StoredMessage, StoredRoom } from '../index.ts';
+import type { Entry } from '../../protocol/files.ts';
+type GitOpt = {
+    input?: string | Buffer;
+    env?: Record<string, string>;
+    where?: string;
+};
+export declare const runGit: (args: string[], o?: GitOpt) => string;
+export declare class GitStore implements Store {
+    readonly type = "git";
+    readonly trust: 'asserted' | 'signed';
+    readonly dir: string;
+    readonly d: Descriptor;
+    readonly home: string;
+    readonly h: Remote.Handle;
+    constructor(hubDir: string, d: Descriptor, home: string);
+    private args;
+    private git;
+    private gitOk;
+    rev(ref: string): string | null;
+    isAncestor(a: string, b: string): boolean;
+    isRef(s: string): boolean;
+    extends(older: string, newer: string): boolean;
+    private emptyTree;
+    private tree;
+    private commit;
+    private advance;
+    static create(hubDir: string, d: Descriptor, home: string, contract: Record<string, string>, text: string): GitStore;
+    static rootFor(hubDir: string, d: Descriptor, home: string): string;
+    sync(): void;
+    contractHead(): string;
+    contractFile(rev: string, name: string): string | null;
+    contractFiles(rev: string): string[];
+    amendContract(who: string, text: string, files: Record<string, string | Buffer>): string;
+    private base;
+    roomNames(archived: boolean): string[];
+    room(name: string): StoredRoom | null;
+    controlFile(room: StoredRoom, name: string, rev?: string): string | null;
+    createRoom(name: string, who: string, text: string, files: Record<string, string>): string;
+    updateControl(room: StoredRoom, who: string, text: string, files: Record<string, string>): string;
+    private refsUnder;
+    archiveRoom(room: StoredRoom, as: string): void;
+    deleteRoom(room: StoredRoom): void;
+    private legacy;
+    roster(room: StoredRoom): Roster | null;
+    logIds(room: StoredRoom): string[];
+    logHead(room: StoredRoom, id: string): string | null;
+    messages(room: StoredRoom, id: string, head: string): StoredMessage[];
+    append(room: StoredRoom, who: string, text: string, entries: Entry[]): string;
+    verifyLog(room: StoredRoom, id: string, head: string): string | null;
+    pin(room: StoredRoom, reader: string, id: string, rev: string): void;
+    unpin(room: StoredRoom, reader: string, id: string): void;
+    file(rev: string, p: string): Buffer;
+    sizes(rev: string, paths: string[]): Map<string, number>;
+    signal(room: StoredRoom, who: string, target: string, name: string, text: string): void;
+    signals(room: StoredRoom): SignalRecord[];
+    admit(room: StoredRoom, who: string, key: string): string;
+    joinKey(room: StoredRoom, who: string): JoinKey;
+    forgetLog(room: StoredRoom, id: string): void;
+    rootKey(): string;
+    rootRoster(): string;
+}
+export {};

package/target/dts/store/git/remote.d.ts

@@ -0,0 +1,70 @@
+import * as C from '../../lib/index.ts';
+import type { Descriptor, Member } from '../index.ts';
+export type Handle = {
+    name: string;
+    dir: string;
+    d: Descriptor;
+    main?: string;
+    remoteAlarms?: Record<string, string>;
+    bootstrap?: boolean;
+};
+export type Room = {
+    name: string;
+    head: string;
+    genesis: string;
+    control: string;
+    log: (who: string) => string;
+    archived?: boolean;
+    members?: Record<string, Member>;
+};
+type Key = {
+    line: string;
+    fp: string;
+};
+type Signer = {
+    principal: string;
+    key: Key;
+};
+type VerifiedRoom = {
+    genesis: string;
+    entries: Signer[];
+    members: Record<string, Member>;
+};
+export declare const withVerification: <T>(H: Handle, fn: () => T) => T;
+declare const strictJson: typeof C.strictJson;
+export { strictJson };
+export declare const gitEnv: (extra?: NodeJS.ProcessEnv) => NodeJS.ProcessEnv;
+export declare const gitTimeout: () => number;
+export declare const checkGitTimeout: (error?: NodeJS.ErrnoException) => void;
+export declare const isRemote: (H: Handle) => boolean;
+export declare const parseKey: (value: unknown) => Key;
+export declare const setupSigned: (H: Handle, home: string, url?: string) => {
+    root: string;
+    allowedSigners: string;
+};
+export declare const sign: (H: Handle, who: string, home: string) => string[];
+export declare const rootRoster: (H: Handle) => string;
+export declare const verifyHub: (H: Handle) => {
+    head: string;
+    genesis: string;
+    commits: string[];
+} | null;
+export declare const verifyRoom: (H: Handle, R: Room) => VerifiedRoom;
+export declare const verify: (H: Handle, R: Room, who: string, head: string) => string | null;
+export declare const verifySignal: (H: Handle, R: Room, ref: string, sha: string) => string | null;
+export declare const sync: (H: Handle) => Handle;
+export declare const hubAdd: ({ home, name, url, root, genesis }: {
+    home: string;
+    name: string;
+    url: string;
+    root?: string;
+    genesis?: string;
+}) => string;
+export declare const join: (H: Handle, R: Room, who: string, home: string) => {
+    publicKey: string;
+    fingerprint: string;
+    admitted: boolean;
+};
+export declare const roomAdmit: (H: Handle, R: Room, who: string, publicKey: string, home: string) => string;
+export declare const push: (H: Handle, ref: string) => void;
+export declare const forget: (H: Handle, R: Room, who: string) => void;

package/target/dts/store/index.d.ts

@@ -0,0 +1,102 @@
+import type { Entry } from '../protocol/files.ts';
+export type Rev = string;
+export type Member = {
+    role?: string;
+    since?: string;
+};
+export type StoredMessage = {
+    id: Rev;
+    parent: Rev | null;
+    time: number;
+    text: Buffer;
+    files: {
+        path: string;
+        mode: string;
+    }[];
+    refused: {
+        path: string;
+        mode: string;
+        why?: string;
+    }[];
+};
+export type ControlRecord = {
+    rev: Rev;
+    text: string;
+};
+export type StoredRoom = {
+    name: string;
+    archived: boolean;
+    head: Rev;
+    genesis: Rev;
+    base: Rev;
+    control: ControlRecord[];
+};
+export type SignalRecord = {
+    ref: string;
+    object: Rev;
+    name: string;
+    actor: string;
+    target: Rev;
+    tagger: string;
+    text: string;
+};
+export type Roster = {
+    members: Record<string, Member>;
+    signers: Array<{
+        principal: string;
+    }>;
+};
+export type JoinKey = {
+    publicKey: string;
+    fingerprint: string;
+    admitted: boolean;
+};
+export interface Store {
+    readonly type: string;
+    readonly trust: 'asserted' | 'signed';
+    isRef(s: string): boolean;
+    sync(): void;
+    contractHead(): Rev;
+    contractFile(rev: Rev, name: string): string | null;
+    contractFiles(rev: Rev): string[];
+    amendContract(who: string, text: string, files: Record<string, string | Buffer>): Rev;
+    roomNames(archived: boolean): string[];
+    room(name: string): StoredRoom | null;
+    controlFile(room: StoredRoom, name: string, rev?: Rev): string | null;
+    createRoom(name: string, who: string, text: string, files: Record<string, string>): Rev;
+    updateControl(room: StoredRoom, who: string, text: string, files: Record<string, string>): Rev;
+    archiveRoom(room: StoredRoom, as: string): void;
+    deleteRoom(room: StoredRoom): void;
+    roster(room: StoredRoom): Roster | null;
+    logIds(room: StoredRoom): string[];
+    logHead(room: StoredRoom, id: string): Rev | null;
+    extends(older: Rev, newer: Rev): boolean;
+    messages(room: StoredRoom, id: string, head: Rev): StoredMessage[];
+    append(room: StoredRoom, who: string, text: string, entries: Entry[]): Rev;
+    verifyLog(room: StoredRoom, id: string, head: Rev): string | null;
+    pin(room: StoredRoom, reader: string, id: string, rev: Rev): void;
+    unpin(room: StoredRoom, reader: string, id: string): void;
+    file(rev: Rev, path: string): Buffer;
+    sizes(rev: Rev, paths: string[]): Map<string, number>;
+    signal(room: StoredRoom, who: string, target: Rev, name: string, text: string): void;
+    signals(room: StoredRoom): SignalRecord[];
+    admit?(room: StoredRoom, who: string, key: string): Rev;
+    joinKey?(room: StoredRoom, who: string): JoinKey;
+    forgetLog?(room: StoredRoom, id: string): void;
+    rootKey?(): string;
+    rootRoster?(): string;
+}
+export type Descriptor = {
+    schema: 'ringi-hub/2';
+    name: string;
+    trust: 'asserted' | 'signed';
+    root?: string;
+    genesis?: string;
+    store: {
+        type: string;
+        path: string;
+        remote?: string;
+    };
+};
+export type StoreFactory = (dir: string, d: Descriptor, home: string) => Store;
+export declare const STORES: Record<string, StoreFactory>;

package/target/dts/store/kafka/index.d.ts

@@ -0,0 +1,2 @@
+import type { StoreFactory } from '../index.ts';
+export declare const kafka: StoreFactory;

package/target/dts/store/temporal/index.d.ts

@@ -0,0 +1,2 @@
+import type { StoreFactory } from '../index.ts';
+export declare const temporal: StoreFactory;

package/target/esm/app/agent.js

@@ -0,0 +1,84 @@
+// Agent operations return data; the runtime owns readers, seats and headless turns.
+import { HIDDEN, append, pongText, withSizes } from '../hub/index.js';
+import * as Signals from '../hub/signals.js';
+import { fail, sleep } from '../lib/index.js';
+import { ID_RE, checkOutgoing, compose, link, lookup, unread } from '../protocol/index.js';
+import { linked, loadRoom, loadRoomUnlocked, loadState, readerLock, saveState } from '../runtime/reader.js';
+import { bound } from '../runtime/session.js';
+import { isRef } from './room.js';
+export { bound } from '../runtime/session.js';
+export { watch } from '../runtime/watch.js';
+export const inbox = ({ R, me }, { peek = false, limit = 20 } = {}) => {
+    if (!Number.isSafeInteger(limit) || limit < 1)
+        fail('inbox limit must be a positive integer');
+    const res = readerLock(R, me, () => {
+        const { logs, st } = loadRoomUnlocked(R, me);
+        const r = unread(logs, me, st.seen ?? {}, limit, HIDDEN);
+        if (!peek)
+            saveState(R, me, { ...loadState(R, me), seen: r.cursors });
+        return { all: link(logs), ...r };
+    });
+    if (!peek)
+        for (const m of res.msgs)
+            Signals.mark(R, me, m, 'read');
+    return { ...res, msgs: res.msgs.map(m => ({ ...m, files: withSizes(R, m) })) };
+};
+export const take = ({ R, me }, ref) => {
+    const m = lookup(linked(R, me).all, ref);
+    return { m, made: Signals.mark(R, me, m, 'taken') };
+};
+export const whoami = ({ s, R }) => ({
+    session: s ?? fail('agent identity needs a joined session'), profile: R.profile.name, members: Object.keys(R.members),
+});
+export const card = ({ R, me }, text) => {
+    const message = compose(text, [['To', '*'], ['Kind', 'card']]);
+    checkOutgoing(message, isRef(R));
+    return append(R, me, message);
+};
+export const ping = ({ R, me }, { to, text = 'ping: still working', next = 600, re }) => {
+    if (!ID_RE.test(to))
+        fail(`bad recipient ${to}`);
+    if (!Number.isFinite(next) || next <= 0)
+        fail('ping next must be positive seconds');
+    const { all } = linked(R, me);
+    const mine = [...all.values()].filter(m => m.from === me && m.kind === 'ping' && m.to.includes(to)).at(-1);
+    const pong = mine && [...all.values()].find(m => m.kind === 'pong' && m.from === to && m.reId === mine.id);
+    const parent = re ? lookup(all, re) : null;
+    const message = compose(text, [['To', to], ['Re', parent?.id], ['Kind', 'ping'], ['Next', String(next)], ['Hop', parent && String(parent.hopEff + 1)]]);
+    checkOutgoing(message, isRef(R));
+    return { id: append(R, me, message), to, previous: mine ? { id: mine.id, answeredAt: pong?.time ?? null } : null };
+};
+export const wait = async (a, { max = 120, ...options } = {}) => {
+    if (!Number.isFinite(max) || max < 0)
+        fail('wait max must be nonnegative seconds');
+    const start = Date.now(), ponged = new Set();
+    let last = start, silence = Math.min(max, 110);
+    for (;;) {
+        // Each poll renews the lease and checks stop, takeover, membership and the room's identity.
+        const current = bound();
+        if (current.R.genesis !== a.R.genesis || current.me !== a.me)
+            fail('the waiting session changed its binding');
+        const { R, me } = current;
+        const { logs, st } = loadRoom(R, me);
+        if (unread(logs, me, st.seen ?? {}, Infinity, HIDDEN).msgs.length)
+            return { inbox: inbox(current, options), seconds: (Date.now() - start) / 1000 };
+        link(logs);
+        for (const m of logs.get(me) ?? [])
+            if (m.kind === 'pong' && m.reId)
+                ponged.add(m.reId);
+        for (const msgs of logs.values())
+            for (const m of msgs) {
+                if (m.kind !== 'ping' || m.bad || !m.to.includes(me) || ponged.has(m.id))
+                    continue;
+                ponged.add(m.id);
+                last = Date.now();
+                silence = Math.max(silence, Number(m.trailers.next?.[0]) || 600);
+                append(R, me, pongText(me, m, 'is waiting'));
+            }
+        const now = Date.now();
+        if (now - last >= silence * 1000 || now - start >= max * 1000)
+            return { inbox: null, seconds: (now - start) / 1000 };
+        await sleep(Math.min(1000, max * 1000 - (now - start)));
+    }
+};
+//# sourceMappingURL=agent.js.map

package/target/esm/app/budget.js

@@ -0,0 +1,95 @@
+// budget: proposals, reviewers' stamps, the decider's decision, and the grants it makes (decisions/1). Each operation
+// takes who acts and typed input, and returns data; interfaces print it.
+import * as D from '../domain/decisions.js';
+import { OPERATOR, locked } from '../home/index.js';
+import { append } from '../hub/index.js';
+import { fail, note, short } from '../lib/index.js';
+import { ID_RE, checkOutgoing, compose, lookup } from '../protocol/index.js';
+import { linked } from '../runtime/reader.js';
+import { isRef } from './room.js';
+import { grantView, proposalView } from './view.js';
+export const propose = ({ R, me }, x) => {
+    const { all } = linked(R, me);
+    if (!ID_RE.test(x.decider))
+        fail(`bad decider ${x.decider}`);
+    const reviewers = [...new Set(x.reviewers ?? [])].filter(r => r !== me);
+    for (const r of reviewers)
+        if (!ID_RE.test(r))
+            fail(`bad reviewer ${r}`);
+    const budget = x.budget ? D.parseBudget(x.budget) ?? fail('--budget takes runs=<n>[, run-seconds=<n>][, concurrency=<n>]') : null;
+    const sup = x.supersedes ? lookup(all, x.supersedes) : null;
+    if (sup && (sup.kind !== 'proposal' || (sup.from !== me && me !== OPERATOR)))
+        fail(`${short(sup.id)} is not your proposal`);
+    if (budget && !D.mayDecide(R.contract.authority, x.decider, me, budget))
+        note(`${x.decider} has no authority for this budget in hub ${R.hub.name}; only operator could approve it`);
+    const to = [...new Set([...reviewers, x.decider])].filter(t => t !== me);
+    const text = compose(x.text, [['To', to.join(', ') || '*'], ['Kind', 'proposal'], ['Decider', x.decider], ['Reviewers', reviewers.join(', ')],
+        ['Due', x.due && D.parseDue(x.due)], ['Budget', budget && D.budgetText(budget)], ['Supersedes', sup?.id]]);
+    const bad = D.check(checkOutgoing(text, isRef(R)), isRef(R));
+    if (bad)
+        fail(`refusing to send: ${bad}`);
+    return { id: append(R, me, text, x.files ?? []), to, budget };
+};
+const proposalAt = (all, ref) => {
+    const p = lookup(all, ref);
+    if (p.kind !== 'proposal' || p.bad)
+        fail(`${short(p.id)} is not a proposal`);
+    return p;
+};
+export const stamp = ({ R, me }, ref, s, text) => {
+    const { all } = linked(R, me);
+    const p = proposalAt(all, ref);
+    if (!D.STAMPS.includes(s))
+        fail(`usage: stamp <proposal> ${D.STAMPS.join('|')} -m <reason>`);
+    const info = D.proposalOf(all, p, R.authorityAt);
+    if (!info.reviewers.includes(me))
+        fail(`you are not a named reviewer of ${short(p.id)} (reviewers: ${info.reviewers.join(', ') || 'none'})`);
+    if (info.decision)
+        fail(`${short(p.id)} is already ${info.decision.decision}`);
+    const out = compose(text, [['To', [...new Set([p.from, info.decider])].filter(x => x !== me).join(', ') || p.from], ['Re', p.id], ['Kind', 'stamp'], ['Stamp', s], ['Hop', String(p.hopEff + 1)]]);
+    checkOutgoing(out, isRef(R));
+    return { proposal: p, id: append(R, me, out) };
+};
+// The decision names the control entry, and so the authority, it was made under (decisions/1).
+export const decide = ({ R, me }, ref, d, text) => locked(`grant-${R.hub.name}`, () => {
+    const { all } = linked(R, me);
+    const p = proposalAt(all, ref);
+    if (!D.DECISIONS.includes(d))
+        fail(`usage: decide <proposal> ${D.DECISIONS.join('|')} -m <reason>`);
+    const info = D.proposalOf(all, p, R.authorityAt);
+    if (d === 'revoked') {
+        if (info.state !== 'approved')
+            fail(`${short(p.id)} is ${info.state}; only an approval can be revoked`);
+        if (me !== info.decider && me !== OPERATOR)
+            fail(`only ${info.decider} or the operator revokes it`);
+    }
+    else {
+        if (me !== info.decider)
+            fail(`only the named decider, ${info.decider}, decides ${short(p.id)}`);
+        if (!D.mayDecide(R.contract.authority, me, p.from, info.budget))
+            fail(`${me} has no authority to decide this${info.budget ? ` budget (${D.budgetText(info.budget)})` : ''} in hub ${R.hub.name}, or it is your own proposal`);
+        if (info.decision)
+            fail(`${short(p.id)} is already ${info.decision.decision}`);
+        if (info.superseded)
+            fail(`${short(p.id)} was superseded by ${short(info.superseded.id)}; decide that revision`);
+    }
+    const to = [...new Set([p.from, ...info.reviewers])].filter(x => x !== me);
+    const out = compose(text, [['To', to.join(', ') || '*'], ['Re', p.id], ['Kind', 'decision'], ['Decision', d], ['Control', R.head], ['Hop', String(p.hopEff + 1)]]);
+    checkOutgoing(out, isRef(R));
+    const id = append(R, me, out);
+    if (d === 'approved' && info.missing.length)
+        note(`decided without stamps from ${info.missing.join(', ')}`);
+    return { proposal: p, id, budget: d === 'approved' ? info.budget : null };
+});
+// Open proposals (with `all`, every one).
+export const proposals = ({ R, me }, { all: everything = false } = {}) => {
+    const { all } = linked(R, me);
+    const ps = D.proposals(all, R.authorityAt).filter(x => everything || ['open', 'overdue'].includes(x.state));
+    return { proposals: ps, views: ps.map(proposalView) };
+};
+export const grants = ({ R, me }) => {
+    const { all } = linked(R, me);
+    return D.proposals(all, R.authorityAt).filter(x => x.grant).map(x => grantView(x, D.usageOf(all, x.grant)));
+};
+export { DECISIONS, STAMPS, budgetText } from '../domain/decisions.js';
+//# sourceMappingURL=budget.js.map

package/target/esm/app/context.js

@@ -0,0 +1,16 @@
+// context: who acts and where, as an interface asks for it (the operator in its terminal context, an agent through its
+// session's binding), and what this build is.
+import { HOME, OPERATOR, RESOURCES, VERSION, config } from '../home/index.js';
+import { CAPS, HUB_MAJOR, openHub, room as roomOf } from '../hub/index.js';
+import { bound } from '../runtime/session.js';
+// The operator, in the named hub and room, else in the terminal's current ones.
+export const operator = ({ hub, room } = {}) => {
+    const H = openHub(hub ?? config().hub);
+    const name = room ?? (hub && hub !== config().hub ? null : config().room);
+    return { R: roomOf(H, name), me: OPERATOR };
+};
+// The agent this session is bound to; refuses when it is not joined, is stopped, or its room is gone.
+export const agent = () => bound();
+export const about = () => ({ version: VERSION, home: HOME, resources: RESOURCES, contract: `${HUB_MAJOR}.x`, capabilities: [...CAPS] });
+export { config };
+//# sourceMappingURL=context.js.map

package/target/esm/app/hubs.js

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

package/target/esm/app/overview.js

@@ -0,0 +1,39 @@
+// overview: where things stand for the operator: the hub, the room, who is in, open work and proposals, the latest
+// messages, and new ones as they land; and the sessions of this machine.
+import * as D from '../domain/decisions.js';
+import { OPERATOR, ensureHome, locked } from '../home/index.js';
+import { HIDDEN, openHub, room as roomOf } from '../hub/index.js';
+import { fail } from '../lib/index.js';
+import { ordered } from '../protocol/index.js';
+import { linked } from '../runtime/reader.js';
+import { allSessions, dropSession, liveness, readSession } from '../runtime/session.js';
+import { tasks } from './room.js';
+const sessionView = (s) => ({ ...s, liveness: liveness(s) });
+export const where = (H, name) => {
+    if (!name)
+        return { hub: H, room: null, sessions: [], work: [], proposals: [], all: new Map(), messages: [] };
+    const R = roomOf(H, 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),
+        work: tasks({ R, me: OPERATOR }).views, proposals: D.proposals(all, R.authorityAt).filter(x => ['open', 'overdue'].includes(x.state)),
+        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);
+    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 };
+};
+export const sessions = () => {
+    ensureHome();
+    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