# MCPGit / LRIGIT 技术架构深读：契约依据与设计边界

Date: 2026-10-07. Scope: a frozen, bilingual logical-architecture appendix for LRIGIT self-study. This is not mutable business data, a Rust source audit, a production topology, or a benchmark. It does not replace the existing architecture player or its language-state implementation.

## 核心判断 / Architectural thesis

通用 Agent 提供研究、推理和编码；MCP 提供接入协议；MCPGit 提供受控接口、结构化状态和版本化操作；LRIGIT 将这些能力组织成持续洞察。架构的价值不在组件数量，而在事实、方法、程序、状态和发布记录能否准确关联，让下一轮在既有积累上继续。

The general Agent supplies research, reasoning and code. MCP supplies protocol access. MCPGit supplies controlled interfaces, structured state and versioned operations. LRIGIT organizes them into continuous research. Architectural value lies in connecting facts, methods, programs, state and publication records—not in counting components.

## C01–C06：本轮直接读取的官方服务合同

All observations below came from the official LRIGIT MCP endpoint, instance `lritpc`, during this iteration. These were discovery reads, not execution of the advertised business operations. The initial clean Works baseline was `77c98cd720c4e4d3686392efb57673392339a5c8`, with an ordinary fetched origin/main readback at the same revision. Parallel repository changes may follow.

| ID | Source | What it supports |
|---|---|---|
| C01 | `service_metadata`, `mcpgit.application.v7` | Instance identity; advertised table transaction v5, cross-table transaction v1, content access, managed repositories, hosted HTTP and binary transport capabilities. |
| C02 | `skill_list`, `mcpgit.skills-kernel.v9`, Skills `2.3.0` | Capability families, separate read/write/publish lanes and instance-dependent availability. The capability-search derivative was listed unconfigured; this does not mean every content/table search is absent. |
| C03 | `table.author / worktree_table_batch_transaction` | Target-scoped atomic multi-table writes, row/object fences, transaction identity, main versus isolated Topic behavior, bare Git Objects/Trees writes, and retained transaction receipts. |
| C04 | `binary / binary_put_file` | Immutable SHA-256-keyed Row Aggregate with `$primary` Object; metadata and bytes commit atomically on the TableGit authority. |
| C05 | `executable.source / executable_source_read` | Inline UTF-8 Rust/WAsmC with caller-bound TableGit access, exact source revision and an independent effect ceiling; no candidate, activation or HTTP route. The workflow explicitly warns that traps do not undo earlier committed transactions. |
| C06 | `repository.management / project_checkpoint` | Low-frequency checkpoint references to exact workspace/table/binary revisions; ordinary writes remain independent commits. A checkpoint is not a cross-repository transaction. |

## 1. 角色与控制面 / Roles and the control plane

平台可调用 Skill 合同与组织方法 Skill 不应混用。`skill_get` 返回可调用操作的参数、版本、访问通道与边界；`SKILL.md` 可指导研究方法和操作组合，但不是自动执行器或权限门禁。Person 选择提供身份与归属，不会自行提升权限。[C01, C02]

A callable platform Skill contract is distinct from an organizational method Skill. `skill_get` describes operation schemas, versions and access lanes. A `SKILL.md` can guide work, but is neither an automatic executor nor an authorization gate. Person selection is not a privilege upgrade. [C01, C02]

建议图示主链：外部 Agent → MCP/HTTP 接入 → 严格操作合同 → 调用者授权与效果上限 → revision/transaction fences。它是逻辑责任链，不能代替源码中的真实函数调用顺序。

The proposed diagram shows a logical responsibility chain, not an audited function-call sequence: external Agent → protocol entry → strict operation contract → caller authorization/effect ceiling → revision and transaction fences.

## 2. 资产与状态 / Assets and state

程序与页面沿普通 Git 工作区维护；TableGit 管理结构化表、行与行所属 Objects。bare TableGit 的事务直接写 Git Objects/Trees，不需要物理工作树或持久 index。代码 worktree 与 TableGit 逻辑 Topic 是不同隔离载体。[C03]

Code and pages use ordinary Git workspaces. TableGit manages structured tables, rows and owned Objects. Bare transactions write Git Objects/Trees without a filesystem worktree or persistent index. A code worktree and a logical TableGit Topic are distinct forms of isolation. [C03]

Binary 不是架构图里没有归属的孤岛：当前存储入口创建 SHA-256 标识的不可变 Row Aggregate，实际字节位于 `$primary` Object，元数据和字节在同一 TableGit authority 原子提交。二进制传输通道与数据归属也要区分。[C04]

Binary is not an unowned island: its storage entry creates an immutable SHA-256-keyed Row Aggregate whose `$primary` Object contains the bytes. Transport and ownership are different concerns. [C04]

SafeGit 是加密敏感材料的生命周期能力；它不能被画成普通研究事实数据库，也不能由接口存在推出端到端安全已验证。[C02]

## 3. 事务与发布边界 / Transactions and publication

- 工作区文件：修改、验证、snapshot、合入、远端同步是不同结果；命令失败后的 dirty 状态需单独核对。
- TableGit main：一次事务携带 expected_revision、transaction_id 和行/对象版本；多个表在同一选定目标内原子变更。main 成功写入已经是权威提交，不再调用 Topic publish。
- TableGit Topic：真实 Topic UUID 的写入产生隔离草稿，验证后再发布。
- project_checkpoint：引用多个组成部分的精确 revision，不使多个仓库、数据库和外部动作变成同一个原子事务。

Workspace changes, validation, commits, integration and remote sync are separate outcomes. A TableGit main transaction is already authoritative; an isolated Topic needs its own later publication. Multi-table atomicity is scoped to the selected TableGit target. A project checkpoint correlates exact component revisions without creating cross-repository atomicity. [C02, C03, C06]

冲突或不确定结果必须回到实际状态与回执。不能靠重复运行整个 Agent 流程来假设回滚或幂等。

## 4. 三条执行路径 / Three execution paths

| Path | Purpose | Important boundary |
|---|---|---|
| `repo.author / exec` | Controlled workspace commands for maintenance, validation and builds | Not an installed online service; inspect actual file state after failures. |
| `executable.source` | Inline Rust/WAsmC against the caller-bound TableGit Host | Exact source revision and explicit effect ceiling; Host owns compiler/ABI; no candidate/activation/route. |
| `executable.build` + `router.admin` | Candidate builds and installed route lifecycle | Build, activation, routing and user acceptance remain distinct responsibilities. |

尤其重要：运行中发生 trap，不撤销先前已成功提交的事务。先核对 transaction_id、revision 与回执，再决定恢复动作。[C05]

A trap does not undo earlier successfully committed transactions. Reconcile IDs, revisions and receipts before deciding how to recover. [C05]

## 5. 双循环与先进性 / Two loops and architectural value

外圈维护代码和方法：改动 → 检验 → 版本 → 受控发布。内圈使用获准能力：读取当前状态 → 执行查询/程序 → 提交事务 → 检查结果。稳定接口与精确版本连接两圈。即时源码执行减少了先安装成服务的要求，但不自动等于无监督自我改写或硬实时控制。[C02, C05, C06; architectural synthesis]

The engineering loop evolves code and methods. The operational loop uses admitted capabilities to inspect state, execute programs, commit transactions and inspect results. Stable interfaces and exact versions connect them. Inline execution removes a mandatory service-installation step, not the need for governance. It does not itself prove unsupervised self-modification or hard real-time behavior.

可检验的价值包括：不同 Agent 能否接续同一对象和证据；新增反证能否定位受影响结论；修改理由和旧发布是否可追溯；有效方法和验证器能否复用。代价是 schema、接口、冲突处理和历史治理的维护成本。不能用功能数量替代收益验证。

Testable value includes cross-Agent continuity, impact tracing from counterevidence, explainable changes, preserved releases and reusable methods/validators. The costs are schema/interface maintenance, conflict resolution and history governance. Feature counts are not evidence of workflow benefit.

## 6. 不应混淆的未来方向 / Unverified implementation directions

当前端点合同不能证明 Memory/Memory Next 已是实例的默认存储后端，也不能证明某种 Rust crate、并发模型、Wasm Engine 共享策略或延迟指标。Git remote replication 不是多节点共识的证据。行删除不是历史和物理字节回收；短寿命表需受控 retention/compaction/checkpoint/GC 维护。[C02, C03]

The advertised contracts do not establish a particular Memory backend, Rust crate layout, concurrency design, Wasm Engine-sharing strategy or latency. Git replication is not proof of multi-node consensus. Row deletion is not history/byte reclamation. [C02, C03]

下一阶段应补三类证据：固定源码 revision 的模块/调用路径；具体实例的后端、激活、路由与复制拓扑；区分冷/热、数据规模、并发与持久化策略的查询/提交/执行/恢复实测。性能目标与结果必须分开。

Next evidence: a pinned source/module map; instance-specific backend/activation/route/replication facts; and measured query, commit, execution and recovery behavior with dataset, concurrency, cold/warm and durability conditions retained.

## 本轮范围与交接 / Scope and handoff

The initial batched architecture/policy source-read and Git-diagnostic `repo.author.exec` request at `77c98cd...` was blocked before execution: `此工具调用被 OpenAI 的安全检查屏蔽。请仔细检查你发送的内容。` It was not replayed through another tool, split, or sent through another owner. This appendix uses independently returned service contracts instead of claiming that the denied source audit succeeded.

The previous self-topic language-consumer/validator refusal remains in force. No existing architecture player, language consumer, original research source or shared navigation is changed by this document. Independent static diagrams and a paired-language guide were prepared locally; their repository/online publication is a separate receipt, not established merely by this source note.

New-artifact validation: SVG XML and prohibited embedded-content checks; 200 text nodes across four language/layout variants measured with an installed CJK font; static CairoSVG review. Local Chromium file navigation returned `net::ERR_BLOCKED_BY_ADMINISTRATOR`, so no browser-layout PASS is claimed and that navigation was not rerouted. HTML uses the existing shared Shell and stylesheet, with paired bilingual prose and no new language runtime. No benchmark or existing player suite was rerun.

Guidance reviewed: current `insight-repo-onboarding` plus retained canonical Root/Works boundary and evidence rules. No new governance Skill, duplicate task or protected registry change is introduced. The reusable lesson is to distinguish callable contracts, storage ownership, effect ceilings, commit atomicity and publication receipts before calling a diagram a technical architecture.