@mcsherrylabs/pi-meerkat 0.6.0 → 0.8.0

package/dist/installer-runtime/dist/scripts/wait-for-chain.js

@@ -0,0 +1,90 @@
+// Wait until the target's node is up AND its chain is actually committing.
+//
+// "The container is running" is not the same as "the chain is usable": the node generates
+// keys, writes genesis, migrates two databases and starts consensus before it will accept a
+// transaction. Polling for a COMMITTED round is the only honest readiness signal — a node
+// that answers /status can still refuse every write with `not-ready`.
+//
+// It resolves the node URL through src/env.ts, the SAME place the app does. It used to read
+// EVOLVER_NODE directly and default to localhost, which made it target-BLIND: the published
+// image runs this before the app, so `docker run -e EVOLVER_TARGET=devnet <image>` polled
+// its own localhost for 180 s and exited before the app ever started.
+//
+// An OPTIONAL argument PINS the chain, and the local-chain scripts pass `local`. They have
+// to: once the default chain can be a remote one, a bare currentTarget() here makes
+// `npm run chain:up` boot the local node and then report the REMOTE chain's tip as its
+// readiness — green while nothing local is up at all. The no-argument form is still what the
+// container runs, where the environment names the chain and the answer must follow it.
+import { currentTarget, isTargetName, targetByName, knownTargets, optionalEnv, TargetError } from "../src/env.js";
+const want = process.argv[2];
+let target;
+try {
+    if (want && !isTargetName(want)) {
+        console.error(`unknown chain '${want}' — available by name: ${knownTargets().map((t) => t.name).join(", ")}`);
+        process.exit(1);
+    }
+    target = want ? targetByName(want) : currentTarget();
+}
+catch (e) {
+    if (e instanceof TargetError) {
+        console.error(`\n✗ ${e.message}\n`);
+        process.exit(1);
+    }
+    throw e;
+}
+// Through optionalEnv for the reason documented there: compose passes CHAIN_WAIT_MS through
+// as present-and-empty, `Number("")` is 0, and a 0 ms deadline means the loop below never
+// runs even once — the app then reports "chain not ready after 0s" about a chain it never
+// asked. Junk is treated the same way as absent, because "unparseable" must not silently
+// become "do not wait at all".
+const DEADLINE_MS = (() => {
+    const raw = optionalEnv("CHAIN_WAIT_MS");
+    const n = raw === undefined ? NaN : Number(raw);
+    if (raw !== undefined && !(Number.isFinite(n) && n > 0))
+        console.error(`(ignoring CHAIN_WAIT_MS='${raw}' — not a positive number of milliseconds)`);
+    return Number.isFinite(n) && n > 0 ? n : 180_000;
+})();
+if (process.env.EVOLVER_INSECURE_TLS === "1")
+    process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
+const started = Date.now();
+let lastErr = "never reached";
+while (Date.now() - started < DEADLINE_MS) {
+    try {
+        const res = await fetch(`${target.nodeUrl}/api/explorer/blocks?limit=1`, {
+            headers: { Accept: "application/json" },
+        });
+        if (res.ok) {
+            const b = (await res.json());
+            const round = b?.blocks?.[0]?.roundNum ?? 0;
+            if (round > 0) {
+                console.log(`chain ready — ${target.nodeUrl}, committed round ${round}`);
+                process.exit(0);
+            }
+            lastErr = "tip still round 0 (consensus started, nothing committed yet)";
+        }
+        else {
+            lastErr = `HTTP ${res.status}`;
+        }
+    }
+    catch (e) {
+        lastErr = e instanceof Error ? e.message.split("\n")[0] : String(e);
+    }
+    await new Promise((r) => setTimeout(r, 2000));
+}
+// Advice depends on WHERE this is running: inside the published image there is no npm
+// project and no docker compose, so the host-side commands would be a dead end.
+const inContainer = process.env.EVOLVER_IN_CONTAINER === "1";
+const advice = inContainer
+    ? [
+        `  · this container waits for target '${target.name}' at ${target.nodeUrl}`,
+        `  · pointing at a remote chain?   docker run -e EVOLVER_TARGET=devnet ...`,
+        `  · running the bundled chain?    the 'node' service must be healthy first`,
+    ]
+    : [
+        `  · docker compose ps            is the node running?`,
+        `  · docker compose logs node     what did it say?`,
+        `  · npm run reset                wipe chain + local state and start over`,
+    ];
+console.error(`\n✗ chain not ready after ${Math.round(DEADLINE_MS / 1000)}s at ${target.nodeUrl} ` +
+    `(target '${target.name}') — last: ${lastErr}\n` + advice.join("\n") + "\n");
+process.exit(1);

package/dist/installer-runtime/dist/src/announcements.js

@@ -0,0 +1,448 @@
+// ── the announcements channel: claim it (with DA), write to it, read it back ─
+//
+// This is the part the template leaves out, and the reason this app runs a node of its own.
+//
+// A CHANNEL is an owned ledger id that the quorum orders OPAQUELY: the committee agrees the
+// order of the messages and never sees inside them. The app defines what a message means and
+// derives its own state by folding the ordered stream, read from a node with
+// `GET /api/channel/next`. Four facts, each of them established by running this against a live
+// devnet rather than by reading:
+//
+//  1. THE CURSOR IS SINGLE-CONSUMER AND SERVED FROM THE NODE'S OWN POSITION. The (round,index)
+//     a client asks for is a FLOOR, not an address: the node serves the next declared-channel
+//     tx at or after its own cursor, applies everything in between, and advances atomically.
+//     So `{0,0}` means "whatever is next" — and HISTORY CANNOT BE REPLAYED. A caught-up node
+//     answers `not-ready` to `?round=0&index=0`, having passed it.
+//  2. POLLING IS WHAT MAKES A PROCESSING NODE APPLY BLOCKS AT ALL. Apply is deferred and
+//     paced by these polls, so committed reads answer "as of MY cursor" — an unpolled node is
+//     a stopped node. Measured twice: a node whose store was level with devnet answered
+//     `Unknown identity` about ITSELF, and this channel read `owners: []` for a channel devnet
+//     already showed as claimed.
+//  3. EVERY WRITE HERE TIMES OUT AND THEN COMMITS. The submit's commit-wait fires on apply,
+//     which this app paces — so `?wait=true` routinely expires while the transaction is
+//     ordered anyway. A write is therefore SUBMITTED and then CONFIRMED BY READING, never
+//     resent (identical bytes are refused as a duplicate; a rebuilt transaction is a second
+//     transaction). `submitAndConfirm` is that pattern, once, for every write below.
+//  4. A CHANNEL WITH NO DA GROUP CANNOT TAKE A BODY-FORM WRITE. The node refuses it —
+//     "channel 'x' is out-of-band — submit the id-only form (the node does not disseminate
+//     its body)" — because without a DA group nothing will carry the body to anyone. So the
+//     channel is claimed WITH a DA group whose member is this app's own node, and that node
+//     stores and floods the body it will later serve. This is why the group-chat deployment
+//     has a "DA group = the app nodes" step, and why an app cannot simply write to a channel
+//     it claimed with defaults.
+import { buildSignedTx, claimBody, channelBody, createGroupBody, addMemberBody, fString, fVarint, fMessage, concat, LEDGER, } from "@mcsherrylabs/evolver-client";
+/**
+ * The channel this app owns — ONE variable, read by the app AND by the node's
+ * `subscribed-channels` declaration in docker-compose.devnet.yml, because the two must agree
+ * or the write succeeds and the stream stays silent.
+ *
+ * Overridable, and that is not decoration: a channel can become UNUSABLE through no fault of
+ * this app. A message whose body no live node holds stalls a processing node's apply at that
+ * position for as long as its consumer keeps asking for that position (evolver#83, as
+ * corrected: the NODE is not wedged — asking for index+1 walks past it and the skipped tx is
+ * still applied in the slice; what is permanent is the LOSS of that message). The ways past it
+ * are to walk past it and lose it, or to stop declaring that channel — an undeclared channel's
+ * tx is applied in the slice and never offered, so the node walks straight past it. `announcements` was poisoned exactly that way: its DA group had one
+ * member, and that member's volume was destroyed. Hence `announcements1`, and hence a knob
+ * rather than a literal.
+ */
+export const CHANNEL = process.env.EVOLVER_CHANNEL?.trim() || "announcements1";
+/**
+ * The DA threshold. ZERO — best-effort — because this app's DA group has ONE member.
+ *
+ * The scheduler's own validation states the rule and I had it wrong: at one DA node a
+ * threshold of 1 can never be satisfied, because a node is never its own flood target and
+ * does not self-attest, so a write needing one attestation waits for one that will not come
+ * and ends in `503 da_unavailable`.
+ *
+ * ⚠ And best-effort means what it says: one member is ONE VOLUME. Lose it and every message
+ * that member alone held is unrecoverable — and any future processing node declaring this
+ * channel WEDGES on the first such message, permanently, because apply is forward-only. That
+ * is not hypothetical: it is what happened to `announcements`, and it is why this app is on
+ * `announcements1` (evolver#83). Two members on separate volumes is the answer when the
+ * messages matter.
+ */
+export const DA_THRESHOLD_M = Number(process.env.EVOLVER_DA_THRESHOLD_M?.trim() || 0);
+const utf8 = (s) => new TextEncoder().encode(s);
+/** The channel's terms as a NAMED node sees them — pass the devnet url to ask the chain, or
+ *  this app's node to ask its own cursor. The difference is the point (fact 2). */
+export async function channelTerms(baseUrl, ledgerId = CHANNEL) {
+    try {
+        // A DEADLINE, because a read with no deadline is not a read. Without this the confirm
+        // loop below ran three times past its own 300-second budget on a node that had stopped
+        // answering this route — a hang, reported as nothing at all.
+        const res = await fetch(`${baseUrl}/api/explorer/channels/${encodeURIComponent(ledgerId)}`, { signal: AbortSignal.timeout(10_000) });
+        if (!res.ok)
+            return { ok: false, why: `HTTP ${res.status}` };
+        return { ok: true, terms: (await res.json()) };
+    }
+    catch (e) {
+        return { ok: false, why: e instanceof Error ? e.message : String(e) };
+    }
+}
+/**
+ * The members of a group, or the fact that there is no such group — and those are DIFFERENT
+ * from "could not tell", which is why this returns three things and not two.
+ *
+ * It matters because the caller's next move on a wrong answer is a CreateGroup for a name that
+ * already exists, and that transaction is not merely refused: it is rejected pre-commit and
+ * RETAINED, re-proposed every round until its TTL. See ensureDaGroup.
+ *
+ * `/api/explorer/groups/<g>/members` answers 200 with the member list, or 404 `Unknown group`.
+ */
+export async function groupMembers(baseUrl, group) {
+    try {
+        const res = await fetch(`${baseUrl}/api/explorer/groups/${encodeURIComponent(group)}/members`, { signal: AbortSignal.timeout(10_000) });
+        // A 404 is evidence of absence only if it came from THIS route. A node too old to serve
+        // it answers 404 for the PATH, and reading that as "no such group" is how a CreateGroup
+        // for an existing name gets sent — the very thing this reader exists to prevent.
+        if (res.status === 404) {
+            const body = await res.text().catch(() => "");
+            if (/unknown group/i.test(body))
+                return { known: true, absent: true };
+            return { known: false };
+        }
+        if (!res.ok)
+            return { known: false };
+        const body = (await res.json());
+        return { known: true, members: body.members ?? [] };
+    }
+    catch {
+        return { known: false };
+    }
+}
+/**
+ * This node's OWN on-chain identity, which the app needs because the DA group's member is the
+ * NODE, not the app.
+ *
+ * Read from `/status`, which is an HTML page — the honest state of things: a node reports its
+ * own identity to a human and has no machine-readable equivalent. A JSON status route would
+ * make this a question instead of a parse (see evolver#82, which asks for the same thing about
+ * readiness).
+ */
+export async function nodeSelfId(baseUrl) {
+    try {
+        const res = await fetch(`${baseUrl}/status`, { signal: AbortSignal.timeout(10_000) });
+        if (!res.ok)
+            return null;
+        const m = /<h1>\s*Node:\s*([A-Za-z0-9]+)\s*<\/h1>/.exec(await res.text());
+        return m ? m[1] : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Submit a write and then CONFIRM IT BY READING — the only reliable shape on a node whose
+ * apply this app paces (fact 3).
+ *
+ * `confirm` is a question about committed state, asked of this node, and it is asked only
+ * after pacing the cursor forward: the answer cannot change until the node has applied the
+ * block. Nothing is ever resent.
+ */
+export async function submitAndConfirm(node, stx, label, confirm, say, opts) {
+    const r = opts.da ? await node.submitTxWithDa(stx) : await node.submitTx(stx);
+    if (r.kind === "committed") {
+        say(`   ${label}: committed`);
+        return;
+    }
+    if (r.kind === "failed") {
+        // A duplicate is not a failure of this app: the write is already on the chain, which is
+        // exactly what `confirm` is about to establish.
+        if (r.reason !== "duplicate") {
+            throw new Error(`${label} refused: ${JSON.stringify(r)}`);
+        }
+    }
+    say(`   ${label}: submit returned '${r.kind === "failed" ? r.reason : r.kind}' — confirming by reading (nothing resent)`);
+    // Default five minutes: on a cold node the first writes wait for the ROUTER to drain its
+    // sync backlog before anything is forwarded, and no API reports when that is (evolver#82).
+    const deadline = Date.now() + (opts.deadlineMs ?? 300_000);
+    while (Date.now() < deadline) {
+        // Both legs are wrapped: a failed pace or a failed read is "not yet", never "failed".
+        // The loop's contract is that only the DEADLINE ends it, and a raw throw from either
+        // would have escaped as a fetch error while the transaction was still perfectly fine.
+        try {
+            await opts.pace();
+        }
+        catch { /* transient — try again below */ }
+        try {
+            if (await confirm()) {
+                say(`   ${label}: confirmed on chain`);
+                return;
+            }
+        }
+        catch { /* an unreadable answer is not a confirmation */ }
+        await new Promise((r) => setTimeout(r, 250));
+    }
+    throw new Error(`${label}: not visible on chain within the deadline — outcome UNKNOWN, nothing resent`);
+}
+/**
+ * Create the DA group and put this app's NODE in it.
+ *
+ * Both steps are best-effort and SAY what happened, because neither is the gate: from run two
+ * onward "already exists" is the normal answer, and on a paced node a submit routinely returns
+ * `timeout` and commits anyway. The real gate is the CLAIM below — it cannot succeed unless the
+ * group exists with this node in it, so a silent failure here surfaces there rather than
+ * passing unnoticed.
+ */
+export async function ensureDaGroup(node, baseUrl, owner, signer, group, memberNodeId, say, pace) {
+    say(`   DA group '${group}', member '${memberNodeId}' — the NODE's identity, not the app's`);
+    // READ FIRST, AND SUBMIT ONLY WHAT IS MISSING.
+    //
+    // This used to submit CreateGroup and AddMember unconditionally on every run. A CreateGroup
+    // for a name that already exists is not simply refused: the node ACCEPTS it, then rejects it
+    // PRE-COMMIT every round ("name 'x' taken by group") and RETAINS it, re-proposing until its
+    // TTL. On the live devnet that did two things — three rejection warnings per round in the
+    // leader's log, and, far worse, it kept the tx queue permanently non-empty, which SUPPRESSES
+    // wake-on-work for the whole chain (evolver#85: the wake fires only on the queue's empty →
+    // non-empty edge). Every submitter, ours and everyone else's, then waited up to the
+    // five-minute idle heartbeat — which is also what burned an identity name through
+    // evolver#86. A pointless resubmission is not free, and on a shared chain it is not local.
+    const before = await groupMembers(baseUrl, group);
+    if (before.known && "members" in before && before.members.includes(memberNodeId)) {
+        say(`   group '${group}' exists with '${memberNodeId}' as a member — nothing to submit`);
+        return;
+    }
+    if (!before.known) {
+        throw new Error(`could not read group '${group}' from ${baseUrl} — refusing to guess: ` +
+            `submitting a CreateGroup for a name that already exists poisons the ` +
+            `chain's tx queue (evolver#85), so this needs an answer, not an attempt.`);
+    }
+    const steps = [];
+    if ("absent" in before) {
+        steps.push([`create group '${group}'`, createGroupBody(group),
+            async () => { const g = await groupMembers(baseUrl, group); return g.known && !("absent" in g); }]);
+    }
+    else {
+        say(`   group '${group}' already exists — adding the member only`);
+    }
+    steps.push([`add '${memberNodeId}' to '${group}'`, addMemberBody(group, memberNodeId),
+        async () => {
+            const g = await groupMembers(baseUrl, group);
+            return g.known && "members" in g && g.members.includes(memberNodeId);
+        }]);
+    for (const [label, body, confirm] of steps) {
+        const stx = buildSignedTx({
+            ledgerId: LEDGER.groups, senderNodeId: owner.nodeId, body,
+            ttlRound: BigInt((await node.currentRound()) + 50), signers: [signer],
+        });
+        // Confirmed by READING, like every other write here: a submit that times out has an
+        // unknown outcome, and on a quiescent chain the block is minutes away.
+        await submitAndConfirm(node, stx, label, confirm, say, { pace });
+    }
+}
+/**
+ * `UpdateChannelDaTxBody` (097) — OwnersTxBody variant 4.
+ *
+ * ⚠️ HAND-ROLLED BECAUSE THE SDK DOES NOT HAVE IT. `@mcsherrylabs/evolver-client` exports
+ * `claimBody`, `updateChannelTollBody` and `updateChannelWritePolicyBody` but no DA
+ * equivalent. Taken VERBATIM from evolver-scheduler's provisioner, which needed it first —
+ * copied rather than re-derived, because a second hand-written encoding of the same fields is
+ * a second thing to get wrong. Built from the SDK's own field writers, so only the field
+ * layout is restated: owners.proto (1 ledger_id, 2 da_group, 3 da_threshold_m) and the oneof
+ * tag update_channel_da = 4.
+ *
+ * A BODY, not a signing digest, so Constitution X does not apply — the digest folds
+ * SHA-256(tx_body) as a bytes read. Worth an SDK addition all the same.
+ */
+export function updateChannelDaBody(args) {
+    const parts = [...fString(1, args.ledgerId), ...fString(2, args.daGroup)];
+    if (args.daThresholdM !== 0)
+        parts.push(...fVarint(3, args.daThresholdM));
+    return concat(fMessage(4, concat(parts)));
+}
+/**
+ * Make the channel exist, owned by us, WITH a DA group — the only shape that accepts a
+ * body-form write (fact 4).
+ *
+ * Idempotent, and the three cases are genuinely different: nothing claimed (claim it, carrying
+ * the DA policy), claimed by us with the WRONG DA policy (converge it in place with
+ * `UpdateChannelDa`), claimed by somebody else (stop: that is a real conflict on a shared
+ * chain).
+ */
+export async function ensureChannelWithDa(node, chainUrl, owner, signer, group, say, pace) {
+    const ask = () => channelTerms(chainUrl);
+    const read = await ask();
+    if (!read.ok)
+        throw new Error(`could not read the terms of '${CHANNEL}' from ${chainUrl}: ${read.why}\n` +
+            `  Refusing to guess: an unreadable answer used to mean "unclaimed", and acting on ` +
+            `that submits a Claim for a channel someone else may own — accepted, then rejected ` +
+            `every round until its TTL (evolver#85).`);
+    const terms = read.terms;
+    const ownedByUs = terms.owners.some((o) => o.name === owner.nodeId);
+    const someoneElse = terms.owners.length > 0 && !ownedByUs;
+    // A CHANNEL NAME IS GLOBAL ON A SHARED CHAIN, and whoever claims it owns it. A second
+    // deployment of this app — new identities, same channel name — is therefore a READER, not a
+    // broken installation: it can declare the channel, subscribe, and fold the ordered stream,
+    // which is most of what an announcements channel is for. Only the owner may write (the
+    // default write policy is owner-or-group; 156 lets an owner open it to any writer).
+    //
+    // Dying here instead would be wrong in the ordinary case and would make the name a
+    // first-come landmine.
+    if (someoneElse) {
+        say(`   '${CHANNEL}' is owned by ${terms.owners.map((o) => o.name).join(", ")} — this app will READ it, not write`);
+        return "reader";
+    }
+    // THE POLICY MUST MATCH, not merely exist — and "wrong" includes a threshold this app now
+    // knows is unsatisfiable. A mismatch is converged with `UpdateChannelDa`, in place; a second
+    // Claim would not do it (on an already-claimed ledger a Claim is a committed NO-OP).
+    //
+    // Measured on the deployment: `announcements1` was claimed at m=1 with a single-member
+    // group, this function said "already claimed by us with a DA group — reusing", and the very
+    // next write died with `fetch failed` — the attestation that can never arrive, waited out
+    // until the connection dropped. Checking only for PRESENCE is what let that through twice.
+    const daOk = !!terms.da && terms.da.group === group && terms.da.thresholdM === DA_THRESHOLD_M;
+    if (ownedByUs && daOk) {
+        say(`   '${CHANNEL}' already claimed by us with DA group '${group}' (m=${DA_THRESHOLD_M}) — reusing`);
+        return "owner";
+    }
+    if (ownedByUs && !daOk) {
+        const had = terms.da ? `DA group '${terms.da.group}' (m=${terms.da.thresholdM})` : "NO DA group";
+        say(`   '${CHANNEL}' is claimed by us with ${had}, but this app needs '${group}' (m=${DA_THRESHOLD_M})`);
+        // ⚠️ A TARGETED UPDATE, NOT UNCLAIM-THEN-RECLAIM.
+        //
+        // This used to drop the claim and re-claim, on the belief that a DA policy is set at claim
+        // time and cannot be changed. That belief is wrong — `UpdateChannelDa` (097) exists and is
+        // owner-gated (OwnersLedgerOrchestrator validates it and sets the policy in place) — and
+        // the belief made the app do something irreversible to fix something reversible:
+        // `clearChannelPolicies` drops all three policy rows, and BETWEEN the unclaim and the
+        // re-claim the channel name is UNOWNED, so on a shared chain anyone can claim it and the
+        // name is lost for good. A second Claim would not even have converged it: on an
+        // already-claimed ledger a Claim is a committed NO-OP, which is why the unclaim was there
+        // at all. evolver-scheduler's provisioner had this right first.
+        say(`   converging in place with UpdateChannelDa — an unclaim would expose the name to being taken`);
+        const upd = buildSignedTx({
+            ledgerId: LEDGER.owners, senderNodeId: owner.nodeId,
+            body: updateChannelDaBody({ ledgerId: CHANNEL, daGroup: group, daThresholdM: DA_THRESHOLD_M }),
+            ttlRound: BigInt((await node.currentRound()) + 50), signers: [signer],
+        });
+        await submitAndConfirm(node, upd, `update '${CHANNEL}' DA policy to '${group}' (m=${DA_THRESHOLD_M})`, async () => {
+            const r = await ask();
+            return r.ok && !!r.terms.da && r.terms.da.group === group &&
+                r.terms.da.thresholdM === DA_THRESHOLD_M;
+        }, say, { pace });
+        return "owner";
+    }
+    // Nothing owns it: claim it, carrying the DA policy in the claim itself.
+    const claim = buildSignedTx({
+        ledgerId: LEDGER.owners, senderNodeId: owner.nodeId,
+        body: claimBody({ ledgerId: CHANNEL, daGroup: group, daThresholdM: DA_THRESHOLD_M }),
+        ttlRound: BigInt((await node.currentRound()) + 50), signers: [signer],
+    });
+    await submitAndConfirm(node, claim, `claim '${CHANNEL}' with DA group '${group}' (m=${DA_THRESHOLD_M})`, async () => {
+        const r = await ask();
+        return r.ok && !!r.terms.da && r.terms.da.group === group &&
+            r.terms.da.thresholdM === DA_THRESHOLD_M &&
+            r.terms.owners.some((o) => o.name === owner.nodeId);
+    }, say, { pace });
+    return "owner";
+}
+/** Write one announcement. Plain UTF-8: this channel is public by intent. */
+export async function announce(node, from, signer, text, say) {
+    const stx = buildSignedTx({
+        ledgerId: CHANNEL, senderNodeId: from.nodeId,
+        body: channelBody(utf8(text)), ttlRound: BigInt((await node.currentRound()) + 50), signers: [signer],
+    });
+    // submitTxWithDa: the node collects the channel's DA attestations over the overlay and
+    // assembles the transaction. A client cannot do that for itself — it has no overlay.
+    const r = await node.submitTxWithDa(stx);
+    if (r.kind === "committed") {
+        say(`   announced: "${text}"`);
+        return;
+    }
+    if (r.kind === "timeout") {
+        say(`   announce: submit timed out — the stream below is the confirmation`);
+        return;
+    }
+    // A duplicate is not a failure of this app: the txId is a function of the body, the sender
+    // and the TTL, so an identical announcement that already committed answers `duplicate` —
+    // which means the message IS on the channel, which is exactly what the stream below checks.
+    if (r.kind === "failed" && r.reason === "duplicate") {
+        say(`   announce: this exact message is already on the chain — the stream below is the confirmation`);
+        return;
+    }
+    throw new Error(`the announcement was refused: ${JSON.stringify(r)}\n` +
+        `  insufficient_da means the DA group could not be mustered — is this app's node a member?\n` +
+        `  out-of-band means the channel has no DA group at all (see ensureChannelWithDa).`);
+}
+// The demo reads the shared collector's durable inbox. There is no local handler map,
+// volatile receive buffer, cursor probe or second consumer of the channel route.
+export async function retainedMessages(store, channel) {
+    const messages = [];
+    let after;
+    do {
+        const page = await store.inboxPage(channel, { limit: 100, after });
+        for (const entry of page.entries)
+            if (entry.body !== null)
+                messages.push(new TextDecoder().decode(entry.body));
+        if (!page.more)
+            return messages;
+        if (!page.next || (after && (BigInt(page.next.round) < BigInt(after.round) ||
+            (page.next.round === after.round && BigInt(page.next.index) <= BigInt(after.index)))))
+            throw new Error("inbox readback did not advance its continuation");
+        after = page.next;
+    } while (true);
+}
+/** Pace the processor forward until this node stops making progress — which is how a processing
+ *  node applies blocks at all (fact 2). Anything of ours it passes on the way is KEPT. */
+export async function paceApply(pace, say) {
+    const MAX = 200;
+    // A walk stops at its budget whether or not the cursor reached the tip, so the report
+    // distinguishes the two. Claiming "to its tip" after a truncated walk is a statement the code
+    // cannot make — a backlog longer than MAX leaves apply behind, and the reads that follow would
+    // silently answer as of an earlier round.
+    let walked = 0;
+    let caughtUp = false;
+    for (let attempts = 0; attempts < 10 && walked < MAX; attempts++) {
+        const r = await pace();
+        walked += r.inboxed + r.missed + r.duplicates;
+        if (r.stoppedBecause === "body-pending")
+            throw new Error("node is waiting for a channel body; nothing skipped");
+        if (r.stoppedBecause === "caught-up") {
+            caughtUp = true;
+            break;
+        }
+    }
+    if (!caughtUp)
+        say(`   paced this node's apply, stopping at ${walked} delivery(ies) — the backlog is longer, so apply may still be behind`);
+    else
+        say(`   paced this node's apply to its tip; original deliveries are retained in the inbox`);
+}
+/** Pacing with no narration, for use inside a wait loop. Keeps what it walks past, as above. */
+export async function paceQuietly(pace) {
+    await pace();
+}
+/**
+ * Follow the stream until our own message arrives.
+ *
+ * The delivery is the app's write coming back THROUGH CONSENSUS, which is the only evidence
+ * that matters: a submit says the transaction was ordered; a delivery says the app can read
+ * what was ordered, in order, from its own node.
+ *
+ * A submit that timed out has an UNKNOWN outcome and the block carrying it can be minutes away
+ * on a quiescent chain, so this waits to a DEADLINE rather than for a fixed number of idle polls
+ * (20s of idle was the old bound, and it expired before the block existed). Nothing is ever
+ * resent — the transaction id is fixed, so waiting is the only correct move.
+ */
+export async function readBack(pace, want, say, opts) {
+    // ⚠️ A CALLER THAT CANNOT MATCH MUST PASS ITS OWN DEADLINE. This waits for a specific
+    // message, so with a sentinel that never matches it waits out the whole budget — five
+    // minutes of "following the stream" for the reader-mode caller, which only wants to watch
+    // briefly. That regression arrived with the deadline itself, from changing this function's
+    // contract without revisiting its second call site.
+    const deadline = Date.now() + (opts.deadlineMs ?? 300_000);
+    let received = [...await opts.messages()];
+    while (!received.some((t) => t.includes(want)) && Date.now() < deadline) {
+        // Pending/quiet is an outcome; storage, module and transport failures are errors. Never
+        // disguise one as an empty read or a successful wait. The app's finally releases its owner.
+        const r = await pace();
+        received = [...await opts.messages()];
+        if ((r.stoppedBecause === "caught-up" || r.stoppedBecause === "body-pending") && !received.some(t => t.includes(want)))
+            await new Promise(res => setTimeout(res, 500));
+    }
+    const found = received.some((t) => t.includes(want));
+    say(`   retained ${received.length} message(s) on '${CHANNEL}'`);
+    return { seen: [...received], found };
+}
+// Only the node's body-unavailable outcome permits advancement. No application timer
+// converts pending/unreadable outcomes into absence; the shared collector owns that rule.