@mcsherrylabs/pi-meerkat 0.8.0 → 0.10.1

package/README.md

@@ -5,7 +5,9 @@ Meerkat tools plus every tool dynamically discovered from the private
 `@mcsherrylabs/evolver-mcp@0.15.0` child. The released upstream baseline is 65 tools, so healthy
 discovery currently returns 72. The count is a comparison baseline, not a routing allowlist.
 
-**Version 0.8.0 adds the zero-required-parameter installer.** Version 0.7.0 introduced the
+**Version 0.9.0 makes DevNet the default install target** (`install` installs against the public
+DevNet; `install --local` creates a private local chain). Version 0.8.0 added the
+zero-required-parameter installer (local chain only). Version 0.7.0 introduced the
 facade but required an existing node, registry, identity and key. Version 0.6.0 is the old
 Pi/local-signing package. Always use an exact published version, not npm `latest`.
 
@@ -23,15 +25,34 @@ Prerequisites in the environment where your MCP harness runs:
 ### 1. Install
 
 ```bash
-npx --yes @mcsherrylabs/pi-meerkat@0.8.0 install
+npx --yes @mcsherrylabs/pi-meerkat@0.9.0 install          # public DevNet (default)
+npx --yes @mcsherrylabs/pi-meerkat@0.9.0 install --local  # private local chain
 ```
 
 No identity, key, endpoint, registry, chain ID, channel, port, GID, path, environment variables
-or paid model service is required. This creates an **independent private local chain** and
-starts its owned consensus node, separate processing node and Meerkat registry/content/inbox services. It does **not** join the
-shared devnet, claim from its faucet, inspect unrelated keys, or change another deployment.
-The first install downloads public pinned artifacts and builds three wrapper images, so
-allow time for Docker/npm downloads. Failed preflight/build/readiness exits nonzero with a reason.
+or paid model service is required.
+
+**Default (DevNet)** installs a single non-genesis follower node against the public DevNet, syncing
+its shared chain, and a Meerkat registry that reads and indexes the shared, pinned
+`ce.meerkat.announcements` channel (owned by the pinned `evolvermeerkatA483344` operator). That
+registry runs **read-only**: it never claims, signs or submits with any identity. DevNet catch-up
+syncs from block 0 (~14k blocks at the time of release) and is paced by the registry's own cursor
+drain, so the first install can take a while; it reports progress and fails only if sync stalls.
+
+A DevNet install **permanently claims two DevNet identities**, both funded by the public DevNet
+faucet: its node (`meerkatnode<id>`) and your agent (`meerkatuser<id>`), which signs your
+announcements. Names on DevNet cannot be reused. Re-running install never claims again. DevNet mode
+needs **outbound internet access** from Docker (the node dials DevNet's front nodes, and the faucet
+is reached over HTTPS); it still publishes no host ports.
+
+**`--local`** creates an **independent private local chain** — an owned consensus node, a separate
+processing node, and a Meerkat registry/content/inbox service. The agent's own identity
+(`meerkatuser<id>`) owns the install's private `meerkat.<id>.announcements` channel (claimed once,
+idempotently), and nothing touches DevNet. In either mode the registry claims no identity, and the
+installer never inspects unrelated keys or changes another deployment. The first install downloads public pinned artifacts and
+builds the wrapper images, so allow time for Docker/npm downloads. Failed
+preflight/build/readiness exits nonzero with a reason. Each mode keeps its own state directory
+(`devnet/` or `local/` under your XDG state directory); 0.8.0 state is never touched.
 
 ### 2. Register one server
 
@@ -40,17 +61,20 @@ if you do not already have a registration named `meerkat`, the equivalent comman
 
 ```bash
 claude mcp add --scope user --transport stdio meerkat -- \
-  npx --yes @mcsherrylabs/pi-meerkat@0.8.0 serve
+  npx --yes @mcsherrylabs/pi-meerkat@0.9.0 serve
 ```
 
+Add `--local` after `serve` if you installed with `install --local`.
+
 Do not remove or replace an unrelated `meerkat` registration. Choose a different harness
 registration name for this entry if necessary; its underlying saved deployment remains the same.
 Other MCP clients can add the printed stdio JSON entry directly. Do **not** register an Evolver
 child separately. Restart the harness connection, inspect its tools, and begin with
 `meerkat_summary`, `meerkat_services`, `meerkat_inbox` and `evolver_chain_height`.
 
-`serve` finds the installer's saved state automatically; there is no `--config` or environment
-ceremony. The public package launcher is pinned and survives npm-cache cleanup. Each client
+`serve` finds the installer's saved state automatically (default `devnet`, `--local` for the
+private chain); there is no `--config` or environment ceremony. The public package launcher is
+pinned and survives npm-cache cleanup. Each client
 gets its **own facade and exact Evolver child/session/store** inside the owned runtime container,
 connected through Docker exec stdio. Node/content/registry HTTP stays on the private owned
 Docker network, with **no host-published ports**, so a separate Docker daemon needs neither

package/dist/installer/genesis.devnet.conf

@@ -0,0 +1,92 @@
+# devnet genesis — the committee, plus SEED NODES (170).
+#
+# ⚠️ THIS FILE IS THE CHAIN'S IDENTITY. Its canonical hash is the genesis block id, so any edit
+# here produces a DIFFERENT CHAIN. Every node must hold a byte-identical copy; a node with an
+# older one does not disagree politely, it cannot join at all.
+#
+# ── Why the seed entries exist (170, issue #121) ────────────────────────────────────────────
+# A node starting with an empty volume can only learn a peer's ADDRESS from this file, and can
+# only VERIFY a peer whose key is already in its chain state — which, before it has synced, is
+# also only this file. Both roads lead here. Before 170 this file named one node, the committee,
+# whose `allowed-inbound` is deliberately full, so a newcomer could reach nothing it was able to
+# trust and nothing it was able to trust would accept it. No configuration could fix that.
+#
+# A `quorum-weight = 0` entry is present-and-trusted WITHOUT being on the committee: it is seeded
+# as an identity, its Ed25519 key becomes verifiable, and its address becomes dialable — while
+# `seedGenesis` keeps it out of the quorum store and leader rotation filters it out of the
+# proposer set. That is the whole mechanism; no new key, no new trust path.
+#
+# ⚠️ The two front nodes keep the names they already had. They were NOT in genesis before, so a
+# chain rebuild would have reassigned their names and invalidated every pin across the estate and
+# the published installer. Pinning them here makes the names stable by construction.
+ce.evolver.genesis.nodes = [
+  # ── the committee ──────────────────────────────────────────────────────────────────────────
+  {
+    node-id        = "devnet1-node0"
+    host           = "devnet.mcsherrylabs.com"
+    port           = 7000
+    public-key     = "MCowBQYDK2VwAyEAxTC3mipBz3Ae6nkUzORWLAco21eX3iSSC+QEUSbJMCs="
+    bls-public-key = "rCrpHeLH85ECkow6A58I54fjvtCmOHfdm1llPrish+aD49l32sBciyYAzytRxwak"
+    quorum-weight  = 1000
+  },
+
+  # ── seed nodes: weight 0, so present and trusted but never voting, never leading ───────────
+  #
+  # ⚠️ Keys are the ones these two nodes ALREADY hold, read from their own /status. Their host
+  # secrets are untouched and stay where they are — only the public halves appear here.
+  {
+    node-id        = "evolvermeerkatnode920080"
+    host           = "65.21.255.224"
+    port           = 7100
+    public-key     = "MCowBQYDK2VwAyEAvDNSSDsSYRHfvFCOcl/Fba89VnBrkLzYBy28xqjg8Zg="
+    bls-public-key = "iJZMbE+J+TnNnHpYxk2lQDJipTvvUg0qCQNVJViTfoatqZkqazLCZbUmSP4W26Vj"
+    quorum-weight  = 0
+  },
+  {
+    node-id        = "schednode2"
+    host           = "65.21.255.224"
+    port           = 7200
+    public-key     = "MCowBQYDK2VwAyEAvUOp3fA1nTjv546jme0n14wYDVjHshLL3I7XpQxQ8V4="
+    bls-public-key = "ht3U8qRoQtKIU0NUbuuwx/ni4iF+rcAs2dJgxDOcf+YOs+brlSKSnC2XBFBp1rR1"
+    quorum-weight  = 0
+  },
+
+  # ⚠️ devnet-seed-3 IS NEVER DEPLOYED, ON PURPOSE, AND MUST STAY THAT WAY. A list of seeds is
+  # only worth having if a dead entry is walked past rather than waited on, and a seed that is
+  # permanently absent tests that on every single join instead of on the one afternoon somebody
+  # remembers to stop a live one. Its private key material was generated in a throwaway container
+  # and destroyed with it — nobody can bring this node up, which is the point. `.invalid` is
+  # reserved by RFC 2606 and can never resolve, so the attempt fails fast instead of hanging.
+  # If you are reading this because something reports it unreachable: that is the test passing.
+  {
+    node-id        = "devnet-seed-3"
+    host           = "devnet-seed-3.invalid"
+    port           = 7300
+    public-key     = "MCowBQYDK2VwAyEAHY2onS4+fZss0VZaT84AMcQQugILPagvBm3PFDE5cYY="
+    bls-public-key = "oO91EyEt4jvpP3XuuNiT+6F/9djCjAqgs/+e7eI64eGz9iRCcHT5HY17coLLKfsk"
+    quorum-weight  = 0
+  }
+]
+
+ce.evolver.consensus {
+  # ⚠️ ONE voting node. This is the committee size, not the number of genesis entries — the three
+  # seed entries above carry weight 0 and are not counted (NodeBootstrap derives the consensus
+  # cluster size with the same `quorumWeight > 0` filter the quorum store and leader rotation
+  # already use; before 170 it counted every entry, which would have put the relay threshold
+  # beyond anything a one-member committee could reach).
+  n-nodes                   = 1
+  block-time-ms             = 600
+  round-timeout-ms          = 1500
+  block-reward-tokens       = 10000   # generous dev reward: the faucet (5000/identity) is funded from the FIRST blocks, even under quiescence
+  snapshot-interval-blocks  = 0       # single-node: no snapshot cadence; joiners sync from block 0
+  identity-sponsorship-cost = 100
+
+  # Low idle disk-write: after 3 empty blocks the leader lingers on a 5-MINUTE heartbeat
+  # instead of the 600ms cadence (#31: idle-heartbeat-ms > block-time-ms activates quiescence);
+  # wake-on-work (node-local, always on) still proposes immediately on incoming txs.
+  # CHAIN-WIDE — identical on every node by construction.
+  quiescence {
+    idle-heartbeat-ms       = 300000
+    idle-after-empty-rounds = 3
+  }
+}

package/dist/installer/node-join.sh

@@ -224,5 +224,12 @@ echo "[node-join] pinning ${_peers} as the seed; allowing ${_outbound} outbound
 } > /data/chain/peers.conf
 
 echo "[node-join] launching follower '$NODE_ID' — syncing devnet from block 0"
-exec /opt/evolver/bin/evolver -Dconfig.file=/config/node.conf "$NODE_ID"
+# Only a stale SOCKET left by an unclean previous exit is removed here (this entrypoint
+# runs only while this node JVM is stopped, and this directory is exclusive to this node).
+# Any other entry type is left for the node itself to refuse.
+if [ -S /node-control/node.sock ]; then
+  echo "[node-join] removing stale node-control socket left by an unclean previous exit"
+  rm -f /node-control/node.sock
+fi
+exec /opt/evolver/bin/evolver -Dconfig.file="${EVOLVER_NODE_CONFIG:-/config/node.conf}" "$NODE_ID"
 

package/dist/installer/node.conf

@@ -123,6 +123,9 @@ ce.evolver.consensus {
 # Processing is enabled only by the paired managed composition with its persistent zero-module
 # shared SDK consumer. MCP sessions never drain. Independent remote nodes remain unmanaged.
 ce.evolver.execution.enabled = ${?EVOLVER_EXECUTION_ENABLED}
+# Private node-owned lifecycle capability; only the paired processor receives this volume.
+# No control route is exposed on any TCP listener. 202 is acceptance, not ACTIVE.
+ce.evolver.node-control.socket-path = "/node-control/node.sock"
 # Shared SDK controller is the SOLE writer; node sees the whole config-only directory read-only.
 # Ordinary boot/upgrade cannot merge defaults, resurrect removals or seed a lost declaration.
 include required(file("/subscriptions/channels.conf"))

package/dist/installer/node.devnet.conf

@@ -0,0 +1,238 @@
+# This node: a NON-GENESIS FOLLOWER on devnet. Chain-wide params come from the genesis
+# spec — never set them here, they must stay byte-identical on every node. Only
+# node-local knobs below.
+include file("/config/genesis.devnet.conf")
+
+# 089 chain-spec pin: the canonical hash of the genesis file IS the genesis block id.
+# Any drift refuses to boot rather than forking quietly.
+ce.evolver.genesis-file = "/config/genesis.devnet.conf"
+
+# This node's OWN identity, from the first-boot faucet claim (node-join.sh). REQUIRED
+# substitutions (no `?`): a node booting with missing keys must fail fast, not later and
+# obscurely at the first TLS handshake.
+ce.evolver.node {
+  private-key = ${EVOLVER_PRIVATE_KEY}      # Ed25519 PKCS#8 base64
+  public-key  = ${EVOLVER_NODE_PUBLIC_KEY}  # Ed25519 X.509 base64
+  bls-secret  = ${EVOLVER_BLS_SEED}         # BLS IKM base64
+  port        = ${EVOLVER_NODE_PORT}        # p2p transport (raw TCP, mTLS)
+}
+
+evolver.peer-discovery {
+  # THIS NODE ADVERTISES NOTHING, AND MUST NOT. `preferred-url` is the address this node
+  # gossips as its OWN (`""` = feature off), and a joined app node behind Docker HAS no
+  # routable p2p address: its 7000 is container-local and deliberately unpublished. So
+  # advertising one means every node on the chain records `<us> -> https://127.0.0.1:7000`
+  # and then dials its own loopback.
+  #
+  # Observed on devnet, and it is worse than noise: this node CONNECTED TO ITSELF, logged
+  # `Peer connected: <self>`, sent its own SyncManager `BlockRangeRequest(4841,4845)`, and
+  # TipGossip then reported `rotating to <self> (failed=devnet1-node0)` followed by
+  # `stalled (upstream=none)`. After that its submits were never forwarded and every write
+  # timed out. The table also keeps the dead: `evolvertemplateappnode965813 at
+  # 127.0.0.1:7000` from an earlier deployment was still being dialled hours later.
+  # ADVERTISED AGAIN, and ⚠️ ONLY BECAUSE IT IS NOW REAL. This was `""` because the node
+  # had been advertising `https://127.0.0.1:7000`: every peer that read the discovery
+  # table dialled its OWN loopback, so this node connected to itself, sent its own
+  # SyncManager block requests, reported `candidates=<self>` / `stalled (upstream=none)`
+  # and stopped forwarding submits. An unroutable value reinstates that exactly — which
+  # is why `EVOLVER_TRANSPORT_ADDRESS` is REQUIRED here rather than defaulted, and why the
+  # command suite refuses a loopback value.
+  # ⚠️ EMPTY, DELIBERATELY. This node is a READER behind NAT: it has no routable p2p address.
+  # Advertising one is not merely useless, it is harmful — devnet recorded a node that advertised
+  # an unroutable address CONNECTING TO ITSELF, sending its own sync requests, reporting
+  # `stalled (upstream=none)`, and leaving dead entries other nodes dialled for hours.
+  #
+  # It costs this node nothing: advertising is how others DIAL YOU, and nothing needs to. Writing
+  # still works — this node dials OUT, discovers the network, learns its distance to the committee
+  # and forwards transactions along that path. Being undialable only stops bodies being flooded TO
+  # it, which is a DA member's concern and not a reader's.
+  transport-address       = ""
+  peer-url                = ""
+  gossip-interval-seconds = 60
+
+  # 16 INBOUND, not 0. The 141 leaf recipe (`in=0`) is right for an app node that only
+  # talks upstream — and wrong here: the registry's channel requires announcers' nodes to
+  # reach THIS node so their flooded bodies can be attested (research D2). Each announcer
+  # holds one inbound slot, so 16 is the number of concurrent announcer nodes supported.
+  # Generous on both sides so DISCOVERY actually happens. The seed below is pinned so the node
+  # always has a way back to the chain, but `allowed-outbound` is deliberately LARGER than the
+  # pinned list — the pin is strict only while the two are equal, and a strict pin here would mean
+  # this node never dials anything it discovers.
+  allowed-inbound         = 16
+  # `allowed-outbound` and `preferred-peers` are DELIBERATELY ABSENT HERE — node-join.sh renders
+  # both into peers.conf so the two cannot drift apart in two files.
+  #
+  # ⚠️ THIS COMMENT USED TO CLAIM THE PIN IS STRICT. It is NOT, and the difference matters to
+  # anyone reasoning about what this node will dial. It said `|preferred| == allowed-outbound`
+  # holds "by construction"; node-join.sh renders ONE pinned seed and an outbound budget of 16,
+  # so 1 != 16 and the pin is deliberately LOOSE. That is the intended design — a follower has to
+  # dial what it discovers or it is a leaf — but the old wording described the opposite property
+  # and named the incidents (a dead address from a torn-down deployment still being dialled, this
+  # node dialling its own loopback) that a strict pin was supposed to prevent. Those are the COST
+  # of the loose pin, not evidence against it: the seed guarantees a way back to the chain, and
+  # discovery does the rest. Which is what keeps a shared chain's discovery table out of the
+  # dial queue — it keeps the dead (an address from a torn-down deployment was still
+  # being dialled hours later) and once made this node dial its own loopback. Raising
+  # the budget without naming a peer would silently unpin it; naming a peer without
+  # raising the budget could never reach it. One list, both keys, no drift.
+  #
+  # ⚠️ THIS USED TO BE `out=1`, copied verbatim from the 141 LEAF recipe, and it decided
+  # WHICH CHANNELS THIS NODE COULD READ — silently. `ChannelOverlay.peers(ledgerId)` is
+  # the channel's DA group ∩ connected, so with the one slot spent on the upstream every
+  # channel whose DA member is somebody else resolved to an EMPTY pull set: the node
+  # records the miss, sends no request, and says so at DEBUG only (evolver#89). A node
+  # reading a channel it does not itself serve needs the upstream AND one reachable DA
+  # member per such channel, so a fixed 1 is only ever right for a node that reads
+  # nothing but its own.
+}
+
+ce.evolver.consensus {
+  validate-chain-on-startup = false
+  wake-on-work { forward-watermark = 16 }
+}
+
+# PROCESSING MODE — off by default, and THE REASON THIS DEPLOYMENT EXISTS once your app
+# reads a channel.
+#
+# `/api/channel/next` is a SINGLE-CONSUMER, FORWARD-ONLY cursor: two readers do not
+# error, they silently split the stream and the message is unrecoverable. So an app that
+# consumes an ordered channel must drain a node NOBODY ELSE drains — which means a node
+# of its own. It cannot share a public one, and a single-node chain (devnet today) IS the
+# committee, so that node is not a processing node and serves no stream at all.
+#
+# And the committee's node must never be put in this mode: processing mode DEFERS apply
+# and paces it from the app's polling, so a committee node in processing mode would
+# couple consensus progress to an HTTP poller. Ordering is its job; give the app its own.
+#
+# Turning it on changes what committed reads MEAN here — they answer "as of MY cursor".
+# Measured in this family (evolver-scheduler): right after a successful faucet claim a
+# quorum node reported `{"balance":5000}` for an identity while a processing node
+# reported `{"error":"not_found"}` for the same one. An app in that mode needs to know
+# which of its questions are "has the chain agreed?" (ask a quorum node) and which are
+# "what have I processed?" (ask this one).
+#
+# ON, because this app owns a channel (`announcements`) and reads its ordered stream —
+# steps 5-7 of src/app.ts. BOTH lines are needed and neither works alone: a node in
+# processing mode with no channels declared has nothing to offer, and a node that
+# declares channels without execution stores bodies it never streams.
+#
+# The channel must be named HERE as well as claimed on chain. A processing node stores
+# bodies only for the channels it lists, so an undeclared channel's message is applied
+# in the slice and never offered — the write looks fine and the stream stays silent,
+# which is the failure the app's step 7 names explicitly.
+# Processing is enabled only by the paired managed composition with its persistent zero-module
+# shared SDK consumer. MCP sessions never drain. Independent remote nodes remain unmanaged.
+ce.evolver.execution.enabled = ${?EVOLVER_EXECUTION_ENABLED}
+# Private node-owned lifecycle capability; only the paired processor receives this volume.
+# No control route is exposed on any TCP listener. 202 is acceptance, not ACTIVE.
+ce.evolver.node-control.socket-path = "/node-control/node.sock"
+# Shared SDK controller is the SOLE writer; node sees the whole config-only directory read-only.
+# Ordinary boot/upgrade cannot merge defaults, resurrect removals or seed a lost declaration.
+include required(file("/subscriptions/channels.conf"))
+# `required` for the same reason: an absent optional include is IGNORED, and a node
+# that silently fell back to the 64/64 defaults would dial the discovery table.
+include required(file("/data/chain/peers.conf"))
+
+# ── THE LOCAL ROUTES THIS DEPLOYMENT OPENS TO ITS OWN CONTAINERS ────────────
+#
+# The agent and the registry run BESIDE this node, each in its own container on this compose
+# project's network. These routes carry no token and no client certificate — reaching the address
+# IS the authorization — so the node binds them to loopback unless told otherwise, and loopback
+# inside this container is reachable by nothing else in the stack.
+#
+# `bind-host = 0.0.0.0` here means: THIS COMPOSE NETWORK IS THE BOUNDARY. That claim holds only
+# because none of these ports appear under `ports:` in docker-compose.yml and the stack does not
+# use host networking. Publish one, or run with `--network host`, and the claim is simply false.
+#
+# ⚠️ `ce.evolver.login` is deliberately NOT here and cannot be: that route signs as any identity
+# this host holds a signer for, which on this node is the node's own. Setting `bind-host` under
+# that namespace fails the boot rather than being ignored.
+
+# 145 — the agent sends and drains application messages. `/api/p2p/send` relays a message the
+# agent signed ITSELF (its own identity, verified at the far end); `/api/p2p/sign-and-send` makes
+# this node sign as itself. One listener, so opening it grants both.
+ce.evolver.p2p {
+  http-port = 8460
+  bind-host = "0.0.0.0"
+}
+
+# 158 — the agent may ASK an enrolled phone to authorise a transaction. It cannot sign: the device
+# holder approves every one, and that gate does not move when the bind does. Inert until a
+# `mobile-signer` block exists, and the node says so at boot rather than failing.
+ce.evolver.mobile {
+  http-port = 8470
+  bind-host = "0.0.0.0"
+}
+
+# 139 — CONTENT, so the agent can publish a document and the registry can read one back.
+#
+# `POST /content` writes to this node's own store, keyed by the bytes' own digest, and talks to
+# no peer at all (FR-006). `bind-host` below is what lets the agent and the registry reach that
+# route from their own containers. Fetching a document another node holds is the part that uses
+# the overlay, and that is what the TLS listener underneath is for.
+ce.evolver.content {
+  enabled   = true
+  http-port = 8450
+  bind-host = "0.0.0.0"
+}
+
+data.base       = "/data/chain"
+state.snapshots = "snapshots"
+# BOTH LISTENERS, and the pair is the point.
+#
+# 8440 PLAIN is what the agent and the registry talk to. They are ordinary HTTP clients in their
+# own containers, and the alternative is not "use TLS" — this node's HTTPS listener presents its
+# own IDENTITY certificate, self-signed, CN=<nodeId>, ~13 minutes old. It rotates, so it cannot
+# be pinned as a CA, so a client that verifies it must turn verification off process-wide. For
+# the agent that would also stop it verifying GoToSocial, which is not a trade worth making for
+# a hop between two containers on one network.
+#
+# 8441 TLS is what PEERS use, and it exists so `ce.evolver.content` above can: the content peer
+# route identifies its requester by client certificate, and refuses to start without somewhere
+# mTLS to live. NOT PUBLISHED in docker-compose.yml — this node is a reader behind NAT that
+# fetches outbound and serves nobody, so nothing needs to dial it.
+#
+# ⚠️ IF THIS NODE EVER SERVES CONTENT, `evolver.peer-discovery.api-url` must name 8441 and that
+# port must be publicly reachable. It is empty here (see above): a node with no routable address
+# advertises nothing and can only fetch.
+http.port       = 8440
+# Only this private Compose network may reach the unsigned processing API.
+http.bind-host  = "0.0.0.0"
+# ⚠️ REQUIRED SINCE 131 (#131), and without it this stack breaks. `http.bind-host` now defaults
+# to 127.0.0.1 — the plain listener joined the bind-is-authorization set the four local listeners
+# above already belong to, because it carries the whole API with no token and no client
+# certificate, including (this node runs `ce.evolver.execution.enabled`) the SINGLE-CONSUMER
+# cursor `GET /api/channel/next`, which a stranger can step past the registry's own deliveries.
+#
+# The claim being made here is the same one `ce.evolver.content.bind-host` and the p2p/login ones
+# above make: THIS COMPOSE NETWORK IS THE BOUNDARY. It holds because 8440 is NOT published in
+# docker-compose.yml and nothing uses host networking — the agent and the registry reach this
+# node as `node:8440`, a service name on that network. Publish the port, or run with host
+# networking, and the claim stops being true. The node cannot tell, so it logs a WARN naming it.
+http.bind-host  = "0.0.0.0"
+https.port      = 8441
+evolver.grpc.port = 9000
+
+# REQUIRED, and there is no default: `NodeBootstrap.initChainDb` reads this block
+# directly, so a node without it dies with `No configuration setting found for key
+# 'chainDb'` after the migrations have already run — which is exactly how this omission
+# was found. Same values as the bundled deployment's node.
+chainDb {
+  datasource {
+    driver                    = "org.hsqldb.jdbc.JDBCDriver"
+    user                      = "sa"
+    pass                      = ""
+    maxPoolSize               = 5
+    connectionProperties      = ""
+    cachePrepStmts            = true
+    prepStmtCacheSize         = 250
+    prepStmtCacheSqlLimit     = 2048
+    connectionTimeout         = 5000
+    useServerPrepStmts        = false
+    transactionIsolationLevel = "TRANSACTION_READ_COMMITTED"
+  }
+  viewCachesSize  = 50
+  useShutdownHook = false
+  freeBlobsEarly  = false
+}
+

package/dist/installer/runtime.json

@@ -1 +1 @@
-{"operatorIdentity":"evolvermeerkatA","sdk":"0.22.1","bootstrap":"0.15.0"}
+{"operatorIdentity":"evolvermeerkatA","devnet":{"origin":"https://devnet.mcsherrylabs.com","chainId":"c8925985ae7948d2e608efcf863928d15476c4b561ad773fdca6f0d53d4fea05","channel":"ce.meerkat.announcements","operator":"evolvermeerkatA483344","upstreamNodeId":"evolvermeerkatnode920080","daPeers":"schednode2","allowedOutbound":"2","genesisSha256":"7f6a95cd0fcbe2306d89b2426a9473b1c6537427a82feaffff4783d9cc5dc6b9"},"sdk":"0.23.0","bootstrap":"0.16.0"}

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

@@ -38,7 +38,7 @@ 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 { processorHttpPort, registryChannel, registryChannelOperator, registryReadOnly } from "./env.js";
 import { join } from "node:path";
 import { registryModule, registryReadRoutes } from "./registry/index.js";
 import { meerkatShutdown, startMeerkatProcessor, startMeerkatService } from "./runtime.js";
@@ -401,12 +401,25 @@ try {
     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 readOnly = registryReadOnly();
+        // READ-ONLY: the installer's registry never claims or signs with any identity. The operator is
+        // the PINNED channel operator; no sender identity is ever loaded or claimed, so the identity()
+        // claim path is never reached in this mode. A read-only registry without a valid pinned operator
+        // has nobody to trust the channel's terms to, so it refuses at startup rather than proceeding
+        // owner-less.
+        const pinnedOperator = registryChannelOperator();
+        if (readOnly && !pinnedOperator)
+            throw new Error("REGISTRY_READ_ONLY=1 requires a valid REGISTRY_CHANNEL_OPERATOR naming the identity " +
+                "that owns the index channel; the installer's rendered compose always sets both.");
+        const operator = readOnly ? pinnedOperator : 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,
+            readOnly,
             beforeProvision: waitUntilNodeCanWrite,
             identity: async () => {
+                if (readOnly)
+                    throw new Error("read-only registry must never claim or sign with any identity");
                 const sender = await identity("sender");
                 return { sender, signer: signerFor(sender) };
             },

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

@@ -350,6 +350,18 @@ export function registryChannel() {
 export function registryChannelOperator() {
     return optionalEnv("REGISTRY_CHANNEL_OPERATOR");
 }
+/**
+ * Opt-in READ-ONLY registry mode (the installer always sets this; the published app image and the
+ * real-estate operator deployment must NOT).
+ *
+ * In this mode the registry never claims or signs with any identity, submits nothing, and its role
+ * decision can never yield `owner`. Owned+open+operator-matches reads back `reader`; an unclaimed
+ * channel drains nothing and `wait`s; an owner different from the pinned operator or a non-open
+ * write policy is `unusable`. Without this flag the existing owner path is byte-for-byte unchanged.
+ */
+export function registryReadOnly() {
+    return optionalEnv("REGISTRY_READ_ONLY") === "1";
+}
 // ── 004-event-processor-inbox ─────────────────────────────────────────────────
 /** A setting 004 renamed. It is REFUSED, not read: see `processorHttpPort`. */
 export class RenamedSettingError extends Error {

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

@@ -2,7 +2,7 @@
 // the SDK. Signing keys and chain provisioning remain in this parent, never worker options.
 import { isValidNodeId } from "@mcsherrylabs/evolver-client";
 import { registryChannel, registryChannelOperator, registryContentUrl, registryDenyList, registryMaxLeaseRounds, } from "../env.js";
-import { provisionRegistryChannel } from "./provision.js";
+import { provisionRegistryChannel, provisionRegistryChannelReadOnly } from "./provision.js";
 import { REGISTRY_MODULE_NAME } from "./worker-module.js";
 export function registryModule(args) {
     if (!isValidNodeId(args.operator))
@@ -13,6 +13,7 @@ export function registryModule(args) {
         maxLeaseRounds: registryMaxLeaseRounds(), deny: [...registryDenyList()],
         chainUrl: args.chainUrl, contentUrl: registryContentUrl(),
     };
+    const pinnedOperator = registryChannelOperator();
     return {
         // Production starts emitted JS. No tsx worker remapping, test factory or remote discovery.
         worker: { url: new URL("./worker-module.js", import.meta.url).href, options },
@@ -20,13 +21,21 @@ export function registryModule(args) {
             name: REGISTRY_MODULE_NAME, channels: [channel],
             async setup(context) {
                 await args.beforeProvision?.();
+                if (args.readOnly) {
+                    const provisioned = await provisionRegistryChannelReadOnly({
+                        chainAgreedUrl: args.chainAgreedUrl, channel, nodeIdentity: args.nodeIdentity,
+                        say: args.say, operator: pinnedOperator ?? args.operator,
+                    });
+                    args.say(`   registry ${provisioned.role}: ${channel}`);
+                    return;
+                }
                 const { sender, signer } = await args.identity();
                 if (sender.nodeId !== args.operator)
                     throw new Error("registry signing identity differs from fixed worker operator");
                 const provisioned = await provisionRegistryChannel({
                     node: args.node, chainUrl: args.chainUrl, chainAgreedUrl: args.chainAgreedUrl,
                     channel, owner: sender, signer, nodeIdentity: args.nodeIdentity,
-                    say: args.say, operator: registryChannelOperator(),
+                    say: args.say, operator: pinnedOperator,
                     pace: async () => { await context.pace(); },
                 });
                 args.say(`   registry ${provisioned.role}: ${channel}`);

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

@@ -29,7 +29,28 @@
 import { buildSignedTx, claimBody, updateChannelWritePolicyBody, LEDGER } from "@mcsherrylabs/evolver-client";
 import { channelTerms, submitAndConfirm, updateChannelDaBody, } from "../announcements.js";
 export function decideRegistryRole(args) {
-    const { terms, self, operator } = args;
+    const { terms, self, operator, readOnly } = args;
+    // READ-ONLY: the installer's registry never claims or signs with any identity. `self` is the
+    // PINNED operator name, not this deployment's (nonexistent) identity, and it must NEVER yield
+    // `owner` — a read-only indexer submitting a Claim for a channel someone else owns poisons the
+    // chain's tx queue (evolver#85). Decision folds entirely onto the pinned operator.
+    if (readOnly) {
+        if (terms.owners.length === 0) {
+            return { kind: "waiting", why: `'${terms.ledgerId}' is UNCLAIMED and this read-only registry will not claim it (owned ` +
+                    `by '${operator ?? "(no operator pinned)"}', not by this deployment). Draining the cursor ` +
+                    `and indexing nothing until the operator provisions it.` };
+        }
+        const holder = terms.owners.map((o) => o.name).join(", ");
+        if (operator && !terms.owners.some((o) => o.name === operator))
+            return { kind: "unusable", why: `'${terms.ledgerId}' is owned by ${holder}, but REGISTRY_CHANNEL_OPERATOR pins ` +
+                    `'${operator}'. Either the operator changed — update the pin — or this name was taken by ` +
+                    `somebody else. Refusing to index a channel whose terms are set by a party this deployment ` +
+                    `was not told to trust.` };
+        if (terms.writePolicy !== "open")
+            return { kind: "unusable", why: `'${terms.ledgerId}' is owned by ${holder} and its write policy is ` +
+                    `'${terms.writePolicy}', not 'open'. Every announcement would be a permanent miss.` };
+        return { kind: "reader", holder };
+    }
     // ALREADY OURS — see "keeping is not acquiring" above. Note this is the IDENTITY name,
     // matching what the claim/converge path below can actually sign for: a channel owned by a
     // group we happen to belong to is deliberately NOT treated as ours, because this app holds
@@ -178,3 +199,27 @@ export async function provisionRegistryChannel(args) {
         say(`   '${channel}' already has the terms this registry needs — nothing to submit`);
     return { role: "owner", channel, member: nodeIdentity, writes };
 }
+/**
+ * READ-ONLY provisioning: decide the role from the chain-agreed terms and NEVER submit, claim or
+ * sign. Used only by the installer's registry (`REGISTRY_READ_ONLY=1`), where no identity exists to
+ * sign with and the pinned operator (`REGISTRY_CHANNEL_OPERATOR`) is the only authority trusted.
+ */
+export async function provisionRegistryChannelReadOnly(args) {
+    const { chainAgreedUrl, channel, nodeIdentity, operator, say } = args;
+    const read = await channelTerms(chainAgreedUrl, channel);
+    if (!read.ok)
+        throw new Error(`could not read the terms of '${channel}' from ${chainAgreedUrl}: ${read.why}\n` +
+            `  Refusing to guess — an unreadable answer is "not yet", never a licence to index unverified terms.`);
+    const role = decideRegistryRole({ terms: read.terms, self: operator ?? "", operator, readOnly: true });
+    if (role.kind === "unusable")
+        throw new Error(role.why);
+    if (role.kind === "waiting") {
+        say(`   ⚠ ${role.why}`);
+        return { role: "waiting", channel, member: nodeIdentity, writes: 0 };
+    }
+    if (role.kind !== "reader")
+        throw new Error(`read-only registry resolved an impossible owner role — refusing to index`);
+    say(`   '${channel}' is owned by ${role.holder} — running as a READ-ONLY reader`);
+    say(`   nothing will be claimed, provisioned or submitted here`);
+    return { role: "reader", channel, member: nodeIdentity, writes: 0 };
+}