@mcsherrylabs/pi-meerkat 0.6.0 → 0.8.0

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

@@ -0,0 +1,425 @@
+// ── THE FOUR STATES, and the one place that knows about them ────────────────
+//
+// An evolver app has TWO independent pieces of state, and each exists PER CHAIN:
+//
+//                        │ chain state                  │ application state
+//   ─────────────────────┼──────────────────────────────┼───────────────────────────
+//   local   (ephemeral)  │ the docker volume node-data  │ state/local/
+//   devnet  (persistent) │ NOT OURS — shared and remote │ state/devnet/
+//   <yours> (persistent) │ NOT OURS — wherever it runs  │ state/<name>/
+//
+// Conflating any two of them is the bug this module exists to prevent. Concretely:
+//
+//   · Resetting the LOCAL CHAIN (`npm run reset`) throws away every identity that
+//     ever existed on it — so the local application state is worthless afterwards and must
+//     go too. The reset does both, together, because doing one is always a mistake.
+//   · Resetting a REMOTE chain is not possible: it is shared, with other people's data on
+//     it. Only the application state can be reset, and doing so ABANDONS the identities it
+//     held — they stay on the chain forever, they are simply no longer ours.
+//   · Two chains must never share a state directory. If they did, one of them would be
+//     handed keys for identities that only exist on the other, and every write would fail in
+//     a way that looks like a bug in the app. That is why the directory is `state/<name>`
+//     and the chain's NAME is part of its identity — not just its URL. Pointing a second
+//     chain at `devnet`'s name was how this used to be done, and it put two chains'
+//     identities in one directory.
+//
+// ── HOW THE CHAIN IS CHOSEN, in order, with no silent step ─────────────────
+//
+//   1. `EVOLVER_CHAIN` (+ `EVOLVER_CHAIN_URL`) — a chain DEFINED by the environment. This is
+//      how a deployment reaches a chain this file has never heard of. The name is free-form
+//      because it becomes a directory name; the URL is REQUIRED for a name that is not
+//      built in, because a chain nobody can locate is not a chain.
+//   2. `EVOLVER_TARGET` — SELECTS a built-in chain by name. An unknown value is an ERROR,
+//      never a fallback: the variable is a deliberate instruction, and quietly running on a
+//      different chain than the one named is the worst outcome available. (It used to fall
+//      through to the default, so `EVOLVER_TARGET=stagng` ran against the throwaway chain
+//      while the operator believed it was on the deploy chain.)
+//   3. `.target` — the file, for interactive work. A file is right there and an environment
+//      variable is not: a variable lives for one command and lies to the next one, while the
+//      whole point is that a session — human or agent — can ask "where am I pointed?" and
+//      get a durable answer. A file holding nonsense is TOLERATED (it falls back to the
+//      default and `npm run status` reports it), because status is the command you are told
+//      to run first when something is wrong.
+//   4. The default, `local` — EXCEPT in a container, where there is no default at all.
+//      A container is a single process whose whole configuration is its environment; if
+//      nothing in it names a chain, that is a deployment that forgot to say, and guessing
+//      means claiming permanent identities on a chain nobody chose.
+//
+// Every rung is reported: `preflight`, `npm run target` and `npm run status` all print the
+// resolved chain AND where the choice came from.
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { basename, dirname, join, resolve } from "node:path";
+/** A chain that cannot be resolved from the environment: an unknown name, a name with no
+ *  URL, or — in a container — nothing naming a chain at all. A distinct type because the
+ *  CALLERS want different things from it: the app must refuse and say why, `status` must
+ *  report it on the line that names it. The same split as `store.StateError`. */
+export class TargetError extends Error {
+}
+// fileURLToPath, NOT url.pathname: pathname is percent-ENCODED, so a checkout under a path
+// containing a space resolves to a "%20" sibling directory — state, including private keys,
+// written outside the project and invisible to `ls`. On Windows pathname also carries a
+// leading slash before the drive letter.
+const moduleRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+// The supported emitted layout is dist/src, while source-only operator scripts use src.
+// Both must resolve the SAME application state, never dist/state on a production upgrade.
+export const ROOT = basename(moduleRoot) === "dist" ? dirname(moduleRoot) : moduleRoot;
+const TARGET_FILE = join(ROOT, ".target");
+// DEVNET, not local — this app's default. A fresh clone with no `.target` file (it is
+// gitignored, so that is what a clone has) and no Docker running still does something real.
+//
+// It applies to INTERACTIVE runs only: a container has no default at all (see the ladder
+// above), so this is not what points a deployment. Two consequences, neither undoable by a
+// switch:
+//   · `npm start` on a clean checkout claims identities on a chain nobody can reset. They
+//     are suffixed per state directory so they never collide, and they are permanent.
+//   · anything that drives the LOCAL chain must NAME it rather than trusting the active
+//     chain — `npm run chain:wait` passes `local`, and docker-compose.yml states
+//     `EVOLVER_TARGET: local`. Before both, the local chain's own readiness check polled
+//     DEVNET and passed while nothing local was up.
+export const DEFAULT_TARGET = "devnet";
+/** A chain name becomes a directory name (`state/<name>`) and appears in every message, so
+ *  it is bounded here rather than trusted. Refusing `..` and separators is the point. */
+export const CHAIN_NAME_RE = /^[a-z0-9][a-z0-9._-]{0,31}$/;
+/** An environment variable, with EMPTY meaning UNSET.
+ *
+ *  `??` is the wrong operator for these. Compose renders a pass-through variable as
+ *  PRESENT-AND-EMPTY rather than omitting it (`EVOLVER_DEVNET_URL: ${EVOLVER_DEVNET_URL:-}`),
+ *  and `process.env.X ?? default` only falls back on undefined — so an empty value WINS and
+ *  the default never applies. That is not hypothetical: `docker-compose.remote.yml` was the
+ *  first caller to pass these through, devnet's url resolved to the empty string, and the
+ *  deployment failed with `chain not ready at  (target 'devnet')`. Every optional variable
+ *  in this project goes through here. */
+export function optionalEnv(k) {
+    const v = process.env[k]?.trim();
+    return v ? v : undefined;
+}
+const env = optionalEnv;
+const BUILTINS = {
+    local: {
+        // The one-node chain from docker-compose.yml. In-container the app reaches it by service
+        // name; on the host, by published port — which is `LOCAL_CHAIN_PORT` if the compose file
+        // was told to publish elsewhere, so ONE variable moves both halves. EVOLVER_NODE
+        // overrides the whole url.
+        nodeUrl: env("EVOLVER_NODE") ?? `http://localhost:${env("LOCAL_CHAIN_PORT") ?? "8440"}`,
+        chainIsEphemeral: true,
+        describe: "ephemeral one-node chain from docker-compose.yml (resettable, plain HTTP)",
+    },
+    devnet: {
+        nodeUrl: env("EVOLVER_DEVNET_URL") ?? "https://devnet.mcsherrylabs.com",
+        chainIsEphemeral: false,
+        describe: "shared remote devnet (chain NOT resettable — other people's data)",
+    },
+};
+const inContainer = () => process.env.EVOLVER_IN_CONTAINER === "1";
+/**
+ * Where a faucet claim goes — `EVOLVER_FAUCET_URL` if set, otherwise the node we talk to.
+ *
+ * SCOPE, and it is deliberately narrow: **claims only, and only at bootstrap.** Every other
+ * request — submits, commit waits, reads — goes to `nodeUrl`, always. An app that routes its
+ * WRITES to a remote endpoint has a permanent non-local dependency, and then owning a node
+ * buys nothing: the chain is still only as reachable as somebody else's API.
+ *
+ * The one structural reason this exists: a faucet claim is SPONSORED BY THE NODE THAT
+ * RECEIVES IT, out of that node's own balance (`sponsorshipCost` + the new identity's 5000),
+ * and only committee members earn block rewards. A follower is given 5000 once and never more,
+ * so it answers
+ *   node_underfunded — Node balance insufficient (need 5100 tokens) to sponsor identity
+ * to every claim, forever. That is a BOOTSTRAP problem — it happens once per identity, before
+ * the app has done anything — and it disappears entirely if somebody funds the follower, after
+ * which this may be left unset and even claims are local.
+ *
+ * WHAT THIS IS NOT FOR, having been measured and then corrected: a freshly synced follower
+ * cannot yet FORWARD a submit — its routing loop was still replaying per-block events at round
+ * 3750 while its chain store was at 4500, so a transfer expired unrouted. That is a TRANSIENT
+ * startup condition and the answer is to WAIT for the node (see `waitUntilNodeCanWrite` in
+ * src/app.ts), not to post somewhere else. Sending writes elsewhere turns one slow minute at
+ * boot into a dependency that never goes away.
+ */
+function faucetFor(nodeUrl) {
+    return env("EVOLVER_FAUCET_URL") ?? nodeUrl;
+}
+function build(name, def, source) {
+    // The guard that would have turned the empty-url failure into a sentence instead of
+    // `chain not ready after 0s at ` — an unreachable-looking message with nothing in it.
+    if (!def.nodeUrl)
+        throw new TargetError(`chain '${name}' has no url. ${name === "devnet" ? "EVOLVER_DEVNET_URL" : name === "local" ? "EVOLVER_NODE" : "EVOLVER_CHAIN_URL"} ` +
+            `is set to an empty value — unset it to use the default, or give it a url.`);
+    return { name, ...def, faucetUrl: faucetFor(def.nodeUrl), stateDir: join(ROOT, "state", name), source };
+}
+/** The chain named by the ENVIRONMENT, or null if the environment names none.
+ *  Throws [[TargetError]] for an environment that names one badly — a deployment's only
+ *  instruction being wrong is not a thing to paper over. */
+function fromEnvironment() {
+    const chain = env("EVOLVER_CHAIN");
+    const url = env("EVOLVER_CHAIN_URL");
+    const pick = env("EVOLVER_TARGET");
+    if (chain) {
+        if (!CHAIN_NAME_RE.test(chain))
+            throw new TargetError(`EVOLVER_CHAIN='${chain}' is not a usable chain name — lower-case letters, digits, ` +
+                `'-', '_' and '.', starting with a letter or digit, at most 32 characters ` +
+                `(it becomes the directory state/<name>)`);
+        const builtin = BUILTINS[chain];
+        if (!builtin && !url)
+            throw new TargetError(`EVOLVER_CHAIN='${chain}' is not a chain this app knows, so EVOLVER_CHAIN_URL must ` +
+                `say where it is. Built-in chains: ${Object.keys(BUILTINS).join(", ")}`);
+        const def = builtin
+            ? { ...builtin, nodeUrl: url ?? builtin.nodeUrl }
+            : {
+                nodeUrl: url,
+                // NOT ephemeral: a chain we were merely pointed at is not ours to throw away, and
+                // that flag decides whether identity names carry a uniqueness suffix and whether
+                // `state:reset` warns that they are abandoned forever. Guessing "ephemeral" would
+                // be the dangerous guess in both places.
+                chainIsEphemeral: false,
+                describe: `chain '${chain}' from EVOLVER_CHAIN_URL (assumed shared — NOT resettable)`,
+            };
+        return build(chain, def, "environment");
+    }
+    if (url)
+        throw new TargetError(`EVOLVER_CHAIN_URL is set but EVOLVER_CHAIN is not — a URL with no chain name has no ` +
+            `state directory to belong to. Set both, or use EVOLVER_TARGET for a built-in chain.`);
+    if (pick) {
+        const builtin = BUILTINS[pick];
+        if (!builtin)
+            throw new TargetError(`EVOLVER_TARGET='${pick}' is not a chain this app knows. Built-in chains: ` +
+                `${Object.keys(BUILTINS).join(", ")}. For any other chain set EVOLVER_CHAIN and ` +
+                `EVOLVER_CHAIN_URL.`);
+        return build(pick, builtin, "environment");
+    }
+    return null;
+}
+/** True for a chain this app can resolve BY NAME ALONE — a built-in, or the one the
+ *  environment defines. Anything else needs `EVOLVER_CHAIN_URL` to say where it is. */
+export function isTargetName(s) {
+    return s in BUILTINS || knownTargets().some((t) => t.name === s);
+}
+/** Every chain this app can name right now: the built-ins, plus the environment's own if it
+ *  defined one that is not built in. What `status` lists and what error messages offer. */
+export function knownTargets() {
+    const builtins = Object.keys(BUILTINS).map((n) => build(n, BUILTINS[n], "default"));
+    let extra = [];
+    try {
+        const e = fromEnvironment();
+        if (e && !(e.name in BUILTINS))
+            extra = [e];
+    }
+    catch { /* a broken environment is reported by currentTarget/inspectTarget, not here */ }
+    return [...builtins, ...extra];
+}
+/** @deprecated name kept for readability at call sites that mean "every chain". */
+export const allTargets = knownTargets;
+/**
+ * THE chain this command is talking to, resolved by the ladder in the header.
+ *
+ * THROWS [[TargetError]] when the ENVIRONMENT is wrong (an unknown name, a missing URL, or
+ * a container with nothing naming a chain). Does NOT throw for an unreadable or nonsense
+ * `.target` FILE — that falls back to the default and is reported by [[inspectTarget]].
+ */
+export function currentTarget() {
+    const fromEnv = fromEnvironment();
+    if (fromEnv)
+        return fromEnv;
+    const fromFile = readTargetFile();
+    if (fromFile.name)
+        return build(fromFile.name, BUILTINS[fromFile.name], "file");
+    if (inContainer())
+        throw new TargetError(`nothing tells this container which chain to use. Set EVOLVER_TARGET to one of ` +
+            `${Object.keys(BUILTINS).join(", ")}, or EVOLVER_CHAIN + EVOLVER_CHAIN_URL for another ` +
+            `chain. There is deliberately no default here: guessing would claim permanent ` +
+            `identities on a chain nobody chose.`);
+    return build(DEFAULT_TARGET, BUILTINS[DEFAULT_TARGET], "default");
+}
+/** The `.target` file, tolerantly: a built-in name, or nothing plus the reason. */
+function readTargetFile() {
+    let raw;
+    try {
+        raw = readFileSync(TARGET_FILE, "utf8").trim();
+    }
+    catch {
+        return {}; // no file yet — the ordinary case
+    }
+    if (!raw)
+        return { problem: `.target is empty` };
+    if (raw in BUILTINS)
+        return { name: raw };
+    return {
+        problem: `.target names '${raw}', which is not a built-in chain ` +
+            `(${Object.keys(BUILTINS).join(", ")}) — using '${DEFAULT_TARGET}'. ` +
+            `Fix it with: npm run target:${DEFAULT_TARGET}`,
+    };
+}
+/** What `status` uses. NEVER throws.
+ *
+ *  `currentTarget` is deliberately strict — a deployment pointed at nothing, or at a chain
+ *  that cannot be located, must stop rather than run somewhere else. But `status` is the
+ *  command you are told to run FIRST when something is wrong, and a first-aid command that
+ *  dies on exactly the misconfiguration it exists to describe is worse than useless. Same
+ *  split as `store.inspect` vs `store.summary`. */
+export function inspectTarget() {
+    try {
+        const t = currentTarget();
+        const f = t.source === "default" ? readTargetFile() : { problem: undefined };
+        return { target: t, problem: f.problem };
+    }
+    catch (e) {
+        if (e instanceof TargetError)
+            return { problem: e.message };
+        throw e;
+    }
+}
+/** Switch the interactive chain. Built-ins only: an arbitrary chain is defined by the
+ *  ENVIRONMENT of the process that talks to it, so writing its name into a file would leave
+ *  a name here with no URL anywhere — a target that resolves to nothing next time. */
+export function setTarget(name) {
+    if (!(name in BUILTINS))
+        throw new TargetError(`'${name}' is not a built-in chain (${Object.keys(BUILTINS).join(", ")}). Another chain ` +
+            `is selected per command with EVOLVER_CHAIN + EVOLVER_CHAIN_URL, not written to .target.`);
+    writeFileSync(TARGET_FILE, name + "\n");
+    return build(name, BUILTINS[name], "file");
+}
+/** A chain BY NAME — a built-in, or the one the environment defined. Throws otherwise: a
+ *  name with no URL cannot be resolved, and inventing one would point the app at a chain
+ *  that does not exist. */
+export function targetByName(name) {
+    if (name in BUILTINS)
+        return build(name, BUILTINS[name], "default");
+    const known = knownTargets().find((t) => t.name === name);
+    if (known)
+        return known;
+    throw new TargetError(`'${name}' is not a chain this app knows (${knownTargets().map((t) => t.name).join(", ")}). ` +
+        `For another chain set EVOLVER_CHAIN=${name} and EVOLVER_CHAIN_URL=<url>.`);
+}
+export function ensureStateDir(t) {
+    mkdirSync(t.stateDir, { recursive: true });
+    return t.stateDir;
+}
+export function stateExists(t) {
+    return existsSync(join(t.stateDir, "identities.json"));
+}
+/** Every state directory that exists on disk, whether or not its chain is nameable now — so
+ *  `status` can show state left behind by a chain the environment is no longer defining, and
+ *  `state:reset` can be pointed at it. Without this, state for `staging` becomes invisible
+ *  the moment EVOLVER_CHAIN is unset, which is exactly when someone goes looking for it. */
+export function stateDirsOnDisk() {
+    const root = join(ROOT, "state");
+    if (!existsSync(root))
+        return [];
+    return readdirSync(root, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name)
+        .sort();
+}
+/** The state directory of a chain named on disk but not resolvable by name — enough to
+ *  REPORT it and to DELETE it, which is all either caller needs. Deliberately carries a
+ *  nodeUrl nothing can reach: reading state needs no chain, and a plausible-looking URL here
+ *  would be an invitation to talk to it. */
+export function orphanTarget(name) {
+    return {
+        name,
+        nodeUrl: "",
+        faucetUrl: "",
+        stateDir: join(ROOT, "state", name),
+        chainIsEphemeral: false,
+        describe: "state on disk for a chain the environment does not currently define",
+        source: "default",
+    };
+}
+// ── 001-announcements-registry ────────────────────────────────────────────────
+//
+// `optionalEnv` and not `??` on purpose: a compose `${X:-}` renders PRESENT-AND-EMPTY, so a
+// default applied with `??` never fires (it cost this app devnet's url once, and a
+// `CHAIN_WAIT_MS` of 0).
+/** The channel the registry drains. Its own knob, NOT `EVOLVER_CHANNEL`: the demo channel and
+ *  the registry channel are different concerns, and pointing the registry at a channel someone
+ *  else's code also drains is the one thing FR-029 forbids. */
+export function registryChannel() {
+    return optionalEnv("REGISTRY_CHANNEL") ?? "ce.meerkat.announcements";
+}
+/** WHO OWNS THE REGISTRY CHANNEL — the identity name, and the only deployment that may CLAIM
+ *  the channel when it is unclaimed.
+ *
+ *  ⚠️ NO DEFAULT, and deliberately not derived from this deployment's own identity. Defaulting
+ *  it to self is exactly the first-boot-wins behaviour this key exists to remove: every
+ *  pi-agent ships a registry, so on a fresh chain the first laptop to start would take
+ *  `ce.meerkat.announcements` permanently. Unset means "this deployment acquires nothing",
+ *  which is the right answer for every deployment but one.
+ *
+ *  Unset does NOT stop a deployment reading a channel somebody else owns — that is the ordinary
+ *  case and needs no configuration. See `decideRegistryRole`. */
+export function registryChannelOperator() {
+    return optionalEnv("REGISTRY_CHANNEL_OPERATOR");
+}
+// ── 004-event-processor-inbox ─────────────────────────────────────────────────
+/** A setting 004 renamed. It is REFUSED, not read: see `processorHttpPort`. */
+export class RenamedSettingError extends Error {
+}
+/**
+ * THE SWITCH BETWEEN THE APP'S TWO SHAPES, and the event processor's read-server port.
+ *
+ * `> 0` is the SERVICE shape: the event processor with the registry module, serving its routes
+ * on this port, until stopped. Unset or `0` is the DEMO shape: the event processor with the demo
+ * module, for as long as the template's steps take. Both shapes have exactly one consumer of
+ * the node's stream — the processor — and both keep what nobody handles in the inbox.
+ *
+ * ⚠️ IT STAYS ONE SWITCH BECAUSE THE NODE READS IT TOO. `node-join.sh` decides from the same
+ * value whether the node subscribes to `REGISTRY_CHANNEL`, and phase M of the command suite
+ * fails the build if the two are keyed on anything else. A second "which modules" setting could
+ * disagree with the node's channel list, and the registry would then index nothing (research R1).
+ *
+ * `0` = no read server, mirroring `https.port`'s convention in the node — the port IS the switch,
+ * so there is no second `enabled` flag.
+ *
+ * ⚠️ `REGISTRY_HTTP_PORT`, its name before 004, is REFUSED whenever it is set — not read, not
+ * aliased. Ignoring it would be worse than either: a registry deployment whose environment still
+ * says `REGISTRY_HTTP_PORT=8090` would start as the template DEMO, drain its node with the wrong
+ * module and serve nothing, and say so nowhere. The refusal names the fix.
+ */
+export function processorHttpPort() {
+    const old = optionalEnv("REGISTRY_HTTP_PORT");
+    if (old !== undefined)
+        throw new RenamedSettingError(`REGISTRY_HTTP_PORT is set (${old}), but it was renamed PROCESSOR_HTTP_PORT and is no longer read.\n` +
+            `  Set PROCESSOR_HTTP_PORT=${old} and remove REGISTRY_HTTP_PORT. Left as it is, this deployment\n` +
+            `  would start as the template demo instead of the registry.`);
+    const port = Number(optionalEnv("PROCESSOR_HTTP_PORT") ?? 0);
+    if (!Number.isSafeInteger(port) || port < 0 || port > 65535)
+        throw new TargetError("invalid PROCESSOR_HTTP_PORT");
+    return port;
+}
+/** The lease ceiling, in ROUNDS, measured from the round an announcement is ordered.
+ *
+ * ⚠️ Rounds, never wall-clock: devnet commits on a ~600 ms floor when busy and a 300-second
+ * idle heartbeat when quiescent, so the same number of rounds is a wildly different amount of
+ * time in each regime. The default is deliberately conservative and T038 replaces it with a
+ * measured value. */
+export function registryMaxLeaseRounds() {
+    return Number(optionalEnv("REGISTRY_MAX_LEASE_ROUNDS") ?? 20_000);
+}
+/**
+ * Where a detail document is fetched from — REQUIRED for `detail` support, and with NO default.
+ *
+ * ⚠️ IT USED TO DEFAULT TO THE NODE'S OWN API AND THAT COULD NEVER WORK. `detail.key` is a
+ * content-cache key, and the content cache is off unless `ce.evolver.content.enabled = true`
+ * (reference.conf:112, default FALSE) — and even when it is on, its route rides either the TLS
+ * peer listener (which presents the node's ~13-minute identity certificate) or a listener bound
+ * to `127.0.0.1` INSIDE the node's container (NodeBootstrap.scala:2081), which a sibling
+ * container cannot reach. So every detail fetch was an HTTP 404 recorded as `unfetchable`, and
+ * the entry told a reader the announcer's documentation was broken when the registry simply had
+ * nowhere to ask.
+ *
+ * Required-with-no-default rather than a guess: the endpoint only has to serve
+ * `GET /content/<key>`, and whatever serves it is UNTRUSTED — the announced sha256 is verified
+ * over the assembled bytes before anything is indexed, which is what makes the source
+ * interchangeable. Unset, a `detail` announcement is still indexed, marked `unfetchable` with
+ * that reason (FR-016).
+ */
+export function registryContentUrl() {
+    const raw = optionalEnv("REGISTRY_CONTENT_URL");
+    return raw && raw.trim().length > 0 ? raw.trim().replace(/\/+$/, "") : null;
+}
+/** Announcer identities whose entries are suppressed (FR-024). Comma-separated. Applied at
+ *  ingest AND at query time, so adding a name takes effect without waiting for a refresh. */
+export function registryDenyList() {
+    const raw = optionalEnv("REGISTRY_DENY_LIST");
+    return new Set((raw ?? "").split(",").map((s) => s.trim()).filter((s) => s.length > 0));
+}

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

@@ -0,0 +1,77 @@
+// Writing an announcement — used by an operator for its own entries, and by the CLI for
+// testing. An ordinary announcer does not need this file; they write to the channel however
+// they like, and `contracts/announcement.md` is the contract.
+//
+// ⚠️ THE OPERATOR MUST ANNOUNCE THROUGH ITS OWN NODE. This file said the exact opposite, and
+// the correction is the difference between "the base instruction document has an availability
+// guarantee" and "it has none".
+//
+// The claim was that the sender can never satisfy the threshold locally, so the operator had to
+// use a foreign gateway. What the node actually does:
+//
+//   `daRequirement` builds the member set with `membersAndOwnerOfTx` — the DA group's members
+//   ∪ ITS OWNER — and this app creates the group, so the app's identity IS in that set. The
+//   gateway therefore computes `required = m - 1 = 0` for the operator, and
+//   `onStartDaCollection` returns the transaction unchanged: nothing stored, nothing flooded,
+//   and `daSatisfied` later passes on zero attestations.
+//
+//   Whichever gateway it went through then stored the body via `channelOriginate` and flooded
+//   it ONCE, best-effort, to `channelDaMembers ∩ connected`. Through a foreign gateway that is
+//   the registry's node — and if the flood is dropped, nothing recovers it: pull targets for
+//   this channel are `{the app's own identity}`, an application and never a connected peer, so
+//   there is no one to ask.
+//
+// Submitted through the registry's OWN node, `channelOriginate` runs there and stores the body
+// LOCALLY before the id-only form is ordered. The registry then holds the body by construction
+// — strictly stronger than collecting an attestation, and with no dependence on a single
+// unacknowledged flood. A THIRD PARTY still uses any node it can reach; that path is unchanged
+// and is the one the threshold protects.
+import { buildSignedTx, channelBody, NodeClient } from "@mcsherrylabs/evolver-client";
+import { deadlineFetch } from "../chainfetch.js";
+export { announcementBody } from "@mcsherrylabs/pi-meerkat/contract";
+import { announcementBody } from "@mcsherrylabs/pi-meerkat/contract";
+/**
+ * Submit an announcement THROUGH A NAMED GATEWAY.
+ *
+ * `gatewayUrl` is required and deliberately has no default, because the right answer differs by
+ * WHO is announcing and neither party should inherit the other's:
+ *
+ *   THE OPERATOR passes its own node. `required` is 0 for it (it owns the DA group), so no
+ *   attestation is collected and the only thing that makes the body available is
+ *   `channelOriginate` storing it on the node it was submitted to. That has to be the node the
+ *   registry reads.
+ *
+ *   A THIRD PARTY passes any node it can reach, and must NOT pass the registry's — that node's
+ *   applied state is paced by the registry's own polling, so a freshly claimed identity's key
+ *   is not yet visible there and the write is refused `unknown_key`.
+ */
+export async function submitAnnouncement(args) {
+    const { channel, gatewayUrl, sender, signer, input, say } = args;
+    // ⚠️ A LONGER DEADLINE THAN AN ORDINARY CHAIN CALL, and for a specific reason: this submit
+    // does not return until the gateway has COLLECTED a DA attestation over the overlay, which
+    // means a round trip to another node plus that node storing the body. The default 30s client
+    // deadline aborted first and reported "internal: The operation was aborted due to timeout" —
+    // a client-side abort dressed as a node failure, which is exactly the wrong thing to tell an
+    // announcer whose transaction may yet commit.
+    const gateway = new NodeClient({
+        baseUrl: gatewayUrl.replace(/\/+$/, ""),
+        fetch: deadlineFetch(Number(process.env.ANNOUNCE_TIMEOUT_MS ?? 120_000)),
+    });
+    // ⚠️ TWO LEDGER IDS, AND THEY ARE DIFFERENT THINGS. The transaction is written to the
+    // announcements CHANNEL; the id inside the body is the channel being DESCRIBED. Getting this
+    // wrong writes the announcement onto the described channel itself, where the registry never
+    // looks — a silence with no error anywhere. Named apart for that reason.
+    const stx = buildSignedTx({
+        ledgerId: channel,
+        senderNodeId: sender.nodeId, body: channelBody(announcementBody(input)),
+        ttlRound: BigInt((await gateway.currentRound()) + 50), signers: [signer],
+    });
+    say(`   announcing '${input.ledgerId}' onto '${channel}' via ${gatewayUrl} (seq ${input.seq})`);
+    const r = await gateway.submitTxWithDa(stx);
+    if (r.kind === "failed" && r.reason === "da_unavailable")
+        say(`   ⚠ da_unavailable — the registry's node did not attest within the gateway's window. ` +
+            `It must hold a live connection to ${gatewayUrl} (research D2: that is what publishing ` +
+            `the p2p port is for). Nothing was ordered. NB: an OPERATOR never sees this — it owns ` +
+            `the DA group, so its own requirement is zero and it submits through its own node.`);
+    return r;
+}

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

@@ -0,0 +1,141 @@
+// The wire shape an announcer writes, and the only place it is trusted enough to become an
+// entry. Pure: no chain, no clock, no I/O — so `test/announcement-checks.ts` can drive it.
+//
+// Bounds are enforced HERE, at ingest, and that is what makes "hundreds of services" a small
+// payload later: the read surface cannot return more than what was allowed in.
+import { registryMaxLeaseRounds } from "../env.js";
+/**
+ * THE BOUNDS COME FROM `@mcsherrylabs/pi-meerkat`, which owns the wire contract.
+ *
+ * ⚠️ RE-EXPORTED, NOT RE-DECLARED. This app is the PARSER and the package is the BUILDER of the
+ * same format, so a bound that differed between them would be a client that cannot announce
+ * something this registry would happily have indexed — or worse, one that announces something
+ * this registry then refuses, which the announcer sees as a successful submit and an entry that
+ * never appears. They are one set of numbers, in the package a client installs.
+ *
+ * Through the `/contract` SUBPATH export, which carries the wire format and nothing else. The
+ * package root would pull in the tools — and with them the vendored chain plumbing — to read a
+ * module that has no imports at all. An external consumer imports exactly the same subpath.
+ */
+export { MAX_BODY_BYTES, MAX_TITLE, MAX_SUMMARY, MAX_KEYWORDS, MAX_KEYWORD, MAX_KIND, MAX_LEDGER_ID, } from "@mcsherrylabs/pi-meerkat/contract";
+import { MAX_BODY_BYTES, MAX_TITLE, MAX_SUMMARY, MAX_KEYWORDS, MAX_KEYWORD, MAX_KIND, MAX_LEDGER_ID, } from "@mcsherrylabs/pi-meerkat/contract";
+const bad = (reason, detail) => ({ ok: false, reason, detail });
+/**
+ * Parse and bound one channel body.
+ *
+ * ⚠️ THE RESULT IS BUILT FIELD BY FIELD, never spread from the input. Whatever else the body
+ * carries is dropped rather than filtered: an `owner` field has no authority (FR-003 — that is
+ * the authenticated sender's alone) and an endpoint has no place in the index (FR-017), and
+ * "dropped by construction" is the only version of that which cannot be forgotten when a
+ * field is added.
+ */
+export function parseAnnouncement(body) {
+    if (body.byteLength > MAX_BODY_BYTES)
+        return bad("oversize", `body is ${body.byteLength} bytes, the limit is ${MAX_BODY_BYTES}`);
+    let raw;
+    try {
+        raw = JSON.parse(new TextDecoder().decode(body));
+    }
+    catch (e) {
+        return bad("malformed", `not JSON: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return bad("malformed", "not a JSON object");
+    const o = raw;
+    // Version first: an unrecognised version means every rule below might be wrong, so it must
+    // not be judged by them.
+    if (o.v !== 1)
+        return bad("unknown-version", `v is ${JSON.stringify(o.v)}, this registry speaks v1`);
+    const str = (k, max, required = true) => {
+        const v = o[k];
+        if (v === undefined || v === null) {
+            if (!required)
+                return "";
+            return bad("malformed", `${k} is missing`);
+        }
+        if (typeof v !== "string")
+            return bad("malformed", `${k} is not a string`);
+        const t = v.trim();
+        if (required && t.length === 0)
+            return bad("malformed", `${k} is empty`);
+        if (t.length > max)
+            return bad("malformed", `${k} is ${t.length} characters, the limit is ${max}`);
+        return t;
+    };
+    const isResult = (x) => typeof x === "object" && x !== null && "ok" in x;
+    const ledgerId = str("ledgerId", MAX_LEDGER_ID);
+    if (isResult(ledgerId))
+        return ledgerId;
+    const title = str("title", MAX_TITLE);
+    if (isResult(title))
+        return title;
+    const summary = str("summary", MAX_SUMMARY);
+    if (isResult(summary))
+        return summary;
+    const kindRaw = str("kind", MAX_KIND);
+    if (isResult(kindRaw))
+        return kindRaw;
+    // `seq` is REQUIRED, and the reason is not tidiness: txId folds the body, so a byte-identical
+    // refresh is refused as a duplicate by the node's replay guard and never reaches the chain
+    // (research A10). Without a changing field an announcer cannot refresh a lease at all.
+    if (typeof o.seq !== "number" || !Number.isSafeInteger(o.seq) || o.seq < 0)
+        return bad("malformed", "seq is missing or not a non-negative integer — a refresh must differ in some byte");
+    const expiry = o.expiresAtRound;
+    if (typeof expiry !== "string" && typeof expiry !== "number")
+        return bad("malformed", "expiresAtRound is missing");
+    let requestedExpiryRound;
+    try {
+        requestedExpiryRound = BigInt(expiry);
+    }
+    catch {
+        return bad("malformed", `expiresAtRound ${JSON.stringify(expiry)} is not an integer`);
+    }
+    if (requestedExpiryRound < 0n)
+        return bad("malformed", "expiresAtRound is negative");
+    const kwRaw = o.keywords ?? [];
+    if (!Array.isArray(kwRaw))
+        return bad("malformed", "keywords is not an array");
+    if (kwRaw.length > MAX_KEYWORDS)
+        return bad("malformed", `keywords has ${kwRaw.length} entries, the limit is ${MAX_KEYWORDS}`);
+    const keywords = [];
+    for (const k of kwRaw) {
+        if (typeof k !== "string")
+            return bad("malformed", "a keyword is not a string");
+        const t = k.trim().toLowerCase();
+        if (t.length === 0)
+            continue;
+        if (t.length > MAX_KEYWORD)
+            return bad("malformed", `a keyword is ${t.length} characters, the limit is ${MAX_KEYWORD}`);
+        if (!keywords.includes(t))
+            keywords.push(t); // de-duplicated, first occurrence wins
+    }
+    // The detail triple is all-or-nothing: the digest is what makes the key checkable, and a key
+    // without one is an unverifiable fetch (research D8).
+    let detail;
+    if (o.detail !== undefined && o.detail !== null) {
+        const d = o.detail;
+        if (typeof d !== "object" || Array.isArray(d))
+            return bad("malformed", "detail is not an object");
+        const dd = d;
+        const key = typeof dd.key === "string" ? dd.key.trim() : "";
+        const sha256 = typeof dd.sha256 === "string" ? dd.sha256.trim().toLowerCase() : "";
+        const bytes = typeof dd.bytes === "string" ? Number(dd.bytes) : dd.bytes;
+        if (key.length === 0 || sha256.length === 0)
+            return bad("malformed", "detail needs both key and sha256 — a key with no digest cannot be verified");
+        if (!/^[0-9a-f]{64}$/.test(sha256))
+            return bad("malformed", "detail.sha256 is not a 64-character hex digest");
+        if (typeof bytes !== "number" || !Number.isSafeInteger(bytes) || bytes <= 0)
+            return bad("malformed", "detail.bytes is missing or not a positive integer");
+        detail = { key, sha256, bytes };
+    }
+    return {
+        ok: true,
+        value: {
+            v: 1, ledgerId, seq: o.seq, requestedExpiryRound,
+            kind: kindRaw.toLowerCase(), title, summary, keywords, ...(detail ? { detail } : {}),
+        },
+    };
+}
+/** The ceiling, read once per process. Here rather than in `lease.ts` so the pure rules take
+ *  their bound as an argument and stay testable without the environment. */
+export const maxLeaseRounds = registryMaxLeaseRounds;