@mcsherrylabs/pi-meerkat 0.7.0 → 0.8.0

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

@@ -0,0 +1,539 @@
+// ── template app: the smallest thing that is really an evolver app ──────────
+//
+// Four steps, in the order you will need them in your own app:
+//
+//   1. PREFLIGHT   is a node there, and is its chain advancing?
+//   2. IDENTITIES  load them from application state, or claim and persist them
+//   3. WRITE       build → sign → submit a transaction, and wait for it to commit
+//   4. VERIFY      read the result back off the chain, never trust the submit
+//
+// AND THEN THREE MORE, which are this app's own and the reason it runs a node of its own:
+//
+//   5. CHANNEL     claim `announcements` — an owned ledger id the quorum orders opaquely
+//   6. ANNOUNCE    write a message onto it
+//   7. STREAM      read that message back off the ORDERED STREAM, through this node
+//
+// Steps 5-7 are SKIPPED, loudly, when the node cannot serve a stream: `/api/channel/next`
+// exists only on a processing node, so a public committee node has none to give. See
+// src/announcements.ts for the three facts about that cursor that shape all of it.
+//
+// RUN IT TWICE. The second run does not re-claim: step 2 finds the identities in this
+// target's application state and reuses them. That is what makes the flow repeatable
+// rather than merely re-runnable — and it is why `state:reset` exists as a separate,
+// deliberate act. See src/env.ts for the four states and how they relate.
+//
+// WHY A TRANSFER IS THE WRITE. Step 3 needs a transaction any identity may send with zero
+// setup. A channel message is the obvious choice and the wrong one here: a channel needs an
+// owner, a write-authorised group, and a DA group to hold the body — and a public devnet
+// retains no channel bodies at all unless it lists that channel in
+// `ce.evolver.subscribed-channels`. A credit transfer is permissionless: a freshly claimed
+// identity is faucet-funded, so it can pay another immediately. Swap this step for whatever
+// your app's real transaction is.
+import { isValidNodeId, NodeClient, transferBody, buildSignedTx, LEDGER, FAUCET_SPONSORED_CREDIT, } from "@mcsherrylabs/evolver-client";
+import { readFileSync } from "node:fs";
+import { currentTarget, stateExists, TargetError, ROOT } from "./env.js";
+// ONE implementation of "what may an identity be called", shared with scripts/rename.mjs.
+import { identityPrefix } from "../scripts/versions.mjs";
+import * as store from "./store.js";
+// The channel this app owns. Everything about the ordered stream — and why it needs a node of
+// its own — lives in that module.
+import { CHANNEL, DA_THRESHOLD_M, ensureChannelWithDa, ensureDaGroup, announce, readBack, retainedMessages, paceApply, paceQuietly, nodeSelfId } from "./announcements.js";
+import { processorHttpPort, registryChannel } from "./env.js";
+import { join } from "node:path";
+import { registryModule, registryReadRoutes } from "./registry/index.js";
+import { meerkatShutdown, startMeerkatProcessor, startMeerkatService } from "./runtime.js";
+import { deadlineFetch, CHAIN_TIMEOUT_MS, validateDaConfig } from "./chainfetch.js";
+const AMOUNT = 10n;
+/** This app's own name, from package.json — never a literal, so a rename cannot leave a
+ *  stale one behind in the output. */
+const APP_NAME = (() => {
+    try {
+        return JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8")).name ?? "app";
+    }
+    catch {
+        return "app";
+    }
+})();
+// Resolving the chain is the first thing a deployment can get wrong, and a TargetError says
+// exactly what is missing — so it is reported as the refusal it is, not as a stack trace out
+// of env.ts. (`die` is defined below; this cannot use it, hence the explicit exit.)
+const target = (() => {
+    try {
+        return currentTarget();
+    }
+    catch (e) {
+        if (e instanceof TargetError) {
+            console.error(`\n✗ ${e.message}\n`);
+            process.exit(1);
+        }
+        throw e;
+    }
+})();
+// TLS verification is left ON. The local chain serves plain HTTP (see docker-compose.yml for
+// why), and the devnet has a real certificate, so nothing needs bypassing — which matters
+// because `NODE_TLS_REJECT_UNAUTHORIZED=0` disables verification PROCESS-WIDE, for every
+// host, not just the node. Set EVOLVER_INSECURE_TLS=1 only if you point a target at a chain
+// serving the node's own short-lived identity certificate.
+if (process.env.EVOLVER_INSECURE_TLS === "1")
+    process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
+// BOUNDED, not bare: a `fetch` with no deadline never returns if the peer never answers, and
+// this app's confirm loops have budgets that a hang makes meaningless. Ported from the
+// scheduler, which had it first — see src/chainfetch.ts.
+const node = new NodeClient({ baseUrl: target.nodeUrl, fetch: deadlineFetch(CHAIN_TIMEOUT_MS) });
+// A SECOND client for the BOOTSTRAP CLAIM ONLY, and only when the faucet is somewhere else.
+// Everything else — submits, commit waits, reads — goes to `node`. The scope is narrow on
+// purpose: see `faucetFor` in src/env.ts. A claim needs a SPONSOR with funds (structural, and
+// a one-time bootstrap step); a submit needs a node that has caught up (transient, and the
+// answer is to wait — `waitUntilNodeCanWrite` below — not to post somewhere else, which would
+// trade one slow minute at boot for a dependency that never goes away).
+const faucet = target.faucetUrl === target.nodeUrl
+    ? node
+    : new NodeClient({ baseUrl: target.faucetUrl, fetch: deadlineFetch(CHAIN_TIMEOUT_MS) });
+const say = (s) => console.log(s);
+// Throw, never exit past the owned worker/listener cleanup in finally.
+const die = (s) => { throw new Error(s); };
+// ── identity naming, and why it differs per target ─────────────────────────
+//
+// LOCAL: the chain is ephemeral, so fixed names are safe AND better — every run of a fresh
+// chain produces the same identities, which is what "deterministic" should mean.
+//
+// DEVNET: the chain is shared and permanent. A fixed name would collide with a previous run
+// (or another developer) and the claim would come back `exists` with keys we do not hold. So
+// devnet names carry a suffix generated once and kept in this target's state, which means
+// they are stable across runs and unique across resets.
+//
+// The prefix is DERIVED FROM THIS APP'S NAME, not a literal. It used to be `tmpl`, which
+// survived `npm run rename` — so an app called anything at all still claimed identities
+// called `tmplA`/`tmplB`, and on a shared chain like devnet that is exactly where the name
+// is the only provenance anyone has.
+const PREFIX = identityPrefix(APP_NAME);
+function nameFor(role) {
+    const letter = role === "sender" ? "A" : "B";
+    if (target.chainIsEphemeral)
+        return `${PREFIX}${letter}`;
+    const suffix = devnetSuffix();
+    return `${PREFIX}${letter}${suffix}`;
+}
+let cachedSuffix = null;
+function devnetSuffix() {
+    if (cachedSuffix)
+        return cachedSuffix;
+    // Derived from an identity already in state if there is one, so a partially completed run
+    // resumes with the SAME names rather than claiming a second pair.
+    for (const { nodeId } of store.summary(target)) {
+        const m = new RegExp(`^${PREFIX}[AB](\\d+)$`).exec(nodeId);
+        if (m)
+            return (cachedSuffix = m[1]);
+    }
+    return (cachedSuffix = String(Date.now()).slice(-6));
+}
+// ── 1. preflight ───────────────────────────────────────────────────────────
+async function preflight() {
+    say(`\n① preflight — chain '${target.name}' → ${target.nodeUrl}   (from the ${target.source})`);
+    say(`   ${target.describe}`);
+    // Never silent: if claims go somewhere other than the node we operate through, that is the
+    // first thing to know when one of them misbehaves.
+    if (target.faucetUrl !== target.nodeUrl)
+        say(`   faucet for the first claim only: ${target.faucetUrl}`);
+    let res;
+    try {
+        res = await deadlineFetch(CHAIN_TIMEOUT_MS)(`${target.nodeUrl}/status`); // NOTE: /status, not /api/status (404)
+    }
+    catch (e) {
+        return die(`cannot reach ${target.nodeUrl}/status — ${e instanceof Error ? e.message : String(e)}\n` +
+            (target.chainIsEphemeral
+                ? `  the local chain is not running: npm run chain:up`
+                : `  is the devnet up, and is EVOLVER_DEVNET_URL right?`));
+    }
+    if (!res.ok)
+        return die(`${target.nodeUrl}/status → HTTP ${res.status} (expected 200)`);
+    say(`   status ok`);
+    let round;
+    try {
+        round = await node.currentRound();
+    }
+    catch (e) {
+        return die(`chain tip unreadable — ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (round === 0)
+        say(`   ⚠ tip is round 0 — a fresh chain that has not committed yet`);
+    else
+        say(`   chain tip round ${round}`);
+    return round;
+}
+// ── 2. identities: load, or claim and persist ──────────────────────────────
+//
+// A faucet claim is node-SPONSORED: the node pays, so the client needs no funds and no
+// permission. What the client must NOT do is sign whatever bytes the node hands back — so
+// the SDK recomputes the proof-of-possession digest locally and refuses to sign if the
+// server's differs. That makes this safe against a node you do not control, and it is the
+// drift alarm: if the node's claim recipe changes you get `digest_mismatch` by name rather
+// than a signature over unknown bytes.
+async function identity(role) {
+    const existing = store.get(target, role);
+    if (existing) {
+        // RECONCILE against the chain rather than trusting state. Persisting before claiming
+        // (below) means state can hold keys for an identity whose claim never committed — a
+        // crash, a transient node error, or a name that was already taken. Without this check
+        // the app happily "reuses" those keys and fails later at the WRITE, reporting
+        // `unknown_key` under a hint about version mismatches: a wrong diagnosis for the one
+        // failure the reader has been trained to expect. Reconciling here is also what makes
+        // persist-before-claim pay off — a half-finished run RESUMES with the same keys.
+        // ⚠️ ASK THE CHAIN, NOT THIS NODE — and the difference is not pedantic, it is a DEADLOCK.
+        //
+        // "Is this name on chain?" is a HAS-THE-CHAIN-AGREED question. A processing node answers
+        // every committed-state read AS OF ITS CURSOR, and that cursor is advanced by whatever
+        // drains /api/channel/next. Historically startup waited here before starting that owner;
+        // services now bind recovery control first and reconcile identities in parent-only setup.
+        // On a node replaying a chain (a fresh volume, a resync, a first join), the old sequence
+        // is: apply walks forward, PAUSES at the first announcement it has no body for, and waits
+        // for a consumer; the consumer is us; we are blocked here asking about an identity that is
+        // applied LATER than that pause point. Neither side can move.
+        //
+        // Observed exactly that way: the node answered `not_found` for an identity devnet showed
+        // holding 5000, this app declared "state/devnet is stale" and exited, and the restart loop
+        // guaranteed the cursor was never drained — so the node could never reach the block that
+        // would have made the answer true.
+        //
+        // The faucet client is the chain-agreed view (it is a quorum node, fully applied, and it is
+        // already trusted for the CLAIM below, so this introduces no new trust). When faucet and
+        // node are the same url `faucet === node` and nothing changes for a single-node target.
+        //
+        // ⚠️ A negative from here is authoritative; a negative from the local node is merely
+        // "not yet". That asymmetry is the whole bug — Constitution III, an undetermined answer is
+        // not a "no".
+        const onChain = await faucet.getIdentity(existing.nodeId);
+        if (onChain !== null) {
+            say(`   ${role}: reusing ${existing.nodeId} from state/${target.name}`);
+            return existing;
+        }
+        say(`   ${role}: ${existing.nodeId} is in state but not on chain — claiming it now`);
+        const retry = await faucet.claimIdentity(existing);
+        if (retry.kind === "committed") {
+            say(`   ${role}: claimed ${existing.nodeId} (block ${retry.blockHeight})`);
+            return existing;
+        }
+        if (retry.kind === "exists") {
+            // The name is taken by keys that are not ours, so this identity is unusable. Say
+            // which one, because the fix differs per target.
+            return die(`'${existing.nodeId}' is on chain with keys this app does not hold.\n` +
+                `  state/${target.name} is stale for '${role}'. npm run state:reset` +
+                (target.chainIsEphemeral ? ` (or npm run reset for chain + state)` : ``));
+        }
+        return die(`re-claim of '${existing.nodeId}' failed: ${retry.error}` +
+            `${retry.message ? ` — ${retry.message}` : ""}`);
+    }
+    const name = nameFor(role);
+    if (!isValidNodeId(name)) {
+        return die(`'${name}' is not a usable identity name — the node requires 1–50 ASCII alphanumeric characters ` +
+            `(letters and digits only: no hyphens, dots or underscores).`);
+    }
+    const id = store.create(target, role, name); // persisted BEFORE the claim, so a claim
+    const r = await faucet.claimIdentity(id); // that commits is never orphaned
+    switch (r.kind) {
+        case "committed":
+            say(`   ${role}: claimed ${name} (block ${r.blockHeight}) → state/${target.name}`);
+            return id;
+        case "exists":
+            // The remedy differs by WHERE this runs. Inside the published image there is no npm
+            // project, so `npm run reset` would be a dead end — the equivalent is discarding both
+            // volumes, which is what `down -v` does.
+            return die(`'${name}' already exists on chain and these keys are not its keys.\n` +
+                (!target.chainIsEphemeral
+                    ? `  this target's state was reset but the name was reused — npm run state:reset, then retry`
+                    : process.env.EVOLVER_IN_CONTAINER === "1"
+                        ? `  the chain outlived the app's state. Discard both together:\n` +
+                            `    docker compose down -v      (or: docker compose -f oci://<ref> down -v)`
+                        : `  the local chain outlived its state: npm run reset  (chain + state together)`));
+        case "failed":
+            if (r.error === "digest_mismatch") {
+                return die(`CLAIM RECIPE DRIFT — ${r.message}\n` +
+                    `  Nothing was signed. The node and @mcsherrylabs/evolver-client disagree on the\n` +
+                    `  proof-of-possession digest, which means their versions do not match.`);
+            }
+            return die(`claim of '${name}' failed: ${r.error}${r.message ? ` — ${r.message}` : ""}`);
+    }
+}
+// ── 3. write ───────────────────────────────────────────────────────────────
+// `signerFor` moved to src/store.ts, beside the identities it signs for — three callers need
+// it now (this app, the registry, the rig's announcer) and a private copy per caller is the
+// duplication Constitution IX exists to prevent.
+const signerFor = store.signerFor;
+async function transfer(from, to, amount, expectAtLeast, pace) {
+    // THE ROUND IS READ HERE, not passed in from preflight.
+    //
+    // A TTL is `currentRound + 50`, so it is only meaningful relative to a CURRENT round — and
+    // anything between preflight and this line can take arbitrarily long: waiting for a joining
+    // node to stop syncing, or a faucet claim on a remote chain. Measured: preflight read round
+    // 850 while the node was still catching up, the claims took the chain to 4628, and the
+    // transfer was refused `ttl_expired` for a TTL of 900 — a transaction dead on arrival,
+    // signed against a round that had passed minutes earlier.
+    const tip = await node.currentRound();
+    const tx = buildSignedTx({
+        // Use the SDK's LEDGER constants, never a literal. A core ledger id that is even
+        // slightly wrong is not a 404: the node reads an unknown id as an APPLICATION channel
+        // and refuses with `malformed_signed_tx … is out-of-band`, which reads like a broken
+        // transaction rather than a mistyped address.
+        ledgerId: LEDGER.identity,
+        senderNodeId: from.nodeId,
+        body: transferBody([{ recipient: to, amount }]),
+        // A real round number, not a far-future constant: the node refuses a TTL more than
+        // `maxTtlOffset` rounds ahead (`TtlTooFar`), so it must come from the current tip.
+        ttlRound: BigInt(tip + 50),
+        signers: [signerFor(from)],
+    });
+    const r = await node.submitTx(tx);
+    if (r.kind === "committed") {
+        say(`   transfer committed: ${from.nodeId} → ${to}, ${amount}`);
+        return;
+    }
+    // AN UNKNOWN OUTCOME IS SETTLED BY LOOKING THE TRANSACTION UP, NEVER BY RESENDING.
+    //
+    // `timeout` does not mean refused — it means the node accepted the transaction and no
+    // commit was observed in the wait window. On a node of your own that has just joined, the
+    // likeliest cause is that it is still draining its routing backlog (which is why
+    // `waitUntilNodeCanWrite` runs before this); on a quiescent chain it can simply be waiting
+    // for the next block. Either way the transaction may still commit, so re-sending is the one
+    // thing not to do: identical bytes are refused as a duplicate (the txId is deterministic and
+    // the node dedupes on it in four states), and a REBUILT transaction has a new TTL, so a new
+    // txId, so it is a SECOND payment.
+    if (r.kind === "timeout") {
+        say(`   submit timed out — outcome UNKNOWN, nothing resent. Resolving by reading the chain.`);
+        // FIVE MINUTES, and the reason is a cold node rather than a slow chain. A freshly joined
+        // node forwards nothing until its ROUTER has drained the per-block events it accumulated
+        // while syncing — thousands of them — and no API reports when that is done (evolver#82).
+        // Measured both ways: on a node up ten minutes the transfer committed in seconds; on a
+        // node minutes old it had not been forwarded after 90 seconds. So the window is generous,
+        // and nothing is resent while it waits: the transaction is already queued and valid until
+        // its TTL.
+        const deadline = Date.now() + 300_000;
+        while (Date.now() < deadline) {
+            // PACING, not sleeping. On a processing node the commit this is waiting for becomes
+            // visible only once the node has APPLIED that block, and it applies only when polled —
+            // by this app. A loop that merely slept would wait out its deadline against a node that
+            // was never going to move, which is exactly what happened before this line existed.
+            if (pace)
+                await paceQuietly(pace);
+            else
+                await new Promise((x) => setTimeout(x, 1000));
+            const now = await node.getIdentity(to);
+            if (now !== null && BigInt(now.balance) >= expectAtLeast) {
+                say(`   transfer committed: ${from.nodeId} → ${to}, ${amount}   (confirmed by reading the chain, not by the submit)`);
+                return;
+            }
+        }
+        return die(`the transfer has not appeared within 90s and its outcome is still UNKNOWN.\n` +
+            `  txId ${r.txIdHex ?? "(unreported)"} — look it up; do NOT resend, that is either a\n` +
+            `  no-op or, once the TTL has passed and the transaction is rebuilt, a second payment.`);
+    }
+    return die(`transfer refused: ${JSON.stringify(r)}\n` +
+        `  invalid_signature here usually means the node and SDK versions differ.\n` +
+        `  others: insufficient_balance · ttl_expired · invalid_identity_body`);
+}
+// ── 4. verify ──────────────────────────────────────────────────────────────
+// Read the chain; do not trust the write. A transfer the sender could no longer fund commits
+// with its instructions ABANDONED, and the charge is chain-wide configuration no client can
+// read — so the balances are the only ground truth for what moved.
+/**
+ * WAIT UNTIL THIS NODE CAN ACTUALLY WRITE — i.e. until it has stopped bulk-syncing.
+ *
+ * Why an app that owns a node still has to wait, and why waiting is the right answer rather
+ * than posting somewhere else: a joining node catches up its CHAIN STORE and its ROUTER
+ * independently. Measured on a 102 follower joining devnet — with the store already at the
+ * tip, the routing loop was still replaying per-block events at round 3750, so a submit was
+ * ACCEPTED and never forwarded, and the only symptom was a commit-wait timeout. Routing the
+ * write to a remote committee node makes that go away by making the node pointless: the app
+ * would then depend on somebody else's endpoint forever, for every write, which is a strictly
+ * worse property than being slow for a minute at boot.
+ *
+ * HOW "still bulk-syncing" is detected WITHOUT asking anything remote: sync and normal
+ * operation move the tip at wildly different rates. Measured: sync persisted ~130 blocks/sec,
+ * while devnet's block cadence is 600ms (~1.7/sec) and its idle heartbeat is 5 minutes. So a
+ * tip advancing by more than a few rounds per half-second is a node still catching up, and one
+ * that is not is a node keeping pace with the chain. That is inference, and it is inference
+ * only because the node has no readiness surface to ask (evolver#82); when it grows one, this
+ * becomes a question instead of a measurement.
+ */
+async function waitUntilNodeCanWrite() {
+    const deadline = Date.now() + 180_000;
+    let last = await node.currentRound();
+    let announced = false;
+    while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 500));
+        const now = await node.currentRound();
+        const advanced = now - last;
+        last = now;
+        // Fewer than 5 rounds in half a second = chain cadence, not bulk sync.
+        if (advanced < 5)
+            return;
+        if (!announced) {
+            say(`   this node is still catching up (round ${now}, +${advanced}/500ms) — waiting`);
+            announced = true;
+        }
+    }
+    die(`this node is still bulk-syncing after 3 minutes (round ${last}).\n` +
+        `  A submit would be accepted and then sit unrouted, so nothing is sent.`);
+}
+async function verify(sender, recipient, before, amount) {
+    const s = await node.getIdentity(sender);
+    const r = await node.getIdentity(recipient);
+    if (s === null)
+        return die(`sender '${sender}' is not on chain`);
+    if (r === null)
+        return die(`recipient '${recipient}' is not on chain`);
+    say(`   ${sender} balance ${s.balance}`);
+    say(`   ${recipient} balance ${r.balance}`);
+    const expected = before + amount;
+    if (BigInt(r.balance) !== expected) {
+        return die(`recipient balance ${r.balance}, expected ${expected} — the transfer did not move what was asked`);
+    }
+    say(`   ✓ recipient received exactly ${amount}`);
+}
+// ── run ────────────────────────────────────────────────────────────────────
+//
+// Wrapped so that unusable application state is REFUSED with the one sentence that fixes it.
+// It used to escape as an unhandled rejection — a stack trace naming a line of store.ts —
+// for the most ordinary mistake there is: switching target with the state directories crossed.
+const shutdown = meerkatShutdown();
+try {
+    const port = processorHttpPort();
+    const service = port > 0;
+    if (service) {
+        // Recovery control is independent of /status, chain wait, identity reconciliation and
+        // provisioning. Name resolution is local only; keys are loaded/claimed lazily in setup.
+        const operator = store.get(target, "sender")?.nodeId ?? nameFor("sender");
+        const module = registryModule({
+            chain: target.name, node, chainUrl: target.nodeUrl, chainAgreedUrl: target.faucetUrl,
+            operator, nodeIdentity: process.env.APP_NODE_ID?.trim() ?? "", say,
+            beforeProvision: waitUntilNodeCanWrite,
+            identity: async () => {
+                const sender = await identity("sender");
+                return { sender, signer: signerFor(sender) };
+            },
+        });
+        const reg = await shutdown.own(() => startMeerkatService({
+            target, node, say, worker: module.worker, lifecycle: module.lifecycle, port,
+            routes: runtime => registryReadRoutes(runtime, async () => String(await node.currentRound())),
+        }), resource => resource.stop());
+        say(`registry service on :${reg.port} — private recovery control available independently of node readiness`);
+        say(`one cursor, one consumer; '${registryChannel()}' follows saved subscriptions (including []).`);
+        await new Promise(() => { });
+    }
+    // The preflight round is REPORTED, not reused: every transaction below reads a fresh one when
+    // it is built (see `transfer`), because a TTL is only meaningful against a current round and
+    // the steps in between can take minutes on a joining node.
+    await preflight();
+    const fresh = !stateExists(target);
+    // ASK FIRST, because it changes what every step below means. `/api/channel/next` exists only
+    // on a PROCESSING node, and on one of those apply is DEFERRED and paced by these polls — so
+    // this app is the only thing that can advance its node, and it must do so BEFORE it writes,
+    // not just before it reads: the node's own submit gate (`identityStore.exists(selfNodeId)`)
+    // reads applied state as well. Measured: with nothing pacing it, a node whose store was level
+    // with devnet answered `Unknown identity` about ITSELF indefinitely.
+    // Processing is an explicit deployment capability, not a destructive cursor probe. A
+    // public/non-processing demo has no fixed binding and never touches the channel route.
+    const processingConfigured = Boolean(process.env.EVOLVER_CHAIN_ID?.trim() || process.env.APP_NODE_ID?.trim());
+    const hasStream = service || processingConfigured;
+    // A demo uses the same shared collector with ZERO modules: original bytes for every channel
+    // stay in its inbox. Its read-back below projects that inbox, never an extra drain or handler.
+    const demo = hasStream && !service
+        ? await shutdown.own(() => startMeerkatProcessor({ target, node, say }), runtime => runtime.stop())
+        : null;
+    if (demo)
+        await paceApply(demo.pace, say);
+    const demoMessages = async () => {
+        if (!demo)
+            return [];
+        return retainedMessages(demo.store, CHANNEL);
+    };
+    say(`\n② identities — application state: state/${target.name}${fresh ? " (empty: will claim)" : " (present: will reuse)"}`);
+    const sender = await identity("sender");
+    const recipient = await identity("recipient");
+    // This is the one-shot demo only. Services branched before preflight or identities.
+    say(`\n③ write — ${sender.nodeId} pays ${recipient.nodeId} ${AMOUNT}`);
+    // Only meaningful when the node is OURS and may still be joining. A public endpoint on a
+    // running chain is caught up by definition, and this returns on its first poll.
+    await waitUntilNodeCanWrite();
+    // Then pace apply, because the node's SUBMIT gate reads applied state too — and read the
+    // recipient's balance AFTER both, so the "before" figure is not one from mid-sync.
+    if (demo)
+        await paceApply(demo.pace, say);
+    const before = BigInt((await node.getIdentity(recipient.nodeId))?.balance ?? FAUCET_SPONSORED_CREDIT);
+    await transfer(sender, recipient.nodeId, AMOUNT, before + AMOUNT, demo?.pace ?? null);
+    say(`\n④ verify — read the result back off the chain`);
+    // Again, and for a different reason: the transfer above is invisible to a read on this node
+    // until the cursor has passed its block.
+    if (demo)
+        await paceApply(demo.pace, say);
+    await verify(sender.nodeId, recipient.nodeId, before, AMOUNT);
+    // ── ⑤–⑦: the channel, when this node can serve one ─────────────────────────
+    if (!hasStream) {
+        say(`\n⑤ channel — SKIPPED: this node serves no ordered stream`);
+        say(`   /api/channel/next exists only on a processing node (ce.evolver.execution.enabled).`);
+        say(`   A public committee node cannot serve one, and the bundled single-node chain IS the`);
+        say(`   committee, so it is not a processing node. Run docker-compose.devnet.yml — a node of`);
+        say(`   this app's own, joined to devnet, with the channel declared — to exercise the rest.`);
+    }
+    else {
+        say(`\n⑤ channel — '${CHANNEL}', owned by this app, with a DA group whose member is this node`);
+        // The DA group's member is the NODE, because the node is what stores and attests a channel
+        // body. The app must therefore learn its node's on-chain name — read from /status, the only
+        // place a node states it (see nodeSelfId).
+        const selfNode = await nodeSelfId(target.nodeUrl);
+        if (!selfNode) {
+            die(`could not read this node's own identity from ${target.nodeUrl}/status — without it the\n` +
+                `  DA group has no member, and a channel with no DA group cannot take a body-form write.`);
+        }
+        // PER DEPLOYMENT, not per app. Derived from the app name alone it is the same string for
+        // every instance — and a group name is GLOBAL on a shared chain, so the second deployment
+        // finds a group owned by the first and can neither add its node nor use it. The sender's
+        // identity already carries the per-deployment suffix, so it is the right root.
+        const daGroup = `${sender.nodeId}da`;
+        // VALIDATED BEFORE ANYTHING IS CLAIMED, with every problem reported at once — the
+        // scheduler's shape, and its rule: at ONE DA node a threshold of 1 can never be satisfied
+        // (a node is never its own flood target and does not self-attest), so this app uses 0.
+        // Checking here rather than discovering it as `503 da_unavailable` on the first write.
+        validateDaConfig({ channel: CHANNEL, daGroup, daNodes: [selfNode], daThresholdM: DA_THRESHOLD_M });
+        const pace = () => paceQuietly(demo.pace);
+        await ensureDaGroup(node, target.nodeUrl, sender, signerFor(sender), daGroup, selfNode, say, pace);
+        const role = await ensureChannelWithDa(node, target.nodeUrl, sender, signerFor(sender), daGroup, say, pace);
+        if (role === "reader") {
+            // Not this app's channel to write to — so what it demonstrates is the half that any
+            // subscriber gets: it declares the channel, follows the ordered stream, and reports what
+            // is on it. Whoever owns the name can open it to other writers (156 write policy).
+            say(`\n⑥ stream — follow '${CHANNEL}' as a subscriber (this app is not its owner)`);
+            const { seen } = await readBack(demo.pace, "\u0000never-matches", say, { deadlineMs: 20_000, messages: demoMessages });
+            say(`   ✓ subscribed and followed the stream (${seen.length} message(s) while watching)`);
+        }
+        else {
+            say(`\n⑥ announce — write a message onto '${CHANNEL}'`);
+            const text = `hello from ${APP_NAME} at round ${await node.currentRound()}`;
+            await announce(node, sender, signerFor(sender), text, say);
+            say(`\n⑦ stream — read it back off the ordered stream, through this node`);
+            // No stored cursor yet: this follows from wherever the node's cursor is, which is why the
+            // announcement above had to be written AFTER pacing. A real app persists its position —
+            // history cannot be replayed (see fact 1 in src/announcements.ts).
+            const { seen, found } = await readBack(demo.pace, text, say, { messages: demoMessages });
+            if (!found) {
+                die(`the announcement did not arrive on the stream.\n` +
+                    `  If the write was accepted, the likeliest cause is that this node does not DECLARE\n` +
+                    `  '${CHANNEL}' in ce.evolver.subscribed-channels: a processing node stores bodies only\n` +
+                    `  for channels it lists, so the body never lands here and can never be delivered.\n` +
+                    `  Seen instead: ${seen.length} message(s).`);
+            }
+            say(`   ✓ the app read its own write back through consensus, from its own node`);
+        }
+    }
+    say(`\n✓ ${APP_NAME} OK — chain '${target.name}', ${target.nodeUrl}${hasStream ? `, channel '${CHANNEL}'` : ""}\n`);
+}
+catch (e) {
+    const message = e instanceof store.StateError
+        ? `${e.message}\n  the application state for '${target.name}' cannot be used.\n` +
+            `  Preserve its identities/keys and repair it explicitly; nothing was reset.`
+        : e instanceof Error ? e.message : String(e);
+    console.error(message);
+    process.exitCode = 1;
+}
+finally {
+    await shutdown.close();
+}

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

@@ -0,0 +1,87 @@
+import { deadlineFetch } from "@mcsherrylabs/evolver-client/processor";
+export { deadlineFetch } from "@mcsherrylabs/evolver-client/processor";
+/**
+ * A `fetch` with a deadline, to be injected into `NodeClient` so EVERY call it makes is
+ * bounded — not only the ones this app writes by hand.
+ *
+ * The failure this closes: a bare `fetch` never returns if the peer never answers, so a
+ * confirm loop with a 300-second budget ran three times past it and reported nothing at all.
+ * A read with no deadline is not a read. Wrapping the client's fetch covers the SDK's own
+ * calls too, which is the difference between fixing two call sites and fixing all of them.
+ *
+ * `AbortSignal.any` rather than replacing the caller's signal: a caller that passes its own
+ * abort still gets it honoured, and gets this deadline as well.
+ */
+// Implementation is shared with the collector; no application-local timeout variant.
+/** How long any single chain call may take before it is abandoned. Generous, because a node
+ *  under load is slow rather than broken; finite, because a node that has stopped answering
+ *  must not stop this app forever. */
+export const CHAIN_TIMEOUT_MS = Number(process.env.EVOLVER_NODE_TIMEOUT_MS?.trim() || 30_000);
+/**
+ * EVERY problem with a configuration, not just the first one.
+ *
+ * The scheduler's shape, and the reason for it: an operator fixing one variable at a time,
+ * with a restart and a chain sync between attempts, pays minutes for each round trip. Say all
+ * of it at once.
+ */
+export class ConfigError extends Error {
+    problems;
+    constructor(problems) {
+        super(`configuration is unusable:\n${problems.map((p) => `  · ${p}`).join("\n")}`);
+        this.problems = problems;
+    }
+}
+/**
+ * Validate the channel/DA configuration BEFORE anything is claimed or written.
+ *
+ * THE RULE THAT MATTERS, and it is the scheduler's, measured there rather than reasoned here:
+ * at ONE DA node, a threshold of 1 can never be satisfied — a node is never its own flood
+ * target and does not self-attest, so a submit that needs one attestation waits for an
+ * attestation that will not come and ends in `503 da_unavailable`. Use 0 (best-effort) with a
+ * single member.
+ *
+ * AND THE COST OF BEST-EFFORT, stated because it is invisible until it bites: at one member a
+ * body lives in ONE volume. Lose it and every message that member alone held is unrecoverable
+ * — and any future processing node that declares the channel WEDGES on the first such message,
+ * permanently, because apply is forward-only (evolver#83). Two members on separate volumes is
+ * the answer when the messages matter.
+ */
+export function validateDaConfig(args) {
+    const problems = [];
+    const say = args.say ?? ((s) => console.log(s));
+    const { channel, daGroup, daNodes, daThresholdM } = args;
+    if (!channel)
+        problems.push("no channel id — there is nothing to claim or read");
+    if (!daGroup)
+        problems.push("no DA group — a channel without one refuses every body-form write");
+    if (daNodes.length === 0)
+        problems.push("the DA group has no members — a body needs a node to hold it, and only a node can attest one");
+    if (daThresholdM > daNodes.length)
+        problems.push(`threshold ${daThresholdM} exceeds the ${daNodes.length} DA node(s) — the chain refuses the claim`);
+    // ⚠️ THERE USED TO BE A RULE HERE REFUSING `1 node, m=1` AS "NEVER SATISFIABLE", AND IT WAS
+    // FALSE. What the gateway computes is
+    //     required = if (daMembers.contains(sender)) m - 1 else m          (NodeBootstrap:1736-1738)
+    // where `daMembers` is the group's members ∪ ITS OWNER (`GroupStore.membersAndOwnerOfTx`). So
+    // satisfiability depends on WHO IS WRITING, which this function cannot see:
+    //
+    //   a THIRD PARTY writing to a one-node group at m=1 needs one attestation and the node is
+    //   there to give it — that is the announcements registry, and it works;
+    //
+    //   THIS APP writing to a group IT OWNS needs `m - 1`, so at m=1 it needs none, and the write
+    //   succeeds while proving nothing about availability.
+    //
+    // The refusal was written after diagnosing a commit-wait timeout on a paced node as a DA
+    // failure, and it is the reason this template's demo channel defaults to m=0. Both m=0 and
+    // m=1 are legitimate here; what an operator needs told is what each one buys.
+    if (daNodes.length === 1 && daThresholdM === 1)
+        say("   note: threshold 1 with a single DA node means a STRANGER's write needs that node's " +
+            "attestation, while this app's OWN write needs none (it owns the group, so its " +
+            "requirement is m-1 = 0) — its bodies are available because they are stored locally at " +
+            "origination, not because anything attested them.");
+    if (problems.length > 0)
+        throw new ConfigError(problems);
+}
+/** A client whose every call is bounded. Use this instead of `new NodeClient({baseUrl})`. */
+export function boundedClient(NodeClientCtor, baseUrl, timeoutMs = CHAIN_TIMEOUT_MS) {
+    return new NodeClientCtor({ baseUrl, fetch: deadlineFetch(timeoutMs) });
+}