@mcsherrylabs/pi-meerkat 0.6.0 → 0.8.0

package/README.md

@@ -1,75 +1,255 @@
 # @mcsherrylabs/pi-meerkat
 
-Pi agent tools for the meerkat announcements registry: **announce a channel you control**, and
-search what others have announced.
+Meerkat registry tools and a **stdio MCP facade**. One client registration exposes the seven
+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.
 
-```
-pi-meerkat  ──▶  @mcsherrylabs/evolver-core  ──▶  @mcsherrylabs/evolver-client
-  the service's verbs        chain + content capability        the wire
-```
+**Version 0.8.0 adds the zero-required-parameter installer.** 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`.
 
-`pi-meerkat` depends on `@mcsherrylabs/evolver-core` (the extracted chain capability that the MCP
-server and any agent extension share) rather than carrying a vendored copy. Two things stay local
-because core deliberately does not provide them: the **two-file project/home config precedence**
-(`src/config.ts`) and the **chain target** (`src/target.ts`, the node client + signer wiring). The
-failure taxonomy (`ToolResult`) and the content publish (`publishBytes`) come from core.
+## Install the complete experience
 
-## Why this is a separate package
+Prerequisites in the environment where your MCP harness runs:
 
-The generic chain tool surface forbids a tool from naming a channel, a ledger or a service, and fails its build
-for it — a draft of its content tool was rejected for the word "announcement". That rule is what
-keeps it chain-generic, and it is also what says where a service's own verbs belong: **here**, in
-the service's own repository, installed by whoever wants them. A new service becomes usable by an
-agent with nothing central edited.
+- Node.js **22 or newer**, with `npm` and `npx` on `PATH`.
+- A reachable Docker Engine and **Docker Compose v2** (`docker version`, `docker compose version`).
+  A normal local engine or a separately hosted Docker daemon/context both work. Existing Docker
+  authentication/TLS settings are respected; no new credentials are requested for public images.
+- An MCP harness with stdio support. The installer prints registration JSON; it does not edit
+  the harness or silently replace an existing registration.
 
-## Tools
+### 1. Install
 
-| tool | what it answers |
-|---|---|
-| `meerkat_summary` | start here — counts, kinds, keywords, misses, and **which channel** this registry indexes |
-| `meerkat_services` | search by keyword or free text |
-| `meerkat_service` | one entry in full, with its `provenance` |
-| `meerkat_detail` | the announced document, digest-verified by the registry |
-| `meerkat_rejections` | why an announcement was refused |
-| `meerkat_announce` | describe a channel you control, optionally with a document |
-| `meerkat_inbox` | what arrived on a channel this node subscribes to and no handler claimed — the event inbox |
+```bash
+npx --yes @mcsherrylabs/pi-meerkat@0.8.0 install
+```
 
-## Three things that are deliberate
+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.
 
-**The document is published before the announcement, inside the tool.** An announcement names its
-document by key and digest. Announce first and the entry refers to bytes that exist nowhere —
-permanently `unfetchable`, indistinguishable from a document that is merely slow, and *every*
-detail document on this estate was in that state until it was found. Two composable tools would
-put that ordering in a model's hands. `meerkat_announce` takes the text.
+### 2. Register one server
 
-**The document is published OPEN.** Anyone who obtains the key may read it. That is right for a
-public index, and with the announcements channel no longer carrying a DA group there is no group
-left to grant to. Do not announce anything whose disclosure depends on a key staying private.
+Use the one `registration.mcpServers.meerkat` entry printed by installation. For Claude Code,
+if you do not already have a registration named `meerkat`, the equivalent command is:
 
-**The channel is configuration, not a parameter.** `REGISTRY_CHANNEL` — the same variable the
-registry reads, so the two cannot disagree. A model with a free-text channel field will
-eventually fill it from something it read, and an announcement is charged and permanent.
+```bash
+claude mcp add --scope user --transport stdio meerkat -- \
+  npx --yes @mcsherrylabs/pi-meerkat@0.8.0 serve
+```
 
-## Configuration
+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
+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
+host-path sharing nor a public read port.
+Stdout carries MCP protocol only. Closing the connection or signalling the launcher awaits the
+exact remote facade and its private child, not the shared registry or another client's session.
+
+### Resume and ownership
+
+Run the **same install command** again to resume the same installation. Names, identity/key
+references, internal service ports, daemon identity, real genesis/node binding and ownership are saved
+privately under the operator's XDG state directory (or normal home state directory). Services
+use separately owned Docker volumes for consensus data, processing-node data, public genesis,
+registry/app state, subscriptions and announcer state. Consensus and consumer-paced processing
+are separate roles required by the released node. The follower receives only the **public** chain
+specification, never the consensus node's private volume. The released Evolver bootstrap alone
+creates/loads announcer signing keys; the facade,
+installer and output carry only references. No key bytes are copied to the harness.
+
+Rerun does not initialize subscriptions again, regenerate genesis, rotate keys, change authority,
+force-claim/unclaim, adopt another daemon's resources or recover an owner lock. A missing valued
+volume, conflicting ownership, changed daemon/binding, interrupted initializer or stale owner lock
+refuses explicitly and retains state for operator inspection. There is no automatic reset,
+force recovery, Docker prune, broad restart or harness-registration mutation. `serve` never
+creates or restarts services. An intentional **install** invocation may start its own stopped
+services; unrelated services are never touched. Automatic cross-version migration is not provided:
+resume with the saved pinned version.
+
+The installer enables the complete registry/read/announce experience, not every optional upstream
+capability. Generic Evolver subscription-control and other optional capability tools can remain
+unconfigured and refuse clearly; no Docker socket or private node-control API is exposed to the
+registry/facade. The real tool catalog baseline is 65 upstream + 7 local, **not a promise that each
+optional capability is configured**.
+
+## Advanced: attach an existing node
+
+If you already operate a node, registry and keys, you may install this exact package normally
+and use `meerkat-mcp setup` instead. This is an alternative to the automatic installer, not a
+prerequisite for it. Keep your installed package on a persistent user-owned PATH, not an
+npm-cache-internal pathname.
+
+Setup records **references**, not key bytes. Select an existing node endpoint, separate content
+endpoint, identity, existing key file, registry read origin, explicit genesis/chain ID and node ID,
+registry channel, and TLS policy. This command does not provision a node, claim an identity,
+create/copy a key, initialize a registry database, or change a client registration automatically.
+
+Set the following shell inputs to values you already operate. Do not copy a guessed identity,
+chain ID, key, or endpoint from a model or from registry content. `MEERKAT_TLS_INSECURE=false`
+keeps certificate verification enabled; an explicitly chosen private CA may be supplied with
+`--ca-file /absolute/operator-ca.pem`.
+
+<!-- meerkat-setup:start -->
+```bash
+meerkat-mcp setup \
+  --config "${MEERKAT_CONFIG:?Choose an absolute operator-owned config path}" \
+  --node-url "${MEERKAT_NODE_URL:?Select the existing node origin}" \
+  --content-url "${MEERKAT_CONTENT_URL:?Select its separate content origin}" \
+  --identity "${MEERKAT_IDENTITY:?Select the existing signing identity}" \
+  --key-path "${MEERKAT_KEY_PATH:?Select the existing absolute key reference}" \
+  --key-type "${MEERKAT_KEY_TYPE:?Select ed25519 or bls}" \
+  --tls-insecure "${MEERKAT_TLS_INSECURE:?Explicitly choose true or false}" \
+  --meerkat-url "${MEERKAT_READ_URL:?Select the registry processor read origin}" \
+  --chain-id "${MEERKAT_CHAIN_ID:?Supply the existing 64-hex chain ID}" \
+  --node-id "${MEERKAT_NODE_ID:?Supply the existing inbox-binding node ID}" \
+  --channel "${MEERKAT_CHANNEL:?Select the registry announcement channel}"
+```
+<!-- meerkat-setup:end -->
 
-| variable | what |
-|---|---|
-| `MEERKAT_URL` | the event processor's read server — the registry's routes and the inbox — e.g. `http://registry:8090`. `REGISTRY_URL`, its name before 0.3.0, is refused: every read answers `misconfigured` until it is renamed |
-| `REGISTRY_CHANNEL` | the channel to announce onto and read (default `ce.meerkat.announcements`) |
-| `EVOLVER_URL`, `EVOLVER_IDENTITY`, `EVOLVER_KEY_PATH` | the local loader — who signs |
-| `EVOLVER_CONTENT_URL` | the local loader — required only to announce a document |
+Create the config's parent directory beforehand. Setup exclusively creates an operator-owned
+mode-0600 file and refuses to overwrite an existing one. Treat that file and all parent paths as
+trusted launch configuration; do not let a project or another user replace them. Setup checks
+that the key reference exists but **only the child reads signing-key bytes**. Key bytes do not
+enter the setup output, facade, or registration.
+
+Setup emits one JSON `mcpServers` entry, with the installed facade's absolute command and
+`--config` pointing to the saved file. Add **that one Meerkat entry** to your MCP client's
+configuration. No manual environment ceremony, separate Evolver registration, HTTP MCP service,
+Pi adapter, or separately managed child is required. Direct launch uses the same entrypoint:
+
+```bash
+meerkat-mcp --config "$MEERKAT_CONFIG"
+```
 
-The read tools need no chain at all: an agent with no signing key can still search the index.
+For advanced attach, register the exact persistent installed entrypoint/config returned by
+setup; do not point a client at an npm-cache-internal file. The automatic installer's pinned
+`serve` registration above is the recommended route for a virgin harness. In Claude Code,
+`--scope user` makes the operator registration available across projects; `--scope local`
+limits it to the current project. Start a fresh session and use `/mcp` to inspect the connection.
+Do not approve announcement/sign/submit calls until you deliberately choose to exercise a write.
+
+The stdio connection uses stdout exclusively for MCP messages. Diagnostics go to stderr. The
+operator-selected node/content/trust/identity/key/channel inputs are captured at facade startup;
+model arguments and project configuration cannot select signing authority. Within one client,
+forwarded Evolver tools and `meerkat_announce` deliberately share the owned upstream session and
+signing history. Independent clients each get a distinct child/session/store. There are **two
+server OS processes**, privately owned by the single registration. Close the client connection
+or stop the facade to await its child and transport cleanup.
+
+## Degraded discovery and independent reads
+
+Initialization and local reads do not require a signing key or a working upstream child.
+Without `--config`, registry read inputs retain `MEERKAT_URL`, `EVOLVER_CHAIN_ID` and
+`APP_NODE_ID`; these are the only inputs needed for bound inbox reads. With `--config`, the
+saved operator values bind those reads. `REGISTRY_URL` remains a refused obsolete name.
+
+A bounded failed upstream discovery returns the **seven local definitions** with explicit
+upstream-unavailable/degraded metadata and a stderr diagnostic. All six read tools remain
+usable, including both inbox summary and paginated page routes. Announce and upstream-dependent
+calls refuse clearly. Failed refresh invalidates stale upstream routing; a later successful
+catalog discovery can restore healthy routing but never resumes or replays an interrupted write.
+There is no hidden-name workaround or eighth status tool.
 
-## The contract lives here
+## Tools
 
-`src/contract.ts` is the announcement wire format — bounds, types and the body builder. It is in
-this package rather than in the app so a client can announce without depending on the whole
-registry, and so there is one encoding rather than two. Pure: no chain, no clock, no I/O.
+| Tool | Purpose |
+|---|---|
+| `meerkat_summary` | Start here: counts, kinds, keywords, misses, indexed channel and progress |
+| `meerkat_services` | Search announced services by keyword or free text |
+| `meerkat_service` | Read one service, including provenance |
+| `meerkat_detail` | Read the document already digest-verified by the registry |
+| `meerkat_rejections` | Learn why an ordered announcement was not indexed |
+| `meerkat_inbox` | Read the inbox summary, or a bounded page with `round:index` continuation |
+| `meerkat_announce` | Describe a channel you control, optionally with an open document |
+
+The original seven names, descriptions and input schemas are preserved against published 0.6.0.
+Upstream descriptions/schemas/results are forwarded unchanged. A newly discovered tool routes
+without an adapter. Colliding names and unknown/undiscovered calls refuse rather than shadowing.
+This is a tools facade, not a generic prompts/resources proxy. Supported cancellation is passed
+through; cancellation is not rollback. Supported upstream tool-list changes refresh the catalog.
+
+Registry strings are **untrusted data**, never instructions or signing configuration. Read errors
+are not empty answers: not-found, unreachable, unavailable and truncated remain distinct. Inbox
+binding validates the configured chain and node; previews remain at most 256 decoded bytes per
+entry, with at most 50 entries and 12,800 preview bytes per page. Carry the returned `next` as
+`after` yourself; the facade does not advance a processor cursor.
+
+## Announcement semantics
+
+The registry channel is **trusted configuration**, not a tool parameter. The facade uses the
+existing unsigned `announcementBody` encoder, with its field order, bounds, UTF-8 bytes and
+4,096-byte body cap. Sequence is epoch seconds; lease expiry uses a read-only chain-round
+preflight in the same session, defaulting to 20,000 rounds, never wall-clock as chain height.
+
+The owned sequence is:
+
+1. `evolver_chain_height` (read-only preflight).
+2. If nonempty detail text is supplied, await `evolver_content_put` with `access=open`; validate
+   the real acknowledgement and original UTF-8 size/SHA-256 before embedding its reference.
+3. `evolver_sign_channel_write` for the configured channel and exact announcement `bodyHex`.
+4. Ordinary `evolver_submit` with **only the original returned txId**.
+
+No DA conversion/collection, auto-claim, extra mutating setup, caller-selected identity/key/TTL,
+local signer, local key read or direct node submit is added. The document is published **OPEN**:
+anyone with its key may read it. Upload occurs before signing; a successful upload may remain
+stored after a later failure.
+
+Only this owned orchestration decodes upstream's actual warning-suffixed JSON and submit prose;
+transparent forwarded results are never reworded. Protocol success or `isError:false` does not
+establish a committed announcement. Committed, fined, refused, unknown and local
+already-submitted remain distinct. A fined write can charge and deliver a body; committed is
+**not registry acceptance**—read the entry/rejections afterward.
+
+Definitive local child/session loss before submit prevents that send. Once submit may have left
+the transport, a lost, timed-out or unreadable reply means **UNKNOWN**, retaining the original
+txId and reconciliation guidance. Read/reconcile that transaction; never automatically reconnect,
+resume, re-sign, retry or replay the write. Already-submitted says this call sent nothing, not
+that a previous attempt failed.
+
+## Existing Pi package and registry application
+
+The retained Pi extension and useful `channel-subscription` / `service-discovery` skills are
+still shipped. The legacy extension's `EVOLVER_URL`, `EVOLVER_IDENTITY`, `EVOLVER_KEY_PATH`,
+`EVOLVER_CONTENT_URL` and two-file Pi config are **not** the MCP facade's authority interface.
+No additional Pi host adapter is required. The root registry application, database/schema,
+processor cursor and supported SDK Docker helper are unchanged. Root `npm start` starts the
+registry application and does not demonstrate facade acceptance.
+
+The announcement wire contract remains in this package (`src/contract.ts`, export `./contract`),
+so clients and the registry use one encoder rather than divergent copies. MCP runtime
+capability comes from the exact installed child; remaining SDK usage in the facade is unsigned
+encoding/types or the existing bound `ProcessorClient` inbox reads, not local signing.
+
+## Verification lanes
 
 ```bash
-npm run check:contract   # the encoding and every bound, with nothing running
-npm run check:surface    # the tool table's properties
+npm run check:pi                     # root: ordinary package tests, including K01–K07
+npm run check:plan-two:client --workspace @mcsherrylabs/pi-meerkat
 ```
 
-Version 0.4.2 (history) pinned pi-evolver 0.9.0 and evolver-client 0.19.0 to share the corrected identity-key lookup. Configure the agent API endpoint to evolver-node **v0.24.1+** before using that lookup. The announcement and inbox contracts are unchanged.
+Run networked gates in a disposable isolated network namespace/container, with physical
+`K_REGISTRY_TEST_TMP` and temporary outputs outside the source tree. K uses a real downstream
+MCP client, built and freshly packed-installed facade, real released child, fixed fixture keys,
+HTTP boundary stand-ins, explicit counters/barriers, and awaited exact-owned cleanup. It makes
+no live model, faucet/devnet, production database or estate changes. `PLAN_TWO_REPORT` selects
+the acceptance report path; source CI retains this report and runs the normal package chain.
+
+An npm pack is **not publication**. Publication needs an unused version, synchronized locks,
+an immutable `pi-meerkat-vX.Y.Z` tag at the accepted revision and successful exact-SHA required
+CI/publish jobs. Published-release verification additionally retrieves anonymous metadata and
+tarballs/integrity and exercises the installed published facade/dependency with independent
+clients in isolation. Served/downloaded instruction hashes and transcripts belong to that
+post-publication lane. Pending publication or delivery gates must not be represented as passes.

package/dist/installer/committee-init.sh

@@ -0,0 +1,117 @@
+#!/bin/sh
+# node entrypoint: host keys + genesis on first boot, then exec the node.
+#
+# On FIRST boot it generates this node's key material ON THE HOST (never in the
+# image or the repo), renders a one-node genesis committee from the derived public
+# keys, and persists everything into the /data volume. On every subsequent boot it
+# REUSES the same keys + genesis so the chain continues — the genesis committee must
+# stay byte-stable or the chain identity diverges.
+#
+# Two secrets, handled identically (spec 101 — both are host-only secrets):
+#   - Ed25519 node-identity key  -> ce.evolver.node.private-key (EVOLVER_PRIVATE_KEY)
+#   - BLS consensus key (IKM)    -> ce.evolver.node.bls-secret   (EVOLVER_BLS_SEED)
+# Their public keys go into genesis (public-key / bls-public-key).
+set -eu
+
+# Deliberately NOT derived from the app name. This id is written into the genesis
+# file on the volume at FIRST BOOT, so changing it on an existing chain would launch
+# the node under a name absent from its own genesis. Keeping it neutral means
+# `npm run rename` never has to touch this file and cannot leave a previous project's
+# name behind — the template used to default to `tmplnode0`, so every app built from
+# it had a node introducing itself by the TEMPLATE's name, in its logs and in its
+# published deployment artifact.
+NODE_ID="${NODE_ID:-node0}"
+KEYS=/data/keys
+GENESIS=/data/genesis.gen.conf
+ED_KEY="$KEYS/ed25519.key"     # base64 PKCS#8 Ed25519 private
+BLS_KEY="$KEYS/bls.key"        # base64 BLS IKM (>=32 bytes)
+
+if [ -f "$ED_KEY" ] || [ -f "$BLS_KEY" ] || [ -f "$GENESIS" ]; then
+  [ -s "$ED_KEY" ] && [ -s "$BLS_KEY" ] && [ -s "$GENESIS" ] || {
+    echo '[node-init] incomplete owned keys/genesis; refusing regeneration' >&2; exit 1;
+  }
+fi
+if [ ! -f "$ED_KEY" ]; then
+  echo "[node-init] first boot: generating host key material for '$NODE_ID'"
+  mkdir -p "$KEYS"; chmod 700 "$KEYS"
+
+  # Ed25519 identity keypair — PKCS#8 private + X.509 public, base64 DER.
+  tmp="$(mktemp)"
+  openssl genpkey -algorithm ed25519 -outform DER -out "$tmp" 2>/dev/null
+  ED_PRIV="$(base64 -w0 < "$tmp")"
+  ED_PUB="$(openssl pkey -inform DER -in "$tmp" -pubout -outform DER 2>/dev/null | base64 -w0)"
+  rm -f "$tmp"
+
+  # BLS consensus keypair — random IKM + derived pubkey, via the evolver keygen.
+  BLS_OUT="$(java -cp "/opt/evolver/lib/*" ce.evolver.crypto.keys.BLSKeyGenerator)"
+  BLS_SECRET="$(echo "$BLS_OUT" | awk '/^bls-secret:/{print $2}')"
+  BLS_PUB="$(echo "$BLS_OUT" | awk '/^bls-public-key:/{print $2}')"
+
+  if [ -z "$ED_PRIV" ] || [ -z "$ED_PUB" ] || [ -z "$BLS_SECRET" ] || [ -z "$BLS_PUB" ]; then
+    echo "[node-init] FATAL: key generation produced empty output" >&2
+    exit 1
+  fi
+
+  # Persist secrets — host-only, mode 600.
+  printf '%s' "$ED_PRIV"    > "$ED_KEY";  chmod 600 "$ED_KEY"
+  printf '%s' "$BLS_SECRET"  > "$BLS_KEY"; chmod 600 "$BLS_KEY"
+
+  # Render the chain spec (089): committee PUBLIC keys + the chain-wide consensus
+  # parameters. This exact file is published verbatim to every follower / app node
+  # (102 follower-join: the genesis file IS the chain, byte-identical everywhere) and
+  # its canonical hash is pinned as the genesis block id (ce.evolver.genesis-file in
+  # node.conf). 103: the host is the ROUTABLE public address — followers dial the
+  # committee at exactly this host:port. Chain-wide params live HERE, not in node.conf,
+  # so joiners inherit them automatically — quiescence especially (FR-019: a joiner
+  # with different quiescence would time out the deliberately-lingering leader).
+  PUBLIC_HOST="${PUBLIC_HOST:-localhost}"
+  cat > "$GENESIS" <<EOF
+ce.evolver.genesis.nodes = [
+  {
+    node-id        = "$NODE_ID"
+    host           = "$PUBLIC_HOST"
+    port           = 7000
+    public-key     = "$ED_PUB"
+    bls-public-key = "$BLS_PUB"
+    quorum-weight  = 1000
+  }
+]
+
+ce.evolver.consensus {
+  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
+  }
+}
+EOF
+  echo "[node-init] generated keys (secrets in $KEYS, mode 600) + chain spec (host=$PUBLIC_HOST)"
+  echo "[node-init] PUBLISH the chain spec (public keys + chain-wide config): docker compose cp node:/data/genesis.gen.conf ."
+else
+  echo "[node-init] existing keys found in $KEYS — reusing (chain continues)"
+fi
+
+# Secrets reach the node via env (HOCON ${?...} substitution in node.conf).
+EVOLVER_PRIVATE_KEY="$(cat "$ED_KEY")";  export EVOLVER_PRIVATE_KEY
+EVOLVER_BLS_SEED="$(cat "$BLS_KEY")";    export EVOLVER_BLS_SEED
+mkdir -p /data/chain
+
+echo "[node-init] launching evolver node '$NODE_ID'"
+if [ -f /public-genesis/genesis.conf ]; then
+  cmp -s "$GENESIS" /public-genesis/genesis.conf || { echo '[node-init] public genesis differs; refusing replacement' >&2; exit 1; }
+else
+  cp "$GENESIS" /public-genesis/genesis.pending
+  chmod 640 /public-genesis/genesis.pending
+  mv /public-genesis/genesis.pending /public-genesis/genesis.conf
+fi
+exec /opt/evolver/bin/evolver -Dconfig.file=/config/node.conf "$NODE_ID"

package/dist/installer/committee.conf

@@ -0,0 +1,102 @@
+# Single-node full-quorum, quiescent. The chain spec (committee with this
+# node's generated public keys + ALL chain-wide consensus params, incl. quiescence) is
+# rendered at first boot by node-init.sh into /data/genesis.gen.conf and included
+# here — this file holds only NODE-LOCAL config. Secrets arrive via env (never in this
+# file).
+include file("/data/genesis.gen.conf")
+
+# 089 chain-spec pin: the canonical hash of the genesis file IS the chain's genesis
+# block id. Joiners set this to their verbatim copy — any drift refuses to boot.
+ce.evolver.genesis-file = "/data/genesis.gen.conf"
+
+ce.evolver.node {
+  private-key = ${?EVOLVER_PRIVATE_KEY}   # Ed25519 PKCS#8 (host secret, from node-init.sh)
+  bls-secret  = ${?EVOLVER_BLS_SEED}      # BLS IKM       (host secret, from node-init.sh)
+}
+
+evolver.peer-discovery {
+  # What this node ADVERTISES about ITSELF to peers — not somewhere it connects to.
+  # This chain is standalone (one node, its own genesis, no seeds) so nothing reads
+  # these; localhost is used because the alternative is advertising an address that
+  # is not this node. They named devnet.mcsherrylabs.com purely because this config
+  # was copied from that deployment. Joining a real chain means setting them to the
+  # ROUTABLE p2p transport (raw TCP mTLS :7000) and HTTPS API your peers can dial.
+  # 163 — `host:port`, no scheme: the transport is raw TCP + mTLS and never was a URL.
+  transport-address       = "committee:7000"
+  # No `peer-url`: this chain is one node, so nothing fetches content from it, and the
+  # plain-HTTP :8440 above could not serve a peer anyway — a content fetch carries the
+  # caller's client certificate and needs the node's OWN TLS listener. Joining a real
+  # chain means setting `transport-address` to the routable :7000 and `peer-url` to this
+  # node's https listener (never a reverse proxy: it presents no client certificate).
+  gossip-interval-seconds = 60
+}
+
+# Chain-wide consensus params (n-nodes, block-time, quiescence, ...) come from the
+# included chain spec — do NOT set them here, they must stay byte-identical on every
+# node. Only node-local knobs below.
+ce.evolver.consensus {
+  validate-chain-on-startup = false
+
+  # Reactivity (node-local, always on since #28): on incoming work the leader proposes
+  # IMMEDIATELY rather than waiting out the (5-minute) idle heartbeat — tx latency stays
+  # sub-second despite slow idle.
+  wake-on-work {
+    forward-watermark = 16
+  }
+}
+
+data.base       = "/data/chain"
+state.snapshots = "snapshots"
+# PLAIN HTTP on 8440 for everything that TALKS to this node, deliberately. The HTTPS
+# listener presents the node's IDENTITY certificate — self-signed, and valid for ~13
+# MINUTES, because it is a peer authentication credential and not a web certificate. No
+# browser can be made happy with that: an exception you click through expires before you
+# finish reading the page. Tolerating it in code means NODE_TLS_REJECT_UNAUTHORIZED=0,
+# which disables verification PROCESS-WIDE for every host — a bad habit to ship in a
+# template.
+#
+# TLS on 8441 for PEERS, because the content cache needs somewhere mTLS to live: its peer
+# route identifies callers by client certificate and the node refuses to start content
+# without a TLS listener. Before evolver v0.16.0 those were the same listener, so
+# "hold documents" and "put every client on an unpinnable certificate" were one decision.
+# They are not, and this is what that separation looks like in a deployment.
+http.port       = 8440
+# ⚠️ REQUIRED since evolver #131: the plain API listener now defaults to 127.0.0.1. The app
+# container reaches this node over the CONTAINER NETWORK, which is not loopback from the
+# node's point of view — without this line the app gets connection refused and the node
+# logs nothing unusual. "0.0.0.0" is what this deployment effectively had before.
+http.bind-host  = "0.0.0.0"
+https.port      = 8441
+evolver.grpc.port = 9000
+
+# 139 — CONTENT, so a detail document announced on this chain can actually be fetched.
+#
+# `bind-host` is what lets a SIBLING CONTAINER reach the publish/read route: it is
+# authorized by what can reach it, and the default (loopback) means "inside this node's
+# container and nowhere else". 0.0.0.0 here says: this compose project's network is the
+# boundary. It holds because the port below is published to 127.0.0.1 only.
+ce.evolver.content {
+  enabled   = true
+  http-port = 8450
+  bind-host = "0.0.0.0"
+}
+
+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
+}
+ce.evolver.execution.enabled = false