Integrate peer review findings into architecture docs

- 01: add eight testable hard invariants (self-approval ban, duty
  separation, digest-bound approvals, permit-only effects, LLM-less
  degraded operation)
- 03: approval staleness model — proposal digest, FRESH_CHECK/STALE
  states, APPROVED→AUTHORIZED split with revocable ExecutionPermit;
  gateways accept permits, never bare plans
- 05: rules packaged as versioned, testable Policy Packs pinned in
  proposal lineage
- 02: approval workbench reshaped into a Case Desk (DecisionCase as
  the operator's accountability unit)
- 10 (new): cross-province federation boundary — signed artifacts
  only, plus three phase-1 no-rework reservations
- 08: add M5 shadow-run milestone as phase-1 acceptance form
- 00/04/07: object table, doc map, and walkthrough consistency updates
- add brainstorming.md (peer review source document)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019u5SLNweVio6ozJX7yfxQr

🔮 View transcript: https://logs.lojong.info/s/e8u90k3t33w590r7b5y7yzqh

brainstorming.md

@@ -0,0 +1,597 @@
+# VPP AI Platform Architecture Brainstorming
+
+## 1. Purpose
+
+This document develops the technical architecture proposed for the virtual power
+plant multi-timescale collaborative operations platform. It is intended for
+business architects, platform engineers, algorithm teams, control-system
+engineers, security teams, and project stakeholders.
+
+The goal is not to select products or implementation frameworks yet. The
+immediate goal is to agree on:
+
+- The system's major trust and responsibility boundaries.
+- The role AI and large language models should play.
+- How decisions become approved external actions.
+- How the platform should divide work across time and spatial scales.
+- Which architecture should be taken into detailed design.
+
+## 2. Executive Recommendation
+
+The proposal has a strong business vision, but the platform should not be
+implemented literally as five autonomous agents coordinated by a single
+all-purpose runtime.
+
+The recommended direction is:
+
+1. Use a deterministic, event-driven VPP operating kernel as the operational
+   foundation.
+2. Present work to operators through durable operation and decision cases.
+3. Expose a small decision-case lifecycle API to external systems.
+4. Treat the five agents as business-facing roles and replaceable contributors,
+   not as trust boundaries or direct controllers.
+5. Allow AI to create, compare, and explain draft decisions, but never to
+   authorize or directly execute consequential actions.
+
+In short:
+
+> The operational domain should remain correct, auditable, and usable when the
+> LLM is unavailable.
+
+## 3. What Is Already Strong
+
+The proposal establishes several sound principles:
+
+- It covers the full operational loop from monitoring and planning to execution
+  feedback and review.
+- It explicitly states that AI must not directly control terminal equipment.
+- It includes rule validation, simulation, human approval, rollback, and audit.
+- It builds on existing business processes, algorithms, data, and resource
+  access.
+- It evaluates success through operational and financial outcomes rather than
+  model capability alone.
+- It recognizes that annual, monthly, day-ahead, intraday, and real-time
+  decisions require coordination.
+
+These principles should be preserved as architectural invariants.
+
+## 4. Architectural Questions in the Current Proposal
+
+Several aspects need to be resolved before detailed system design begins.
+
+### 4.1 Agent taxonomy is inconsistent
+
+The proposal alternates between five agent roles and six business stages. Names
+also change between analysis, resource dispatch or organization, transaction
+gaming or decision-making, transaction service or user interaction, and load
+control or load management.
+
+If these names become public APIs or independently deployed services, normal
+changes in the business model will cause expensive coupling. They are better
+treated as product personas or internal capability compositions.
+
+### 4.2 The LLM appears too foundational
+
+The diagrams place the Guangming power model at the bottom of the architecture.
+This suggests that normal operation depends on LLM availability and behavior.
+
+Forecasting, flexibility calculation, optimization, rule enforcement, approval,
+market submission, and device control must remain available without an LLM. The
+LLM should be an advisory and orchestration participant above a deterministic
+operating foundation.
+
+### 4.3 The runtime owns too much
+
+The proposed Agent Runtime includes workflow orchestration, context
+construction, memory, tools, security, and state synchronization. This risks
+becoming a platform-wide bottleneck and a single failure domain.
+
+Workflow durability, operational state, model execution, policy enforcement,
+approval authority, and control execution should have separate responsibilities
+and contracts.
+
+### 4.4 Time scales are not separated operationally
+
+Second-level equipment control and day-ahead reasoning appear in the same
+logical workflow. They have different availability, latency, determinism, and
+safety requirements.
+
+Real-time control should live at the site or edge and use prevalidated policies.
+Cloud or provincial AI workflows should produce bounded plans and control
+envelopes rather than participate in a fast control loop.
+
+### 4.5 Knowledge and executable rules are conflated
+
+RAG is useful for retrieving regulations, operating procedures, explanations,
+and historical cases. It must not be the authoritative mechanism for enforcing a
+market rule, safety limit, or device constraint.
+
+Consequential rules should be stored as versioned, testable, executable policy
+packs. RAG may explain a policy or locate its source, while a deterministic
+policy engine enforces it.
+
+### 4.6 Decision provenance is underspecified
+
+The architecture needs canonical, versioned representations of forecasts,
+constraints, flexibility, plans, approvals, commands, execution receipts, and
+settlement outcomes. Without these, simulation, approval, replay, and audit
+cannot reliably refer to the same decision.
+
+### 4.7 Cross-province operation needs a federation boundary
+
+Cross-province collaboration should not imply a single central platform with
+unrestricted access to raw telemetry or terminal control. The exchanged objects
+should normally be signed flexibility envelopes, commitments, bids, awards, and
+settlement facts.
+
+## 5. Non-Negotiable Architecture Invariants
+
+The following invariants should guide all designs:
+
+- AI cannot approve its own proposal.
+- AI cannot directly call a market-submission or device-control endpoint.
+- Every consequential action is bound to an immutable artifact digest and a
+  validity window.
+- Approval is invalidated when material evidence, constraints, or the proposed
+  effect changes.
+- Operational decisions retain their input data snapshot, rule version, model
+  version, solver version, and approvals.
+- External effects are idempotent and produce durable receipts.
+- The platform supports replay from recorded evidence.
+- Degraded operation remains possible without the LLM.
+- Edge control remains safe during provincial-platform or wide-area network
+  outages.
+- Operational truth is stored in authoritative domain stores, not in agent
+  memory.
+
+## 6. Three Architecture Alternatives
+
+The following alternatives are intentionally different rather than variations of
+the same agent-runtime design.
+
+### 6.1 Alternative A: Minimal Decision Platform
+
+This design exposes only three lifecycle operations:
+
+```ts
+interface VppDecisionPlatform {
+  start(request: DecisionRequest): Promise<DecisionCase>;
+  act(action: CaseAction): Promise<DecisionCase>;
+  observe(query: CaseQuery): Promise<CaseObservation>;
+}
+```
+
+Human requests, scheduled jobs, and operational events all create a versioned
+decision case. The caller never selects an agent, prompt, model, skill, or
+solver.
+
+A day-ahead planning case may produce:
+
+- Load, renewable-generation, and market-price forecasts.
+- A resource portfolio and flexibility envelope.
+- Candidate market bids.
+- A customer response plan.
+- A dispatch envelope.
+- Rule and simulation results.
+- Separate approval gates for market submission, outreach, and dispatch.
+
+An authorized user approves an exact proposal version and digest. Approval does
+not grant the AI direct access to an external system; it allows a guarded
+adapter to process the authorized effect.
+
+This design hides orchestration, retries, agent topology, model selection, tool
+invocation, and integration protocols very effectively. Its main risk is that
+`DecisionCase` and the service behind it become generic containers with
+insufficient domain boundaries.
+
+### 6.2 Alternative B: Event-Driven VPP Operating Kernel
+
+This design makes the deterministic operational domain the foundation and treats
+AI as a replaceable adapter.
+
+Representative ports are:
+
+```ts
+interface ObservationIngestPort {
+  record(observation: Observation): Promise<EvidenceReference>;
+}
+
+interface CommandPort {
+  execute(command: DomainCommand): Promise<CommandResult>;
+}
+
+interface ControlAuthorityPort {
+  authorize(
+    plan: CandidatePlan,
+    simulation: SimulationResult,
+    approvals: Approval[],
+  ): Promise<ExecutionPermit | Denial>;
+}
+
+interface ControlGateway {
+  dispatch(permit: ExecutionPermit): Promise<ExecutionReceipt>;
+}
+```
+
+The core invariant is:
+
+> Evidence can trigger decisions; decisions can propose effects; only the
+> authority plane can authorize effects.
+
+For a demand-response operation, the system records the request as evidence,
+calculates a forecast and flexibility envelope, creates candidate plans, runs
+safety simulation, collects approval, and requests an execution permit. The
+control gateway accepts a permit, not a raw plan.
+
+This alternative offers the strongest replayability, auditability, safety
+isolation, and AI replaceability. Its cost is conceptual complexity: teams must
+handle commands, observations, events, idempotency, revisions, projections, and
+eventual consistency correctly.
+
+### 6.3 Alternative C: Operations Case Desk
+
+This design optimizes the product around the operator's unit of accountability:
+a bounded operational case.
+
+Examples include:
+
+- Prepare tomorrow's market bid.
+- Deliver a 20 MW demand-response event.
+- Resolve an execution deviation.
+- Review a completed dispatch.
+
+The operator-facing interface is:
+
+```ts
+interface OperationsDesk {
+  open(kind: CaseKind, input: CaseInput): Promise<CaseId>;
+  read(caseId: CaseId): Promise<CaseView>;
+  apply(command: CaseCommand): Promise<CommandReceipt>;
+  watch(caseId: CaseId): AsyncIterable<CaseEvent>;
+}
+```
+
+Each case contains its objective, owner, horizon, evidence, assumptions,
+scenario branches, recommendations, approvals, execution receipts, and outcome.
+An advanced operator can fork a high-price or low-solar scenario without
+directly invoking an agent.
+
+This design produces the strongest operator experience and naturally organizes
+audit and collaboration. Its principal risk is turning a case into a permanent
+collection of unrelated activity. Each case therefore needs one accountable
+objective, an explicit deadline, an owner, and a completion contract.
+
+## 7. Comparison and Recommended Hybrid
+
+The Minimal Decision Platform has the smallest learning and misuse surface for
+external callers. It is a deep interface, but its simplicity can conceal an
+overly centralized implementation.
+
+The Event-Driven Operating Kernel is the strongest internal architecture for a
+safety-sensitive and heavily audited system. It makes evidence, authority, and
+external effects explicit. It is less convenient as the operator's primary
+mental model.
+
+The Operations Case Desk best matches how business users collaborate and accept
+responsibility for decisions. It is not, by itself, sufficient as the low-level
+operating and control architecture.
+
+The recommended hybrid is therefore:
+
+- Event-driven deterministic kernel inside.
+- Operations Case Desk for operators.
+- Minimal decision-case API for external systems.
+
+The layers complement one another instead of duplicating responsibilities.
+
+## 8. Recommended Logical Architecture
+
+```mermaid
+flowchart TB
+    T[Operators / Schedules / Operational Events] --> C[Operations Case Desk and Decision API]
+    C --> P[Durable Process Manager and Decision Ledger]
+
+    P --> F[Forecasting Services]
+    P --> R[Flexibility and Resource Portfolio Services]
+    P --> M[Market and Dispatch Optimization]
+    P --> U[Customer Response Planning]
+    P --> S[Settlement and Review]
+
+    A[LLM Advisor and Agent Roles] --> P
+    A --> F
+    A --> R
+    A --> M
+    A --> U
+
+    F --> G[Policy Validation]
+    R --> G
+    M --> G
+    U --> G
+
+    G --> V[Simulation and Fresh-State Verification]
+    V --> H[Human Approval]
+    H --> E[Execution Authority]
+    E --> X[Market / Messaging / Control Gateways]
+    X --> D[Site and Edge Controllers]
+    D --> O[Execution Observations]
+    O --> P
+```
+
+### 8.1 Experience plane
+
+The experience plane provides the operations desk, dashboards, AI-assisted
+investigation, scenario comparison, approval inbox, and operational reports.
+Pages are projections over cases and the decision ledger rather than independent
+workflow silos.
+
+### 8.2 Orchestration plane
+
+The orchestration plane owns durable process state, deadlines, retries,
+compensation, correlation, and case progression. It invokes domain capabilities
+but does not perform forecasting, optimization, authorization, or control
+itself.
+
+### 8.3 Decision-services plane
+
+Domain services provide deterministic or bounded capabilities:
+
+- Load, generation, and price forecasting.
+- Resource capability and flexibility assessment.
+- Portfolio aggregation and commitment management.
+- Market bidding and dispatch optimization.
+- Customer segmentation and response planning.
+- Simulation, deviation analysis, settlement, and attribution.
+
+These services accept complete, versioned inputs and return typed artifacts with
+provenance.
+
+### 8.4 AI advisory plane
+
+The AI layer provides intent understanding, task decomposition, retrieval,
+explanation, report generation, tool selection, and candidate strategy
+generation. The five proposed agents can exist here as business-specific
+contributors.
+
+There should be no `executeDeviceCommand` or unrestricted `submitMarketBid` tool
+available to an agent.
+
+### 8.5 Authority and execution plane
+
+This plane enforces executable policies, separation of duties, approval
+requirements, current-state verification, permit expiry, and effect limits. It
+is the only route to market, messaging, and control gateways.
+
+### 8.6 Evidence and data plane
+
+This plane records raw observations, normalized telemetry, business events,
+reference data, feature values, forecasts, model outputs, decisions, and
+execution outcomes. It supports point-in-time reconstruction and replay.
+
+## 9. Decision and Execution Lifecycle
+
+A consequential artifact should follow an explicit lifecycle:
+
+```text
+DRAFT
+  -> VALIDATED
+  -> SIMULATED
+  -> APPROVED
+  -> AUTHORIZED
+  -> ISSUED
+  -> ACKNOWLEDGED
+  -> COMPLETED / FAILED / ROLLED_BACK
+```
+
+The LLM may create or explain a `DRAFT`. It cannot advance an artifact to
+`AUTHORIZED`.
+
+Approval should bind to:
+
+- The exact artifact digest.
+- The approved effect scope.
+- Financial and quantity limits.
+- A validity window.
+- The approver's identity and role.
+- The evidence and policy versions used for evaluation.
+
+If material telemetry, constraints, rules, or proposed effects change, the
+approval becomes stale.
+
+## 10. Separation by Time Scale
+
+### Seconds
+
+Site and edge controllers own equipment protection, local interlocks, fast
+feedback control, and prevalidated fallback behavior. There is no LLM dependency
+in this loop.
+
+### One to fifteen minutes
+
+Streaming services perform telemetry processing, state estimation, deviation
+detection, rolling forecasts, and bounded corrective optimization. Any automatic
+response must be preauthorized and constrained.
+
+### Intraday and day-ahead
+
+The provincial platform performs market analysis, portfolio planning, scenario
+comparison, operator review, and approval. This is the main operating range for
+AI-assisted decision workflows.
+
+### Monthly and annual
+
+Planning services support contract strategy, resource acquisition, capacity
+planning, model training, policy analysis, and long-horizon simulation.
+
+## 11. Separation by Spatial Scale
+
+### Device and site
+
+The site retains device protocols, protection constraints, local control, and
+detailed telemetry. It exposes a controlled resource capability interface
+upward.
+
+### Aggregation unit
+
+The aggregation layer calculates site or resource-group flexibility envelopes,
+manages local commitments, and translates bounded dispatch envelopes into site
+plans.
+
+### Provincial platform
+
+The provincial layer manages portfolios, markets, operator decisions, approval,
+reporting, and province-wide optimization.
+
+### Cross-province federation
+
+Federated platforms should exchange signed and versioned business artifacts such
+as:
+
+- Flexibility envelopes.
+- Available capacity and reserve.
+- Commitments and constraints.
+- Bids and awards.
+- Delivery and settlement facts.
+
+Raw device control authority and unrestricted customer-level telemetry should
+not cross this boundary by default.
+
+## 12. Canonical Domain Contracts
+
+Before selecting implementation frameworks, the project should define and
+version the following objects:
+
+- `Resource`
+- `ResourceCapability`
+- `Portfolio`
+- `Commitment`
+- `FlexibilityEnvelope`
+- `ForecastBundle`
+- `MarketOpportunity`
+- `DecisionCase`
+- `CandidatePlan`
+- `ConstraintSet`
+- `ValidationResult`
+- `SimulationResult`
+- `Approval`
+- `ExecutionPermit`
+- `DispatchOrder`
+- `ExecutionReceipt`
+- `Settlement`
+- `PolicyPack`
+
+Every material plan should contain:
+
+- Its validity window.
+- The input-data snapshot or evidence references.
+- Market-rule and policy versions.
+- Model and solver versions.
+- Objectives and constraints.
+- Uncertainty and confidence information.
+- Expected physical and financial effects.
+- An immutable digest.
+- Current validation and approval state.
+
+## 13. Data, Knowledge, Rules, and Memory
+
+These four concepts should remain distinct.
+
+### Operational data
+
+Telemetry, market facts, commitments, user responses, and execution observations
+are authoritative domain data. They require quality indicators, timestamps,
+lineage, retention, and access controls.
+
+### Knowledge
+
+Regulations, procedures, manuals, historical reports, and operating experience
+can be indexed for retrieval and explanation. Retrieved content is evidence for
+a user or model, not automatically an executable rule.
+
+### Rules
+
+Market rules, approval rules, equipment constraints, financial limits, and
+security policies should be versioned, executable, testable, and auditable.
+
+### Memory
+
+Agent memory should contain convenience context and curated lessons, not
+authoritative operational state. Feedback should enter a controlled evaluation
+and promotion process before it changes a model, policy, or operating template.
+
+## 14. Reliability and Security Considerations
+
+The detailed design should account for:
+
+- Idempotent handling of repeated events, approvals, submissions, and commands.
+- Optimistic concurrency to reject stale approvals and conflicting actions.
+- Late, missing, duplicated, or low-quality telemetry.
+- Model and solver timeouts with deterministic fallbacks.
+- Network partition between provincial and site systems.
+- Partial device acceptance and compensating dispatch.
+- Permit expiry and revocation.
+- Segregation of operator, approver, and administrator duties.
+- Field-level authorization for customer, market, and infrastructure-sensitive
+  data.
+- Immutable audit records and tamper evidence.
+- Tenant, portfolio, site, and provincial data boundaries.
+- Observability for every decision and external effect.
+
+## 15. Recommended First Vertical Slice
+
+The first implementation should be one complete operational flow rather than
+five partially connected agents:
+
+> Day-ahead portfolio plan -> forecast -> flexibility assessment -> candidate
+> bids -> simulation -> operator approval -> simulated market submission ->
+> execution replay -> settlement review.
+
+The slice should initially run in shadow mode using historical and live data
+without producing real external effects. It should prove:
+
+- Canonical domain contracts.
+- Evidence and decision lineage.
+- Durable orchestration and case state.
+- Rule and model versioning.
+- Scenario comparison.
+- Approval bound to immutable artifacts.
+- External-effect simulation and receipts.
+- Replay and outcome attribution.
+- Operation without the LLM.
+
+Once this foundation works, the proposed analysis, resource, trading,
+customer-interaction, and load-management agents can be introduced as
+contributors to the same case lifecycle.
+
+## 16. Decisions Required Next
+
+The following decisions materially affect the detailed architecture:
+
+1. Is the new platform an AI overlay on the existing 3060 platform, a gradual
+   replacement, or a separate system of engagement?
+2. Which existing system remains the source of truth for resources, customers,
+   market positions, dispatch instructions, and settlement?
+3. Is the first release recommendation-only, capable of controlled market
+   submission, or capable of controlled dispatch?
+4. Which actions may eventually become automatically authorized within
+   predefined limits?
+5. Which functions and data must remain at the site, provincial, or dedicated
+   security zone?
+6. What protocols and latency guarantees currently exist between the provincial
+   platform, aggregation units, and edge terminals?
+7. Which province-specific rules must become executable policy packs in the
+   first release?
+8. What is the acceptable behavior when forecasts, telemetry, the LLM, an
+   optimizer, or a downstream system is unavailable?
+
+## 17. Suggested Next Architecture Work
+
+After the decisions above are answered, the next design artifacts should be:
+
+1. A system-context diagram showing existing systems and ownership boundaries.
+2. A source-of-truth matrix for all major domain entities.
+3. A canonical domain vocabulary and schema definitions.
+4. A detailed day-ahead decision-case sequence.
+5. A dispatch authority and execution threat model.
+6. A latency, availability, recovery, and data-retention requirements matrix.
+7. A deployment-zone and cross-province federation design.
+8. An incremental roadmap built from end-to-end vertical slices.

docs/00-overview.md

@@ -98,8 +98,11 @@ flowchart TB
 | `SituationReport` 态势报告 | 运行状态、异常、风险研判 | 智能分析 → 全体 |
 | `ResourceProfile` 资源画像 | 容量、约束、可调潜力、可靠性评分 | 资源调度 → 交易博弈 / 负荷控制 |
 | `PositionLedger` 持仓账本 | 各时间尺度的持仓与约束级联 | 交易博弈 ↔ Runtime（共享账本） |
-| `Proposal` 建议 | 一切拟执行动作的载体（申报、邀约、控制计划） | 各 Agent → 可信执行链 |
+| `Proposal` 建议 | 一切拟执行动作的载体（申报、邀约、控制计划），带不可变摘要 | 各 Agent → 可信执行链 |
-| `Envelope` 运行包络 | 人工预批准的自治边界 | 人工审批 → 可信执行链 |
+| `Envelope` 运行包络 | 人工预批准的自治边界（授权，向下） | 人工审批 → 可信执行链 |
+| `FlexibilityEnvelope` 灵活性包络 | 资源/聚合单元的可调能力（能力，向上；省间交换的核心工件） | 资源调度 → 交易博弈 / 省间联邦 |
+| `ExecutionPermit` 执行许可 | 现势复核后签发的短时效执行凭证，网关只认许可 | 授权环节 → 网关 |
+| `DecisionCase` 运营工单 | 运营人员的问责单元，聚合一件事的证据/建议/审批/结果 | 触发源 → 运营工单台 |
 | `ExecutionReport` 执行报告 | 指令执行结果与偏差 | 控制平面 → 偏差复盘 |
 | `ReviewFinding` 复盘结论 | 结构化经验教训，回写记忆与策略库 | 复盘流程 → Runtime 记忆 |
 
@@ -114,4 +117,6 @@ flowchart TB
 | 05-skills-and-data | 专业模型工具契约、数据分层存储 | 2.3 建设内容 02/03 |
 | 06-integration | 外部系统接口边界 | 2.1 业务系统 |
 | 07-scenario-walkthrough | 日前现货申报端到端场景 | 全部（验证用） |
-| 08-implementation | Mastra 映射、LLM 抽象层、部署形态 | 2.5 基础条件 |
+| 08-implementation | Mastra 映射、LLM 抽象层、部署形态、影子运行 | 2.5 基础条件 |
+| 09-runtime-implementation | Runtime 实现设计（Mastra 落地细节） | 2.3 建设内容 05 |
+| 10-federation | 省间协同联邦边界 | 3.3 二期推广 |

docs/01-principles.md

@@ -70,6 +70,25 @@
 
 ---
 
+## 硬性不变式（Invariants）
+
+原则是设计导向，以下不变式是**可测试的硬约束**——违反任何一条即为缺陷，
+每条都应有对应的自动化测试或审计检查：
+
+| # | 不变式 | 落点 |
+|---|---|---|
+| I1 | AI 不得批准自己的建议；审批人身份与发起链路强制分离 | 03 篇状态机权限校验 |
+| I2 | 操作、审批、管理三类职责在权限体系中分离（separation of duties） | 06 篇权限对接 |
+| I3 | 审批绑定 Proposal 的不可变摘要（digest）与有效窗口；实质证据、约束或预期效果变化后审批自动失效 | 03 篇审批绑定 |
+| I4 | 任何外部效果（申报/控制）只凭执行许可（ExecutionPermit）受理，许可有时效、可吊销 | 03 篇授权环节、04 篇网关 |
+| I5 | 外部效果幂等（重发不重执行）并产生持久回执 | 04/06 篇适配器与执行引擎 |
+| I6 | LLM 不可用时系统降级可运行：预测、优化、校核、审批、申报、控制全链路不依赖 LLM 存活 | P1/P2 的运行时验证 |
+| I7 | 任何历史决策可从留存证据完整重放（输入快照 + 规则版本 + 模型/求解器版本 + 审批记录） | P5、05 篇快照机制 |
+| I8 | 运营事实的权威存储是领域数据库，不是智能体记忆 | 02 篇记忆体系 |
+
+> 注：本节不变式与另一份独立评审（brainstorming.md）的结论互相印证——
+> 两份独立设计收敛于同一组约束，是架构方向正确性的有力佐证。
+
 ## 原则间的张力与取舍备忘
 
 | 张力 | 取舍 |

docs/02-cognitive-plane.md

@@ -105,8 +105,33 @@ D+1 结算数据到达
 复盘本质是分析任务，其结论的权威数据源是持仓账本与事件日志（P5/P7），
 单独设 Agent 会造成与分析 Agent 的职责重叠。
 
-## 5. 人机交互面
+## 5. 人机交互面：运营工单台（Case Desk）
 
-- 自由文本只存在于「人 ↔ 平台」界面：智能问答、专题分析、报告生成（AI 交互与分析引擎）
+运营人员的工作单元不是「某个 Agent 的输出」，而是**运营工单（DecisionCase）**——
-- 业务页面嵌入 AI 结论卡片，卡片与页面双向联动（点卡片定位数据，选数据追问 AI）
+一件有明确目标、责任人、期限和完结条件的业务事项：
-- 每张 AI 卡片必须可展开血缘：结论 → 引用的工具输出 → 数据来源（P5 在 UI 层的体现）
+
+```yaml
+DecisionCase:
+  kind: DAY_AHEAD_BID | DR_EVENT | DEVIATION_RESOLUTION | REVIEW | ...
+  objective: "完成 D 日现货申报"      # 一单一目标，禁止杂物箱化
+  owner: string                      # 责任人（问责单元）
+  deadline: ts                       # 期限（如申报截止）
+  contents:                          # 工单聚合的全部工作产物（引用，非复制）
+    evidence: [...]                  # 态势报告、预测、画像快照
+    proposals: [...]                 # 关联 Proposal 及其状态
+    approvals / permits: [...]
+    scenarios: [...]                 # 情景分支（高价情景、低光伏情景的对比测算）
+    outcome: ...                     # 执行回执与复盘结论（完结条件）
+```
+
+- 工单由三类触发源随流程模板**自动开单**（周期申报单、事件偏差单），人工也可开专题单；
+- 审批收件箱、看板、报告都是工单与账本/事件日志之上的**投影**，不是独立功能烟囱；
+- 运营人员可在工单内叉分情景（「如果明日出现高价时段？」）——由 Agent 重跑测算工具
+  生成对比分支，但不产生新 Proposal，纯分析用途；
+- 自由文本只存在于「人 ↔ 平台」界面：智能问答、专题分析、报告生成，均挂在工单上下文内；
+- 业务页面嵌入 AI 结论卡片，卡片与页面双向联动；每张卡片可展开血缘：
+  结论 → 引用的工具输出 → 数据来源（P5 在 UI 层的体现）。
+
+**工单 vs 工作流**：工作流（Runtime 内部）是机器的执行单元，工单是人的问责单元；
+一张工单通常聚合多条工作流的产物（申报单 = 态势流程 + 画像流程 + 申报流程 + 生命周期流程）。
+两者通过 case_id 关联，禁止互相替代。

docs/03-safety-chain.md

@@ -23,6 +23,7 @@ Proposal:
     data_refs: [string]         # 引用的数据快照
     ledger_version: string      # 读取的持仓账本版本
   envelope_ref: string | null   # 命中的包络（null = 必走人工）
+  digest: string                # 载荷 + 血缘的不可变内容摘要（审批与许可的绑定对象）
   status: <状态机，见 §2>
   audit: [...]                  # 状态迁移全记录：时间、执行者(系统/人)、依据
 ```
@@ -43,8 +44,12 @@ stateDiagram-v2
     ENVELOPE_CHECK --> PENDING_HUMAN: 包络外 / 无包络
     PENDING_HUMAN --> APPROVED: 人工批准（可多级）
     PENDING_HUMAN --> REJECTED: 人工驳回
-    AUTO_APPROVED --> RELEASED: 下发
+    AUTO_APPROVED --> FRESH_CHECK: 执行前现势复核
-    APPROVED --> RELEASED: 下发
+    APPROVED --> FRESH_CHECK: 执行前现势复核
+    FRESH_CHECK --> AUTHORIZED: 复核通过，签发 ExecutionPermit
+    FRESH_CHECK --> STALE: 实质状态已变化，审批失效
+    STALE --> RULE_CHECK: 重新走链（视变化幅度沿用或重批）
+    AUTHORIZED --> RELEASED: 网关凭许可受理
     RELEASED --> EXECUTING: 控制平面 / 外部接口受理
     EXECUTING --> COMPLETED: 执行完成，反馈回传
     EXECUTING --> ROLLED_BACK: 异常触发回退
@@ -57,8 +62,49 @@ stateDiagram-v2
 
 - **规则校核**（确定性规则引擎）：合规性（交易规则、申报格式）、约束校验（资源约束、合同边界、账本一致性）、权限校验（发起 Agent 是否有权发起该类型）、血缘完整性；
 - **仿真验证**：按类型选择——申报类走收益/风险情景回测，控制类走功率平衡/潮流仿真；仿真告警**一票升级**人工，没有例外；
+- **权限校验**（规则校核内含，落实 I1/I2）：审批人不得出现在该 Proposal 的发起链路中；AI 无任何通往「批准」迁移的路径；
 - **实现形态**：持久化工作流（durable workflow）。审批可能悬挂数小时，状态机必须可恢复、超时可配（如申报截止前 30 分钟未批自动升级告警）。
 
+### 2.1 审批绑定与失效（Staleness，落实 I3）
+
+审批的对象不是「这个 Proposal」，而是「**这个摘要版本**的 Proposal 在**这个窗口内**生效」：
+
+```yaml
+Approval:
+  proposal_digest: string       # 绑定不可变摘要——载荷任何改动即另一次审批
+  approver: {id, role}          # 来自既有权限系统（I2 职责分离）
+  scope: {effect_type, limits}  # 批准的效果范围与金额/电量上限
+  validity: {from, to}          # 有效窗口
+  evidence_versions:            # 审批时所依据的证据版本
+    policy_pack: string
+    ledger_version: string
+    data_snapshot_refs: [...]
+```
+
+**失效条件**：有效窗口过期；或依据的实质证据发生变化（引用资源离线、账本持仓变动、
+政策包升版、遥测显著偏离审批时快照）。失效检测由执行前**现势复核（FRESH_CHECK）**承担。
+
+### 2.2 授权与执行许可（AUTHORIZED / ExecutionPermit，落实 I4）
+
+人工/自动批准 ≠ 可以执行。批准与执行之间可能相隔数小时，物理世界会变。
+下发前由授权环节做**现势复核**：重跑关键校验（资源在线、约束仍满足、审批未失效），
+通过后签发执行许可：
+
+```yaml
+ExecutionPermit:
+  proposal_digest: string       # 与批准的摘要一致
+  issued_at / expires_at: ts    # 短时效（如控制类分钟级、申报类至截止时刻）
+  effect_limits: {...}          # 从 Approval.scope 继承收窄
+  revocable: true               # 可吊销（吊销 = 网关拒收 + 边缘回退策略）
+```
+
+**网关只认许可，不认计划**：交易平台适配器与执行引擎的受理入口只接受
+`(Proposal, ExecutionPermit)` 且验证摘要一致、许可未过期未吊销。
+即使一个已批准的计划被泄露或重放，没有有效许可也无法产生外部效果。
+
+*典型场景*：08:30 申报获批 → 09:00 某 10 MW 储能站离线 → 09:30 适配器请求许可
+→ 现势复核发现核定容量已失效 → STALE，回到规则校核重走（容量核减后的新摘要需重批或落在包络内自动通过）。
+
 ## 3. 包络（Envelope）模型
 
 ```yaml
@@ -93,6 +139,8 @@ Envelope:
 
 ## 4. 异常回退
 
+- **许可吊销**是最高优先级的回退手段：吊销后网关立即拒收后续指令，
+  边缘终端按断连策略退回上一批准计划或安全曲线（04 篇 §3）；
 - 执行中任何环节异常（校核失败、执行偏差超阈、通道故障）→ 回退至 Runtime 安全控制：
   控制类回退到上一批准计划或安全停机曲线（边缘终端本地持有，见 04 篇）；
   申报类在截止前可撤单重报，截止后转入偏差管理流程。

docs/04-control-plane.md

@@ -19,7 +19,8 @@
 | 设备 | 设定值执行 | 秒级 | 设备保护自主 |
 
 **分解原则**：省级只下发到聚合单元粒度的**目标 + 包络**，单元内的设备级分配由聚合层
-本地完成。省级不做设备级微观管理——既降低通信与时延要求，也符合「分区隔离」安全要求。
+本地完成；聚合单元向上以 `FlexibilityEnvelope`（灵活性包络）上报可调能力——
+该工件与省间联邦交换用同一 schema（10 篇）。省级不做设备级微观管理——既降低通信与时延要求，也符合「分区隔离」安全要求。
 
 ## 2. 执行引擎（省级）
 

docs/05-skills-and-data.md

@@ -70,11 +70,32 @@ flowchart LR
 - **快照与引用**：Proposal 血缘引用的数据是不可变快照（按版本/时间戳），保证任何历史决策可复现；
 - **脱敏分级**：用户行为数据按敏感级分级，跨区流动（如上送省级）经脱敏策略。
 
-## 4. 知识库运营（容易被低估的持续成本）
+## 4. 政策包（Policy Pack）与知识库运营
 
-规则库不是一次性建设：交易规则年年修订、政策频繁更新。设计上：
+**知识（可检索）与规则（可执行）严格分开**：RAG 用于解释规则、定位出处、支撑问答；
+任何有后果的校核（市场规则、安全限值、设备约束、财务上限）由**政策包**强制执行。
+
+### 4.1 政策包
+
+规则校核引擎的规则不是散落的代码，而是**版本化、可测试、可部署的政策包**：
+
+```yaml
+PolicyPack:
+  id: hubei-spot-bidding
+  version: 2026.03            # 随规则修订升版，旧版本保留（历史决策重放需要，I7）
+  effective: {from, to}
+  rules: [...]                # 可执行规则（申报格式、价格限值、持仓偏差带…）
+  tests: [...]                # 每条规则附正/反用例，升版必须全绿
+  source_refs: [...]          # 指向知识库原文条目（可解释性：规则 → 出处）
+```
+
+- Proposal 血缘固化**政策包版本**（03 篇 `evidence_versions.policy_pack`）——
+  「当时按哪版规则校核的」永远可查、可重放；
+- 政策包升版触发影响分析工作流：扫描悬挂中/包络内的存量 Proposal，标记需重校核者。
+
+### 4.2 知识库运营（容易被低估的持续成本）
 
 - 知识条目带**生效期与版本**，RAG 检索默认过滤失效条目；
-- 规则校核引擎中的硬规则与知识库中的文本规则**双轨维护**，
+- 知识条目（文本规则）变更触发对应政策包同步评审的工作流
-  文本规则变更触发硬规则同步评审的工作流（避免「文档更新了、校核引擎还是旧规则」）；
+  （避免「文档更新了、校核引擎还是旧规则」的双轨漂移）；
-- 每次申报被交易平台驳回的原因，强制回流为知识条目候选（复盘流程的一部分）。
+- 每次申报被交易平台驳回的原因，强制回流为知识条目候选 + 政策包规则候选（复盘流程的一部分）。

docs/07-scenario-walkthrough.md

@@ -38,8 +38,10 @@ D 日执行与监测，D+1 复盘。
 1. **规则校核**：申报格式 ✓、价格限值 ✓、账本一致性 ✓、血缘完整性 ✓；
 2. **仿真验证**：收益情景回测——千组价格情景，极端亏损在容忍带内 ✓；
 3. **包络检查**：本日申报曲线落在已批准的申报包络内（价格偏离预测基准 < 容差、电量在持仓偏差带内）→ `AUTO_APPROVED`；
-   - *对照分支*：若明日有极端天气、优化结果越出包络 → `PENDING_HUMAN`，交易员在审批界面看到申报说明 + 血缘展开 + 仿真结果，批准/修改/驳回；
+   - *对照分支*：若明日有极端天气、优化结果越出包络 → `PENDING_HUMAN`，交易员在工单台看到申报说明 + 血缘展开 + 仿真结果，批准/修改/驳回；
-4. `RELEASED` → 交易平台适配器提交申报；回执写入事件日志。
+4. 提交前**现势复核**：重验资源在线与账本一致 → 签发 `ExecutionPermit` → `AUTHORIZED`；
+   - *对照分支*：若批准后某储能站离线 → `STALE`，容量核减后重走校核（03 篇 §2.2）；
+5. `RELEASED` → 交易平台适配器凭许可提交申报；回执写入事件日志。
 
 *验证构件：状态机全路径、包络自治、降级路径（若接口故障 → 导出文件人工上传）。*
 

docs/08-implementation.md

@@ -24,7 +24,8 @@
 | 意图解析 | 路由 Agent → 选择 Workflow 模板并填参 |
 
 **需自建、框架不提供的部分**（工作量估算时别漏）：
-规则校核引擎、包络模型与检查器、持仓账本服务、审批工作台（多级审批 UI）、
+政策包引擎（规则校核）、包络模型与检查器、现势复核与执行许可服务（ExecutionPermit）、
+持仓账本服务、运营工单台（Case Desk，含多级审批收件箱）、
 交易平台/调度/计量适配器、执行引擎与边缘协议、审计血缘组装。
 ——这些恰恰是本平台的差异化资产；智能体框架只解决约 1/3 的问题。
 
@@ -76,10 +77,14 @@ Agent 代码 → 能力接口（complete / plan / extract / explain, 统一消
 
 1. **M1**：数据接入管道 + 时序/关系库 + 持仓账本服务（数据先行）；
 2. **M2**：Skill 服务群 v1（负荷/光伏/电价预测 + 报价优化 MILP）+ 评测基线；
-3. **M3**:Runtime + 智能分析/交易博弈两个 Agent + 规则校核 + 审批工作台
+3. **M3**：Runtime + 智能分析/交易博弈两个 Agent + 政策包引擎 + 运营工单台
    （此时即可跑通 07 篇 06:00→08:30 的申报链路，申报走文件导出人工上传）；
-4. **M4**：资源调度 Agent + 包络模型 + 复盘流程 + AI 卡片嵌入既有页面；
+4. **M4**：资源调度 Agent + 包络模型 + 现势复核/执行许可 + 复盘流程 + AI 卡片嵌入既有页面；
-5. 交互服务/负荷控制 Agent 与边缘控制链路放二期（依赖现场资源接入与外部联调）。
+5. **M5 影子运行（一期验收形态）**：全链路接实时数据，外部效果全部仿真
+   （申报只生成不提交、指令只投递仿真网关），逐日对比影子决策与人工实际决策——
+   既是最有说服力的验收演示，也是包络初值设定的数据依据；
+6. 交互服务/负荷控制 Agent 与边缘控制链路放二期（依赖现场资源接入与外部联调）；
+   二期上线路径：影子运行 → 受控实报（人工逐笔批）→ 包络自治逐步放宽。
 
 **排序理由**：M1–M3 不依赖任何外部单位排期，最快形成端到端演示与真实历史回测能力；
 回测结果（用历史行情验证报价优化收益）是二期扩大授权（包络放宽）与评审汇报的最强证据。

docs/10-federation.md

@@ -0,0 +1,79 @@
+# 10 · 省间协同联邦边界
+
+> 对应 proposal 二期目标「省间余缺互补、华中推广、跨省复制」与省间协同业务组的工作范畴。
+> 核心结论：**省间协同是联邦（federation），不是集中（centralization）**。
+
+## 1. 边界原则
+
+跨省协同**不意味着**一个中心平台可以访问另一省的原始遥测或终端控制权。
+每个省级平台是独立的信任域与责任域；省间交换的是**签名的、版本化的业务工件**，
+而非数据管道或控制通道。
+
+**默认不出省的**：
+
+- 原始设备遥测与用户级用电数据（隐私 + 商业敏感 + 数据出域合规）；
+- 终端控制权（任何一省的许可/网关体系不受他省指令）；
+- 用户档案、合同细节、内部收益分摊。
+
+**可跨省交换的（签名工件）**：
+
+| 工件 | 内容 | 方向 |
+|---|---|---|
+| `FlexibilityEnvelope` | 分时段可调能力（容量、爬坡、持续时间、价格意向），不含构成明细 | 双向发布 |
+| `Commitment` | 对某时段某容量的承诺及约束 | 协商达成 |
+| 报价 / 中标 | 省间市场交易工件（经国分调交易体系） | 按市场规则 |
+| 交付与结算事实 | 计量口径的交付确认、结算单 | 事后 |
+
+*类比：* 省内「聚合单元向省级平台上报灵活性包络、接受调度包络」的模式（04 篇），
+在省间以对等联邦形式复用——**同一套工件语义，不同的信任关系**（上下级 → 对等）。
+
+## 2. 联邦交互模型
+
+```mermaid
+flowchart LR
+    subgraph HB["湖北省级平台（本项目）"]
+        HBk[运营内核 + 可信执行链]
+        HBf[联邦网关]
+    end
+    subgraph OTHER["他省平台 / 华中区域协调"]
+        OTf[联邦网关]
+        OTk[对方运营内核]
+    end
+    HBk --> HBf
+    HBf <-->|签名工件：灵活性包络 · 承诺 · 报价/中标 · 结算事实| OTf
+    OTf --> OTk
+```
+
+- **联邦网关**是唯一的省间通道：工件签名/验签、版本协商、幂等去重、留痕；
+- 收到的他省工件进入本省平台时按「外部证据」处理——进事件日志、可触发本省流程，
+  但**不直接进入**本省可信执行链（他省的承诺请求也要走本省完整的校核-审批-许可链）；
+- 跨省承诺在双方各自的账本上记账（各记各的 `PositionLedger`），结算事实到达后对账。
+
+## 3. 跨省场景示例：省间余缺互补
+
+1. 湖北平台按周期发布次日 `FlexibilityEnvelope`（富余可调能力，已脱敏聚合）；
+2. 他省（缺口方）发起承诺请求 → 湖北联邦网关验签、入事件日志；
+3. 事件触发湖北侧交易博弈 Agent：测算履约能力与收益 → 生成省间承诺 `Proposal`；
+4. 走湖北本省可信执行链（规则校核用省间政策包、现势复核、审批/包络、许可）；
+5. 承诺工件签名回传；执行期由湖北自己的控制平面在省内组织履约；
+6. 交付事实与结算单交换，双方复盘。
+
+**要点**：他省全程只看到工件（包络 → 承诺 → 交付事实），
+看不到湖北用哪些资源、哪个用户履约——「跨区域资源匹配准确率 ≥ 85%」的指标
+在工件层面衡量，不需要跨省数据穿透。
+
+## 4. 信任与安全
+
+- 工件签名：省级平台各持机构密钥，工件带摘要与时间戳，防篡改可追责；
+- 版本化：工件 schema 版本协商（联邦各方升级不同步是常态）；
+- 政策包分层：省内政策包 + 省间政策包（国分调规则、区域协议）分开维护与升版；
+- 最小披露：灵活性包络的聚合粒度是合规参数（可配到不低于聚合单元级）。
+
+## 5. 对一期的要求（避免二期返工）
+
+一期不建联邦，但要**预留三个不返工点**：
+
+1. `FlexibilityEnvelope` 作为一等业务对象进入 domain 包（省内聚合单元上报即用它，
+   省间复用同一 schema）；
+2. 账本支持「对外承诺」条目类型（区别于市场持仓）；
+3. 政策包引擎支持多包并存与按场景选包（省内包 / 省间包）。