Vinculum architecture

状态：Proposed architecture。 本文是 Vinculum 的 canonical system definition。Pysolate 已实现的基础与尚未实现的 Vinculum 构件见 pysolate-mapping.md。

1. 系统命题

Agent 生成程序不是普通 serverless function。代码由概率模型临时生成，可能在一次执行中完成循环、分支、聚合和多次工具调用；真实权限、凭据、审批与外部状态却不能交给该程序自行决定。

Vinculum 因此把一次执行定义为一个绑定单元：

text

program identity
+ frozen capability surface
+ Host authority and budget
+ runtime lifecycle
+ effect semantics
+ outcome oracle
+ evidence and replay contract
────────────────────────────────
Vinculum execution

它解决的是一个联合问题：Harness 如何将工具编排下放为程序，Runtime 又如何低成本执行该程序而不削弱 authority、effect 和 evidence boundary。

text

Agent intent and tool workflow
              │
              ▼
Harness-generated bounded program
              │
              │ Agent Execution Contract
              ▼
Host admission and authority binding
              │
              ▼
Pysolate bounded execution
              │
              ├── typed Host capabilities
              ├── journaled effects
              └── lifecycle evidence
              │
              ▼
Result + receipts + outcome/evidence status

这不是“让 Agent 在 Python 中直接持有 MCP client”。Authority-Preserving Tool-Call Lowering 只移动控制流；credential、grant、budget、approval、commit policy、effect adapter 和 receipt authority 仍由 Host 持有。

2. Harness–Runtime 的共同窄腰

Vinculum 采用 semantic co-design, implementation decoupling。

Harness 不应知道：

wazero memory layout；
COW page、memfd 或 snapshot shell 实现；
prepared-pool refill 与 scheduler internals；
Runtime evidence 的存储布局。

Runtime 不应知道：

prompt、模型供应商或 sampling policy；
conversation/memory storage；
Agent reasoning 与任务规划；
approval UI 或 counterfactual branch strategy。

双方通过 canonical Agent Execution Contract 对齐语义。该 contract 必须足以阻止两个实现各自对 identity、authority、effect completion 或 replay 作不同解释。

2.1 Execution request

字段组	最小内容	所属责任
Agent coordinates	run/turn/output/segment、logical invocation、attempt	Harness 产生；Host 绑定
Program	source/artifact reference、effective-code identity expectation	Harness 请求；Runtime 回报实际值
Runtime requirement	artifact/base/profile、strategy qualification	Host 选择 qualified strategy
Capability surface	frozen catalog、schema projection、grant、handler/effect policy	Host 构建并冻结
Resource envelope	memory、CPU、timeout、request/response limits、call budget	Host-owned；Guest 不可扩大
Effect contract	operation identity、commit policy、effect class、approval reference	Effect plane 解释与执行
Replay/evidence mode	required events、capture policy、replay level、privacy boundary	Harness 请求；Host 校验
Outcome contract	checkpoint refs、task/final-state/safety oracle refs	Harness 定义；Verifier 执行

2.2 Execution result

字段组	最小内容
Bounded result	result、error、timeout/cancel/trap classification
Effective identity	artifact/base/profile、effective code、execution reference
Runtime outcome	metrics、active strategy、retirement/reclaim result
Capability outcome	calls、budget use、catalog/handler binding、receipts
Effect outcome	intent、attempt、provider identity、readback/reconciliation、ambiguity
Outcome verification	oracle result、state projection、unresolved conditions
Evidence status	required/present/dropped evidence、integrity status、bundle refs
Replay status	highest qualified level、prerequisites、prohibited effect mode

completed 不应只表示 Guest 函数返回；它必须与 contract 要求的 Runtime、effect 和 evidence terminal state 相容。

3. 分层架构

text

┌──────────────────────────────────────────────────────────────┐
│ Agent / Harness                                              │
│ task semantics, generated program, tool workflow, oracles    │
└───────────────────────────┬──────────────────────────────────┘
                            │ Agent Execution Contract
┌───────────────────────────▼──────────────────────────────────┐
│ Vinculum Control Plane                                      │
│ admission, identity, frozen capability surface, budget,     │
│ approval, strategy and qualification selection              │
└──────────────┬──────────────────────────────┬────────────────┘
               │                              │
┌──────────────▼───────────────┐  ┌──────────▼────────────────┐
│ Pysolate Execution Plane    │  │ Effect Plane              │
│ artifact/base, CPython/WASI,│  │ typed registry, intent,   │
│ Disposable COW, execute,    │  │ commit, reconciliation,   │
│ cancel, retire and reclaim  │  │ rollback/compensation     │
└──────────────┬───────────────┘  └──────────┬────────────────┘
               │                              │
┌──────────────▼──────────────────────────────▼────────────────┐
│ Evidence Plane                                               │
│ lineage, atomic journal snapshot, receipts, state/oracle refs│
└───────────────────────────┬──────────────────────────────────┘
                            │
┌───────────────────────────▼──────────────────────────────────┐
│ Verification / Replay Plane                                  │
│ claim verifier, structural playback, stubs/twins and oracles │
└──────────────────────────────────────────────────────────────┘

Control、Effect 和 Evidence planes 属于 Vinculum 的 Host-side semantics；它们不必与 Pysolate 位于同一进程，但必须共享 contract identity 和 fail-closed rules。

4. 关键机制如何闭合

4.1 Programmatic tool execution

text

MCP/tool discovery
  → canonical schema
  → Bounded Schema Projection
  → Host grant/effect/policy overlay
  → Frozen Capability Surface
  → generated Python SDK

Harness 可以生成在 Python 内完成循环、过滤、分支和聚合的程序；Runtime 只暴露 catalog 中已授权的 typed capability。Direct Agent call 与 Python call 最终汇入 One Effect Plane：

text

Direct call ─┐
             ├→ registry → grant/budget → transaction → adapter → receipt
Python call ─┘

入口可以影响 orchestration cost，不能改变 authority 或 effect semantics。

4.2 High-density single-use execution

text

Producer Determinism Gate
  → State-Census Gate
  → Typed Warm Image
  → Warm State, Cold Authority
  → Prepared Attach Oracle
  → Sealed Sparse Baseline / Snapshot Shell
  → ready inventory
  → checkout once
  → execute
  → retire and replenish

Disposable COW 共享 canonical prepared pages，但 served slot 用后即弃。它以廉价 replacement 避免依赖尚未证明的完整 CPython/WASI reset；COW sharing 不等于 served-instance reuse。

Density 必须分别报告 ready capacity、active concurrency、burst saturation、dirty/private-page rate、refill、retirement 和 workload success。取消请求也不等于内存已释放；reclaim 需要 executor termination 和 mapping/memory observation。

4.3 Effects and ambiguity

一次 effect 至少区分：

text

logical operation
  └── dispatch/recovery attempt
        └── provider request/idempotency identity

Effect class 与 commit authority 正交。Generated program 可以 stage intent 或请求 transaction abort，但不能给自己授予 commit authority，也不能提供 arbitrary rollback code。

派发后结果未知时进入 Ambiguity Firewall：在 readback、webhook 或其他 reconciliation 完成前，禁止 blind retry、rollback、compensation 或依赖该结果继续产生 effect。完整语义见 effects-and-replay.md。

4.4 Evidence and qualified replay

Receipt 不是 success log。Manifest-Bound Receipt 应绑定本次 Run 的 authority、intent、operation/attempt、catalog/handler、effect manifest、provider request identity 和 bounded outcome。

Evidence 也不是固定“全量 trace”。Verifier 按 claim manifest 判断最小充分性：

Claim	最小证据候选
执行了什么	artifact digest + effective code digest + Host execution identity
从哪里开始	prepared-base/profile digest + state census + qualification
有什么权限	frozen grant/policy/catalog digest + budget counters
看到了什么	nondeterministic-input refs/digests + source/version/time
尝试了什么效果	intent + operation/attempt + adapter/provider identity + reconciliation
结果是否满足要求	result digest + independent final-state/safety oracle
是否可重放	replay level + captured dependencies + qualified replayer identity
证据是否完整	atomic snapshot/sequence + required event set + dropped/unknown counters

5. 责任边界

Harness

Harness 负责：

任务、对话和模型生命周期；
生成程序和工具 workflow；
维护 Agent coordinates 与 checkpoint bytes；
定义 task、final-state 和 safety oracles；
请求 replay/counterfactual branch。

Harness 不得制造 Runtime 已执行或 provider effect 已完成的权威证据。

Vinculum Host planes

Host-side Control、Effect 与 Evidence planes 负责：

生成 invocation/attempt/execution identity；
冻结 artifact、catalog、schema、grant、policy 和 budget；
绑定 approval 与 commit authority；
选择 qualified Runtime/effect strategy；
journal intent，管理 reconciliation、rollback/compensation；
生成 receipts，导出 atomic evidence snapshot；
在 drift 或 qualification 失效时降级或 quarantine。

Pysolate Runtime

Runtime 负责：

验证并加载精确 artifact/base/profile；
提供无 ambient authority 的 CPython/WASI 环境；
执行 resource limits 与 cancellation；
只通过 Host broker 访问 capability；
返回实际执行 identity、metrics 和 bounded result；
按 lifecycle contract retire/discard slot，并报告 reclaim evidence。

Runtime 不负责 prompt、模型、conversation、approval UI、业务补偿或完整 Agent replay。

Verifier

Verifier 负责：

按 claim manifest 检查 evidence sufficiency；
检查 sequence、digest、catalog/policy/artifact binding；
运行 independent final-state oracle；
评估 replay prerequisites；
输出 verified | contradicted | insufficient | stale。

6. 操作性性质

Vinculum 的性质必须能被反例推翻，而不是品牌形容词。

性质	操作性定义	典型反例
Trustworthy	特定 verifier 在给定 threat model 下能检查具体 claim	同一进程自述“成功”，无独立 identity/readback/oracle
Replayable	声明 replay level、captured dependencies、effect mode 和 divergence policy	把再次调用 live provider 称为 replay
Stable	在版本与负载包络内保持 contract；越界时检测、降级或 quarantine	schema drift 后 permissive parsing
High-density	在 workload success 与 isolation/lifecycle invariants 下的 ready/active capacity	用 RSS/slot 推导生产并发
Auditable	可追踪 intent、authority、execution、effects、outcome 与 evidence gaps	maximal logging 但没有 binding 或 verifier
Deterministic	分别限定 build、initial state、execution、observation、effect 和 outcome	byte-identical artifact 被当成外部效果确定性

其中：

text

Trust = (claim, evidence, threat model, verifier policy)

签名、hash chain 或 remote attestation 只能加强相应 identity/integrity claim，不能证明程序语义、Agent 决策或外部 final state 正确。

7. Lifecycle state machine

状态：Proposed end-to-end state machine。 Pysolate 当前分别实现 Runtime retirement 与 transaction/attempt 状态子集；尚未实现把 Harness、effects、evidence verification 贯通为下图单一生命周期。

text

admitted
  → prepared
  → running
  → effects_staged
  → committing
  → verifying
  → completed

running / effects_staged / committing
  → ambiguous
  → reconciling
  → completed | compensated | quarantined

any unsafe or uncertain Runtime state
  → retiring
  → retired

关键不变量：

completed 需要 contract 要求的 execution 与 evidence terminal state；
timeout/cancel 后不能仅凭 Guest 返回决定 slot 可复用；
ambiguous 阻止 blind retry 和自动 recovery；
effect class 与 commit authority 正交；
evidence 写入失败时是否 fail closed 必须由显式模式决定；
当前 Disposable COW served slots 进入 retirement，不回 ready pool。

8. Replay levels

“再跑一次”不是统一语义：

Level	名称	保证	明确不保证
R0	Structural playback	验证、浏览既有有序事件	不执行程序，不恢复状态
R1	Input-injection replay	注入已记录输入，重执行 deterministic core	不重复真实外部效果
R2	State-equivalent replay	达到定义的等价状态投影	不要求字节级轨迹一致
R3	Outcome-equivalent replay	满足相同 task/safety oracle	轨迹、文本和调用次数可不同
R4	Counterfactual replay	替换模型、工具、策略或输入并重算后继	需要 dependency graph 与 effect isolation

每个 Evidence Bundle 只能声明已满足 prerequisites 的最高等级。当前 Pysolate metadata trace 支持 R0 Structural playback，不支持据此声称 R1–R4。

9. 非目标与诚实边界

Vinculum 不自动提供：

arbitrary provider 上的 distributed ACID 或 exactly-once；
对未知 UI/API 的完整 effect footprint、rollback 或 exact replay；
LLM 语义、用户意图或道德正确性的数学证明；
防御同时控制 Runtime、Host store、signing key 和 verifier 的攻击者；
仅凭 COW、slot count 或 synthetic fixture 推导 production SLA；
在线模型自动扩大 tool exposure、credential scope 或 commit authority。

未知外部系统的默认上限仍是：

text

record → infer → document uncertainty

Environment Crystallization 可以把经过独立资格化的观察提升为 fixture、adapter、state model 或 oracle，但不能把推断直接提升为 authority 或 guarantee。

Vinculum architecture ​

1. 系统命题 ​

2. Harness–Runtime 的共同窄腰 ​

2.1 Execution request ​

2.2 Execution result ​

3. 分层架构 ​

4. 关键机制如何闭合 ​

4.1 Programmatic tool execution ​

4.2 High-density single-use execution ​

4.3 Effects and ambiguity ​

4.4 Evidence and qualified replay ​

5. 责任边界 ​

Harness ​

Vinculum Host planes ​

Pysolate Runtime ​

Verifier ​

6. 操作性性质 ​

7. Lifecycle state machine ​

8. Replay levels ​

9. 非目标与诚实边界 ​

Vinculum architecture

1. 系统命题

2. Harness–Runtime 的共同窄腰

2.1 Execution request

2.2 Execution result

3. 分层架构

4. 关键机制如何闭合

4.1 Programmatic tool execution

4.2 High-density single-use execution

4.3 Effects and ambiguity

4.4 Evidence and qualified replay

5. 责任边界

Harness

Vinculum Host planes

Pysolate Runtime

Verifier

6. 操作性性质

7. Lifecycle state machine

8. Replay levels

9. 非目标与诚实边界