@idleware/ringi 0.3.0 → 0.5.0

package/target/esm/store/git/index.js

@@ -56,6 +56,9 @@ const splitBuf = (b, sep) => {
     return parts;
 };
 const REGULAR = new Set(['100644', '100755']);
+// The store is a repository whose work tree holds the contract (`main`) as it is now, so Git clients (SourceTree, IDEs)
+// open `store/` without errors, on the contract, with every room's branch beside it; `git status` stays clean.
+const init = (dir, home) => runGit(['init', '-q', '-b', 'main', path.dirname(dir)], { where: home });
 // The root's principal, and the files only its control records may change.
 const ROOT = 'operator';
 const CONTROL_FILES = new Set(['ROOM.md', 'members.json', 'profile.json', 'allowed_signers']);
@@ -75,6 +78,30 @@ export class GitStore {
         this.h = { name: d.name, dir: this.dir, d };
         if (!fs.existsSync(this.dir))
             fail(`hub ${d.name}: no git store at ${this.dir}`);
+        this.openable();
+    }
+    // A store made bare before, or a replica fetched bare, gets its work tree once (and loses the `_ringi` branch of an unreleased build).
+    openable() {
+        let changed = false;
+        if (/^\s*bare\s*=\s*true\s*$/m.test(fs.readFileSync(path.join(this.dir, 'config'), 'utf8'))) {
+            this.git(['config', 'core.bare', 'false']);
+            changed = true;
+        }
+        if (fs.readFileSync(path.join(this.dir, 'HEAD'), 'utf8') !== 'ref: refs/heads/main\n') {
+            this.git(['symbolic-ref', 'HEAD', 'refs/heads/main']);
+            changed = true;
+        }
+        if (fs.existsSync(path.join(this.dir, 'refs', 'heads', '_ringi'))) {
+            this.gitOk(['update-ref', '-d', 'refs/heads/_ringi']);
+            changed = true;
+        }
+        if (changed)
+            this.checkout();
+    }
+    // The work tree and the index follow the contract, so a Git client sees the store clean.
+    checkout() {
+        if (this.rev('refs/heads/main'))
+            this.git(['--work-tree', path.dirname(this.dir), 'read-tree', '-u', '--reset', 'refs/heads/main']);
     }
     args(a) { return ['--git-dir', this.dir, ...a]; }
     git(a, o) { return runGit(this.args(a), { ...o, where: this.home }); }
@@ -97,7 +124,7 @@ export class GitStore {
             if (drop.length)
                 this.git(['update-index', '--index-info'], { env, input: drop.map(p => `0 ${ZERO}\t${p}\n`).join('') });
             for (const e of entries) {
-                const sha = this.git(['hash-object', '-w', ...(e.file ? ['--', e.file] : ['--stdin'])], { input: e.content }).trim();
+                const sha = e.blob ?? this.git(['hash-object', '-w', ...(e.file ? ['--', e.file] : ['--stdin'])], { input: e.content }).trim();
                 this.git(['update-index', '--add', '--cacheinfo', `${e.mode},${sha},${e.path}`], { env });
             }
             return this.git(['write-tree'], { env }).trim();
@@ -121,7 +148,7 @@ export class GitStore {
         // A signed hub's repository already exists: rootFor made it with the root key.
         if (!fs.existsSync(dir)) {
             mkdirIn(home, path.dirname(dir));
-            runGit(['init', '--bare', '-q', '-b', 'main', dir], { where: home });
+            init(dir, home);
         }
         const s = new GitStore(hubDir, d, home);
         const sha = s.commit('operator', text, s.tree(null, Object.entries(contract).map(([p, c]) => ({ path: p, content: c, mode: '100644' }))), []);
@@ -129,17 +156,21 @@ export class GitStore {
             d.genesis = sha;
         if (!s.advance('refs/heads/main', sha, null))
             fail(`hub ${d.name}: main already exists`);
+        s.checkout();
         return s;
     }
     // A new signed hub: the root key is generated on this machine and pinned in the descriptor.
     static rootFor(hubDir, d, home) {
         const dir = path.join(hubDir, d.store.path, '.git');
         mkdirIn(home, path.dirname(dir));
-        runGit(['init', '--bare', '-q', '-b', 'main', dir], { where: home });
+        init(dir, home);
         return Remote.setupSigned({ name: d.name, dir, d }, home, d.store.remote).root;
     }
     sync() {
+        const main = this.rev('refs/heads/main');
         Remote.sync(this.h);
+        if (this.rev('refs/heads/main') !== main)
+            this.checkout();
     }
     // --- the contract ---
     contractHead() { return this.rev('refs/heads/main') ?? fail(`hub ${this.d.name} has no contract (main)`); }
@@ -153,6 +184,7 @@ export class GitStore {
         const sha = this.commit(who, text, this.tree(`${head}^{tree}`, Object.entries(files).map(([p, c]) => ({ path: p, content: c, mode: '100644' }))), [head]);
         if (!this.advance('refs/heads/main', sha, head))
             fail('the contract moved while amending; retry');
+        this.checkout();
         return sha;
     }
     // --- rooms ---
@@ -163,7 +195,7 @@ export class GitStore {
     roomNames(archived) {
         const prefix = archived ? 'refs/archive/' : 'refs/heads/';
         const names = this.git(['for-each-ref', '--format=%(refname)', prefix]).split('\n').filter(Boolean).map(r => r.slice(prefix.length))
-            .map(n => n.replace(/\/control$/, '')).filter(n => !n.includes('/') && n !== 'main' && n.includes('@') === archived);
+            .map(n => n.replace(/\/control$/, '')).filter(n => ID_RE.test(n.split('@')[0]) && n !== 'main' && n.includes('@') === archived);
         return [...new Set(names)].sort();
     }
     // A control record: the room's genesis, or a root commit of Kind: room.
@@ -514,6 +546,19 @@ export class GitStore {
                     files: files.filter(f => REGULAR.has(f.mode)), refused: [...refused, ...files.filter(f => !REGULAR.has(f.mode))] }];
         });
     }
+    blob(file) {
+        const id = this.git(['hash-object', '-w', '--', file]).trim();
+        return { id, size: Number(this.git(['cat-file', '-s', id]).trim()) };
+    }
+    // A tree of the staged files under refs/ringi/staged/<genesis>/<who>: git keeps what a ref reaches.
+    retain(room, who, entries) {
+        const ref = `refs/ringi/staged/${room.genesis}/${who}`;
+        if (!entries.length) {
+            this.gitOk(['update-ref', '-d', ref]);
+            return;
+        }
+        this.git(['update-ref', ref, this.tree(null, entries)]);
+    }
     // One message on top of the room's branch.
     append(room, who, text, entries) {
         if (room.archived)
@@ -564,6 +609,35 @@ export class GitStore {
             .filter(([, , p]) => wanted.has(p)).map(([, n, p]) => [p, Number(n)]));
     }
     // --- signals ---
+    // The heartbeat of `who` in the room: a tag `<who>.heartbeat.<genesis12>` on the room's last commit here, its text the
+    // facts of the beat (heartbeat/). Each beat replaces the object under the same name, compare-and-swap on the one it
+    // read, so two writers do not overwrite each other blindly. No reader pins it; its replacement is no alarm.
+    // On a signed hub the object is signed by `who` and published with the OID it replaced; a newer beat there wins, and
+    // this one is taken back here (remote.ts).
+    heartbeat(room, who, target, text) {
+        const ref = Remote.heartbeatRef(who, room.genesis), name = ref.slice('refs/tags/'.length);
+        const old = this.rev(`${ref}^{tag}`) ? this.git(['rev-parse', ref]).trim() : null;
+        const obj = this.trust === 'signed' ? Remote.makeHeartbeat(this.h, this.remote(room), who, target, text, this.home)
+            : this.git(['mktag'], { input: `object ${target}\ntype commit\ntag ${name}\ntagger ${who} <${who}@ringi> ${Math.floor(Date.now() / 1000)} +0000\n\n${text}` }).trim();
+        if (this.gitOk(['update-ref', ref, obj, old ?? ZERO]).status !== 0)
+            fail(`${name} moved meanwhile; the next beat writes it`);
+        if (this.trust === 'signed' && !Remote.pushHeartbeat(this.h, this.remote(room), who, obj, old))
+            this.gitOk(['update-ref', ...(old ? [ref, old, obj] : ['-d', ref, obj])]);
+        return obj;
+    }
+    // The room's heartbeats as they stand: whose, on which commit, when, and what they say.
+    heartbeats(room) {
+        const g12 = room.genesis.slice(0, 12);
+        const tags = this.git(['for-each-ref', '--format=%(refname) %(objectname) %(objecttype)', 'refs/tags/']).split('\n')
+            .map(l => l.split(' ')).filter(([ref, , type]) => type === 'tag' && Remote.heartbeatName(ref ?? '')?.genesis12 === g12);
+        const objects = this.tagObjects(tags.map(([, object]) => object));
+        // On a signed hub only a verified beat shows.
+        const ok = (ref, object) => this.trust !== 'signed' || !Remote.verifyHeartbeat(this.h, this.remote(room), ref, object);
+        return tags.flatMap(([ref, object]) => {
+            const o = objects.get(object);
+            return o && ok(ref, object) ? [{ agent: Remote.heartbeatName(ref).actor, target: o.target, time: o.time, text: o.text }] : [];
+        });
+    }
     // An annotated tag without text in its author's namespace, on the message's commit, signed on a signed hub. The
     // message's id in the name keeps it unique, so writing the same signal twice is a no-op.
     signal(room, who, target, name) {
@@ -583,7 +657,8 @@ export class GitStore {
         return this.git(['for-each-ref', '--format=%(refname) %(objectname) %(objecttype)', 'refs/tags/']).split('\n').flatMap(line => {
             const [ref, object, type] = line.split(' ');
             const m = /^refs\/tags\/([a-z0-9]+(?:[_-][a-z0-9]+)*)\.([a-z][a-z0-9.-]*\.[0-9a-f]{12})$/.exec(ref ?? '');
-            return m ? [{ ref, actor: m[1], name: m[2], object, type }] : [];
+            // A heartbeat is no signal: it is replaced on every beat, and readers judge it apart (heartbeats()).
+            return m && !Remote.heartbeatName(ref) ? [{ ref, actor: m[1], name: m[2], object, type }] : [];
         });
     }
     // Annotated tag objects read whole, size-framed: their target, tagger and text are never split on bytes they hold.
@@ -604,7 +679,8 @@ export class GitStore {
             const hdr = body.subarray(0, split < 0 ? body.length : split).toString('utf8');
             const text = split < 0 ? '' : body.subarray(split + 2).toString('utf8').split('-----BEGIN SSH SIGNATURE-----')[0];
             const target = /^object ([0-9a-f]+)\ntype commit$/m.exec(hdr)?.[1] ?? '';
-            out.set(sha, { target, tagger: /^tagger (.*?) <[^>\n]*> \d+ [+-]\d{4}$/m.exec(hdr)?.[1] ?? '', text });
+            const tagger = /^tagger (.*?) <[^>\n]*> (\d+) [+-]\d{4}$/m.exec(hdr);
+            out.set(sha, { target, tagger: tagger?.[1] ?? '', time: Number(tagger?.[2] ?? NaN), text });
         }
         return out;
     }

package/target/esm/store/git/remote.js

@@ -382,8 +382,113 @@ export const verify = (H, R, who, head) => {
         return reason(e);
     }
 };
+// Heartbeats deliberately share the tag transport, but never the immutable signal acceptance.
+// Only this exact namespace is mutable; e.g. `actor.opened.heartbeat.<id>` is still a signal.
+const HEARTBEAT_NAME = /^([a-z0-9]+(?:[_-][a-z0-9]+)*)\.heartbeat\.([0-9a-f]{12})$/;
+export const heartbeatName = (ref) => {
+    const m = ref.startsWith(TAGS) && HEARTBEAT_NAME.exec(ref.slice(TAGS.length));
+    return m ? { actor: m[1], genesis12: m[2] } : null;
+};
+export const heartbeatRef = (who, genesis) => {
+    if (!SHA.test(genesis))
+        C.fail('heartbeat requires a full room genesis');
+    const ref = `${TAGS}${who}.heartbeat.${genesis.slice(0, 12)}`;
+    if (!heartbeatName(ref))
+        C.fail('malformed heartbeat actor');
+    return ref;
+};
+const heartbeatBody = (text) => {
+    if (Buffer.byteLength(text) > 16384)
+        C.fail('heartbeat body exceeds 16 KiB');
+    const decoded = P.decodeText(Buffer.from(text));
+    if (decoded.invalid)
+        C.fail(`heartbeat body is ${decoded.invalid}`);
+    const lines = decoded.text.trimEnd().split('\n');
+    const fields = new Map();
+    for (const line of lines) {
+        const m = /^([A-Z][A-Za-z]*): (.+)$/.exec(line) ?? C.fail('heartbeat body must contain only facts as trailers');
+        if (fields.has(m[1]))
+            C.fail(`duplicate heartbeat field ${m[1]}`);
+        fields.set(m[1], m[2]);
+    }
+    const genesis = fields.get('Room') ?? C.fail('heartbeat must name its full room genesis');
+    if (!SHA.test(genesis))
+        C.fail('heartbeat must name its full room genesis');
+    if (!/^(working|waiting|gone)$/.test(fields.get('State') ?? ''))
+        C.fail('invalid heartbeat State');
+    if (!/^(yes|no|unknown)$/.test(fields.get('Alive') ?? ''))
+        C.fail('invalid heartbeat Alive');
+    const next = Number(fields.get('Next'));
+    if (!Number.isFinite(next) || next <= 0)
+        C.fail('heartbeat Next must be positive seconds');
+    return genesis;
+};
+const heartbeatObject = (H, ref, sha) => {
+    const s = heartbeatName(ref) ?? C.fail('malformed heartbeat namespace');
+    if (!SHA.test(sha) || git(H, ['cat-file', '-t', sha]).trim() !== 'tag')
+        C.fail('heartbeat must be an annotated tag');
+    if (Number(git(H, ['cat-file', '-s', sha])) > 32768)
+        C.fail('heartbeat object exceeds 32 KiB');
+    const decoded = P.decodeText(git(H, ['cat-file', 'tag', sha], { raw: true }));
+    if (decoded.invalid)
+        C.fail(`heartbeat tag is ${decoded.invalid}`);
+    const [header, ...rest] = decoded.text.split('\n\n');
+    const target = /^object ([0-9a-f]+)\ntype commit\ntag ([^\n]+)\ntagger ([^<\n]+) <[^\n]*> (\d+) [+-]\d{4}\n?$/.exec(header) ?? C.fail('malformed heartbeat tag headers');
+    if (!SHA.test(target[1]) || target[2] !== ref.slice(TAGS.length) || target[3].trim() !== s.actor)
+        C.fail('heartbeat tag name or actor disagrees');
+    const text = rest.join('\n\n').split('-----BEGIN SSH SIGNATURE-----')[0];
+    const genesis = heartbeatBody(text);
+    if (!genesis.startsWith(s.genesis12))
+        C.fail('heartbeat tag name and room genesis disagree');
+    return { ...s, genesis, target: target[1], time: Number(target[4]), text };
+};
+const checkHeartbeat = (H, R, ref, sha) => {
+    const s = heartbeatObject(H, ref, sha);
+    if (s.genesis !== R.genesis)
+        C.fail('heartbeat belongs to another room genesis');
+    const b = branch(H, R, rev(H, R.ref) ?? C.fail('heartbeat room has no branch here'));
+    // It is a replica's sync position, not a claim to author or execute the target message.
+    if (!b.control.includes(s.target) && !b.authors.has(s.target) && !b.skipped.has(s.target))
+        C.fail('heartbeat target is not on this room branch');
+    const signer = b.entries.find(e => e.principal === s.actor) ?? C.fail(`unadmitted heartbeat principal ${s.actor}`);
+    checkSignature(H, sha, s.actor, signer.key, 'tag');
+};
+export const verifyHeartbeat = (H, R, ref, sha) => {
+    if (!isRemote(H))
+        return null;
+    if (H.remoteAlarms?.[ref])
+        return H.remoteAlarms[ref];
+    if (H.heartbeatErrors?.[ref])
+        return H.heartbeatErrors[ref];
+    try {
+        checkHeartbeat(H, R, ref, sha);
+        return null;
+    }
+    catch (e) {
+        return reason(e);
+    }
+};
+// Make an object without moving its ref. The caller performs local CAS before publishing with the same old OID.
+export const makeHeartbeat = (H, R, who, target, text, home) => {
+    const ref = heartbeatRef(who, R.genesis);
+    if (!SHA.test(target))
+        C.fail('heartbeat target must be a full commit id');
+    if (/^Room:/m.test(text))
+        C.fail('heartbeat Room is transport metadata');
+    const body = `Room: ${R.genesis}\n${text.trimEnd()}\n`;
+    heartbeatBody(body);
+    const raw = `object ${target}\ntype commit\ntag ${ref.slice(TAGS.length)}\ntagger ${who} <${who}@ringi> ${Math.floor(Date.now() / 1000)} +0000\n\n${body}`;
+    const key = sign(H, who, home)[0]?.slice(2);
+    const signature = key ? command('ssh-keygen', ['-Y', 'sign', '-n', 'git', '-f', key], { input: raw }) : '';
+    const sha = git(H, ['mktag'], { input: raw + signature }).trim();
+    if (isRemote(H))
+        checkHeartbeat(H, R, ref, sha);
+    return sha;
+};
 const SIGNAL_NAME = /^([a-z0-9]+(?:[_-][a-z0-9]+)*)\.([a-z][a-z0-9.-]*)\.([0-9a-f]{12})$/;
 const signalName = (ref) => {
+    if (heartbeatName(ref))
+        C.fail('heartbeat is not an immutable signal');
     const m = ref.startsWith(TAGS) && SIGNAL_NAME.exec(ref.slice(TAGS.length));
     if (!m)
         return C.fail('malformed signal tag namespace');
@@ -479,6 +584,7 @@ const promote = (H, ref, sha) => {
 };
 const syncUnlocked = (H) => {
     H.remoteAlarms = { ...pushAlarms(H) };
+    H.heartbeatErrors = {};
     const url = origin(H);
     if (!url) {
         if (rev(H, 'refs/heads/main'))
@@ -523,7 +629,34 @@ const syncUnlocked = (H) => {
         }
     }
     const tags = refs(H, TAG_TRACK), pinned = refs(H, TAG_ACCEPT);
+    // Include local beats to remove disappeared remote telemetry; unlike signals, nothing is pinned.
+    for (const ref of refs(H, TAGS).keys())
+        if (heartbeatName(ref) && !tags.has(TAG_TRACK + ref.slice(TAGS.length))) {
+            if (pinned.has(TAG_ACCEPT + ref.slice(TAGS.length)))
+                continue; // never waive previously accepted history
+            git(H, ['update-ref', '-d', ref]);
+        }
     for (const name of new Set([...tags.keys()].map(r => r.slice(TAG_TRACK.length)).concat([...pinned.keys()].map(r => r.slice(TAG_ACCEPT.length))))) {
+        const beatRef = TAGS + name;
+        if (heartbeatName(beatRef)) {
+            if (pinned.has(TAG_ACCEPT + name)) {
+                H.remoteAlarms[beatRef] = 'heartbeat namespace overlaps a previously accepted signal; operator review required';
+                continue;
+            }
+            try {
+                const sha = tags.get(TAG_TRACK + name) ?? C.fail('heartbeat is absent from the remote');
+                const b = heartbeatObject(H, beatRef, sha);
+                const R = byGenesis.get(b.genesis) ?? C.fail('heartbeat room is missing or quarantined');
+                checkHeartbeat(H, R, beatRef, sha);
+                git(H, ['update-ref', beatRef, sha]);
+            }
+            catch (e) {
+                H.heartbeatErrors[beatRef] = reason(e);
+                git(H, ['update-ref', '-d', beatRef]);
+                note(`heartbeat ${name}: ${reason(e)}; withheld`);
+            }
+            continue;
+        }
         // Other tags, including the old room-scoped namespace, are not signals.
         if (!SIGNAL_NAME.test(name))
             continue;
@@ -665,6 +798,8 @@ const validateRef = (H, ref, sha) => {
 // Publish one ref. With `behind`, a room's branch the remote has moved on is not an alarm: push returns false and the
 // caller makes its commit again on the new tip.
 export const push = (H, ref, { behind = false } = {}) => {
+    if (heartbeatName(ref))
+        C.fail('heartbeat publication requires its actor and expected object id (pushHeartbeat)');
     if (!isRemote(H))
         return true;
     return locked(H, () => {
@@ -728,6 +863,41 @@ export const push = (H, ref, { behind = false } = {}) => {
         return true;
     });
 };
+// Publish only the actor's exact heartbeat with an explicit old OID. A racing beat is ordinary contention, never a
+// signal rewrite alarm. Neither success nor failure changes immutable acceptance pins or budget/history state.
+export const pushHeartbeat = (H, R, who, sha, expected) => {
+    const ref = heartbeatRef(who, R.genesis);
+    if (!SHA.test(sha) || (expected !== null && !SHA.test(expected)))
+        C.fail('heartbeat publication requires full object ids');
+    if (!isRemote(H))
+        return true;
+    return locked(H, () => {
+        if (object(H, ref) !== sha)
+            return false; // a newer local beat already won
+        if (object(H, TAG_ACCEPT + ref.slice(TAGS.length)))
+            C.fail('heartbeat namespace overlaps previously accepted signal history');
+        checkHeartbeat(H, R, ref, sha);
+        const url = origin(H);
+        if (!url)
+            return true;
+        checkUrl(url);
+        const r = git(H, ['push', '-q', '--porcelain', `--force-with-lease=${ref}:${expected ?? ''}`, url, `${sha}:${ref}`], { ok: true });
+        if (r.status !== 0) {
+            // A lost acknowledgement is safe to reconcile: equality proves no second beat is needed.
+            const observed = git(H, ['ls-remote', '--refs', url, ref], { ok: true });
+            const got = observed.status === 0 ? observed.stdout.trim().split(/\s+/) : [];
+            if (got[0] !== sha || got[1] !== ref) {
+                if (/\[rejected\].*\(stale info\)/.test(r.stdout))
+                    return false;
+                C.fail(`heartbeat push failed for ${ref.slice(TAGS.length)}: ${String(r.stderr || r.stdout || 'transport error').trim().split('\n').at(-1)}`);
+            }
+        }
+        git(H, ['update-ref', TAG_TRACK + ref.slice(TAGS.length), sha]);
+        if (H.heartbeatErrors)
+            delete H.heartbeatErrors[ref];
+        return true;
+    });
+};
 // Only the operator command calls this after reviewing a room's transport alarm: the room's branch as the remote has
 // it becomes the accepted baseline, and the displaced local branch is kept as evidence. Nothing is waived: the branch
 // must verify, and its invalid commits stay skipped.