运行 Provider-native Model/Tool Graph。

编译 Deployment Contract

从仓库内示例开始。它会构造真实的 Tool-capable Agent、严格 Read-only Policy、 显式 Unpriced Accounting、生成 State Schema、标准 Runtime Schema 与初始 Checkpoint State；不需要 API Key 或数据库，也不会执行任何外部 I/O。

cargo run -p stateknot-runtime --example provider_native_agent --locked

改造前请先阅读完整示例源代码。示例停在 Deployment Boundary；PostgreSQL Suite 会单独证明 Dispatch 与 Recovery。

同时固定代码、Policy 与 Accounting

Composition Digest 会绑定 Agent、Model、Tool、Instruction、Execution Limit、Input Security Label、Policy Implementation 与 Accounting Table。任何一项变化都必须发布 新 Graph Version。

let definition = ProviderNativeAgentGraph::compile(
    typed_definition.descriptor().clone(),
    graph_identity,
    reducer_identity,
    state_schema_id,
    input_security_label,
    policy,
    accounting,
)?;

definition.register_schema(&mut schemas)?;
register_standard_agent_cancellation_event_schema(&mut schemas)?;

Registry 冻结前必须注册全部 Typed Input/Output Schema、Tool Schema、Provider Profile 与标准 Runtime Event Schema。任何 Digest 缺失或冲突都会导致启动失败。存量 Run 始终加载其 Checkpoint 已固定的 Graph Version。

根据真实模型证据计价

ModelTokenAccounting 将部署方核实的费率快照和 Provider 报告的 Model ID 固定到精确的 Model Binding 与 Graph 版本。它依据持久化用量账本，对已提交或失败的模型 Attempt 计价；缺少用量或必需的缓存 Token 明细时返回 Unpriced，绝不会当作免费。Provider 价格会变化，StateKnot 不内置费率。真实 HTTP 与 PostgreSQL 验证覆盖 Adapter、Invocation Ledger、终态费用、精确 Submission Key 读取授权， 以及 PostgreSQL 16/17 上的重复提交幂等。测试费率和密钥只是夹具；由部署方 配置的独立可运行 Agent 示例仍在开发中。

跟随一次可恢复 Turn

1. 重建

   Model Node 从不可变 Invocation Ledger 重建 Provider-native Transcript Order 与 Cumulative Usage。

2. 先提交，再 Dispatch

   Logical Invocation 与 Physical Attempt Start 在 Provider/Tool I/O 前持久化。 幂等观察到的 Start 不授予 Dispatch 权限。

3. 授权每个 Action

   Canonical Tool Arguments、Proposal Order、Admission 与 Model Invocation 共同绑定 Action Digest；Tool Prepare 前必须固定 Policy Evidence。

4. 依据 Ledger 推进

   精确 Terminal Revision 成为 Node Result。Crash 后读取已提交证据，而不是重新 Dispatch 外部调用。

已知 Tool Failure 会保留为有序 Transcript Outcome。Write 的模糊结果保持 Unknown，绝不会作为普通 Business Call 重复执行。当 Descriptor 与 Exact Provider 都启用 Reconciliation 时，Runtime 会针对原 Attempt 执行一次有界 Probe；权威 Evidence 原子提交，Pending 则成为后续 Lease 下的持久化延迟 Retry。其他 Binding 继续阻塞，等待人工 Reconciliation。

从持久化证据修复 Structured Output

将有限的 max_output_repair_turns 配置在总 Model-turn Ceiling 之下。已提交但不符合 Schema 的 Response，或带精确 Usage、发生在 Response Phase 的 response.malformed Adapter Failure，会先绑定进 Node Result，再生成不同的 Repair Invocation 与 Attempt。Crash 后会加载该 Terminal Ledger Fact，绝不会重新 Dispatch 已损坏的 Attempt。

新 Request 保留原始 Input 与可信 Instruction，再附加保留的 Framework Instruction stateknot.output_repair。无效 Payload 与 Provider Error Text 不进入 Prompt 或 Transcript；已完成 Tool 的定义与结果会保留在历史上下文中， 同时选择 none、调用上限设为 0。启用 Tool 与 Repair 的 Model 必须显式支持该选择。 Repair 期间的 Tool Proposal 不会到达 Policy 或 Tool I/O。达到上限后以 runtime.agent.output_repair_exhausted 失败并保留精确计费 Turn；缺少 Usage 的损坏 Envelope 继续 Fail Closed。

并行 Read，让每个 Write 成为 Barrier

parallel_read_only 只把不可变 Descriptor Risk 为 ReadOnly 的连续 Tool 按配置上限分组。Policy、Arguments、Prepare 与 Physical Start 仍按 Provider Proposal 顺序串行；只有 Provider I/O 会重叠。Terminal Evidence 会先缓冲， 再按相同顺序提交，因此完成时序无法重排 Journal 或下一轮 Model Transcript。

每个 Write 必须等前面的 Read 全部落盘后单独执行，后面的 Read 也必须等待其 Terminal Fact。Cancellation 会 Abort Child Provider Task，不会将其 Detach；已提交 Start 仍由 Fenced Recovery 观察。并发值必须依据真实 Provider Quota 与 Connection Capacity 设置。

let execution = AgentExecutionConfig::new(
    AgentStructuredOutputStrategy::ModelNative,
    max_model_turns,
    ExecutionCount::new(1),
    max_tool_calls_per_turn,
    AgentToolConcurrency::parallel_read_only(ExecutionCount::new(8)),
)?;

分别持久化取消请求与取消确认

Request

已认证 Control Plane Append 不可变 Cancellation Intent。Driver 轮询持久化状态、 停止新 Dispatch、发出 Cooperative Cancellation，并执行有界 Grace Period。

Confirm

Agent Loop 把精确 Checkpoint、Journal Head、Revision、Failure ID 与 Lease 交给 Lifecycle；后者重建 Usage，并使用数据库时间原子确认 Cancellation。

Fail closed

Executing Model、Unknown Write 或缺失 Model Usage 会让 Run 保持 cancellation_requested。StateKnot 不会用零 Usage 替代不可用 Evidence。

可公开的 Confirmation Schema 位于稳定 Runtime Identity。AgentService v1 现在提供 Authorization-first Cancellation Ingress；当前 pre-alpha 的 HTTP/gRPC Transport 仍由嵌入服务负责。

运行 PostgreSQL 证据

按照 PostgreSQL 指南配置测试数据库后，强制运行 Integration Suite，不允许因基础设施缺失而跳过。

STATEKNOT_REQUIRE_POSTGRES_TESTS=1 \
cargo test -p stateknot-runtime --test postgres provider_native --locked

Focused Case 在两个受支持 PostgreSQL Major 上覆盖：多轮 Recovery 不重复 Model Dispatch、Stale-fence Policy Race、已知失败 Tool、一次 Business Call 的 Unknown → Pending → Committed Reconciliation、有界 Read-only Overlap 与有序 Write Barrier、跨新 Lease 的已提交/Adapter-failed Output Repair、精确 Repair Exhaustion、Repair-time Tool Rejection、精确 Usage Cancellation、 Pre-dispatch Cancellation，以及 Evidence-unavailable 的 Fail-closed 行为。

保持 Release Boundary 可见

• 已实现串行与有界 Parallel Read-only Tool；所有 Write 有意保持串行。显式可信 Executor Contract 下的 Journal-isolated Graph Sibling Ordering 也已实现。
• 已实现 Model-native Structured Output 与有界可恢复 Repair； Tool-call-emulated Final Output 会被拒绝。
• 已实现精确 Cancellation Confirmation 与 AgentService v1 嵌入式 Ingress； 尚未实现稳定 HTTP/gRPC Transport。
• 已实现 Provider-native Execution Core、严格 MCP Remote Tool 与 A2A Remote Agent Binding。独立 MCP/A2A Server Profile 已存在，但尚未组合进本 Graph； 更广 Protocol Extension、A2A Live-peer Reconciliation Qualification、通用 Artifact Lifecycle/Public Delivery、Failover 与生产 Release 仍未交付。

完整 Integration 与 Operations Contract 见仓库指南。