From cc1d0dfbcdeca102ad12fe08907d0e91616841f1 Mon Sep 17 00:00:00 2001 From: moss Date: Sun, 24 May 2026 20:31:39 +0700 Subject: [PATCH 1/3] docs: align v0.3 morphogenetic architecture and joinpoint model MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add v0.3 target-state doc, effector control plane, ADR 0012, and cross-links for 29-hook inventory, queue dogfood, and §10.5 implementation staging. Co-authored-by: Cursor --- RELEASING.md | 2 +- docs/07-mvp/m6-prerequisites-status.md | 2 +- docs/README.md | 2 +- .../adr/0011-openclaw-joinpoint-model-v0.1.md | 27 +- .../0012-self-built-effector-control-plane.md | 133 ++++++++ docs/design/morphogenetic-aspect-agent.md | 191 ++++++++++++ .../opencoat-openclaw-joinpoint-model-v0.1.md | 85 ++++- .../self-built-effector-control-plane.md | 248 +++++++++++++++ docs/design/v0.2-system-design.md | 3 +- .../design/v0.3-morphogenetic-architecture.md | 292 ++++++++++++++++++ docs/guides/concern-authoring-aop.md | 2 + docs/guides/openclaw-fork-dev.md | 18 ++ examples/09_queue_hook_dogfood/README.md | 14 +- 13 files changed, 983 insertions(+), 36 deletions(-) create mode 100644 docs/adr/0012-self-built-effector-control-plane.md create mode 100644 docs/design/morphogenetic-aspect-agent.md create mode 100644 docs/design/self-built-effector-control-plane.md create mode 100644 docs/design/v0.3-morphogenetic-architecture.md diff --git a/RELEASING.md b/RELEASING.md index 7b9972e..b437bf7 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -44,7 +44,7 @@ bash scripts/verify.sh # 1. bump every pyproject in lockstep (3 files) # pick X.Y.Z per SemVer: -# 0.1.4 → 0.1.5 patch (M6 heartbeat workers, joinpoint ADR-0011 + aliases, bridge 26 hooks + runtime observers) +# 0.1.4 → 0.1.5 patch (M6 heartbeat workers, joinpoint ADR-0011 + aliases, bridge 26 hooks + runtime observers) # superseded: 29 hooks as of queue wave # 0.1.3 → 0.1.4 patch (B.AI LLM, JoinpointDiscovery, AspectJ concerns, OpenClaw bridge verify) # 0.1.2 → 0.1.3 patch (ConcernBuilder MVP, gpt-5 tokens, OpenClaw bridge) # 0.1.1 → 0.1.2 patch (ship CLI `service` + PyPI/doc alignment) diff --git a/docs/07-mvp/m6-prerequisites-status.md b/docs/07-mvp/m6-prerequisites-status.md index b916ffa..740dc0b 100644 --- a/docs/07-mvp/m6-prerequisites-status.md +++ b/docs/07-mvp/m6-prerequisites-status.md @@ -8,7 +8,7 @@ Re-run automation: `./scripts/verify-m6-prerequisites.sh` from repo root (daemon | --- | --- | --- | --- | | **P1** | Joinpoint hot path on `main` | **PASS** | `uv run pytest packages/opencoat-runtime/tests/core` | | **P2a** | Daemon RPC smoke (`messages[]`, `#msg:`) | **PASS** | `./scripts/verify-m6-prerequisites.sh`; `user-shell-guard` in injections | -| **P2b** | Live OpenClaw gateway + bridge | **PASS** | 2026-05-18 local smoke — bridge README § Verify; 26 hooks + runtime observers (`queue.*` / `reply_run.*` / task poll) per [joinpoint model §4.1](../design/opencoat-openclaw-joinpoint-model-v0.1.md#41-mvp-emit-status-bridge-integrationsopenclaw-opencoat-bridge) | +| **P2b** | Live OpenClaw gateway + bridge | **PASS** | 2026-05-18 local smoke — bridge README § Verify; **29 hooks** + runtime observers; **`queue.before_enqueue` sync veto requires OpenClaw fork** (`queue_before_enqueue`); poll fallback observe-only per [joinpoint model §4.1](../design/opencoat-openclaw-joinpoint-model-v0.1.md#41-mvp-emit-status-bridge-integrationsopenclaw-opencoat-bridge) | | **P3** | Conflict paths documented | **PASS** | [m6-conflict-paths.md](./m6-conflict-paths.md); [ADR-0010](../adr/0010-concern-aop-syntax.md) | ## M6 implementation diff --git a/docs/README.md b/docs/README.md index 8fe1f0b..fd35752 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,7 +4,7 @@ Documentation is structured per the design (`docs/design/v0.2-system-design.md` | Section | Folder | Status | | --- | --- | --- | -| Design (v0.1, v0.2) | [`design/`](design/) | done — includes [OpenClaw joinpoint model v0.1](design/opencoat-openclaw-joinpoint-model-v0.1.md) | +| Design (v0.1, v0.2) | [`design/`](design/) | done — includes [OpenClaw joinpoint model v0.1](design/opencoat-openclaw-joinpoint-model-v0.1.md), [self-built effector & control plane](design/self-built-effector-control-plane.md) | | Concept primer | [`01-concepts/`](01-concepts/) | M2 | | Architecture | [`02-architecture/`](02-architecture/) | M2 | | Protocols | [`03-protocols/`](03-protocols/) | M2 | diff --git a/docs/adr/0011-openclaw-joinpoint-model-v0.1.md b/docs/adr/0011-openclaw-joinpoint-model-v0.1.md index 7f1bb93..3a6306a 100644 --- a/docs/adr/0011-openclaw-joinpoint-model-v0.1.md +++ b/docs/adr/0011-openclaw-joinpoint-model-v0.1.md @@ -2,14 +2,15 @@ ## Status -Accepted (design + catalog aliases on `main`; bridge runtime observers for MVP -queue/reply_run/task observe paths; synchronous native hooks remain follow-up). +Accepted (design + catalog aliases on `main`; bridge **29** plugin hooks + runtime +observers; **`queue.before_enqueue` / `queue.after_enqueue` sync collaborative +guard on HyperdustLabs fork** — see [joinpoint model §4.1](../design/opencoat-openclaw-joinpoint-model-v0.1.md#41-mvp-emit-status-bridge-integrationsopenclaw-opencoat-bridge)). **In-proc authoritative `ReflexMonitor`** (fail-closed) is v0.3 / [ADR-0012](./0012-self-built-effector-control-plane.md), not this ADR. ## Context OpenCOAT shipped a flat joinpoint catalog (38 names, 8 levels in `opencoat_runtime_core/joinpoint/catalog.py`) and an OpenClaw gateway bridge -(26 plugin hooks + runtime observers). OpenClaw’s real behavior control spans +(**29** plugin hooks + runtime observers). OpenClaw’s real behavior control spans `auto-reply/reply` (queue, `ReplyRunRegistry`, `agent-runner`), `agents/pi-embedded-runner` (`onAgentEvent`), and `tasks/task-registry` — not only prompt/tool hooks. @@ -38,19 +39,27 @@ task indexes). 6. **Full model:** Documented in [`docs/design/opencoat-openclaw-joinpoint-model-v0.1.md`](../design/opencoat-openclaw-joinpoint-model-v0.1.md) (14 domains; **§5 A/B/C availability tiers** for OpenClaw vs catalog). Implementation is phased (P0 catalog aliases → P2 plugin hooks → - P3 bridge runtime observers for observe-only MVP emits). + P3 bridge runtime observers → **P5a fork queue hooks**). **Collaborative → authoritative** staging: [v0.3 §10](../design/v0.3-morphogenetic-architecture.md#10-openclaw--效应器内核改造权威反射监视器), ADR-0012. ## Consequences - `opencoat inspect joinpoints` lists legacy + v0.1 MVP names. - Concerns may author `joinpoints: ["tool.before_call"]` or `["before_tool_call"]`. -- Queue / reply-run / task joinpoints are **emitted observe-only** by the bridge - (`onAgentEvent`, queue-depth poll, `runtime.tasks` poll) — not synchronous veto - at `enqueueFollowupRun` / `createTaskRecord` without upstream plugin hooks. +- **Decision path (fork + collaborative bridge):** `queue.before_enqueue` sync + **block** / prompt & summaryLine **rewrite** via `queue_before_enqueue` + + bridge `queue_guard` (daemon RPC). Requires fork gateway — see joinpoint model §5.7. +- **Observe fallback:** queue depth poll still emits `queue.before_enqueue` / + `queue.before_collect` when native hooks are absent (no veto). +- **Still observe-only or partial:** fine-grained `reply_run.phase.*`, generic + non-subagent `task.before_create`, `tool.result.before_emit`, unified + `memory.before_write` on every path. +- **ADR-0012** does not supersede this ADR for **unforked** hosts; cooperative + bridge remains the integration path there. - Future ADRs may supersede alias table when v0.1 names become canonical on the wire. ## References -- ADR-0003 (host adapter as plugin), ADR-0002 (AOP mechanism) -- [OpenClaw repo](https://github.com/openclaw/openclaw) — `src/auto-reply/reply/`, `src/tasks/` +- ADR-0003 (host adapter as plugin), ADR-0002 (AOP mechanism), ADR-0012 (effector / in-proc TCB) +- [v0.3 morphogenetic architecture §10](../design/v0.3-morphogenetic-architecture.md) +- [OpenClaw fork](https://github.com/HyperdustLabs/openclaw) — branch `opencoat/hooks-v0.1` - [integrations/openclaw-opencoat-bridge/README.md](../../integrations/openclaw-opencoat-bridge/README.md) diff --git a/docs/adr/0012-self-built-effector-control-plane.md b/docs/adr/0012-self-built-effector-control-plane.md new file mode 100644 index 0000000..2748b9c --- /dev/null +++ b/docs/adr/0012-self-built-effector-control-plane.md @@ -0,0 +1,133 @@ +# ADR 0012 — Self-built effector & deterministic control plane (OpenClaw fork) + +## Status + +Proposed (design). For the **deterministic** subset of joinpoints this supersedes +ADR-0011's "OpenClaw owns state; OpenCOAT owns concern" guest-plugin posture. +ADR-0011's cooperative bridge remains the integration path for **unforked** hosts. + +## Context + +- ADR-0002 made AOP the activation mechanism; ADR-0003 made the host adapter a + plugin; ADR-0011 mapped OpenClaw's lifecycle into a 14-domain joinpoint model. +- The current OpenClaw integration is a **guest plugin** + (`integrations/openclaw-opencoat-bridge`). Its enforcement is *cooperative*: + the core emits `WeavingOperation` rows (`block`, `rewrite`, `suppress`, …); + the bridge folds them into host decisions (`guardToolCall`, + `messageSendingDecision`, `subagentSpawnDecision`, `queueBeforeEnqueueDecision`); + OpenClaw applies them through public hooks and **retains final state mutation** + (mutation boundary `read_only` / `policy_only` / `host_api_only`). +- Joinpoint model §5 classifies availability A/B/C. The genuinely deterministic + interception points — `tool.before_execute` (mid-flight arg rewrite), + `response.before_final` (verifier before delivery), `memory.before_write` — are + **Tier C** for *in-proc authority*: blocked until `ReflexMonitor` lands in the fork. + **`queue.before_enqueue` is Tier A on the fork** (native `queue_before_enqueue` hook) + and already emits a **collaborative** `queue_guard` via the bridge — block/rewrite, + not observe-only. Tier C still includes `memory.before_write`, `tool.result.before_emit`, + and other sync paths skipped in the bridge. Even Tier A "strong control" today is + cooperative: tool-arg rewrite is explicitly disabled in `injector.ts` + ("Notes only — do not overwrite structured params on append advice"). +- `WeavingOperation` (12 ops: `INSERT, REPLACE, SUPPRESS, ANNOTATE, WARN, VERIFY, + REWRITE, DEFER, ESCALATE, BLOCK, COMPRESS`) is **undifferentiated** — it carries + no hard/soft distinction and no fail-closed semantics. The 2004 paper's + separation of a deterministic **Reflex layer (RAL ≈ spinal cord)** from the + adaptive **Knowledge-Based layer (KBAL ≈ cortex)** is collapsed into one enum. +- Net: against a *stochastic LLM effector* behind a *cooperative host*, most + weaving degrades to prompt text whose causal effect on behavior is unknowable. + This is both a reliability gap and — per the morphogenetic design §9 — a + **credit-assignment** gap for the aspect-net (you cannot cleanly credit an + advice whose effect you cannot deterministically observe). + +## Decision + +1. **Build a first-party effector by forking OpenClaw.** The effector is a full + MAN instance (`M = (N, ⇩_fast, ⇩_slow, F, κ, T)`) whose `EffectorKernel` + owns the turn loop: route → `ExcitatoryNeuron.propose` → `InhibitoryReflex.mediate` + → verify→repair → action execution → deterministic `r_t` emission. + This is a new host class (`opencoat_runtime_host_effector`), not a guest plugin. + Engineering landing: v0.3 architecture §3.5 + §10. + +2. **Introduce typed aspect cell kinds** — not two separate "planes" but two cell + types within the same connectome (`N`), unified under one plasticity law: + - **`InhibitoryReflex`** (`A_reflex ⊆ A`). Deterministic, fail-closed, in-proc + `ReflexMonitor` (small trusted core / TCB) at effect boundaries. Decisions are + `Allow | Deny(reason) | Rewrite(action')` — **enforced, not suggested**. + Safety-critical policies: `deny` on miss or error (fail-closed). + `A_reflex` excluded from `⇩_slow` structural rewriting (conserved core / + brainstem invariant). Engineering landing: v0.3 §3.3 + §10.2–10.3. + - **`ExcitatoryNeuron`** (`A_cortex = A \ A_reflex`). Aspect-LLM neurons that + `propose` candidates; weaver composes their advice into prompt injections. + Subject to `⇩_slow` (morphogenesis). Engineering landing: v0.3 §3.2. + +3. **Promote Tier C joinpoints to in-proc synchronous interception** in the fork + via `ReflexMonitor.mediate`. OpenClaw hook mapping (v0.3 §10.1): + + | Hook | Gate | **Current (2026-05)** | + |---|---|---| + | `before_tool_call` | authority reflex (step 1) | collaborative — daemon RPC `tool_guard` | + | `message_sending` | authority reflex (step 1) | collaborative — outbound cancel | + | `subagent_spawning` | authority reflex (step 1) | collaborative — spawn veto | + | `queue_before_enqueue` | authority reflex (step 1) | **collaborative on fork** — `queue_guard` block/rewrite | + | `before_agent_reply` | verify→repair (step 2) | not wired (bridge uses `message_sending`) | + | `after_tool_call` / `llm_output` / `agent_end` | `r_t` emission (step 3) | observe only — **`r_t` pending** | + | `before_message_write` / `tool_result_persist` | re-admit when in-proc | **skipped** in bridge | + + Previously-skipped hooks (`before_message_write`, `tool_result_persist`) can be + re-admitted because the monitor runs in-proc synchronously (no daemon RPC). + +4. **Tag the substrate.** Annotate each `WeavingOperation` / `AdviceType` with + `enforcement: hard | soft`, `fail_mode`, and add `neuron_type: excitatory | + inhibitory` to `Concern`. Designate the conserved core `A_reflex` via a + `reflex: true` marker excluded from `PlasticityEngine` rewrites. + +5. **Wire the closed loop: `r_t` → `CreditField` → `PlasticityEngine`.** Hard + decisions produce clean credit (causal effect known); soft advice credit is + statistically estimated. The plasticity engine runs at three time scales (fast / + warm / cold) replacing heuristic meta-governance. Engineering landing: v0.3 §3.6 + + §5. + +6. **Language/process boundary** (v0.3 §10.4): `ReflexMonitor` (hot path, TCB) + implemented in TypeScript inside the OpenClaw process for synchronous authority; + `PlasticityEngine` and credit field live in the Python daemon (warm/cold path). + Policies are expressed as a portable deterministic spec exported from OpenCOAT. + +7. **Keep the cooperative bridge.** For unforked hosts, ADR-0011's bridge remains + the integration path. Fork-based effector is an additional capability; both share + wire protocol and concern semantics. + +## Consequences + +- `InhibitoryReflex` decisions gain real authority: `Deny` / `Rewrite` are enforced + at the call site and fail-closed, closing the cooperative-enforcement gap. +- **Closed loop established**: `r_t` flows from `EffectorKernel` → `CreditField` → + `PlasticityEngine`. Hard decisions yield clean credit (morphogenetic §9); soft + advice credit remains statistically estimated. First time the system has a + deterministic, measurable learning signal. +- The 2004 RAL/KBAL separation is reinstated as two **typed cell kinds** within one + connectome, unified under one plasticity law — not two separate subsystems. +- The hexagonal seam (ADR-0006) gains an `EffectorReflexPort` so the core stays + host-agnostic; the fork is one adapter behind it. +- The `(i)→(ii)` migration path (v0.3 §7) is non-destructive: start with one + `ExcitatoryNeuron` + reflex ring, then widen (multi-neuron MoE) and deepen + (`lift`: aspect-of-aspect) under the same plasticity law. +- Cost: fork drift vs upstream OpenClaw; TS/Python boundary requires portable policy + spec; `ReflexMonitor` is safety-critical — a buggy TCB can deadlock the agent, + hence the `A_reflex` invariants + JSONL replayability are load-bearing. + +## References + +- ADR-0002 (AOP as mechanism), ADR-0003 (host adapter as plugin), + ADR-0006 (hexagonal ports), ADR-0008 (meta-concern governance), + ADR-0011 (OpenClaw joinpoint model v0.1). +- **Engineering landing (v0.3 architecture)**: + [`docs/design/v0.3-morphogenetic-architecture.md`](../design/v0.3-morphogenetic-architecture.md) — + cell types §3, one-turn sequencing §4, three time scales §5, existing-package + mapping §6, migration path §7, OpenClaw hook mapping §10. +- Reflex layer spec + interface contract + milestone roadmap: + [`docs/design/self-built-effector-control-plane.md`](../design/self-built-effector-control-plane.md). +- Formal grounding: + [`docs/design/morphogenetic-aspect-agent.md`](../design/morphogenetic-aspect-agent.md) + §1 (`A_reflex` conserved core), §2 (`⇩_fast` turn), §3 (credit field `κ`), + §5 (plasticity grammar), §9 (hard weaving = clean credit). +- 2004 paper (WAOSD'2004): RAL = spinal cord (deterministic reflex), + KBAL = cortex (adaptive / synaptic plasticity). diff --git a/docs/design/morphogenetic-aspect-agent.md b/docs/design/morphogenetic-aspect-agent.md new file mode 100644 index 0000000..96cc79a --- /dev/null +++ b/docs/design/morphogenetic-aspect-agent.md @@ -0,0 +1,191 @@ +# 形态发生 Agent:一个随机图改写系统的形式纲要 + +> 状态:概念草案(v0.3 方向),非当前实现规格。 +> 目的:把 DCN 的"可塑性"(2019 论文未解的考量 (3))立成一个自洽、可交付、可证伪的形式对象,可交给其他模型做形式化或实现。 + +--- + +## 背景与定位 + +OpenCOAT 是 2019 论文《Aspect-Oriented: a Candidate for the Biologically Inspired Programming Paradigm for Neural Networks and Evolvable Software》(Wang, Tang, Zhang, UESTC)在 LLM 时代的实现。论文给出生物映射 Aspect↔神经元、PointCut↔轴突、Advice↔信号转导、JoinPoint↔突触、Object↔效应器,并提出三条改造考量,其中考量 (3)"突触可塑性(需 dynamic AOP)"被标为未解。 + +本纲要只攻这一根承重柱:**在一个既符号又连接的混合基底上,如何做"以形态发生为机制、无梯度但有方向"的学习。** 立场:aspect 网**不是**又一个 ANN/transformer,而是对神经元做形态学建模的基底,贯彻"形态即功能、拓扑即学习统一";它**编排**外部 LLM(推理外包给 LLM),自身负责结构、治理与自进化。 + +贯穿全篇的一处不可约软点(见 §9):软 advice 对随机 LLM 的因果效应无法确定性获知——这正是"prompt 注入能否可靠改变行为"在最底层的回声。 + +--- + +## §0. 一句话定义 + +一个 **agent = 一个随机图改写系统** + +``` +M = (N, ⇩_fast, ⇩_slow, F, κ, T(·)) +``` + +- `N` —— 带类型的 aspect 动态图(状态) +- `⇩_fast` —— 固定拓扑下的一次推断(发放 → 织入 → 外部 LLM 效应) +- `⇩_slow` —— 改变图本身的形态发生;每条改写以速率 `min(1, exp(−ΔF/T))` 发生 +- `F` —— 自由能 / MDL 泛函 +- `κ` —— 信用场 +- `T(·)` —— 温度调度 + +**核心命题:结构与推断是同一个过程——一次慢归约,就是模型空间里的一步推断。** + +--- + +## §1. 状态 `N = (A, S, x)` + +- **A**:aspect 节点。`a` 带符号身份 `τ(a)`、增益 `g(a)`、dendrite/axon 端口、滑窗缓冲 `D_a = {(φ_t, a_t, r_t)}`。 +- **S**:突触有向边 `s = (aᵢ.axon → aⱼ.dendrite)`,带权 `w(s) ≥ 0`、资格迹 `e(s)`。 +- **x**:本轮激活态(膜电位)。 + +**π 演算读法**:aspect = 进程,突触 = 共享通道名,pointcut = 名字匹配谓词;mobility(通道名作为消息传递)= **结构可塑性的形式归宿**(运行时连接图自身可变)。 + +**保守核**:子集 `A_reflex ⊆ A` 是确定性反射 aspect(抑制性中间神经元),**不参与** `⇩_slow` 的随机改写——自进化的不变量边界(脑干)。 + +--- + +## §2. 快动力学 `⇩_fast`:一次推断(拓扑固定) + +一轮 = 一次 π 归约: + +1. joinpoint 上下文 `φ`(= query)→ pointcut 匹配候选 aspect,各得 `activation_score a_i`(= 注意力权重)。 +2. weaver 在 budget / top-k 下把激活 aspect 的 advice 组合成 injection(= 对 values 的加权和)。 +3. 外部 LLM(效应器)消费(injection + 上下文)→ 产出 / 动作;`A_reflex` 在效应边界确定性 gate(allow / deny / rewrite)。 + +**System1 = LLM(此步);System2 = 调度此步的 aspect 图。** 推理住在 LLM;结构、治理、可塑性住在图。 + +--- + +## §3. 奖励与信用场 `κ` + +确定奖励 `r_t`(验证判决 / 效应器结果 / 任务成功)按 **时间 × 结构 × 优势** 分配: + +``` +κ(a) += (r_t − b) · e_a(t) · ρ_a(t) +κ(s) += (r_t − b) · e_s(t) +``` + +- **`e`(资格迹,时间轴)**:`e_a ← λ·e_a + α·part_a`(边同理),处理延迟信用。`λ` = 信用视野(突触标记)。 +- **`ρ`(责任权重,结构轴)**: + - tier-1 影响力加权 `ρ_i = a_i·contrib_i / Σ_j a_j·contrib_j`(硬 advice 大、软 advice 折扣),廉价、纯日志。 + - tier-2 采样反事实 / Shapley 校准(空玩家性 ⇒ 无关 aspect → 0 信用,杀死相关性陷阱),昂贵、冷路径。 +- **`b`(基线)**:语境分桶滑动均值 ⇒ **credit ∝ 惊异(优势),非原始奖励**(= 奖励预测误差 / 多巴胺第三因子)。 + +**守恒律**:`Σ_a κ_a(t) = r_t − b`(信用守恒,不重复计、不通胀)。 + +分工:**节点信用** 驱动 split / neurogenesis;**边信用** 驱动 connect / prune / reweight。 + +--- + +## §4. 目标泛函 `F`(自由能 / MDL) + +``` +F = 惊异(任务误差 / 验证失败) + β · 复杂度(结构描述长度) +``` + +慢动力学下降的就是它。**同一个 `F` 同时给重赋权、连边、分化打分**——没有"先搜架构再搜权重"的二分。这是"拓扑与学习统一"的形式表达。 + +--- + +## §5. 慢动力学 `⇩_slow`:形态发生(改写文法) + +改写形如 `LHS 模式 + 守卫 ⟹ RHS`,速率 `min(1, exp(−ΔF/T))`。 + +| 原语 | 作用 | 由谁驱动 | +|---|---|---| +| connect(突触发生) | 加边 | 边信用 × 共激活 | +| prune | 删边 | 低权 + 冷 | +| reweight(LTP/LTD) | 改 `w`(退化改写) | 边信用 | +| **split(分化)** | 一节点 → 二专化 | 节点信用方差 | +| merge(融合 / 抽象) | 二近重 → 合一 | 冗余 | +| **lift(aspect-of-aspect)** | 联盟 → 高阶 aspect | 共发放联盟 | + +**split 与 lift 是生成核**(唯二*创造新符号单元*者:分化 = 自顶向下专化;抽象 = 自底向上联盟)。其余为家务。 + +### split(分化)完整规格 —— 样板原语 + +**守卫**(全部满足才触发候选): + +- 奖励异质度 `H(a) = Var_t[r_t] ≥ θ_H` +- 语境可分性 `G(a)/H(a) ≥ θ_sep`,其中 `G(a) = Var[r] − (p₁·Var[r|C₁] + p₂·Var[r|C₂])`(减方差增益;在每个特征上试轴对齐阈值桩 + 首主方向,取最优划分 `π`,确定性 `O(d·W log W)`) +- 样本下限 `n(a) ≥ n_min` +- 效应量下限 `|r̄₁ − r̄₂| ≥ δ` + +**RHS**: + +- pointcut 专化:`pc(a₁) = pc(a) ∧ π`,`pc(a₂) = pc(a) ∧ ¬π` +- 入突触按共激活分配(含糊则两边各半,权减半,后由 prune/reweight 退火) +- 出突触两孩子继承,增益 / advice 分化 +- **域守恒** `dom(a₁) ⊎ dom(a₂) = dom(a)`;**流守恒**(总权守恒) +- 孩子保留具名身份 `τ(a)|C₁`、`τ(a)|C₂`(neuro-symbolic 回报:长出的是具名符号单元) + +**ΔF**: + +- `ΔComplexity = L(π) + L(节点) + L(突触)`(可精算) +- `ΔError ≈ −η·G(a)`(tier-1,信用清洗后的减方差,纯重放);tier-2 反事实校准 +- `ΔF = ΔError + β·ΔComplexity < 0` 接受 + +**形态素(提议定位)**:局部充分统计量决定*在哪提议*——advice 方差高 → 提议 split;联盟共发放强 → 提议 lift;共激活 × 信用高 → 提议 connect。把组合爆炸压成少数候选;`ΔF` 决定*接不接受*。 + +--- + +## §6. 三时间尺度 `T(·)`(= 数字大脑的生理节律) + +| 尺度 | 跑什么 | 生物对应 | +|---|---|---| +| 快(每轮) | `⇩_fast` 推断;资格迹累积 | 神经发放 | +| 温(近线) | reweight + 信用驱动的 connect / prune;高频小改写 | 突触可塑性 | +| 冷(心跳) | split / lift / merge + tier-2 反事实校准 + 稳态归一;低频结构大改写 | 巩固 / 睡眠 / 发育关键期 | + +温度 `T` 退火(早期高、多分化;后期低、多巩固);新结构 `τ_refractory` 轮内禁反转(防 split ↔ merge 抖动)。 + +--- + +## §7. 不变量(良构 / 可证 safe) + +- 域守恒、流守恒、信用守恒 +- **细化保行为**:split / lift 是 refinement,在改写区域*外*可证不改变行为 +- `A_reflex` 不可被随机改写 + +这些是"自进化不跑飞"的硬约束。 + +--- + +## §8. 可证伪性 + +tier-1(资格迹、责任权重、基线、ΔComplexity、减方差代理)全是活动日志(JSONL replay)的固定函数 ⇒ **给定日志 + 常数,结构轨迹逐字节可重放**。tier-2 反事实校准引入 LLM 重放(随机),应多采样平均 + 固定种子,并把校准量记入日志作为周期修正项。 + +可证伪预测: + +1. 成熟过程中 **LLM 调用率下降**(符号认知接管 → 能效)。 +2. 每次被接受的 split 应在其子语境**降低奖励方差**。 +3. 移除信用清洗(用纯参与代替责任)应**升高误分裂率**。 + +--- + +## §9. 一处不可约软点(主线闭环) + +软 advice 对随机 LLM 的因果效应**无法确定性获知**;反事实只能*统计*估计(带方差、贵)。因此: + +> **硬作用 aspect 的信用 / 可塑性是干净确定的;软 aspect 的是统计的。** + +整套系统对*硬结构 + 短视野*可靠,对*软 + 长视野*带噪。这是诚实极限,不是 bug——也是"把更多织入做硬 / 自建效应器"的动机:把软 advice 换成硬作用,既提升可靠性,又让信用变干净,是同一个动作。 + +--- + +## §10. 它是什么、不是什么 + +- **是**:一个随机图改写系统,其改写速率由变分泛函给定;一个编排外部 LLM 的、可读可治理可生长的神经-符号基底;"拓扑 = 学习"的一个具体形式实例。 +- **不是**:一个被梯度训练的 ANN / transformer(它无梯度,靠 ΔF 引导的结构搜索);不是要在原始推理上替代 LLM(推理外包,自身做结构 / 治理 / 自进化)。 +- **承重判断**:骨架自洽且大体确定;能否扛规模,精确归结为两关——**信用清洗的干净度** 与 **特征 `φ` 的充分度**(后者本身是元结构学习问题)。 + +--- + +## 交接给其他模型的备注(handoff) + +- 形式语义候选:随机 π 演算 / 图文法(离散结构)× 变分自由能 / MDL(方向),改写速率 = `exp(−ΔF/T)`;深层统一候选 = 主动推断(structure learning = model expansion)。范畴论可作跨"离散结构 + 可微学习"的通用语候选。 +- 最小可证单元 = §5 的 split 规格;下一条待补的生成原语 = lift(aspect-of-aspect),长出*深度*。 +- 两个被点名的开放子问题:(a) 信用分配的低方差、低成本估计(尤其软 advice 与交互、长视野);(b) 特征 `φ` 的获取 / 生长。 +- 与现有 OpenCOAT 的接口:`ConcernVector.activation_score` ≈ `a_i`;现有 decay/merge = 稳态 + 剪枝(可塑性的家务半,缺的是奖励调制的增强 + 资格迹);JSONL replay = §8 可重放性的基础设施。 diff --git a/docs/design/opencoat-openclaw-joinpoint-model-v0.1.md b/docs/design/opencoat-openclaw-joinpoint-model-v0.1.md index 8952b2c..da4f650 100644 --- a/docs/design/opencoat-openclaw-joinpoint-model-v0.1.md +++ b/docs/design/opencoat-openclaw-joinpoint-model-v0.1.md @@ -1,8 +1,8 @@ # OpenCOAT × OpenClaw Joinpoint Model v0.1 **Status:** accepted — [ADR-0011](../adr/0011-openclaw-joinpoint-model-v0.1.md) -**Implementation:** `joinpoint/catalog.py`, `joinpoint/aliases.py`, `PointcutMatcher` alias equivalence; bridge `hook-bindings.ts` + `runtime-observers.ts` -**Related:** [v0.2 system design](./v0.2-system-design.md) §2.2, [ADR-0002 AOP](../adr/0002-aop-as-mechanism.md), [OpenClaw bridge README](../../integrations/openclaw-opencoat-bridge/README.md) +**Implementation:** `joinpoint/catalog.py`, `joinpoint/aliases.py`, `PointcutMatcher` alias equivalence; bridge **29** `hook-bindings.ts` + `runtime-observers.ts` (collaborative guards; fork `queue_before_enqueue` + `queue_guard`) +**Related:** [v0.2 system design](./v0.2-system-design.md) §2.2, [v0.3 MAN](./v0.3-morphogenetic-architecture.md) §10, [ADR-0012](../adr/0012-self-built-effector-control-plane.md), [self-built effector](./self-built-effector-control-plane.md), [ADR-0002 AOP](../adr/0002-aop-as-mechanism.md), [OpenClaw bridge README](../../integrations/openclaw-opencoat-bridge/README.md) --- @@ -20,6 +20,8 @@ Host Adapter maps host events → `JoinpointEvent`; COT Runtime runs extract → **Mutation boundary:** advice may return `tool_guard`, `prependSystemContext`, queue/run *policy suggestions*, etc. OpenClaw (or its plugin host) applies them via public APIs. OpenCOAT must not write `activeRunsByKey`, `queue.items`, `tasks` Map, or session store internals. +**v0.3 (i) note:** [v0.3 §10](./v0.3-morphogenetic-architecture.md#10-openclaw--效应器内核改造权威反射监视器) reclaims **effect-boundary gate semantics** (in-proc `ReflexMonitor`, fail-closed) without changing who owns internal Maps. Today’s bridge is still **collaborative** (daemon RPC on guard hooks). See [Appendix E](#appendix-e--v03-action--a_reflex-mapping). + --- ## 1. Layering (14 domains) @@ -375,7 +377,7 @@ error.detected | MVP joinpoint | Emitted today | Bridge source | Sync veto at host call site | | --- | --- | --- | --- | -| `input.received` | yes | `message_received`, `inbound_claim`, `before_dispatch` | no (observe / buffer) | +| `input.received` | yes | `message_received`, `inbound_claim`, `before_dispatch`, `before_agent_run` | no (observe / buffer) | | `queue.before_enqueue` | yes | **`queue_before_enqueue` plugin hook** (fork); queue depth poll fallback | **yes** — `block` / `queue.prompt` / `queue.summary_line` rewrite via bridge `queue_guard` | | `queue.after_enqueue` | yes (observe) | **`queue_after_enqueue` plugin hook** (fork); poll snapshot sync | no | | `queue.before_collect` | yes (observe) | queue depth poll (depth decrease) | no | @@ -394,6 +396,16 @@ error.detected | `heartbeat.before_run` | no | OpenCOAT `runtime_tick` / future hook | — | | `error.detected` | yes (observe) | `onAgentEvent` lifecycle `error` | no | +**Queue advice targets** (bridge `queue_guard` → OpenClaw `queue_before_enqueue`): + +| `effect.target` | `effect.mode` | OpenClaw result | +| --- | --- | --- | +| `queue.prompt` | `block` | skip enqueue / steering injection | +| `queue.prompt` | `rewrite` | replace queued prompt | +| `queue.summary_line` | `rewrite` | replace summary line | + +Dogfood: [`examples/09_queue_hook_dogfood`](../../examples/09_queue_hook_dogfood/README.md). Guards are **collaborative** (daemon RPC), not v0.3 in-proc TCB — see [Appendix E](#appendix-e--v03-action--a_reflex-mapping). + Default: `runtimeObservers: true`, `observerPollMs: 500`. Full hook table: [bridge README](../../integrations/openclaw-opencoat-bridge/README.md). --- @@ -482,11 +494,12 @@ Observation (DCN, audit, meta-review): plan / approval / patch / command_output / compaction events queue depth diff, task registry diff, reply_run lifecycle approx -Strong control (host must apply advice): - before_prompt_build → prependSystemContext - before_tool_call → block / params - message_sending → cancel - subagent_spawning → error status +Strong control (host must apply advice — collaborative guard today, not v0.3 TCB): + before_prompt_build → prependSystemContext + before_tool_call → block / params + message_sending → cancel + subagent_spawning → error status + queue_before_enqueue → block / queue.prompt / queue.summary_line rewrite (fork + queue_guard) Upstream “neurosurgery” (recommended order): 1. tool.before_execute middleware (if plugin hook insufficient) @@ -507,6 +520,20 @@ Upstream “neurosurgery” (recommended order): Design catalog lists **17 MVP names**; bridge **strong loop** today: input → prompt fold → tool guard → optional outbound cancel → **queue enqueue veto/rewrite (fork)** → task/subagent edges, plus observe-only run/task/event stream for DCN. Dogfood: [`examples/09_queue_hook_dogfood`](../../examples/09_queue_hook_dogfood/README.md). +### 5.7 Fork gateway ops (queue + native hooks) + +Queue sync veto requires the **HyperdustLabs OpenClaw fork** (`opencoat/hooks-v0.1`), not npm registry OpenClaw. From OpenCOAT repo root: + +```bash +./scripts/use-openclaw-fork.sh +./scripts/check-openclaw-fork.sh +openclaw gateway restart +``` + +**Pass:** gateway log shows `[opencoat-bridge] registered 29 hooks` and **no** `unknown typed hook "queue_before_enqueue" ignored`. If that warning appears, the running gateway is stale or not on fork `dist/` — poll fallback may still emit `queue.before_enqueue` to DCN but **cannot** sync veto. + +See [openclaw-fork-dev.md](../guides/openclaw-fork-dev.md). + --- ## 6. Joinpoint map (tree) @@ -639,7 +666,7 @@ New v0.1-only names (no legacy alias): all `queue.*`, `reply_run.*`, `task.*`, ` ## Appendix B — OpenClaw → v0.1 (integration) -### B.1 Gateway plugin hooks (`api.on`, 26/29) +### B.1 Gateway plugin hooks (`api.on`, 29 registered + 3 skipped) Canonical table lives in [bridge README § Hook → joinpoint mapping](../../integrations/openclaw-opencoat-bridge/README.md). Summary: @@ -647,11 +674,14 @@ Canonical table lives in [bridge README § Hook → joinpoint mapping](../../int | --- | --- | --- | --- | | Weave | `before_prompt_build` | `before_response` | `prependSystemContext` | | Guard | `before_tool_call` | `before_tool_call` | `block` / params | +| Queue guard | `queue_before_enqueue` | `queue.before_enqueue` | `block` / prompt & summaryLine rewrite (fork) | | Outbound | `message_sending` | `before_response` | `cancel` | | Task | `subagent_spawning` … `subagent_ended` | `task.*` | spawn veto + observe | -| Observe | `session_*`, `gateway_*`, `llm_*`, compaction, … | various | submit only | +| Observe | `session_*`, `gateway_*`, `llm_*`, `queue_after_enqueue`, compaction, … | various | submit only | + +Skipped (sync hot path — v0.3 in-proc TCB may re-admit): `before_message_write`, `tool_result_persist`. Skipped (install): `before_install`. -Skipped (sync hot path): `before_message_write`, `tool_result_persist`. Skipped (install): `before_install`. +Dogfood queue concerns: [`examples/09_queue_hook_dogfood`](../../examples/09_queue_hook_dogfood/README.md). ### B.2 Runtime observers (not `api.on`) @@ -661,12 +691,12 @@ Bridge module `runtime-observers.ts` — uses host APIs already available to plu | --- | --- | --- | | `api.runtime.events.onAgentEvent` | `reply_run.before_begin`, `reply_run.phase.running`, `planning.plan_updated`, `approval.requested`, `command.output_stream`, `patch.summary_created`, `error.detected` (lifecycle `error`), compaction → `before_memory_write` / `after_memory_write` | event stream | | `api.registerHook` | `session:compact:before` / `after` → memory JPs | internal gateway hooks | -| Host `getFollowupQueueDepth` | `queue.before_enqueue`, `queue.before_collect` | `registerService` poll per tracked `sessionKey` | +| Host `getFollowupQueueDepth` | `queue.before_enqueue`, `queue.before_collect` | **fallback only** when native `queue_before_enqueue` absent; poll cannot veto | | `api.runtime.tasks.runs.bindSession().list()` | `task.before_create`, `task.after_create`, `task.before_terminal` | task registry diff poll | **Tracked sessions:** any hook `ctx.sessionKey` and agent events with `sessionKey`. -**Limits:** observe-only at poll/event granularity; does not replace native hooks at `enqueueFollowupRun`, `ReplyRunRegistry` phase edges, or `createTaskRecord` for synchronous policy veto. +**Limits:** poll/event paths are observe-only. **`queue.before_enqueue` sync veto** is provided by fork `queue_before_enqueue` + bridge `queue_guard` (not poll). Still missing native hooks at `ReplyRunRegistry` phase edges and generic `createTaskRecord` for non-subagent tasks. ### B.3 Python host event map (design, not in TS bridge) @@ -687,7 +717,8 @@ Bridge module `runtime-observers.ts` — uses host APIs already available to plu | OpenClaw module | v0.1 emit | Bridge today | Native hook for veto | | --- | --- | --- | --- | -| `auto-reply/reply/queue.ts` | `queue.*` | depth poll → before_enqueue / before_collect | yes — enqueue/collect call sites | +| `auto-reply/reply/queue.ts` | `queue.before_enqueue` | fork hook + `queue_guard`; poll fallback observe | **shipped (fork)** — `queue_before_enqueue`; `queue.before_drain` still needed | +| `auto-reply/reply/queue.ts` | `queue.before_collect` | depth poll | yes — collect/drain call sites | | `auto-reply/reply/reply-run-registry.ts` | `reply_run.*` phases | lifecycle + running approx | yes — per-phase hooks | | `auto-reply/reply/agent-runner.ts` | `prompt.before_send_to_model` | plugin hooks | partial | | `agents/pi-embedded-runner` | `planning.*`, `patch.*`, … | `onAgentEvent` observe | optional | @@ -704,10 +735,30 @@ Repo: [github.com/openclaw/openclaw](https://github.com/openclaw/openclaw) — ` | --- | --- | --- | | **P0** (done) | Legacy 38 + MVP 17 catalog + alias matching + ADR-0011 | `catalog.py`, `aliases.py`, matcher | | **P1** (done) | Bridge docs + concern AOP examples | bridge README, authoring guide | -| **P2** (done) | 26 plugin hooks + weave/guard paths | `hook-bindings.ts`, bridge | -| **P3** (done, observe) | `queue.*`, `reply_run.*`, plan/approval via runtime observers | `runtime-observers.ts` | +| **P2** (done) | **29** plugin hooks + weave/guard/queue_guard paths | `hook-bindings.ts`, bridge | +| **P3** (done, observe) | `reply_run.*`, plan/approval/command/patch/error via runtime observers; queue poll fallback | `runtime-observers.ts` | | **P4** (partial) | `task.*` poll + subagent hooks; `flow.*` TBD | bridge; optional daemon mirror | -| **P5** | Sync native hooks at queue/run/task call sites | OpenClaw upstream PR | +| **P5a** (done) | Sync `queue.before_enqueue` / `queue.after_enqueue` on fork | HyperdustLabs/openclaw `opencoat/hooks-v0.1` + OpenCOAT bridge #77 | +| **P5b** (next) | `reply_run.phase.*`, `tool.result.before_emit`, unified `memory.before_write`, generic `task.before_create` | OpenClaw fork PRs | +| **P6** (v0.3) | In-proc `ReflexMonitor` (fail-closed TCB) + `r_t` emission + daemon `PlasticityEngine` | [v0.3 §10](./v0.3-morphogenetic-architecture.md), [ADR-0012](../adr/0012-self-built-effector-control-plane.md) | + +--- + +## Appendix E — v0.3 Action ↔ A_reflex mapping + +Wire catalog for [v0.3 §10](./v0.3-morphogenetic-architecture.md#10-openclaw--效应器内核改造权威反射监视器) and [self-built effector §2](./self-built-effector-control-plane.md). **Collaborative** = today’s bridge (daemon RPC); **Authority** = in-proc `ReflexMonitor` target. + +| OpenClaw hook | Joinpoint | v0.3 `Action.kind` | `A_reflex` id | Bridge `HookKind` | Collaborative today | Authority (v0.3) | +| --- | --- | --- | --- | --- | --- | --- | +| `before_tool_call` | `tool.before_call` | `tool_call` | `reflex.tool_guard` | `tool_guard` | yes | in-proc TCB | +| `message_sending` | `response.before_final` | `message_send` | `reflex.response_verifier` | `message_out` | cancel only | in-proc + verify→repair | +| `subagent_spawning` | `task.before_create` | `subagent_spawn` | `reflex.spawn_guard` | `subagent_spawn` | spawn veto | in-proc deny | +| `queue_before_enqueue` | `queue.before_enqueue` | `queue_enqueue` | `reflex.queue_guard` | `queue_guard` | **yes (fork)** | in-proc | +| `before_message_write` | `memory.before_write` | `memory_write` | `reflex.memory_guard` | *(skipped)* | no | in-proc when TCB lands | +| `tool_result_persist` | — | — | — | *(skipped)* | no | in-proc when TCB lands | +| `after_tool_call` / `llm_output` / `agent_end` | observe JPs | — | — | `observe` | DCN only | **`r_t` emit** (not done) | + +\* v0.3 verify→repair uses `before_agent_reply`; bridge today cancels at `message_sending`. --- diff --git a/docs/design/self-built-effector-control-plane.md b/docs/design/self-built-effector-control-plane.md new file mode 100644 index 0000000..c907b1d --- /dev/null +++ b/docs/design/self-built-effector-control-plane.md @@ -0,0 +1,248 @@ +# 自建 Effector：一个 MAN 实例 + +> 状态：设计草案(v0.2 方向),非当前实现规格。配套决策见 [ADR-0012](../adr/0012-self-built-effector-control-plane.md)。 +> 目标架构：[v0.3 §10](./v0.3-morphogenetic-architecture.md#105-实现分期-2026-05)；连线映射：[joinpoint model Appendix E](./opencoat-openclaw-joinpoint-model-v0.1.md#appendix-e--v03-action--a_reflex-mapping)。 +> 谱系：[形态发生 Agent 纲要](./morphogenetic-aspect-agent.md)；2004 论文 RAL(脊髓/反射)÷ KBAL(皮层/可塑)。 + +--- + +## §0. 一句话 + +``` +effector = M = (N, ⇩_fast, ⇩_slow, F, κ, T(·)) +``` + +**effector 不是"LLM + 旁挂控制面"，而是一个完整的 MAN 实例。** +LLM 是 `⇩_fast` 里被外包的 System1；确定性控制面是图状态 `N` 中 `A_reflex` 子集在效应边界的同步 gate； +软织入是 `A_cortex = A \ A_reflex`，受 `⇩_slow` 形态发生驱动。 + +把今天"OpenCOAT 作为客人插件、只能发建议"翻转为"OpenCOAT 拥有效应边界"的那个翻转， +**形式上就是：把 Tier C 挂载点变成 `⇩_fast` 里 `A_reflex` gate 的同步阻断点。** + +--- + +## §1. 为什么 effector = M 实例（而非"控制面"） + +### 当前合作式路径的三重问题 + +| 问题 | MAN 语言 | 证据 | +|---|---|---| +| 织入退化为 prompt 文本，因果不可知 | `⇩_fast` 的效应边界不在 OpenCOAT 图内 | `injector.ts`："Notes only — do not overwrite structured params" | +| `WeavingOperation` 无软硬之分 | `A_reflex` 与 `A_cortex` 被压成同一个 enum，gate 语义缺失 | `envelopes.py`：12 op 平铺，无 `enforcement` 字段 | +| 硬 advice 信用不干净 | `κ(a)` 无法归因（因果未知 → 反事实估计有噪） | morphogenetic §9：soft advice 信用统计估计，带噪 | + +**结论**：问题不是"控制面不够强"，而是**效应边界不在图里**。 +把效应边界拉进图 = fork OpenClaw + 把 Tier C 挂载点变成 `⇩_fast` 的同步 gate = 解决上面全部三条。 + +### fork 的形式含义 + +fork 让 OpenCOAT 在 `tool.before_execute` / `memory.before_write` / `response.before_final` 等点 +插入**阻断式中介**（即 `⇩_fast` 里的 `A_reflex` gate）： + +``` +⇩_fast 一轮 = joinpoint 匹配 → pointcut gate（A_reflex） → advice 注入 → LLM 效应 → 效应边界 gate（A_reflex）→ 产出 +``` + +--- + +## §2. 状态 `N = (A, S, x)` + +``` +A = A_reflex ⊎ A_cortex +``` + +| 子集 | 类型 | 参与 `⇩_slow`？ | 信用 | +|---|---|---|---| +| `A_reflex` | 确定性反射 aspect；在效应边界同步 gate | **否**（脑干不变量） | 干净（因果已知） | +| `A_cortex` | 软 advice aspect；prompt 级条件化 + DCN 可塑 | **是**（形态发生主体） | 统计（反事实估计） | + +**`A_reflex` 成员**（初始集合，由 meta-concern 治理扩缩）： + +| aspect id | 挂载点 | 默认裁决 fail mode | **Current (2026-05)** | +|---|---|---|---| +| `reflex.tool_guard` | `tool.before_call` | deny | **collaborative** — bridge `tool_guard` + daemon RPC | +| `reflex.memory_guard` | `memory.before_write` | deny | **skipped** — sync hot path; pending in-proc TCB | +| `reflex.response_verifier` | `response.before_final` | allow* | **collaborative** — `message_sending` outbound cancel | +| `reflex.spawn_guard` | `task.before_create` / subagent spawn | deny | **collaborative** — spawn veto via bridge | +| `reflex.queue_guard` | `queue.before_enqueue` | allow | **partial — fork hook + bridge `queue_guard` (collaborative)** block/rewrite | +| `reflex.phase_gate` | `reply_run.phase.*` | allow | **not wired** | + +\* `response.before_final` 默认 fail-open 防止卡死 agent；严格场景由治理面升级为 fail-closed。 + +**突触 `S`**：`A_reflex` 的出边指向 `A_cortex`（单向；反射 gate 结果可作为软 advice 的激活上下文输入，但不反向）。 +**激活态 `x`**：当前轮 gate 中间状态；`A_reflex` gate 的 `x` 是确定性布尔/补丁，`A_cortex` 的 `x` 是激活分数。 + +--- + +## §3. 快动力学 `⇩_fast`：effector 一轮 + +MAN §2 的 π 归约，在 effector 里展开为： + +``` +1. joinpoint 事件 φ 到达（工具调用 / 写记忆 / 交付响应 / ...） +2. A_reflex 同步 gate(φ) → Verdict（阻断；未返回前底层效应不执行） +3. Verdict.allow → pointcut 匹配 A_cortex 候选 → advice 注入 → LLM(System1) 消费 +4. LLM 产出 → 再次触发效应边界 gate（步骤 2 的下游挂载点） +5. 最终效应写出；资格迹 e_a / e_s 累积 +``` + +**A_reflex gate 是 `⇩_fast` 里的同步阻断节点**，不是异步建议。 +这是"fork" = "把 Tier C 挂载点变成进程内同步"的形式表达。 + +--- + +## §4. `A_reflex` 裁决语义（Verdict） + +gate 在每个挂载点产出一个 **Verdict**（纯函数：给定输入快照 + `A_reflex` 成员集 → 确定输出）： + +```typescript +type Verdict = + | { kind: "allow" } + | { kind: "deny"; reason: string } + | { kind: "rewrite"; patch: StructuredPatch; reason: string } + | { kind: "require_approval"; prompt: string } + | { kind: "defer"; until: JoinpointSelector } + +type GateDecision = { + weave_id: string; + joinpoint: string; // e.g. "tool.before_execute" + verdict: Verdict; + enforcement: "hard"; // A_reflex gate 恒为 hard + by: string[]; // 命中的 A_reflex 成员 ids + fail_mode: "deny" | "allow"; +} +``` + +**裁决偏序（确定性、可重放）**：`deny > require_approval > rewrite > defer > allow`。 + +多 `A_reflex` 成员命中同一挂载点时，按偏序合并；同级 `rewrite` 按 `declare precedence` 顺序应用补丁，冲突降级为 `deny` 并记日志。 + +**整个 gate 过程是纯函数** → 给定 JSONL 快照，结构轨迹逐字节可重放（对齐 MAN §8、ADR-0007）。 + +--- + +## §5. 信用场 `κ` 与慢动力学 `⇩_slow` + +### 硬裁决 → 干净信用 + +`A_reflex` 的每次 gate 产出因果已知的信号：deny = 底层效应确实未执行，rewrite = 确实按补丁执行。 +因此： + +``` +κ(a_reflex) += (r_t − b) · e_a(t) · ρ_a(t) // ρ tier-1，纯日志，无需反事实 +κ(s) += (r_t − b) · e_s(t) +``` + +`A_cortex` 的 advice 因果不可确定（随机 LLM），`ρ` 需要 tier-2 反事实校准（带噪，贵）。 + +**`A_reflex` 信用是 `⇩_slow` 的低噪驱动源**：它驱动 `A_cortex` 的 split / connect / prune， +同时自身被 `⇩_slow` 排除在外（`A_reflex ∩ ⇩_slow 改写文法 = ∅`）。 + +### 三时间尺度 + +| 尺度 | effector 里跑什么 | +|---|---| +| 快（每轮） | `⇩_fast`：gate + advice 注入 + LLM 效应；资格迹累积 | +| 温（近线） | `A_cortex` reweight + connect / prune；`κ` tier-1 驱动 | +| 冷（心跳） | `A_cortex` split / lift / merge + tier-2 反事实校准；`A_reflex` 成员集治理审查（只增不减，除非 meta-concern 明确授权） | + +`A_reflex` 成员集在冷尺度接受**治理审查**（ADR-0008 `GovernanceCapability`），但审查结果是"加/删成员"而非随机改写 aspect 内部结构。 + +--- + +## §6. 接口契约 + +### fork 侧（π 演算风格：同步通道） + +```typescript +// 每个效应边界 = 一个同步通道；mediate 返回前通道阻断 +interface ReflexGate { + joinpoint: string; // 对应 A_reflex 成员的挂载点 + mediate(ctx: TCtx, deadlineMs: number): Promise; + // 同步阻断；超时按 fail_mode 处理；ctx 只读快照 +} + +registerReflexGates(gates: ReflexGate[]): void; // fork 注册 6 个挂载点 +``` + +**Today (2026-05):** six joinpoints are defined; **four have collaborative bridge guards** (`tool`, `message`, `spawn`, `queue` on fork); **zero have in-proc authoritative TCB** (`ReflexMonitor`). See [v0.3 §10.5](./v0.3-morphogenetic-architecture.md#105-实现分期-2026-05). + +### OpenCOAT 侧（新 hexagonal port，扩展 ADR-0006） + +```python +class EffectorReflexPort(Protocol): # A_reflex 在 OpenCOAT core 里的 port + def gate(self, jp: JoinpointEvent, deadline_ms: int) -> GateDecision: ... + def reflex_set(self) -> frozenset[str]: ... # A_reflex 当前成员 ids +``` + +**契约硬要求**： +1. **同步阻断**：`mediate` 返回前不得执行底层效应。 +2. **超时即 fail_mode**：deny 子集超时 = deny；allow 子集超时 = allow + 记 `degraded`。 +3. **只读快照**：`ctx` 是 host 状态快照；改动只经 `rewrite` 补丁回流。 +4. **可重放**：每次 `gate` 的输入快照 + `GateDecision` 写 JSONL（与 MAN §8 资格迹同一日志流）。 + +> 接入 fork 时只需补一件事：把 §3 六个 `⇩_fast` 挂载点的 `mediate(...)` 接到 fork 真实调用点；OpenCOAT 侧无需改动。 + +--- + +## §7. 与现有代码的衔接（增量，不推倒） + +| 现有 | 改动 | MAN 含义 | +|---|---|---| +| `WeavingOperation`（12 op） | 加 `enforcement: hard\|soft` + `fail_mode` 分类表（`weaving/enforcement.py`） | 显式区分 `A_reflex` op 与 `A_cortex` op | +| `AdviceType` | `TOOL_GUARD`/`MEMORY_WRITE_GUARD` 归 `A_reflex`（hard）；其余归 `A_cortex`（soft） | 把 enum 成员映射到图子集 | +| `injector.ts` 决策函数 | fork 路径：从"建议"升级为 `GateDecision`；bridge 路径保持合作式不变 | `⇩_fast` gate 替换合作式 suggest | +| ports（ADR-0006） | 加 `EffectorReflexPort` | 新 hexagonal port；core 仍 host-agnostic | +| concern `reflex` 字段 | 新增布尔标记；`DCN ⇩_slow` 改写文法跳过 `reflex=true` 的 aspect | `A_reflex` 在图里的物理标记 | +| JSONL replay（ADR-0007） | `GateDecision` 纳入同一日志流 | 快时间尺度 gate 可重放；喂冷时间尺度信用校准 | +| `ConcernVector.activation_score` | 对应 MAN `a_i`（激活分数）；gate 结果可作为下游 `A_cortex` 的上下文输入 | `S` 的权重流 | + +**关键**：这是"在已有 weaving 上，把 `A_reflex` 子集做硬"，不是另起炉灶。 + +--- + +## §8. 路线图（三时间尺度对齐） + +每个里程碑对应 MAN 的一个时间尺度层或一个组件；全部遵循仓库 PR 工作流（AGENTS.md）。 + +| 里程碑 | MAN 时间尺度 | 范围 | 交付物 | 可证伪/验收 | +|---|---|---|---|---| +| **M-E0 A_reflex 标记** | 基础设施 | `WeavingOperation`/`AdviceType` 加 enforcement+fail_mode 表；concern `reflex` 字段；`⇩_slow` 跳过逻辑 | `weaving/enforcement.py`、concern schema 更新、单测 | 12 op 全覆盖；`A_reflex` 成员被 `⇩_slow` 跳过（测试可证） | +| **M-E1 EffectorReflexPort** | 快（`⇩_fast` gate） | `GateDecision` 协议 + 裁决合并纯函数 + `EffectorReflexPort` port + JSONL replay 写入 | 新 port、协议类型、合并器 | 给定输入 + aspect 集，GateDecision 逐字节可重放 | +| **M-E2 影子模式** | 快（旁路观测） | fork 未接前：`⇩_fast` 旁路跑 `A_reflex` gate，只记 `GateDecision` 不执行 | shadow runner、GateDecision JSONL | 影子裁决 vs 实际宿主行为差异报告（量化合作式缺口） | +| **M-E3 fork 接入（tool）** | 快（gate 真正生效） | `tool.before_execute` deny/rewrite 硬拦截、fail-closed | `opencoat_runtime_host_effector`、fork mediation 钩子 | 红队：被 deny 的工具调用确实未执行；超时 fail-closed | +| **M-E4 fork 接入（memory/response）** | 快 | `memory.before_write`、`response.before_final` 硬拦截 | 两挂载点 mediation | 写入脱敏/响应改写在交付前确定性生效 | +| **M-E5 治理+人在环** | 冷（`A_reflex` 成员集审查） | meta-concern 覆盖 fail_mode；`require_approval` 闭环；冷时间尺度成员集治理 | 治理覆盖 API、approval 流 | 严格 concern 把 `response.before_final` 升为 fail-closed | +| **M-E6 信用回流** | 温/冷（`κ` → `⇩_slow`） | 硬裁决 `GateDecision` 喂 `κ` tier-1；资格迹累积；接 aspect 网 `⇩_slow` | 信用桥、JSONL→κ pipeline | 硬子集信用方差 < 软子集（度量）；与 MAN §8 可证伪预测对齐 | + +**依赖**：M-E0 → M-E1 → {M-E2 影子, M-E3 fork}。M-E2 不依赖 fork，可立即开始。 + +--- + +## §9. 不变量（良构 / 可证 safe） + +继承 MAN §7： + +- **域守恒**：split 后 `dom(a₁) ⊎ dom(a₂) = dom(a)`，`A_reflex` gate 的覆盖域不缩小。 +- **流守恒**：总权守恒（`A_reflex` gate 是幂等的，不引入新信用）。 +- **信用守恒**：`Σ_a κ_a(t) = r_t − b`（不重复计；`A_reflex` 的干净信用不通胀）。 +- **`A_reflex` 不参与 `⇩_slow` 随机改写**：这是自进化的不变量边界（脑干）。 +- **细化保行为**：gate 是 refinement，在 gate 作用域外可证不改变 `⇩_fast` 行为。 + +--- + +## §10. 风险与边界 + +- **fork 漂移**：mediation 钩子做薄（只接 §3 六个点）、契约稳定、其余 rebase。 +- **`A_reflex` 自身故障**：硬边界 bug 可卡死 agent → 不变量 + 超时 fail_mode + JSONL 可重放兜底。 +- **fail-closed 的可用性代价**：`response` 默认 fail-open；`A_reflex` 成员集冷时间尺度治理可调。 +- **不可约软点（MAN §9）**：`A_cortex` 对随机 LLM 的因果仍不可确定获知——本设计不消除它，只是把更多织入移入 `A_reflex`（由 M-E6 信用回流量化迁移进度）。 + +--- + +## 交接备注（handoff） + +- **立即可起步**：M-E0 / M-E1 / M-E2 全在 OpenCOAT 仓库内，不依赖 fork。M-E2 产出"合作式缺口"量化证据，同时为 M-E6 信用回流准备真实 JSONL。 +- **fork 接入最小集**：只需把 §3 六个 `⇩_fast` 挂载点的 `mediate(...)` 接到 fork 真实调用点；OpenCOAT 侧 `EffectorReflexPort` 已就绪。 +- **与 MAN 纲要的接口**：`A_reflex`（MAN §1）、gate = `⇩_fast` 同步节点（MAN §2）、硬裁决=干净信用（MAN §9）、可重放（MAN §8）四处对齐；本线产出的 `GateDecision` JSONL 即 MAN `κ` 的直接输入。 +- **v0.1 → v0.2 的核心变化**：主语从"控制面"换成 `M` 实例；`EffectorControlPlane` 改名为 `EffectorReflexPort`（强调它是 `A_reflex` 在图里的 port，而非旁挂的"面"）；路线图对齐三时间尺度；接口契约增加 π 演算风格的通道语义注释。 diff --git a/docs/design/v0.2-system-design.md b/docs/design/v0.2-system-design.md index 117b164..0955059 100644 --- a/docs/design/v0.2-system-design.md +++ b/docs/design/v0.2-system-design.md @@ -7,6 +7,7 @@ > 本文档是对 [`v0.1-complete-design.md`](v0.1-complete-design.md) 的工程化展开。 > v0.1 定义了**概念与运行机制**，本文档定义**模块边界、接口、协议、目录结构、部署形态、运维与演进路线**。 > 范围：从单文件 demo（in-proc 模式）一直到独立 daemon + 多 host 插件的服务化形态。 +> **Successor:** 闭环形态发生方向见 [`v0.3-morphogenetic-architecture.md`](v0.3-morphogenetic-architecture.md)（§10 权威反射 + `r_t`）；本文档描述 **v0.2 协作式 MVP** 工程骨架，不重复 v0.3 全文。 --- @@ -552,7 +553,7 @@ opencoat-runtime-host-plugins/ #### 4.7.2 Gateway bridge + prompt-code discovery（use case） -生产网关使用 TypeScript bridge（[`integrations/openclaw-opencoat-bridge/`](../../integrations/openclaw-opencoat-bridge/README.md)）：**26** 个 `api.on` 插件钩子（织入 / tool guard / 出站 cancel 等）+ **runtime observers**（`onAgentEvent`、队列深度轮询、`runtime.tasks` 轮询）覆盖 ADR-0011 MVP 中的 `queue.*` / `reply_run.*` / `task.*` 等观察路径（见 [joinpoint model v0.1 §4.1](./opencoat-openclaw-joinpoint-model-v0.1.md#41-mvp-emit-status-bridge-integrationsopenclaw-opencoat-bridge)）。在 `before_prompt_build` 把 hook 的 **`messages[]`** 放进 joinpoint payload；daemon 侧 **JoinpointDiscovery** 在一次 `joinpoint.submit` 内展开 message / section 层 JP，Host 仍只提交粗边界。 +生产网关使用 TypeScript bridge（[`integrations/openclaw-opencoat-bridge/`](../../integrations/openclaw-opencoat-bridge/README.md)）：**29** 个 `api.on` 插件钩子（织入 / tool guard / 出站 cancel / **queue enqueue veto on fork** 等）+ **runtime observers**（`onAgentEvent`、队列深度轮询、`runtime.tasks` 轮询）覆盖 ADR-0011 MVP 中的 `queue.*` / `reply_run.*` / `task.*` 等路径（见 [joinpoint model v0.1 §4.1](./opencoat-openclaw-joinpoint-model-v0.1.md#41-mvp-emit-status-bridge-integrationsopenclaw-opencoat-bridge)）。在 `before_prompt_build` 把 hook 的 **`messages[]`** 放进 joinpoint payload；daemon 侧 **JoinpointDiscovery** 在一次 `joinpoint.submit` 内展开 message / section 层 JP，Host 仍只提交粗边界。**权威反射与 `r_t` 闭环**见 [v0.3 §10](./v0.3-morphogenetic-architecture.md#10-openclaw--效应器内核改造权威反射监视器)（目标态；当前 bridge 仍为协作式 daemon RPC）。 **用户故事** diff --git a/docs/design/v0.3-morphogenetic-architecture.md b/docs/design/v0.3-morphogenetic-architecture.md new file mode 100644 index 0000000..315d9df --- /dev/null +++ b/docs/design/v0.3-morphogenetic-architecture.md @@ -0,0 +1,292 @@ +# OpenCOAT v0.3 系统架构:形态发生连接组(MAN) + +> 状态:架构草案(v0.3 方向)。这是工程布局文档,配套两份姊妹文档: +> [`morphogenetic-aspect-agent.md`](morphogenetic-aspect-agent.md)(形式纲要)与 +> `morphogenetic-aspect-agent-paper.tex`(论文草稿)。 +> 它在 [`v0.2-system-design.md`](v0.2-system-design.md) 的工程骨架之上,提出从"建议式运行时"到"闭环连接组"的重设。 + +--- + +## 1. 一个结构性改变,两条公理 + +现状(v0.2):OpenCOAT 是**建议式 + 协作式**运行时——weaver 产出 `ConcernInjection` 负载,外部宿主*可能*采纳;DCN 靠启发式(decay/merge)演化;效应器是宿主的,运行时拿不到干净的结果信号。由此带来三个已知弱点:协作式(只有宿主调 guard 才生效)、fail-open、只有 OpenClaw 真接。 + +**2026-05 进展 (v0.3 (i) 试点,仍协作式):** HyperdustLabs OpenClaw fork 已 emit `queue_before_enqueue` / `queue_after_enqueue`; OpenCOAT bridge `queue_guard` 可在 daemon RPC 路径上 **block / rewrite** 入队 prompt。这**不是** §10 的 in-proc 权威 `ReflexMonitor`,仍是 fail-open 协作 guard。见 [joinpoint model §4.1 / §5.7 / Appendix E](./opencoat-openclaw-joinpoint-model-v0.1.md). + +v0.3 只动两处,互为补充的两半: + +- **公理 A(闭环)**:自建效应器 → 产出*确定的*结果流 `r_t`(reflex 的 allow/deny/repair、verifier 判决);可塑性律消费 `r_t` 学突触。缺效应器 → 拿不到干净 `r_t`;缺可塑性律 → 效应器结果只是日志,不回流成权重。两半合起来,才是"会随环境学习适应的皮层"第一次有了确定、可度量的实现路径。 +- **公理 B(一张网的细胞类型;(i)→(ii) 是发育)**:三个"平面"不再分离,而是同一连接组里的细胞类型。深度=1 即架构 (i);加节点、aspect-of-aspect 加深 → (ii)。同一条可塑性律全程不变。 + +--- + +## 2. 数据/控制流(闭环) + +```mermaid +flowchart TD + JP[Joinpoint
context = query] --> RT[Synapse routing
activation scores] + RT --> NEU[Aspect-LLM neurons
propose · excitatory] + NEU --> REF[Reflex aspects
allow / deny / rewrite] + REF --> EFF[Effector kernel
→ r_t deterministic stream] + EFF --> CR[Credit field κ
elig × resp × advantage] + CR --> PL[Plasticity engine
ΔF-gated rewrites] + PL -->|rewrite connectome| RT + + subgraph FAST[fast: inference + effector] + JP + RT + NEU + REF + EFF + end + subgraph SLOW[slow: plasticity] + CR + PL + end +``` + +两半的接缝在 `EFF → CR`:效应器内核产出 `r_t`,信用场把它分配到突触,可塑性引擎据此改写连接组。 + +--- + +## 3. 细胞类型 = 组件(接口签名草案) + +签名用 Python 风格类型草图(仓库即 Python);非最终 API。 + +### 3.1 连接组状态 + +```python +class Aspect: # 节点 + id: str + tau: str # 符号身份(可读、可编辑) + neuron_type: Literal["excitatory", "inhibitory"] + params: dict # 增益 g、可学路由参数等 + buffer: Deque[Sample] # (phi, activation, r) 滑窗 + +class Synapse: # 有向边 + src: str; dst: str + w: float # 可学权重 + e: float # 资格迹 + pointcut: Pointcut # 内容条件化路由谓词 + +class Connectome: # = DCN 图(复用 DCNStore) + aspects: dict[str, Aspect] + synapses: list[Synapse] + reflex_core: frozenset[str] # 保守核(不可随机改写) +``` + +### 3.2 兴奋性 aspect-LLM 神经元(推理) + +```python +class ExcitatoryNeuron(Aspect): + def propose(self, ctx: Context) -> Candidate: + # ctx = 路由进来的上下文 + 织入的 advice + # 返回候选动作/文本(可为一次 LLM 调用) + ... +``` + +### 3.3 抑制性反射 aspect(确定性引用监视器) + +```python +class InhibitoryReflex(Aspect): + def mediate(self, action: Action, state: State) -> Decision: + # Decision = Allow | Deny(reason) | Rewrite(action') + # 确定性谓词;安全关键 → fail-closed + ... +``` + +### 3.4 突触路由(注意力 / 权重) + +```python +class Router: + def route(self, jp: Joinpoint) -> list[tuple[Aspect, float]]: + # 返回 (aspect, activation_score) —— 复用 ConcernVector.activation_score + ... +``` + +### 3.5 效应器内核(新——自建效应器,产出 r_t) + +```python +class EffectorKernel: + def run_turn(self, jp: Joinpoint) -> Outcome: + # 1) route → 2) excitatory.propose → 3) inhibitory.mediate(边界闸门) + # 4) verifier 校验 → 5) propose-check-repair 回合 + # 发射:动作结果 + 确定性 r_t + JSONL 可重放日志 + ... +``` + +### 3.6 信用场 + 可塑性引擎(新——取代启发式 meta 治理) + +```python +class CreditField: + def attribute(self, outcome: Outcome) -> None: + # κ(a) += (r - b) · e_a · rho_a ; κ(s) += (r - b) · e_s + # 守恒:Σ_a κ_a = r - b + +class PlasticityEngine: + def step(self, scale: Literal["warm", "cold"]) -> list[Rewrite]: + # 以速率 min(1, exp(-ΔF/T)) 接受改写 + # 原语:connect / prune / reweight / split / lift / merge +``` + +--- + +## 4. 一回合的时序 + +1. `Joinpoint` 事件携带上下文 `φ`(= query)。 +2. `Router` 用 pointcut 匹配候选,给出 `activation_score`(突触发放)。 +3. 兴奋性 aspect-LLM `propose` 候选(weaver 仍负责为其组合 prompt 注入)。 +4. 抑制性反射在节点间与效应边界 `mediate`(allow/deny/rewrite)。 +5. `EffectorKernel` 跑 verify → repair,执行动作面(工具/内存写/消息),发射 `r_t` + 日志。 +6. `CreditField.attribute` 把 `r_t` 分到突触/节点(资格迹 × 责任 × 优势,守恒)。 +7. `PlasticityEngine`(温:reweight/connect/prune;冷:split/lift/merge + tier-2 校准)改写连接组。 +8. 下一回合用更新后的图。 + +--- + +## 5. 三时间尺度 → 运行时落点 + +| 尺度 | 跑什么 | 现有落点 | +|---|---|---| +| 快(每轮) | 推断 + 资格迹累积 | `loops/event_loop` | +| 温(近线) | reweight / connect / prune | daemon 工作线程 | +| 冷(心跳) | split / lift / merge + tier-2 校准 + 稳态归一 | daemon `tick()` / heartbeat(M6) | + +M6 的 `DecayWorker`/`MergeArchiver` 不丢弃,降级为可塑性的**稳态/剪枝那一半**;缺的增强(LTP)+ 资格迹由可塑性引擎补上。 + +--- + +## 6. 与现有包的对应 + +| 处置 | 组件 | +|---|---| +| **复用** | `DCNStore`、JSONL replay(=可塑性可重放确定性基础设施)、`ConcernVector.activation_score`、`pointcut` 策略、`weaving/weaver`(为兴奋神经元组合注入) | +| **改** | `Concern` → 加 `neuron_type` 与可学参数;`advice/TOOL_GUARD` + 宿主 `tool_guard.py` → 提升为效应器内**权威**反射(不再"宿主可能尊重");`meta/*` + heartbeat worker → 并入可塑性引擎 | +| **新增** | **效应器内核**(propose-check-repair + 动作面 + verifier + `r_t` 发射);**信用场 κ**;**ΔF 改写引擎**(split/lift/connect/prune/reweight/merge) | + +关键收益:自建效应器把 `BLOCK` 从"宿主可能尊重"变为"按构造拦得住",一举解决协作式与 fail-open。 + +--- + +## 7. (i)→(ii) 迁移阶段(发育,非重写) + +1. **(i) 现可建**:1 个兴奋 aspect-LLM + 一圈抑制反射 + 可学路由。= 现状收回效应器 + 装闭环。 +2. **加宽**:多兴奋神经元,按 pointcut 分流(MoE 式条件计算)。 +3. **加深**:`lift`(aspect-of-aspect)长出高阶神经元,神经元彼此路由 → (ii) 连接组。 +4. 全程**同一条可塑性律**,从"门控一个 LLM"扩展到"给整张 LLM-神经元网布线"。 + +--- + +## 8. 不变量与安全 + +- 保守核反射 aspect(brainstem)不可被随机改写。 +- 安全关键动作 fail-closed(与 v0.2 现状的 fail-open 相反)。 +- tier-1 可塑性可重放确定(给定日志 + 常数,结构轨迹逐字节复现)。 +- 细化(split)/ 恒等初始化(lift)保证改写在区域外不改变行为。 + +--- + +## 9. 残差与开放问题 + +- 软 advice 因果不透明 ⇒ 软神经元信用是统计的(论文 §9 那条主线)。把软织入尽量换成硬反射,既提升可靠性又让信用变干净——同一个动作。 +- 两道荷载关:信用清洗的干净度;特征 `φ` 的获取/生长(后者是元结构学习)。 +- 多节点跨图信用分配在长视野下噪声大;tier-2 反事实校准昂贵。 + +--- + +## 10. OpenClaw → 效应器内核改造(权威反射监视器) + +OpenClaw 是改造成效应器内核(§3.5)最务实的底座:它已提供真在驱动 LLM 的回合,且 `hook-bindings.ts` 的 `HookKind` 已天然枚举出反射闸门 + 注入点 + 结果流。落 (i) 不是从零造 agent,而是把 OpenClaw 现有的**协作式** hook 提升为**权威、in-proc、安全关键 fail-closed**,再补 verify→repair 与 `r_t` 发射。 + +**本节描述目标态。** 当前实现分期见 **§10.5**; 连线层 hook 表见 [joinpoint model §4.1](./opencoat-openclaw-joinpoint-model-v0.1.md#41-mvp-emit-status-bridge-integrationsopenclaw-opencoat-bridge). + +### 10.1 改造四步与 hook 落点 + +| 步骤 | OpenClaw hook | 改造 | +|---|---|---| +| 1. 权威反射 | `before_tool_call` / `message_sending` / `subagent_spawning` / `queue_before_enqueue` | 把 `tool_guard.py` 的 `ToolGuardOutcome` 从"建议"变"裁决";**in-proc**(不走 daemon RPC);安全关键 fail-closed | +| 2. verify→repair | `before_agent_reply` | 回复前跑 OpenCOAT `verifier`;失败则约束并重提示一次 | +| 3. `r_t` 发射 | `after_tool_call` / `llm_output` / `agent_end` | 把 decision + 判决汇成结构化 `r_t`,写 JSONL replay | +| 4. 可塑性消费 | daemon `tick()` | daemon 只跑 `PlasticityEngine` 的 reweight 子集,消费 `r_t` | + +\* Step 1 中 **`queue_before_enqueue` 已在 fork 落地**,但 bridge 仍走 **daemon RPC 协作 guard** (非 in-proc TCB). `tool` / `message` / `subagent` 同理. + +**in-proc 红利**:`before_message_write` / `tool_result_persist` 这些之前因"同步热路径不能 await daemon RPC"被 `SKIPPED_HOOKS` 跳过的 hook,在监视器进程内同步运行后,**可重新纳入守护**(内存写/工具结果落盘也能 gate). **今天仍 skip** — 待 ReflexMonitor 落地. + +### 10.2 权威反射监视器接口(小可信核) + +```python +@dataclass(frozen=True) +class Action: # 类型化、结构化的待执行动作 + kind: Literal["tool_call", "message_send", "subagent_spawn", + "queue_enqueue", "memory_write"] + name: str + args: Mapping[str, Any] + resource_scope: frozenset[str] # 触及的资源/能力 + risk_tags: frozenset[str] # {"external_write","irreversible","spend",...} + raw: Any # 宿主原生句柄(供 rewrite 透传) + +@dataclass(frozen=True) +class State: # 只读上下文快照(谓词可读) + session_id: str; turn_id: str + features: Mapping[str, Any] + +class Decision: ... # 和类型:Allow | Deny | Rewrite +@dataclass(frozen=True) +class Allow(Decision): ... +@dataclass(frozen=True) +class Deny(Decision): reason: str; policy_id: str +@dataclass(frozen=True) +class Rewrite(Decision): action: Action; reason: str; policy_id: str + +class ReflexPolicy(Protocol): # = 一个抑制性 aspect 的确定性规则 + id: str + criticality: Literal["safety_critical", "advisory"] + def applies(self, a: Action, s: State) -> bool: ... # 廉价谓词 + def decide(self, a: Action, s: State) -> Decision: ... # 确定性,无 LLM/IO + +class ReflexMonitor: # 小可信核(TCB) + def __init__(self, policies: Sequence[ReflexPolicy], + *, conserved_core: frozenset[str]): ... + def mediate(self, a: Action, s: State) -> tuple[Decision, DecisionRecord]: + # 完全中介:每个被守护边界都经此。纯函数 → 可重放。 + ... +``` + +### 10.3 关键语义 + +- **完全中介(complete mediation)**:每个被守护边界必须调 `mediate`,宿主不得有绕过它执行守护动作的路径。可用插桩检验("是否每次工具调用都过了 mediate")。 +- **决策格**:`Deny > Rewrite > Allow`;任一 safety_critical 的 `Deny` 取胜(最严);多条 `Rewrite` 按 `policy_id` 定序合成,冲突则降为 `Deny`。定序保证可复现。 +- **fail-closed(反转现状)**:safety_critical 策略出错/超预算/监视器不可用 → `Deny`;advisory 出错 → 跳过该策略(仅 advisory 允许 fail-open)。这正是把现状 bridge 的 `return {}`(全线放行)反过来。 +- **确定性**:`mediate` 是 `(policies, action, state)` 的纯函数——无 LLM、无 I/O、无 wall-clock 分支 → 逐回合可重放。 +- **in-proc 预算**:每次 `mediate` 有硬 CPU 预算(谓词 O(policies),无网络);超预算按出错处理(safety_critical → Deny)。 +- **审计/信用**:每次 `mediate` 发 `DecisionRecord`(turn、action 摘要、decision、policy_id、reason、criticality)进 `r_t` 流与 JSONL。硬中介 = 干净信用(论文 §9)。 +- **保守核**:`conserved_core` 的 policy id 不可被 `PlasticityEngine` 改写(brainstem)。 + +### 10.4 语言/进程边界 + +监视器要在 OpenClaw 进程内同步运行才能权威 + 低延迟,而 OpenClaw 插件是 TS/Node。落法:**小可信核用宿主语言(TS,bridge 内)实现**,评估一份从 OpenCOAT 导出的**可移植策略规格**(确定性谓词 + criticality);**重学习(Python `PlasticityEngine`)留在 daemon**。即"小可信核在宿主侧,大学习在进程外"——与 §5 三时间尺度一致(热路径 in-proc,温/冷在 daemon)。 + +### 10.5 实现分期 (2026-05) + +| OpenClaw hook | Joinpoint | 协作式 bridge (今) | 权威 ReflexMonitor (下一步) | +|---|---|---|---| +| `before_tool_call` | `tool.before_call` | `tool_guard` + daemon RPC **or in-proc TCB** (`inProcReflexToolGuard`) | in-proc fail-closed (default path when flag on) | +| `message_sending` | `response.before_final` | outbound cancel (协作) | in-proc + verify→repair | +| `subagent_spawning` | `task.before_create` | spawn veto (协作) | in-proc deny | +| `queue_before_enqueue` | `queue.before_enqueue` | **fork hook + `queue_guard`** block/rewrite | in-proc | +| `before_message_write` | `memory.before_write` | **skipped** | in-proc when TCB lands | +| `tool_result_persist` | — | **skipped** | in-proc when TCB lands | +| `after_tool_call` / `llm_output` / `agent_end` | observe JPs | DCN observe | **`r_t` emit** | + +Dogfood (queue collaborative guard): [`examples/09_queue_hook_dogfood`](../examples/09_queue_hook_dogfood/README.md). Full mapping: [joinpoint model Appendix E](./opencoat-openclaw-joinpoint-model-v0.1.md#appendix-e--v03-action--a_reflex-mapping). + +--- + +## 11. 下一步 + +0. **文档对齐 + queue dogfood 收尾** — joinpoint §4.1 / Appendix E, [`examples/09_queue_hook_dogfood`](../examples/09_queue_hook_dogfood/README.md), fork gateway ops ([§5.7 joinpoint model](./opencoat-openclaw-joinpoint-model-v0.1.md#57-fork-gateway-ops-queue--native-hooks)). +1. 落 (i):实现**效应器内核**接口 + 把 `tool_guard` 提升为 **in-proc 权威反射** (TCB 原型) + 装上 `CreditField`/`PlasticityEngine` 的 reweight 子集. +2. **`r_t` JSONL** — wire `after_tool_call` / `agent_end` emission; daemon 消费. +3. 凿 `lift` 与 split 的实现(形式纲要 §5 已给规格). +4. 用 JSONL replay 写可塑性的可重放确定性单元测试(对应论文 §8 可证伪预测). diff --git a/docs/guides/concern-authoring-aop.md b/docs/guides/concern-authoring-aop.md index 255cf7e..8662954 100644 --- a/docs/guides/concern-authoring-aop.md +++ b/docs/guides/concern-authoring-aop.md @@ -52,6 +52,8 @@ Use the **HyperdustLabs fork** (`opencoat/hooks-v0.1`, see [openclaw-fork-dev.md | **Decision** | `queue.before_enqueue`, `tool.before_call`, `subagent_spawning` → `task.before_create` | block, rewrite, spawn veto, prompt prepend, outbound cancel | | **Observe** | `reply_run.*`, `planning.*`, `approval.requested`, `command.output_stream`, `patch.summary_created`, `error.detected`, queue poll fallback | DCN / activation only; no sync veto | +**Decision** = **collaborative guard** (bridge + daemon RPC; host applies advice). Not ADR-0012 **authoritative** in-proc `ReflexMonitor` fail-closed — see [v0.3 §10.5](../design/v0.3-morphogenetic-architecture.md#105-实现分期-2026-05). + **Next decision hooks** ship on the **same fork branch** (`tool_result_persist`, `reply_run.phase.*`, `response.before_final`, …) — not upstream `openclaw/openclaw`. See [fork hook backlog](openclaw-fork-dev.md#fork-hook-backlog-post-queue). Prefer `user_message()` over flat `before_response` when the bridge sends `messages[]`: diff --git a/docs/guides/openclaw-fork-dev.md b/docs/guides/openclaw-fork-dev.md index ed7bbeb..0ea3c42 100644 --- a/docs/guides/openclaw-fork-dev.md +++ b/docs/guides/openclaw-fork-dev.md @@ -87,6 +87,24 @@ After [PR #77](https://github.com/HyperdustLabs/OpenCOAT/pull/77) (queue `queue_ Bridge skipped (fork has hook, hot path): `before_message_write`, `tool_result_persist` until sync/async contract is extended. +## Troubleshooting queue guard + +If gateway logs show `unknown typed hook "queue_before_enqueue" ignored`, the running +gateway is **not** on fork `dist/` (stale LaunchAgent or registry OpenClaw). Queue sync +veto/rewrite will **not** run; poll fallback may still emit observe-only +`queue.before_enqueue` to DCN. + +```bash +./scripts/check-openclaw-fork.sh +openclaw gateway status # CLI version == Gateway version; cmdline uses ~/openclaw-fork/dist/index.js +grep opencoat-bridge ~/.openclaw/logs/gateway.log # expect "registered 29 hooks", no queue hook ignored +``` + +**v0.3 (i) note:** queue guard on fork is the first **collaborative** effect-boundary +pilot ([v0.3 §10.5](../design/v0.3-morphogenetic-architecture.md#105-实现分期-2026-05), +[examples/09_queue_hook_dogfood](../../examples/09_queue_hook_dogfood/README.md)). In-proc +authoritative `ReflexMonitor` is the next step, not done today. + ## Related - [OpenClaw bridge README](../../integrations/openclaw-opencoat-bridge/README.md) diff --git a/examples/09_queue_hook_dogfood/README.md b/examples/09_queue_hook_dogfood/README.md index bb817c7..15b59a1 100644 --- a/examples/09_queue_hook_dogfood/README.md +++ b/examples/09_queue_hook_dogfood/README.md @@ -1,9 +1,11 @@ -# 09 — Queue hook dogfood (OpenClaw fork + bridge) - -End-to-end dogfood for **native** `queue_before_enqueue` / `queue_after_enqueue` -on the OpenClaw fork (`opencoat/hooks-v0.1`). OpenCOAT matches -`queue.before_enqueue` and returns advice the bridge maps to OpenClaw -`{ block, prompt, summaryLine }`. +# 09 — Queue hook dogfood (v0.3 (i) queue boundary pilot) + +End-to-end dogfood for **v0.3 migration phase (i)**: the first **hard effect boundary** +pilot on the collaborative bridge — native `queue_before_enqueue` / `queue_after_enqueue` +on the OpenClaw fork (`opencoat/hooks-v0.1`). This is **not** in-proc authoritative +`ReflexMonitor` ([v0.3 §10.5](../../docs/design/v0.3-morphogenetic-architecture.md#105-实现分期-2026-05)); +OpenCOAT matches `queue.before_enqueue` and returns advice the bridge maps to OpenClaw +`{ block, prompt, summaryLine }` via daemon RPC. Import **one concern at a time** — all three target the same joinpoint. From 7162fd6d30e2451fa240795a76366dfeedd81eb9 Mon Sep 17 00:00:00 2001 From: moss Date: Sun, 24 May 2026 20:37:44 +0700 Subject: [PATCH 2/3] docs: fix queue dogfood link path from docs/design Use ../../examples/... so the link resolves from docs/design/ (not docs/examples/). Co-authored-by: Cursor --- docs/design/v0.3-morphogenetic-architecture.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/design/v0.3-morphogenetic-architecture.md b/docs/design/v0.3-morphogenetic-architecture.md index 315d9df..4463f22 100644 --- a/docs/design/v0.3-morphogenetic-architecture.md +++ b/docs/design/v0.3-morphogenetic-architecture.md @@ -279,13 +279,13 @@ class ReflexMonitor: # 小可信核(TCB) | `tool_result_persist` | — | **skipped** | in-proc when TCB lands | | `after_tool_call` / `llm_output` / `agent_end` | observe JPs | DCN observe | **`r_t` emit** | -Dogfood (queue collaborative guard): [`examples/09_queue_hook_dogfood`](../examples/09_queue_hook_dogfood/README.md). Full mapping: [joinpoint model Appendix E](./opencoat-openclaw-joinpoint-model-v0.1.md#appendix-e--v03-action--a_reflex-mapping). +Dogfood (queue collaborative guard): [`examples/09_queue_hook_dogfood`](../../examples/09_queue_hook_dogfood/README.md). Full mapping: [joinpoint model Appendix E](./opencoat-openclaw-joinpoint-model-v0.1.md#appendix-e--v03-action--a_reflex-mapping). --- ## 11. 下一步 -0. **文档对齐 + queue dogfood 收尾** — joinpoint §4.1 / Appendix E, [`examples/09_queue_hook_dogfood`](../examples/09_queue_hook_dogfood/README.md), fork gateway ops ([§5.7 joinpoint model](./opencoat-openclaw-joinpoint-model-v0.1.md#57-fork-gateway-ops-queue--native-hooks)). +0. **文档对齐 + queue dogfood 收尾** — joinpoint §4.1 / Appendix E, [`examples/09_queue_hook_dogfood`](../../examples/09_queue_hook_dogfood/README.md), fork gateway ops ([§5.7 joinpoint model](./opencoat-openclaw-joinpoint-model-v0.1.md#57-fork-gateway-ops-queue--native-hooks)). 1. 落 (i):实现**效应器内核**接口 + 把 `tool_guard` 提升为 **in-proc 权威反射** (TCB 原型) + 装上 `CreditField`/`PlasticityEngine` 的 reweight 子集. 2. **`r_t` JSONL** — wire `after_tool_call` / `agent_end` emission; daemon 消费. 3. 凿 `lift` 与 split 的实现(形式纲要 §5 已给规格). From 1fb7a4ff917be0585f5386c2e4cb3bfc90f952c9 Mon Sep 17 00:00:00 2001 From: moss Date: Sun, 24 May 2026 20:37:57 +0700 Subject: [PATCH 3/3] docs: fix queue dogfood links from docs/guides Same ../../examples/... prefix as other docs under docs/. Co-authored-by: Cursor --- docs/guides/concern-authoring-aop.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/concern-authoring-aop.md b/docs/guides/concern-authoring-aop.md index 8662954..514e60d 100644 --- a/docs/guides/concern-authoring-aop.md +++ b/docs/guides/concern-authoring-aop.md @@ -41,7 +41,7 @@ The gateway bridge registers **29** plugin hooks plus **runtime observers** (`on queue/task poll) for MVP joinpoints such as `queue.before_enqueue` (sync **block/rewrite** on OpenClaw fork via `queue_before_enqueue`) and `reply_run.before_begin` (observe-only — see [joinpoint model §4.1](../design/opencoat-openclaw-joinpoint-model-v0.1.md#41-mvp-emit-status-bridge-integrationsopenclaw-opencoat-bridge)). -Dogfood concerns: [`examples/09_queue_hook_dogfood`](../examples/09_queue_hook_dogfood/README.md). +Dogfood concerns: [`examples/09_queue_hook_dogfood`](../../examples/09_queue_hook_dogfood/README.md). ### Decision vs observe (OpenClaw fork + bridge) @@ -115,7 +115,7 @@ from `expression()` today). Bridge maps woven advice to OpenClaw `queue_before_e } ``` -Full dogfood set: [`examples/09_queue_hook_dogfood`](../examples/09_queue_hook_dogfood/README.md). +Full dogfood set: [`examples/09_queue_hook_dogfood`](../../examples/09_queue_hook_dogfood/README.md). ## Declare precedence