feat: add shadow LangGraph orchestrator runtime

services/orchestrator/README.md

@@ -29,7 +29,7 @@ Memind-facing protocol is `orchestrator-run-v1` plus `orchestrator-event-v1`.
 
 ## Current stage
 
-Phase 1 establishes:
+Phase 1 established:
 
 - framework-neutral run and event contracts;
 - a plug-in workflow engine registry;
@@ -38,9 +38,19 @@ Phase 1 establishes:
 - deterministic Off / Shadow / Canary / Active routing decisions;
 - an environment-level emergency kill switch.
 
-The default mode is `off`. No production task is routed to LangGraph in this
-phase. Runtime dispatch wiring and a separately deployed Orchestrator worker are
-subsequent phases.
+Phase 2 adds:
+
+- a real LangGraph `StateGraph` service on the versioned HTTP boundary;
+- a PostgreSQL `PostgresSaver` checkpoint owner;
+- an explicitly non-durable MemorySaver option for tests and local debugging;
+- a `code-run-v1` observe-only graph with no executor or tool access;
+- a Portal fire-and-forget shadow projection;
+- live health probing from memindadm;
+- a separate Colima/Compose deployment artifact.
+
+The default memindadm mode remains `off`. Canary and Active routing are not
+wired to the LangGraph executor in Phase 2. Native Agent Run remains the sole
+executor, including in Shadow mode.
 
 ## Admin configuration
 
@@ -55,6 +65,62 @@ Supported modes:
 
 `MEMIND_ORCHESTRATOR_KILL_SWITCH=1` always forces Native selection.
 
+## Local process
+
+PostgreSQL is the default and required checkpoint backend:
+
+```bash
+MEMIND_ORCHESTRATOR_DATABASE_URL='postgresql://...' \
+MEMIND_ORCHESTRATOR_SERVICE_TOKEN='...' \
+pnpm dev:orchestrator
+```
+
+Memory mode is intentionally opt-in and non-durable:
+
+```bash
+MEMIND_ORCHESTRATOR_CHECKPOINT_MODE=memory pnpm dev:orchestrator
+```
+
+The service binds to `127.0.0.1:8093` by default. Configure the same URL and
+service token in Portal, then enable `shadow` in `/ops/admin/orchestrator`.
+
+## Colima deployment
+
+Colima is the recommended first container host on macOS because this service and
+its PostgreSQL checkpoint database have an isolated Compose lifecycle:
+
+```bash
+cd deploy/orchestrator
+cp .env.example .env
+# Replace both example secrets before starting.
+docker compose up -d --build
+docker compose ps
+curl http://127.0.0.1:8093/ready
+```
+
+The Compose project:
+
+- publishes only the Orchestrator port on loopback;
+- does not publish PostgreSQL;
+- does not mount the Docker socket or a Memind workspace;
+- keeps PostgreSQL on a dedicated internal network while the service also joins
+  a separate edge network for its loopback-published port;
+- is not part of the Goosed Compose lifecycle.
+
+This local Compose artifact is not a production release path. Production still
+requires the repository release gates and a separately approved deployment.
+
+## Runtime environment
+
+| Variable | Purpose | Default |
+|---|---|---|
+| `MEMIND_ORCHESTRATOR_HOST` | HTTP bind address | `127.0.0.1` |
+| `MEMIND_ORCHESTRATOR_PORT` | HTTP port | `8093` |
+| `MEMIND_ORCHESTRATOR_SERVICE_TOKEN` | Bearer token for `/v1/*` | empty |
+| `MEMIND_ORCHESTRATOR_CHECKPOINT_MODE` | `postgres` or explicit `memory` | `postgres` |
+| `MEMIND_ORCHESTRATOR_DATABASE_URL` | Dedicated checkpoint PostgreSQL URL | required |
+| `MEMIND_ORCHESTRATOR_DATABASE_SCHEMA` | Checkpoint schema | `memind_orchestrator` |
+
 ## Extraction test
 
 The service is ready to move into a separate repository only when: