@mcsherrylabs/pi-meerkat 0.7.0 → 0.10.1

package/dist/installer-runtime/dist/src/registry/provision.js

@@ -0,0 +1,225 @@
+// Make the registry's channel exist with the terms this feature needs, and prove it by reading.
+//
+// ONE term now, and it is load-bearing for everything:
+//
+//   writePolicy = open    so third parties may announce, AND so any holder will serve a body
+//
+// ⚠️ THERE USED TO BE THREE, and the other two were a DA group of { this node } at m=1. The
+// argument was FR-007 satisfied structurally: `InsufficientDA` is enforced at admit and at
+// pre-commit, so an announcement that committed could not have committed without this node
+// holding the body. That much was true. What it left out is who paid for it — a third party's
+// write needed an attestation from this one node, so announcing required a live p2p path to
+// the registry and failed `503 da_unavailable` with nothing ordered when it was down. An index
+// being unavailable stopped people writing the thing being indexed. And the guarantee bought
+// with that was one volume, not replication: lose it and the message was gone anyway.
+//
+// So the DA policy is REMOVED — permanently, and this path converges an existing channel to
+// that shape rather than leaving two designs in the estate. Bodies are best-effort, `misses`
+// is the honest metric, and the drainer already treated an unfetchable body as a bounded miss
+// rather than a stall, so nothing downstream was relying on the promise.
+//
+// ⚠️ WHAT SURVIVES UNCHANGED: THE OPERATOR ANNOUNCES THROUGH ITS OWN NODE. The first version of
+// this file routed the operator's own announcements through a foreign gateway, which left its
+// entries — including the base instruction document the agent skill trusts most — reachable
+// only by a single best-effort flood. Submitted through THIS node, `channelOriginate` stores
+// the body LOCALLY before the id-only form is ordered (NodeBootstrap.scala:1339-1341 →
+// ChannelOverlay `onOriginate`). With no DA group that local store is now the ONLY thing
+// putting the operator's own bodies anywhere, so it matters more than it did, not less. See
+// announce.ts and research D3.
+import { buildSignedTx, claimBody, updateChannelWritePolicyBody, LEDGER } from "@mcsherrylabs/evolver-client";
+import { channelTerms, submitAndConfirm, updateChannelDaBody, } from "../announcements.js";
+export function decideRegistryRole(args) {
+    const { terms, self, operator, readOnly } = args;
+    // READ-ONLY: the installer's registry never claims or signs with any identity. `self` is the
+    // PINNED operator name, not this deployment's (nonexistent) identity, and it must NEVER yield
+    // `owner` — a read-only indexer submitting a Claim for a channel someone else owns poisons the
+    // chain's tx queue (evolver#85). Decision folds entirely onto the pinned operator.
+    if (readOnly) {
+        if (terms.owners.length === 0) {
+            return { kind: "waiting", why: `'${terms.ledgerId}' is UNCLAIMED and this read-only registry will not claim it (owned ` +
+                    `by '${operator ?? "(no operator pinned)"}', not by this deployment). Draining the cursor ` +
+                    `and indexing nothing until the operator provisions it.` };
+        }
+        const holder = terms.owners.map((o) => o.name).join(", ");
+        if (operator && !terms.owners.some((o) => o.name === operator))
+            return { kind: "unusable", why: `'${terms.ledgerId}' is owned by ${holder}, but REGISTRY_CHANNEL_OPERATOR pins ` +
+                    `'${operator}'. Either the operator changed — update the pin — or this name was taken by ` +
+                    `somebody else. Refusing to index a channel whose terms are set by a party this deployment ` +
+                    `was not told to trust.` };
+        if (terms.writePolicy !== "open")
+            return { kind: "unusable", why: `'${terms.ledgerId}' is owned by ${holder} and its write policy is ` +
+                    `'${terms.writePolicy}', not 'open'. Every announcement would be a permanent miss.` };
+        return { kind: "reader", holder };
+    }
+    // ALREADY OURS — see "keeping is not acquiring" above. Note this is the IDENTITY name,
+    // matching what the claim/converge path below can actually sign for: a channel owned by a
+    // group we happen to belong to is deliberately NOT treated as ours, because this app holds
+    // one identity and submits as it.
+    if (terms.owners.some((o) => o.name === self))
+        return { kind: "owner" };
+    // UNCLAIMED. The route answers 200 with `owners: []` for a channel that has never existed
+    // (research A2), so this is also what a typo'd REGISTRY_CHANNEL looks like — one more reason
+    // not to answer it by claiming.
+    if (terms.owners.length === 0) {
+        if (operator && operator === self)
+            return { kind: "owner" };
+        return { kind: "waiting", why: operator
+                ? `'${terms.ledgerId}' is UNCLAIMED, and this deployment ('${self}') is not its operator — ` +
+                    `REGISTRY_CHANNEL_OPERATOR names '${operator}'. Draining the cursor and indexing nothing ` +
+                    `until '${operator}' provisions it. Nothing will be claimed here.`
+                : `'${terms.ledgerId}' is UNCLAIMED and no REGISTRY_CHANNEL_OPERATOR is set, so this ` +
+                    `deployment will not claim it — a channel name is permanent and cannot be reused, and ` +
+                    `boot order is not a mandate. Draining the cursor and indexing nothing. To make THIS ` +
+                    `deployment the operator, set REGISTRY_CHANNEL_OPERATOR=${self} and restart.` };
+    }
+    const holder = terms.owners.map((o) => o.name).join(", ");
+    // OWNED, BUT NOT BY THE NAMED OPERATOR. Unusable rather than reader: the terms are set by
+    // somebody this deployment was not told to trust, and quietly indexing them is how a squatted
+    // channel becomes an index nobody audits.
+    if (operator && !terms.owners.some((o) => o.name === operator))
+        return { kind: "unusable", why: `'${terms.ledgerId}' is owned by ${holder}, but REGISTRY_CHANNEL_OPERATOR names ` +
+                `'${operator}'. Either the operator changed — update the key — or this name was taken by ` +
+                `somebody else, in which case choose another REGISTRY_CHANNEL. Refusing to index a ` +
+                `channel whose terms are set by a party this deployment was not told to trust.` };
+    // ⚠️ NO DA POLICY IS THE EXPECTED SHAPE, and this used to be the refusal that made reader
+    // mode pointless: "nothing is OBLIGED to hold a body, so a reader cannot index what nobody
+    // must keep." Bodies are best-effort by design now (see [[ProvisionResult]]), a miss is a
+    // counted outcome rather than a broken premise, and refusing here would refuse the registry's
+    // own channel. A channel that still HAS a DA policy is read just the same — it is a legacy
+    // shape the owner has not converged yet, not an error.
+    if (terms.writePolicy !== "open")
+        return { kind: "unusable", why: `'${terms.ledgerId}' is owned by ${holder} and its write policy is ` +
+                `'${terms.writePolicy}', not 'open'. With no DA group there is no membership that would ` +
+                `let a holder serve us anyway, so an open write policy is the ONLY thing that makes a ` +
+                `body obtainable — every announcement would be a permanent miss. Ask ${holder} to open ` +
+                `the channel, or choose another REGISTRY_CHANNEL.` };
+    return { kind: "reader", holder };
+}
+export async function provisionRegistryChannel(args) {
+    const { node, chainUrl, chainAgreedUrl, channel, owner, signer, nodeIdentity, operator, say, pace } = args;
+    let writes = 0;
+    // ⚠️ READ AND DECIDE BEFORE WRITING ANYTHING.
+    //
+    // A DA group used to be created here, ahead of the role decision, so a deployment that turned
+    // out to be a mere READER had already created and paid for a group it could never be asked to
+    // attest with. No group is created at all now, which retires that hazard rather than ordering
+    // around it — but the rule it taught still holds: decide first, so `writes === 0` is a fact
+    // about a reader rather than a hope.
+    const ask = () => channelTerms(chainUrl, channel); // "has MY node applied it?"
+    const read = await channelTerms(chainAgreedUrl, channel); // "what has the CHAIN agreed?"
+    // Refusing to guess, for the reason the group read refuses: acting on an unreadable answer
+    // means submitting a Claim for a channel somebody else may own, which the node accepts and
+    // then rejects every round until its TTL, poisoning the queue for the whole chain
+    // (evolver#85).
+    if (!read.ok)
+        throw new Error(`could not read the terms of '${channel}' from ${chainAgreedUrl}: ${read.why}\n` +
+            `  Refusing to guess — a Claim for a channel someone else owns is retained ` +
+            `and re-proposed until its TTL, which suppresses wake-on-work chain-wide.`);
+    const terms = read.terms;
+    const role = decideRegistryRole({ terms, self: owner.nodeId, operator });
+    if (role.kind === "unusable")
+        throw new Error(role.why);
+    if (role.kind === "waiting") {
+        // NOT a throw, and the distinction is the node's liveness. This process is what reads
+        // `/api/channel/next`; kill it and the node stops applying, so a deployment that merely
+        // has nothing to index would take its own node's core state down with it.
+        say(`   ⚠ ${role.why}`);
+        return { role: "waiting", channel, member: nodeIdentity, writes: 0 };
+    }
+    if (role.kind === "reader") {
+        // A channel's terms are its owner's alone to set — so we set none. Indexing never
+        // needed ownership: the cursor, the walk, the store and the read surface are all
+        // node-local, and the only thing the chain has to grant us is the ABILITY TO FETCH A
+        // BODY, which `writePolicy = open` is exactly what grants (see [[decideRegistryRole]]).
+        say(`   '${channel}' is owned by ${role.holder}, not by '${owner.nodeId}' — running as a READER`);
+        say(`   writes are open, so any node holding a body will serve it to us on request.`);
+        say(`   Nothing will be claimed or provisioned here.`);
+        say(`   ⚠ availability is BEST EFFORT — for the owner too, since this channel carries no DA`);
+        say(`     policy. A body nobody kept is reported as a miss; see /summary.`);
+        return { role: "reader", channel, member: nodeIdentity, writes: 0 };
+    }
+    // ── from here down this deployment OWNS the channel (or it is unclaimed and named for us) ──
+    say(`   channel '${channel}' — no DA policy by design; writes open so any holder will serve`);
+    const ownedByUs = terms.owners.some((o) => o.name === owner.nodeId);
+    // The ONLY acceptable DA state is none at all. `terms.da` present means a channel claimed by
+    // an older build, and converging it is how the estate ends up with one design rather than two.
+    const daOk = !terms.da;
+    const openOk = terms.writePolicy === "open";
+    if (!ownedByUs) {
+        // One transaction sets every term, so there is no window in which the channel is claimed
+        // but not yet open. `claimBody` with no daGroup/daThresholdM is not DA-managed.
+        const claim = buildSignedTx({
+            ledgerId: LEDGER.owners, senderNodeId: owner.nodeId,
+            body: claimBody({ ledgerId: channel, writePolicy: "open" }),
+            ttlRound: BigInt((await node.currentRound()) + 50), signers: [signer],
+        });
+        await submitAndConfirm(node, claim, `claim '${channel}' (no DA, open)`, async () => {
+            const r = await ask();
+            return r.ok && r.terms.owners.some((o) => o.name === owner.nodeId) &&
+                !r.terms.da && r.terms.writePolicy === "open";
+        }, say, { pace });
+        return { role: "owner", channel, member: nodeIdentity, writes: writes + 1 };
+    }
+    // OURS ALREADY, but a term has drifted. Converge IN PLACE — never by unclaiming: a full
+    // unclaim drops all three policy rows and leaves the name UNOWNED between the two
+    // transactions, so on a shared chain anyone can take it. A second Claim is a committed no-op
+    // on an already-claimed ledger, so the targeted updates are the only thing that converges.
+    //
+    // ⚠️ THIS IS THE MIGRATION, and it runs itself. A channel claimed by an older build still
+    // carries a DA group; an empty `daGroup` in UpdateChannelDa turns the policy OFF
+    // (owners.proto: "da_group empty = turn DA off"), so the first boot of this build as owner
+    // removes it. No hand-signed transaction, and nothing to remember to do.
+    if (!daOk) {
+        say(`   DA policy is '${terms.da.group}' (m=${terms.da.thresholdM}); this registry wants NONE — removing in place`);
+        const upd = buildSignedTx({
+            ledgerId: LEDGER.owners, senderNodeId: owner.nodeId,
+            body: updateChannelDaBody({ ledgerId: channel, daGroup: "", daThresholdM: 0 }),
+            ttlRound: BigInt((await node.currentRound()) + 50), signers: [signer],
+        });
+        await submitAndConfirm(node, upd, `remove '${channel}' DA policy`, async () => {
+            const r = await ask();
+            return r.ok && !r.terms.da;
+        }, say, { pace });
+        writes += 1;
+    }
+    if (!openOk) {
+        say(`   write policy is '${terms.writePolicy}', this registry needs 'open' — updating in place`);
+        const upd = buildSignedTx({
+            ledgerId: LEDGER.owners, senderNodeId: owner.nodeId,
+            body: updateChannelWritePolicyBody({ ledgerId: channel, writePolicy: "open" }),
+            ttlRound: BigInt((await node.currentRound()) + 50), signers: [signer],
+        });
+        await submitAndConfirm(node, upd, `open '${channel}' to any writer`, async () => {
+            const r = await ask();
+            return r.ok && r.terms.writePolicy === "open";
+        }, say, { pace });
+        writes += 1;
+    }
+    if (writes === 0)
+        say(`   '${channel}' already has the terms this registry needs — nothing to submit`);
+    return { role: "owner", channel, member: nodeIdentity, writes };
+}
+/**
+ * READ-ONLY provisioning: decide the role from the chain-agreed terms and NEVER submit, claim or
+ * sign. Used only by the installer's registry (`REGISTRY_READ_ONLY=1`), where no identity exists to
+ * sign with and the pinned operator (`REGISTRY_CHANNEL_OPERATOR`) is the only authority trusted.
+ */
+export async function provisionRegistryChannelReadOnly(args) {
+    const { chainAgreedUrl, channel, nodeIdentity, operator, say } = args;
+    const read = await channelTerms(chainAgreedUrl, channel);
+    if (!read.ok)
+        throw new Error(`could not read the terms of '${channel}' from ${chainAgreedUrl}: ${read.why}\n` +
+            `  Refusing to guess — an unreadable answer is "not yet", never a licence to index unverified terms.`);
+    const role = decideRegistryRole({ terms: read.terms, self: operator ?? "", operator, readOnly: true });
+    if (role.kind === "unusable")
+        throw new Error(role.why);
+    if (role.kind === "waiting") {
+        say(`   ⚠ ${role.why}`);
+        return { role: "waiting", channel, member: nodeIdentity, writes: 0 };
+    }
+    if (role.kind !== "reader")
+        throw new Error(`read-only registry resolved an impossible owner role — refusing to index`);
+    say(`   '${channel}' is owned by ${role.holder} — running as a READ-ONLY reader`);
+    say(`   nothing will be claimed, provisioned or submitted here`);
+    return { role: "reader", channel, member: nodeIdentity, writes: 0 };
+}

package/dist/installer-runtime/dist/src/registry/store.js

@@ -0,0 +1,242 @@
+import { BindingError } from "@mcsherrylabs/evolver-client/processor";
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS entries (
+  ledger_id TEXT PRIMARY KEY, announcer TEXT NOT NULL, provenance TEXT NOT NULL,
+  seq INTEGER NOT NULL, kind TEXT NOT NULL, title TEXT NOT NULL, summary TEXT NOT NULL,
+  keywords TEXT NOT NULL,
+  detail_key TEXT, detail_sha256 TEXT, detail_bytes INTEGER,
+  detail_state TEXT NOT NULL DEFAULT 'ok', detail_reason TEXT,
+  announced_at_round INTEGER NOT NULL, verified_at_round INTEGER NOT NULL,
+  requested_expiry_round INTEGER NOT NULL, granted_expiry_round INTEGER NOT NULL,
+  state TEXT NOT NULL, tx_id TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS entries_state    ON entries(state);
+CREATE INDEX IF NOT EXISTS entries_kind     ON entries(kind);
+CREATE INDEX IF NOT EXISTS entries_announced ON entries(announced_at_round);
+CREATE TABLE IF NOT EXISTS rejections (
+  tx_id TEXT PRIMARY KEY, round INTEGER NOT NULL, sender TEXT NOT NULL,
+  ledger_id TEXT NOT NULL, reason TEXT NOT NULL, detail TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS meta (k TEXT PRIMARY KEY, v TEXT NOT NULL);
+-- The VERIFIED detail document, kept here because the registry is the only thing an agent can
+-- reach. Bounded by MAX_DETAIL_BYTES before it is ever stored, and keyed by the content key so
+-- two channels announcing the same document hold one copy.
+CREATE TABLE IF NOT EXISTS detail_docs (
+  detail_key TEXT PRIMARY KEY, sha256 TEXT NOT NULL, bytes BLOB NOT NULL, fetched_at INTEGER NOT NULL
+);
+-- A delivery whose control check could not be DECIDED, held with its body so the answer can be
+-- sought again on a later walk. See defer() below for why this table has to exist.
+CREATE TABLE IF NOT EXISTS deferred (
+  tx_id TEXT PRIMARY KEY, round INTEGER NOT NULL, idx INTEGER NOT NULL,
+  sender TEXT NOT NULL, ledger_id TEXT NOT NULL, body BLOB NOT NULL,
+  first_seen INTEGER NOT NULL, attempts INTEGER NOT NULL DEFAULT 0, last_why TEXT NOT NULL DEFAULT ''
+);
+`;
+export class RegistryStore {
+    #db;
+    #channel;
+    #readMisses;
+    /** All collaborators run on the supplied database owner's serialized execution domain.
+     * `readMisses` concerns THIS index's channel and must propagate failures, never return a
+     * fabricated zero. Keeping it explicit prevents dependence on generic storage table names. */
+    constructor(db, channel, readMisses) {
+        this.#db = db;
+        this.#channel = channel;
+        this.#readMisses = readMisses;
+        this.#db.exec(SCHEMA);
+    }
+    /**
+     * Bind this index to its channel, or REFUSE. The shared owner validates the chain/node binding
+     * before installing the module; this store owns only the registry-channel half.
+     *
+     * Every row here describes an announcement on ONE channel, verified against that channel's
+     * control. Reading them as the index of a different channel would serve assertions nobody
+     * made there. A first bind records; a mismatch throws.
+     */
+    bindChannel() {
+        const chan = this.#meta("request_channel");
+        if (chan === null) {
+            this.#setMeta("request_channel", this.#channel);
+            return;
+        }
+        if (chan !== this.#channel)
+            throw new BindingError(`this store's index was built while draining '${chan}', but the configuration says ` +
+                `'${this.#channel}'. Its entries describe the other channel; serving them as this one's ` +
+                `would be wrong. Point PROCESSOR_DB at the right store, or set REGISTRY_CHANNEL back.`);
+    }
+    #meta(k) {
+        const r = this.#db.prepare("SELECT v FROM meta WHERE k = ?").get(k);
+        return r?.v ?? null;
+    }
+    #setMeta(k, v) {
+        this.#db.prepare("INSERT INTO meta (k, v) VALUES (?, ?) ON CONFLICT(k) DO UPDATE SET v = excluded.v").run(k, v);
+    }
+    /** Replace any live entry for this channel (FR-008, FR-013). One statement, so a refresh
+     *  cannot briefly leave two rows or none. */
+    put(e) {
+        this.#db.prepare(`
+      INSERT INTO entries (ledger_id, announcer, provenance, seq, kind, title, summary, keywords,
+        detail_key, detail_sha256, detail_bytes, detail_state, detail_reason,
+        announced_at_round, verified_at_round, requested_expiry_round, granted_expiry_round, state, tx_id)
+      VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)
+      ON CONFLICT(ledger_id) DO UPDATE SET
+        announcer=excluded.announcer, provenance=excluded.provenance, seq=excluded.seq,
+        kind=excluded.kind, title=excluded.title, summary=excluded.summary, keywords=excluded.keywords,
+        detail_key=excluded.detail_key, detail_sha256=excluded.detail_sha256, detail_bytes=excluded.detail_bytes,
+        detail_state=excluded.detail_state, detail_reason=excluded.detail_reason,
+        announced_at_round=excluded.announced_at_round, verified_at_round=excluded.verified_at_round,
+        requested_expiry_round=excluded.requested_expiry_round, granted_expiry_round=excluded.granted_expiry_round,
+        state=excluded.state, tx_id=excluded.tx_id`).run(e.ledgerId, e.announcer, e.provenance, e.seq, e.kind, e.title, e.summary, JSON.stringify(e.keywords), e.detail?.key ?? null, e.detail?.sha256 ?? null, e.detail?.bytes ?? null, e.detail?.state ?? "ok", e.detail?.reason ?? null, Number(e.announcedAtRound), Number(e.verifiedAtRound), Number(e.requestedExpiryRound), Number(e.grantedExpiryRound), e.state, e.txId);
+    }
+    get(ledgerId, deny = new Set()) {
+        const r = this.#db.prepare("SELECT * FROM entries WHERE ledger_id = ?").get(ledgerId);
+        if (!r)
+            return null;
+        const e = row(r);
+        return deny.has(e.announcer) ? null : e;
+    }
+    /**
+     * Search. Ordering is `announced_at_round` ASC — deterministic, and not influenced by
+     * anything an announcer supplies (FR-022): the only way to rank higher is to have been there
+     * longer, which cannot be bought with keywords.
+     */
+    search(q, deny = new Set()) {
+        const all = this.#db.prepare("SELECT * FROM entries ORDER BY announced_at_round ASC, ledger_id ASC")
+            .all().map(row).filter((e) => !deny.has(e.announcer));
+        const terms = (q.terms ?? []).map((t) => t.trim().toLowerCase()).filter((t) => t.length > 0);
+        const match = (e) => (q.kind === undefined || e.kind === q.kind) &&
+            (terms.length === 0 || terms.some((t) => e.keywords.includes(t) || e.title.toLowerCase().includes(t) ||
+                e.summary.toLowerCase().includes(t) || e.ledgerId.toLowerCase().includes(t)));
+        const hits = all.filter(match);
+        return { total: hits.length, entries: hits.slice(q.offset, q.offset + q.limit) };
+    }
+    summary(deny = new Set()) {
+        const all = this.#db.prepare("SELECT * FROM entries").all()
+            .map(row).filter((e) => !deny.has(e.announcer));
+        const entries = { live: 0, expired: 0 };
+        const kinds = {};
+        const kw = new Map();
+        for (const e of all) {
+            entries[e.state] += 1;
+            if (e.state === "live") {
+                kinds[e.kind] = (kinds[e.kind] ?? 0) + 1;
+                for (const k of e.keywords)
+                    kw.set(k, (kw.get(k) ?? 0) + 1);
+            }
+        }
+        const keywords = [...kw.entries()].map(([keyword, live]) => ({ keyword, live }))
+            .sort((a, b) => b.live - a.live || a.keyword.localeCompare(b.keyword));
+        return { entries, kinds, keywords, misses: this.misses(), deferred: this.deferredCount() };
+    }
+    /** Mark leases that the tip has passed (FR-012). Kept, never deleted: an agent that reads
+     *  "expired" learns more than one that reads nothing. */
+    sweep(tipRound) {
+        const r = this.#db.prepare("UPDATE entries SET state = 'expired' WHERE state = 'live' AND granted_expiry_round < ?")
+            .run(Number(tipRound));
+        return Number(r.changes);
+    }
+    /** Keep a VERIFIED detail document. The caller has already checked its digest and its size —
+     *  this stores bytes, it does not vouch for them. */
+    putDetailDoc(key, sha256, bytes) {
+        this.#db.prepare(`INSERT INTO detail_docs (detail_key, sha256, bytes, fetched_at) VALUES (?,?,?,?)
+      ON CONFLICT(detail_key) DO UPDATE SET sha256=excluded.sha256, bytes=excluded.bytes,
+      fetched_at=excluded.fetched_at`).run(key, sha256, bytes, Date.now());
+    }
+    detailDoc(key) {
+        const r = this.#db.prepare("SELECT sha256, bytes FROM detail_docs WHERE detail_key = ?").get(key);
+        if (!r || r.bytes === undefined || r.sha256 === undefined)
+            return null;
+        return { sha256: String(r.sha256), bytes: new Uint8Array(r.bytes) };
+    }
+    reject(r) {
+        this.#db.prepare(`INSERT INTO rejections (tx_id, round, sender, ledger_id, reason, detail)
+      VALUES (?,?,?,?,?,?) ON CONFLICT(tx_id) DO NOTHING`)
+            .run(r.txId, Number(r.round), r.sender, r.ledgerId, r.reason, r.detail.slice(0, 500));
+    }
+    rejections(limit = 50) {
+        return this.#db.prepare("SELECT * FROM rejections ORDER BY round DESC LIMIT ?").all(limit)
+            .map((r) => ({
+            txId: String(r.tx_id), round: BigInt(Number(r.round)), sender: String(r.sender),
+            ledgerId: String(r.ledger_id), reason: String(r.reason), detail: String(r.detail),
+        }));
+    }
+    /**
+     * HOLD a delivery whose control check could not be decided, WITH ITS BODY.
+     *
+     * ⚠️ THE ONLY UNRECOVERABLE THING IN THIS SYSTEM IS THE BODY, and the undetermined path used
+     * to throw one away while holding it. `/api/channel/next` is forward-only and no route fetches
+     * a body by txId (evolver#87), so once the walk has passed a position the body exists in
+     * exactly one place: this process's memory. Recording a miss and dropping it meant a chain
+     * read that was briefly unavailable cost an announcement its entry until its owner refreshed
+     * — for a reason that had nothing to do with the announcement.
+     *
+     * So it is written down instead, and retried on every later walk. The walk still never
+     * blocks: the single consumer moves on immediately, which is the property that mattered.
+     */
+    defer(d) {
+        this.#db.prepare(`INSERT INTO deferred (tx_id, round, idx, sender, ledger_id, body, first_seen, attempts, last_why)
+      VALUES (?,?,?,?,?,?,?,1,?)
+      ON CONFLICT(tx_id) DO UPDATE SET attempts = attempts + 1, last_why = excluded.last_why`)
+            .run(d.txId, Number(d.round), d.index, d.sender, d.ledgerId, d.body, Date.now(), d.why.slice(0, 300));
+    }
+    /** Oldest first: a delivery held longer has waited longer, and order of arrival is the only
+     *  ranking this system recognises. */
+    deferredAll(limit = 100) {
+        return this.#db.prepare("SELECT * FROM deferred ORDER BY round ASC, idx ASC LIMIT ?")
+            .all(limit).map((r) => ({
+            txId: String(r.tx_id), round: BigInt(Number(r.round)), index: Number(r.idx),
+            sender: String(r.sender), ledgerId: String(r.ledger_id),
+            body: new Uint8Array(r.body), attempts: Number(r.attempts),
+            why: String(r.last_why),
+        }));
+    }
+    undefer(txId) {
+        this.#db.prepare("DELETE FROM deferred WHERE tx_id = ?").run(txId);
+    }
+    deferredCount() {
+        const r = this.#db.prepare("SELECT COUNT(*) AS n FROM deferred").get();
+        return Number(r.n);
+    }
+    /** Announcements whose bodies never arrived, not authorization rejections, failed reads,
+     * module errors, or eviction of a body that was already indexed. The shared owner's outcome
+     * projection defines these facts; this store does not know its generic inbox schema. */
+    misses() { return this.#readMisses(); }
+}
+function row(r) {
+    const detail = r.detail_key
+        ? {
+            key: String(r.detail_key), sha256: String(r.detail_sha256), bytes: Number(r.detail_bytes),
+            state: String(r.detail_state),
+            ...(r.detail_reason ? { reason: String(r.detail_reason) } : {}),
+        }
+        : undefined;
+    return {
+        ledgerId: String(r.ledger_id), announcer: String(r.announcer),
+        provenance: String(r.provenance), seq: Number(r.seq),
+        kind: String(r.kind), title: String(r.title), summary: String(r.summary),
+        keywords: JSON.parse(String(r.keywords)),
+        ...(detail ? { detail } : {}),
+        announcedAtRound: BigInt(Number(r.announced_at_round)),
+        verifiedAtRound: BigInt(Number(r.verified_at_round)),
+        requestedExpiryRound: BigInt(Number(r.requested_expiry_round)),
+        grantedExpiryRound: BigInt(Number(r.granted_expiry_round)),
+        state: String(r.state), txId: String(r.tx_id),
+    };
+}
+/** Build an entry from an accepted announcement — the one place the two shapes meet, so a new
+ *  announcement field cannot reach the index without passing through here. */
+export function entryFrom(args) {
+    const { a } = args;
+    return {
+        ledgerId: a.ledgerId, announcer: args.announcer, provenance: args.provenance, seq: a.seq,
+        kind: a.kind, title: a.title, summary: a.summary, keywords: a.keywords,
+        ...(a.detail ? { detail: {
+                ...a.detail, state: args.detailState ?? "ok",
+                ...(args.detailReason ? { reason: args.detailReason } : {}),
+            } } : {}),
+        announcedAtRound: args.announcedAtRound, verifiedAtRound: args.verifiedAtRound,
+        requestedExpiryRound: args.lease.requestedExpiryRound,
+        grantedExpiryRound: args.lease.grantedExpiryRound,
+        state: "live", txId: args.txId,
+    };
+}

package/dist/installer-runtime/dist/src/registry/sweep.js

@@ -0,0 +1,9 @@
+/** One pass. Separated from the timer so it can be driven directly in a test and once at boot,
+ *  where waiting a whole interval to retire an already-stale entry would be strange. */
+export function sweepOnce(store, tipRound, say) {
+    const n = store.sweep(tipRound);
+    if (n > 0)
+        say(`   ${n} lease(s) expired as of round ${tipRound}`);
+    return n;
+}
+// Scheduled by the shared worker's serialized afterWalk hook, including quiet walks.

package/dist/installer-runtime/dist/src/registry/worker-module.js

@@ -0,0 +1,87 @@
+// Registry adapter for the shared SDK's ONE storage worker. No listener, polling, setup,
+// subscription mutation, signing material, second database or independent DB timer lives here.
+// The parent provisions using RuntimeModule.setup({pace,readModule}), after recovery listeners.
+import { position, validateChannelId, } from "@mcsherrylabs/evolver-client/processor";
+import { registryDependencies } from "./dependencies.js";
+import { createRegistryHandler } from "./drainer.js";
+import { registryRoutes } from "./http.js";
+import { RegistryStore } from "./store.js";
+import { sweepOnce } from "./sweep.js";
+export const REGISTRY_MODULE_NAME = "registry";
+function readRequest(request) {
+    if (!request || typeof request !== "object")
+        throw new Error("invalid registry read projection");
+    const r = request;
+    if (typeof r.path !== "string" || r.path.length > 4096 || !r.path.startsWith("/") || r.path.startsWith("//") ||
+        typeof r.tip !== "string" || typeof r.walked !== "string" ||
+        (r.deny !== undefined && (!Array.isArray(r.deny) || r.deny.length > 1024 || r.deny.some(id => typeof id !== "string"))))
+        throw new Error("invalid registry read projection");
+    position(r.tip, "0");
+    position(r.walked, "0");
+    return r;
+}
+/** Factory with explicit collaborators for owned tests and trusted application composition.
+ * Only the default factory below is selected by the production ModuleReference. */
+export function createRegistryWorkerModule(options, deps, clock) {
+    validateChannelId(options.channel);
+    if (deps.channel !== options.channel)
+        throw new Error("registry handler channel differs from module claim");
+    return {
+        name: REGISTRY_MODULE_NAME,
+        install(context) {
+            const store = new RegistryStore(context.db, options.channel, () => {
+                const summary = context.outcomeSummary(options.channel);
+                const total = Number(summary.unavailable);
+                if (!/^(0|[1-9][0-9]*)$/.test(summary.unavailable) || !Number.isSafeInteger(total))
+                    throw new Error("registry unavailable count is not an exact safe integer");
+                if (summary.lastRound !== null)
+                    position(summary.lastRound, "0");
+                return { total, lastRound: summary.lastRound === null ? null : BigInt(summary.lastRound) };
+            });
+            store.bindChannel();
+            const handler = createRegistryHandler(store, deps, clock);
+            // Only serialized read projections set this view; never an independently scheduled task.
+            let view = {
+                tip: 0n, walked: 0n, deny: new Set(options.deny),
+            };
+            const routes = registryRoutes({
+                store, chain: options.chain, channel: options.channel,
+                tipRound: () => view.tip, walkedRound: () => view.walked, deny: () => view.deny,
+            });
+            return {
+                handlers: [[options.channel, async (delivery) => {
+                            // SDK positions are canonical strings in the node Int range. The registry's domain
+                            // logic uses bigint rounds and safe numeric indices internally, never on the wire.
+                            await handler.handle({ ...delivery, round: BigInt(delivery.round), index: Number(delivery.index) });
+                        }]],
+                afterWalk({ tip }) {
+                    handler.takeAccepted();
+                    // The owner invokes this hook, including quiet walks. No DB handle escapes to a timer.
+                    sweepOnce(store, BigInt(tip), deps.say);
+                },
+                read(request) {
+                    const r = readRequest(request);
+                    view = { tip: BigInt(r.tip), walked: BigInt(r.walked), deny: new Set(r.deny ?? options.deny) };
+                    const url = new URL(r.path, "http://registry.local");
+                    const route = routes.find(candidate => candidate.prefix
+                        ? url.pathname.startsWith(candidate.path) : url.pathname === candidate.path);
+                    return route ? route.handle(url) : { status: 404, json: { error: "not_found" } };
+                },
+            };
+        },
+    };
+}
+/** Trusted local factory: its options are cloneable deployment settings, never remote plugin
+ * discovery or signing keys. Loading the module does not install it or touch the node. */
+export default function registryWorkerModule(value) {
+    if (!value || typeof value !== "object")
+        throw new Error("registry worker options are required");
+    const o = value;
+    if (typeof o.chain !== "string" || typeof o.channel !== "string" || typeof o.operator !== "string" ||
+        typeof o.chainUrl !== "string" || (o.contentUrl !== null && typeof o.contentUrl !== "string") ||
+        !Number.isSafeInteger(o.maxLeaseRounds) || o.maxLeaseRounds < 1 ||
+        !Array.isArray(o.deny) || o.deny.length > 1024 || o.deny.some(id => typeof id !== "string"))
+        throw new Error("invalid registry worker options");
+    const options = o;
+    return createRegistryWorkerModule(options, registryDependencies(options, message => console.log(message)));
+}