@mcsherrylabs/pi-meerkat 0.6.0 → 0.8.0

package/dist/installer/node-join.sh

@@ -0,0 +1,228 @@
+#!/bin/sh
+# Claim-then-boot (evolver feature 102) for an explicitly managed follower.
+# Static config is baked into the candidate image. The separately initialized subscription
+# directory is mounted read-only; the installer provisions/persists APP_NODE_ID before boot.
+# Ordinary entry never initializes subscription preferences or adopts existing valued state.
+#
+# FIRST boot: generate this node's keys LOCALLY (they never leave this volume),
+# faucet-claim its identity on devnet (the committee node sponsors and funds it — no
+# admin secret exists anywhere in this deployment), persist the result. EVERY boot:
+# source it and start as a non-genesis follower, syncing the chain from block 0.
+set -eu
+
+# Same read-only guard on normal boot and the owned-fixture preflight. It NEVER initializes,
+# rewrites or merges a declaration; canonical fragment validation belongs to the shared SDK.
+require_subscriptions() {
+  if [ ! -r "$1/channels.conf" ] ||
+     [ "$(cat "$1/channels.conf.initialized" 2>/dev/null || true)" != "evolver-subscriptions-v1" ]; then
+    echo "[node-join] FATAL: initialized subscription declaration missing; refusing to reseed"
+    return 1
+  fi
+}
+if [ "${1:-}" = "--check-subscriptions" ]; then
+  : "${2:?owned subscription directory required}"
+  require_subscriptions "$2"
+  exit $?
+fi
+require_subscriptions /subscriptions
+
+: "${DEVNET_API:?DEVNET_API required (the faucet base url, e.g. https://devnet.mcsherrylabs.com)}"
+
+# ⚠️ CHECKED HERE, not left to HOCON. `preferred-url` is a REQUIRED substitution in the
+# node config, so an unset value fails with
+#   ConfigException$UnresolvedSubstitution: Could not resolve substitution to a value
+# and a stack trace that says nothing about what an operator must do. Required is the
+# right choice — an unroutable default is what made this node dial its own loopback and
+# stop forwarding submits — but the refusal has to be readable.
+# NOTE: meerkat's version of this script FATALs here unless EVOLVER_TRANSPORT_ADDRESS is set. That is
+# an ANNOUNCER's requirement — its channel has a DA group, so other nodes must be able to dial it
+# to flood bodies to it. A reader has no such need and must advertise nothing, so the guard is
+# deliberately absent rather than satisfied with a made-up value.
+
+
+KEYS=/data/keys
+CLAIM="$KEYS/claim.env"
+ID_FILE="$KEYS/node-id"
+mkdir -p "$KEYS"
+chmod 700 "$KEYS"
+
+# The node id is chosen ONCE and persisted, because it is an on-chain name: re-deriving
+# it on a later boot would claim a SECOND identity and abandon the first.
+if [ -f "$ID_FILE" ]; then
+  NODE_ID="$(cat "$ID_FILE")"
+  echo "[node-join] reusing node id '$NODE_ID' (chain state continues)"
+else
+  if [ -n "${APP_NODE_ID:-}" ]; then
+    NODE_ID="$APP_NODE_ID"
+  else
+    # Identity names are ^[A-Za-z0-9]{1,50}$ — no hyphens, dots or underscores — so the
+    # app name is stripped to what a node id may contain (the same rule as
+    # scripts/versions.mjs identityPrefix), and a random suffix keeps a shared chain
+    # collision-free: a fixed name would come back `exists` with keys nobody holds.
+    BASE="$(printf '%s' "${APP_NAME:-app}" | tr -cd '[:alnum:]' | cut -c1-40)"
+    [ -n "$BASE" ] || BASE=app
+    NODE_ID="${BASE}node$(tr -cd '0-9' < /dev/urandom | head -c 6)"
+  fi
+  printf '%s' "$NODE_ID" > "$ID_FILE"
+  echo "[node-join] node id '$NODE_ID' chosen and persisted"
+fi
+
+: "${APP_NODE_ID:?managed deployment requires its saved explicit node id}"
+if [ "$NODE_ID" != "$APP_NODE_ID" ]; then
+  echo "[node-join] FATAL: saved node id differs from managed binding; refusing to claim or boot"
+  exit 1
+fi
+
+if [ ! -f "$CLAIM" ]; then
+  # A CLAIM WHOSE CONFIRMATION TIMED OUT MUST NOT BE RE-SENT BLIND.
+  #
+  # Observed on the live devnet: the faucet answered
+  # `504 {"error":"confirmation_timeout","message":"Transaction submitted but block
+  # confirmation timed out"}` — submitted, outcome UNKNOWN — the container exited, and
+  # the next boot found the id file but no claim file and claimed AGAIN. That is the one
+  # move that cannot be undone: the client persists its keypair only on success, so the
+  # first attempt's keys are gone, and if that attempt committed the name now belongs to
+  # keys nobody holds. The retry then either takes a name with a fresh keypair (and the
+  # first identity is abandoned) or comes back `exists`, after which the node fails every
+  # peer handshake with `Signature does not match` — the 103 failure verbatim.
+  #
+  # So the outcome is settled by READING, exactly as the app settles a submit: if the
+  # name is on chain and we hold no keys for it, stop and say so. The name cannot be
+  # reclaimed, so this is terminal by nature and the operator needs a different one.
+  # ASK, AND DISTINGUISH "NO" FROM "COULD NOT ASK".
+  #
+  # `wget | grep -q '"balance"'` is false for BOTH "the name is free" and "the faucet
+  # is unreachable", and on this path the second must not be read as the first: the
+  # whole point is to avoid claiming a name that may already be bound to keys nobody
+  # holds. So the identity route is asked with the exit status kept, and only a body
+  # that says `not_found` counts as free.
+  #   0 with "balance"    -> taken
+  #   0 with "not_found"  -> free
+  #   anything else       -> could not tell, which is not a licence to claim
+  # ⚠️ THE STATUS LINE, NOT THE EXIT CODE. `/api/identity/<name>` answers 404 for a name
+  # that is FREE — the commonest case — and `wget -qO-` reports any 404 as exit 8 with no
+  # body, so keying on the exit code classified "free" as "cannot ask" and refused to
+  # claim anything at all. Caught by the local rig, where every name is free.
+  #
+  # `-S` prints the response line even for an error status (GNU wget 1.25 in this image),
+  # so the three answers are distinguishable:
+  #   200 + "balance"  -> taken
+  #   404              -> free
+  #   anything else    -> could not ask, which is NOT a licence to claim
+  id_state() {
+    # `|| true` IS LOAD-BEARING, and it is the second layer of the same trap. Keying on
+    # the status line instead of the exit code is necessary but not sufficient: under
+    # `set -e` the ASSIGNMENT inherits wget's exit status, so a 404 killed this function
+    # before the case could run — the caller saw an empty answer and the script exited 8.
+    _resp="$(wget --timeout=5 --tries=1 -S -qO- "$DEVNET_API/api/identity/$1" 2>&1)" || true
+    case "$_resp" in
+      *"200 OK"*'"balance"'*) echo taken ;;
+      *"200 OK"*)             echo taken ;;
+      *"404"*)                echo free ;;
+      *)                      echo unreachable ;;
+    esac
+  }
+  state="$(id_state "$NODE_ID")"
+  if [ "$state" = unreachable ]; then
+    echo "[node-join] FATAL: cannot reach $DEVNET_API to ask whether '$NODE_ID' is already"
+    echo "[node-join]   claimed. Refusing to claim blind: if that name is already bound to keys"
+    echo "[node-join]   this deployment does not hold, claiming it again destroys the name."
+    exit 1
+  fi
+  if [ "$state" = taken ]; then
+    echo "[node-join] FATAL: identity '$NODE_ID' already exists on chain, and this"
+    echo "[node-join]   deployment holds no keys for it ($CLAIM is absent). A previous"
+    echo "[node-join]   claim committed after its confirmation timed out, and its keys"
+    echo "[node-join]   were never persisted — nothing here can authenticate as that name."
+    echo "[node-join]   Set APP_NODE_ID to an unused name (an identity name cannot be reused)."
+    exit 1
+  fi
+  echo "[node-join] first boot: claiming identity '$NODE_ID' via $DEVNET_API"
+  java -cp "/opt/evolver/lib/*" ce.evolver.tools.IdentityClaimClient \
+    --target="$DEVNET_API" --node-id="$NODE_ID" --out="$CLAIM" \
+    --timeout="${CLAIM_TIMEOUT:-180}" || CLAIM_RC=$?
+  if [ ! -f "$CLAIM" ]; then
+    # OUR attempt's outcome is now the unknown one, and asking ONCE is not enough: a
+    # `504 confirmation_timeout` means the transaction was submitted, and it can commit
+    # minutes later (its TTL is +50 rounds, and on a quiescent chain rounds are slow).
+    # Asking immediately and printing "the name is still free" was wrong while the claim
+    # was in flight — and with `restart: unless-stopped` the next boot would claim the
+    # same name AGAIN with fresh keys, which is how a name gets bound to keys nobody
+    # holds. So watch it for a bounded window before saying anything.
+    echo "[node-join] the claim for '$NODE_ID' did not confirm (exit ${CLAIM_RC:-?}) —"
+    echo "[node-join]   outcome UNKNOWN. Watching for up to ${CLAIM_WATCH_SECS:-300}s to see"
+    echo "[node-join]   whether it commits; nothing is resent."
+    _waited=0
+    _final=free
+    while [ "$_waited" -lt "${CLAIM_WATCH_SECS:-300}" ]; do
+      _s="$(id_state "$NODE_ID")"
+      if [ "$_s" = taken ]; then _final=taken; break; fi
+      sleep 10
+      _waited=$((_waited + 10))
+    done
+    if [ "$_final" = taken ]; then
+      echo "[node-join] FATAL: the claim for '$NODE_ID' COMMITTED after its confirmation"
+      echo "[node-join]   timed out, and its keys were never persisted (evolver#86)."
+      echo "[node-join]   Set APP_NODE_ID to an unused name and start again — an identity"
+      echo "[node-join]   name cannot be reused."
+    else
+      echo "[node-join] '$NODE_ID' is still not on chain after ${_waited}s, so the claim"
+      echo "[node-join]   did not commit and the name remains free; a restart may retry it."
+    fi
+    exit 1
+  fi
+  chmod 600 "$CLAIM"
+  echo "[node-join] claim committed — keys persisted (mode 600)"
+fi
+
+# EVOLVER_PRIVATE_KEY / EVOLVER_NODE_PUBLIC_KEY / EVOLVER_BLS_SEED
+set -a
+. "$CLAIM"
+set +a
+
+mkdir -p /data/chain
+# Config-only directory is mounted read-only into this node. Only the shared SDK controller
+# writes it. Ordinary boot NEVER merges environment/module defaults or initializes a missing file.
+# SDK initialization is an explicit fresh-resource command; its marker survives an empty set.
+# Already required before any identity/claim effects at entry.
+# Keep keys/chain private: no agent/container writes this node's database or fragment.
+chmod 700 /data/chain
+
+# ── WHICH PEERS THIS NODE DIALS ───────────────────────────────────────────
+#
+# ONE list rendered as BOTH keys, because they are one decision: `preferred-peers` says
+# who, `allowed-outbound` says how many, and the pin is strict only while the two agree
+# (node.conf says why). Computed here rather than written in node.conf for the same
+# reason the channel list is — so the two halves cannot drift apart.
+#
+# The upstream is always dialled. EVOLVER_DA_PEERS adds the DA members this deployment
+# must reach to PULL bodies for the channels declared above; without a slot for them,
+# `ChannelOverlay.peers()` is empty for those channels and nothing is ever fetched.
+_peers="${EVOLVER_UPSTREAM_NODE_ID}"
+# EVOLVER_DA_PEERS, comma-separated, deduplicated against the upstream. The comment above has
+# promised this since the file was written and the code never did it — so a deployment that set
+# it got silence, and the only way to pin a second peer was to smuggle a comma into
+# EVOLVER_UPSTREAM_NODE_ID, which works here only by accident of raw substitution and breaks the
+# dedupe and the count in the sibling stacks that DO implement this. Same shape as
+# evolver-llm/docker-compose.devnet.yml.
+for _p in $(printf '%s' "${EVOLVER_DA_PEERS:-}" | tr ',' ' '); do
+  if [ -n "$_p" ] && [ "$_p" != "${EVOLVER_UPSTREAM_NODE_ID}" ]; then
+    _peers="$_peers, $_p"
+  fi
+done
+_outbound="${EVOLVER_ALLOWED_OUTBOUND:-16}"
+echo "[node-join] pinning ${_peers} as the seed; allowing ${_outbound} outbound so discovery can happen"
+{
+  # The seed is PINNED so there is always a way back to the chain. `allowed-outbound` is
+  # deliberately LARGER than that one entry: the pin is strict only while the two are equal, and a
+  # strict pin would stop this node dialling anything it discovers. Once it has peers it learns its
+  # own distance to the committee and forwards transactions along that path like any other node.
+  printf 'evolver.peer-discovery.preferred-peers  = [ %s ]
+' "$_peers"
+  printf 'evolver.peer-discovery.allowed-outbound = %s
+'     "$_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"
+

package/dist/installer/node.conf

@@ -0,0 +1,235 @@
+# 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("/public-genesis/genesis.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 = "/public-genesis/genesis.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}
+# 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

@@ -0,0 +1 @@
+{"operatorIdentity":"evolvermeerkatA","sdk":"0.22.1","bootstrap":"0.15.0"}

package/dist/installer-runtime/dist/scripts/recover-owner.js

@@ -0,0 +1,15 @@
+// Explicit offline operator action. Never imported/called by ordinary startup.
+import { pathToFileURL } from "node:url";
+import { recoverProcessorOwnerLock } from "@mcsherrylabs/evolver-client/processor";
+import { currentTarget } from "../src/env.js";
+import { processorStatePath } from "../src/runtime.js";
+export function recoverMeerkatOwner(args, target, say = console.error) {
+    if (args.length !== 1 || args[0] !== "--force")
+        throw new Error("usage: recover-owner --force (only after stopping ALL collectors and disabling automatic restarts)");
+    say("WARNING: --force acknowledges ALL collectors are stopped and automatic restarts disabled; this command cannot verify that.");
+    const result = recoverProcessorOwnerLock({ path: processorStatePath(target), force: true });
+    say(`${result.removed ? "Removed owner lock" : "No owner lock present"}: ${result.marker}. Database/WAL, progress, subscriptions and keys unchanged. Start ONE collector normally with the SAME target/state environment to acquire a new lock.`);
+    return result;
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
+    recoverMeerkatOwner(process.argv.slice(2), currentTarget());

package/dist/installer-runtime/dist/scripts/subscriptions-init.js

@@ -0,0 +1,35 @@
+// Explicit fresh-resource operation; NEVER imported/called by ordinary startup or upgrade.
+import { chown, chmod, mkdir, readdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { initializeSubscriptions } from "@mcsherrylabs/evolver-client/processor";
+import { currentTarget, ROOT } from "../src/env.js";
+import { processorConfigPath } from "../src/runtime.js";
+const raw = process.env.EVOLVER_INITIAL_CHANNELS;
+if (raw === undefined)
+    throw new Error("set EVOLVER_INITIAL_CHANNELS to an explicit JSON array (including []); initialization is fresh-only");
+const channels = JSON.parse(raw);
+if (!Array.isArray(channels) || channels.some(id => typeof id !== "string"))
+    throw new Error("EVOLVER_INITIAL_CHANNELS must be a JSON string array");
+const path = processorConfigPath(currentTarget());
+const directory = dirname(path);
+if (process.getuid?.() === 0) {
+    const uid = Number(process.env.EVOLVER_OPERATOR_UID), gid = Number(process.env.EVOLVER_OPERATOR_GID);
+    if (![uid, gid].every(id => Number.isSafeInteger(id) && id >= 1))
+        throw new Error("root fresh initializer requires non-root operator uid/gid");
+    for (const dir of [directory, join(ROOT, "state")]) {
+        await mkdir(dir, { recursive: true, mode: 0o750 });
+        if ((await readdir(dir)).length !== 0)
+            throw new Error("fresh initialization refuses nonempty managed volumes; no valued migration/reseed");
+    }
+    for (const dir of [directory, join(ROOT, "state")]) {
+        await chown(dir, uid, gid);
+        await chmod(dir, 0o750);
+    }
+    process.setgroups([]);
+    process.setgid(gid);
+    process.setuid(uid);
+}
+else
+    await mkdir(directory, { recursive: true, mode: 0o750 });
+await initializeSubscriptions(path, channels);
+console.log(`initialized subscription declaration ${path}; ordinary startup will never reseed it`);

package/dist/installer-runtime/dist/scripts/versions.mjs

@@ -0,0 +1,86 @@
+// Read .env — the single source of truth for versions and image names.
+//
+// Deliberately hand-parsed rather than pulling in dotenv: this is a template, and a
+// dependency whose whole job is reading six lines of KEY=value is a dependency a reader has
+// to evaluate. docker compose reads the same file natively, so there is one file and two
+// consumers, not two sources.
+import { readFileSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+// fileURLToPath, not url.pathname — see the note in src/env.ts.
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+export const ENV_PATH = join(ROOT, ".env");
+export function readEnv() {
+    const out = {};
+    for (const line of readFileSync(ENV_PATH, "utf8").split("\n")) {
+        const t = line.trim();
+        if (!t || t.startsWith("#"))
+            continue;
+        const i = t.indexOf("=");
+        if (i < 0)
+            continue;
+        // Match docker compose's grammar, because it reads this same file: strip an inline
+        // comment and surrounding quotes, and tolerate CRLF. Diverging here is worse than not
+        // parsing at all — `npm run image` would tag one thing while `docker compose up` ran
+        // another, and nothing would report a conflict.
+        let v = t.slice(i + 1).replace(/\r$/, "").trim();
+        v = v.replace(/\s+#.*$/, "").trim();
+        if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+            v = v.slice(1, -1);
+        }
+        if (!v)
+            continue; // empty ⇒ treat as missing, so the required-keys check reports it
+        out[t.slice(0, i).trim()] = v;
+    }
+    for (const k of ["EVOLVER_REGISTRY", "REGISTRY", "EVOLVER_VERSION", "APP_NAME", "APP_VERSION"]) {
+        if (!out[k])
+            throw new Error(`${ENV_PATH}: ${k} is missing — it is required, see the comments in that file`);
+    }
+    return out;
+}
+/** Update keys in .env IN PLACE, preserving comments and order — the comments are the
+ *  documentation, so rewriting the file from an object would delete the explanation. */
+export function updateEnv(updates) {
+    const lines = readFileSync(ENV_PATH, "utf8").split("\n");
+    const seen = new Set();
+    const out = lines.map((line) => {
+        const t = line.trim();
+        if (!t || t.startsWith("#"))
+            return line;
+        const i = t.indexOf("=");
+        if (i < 0)
+            return line;
+        const key = t.slice(0, i).trim();
+        if (!(key in updates))
+            return line;
+        seen.add(key);
+        return `${key}=${updates[key]}`;
+    });
+    for (const [k, v] of Object.entries(updates))
+        if (!seen.has(k))
+            out.push(`${k}=${v}`);
+    writeFileSync(ENV_PATH, out.join("\n"));
+}
+export const appImage = (e = readEnv()) => `${e.REGISTRY}/${e.APP_NAME}:${e.APP_VERSION}`;
+export const deployRef = (e = readEnv()) => `${e.REGISTRY}/${e.APP_NAME}-deploy:${e.APP_VERSION}`;
+/** The app-ALONE deployment, pointed at a chain that already exists — from
+ *  `docker-compose.remote.yml`. */
+export const remoteDeployRef = (e = readEnv()) => `${e.REGISTRY}/${e.APP_NAME}-deploy-remote:${e.APP_VERSION}`;
+/** The app PLUS ITS OWN NODE, that node joining devnet — from `docker-compose.devnet.yml`.
+ *
+ *  Three refs because they are three different things to hand someone, and the difference is
+ *  not cosmetic: one carries a throwaway chain, one borrows somebody else's node on a real
+ *  chain, and one brings a node of its own onto that real chain (which is the only shape that
+ *  can read an ordered channel stream or join a DA overlay). */
+export const devnetDeployRef = (e = readEnv()) => `${e.REGISTRY}/${e.APP_NAME}-deploy-devnet:${e.APP_VERSION}`;
+/** Identity names are `^[A-Za-z0-9]{1,50}$` — no hyphens, dots or underscores — so an app
+ *  name cannot be used verbatim. Strip it to what a node id may contain and bound it.
+ *
+ *  This exists because the identity names used to be hardcoded `tmplA`/`tmplB`: rename your
+ *  app to anything you like and it still claimed identities named after the template, which
+ *  on a SHARED chain like devnet is the one place provenance matters. Empty after stripping
+ *  (a name of only separators) falls back to `app` rather than producing `A`/`B`.  */
+export function identityPrefix(appName) {
+    const stripped = String(appName ?? "").replace(/[^A-Za-z0-9]/g, "").slice(0, 40);
+    return stripped || "app";
+}