@mcsherrylabs/evolver-mcp 0.9.5 → 0.10.0

package/deploy/.dockerignore

@@ -0,0 +1,8 @@
+.git
+node_modules
+dist
+.ci-sdk
+.env
+.env.*
+**/.env
+**/.env.*

package/deploy/Dockerfile

@@ -8,9 +8,9 @@
 # idea of `/workspace` is a different directory than the container's, so `./config` is empty and
 # the node boots with `/config/node-join.sh: No such file`. Baking removes the path entirely.
 
-ARG EVOLVER_REGISTRY=nexus.mcsherrylabs.com
-ARG EVOLVER_VERSION=v0.24.7
-FROM ${EVOLVER_REGISTRY}/evolver-node:${EVOLVER_VERSION}
+# Explicit coordinated candidate: v0.24.7 lacks processor-state observation.
+ARG EVOLVER_NODE_IMAGE
+FROM ${EVOLVER_NODE_IMAGE}
 
 # The static, chain-identity configs. node.conf references these by absolute path and
 # node-join.sh execs `-Dconfig.file=/config/node.conf`, so /config is their fixed home.

package/deploy/config/node-join.sh

@@ -1,8 +1,8 @@
 #!/bin/sh
-# Claim-then-boot (evolver feature 102), the pattern from the evolver repo's
-# deployments/group-chat/app-node-init.sh, made publishable: nothing is bind-mounted and
-# the node id is derived rather than required, so this artifact runs in an empty
-# directory with no arguments.
+# 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
@@ -10,6 +10,22 @@
 # 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
@@ -51,6 +67,12 @@ else
   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.
   #
@@ -159,76 +181,12 @@ set -a
 set +a
 
 mkdir -p /data/chain
-# ⚠️ THE AGENT WRITES HERE TOO, as uid 1000, not as this node's uid (10001). Without o+rwx on
-# the directory the agent gets EACCES creating the file at all. The Docker socket already grants
-# equivalent access (docker exec), so this does not widen the effective boundary.
-chmod o+rwx /data/chain
-
-# ── WHICH CHANNELS THIS NODE DECLARES ─────────────────────────────────────
-#
-# ONE decision, in ONE place, keyed on the SAME switch the app uses. The node config
-# `include required`s this file, so if the write below ever fails the node refuses to
-# start instead of quietly declaring nothing (HOCON ignores an absent optional include,
-# and a node that declares no channels retains no bodies, streams nothing and delivers
-# nothing — while logging nothing unusual).
-#
-# The registry's channel is declared IFF a registry is deployed here. Declaring it
-# otherwise wedges this node's apply on the first transaction written to a channel it is
-# not a DA member of: nothing stores the body, nothing can pull it, and apply is
-# forward-only (evolver#83).
-# ⚠️ A SUBSCRIPTION IS HOW THIS COMPONENT GAINS A CAPABILITY, not a configuration detail. Each
-# ledger declared here is something the component can then process, index and act on — the set grows
-# as its owner's interests do.
-#
-# The precondition is not optional: this node must be able to OBTAIN the bodies. A channel with a DA
-# policy serves them from its DA group, so this node needs a live connection to a member — otherwise
-# apply blocks on the first body it cannot fetch, PERMANENTLY, because apply is forward-only
-# (evolver#83). For `ce.meerkat.announcements` that group is `evolvermeerkatA286174reg`, whose only
-# member is `appnode046550` — which this node discovers and dials.
-#
-# ⚠️ THIS LIST IS MERGED, NEVER REPLACED. `meerkat_add_channel` writes the same file when the
-# agent subscribes to something, so the file is the union of two writers: this deployment's
-# channel, which is a property of the deployment, and whatever the agent has since subscribed
-# to, which is a property of its work. A boot that rewrote the list from EVOLVER_CHANNEL alone
-# would silently revoke every capability the agent had gained — including the reply channel it
-# is waiting on — and the agent has no way to notice: the file it wrote is simply gone.
-#
-# ⚠️ AND IT IS WRITTEN tmp-THEN-RENAME, chmod 666. Two uids write this one file, and a plain
-# `>` redirect must open the EXISTING file for writing: whichever of them creates it owns a
-# 0644 the other then cannot truncate, for as long as the file lives. That is not theoretical —
-# it wedged a node in a restart loop (`cannot create /data/chain/channels.conf: Permission
-# denied`), and because `include required` makes the node refuse to start rather than declare
-# nothing, the whole stack came down with it. `mv` needs write on the DIRECTORY, which the
-# o+rwx above grants both, so the rename lands whoever owns the old file; the 666 then lets
-# the agent's direct `writeFileSync` land too.
-# ⚠️ THE MCP CONSUMES NO CHANNEL STREAM, so the node declares NO channel by default
-# (`EVOLVER_CHANNEL` defaults empty). The `include required` of `channels.conf` in node.conf still
-# needs the file to EXIST, so an empty list is written below rather than the file being omitted.
-_ch="${EVOLVER_CHANNEL:-}"
-_conf=/data/chain/channels.conf
-_existing=""
-if [ -f "$_conf" ]; then
-  # the HOCON this file ever contains is one list on one line, written by this script or by
-  # pi-meerkat's formatHocon — strip to the bare comma-separated ids.
-  _existing=$(sed -n 's/.*\[\(.*\)\].*/\1/p' "$_conf" | tr -d ' "')
-fi
-_merged="$_ch"
-for _c in $(echo "$_existing" | tr ',' ' '); do
-  [ -n "$_c" ] || continue
-  [ "$_c" = "$_ch" ] && continue
-  _merged="$_merged,$_c"
-done
-# An empty channel set becomes `[]`, not `[""]` — the node declares no subscribed channel, which
-# is correct for a reader that owns no channel stream.
-if [ -z "$_merged" ] || [ -z "${_merged##*,}" ]; then
-  _body="[]"
-else
-  _body="[ $(echo "$_merged" | sed 's/,/", "/g; s/^/"/; s/$/"/') ]"
-fi
-echo "[node-join] declaring channels: $_merged"
-printf 'ce.evolver.subscribed-channels = %s\n' "$_body" > "$_conf.node.tmp"
-chmod 666 "$_conf.node.tmp"
-mv -f "$_conf.node.tmp" "$_conf"
+# 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 ───────────────────────────────────────────
 #

package/deploy/config/node.conf

@@ -120,54 +120,12 @@ ce.evolver.consensus {
 # 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.
-# ⚠️ OFF. This is a READER, and processing mode is what a node running an APP turns on.
-#
-# In processing mode apply is DEFERRED and paced by the app polling /api/channel/next, so
-# committed reads answer "as of MY cursor" rather than "as of the chain". With no channels
-# declared and no consumer draining — which is exactly this node — the cursor never advances and
-# NOTHING IS EVER APPLIED: the node syncs every block and still answers `not_found` for an identity
-# the chain committed. Observed here: its own identity, committed at block 7225 and verified on
-# chain, was unknown to it at height 7231.
-#
-# ⚠️ ON, NOW THAT SOMETHING DRAINS THIS NODE. The rule is not "readers off, apps on" — it is that
-# processing mode paces apply from whatever drains /api/channel/next, so it is correct exactly when
-# there IS a drainer and catastrophic when there is not (with none, this node synced every block and
-# still answered `not_found` for an identity it had itself committed).
-#
-# The meerkat registry beside it is that drainer. Its polling is what advances apply, so the agent's
-# reads stay correct — as of that cursor, which is what a component reading its own processed state
-# means by correct.
+# 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}
-# ⚠️ THE CHANNEL LIST IS GENERATED BY node-join.sh, and `include required` means this node
-# REFUSES TO START if the fragment is missing rather than silently declaring nothing.
-#
-# It cannot be written here, because WHICH channels this node declares depends on whether
-# a registry is deployed beside it — and declaring one that is not wanted is not harmless:
-#
-#   the registry's channel is declared by the node so it can STORE and ATTEST bodies
-#   (`onBody` drops a flooded body for an undeclared channel, and a body it never stored
-#   is one it cannot attest — at m=1 that stops the registry rather than degrading it);
-#
-#   but a node that declares a channel it is NOT a DA member of STALLS at every transaction
-#   on that channel. `channelSubscribes` is false, so it stores no body, and nothing can be
-#   pulled either (the DA group's members are identities, not this node's peers), so the
-#   position answers `body-pending` and the cursor sits ON it — applied state, and every
-#   committed read, frozen at the block before it.
-#
-#   ⚠️ NOT a permanent wedge of the NODE, and evolver#83 was corrected on exactly this
-#   point: the runner advances the cursor atomically with the apply and the body lookup
-#   happens afterwards, so a CONSUMER that asks for `index + 1` walks past and the skipped
-#   transaction is still applied in the slice. What is permanent is the LOSS of that
-#   message. So the stall lasts as long as the consumer retries the same position — which
-#   the SDK's `drainChannel` does, correctly, for at-most-once delivery — and it is
-#   reachable by anyone willing to spend 10 credits on an id-only write to an unclaimed
-#   name. Declaring only what this deployment participates in avoids the whole question.
-#
-# In demo mode this node is not in the registry channel's DA group — nothing here claimed
-# it — so declaring it was exactly that hazard. The switch is PROCESSOR_HTTP_PORT (named
-# REGISTRY_HTTP_PORT before meerkat v0.6.0), the same one the app uses to decide it is a
-# service, so the two cannot disagree.
-include required(file("/data/chain/channels.conf"))
+# 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"))

package/deploy/docker-compose.yml

@@ -1,120 +1,136 @@
-# Evolver devnet-follower NODE + the evolver-mcp stdio server's launch context.
-#
-# One `docker compose -f deploy/docker-compose.yml up -d` starts a LOCAL Evolver node that
-# JOINS and syncs the live devnet chain (it is a non-genesis follower, not a new chain), and the
-# env contract an agent runtime supplies when it launches `npx -y @mcsherrylabs/evolver-mcp`
-# against that node.
-#
-# CONTENT LIVES HERE, NOT ON DEVNET. The MCP posts to and reads from THIS node's own content
-# cache (`ce.evolver.content.http-port = 8450`) via `EVOLVER_CONTENT_URL=http://node:8450`. The
-# devnet URL is only the FAUCET origin for the node's first-boot identity claim; every other call
-# is against the local node (`node:8440` chain API, `node:8450` content).
-#
-# GROUNDING — mirror /workspace/evolver/deployments/claude-agent/, the canonical follower pattern:
-#  - genesis.devnet.conf is a BYTE-IDENTICAL copy of the devnet genesis (committee + seed nodes).
-#    It is the chain's identity; never edit it.
-#  - node-join.sh is the claim-then-boot entrypoint: mint node keys locally, faucet-claim the
-#    identity on devnet (the committee sponsors it), persist the claim, then start as a non-genesis
-#    follower syncing from block 0.
-#  - node.conf includes genesis + peers.conf + channels.conf; content 8450, chain API 8440, TLS
-#    8441 (peer content fetches), gRPC 9000.
-#
-# THE MCP IS STDIO, NOT A LONG-RUNNING SERVICE. There is no published evolver-mcp image; an agent
-# runtime (Claude Code / Codex) launches it per session as a child process. The `mcp` service below
-# only documents the exact env contract (see the comment on it). For dockerized use, build from
-# docs/mcp.Dockerfile and exec `docker compose run --rm mcp npx -y @mcsherrylabs/evolver-mcp …`.
-
+# Managed paired composition. Run fresh initialization explicitly through `evolver-mcp install
+# --new`; ordinary up/restart NEVER runs processor-init or seeds subscriptions.
+# Candidate node image, SDK archive/hash and known genesis/node binding are mandatory.
 name: evolver-mcp
 
+x-processor-image: &processor-image
+  image: ${EVOLVER_PROCESSOR_IMAGE:?explicit local candidate processor image tag required}
+  build:
+    context: ./processor
+    dockerfile: Dockerfile
+    additional_contexts:
+      sdk-candidate: ${EVOLVER_PROCESSOR_SDK_DIR:?directory containing exact sdk.tgz required}
+    args:
+      EVOLVER_PROCESSOR_SDK_SHA256: ${EVOLVER_PROCESSOR_SDK_SHA256:?exact SDK archive SHA256 required}
+
 services:
-  # ── the LOCAL devnet follower ──────────────────────────────────────────────
+  # Explicit fresh-resource operation only; NEVER a dependency of node/processor/up.
+  processor-init:
+    <<: *processor-image
+    profiles: ["initialize-only"]
+    user: "0:0"
+    command: ["initialize"]
+    environment:
+      EVOLVER_OPERATOR_UID: ${EVOLVER_OPERATOR_UID:?operator uid required}
+      EVOLVER_OPERATOR_GID: ${EVOLVER_OPERATOR_GID:?operator gid required}
+      EVOLVER_INITIAL_CHANNELS: ${EVOLVER_INITIAL_CHANNELS:-[]}
+    volumes:
+      - subscriptions:/subscriptions
+      - processor-state:/processor-state
+    restart: "no"
+    network_mode: none
+
   node:
-    # Build FROM the pinned evolver-node and bake /config in (see deploy/Dockerfile). No bind
-    # mount: the daemon resolves host paths, and `install` may run in a container whose /workspace
-    # differs from the host's. `--build` is passed by the install so a fresh machine builds it.
+    container_name: ${EVOLVER_MANAGED_NODE_CONTAINER:?saved fixed node container required}
     build:
       context: .
       dockerfile: Dockerfile
       args:
-        EVOLVER_REGISTRY: ${EVOLVER_REGISTRY:-nexus.mcsherrylabs.com}
-        EVOLVER_VERSION: ${EVOLVER_VERSION:-v0.24.7}
-    image: evolver-mcp-node:latest
+        EVOLVER_NODE_IMAGE: ${EVOLVER_NODE_IMAGE:?candidate node image with processor-state observation required}
+    image: ${EVOLVER_MANAGED_NODE_IMAGE:?explicit local config-bearing candidate node image tag required}
     restart: unless-stopped
+    group_add: ["${EVOLVER_OPERATOR_GID:?operator group required}"]
     environment:
-      # The node claims its OWN identity (node keys never leave this container) and persists the
-      # name to /data/keys/node-id. `<APP_NAME>node<random6>` keeps a shared chain collision-free.
-      APP_NAME: evolverscp
-      # FAUCET ONLY — the first-boot claim target. Not the chain URL the MCP talks to.
+      APP_NODE_ID: ${APP_NODE_ID:?saved known node id required}
+      APP_NAME: evolvermcp
       DEVNET_API: ${DEVNET_API:-https://devnet.mcsherrylabs.com}
-      # THE MCP READS NO CHANNEL STREAM, so the node declares NO channel. Empty on purpose: a node
-      # that declares a channel it is not a DA member of stalls its apply (evolver#83).
-      EVOLVER_CHANNEL: ${EVOLVER_CHANNEL:-}
-      # ⚠️ PIN A FRONT/SEED NODE, NOT THE COMMITTEE. `devnet1-node0` runs `allowed-inbound = 2`
-      # with both slots reserved; pinning it cannot work (every dial is refused).
       EVOLVER_UPSTREAM_NODE_ID: ${EVOLVER_UPSTREAM_NODE_ID:-evolvermeerkatnode920080}
       EVOLVER_DA_PEERS: ${EVOLVER_DA_PEERS:-schednode2}
       EVOLVER_ALLOWED_OUTBOUND: ${EVOLVER_ALLOWED_OUTBOUND:-16}
-      # ⚠️ PROCESSING MODE STAYS OFF. Apply would be paced by whatever drains /api/channel/next;
-      # with no drainer the cursor never advances and committed reads answer not_found. A reader
-      # with no channel owns no stream, so leave this unset (the config's `?` makes it optional).
-      #
-      # (Deliberately ABSENT, not "false": the config reads `ce.evolver.execution.enabled = ${?EVOLVER_EXECUTION_ENABLED}`
-      #  — unset means "off", which is exactly a reader node.)
-      # p2p transport on 7100, NOT 7000 (most devnet discovery entries advertise 127.0.0.1:7000,
-      # which a node on 7000 would dial into its own loopback).
+      # Enabled ONLY in this node + persistent shared consumer composition.
+      EVOLVER_EXECUTION_ENABLED: "true"
       EVOLVER_NODE_PORT: "7100"
     volumes:
       - node-data:/data
-    # INVOKED VIA /bin/sh (a baked script's exec bit is irrelevant; node-join.sh is COPYed into
-    # /config by the Dockerfile, not bind-mounted, so no checkout file-mode concerns).
+      # Whole DIRECTORY, read-only for node; atomic controller rename is visible on restart.
+      - subscriptions:/subscriptions:ro
     entrypoint: ["/bin/sh", "/config/node-join.sh"]
     healthcheck:
-      test: ["CMD-SHELL", "curl -sf http://127.0.0.1:8440/api/explorer/blocks?limit=1 >/dev/null || exit 1"]
+      # Process/API health, NOT collection readiness (the processor /ready checks that separately).
+      test: ["CMD-SHELL", "curl -sf http://127.0.0.1:8440/status >/dev/null || exit 1"]
       interval: 10s
       timeout: 5s
       retries: 30
       start_period: 30s
-    # ⚠️ PUBLISHED LOOPBACK-ONLY (B1: the frictionless single-box install path). The host-side
-    # `npx … install` bootstrap reaches the node at http://127.0.0.1:${EVOLVER_HOST_HTTP_PORT:-8440}
-    # (chain API) and http://127.0.0.1:${EVOLVER_HOST_CONTENT_PORT:-8450} (content) after `up -d
-    # node`. Nothing leaves the machine: `host_ip: 127.0.0.1` keeps both listeners local, and the
-    # node's p2p/TLS listeners stay unpublished (they are for PEERS, reached over the compose
-    # network's DNS).
-    #
-    # TWO NODES ON ONE HOST: the node ALWAYS binds 8440/8450 internally (node.conf, baked into the
-    # image — not env-overridable), so `target` stays fixed at those; only the PUBLISHED host port
-    # varies. Give a second install non-clashing host ports via
-    #   EVOLVER_HOST_HTTP_PORT=8442 EVOLVER_HOST_CONTENT_PORT=8451 COMPOSE_PROJECT_NAME=evolver-mcp2
-    # and `install` must be run with the SAME two values (it polls + bootstraps against them).
     ports:
       - target: 8440
         published: "${EVOLVER_HOST_HTTP_PORT:-8440}"
         host_ip: 127.0.0.1
-        protocol: tcp
       - target: 8450
         published: "${EVOLVER_HOST_CONTENT_PORT:-8450}"
         host_ip: 127.0.0.1
-        protocol: tcp
 
-  # ── the MCP launch context (documentation only) ─────────────────────────────
-  # evolver-mcp is a STDIO server launched per session by an agent runtime — NOT a long-running
-  # compose service. This service exists to (a) pin the exact env contract and (b) give a
-  # containerized operator a `docker compose run --rm mcp …` target. `depends_on` documents that
-  # the node must be healthy before an MCP launch, since the MCP probes and exits if unreachable.
-  mcp:
-    image: node:22
-    profiles: ["run-only"]           # not started by `up -d`; a run-target only
+  processor:
+    <<: *processor-image
+    # One fixed service/owner per node. Never scale this service; SDK owner lock rejects a second.
+    container_name: ${EVOLVER_MANAGED_PROCESSOR_CONTAINER:?saved fixed processor container required}
+    user: "${EVOLVER_OPERATOR_UID:?operator uid required}:${EVOLVER_OPERATOR_GID:?operator gid required}"
+    restart: unless-stopped
     environment:
-      # Chain API — the LOCAL node, not devnet.
-      EVOLVER_MCP_CONFIG: "/state/config.json"
-      # Content listener — the LOCAL node's content cache, a SEPARATE port from the chain API.
-      EVOLVER_CONTENT_URL: "http://node:8450"
-      EVOLVER_KEY_PATH: "/state/<identity>.key"
-      EVOLVER_KEY_TYPE: "bls"
+      EVOLVER_CHAIN_ID: ${EVOLVER_CHAIN_ID:?known genesis block id required}
+      APP_NODE_ID: ${APP_NODE_ID:?saved known node id required}
+      EVOLVER_MANAGED_NODE_CONTAINER: ${EVOLVER_MANAGED_NODE_CONTAINER:?fixed target required}
+    volumes:
+      - subscriptions:/subscriptions
+      - processor-state:/processor-state
+      # Private operator directory; no signing keys or node database mounted into this service.
+      - type: bind
+        source: ${EVOLVER_CONTROL_HOST_DIR:?daemon-host private operator directory required}
+        target: /control
+        bind:
+          create_host_path: false
+      # Privileged composition ONLY. MCP has no Docker socket, config fragment, or restart target.
+      - /var/run/docker.sock:/var/run/docker.sock
+    group_add: ["${EVOLVER_DOCKER_GID:?Docker socket group id required for fixed restarter}"]
     depends_on:
       node:
+        # Private reconciliation control must start even while the configured node is offline.
+        # The SDK runtime gates ALL pulls on fresh binding/processing/ACTIVE observations.
+        condition: service_started
+    healthcheck:
+      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:8090/health').then(r=>process.exit(r.status===200?0:1)).catch(()=>process.exit(1))"]
+      interval: 10s
+      timeout: 5s
+      retries: 12
+    ports:
+      - target: 8090
+        published: "${EVOLVER_HOST_INBOX_PORT:-8090}"
+        host_ip: 127.0.0.1
+
+  # Per-session reader/control launch context only; never started by ordinary up.
+  # Supply only agent state at /state separately. NEVER mount subscriptions/node-data/Docker here.
+  mcp:
+    image: node:22.23.3-bookworm-slim
+    user: "${EVOLVER_OPERATOR_UID:?operator uid required}:${EVOLVER_OPERATOR_GID:?operator gid required}"
+    profiles: ["run-only"]
+    environment:
+      EVOLVER_MCP_CONFIG: /state/config.json
+      EVOLVER_CONTENT_URL: http://node:8450
+      EVOLVER_KEY_PATH: /state/<agent-identity>.key
+      EVOLVER_KEY_TYPE: bls
+    volumes:
+      - type: bind
+        source: ${EVOLVER_CONTROL_HOST_DIR:?daemon-host private operator directory required}
+        target: /control
+        read_only: true
+        bind:
+          create_host_path: false
+    depends_on:
+      processor:
         condition: service_healthy
     restart: "no"
 
 volumes:
   node-data:
+  subscriptions:
+  processor-state:

package/deploy/processor/.dockerignore

@@ -0,0 +1,8 @@
+.git
+node_modules
+dist
+.ci-sdk
+.env
+.env.*
+**/.env
+**/.env.*

package/deploy/processor/Dockerfile

@@ -0,0 +1,14 @@
+# syntax=docker/dockerfile:1
+# Exact runtime and hash-verified SDK archive, prepared from the pinned release by CI.
+FROM node:22.23.3-bookworm-slim
+WORKDIR /app
+ARG EVOLVER_PROCESSOR_SDK_SHA256
+COPY --from=sdk-candidate /sdk.tgz /candidate/sdk.tgz
+RUN --mount=type=cache,id=evolver-release-npm,target=/root/.npm test -n "$EVOLVER_PROCESSOR_SDK_SHA256" && \
+    printf '%s  /candidate/sdk.tgz\n' "$EVOLVER_PROCESSOR_SDK_SHA256" | sha256sum -c - && \
+    printf '{"private":true,"type":"module"}\n' > package.json && \
+    npm install --omit=dev --ignore-scripts --no-save /candidate/sdk.tgz && \
+    rm -rf /candidate
+COPY entrypoint.mjs /app/entrypoint.mjs
+ENTRYPOINT ["node", "/app/entrypoint.mjs"]
+CMD ["serve"]

package/deploy/processor/entrypoint.mjs

@@ -0,0 +1,122 @@
+// Deployment composition only. All collection/storage/config/restart algorithms live in the SDK.
+import { NodeClient } from "@mcsherrylabs/evolver-client";
+import { initializeSubscriptions, subscriptionConfig, startProcessor, subscriptionController,
+  startReadServer, startControlServer, dockerNodeRestarter, nodeObserver, nodePuller,
+  deadlineFetch, position, PROCESSOR_NODE_VERSION, recoverProcessorOwnerLock } from "@mcsherrylabs/evolver-client/processor";
+import { pathToFileURL } from "node:url";
+import { mkdir, chown, chmod, readdir } from "node:fs/promises";
+
+const STATE_PATH = "/processor-state/inbox.sqlite";
+
+export function settingsFrom(env) {
+  const binding = { chainId: env.EVOLVER_CHAIN_ID, nodeId: env.APP_NODE_ID };
+  // The binding is operator-provisioned and is independently checked by every SDK observation.
+  const observe = nodeObserver({ baseUrl: "http://node:8440", binding, timeoutMs: 5000 });
+  return { binding, observe, configPath: "/subscriptions/channels.conf", statePath: STATE_PATH,
+    controlPath: "/control/control.sock", port: 8090,
+    containerName: env.EVOLVER_MANAGED_NODE_CONTAINER };
+}
+
+export async function initialize(env) {
+  const uid = Number(env.EVOLVER_OPERATOR_UID), gid = Number(env.EVOLVER_OPERATOR_GID);
+  if (![uid, gid].every(id => Number.isSafeInteger(id) && id >= 1))
+    throw new Error("fresh initializer requires explicit non-root operator uid/gid");
+  for (const dir of ["/subscriptions", "/processor-state"]) {
+    if ((await readdir(dir)).length !== 0) throw new Error("fresh initialization refuses nonempty managed volumes; no migration/reseed");
+  }
+  for (const dir of ["/subscriptions", "/processor-state"]) {
+    await mkdir(dir, { recursive: true }); await chown(dir, uid, gid); await chmod(dir, 0o750);
+  }
+  process.setgroups([]); process.setgid(gid); process.setuid(uid);
+  const defaults = JSON.parse(env.EVOLVER_INITIAL_CHANNELS ?? "[]");
+  // This command is invoked ONLY by explicit fresh-install initialization, never service startup.
+  await initializeSubscriptions("/subscriptions/channels.conf", defaults);
+}
+
+export function recoverManagedOwner(settings, args, 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("[processor] WARNING: --force acknowledges ALL collectors are stopped and automatic restarts disabled; this command cannot verify that.");
+  const result = recoverProcessorOwnerLock({ path: settings.statePath, force: true });
+  say(`[processor] ${result.removed ? "Removed owner lock" : "No owner lock present"}: ${result.marker}. Database/WAL, progress, subscriptions and keys unchanged. Start ONE collector normally to acquire a new lock.`);
+  return result;
+}
+
+export async function startManagedProcessor(settings, sdk = {
+  NodeClient, subscriptionConfig, startProcessor, subscriptionController, startReadServer,
+  startControlServer, dockerNodeRestarter, nodePuller, deadlineFetch,
+}) {
+  const config = sdk.subscriptionConfig(settings.configPath);
+  await config.read(); // missing initialized declaration is a refusal, never defaults/[]
+  const client = new sdk.NodeClient({ baseUrl: "http://node:8440", fetch: sdk.deadlineFetch(5000,
+    (input, init) => fetch(input, { ...init, redirect: "error" })) });
+  const runtime = await sdk.startProcessor({
+    store: { path: settings.statePath, binding: settings.binding, modules: [] },
+    modules: [], config, observe: settings.observe, puller: sdk.nodePuller(client),
+    tip: async () => position(String(await client.currentRound()), "0").round,
+    say: message => console.error(`[processor] ${message}`),
+  }).catch(error => {
+    if (error?.name === "ProcessorOwnerLockError") {
+      console.error(`[processor] ${error.message}`);
+      console.error("[processor] MANUAL FORCE RECOVERY REQUIRED if the owner has died. Using the SAME Compose project/env/files/volumes: 1) docker compose stop processor; stop any other collectors and disable all external automatic restarts. 2) Only when fenced: docker compose run --rm --no-deps processor recover-owner --force. 3) docker compose up -d --no-deps processor. An ordinary restart or --force-recreate does NOT clear the lock. Never delete the database/WAL or reinitialize subscriptions.");
+    }
+    throw error;
+  });
+  let read, control, stopping, loopStarted = false;
+  function stop() {
+    return stopping ??= (async () => {
+      const errors = [];
+      for (const close of [
+        ...(control ? [() => control.close()] : []),
+        ...(read ? [() => read.close()] : []),
+        () => runtime.stop(),
+      ]) {
+        try { await close(); } catch (error) { errors.push(error); }
+      }
+      if (errors.length) throw new AggregateError(errors, "managed processor cleanup failed");
+    })();
+  }
+  try {
+    // Control must survive unavailable/mismatched ACTIVE state so identical SET can reconcile.
+    // The shared runtime alone decides whether pacing is authorized; health reads never pace.
+    const controller = sdk.subscriptionController({ binding: settings.binding, config, runtime,
+      observe: settings.observe, restart: sdk.dockerNodeRestarter({ socketPath: "/var/run/docker.sock",
+        containerName: settings.containerName }), timeoutMs: 30000 });
+    read = await sdk.startReadServer({ store: runtime.store, host: "0.0.0.0", port: settings.port,
+      routes: [
+        { path: "/health", handle: async () => ({ status: 200, json: { binding: settings.binding, process: "running" } }) },
+        { path: "/ready", handle: async () => {
+          const state = await controller.inspect();
+          const ready = loopStarted && state.outcome === "active" && runtime.lastError === null;
+          return { status: ready ? 200 : 503, json: { binding: settings.binding, collectionReady: ready,
+            subscriptions: state, lastError: runtime.lastError,
+            note: "Ready means verified ACTIVE processing subscriptions and the running shared loop has no reported error; not proof of successful first delivery, caught-up, historical replay or availability of pending bodies." } };
+        } },
+      ] });
+    control = await sdk.startControlServer({ socketPath: settings.controlPath, mode: 0o660, controller });
+    runtime.run();
+    loopStarted = true;
+    return { stop };
+  } catch (e) {
+    try { await stop(); }
+    catch (cleanup) { throw new AggregateError([e, cleanup], "managed processor startup and cleanup failed"); }
+    throw e;
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  if (process.versions.node !== PROCESSOR_NODE_VERSION)
+    throw new Error(`managed processor requires Node ${PROCESSOR_NODE_VERSION}`);
+  if (process.argv[2] === "initialize") await initialize(process.env);
+  else if (process.argv[2] === "recover-owner") recoverManagedOwner({ statePath: STATE_PATH }, process.argv.slice(3));
+  else if (process.argv[2] === "serve") {
+    const service = await startManagedProcessor(settingsFrom(process.env));
+    let stopping = false;
+    const stop = () => {
+      if (stopping) return;
+      stopping = true;
+      service.stop().then(() => process.exit(0), error => { console.error(error); process.exit(1); });
+    };
+    process.once("SIGTERM", stop); process.once("SIGINT", stop);
+  } else throw new Error("expected explicit initialize, serve, or recover-owner --force command");
+}

package/deploy/release.json

@@ -0,0 +1,8 @@
+{
+  "nodeImage": "nexus.mcsherrylabs.com/evolver-node:v0.25.0",
+  "images": {
+    "processor": "evolver-mcp-processor",
+    "node": "evolver-mcp-node",
+    "cli": "evolver-mcp"
+  }
+}

package/dist/bootstrap.d.ts

@@ -1,5 +1,6 @@
 import { NodeClient } from "@mcsherrylabs/evolver-client";
 import type { Identity, ClaimResult } from "@mcsherrylabs/evolver-client";
+import type { ProcessorClientOptions } from "@mcsherrylabs/evolver-client/processor-client";
 export declare const BOOTSTRAP_FLAG = "--bootstrap";
 export declare const RETRYABLE_CLAIM_ERRORS: readonly ["node_not_ready", "queue_full", "confirmation_timeout", "internal"];
 export declare const DEFAULT_RETRY_MAX = 3;
@@ -99,6 +100,8 @@ export interface BootstrapPlan {
     readonly identity: GeneratedIdentity;
     readonly contentUrl: string;
     readonly contentWarning: string;
+    /** Explicit operator/managed-installer pairing; never inferred from target/locality. */
+    readonly processor?: ProcessorClientOptions;
     /** The command-line working directory (for the `.target`/`.env*` refusal of `--target local`). */
     readonly cwd: string;
     /** The REALPATH'd server entry (`dist/index.js`) — the ONLY canonicalised value; derived once. */
@@ -167,6 +170,7 @@ export declare function keyFileFor(identity: Identity): string;
 export declare function configFor(opts: {
     name: string;
     chainUrl: string;
+    processor?: ProcessorClientOptions;
 }): string;
 export declare function identityFromSeed(seed: SeedRecord): Identity;
 export type ReadSeedResult = {