feat: add pluggable workflow orchestrator controls

2026-07-24 20:59:01 +08:00
parent 3fd1db8c2f
commit 46ea22b342
16 changed files with 1327 additions and 2 deletions
@@ -0,0 +1,66 @@
+# Memind Workflow Orchestrator
+
+This directory is the extraction boundary for Memind's durable workflow runtime.
+It is intentionally source-colocated with Memind while remaining framework-neutral
+at its public edge.
+
+## Dependency rule
+
+Allowed:
+
+```text
+Memind -> orchestrator contracts / client
+Orchestrator -> contracts / executor adapters
+Executor adapters -> versioned internal APIs
+```
+
+Forbidden:
+
+```text
+Orchestrator -> server.mjs
+Orchestrator -> user-auth.mjs
+Orchestrator -> Memind business tables
+Orchestrator -> production filesystem paths
+Memind -> LangGraph StateGraph / Command / checkpoint types
+```
+
+LangGraph is an implementation of the generic workflow engine contract. The
+Memind-facing protocol is `orchestrator-run-v1` plus `orchestrator-event-v1`.
+
+## Current stage
+
+Phase 1 establishes:
+
+- framework-neutral run and event contracts;
+- a plug-in workflow engine registry;
+- a remote workflow engine client;
+- versioned admin configuration;
+- 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.
+
+## Admin configuration
+
+The memindadm page is `/ops/admin/orchestrator`.
+
+Supported modes:
+
+- `off`: Native Agent Run only.
+- `shadow`: Native executes; the configured engine may observe.
+- `canary`: user allowlist and deterministic rollout percentage.
+- `active`: the primary engine handles workflow-allowlisted tasks.
+
+`MEMIND_ORCHESTRATOR_KILL_SWITCH=1` always forces Native selection.
+
+## Extraction test
+
+The service is ready to move into a separate repository only when:
+
+1. it can run against a mock Memind control plane;
+2. it owns its checkpoint database and credentials;
+3. task inputs use resource references rather than host paths;
+4. executor calls use versioned adapters;
+5. moving the service requires only changing `ORCHESTRATOR_URL`.