Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -50,10 +50,9 @@ export function scopeWorkspaceDirectory(
/**
* Snapshots a same-source read may keep visible while it reconciles.
* A directory entry is the cheap authoritative signal for "this Goal's
* lifecycle did not move here".
* A partial retry or known action may
* skip unaffected peers. Touched Goals and entries that moved or left the
* directory lose their snapshot.
* lifecycle did not move here". A full refresh still re-reads retained Goals;
* a partial retry or known action may skip unaffected peers. Touched Goals and
* entries that moved or left the directory lose their snapshot.
*/
export function reusableGoalSnapshots(
previous: Pick<WorkspaceProgress, "directory" | "snapshots"> | null,
Expand Down
6 changes: 3 additions & 3 deletions docs/book/chapters/06-codex-app.md
Original file line number Diff line number Diff line change
Expand Up @@ -175,7 +175,7 @@ writeback 和 spend 历史。
**边界一:heartbeat 不创造 frontier。** 一个没有 Todo 的 Goal 不会因为被频繁唤醒而出现下一步。
App 能保证有人看,不能保证有东西可做;没有可运行候选时就该进入 wait 或 monitor,让 cadence 放慢。

不要在 automation prompt 里复制 quota 状态机,也不要让
**边界二:automation 不是第二控制面。** 不要在 automation prompt 里复制 quota 状态机,也不要让
它自己解析 Todo 是否 runnable。稳定 prompt 只负责协议,判断属于每次读到的 packet。

**边界三:切换 Host 要核对工作归属。** App 和 CLI 可以读同一 Goal;切换前应查清旧实例是否仍执行、claim/lease 由谁持有,以及当前 writer 的围栏模式。需要显式移交时走对应 lifecycle,不能仅凭新 Host 已启动就并发推进同一项工作。
Expand Down Expand Up @@ -231,13 +231,13 @@ Gate 而不重复同样的安静轮询;若 Host cadence 更新失败而留下

## 不变式

1. 判断真实性看 writeback 与 spend,不看触发次数。
1. **heartbeat 触发不等于工作发生。** 判断真实性看 writeback 与 spend,不看触发次数。
2. **每次唤醒都过一次 `quota should-run`。** 没有这层 Gate,automation 就变成绕过决策的旁路。
3. **`should_run=false` 是合法结果,但它只关闭这一个 Turn。** 已结算回放保留当前 cadence,用新的
Turn identity 重新评估;`false` 的次数或本 Turn 的 receipt 都不能当作放慢 cadence 的依据。需要
放慢时,由当前 `scheduler_hint` 提出(`apply_needed=true`),再走第 4 条的四步。
4. **cadence 变化的四步缺一不可**:proposal、host apply、host readback、ACK。
5. 只有 Host readback 与目标一致才闭合,不一致时按
5. **本地 ACK ledger 不证明 Host 状态。** 只有 Host readback 与目标一致才闭合,不一致时按
`drift_detected` 修复。
6. **切换 Host 需要明确接管。** 同一 Goal 可被多处读取,写入仍须满足当前 authority、claim/lease 与围栏要求。

Expand Down
2 changes: 1 addition & 1 deletion docs/book/chapters/08-extension-placement.md
Original file line number Diff line number Diff line change
Expand Up @@ -367,7 +367,7 @@ multi-agent preset、Provider 或 presentation 的组合,继续阅读
resolver 和 domain policy,它就不该出现在 catalog 里。
2. **capability 与 extension 是两个维度,一次改动可以只落在其中一个上。** 看到新 package
就直接推断新 capability,是放置错误最常见的形式。
3. 判据是独立调用合同与生命周期,而非文件数量。
3. **共享代码并不构成升级成 capability 的理由。** 判据是独立调用合同与生命周期,而非文件数量。
4. **manifest 可发现并不等于合同可调用。** `[[provides]]` 与 `[[implements]]` 只有在真实入口、
resolver 和 validation 就位后才应写入。
5. **Extension 的独立生命周期是用户可见的成本。** 声明它之前先确认这份成本换来了 caller
Expand Down
4 changes: 2 additions & 2 deletions docs/book/chapters/core-state-machines.md
Original file line number Diff line number Diff line change
Expand Up @@ -750,7 +750,7 @@ owner、协议 schema、characterization fixture 和 migration boundary。
**失败三:投影被当成事实源。** dashboard 上改一个 row 让显示正确,source 没变。症状是
UI 与 CLI 长期不一致,而每次刷新都回到旧值。恢复方式是修 source 或 builder,再 readback。

Goal `stopped`、quota paused 或 peer coordination blocked
**失败四:停止的理由并不等于闭环。** Goal `stopped`、quota paused 或 peer coordination blocked
都可能停止轮询,它们各自是合法停止。只有 `terminal_no_followup` 表达
"因已验证 Goal closure 而停止"。把这几者混作一谈,会让一个被暂停的 Goal 看起来像已完成。

Expand All @@ -765,7 +765,7 @@ Goal `stopped`、quota paused 或 peer coordination blocked
处理拒绝结果。
5. **终局是合取。** 完整且闭合的 Todo source、没有未解决 frontier、结构化 `no_followup`
intent,三者同时成立才算闭环。
6. 改规则先确认 typed owner、协议 schema、characterization
6. **教学地图不等于实现规格。** 改规则先确认 typed owner、协议 schema、characterization
fixture 和 migration boundary。

这六条回答的是同一个问题:**当机制被拆到九组机器、又只能通过持久事实互相说话时,凭什么
Expand Down
2 changes: 1 addition & 1 deletion docs/book/chapters/source-protocol-map.md
Original file line number Diff line number Diff line change
Expand Up @@ -461,7 +461,7 @@ grep -rln "required_decision_scopes" loopx/control_plane/todos/ | head
1. **一条规则的所有者是决定合法转换的模块。** 如果无法指出被保护的不变量,这次改动还没有定位到位。
2. **PR 描述里必须有一条完整的因果链:source、invariant、decision、projection 或 effect、receipt、validation。** 只能列出函数名的切片无法被评审。
3. **文档描述责任归属,代码描述当前行为。** 两者冲突时,按冲突类型选择权威,并让这次 PR 把另一方更新掉。
4. 注册与真实 caller contract 才是发布判据,用 `loopx capability list --format json` 核对。
4. **`loopx/capabilities/<name>/` 下有代码,不证明该 Capability 已经发布。** 注册与真实 caller contract 才是发布判据,用 `loopx capability list --format json` 核对。
5. **placement 先于实现。** capability id、provider id 与 built-in/extension-delivered 的选择,必须在写第一行代码之前写下理由。
6. **任务来自公开入口。** 公开的 Contributor Task、Issue 和 fixture 是可参与工作的唯一来源,live active state 与 maintainer-local 判断都不算。

Expand Down
2 changes: 1 addition & 1 deletion docs/book/chapters/source-trace-protocol-chain.md
Original file line number Diff line number Diff line change
Expand Up @@ -485,7 +485,7 @@ grep -rn "or \[\]\|or ()\|or {}\|\.get(.*, \[\])\|\.get(.*, {})" loopx/control_p
追踪结束后,下面几条应该能独立成立:

1. **每个被改名或改语义的字段,都要能列出全部消费者。** 只改生产者不算完成,缺失字段的回退值算一次消费者。
2. 判断依据是第一处违反不变量的边界,而非最终返回值。
2. **链上每一层返回成功,不构成链路正确的证据。** 判断依据是第一处违反不变量的边界,而非最终返回值。
3. **缺失字段的默认值会参与判定。** 因此必须明确写出它是 reject、repair 还是 compatibility fallback。
4. **authority 只有一份 canonical 来源。** 多处可以读同一个字段,只有一处拥有它;读取方被误当成 owner 是跨层变更最常见的解释残留。
5. **判断 authority 时以协议文档为准,判断当前行为时以源码为准。** 两者冲突时按冲突类型选权威,并让同一次改动把另一方更新掉。
Expand Down
4 changes: 2 additions & 2 deletions docs/book/chapters/source-validation-to-pr.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ public/private scan;完整公开 smoke fleet 是另一回事。更慢的是真
authority 的改动需要一个一次性隔离实例,跑完整套件是分钟到十几分钟量级。每个 PR 都等最宽矩阵,
代价会摊到所有贡献者身上。

一百个命令如果都落在同一层,结论仍然只有一层。开头情境中的检查覆盖的是内存中的规则与静态约束,仍需补充受影响后端的证据。
**跑得多不等于覆盖对。** 一百个命令如果都落在同一层,结论仍然只有一层。开头情境中的检查覆盖的是内存中的规则与静态约束,仍需补充受影响后端的证据。

**有些结论需要人工判断。** 自动检查可以提示默认行为变化是否有说明,但披露是否准确、证据是否覆盖真实影响,仍需要 review。

Expand Down Expand Up @@ -731,7 +731,7 @@ Projection/Docs/fixtures 与 Extension 等贡献面会有不同的最近验证
1. **每一项验证都要对应一个具名风险。** 对应不上的命令属于惯例,构不成本 PR 的证据。
2. **期望值先于实现。** 从当前输出反推的断言只能做 characterization,不能作为 correctness
authority。
3. 拿不到隔离环境时,正确动作是报告证据缺口并暂停交付。
3. **跳过不等于通过。** 拿不到隔离环境时,正确动作是报告证据缺口并暂停交付。
4. **默认行为变化有三件必做:重命名 smoke、更新 docs/release note、点名受影响 lane。**
漏掉第一件的测试仍然是绿的,这正是它危险的原因。
5. **merged、released、deployed、observed 是四种状态。** 不能用前一种的证据宣称后一种。
Expand Down
2 changes: 1 addition & 1 deletion docs/book/en/chapters/00-reading-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -142,7 +142,7 @@ Operators need not run source tests first; prospective contributors can use
Command categories remain explicit. **Runnable** requires the stated version, inputs, and authorization.
**Based on the official scaffold** follows the existing teaching package without inventing a runtime.
**Simplified for explanation** tables, labels, and data shapes must not be pasted into production
configuration.
configuration. Record preview, execution, readback, and test results separately.

## Four questions for an accountable explanation {#judgment-standard}

Expand Down
2 changes: 1 addition & 1 deletion docs/book/en/chapters/01-from-session-to-loop.md
Original file line number Diff line number Diff line change
Expand Up @@ -147,7 +147,7 @@ Externalized state carries costs. Naming them is what lets you judge when it pay

## Invariants

1. Inspect addressable records, identity, and revision rather than whether a window is open.
1. **Prompt content alone does not prove durable writeback.** Inspect addressable records, identity, and revision rather than whether a window is open.
2. **The execution plane and control plane cannot substitute for each other.** The control plane does not write code; the execution plane does not decide whether it is allowed.
3. **What is reused is lifecycle invariants, not a prompt.** That is what lets three different domains share one control plane.
4. **The next executor does not need to trust the previous one's account.** If it does, the state was not externalized far enough.
Expand Down
2 changes: 1 addition & 1 deletion docs/book/en/chapters/04b-budget-and-admission.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ The following is a **hypothetical faulty policy**, not a claim that current impl
| 11:00 | M1 | M1's second unchanged observation | Switch again and start counting again |
| 11:30 | M1 and M2 are each due | Update each observation independently | Depends on processing order rather than actual stagnation |

Conflating different targets. Preserve each Monitor's identity and count instead of repeatedly lowering the threshold. Conversely, without a usable Host executing due observations, correct counters remain static records: that is a liveness gap, not no-change evidence.
The problem is conflating different targets. Preserve each Monitor's identity and count instead of repeatedly lowering the threshold. Conversely, without a usable Host executing due observations, correct counters remain static records: that is a liveness gap, not no-change evidence.

## Choose an observation frequency while waiting for CI {#running-wait}

Expand Down
4 changes: 2 additions & 2 deletions docs/book/en/chapters/06-codex-app.md
Original file line number Diff line number Diff line change
Expand Up @@ -194,7 +194,7 @@ both exit successfully. Telling them apart requires the writeback and spend hist
**Boundary one: a heartbeat does not create a frontier.** A Goal with no Todos will not produce a next step
because it was woken more often. With no runnable candidate, enter wait or monitor and let the cadence slow.

Do not copy the quota state machine into
**Boundary two: the automation is not a second control plane.** Do not copy the quota state machine into
the automation prompt, and do not let it resolve runnable Todos on its own. The stable prompt carries
protocol; the judgment belongs to the packet read on each wake.

Expand Down Expand Up @@ -261,7 +261,7 @@ repeat reminders so that a wait does not become a high-frequency notification.
this turn's receipt is grounds to slow the cadence. Slowing happens when the current `scheduler_hint`
proposes it (`apply_needed=true`), through the four steps below.
4. **A cadence change needs all four steps**: proposal, host apply, host readback, ACK.
5. Only a Host readback that matches the target closes the
5. **A local ACK ledger does not prove Host state.** Only a Host readback that matches the target closes the
loop; a mismatch is repaired as `drift_detected`.
6. **Switching Hosts needs explicit handoff.** Shared Goal reads do not replace current authority, claim/lease, and fence checks.

Expand Down
2 changes: 1 addition & 1 deletion docs/book/en/chapters/09-extension-scaffold.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

Use a complete zero-permission teaching package to learn requests, responses, validation, and packaging. [Companion source](https://github.com/loopx-project/loopx/tree/main/packages/loopx-text-stats) in `packages/loopx-text-stats/` includes its manifest, Python package, two JSON Schemas, sample input, and standard-library tests.

Does not read or write Goals. The package owns text input and results; the existing Extension lifecycle owns installation, activation, and managed calls.
It does not read or write Goals. The package owns text input and results; the existing Extension lifecycle owns installation, activation, and managed calls.

## Run the complete example first

Expand Down
8 changes: 4 additions & 4 deletions docs/book/en/chapters/core-state-machines.md
Original file line number Diff line number Diff line change
Expand Up @@ -786,7 +786,7 @@ therefore not a state you can decide on; it has to be proven item by item.
services, and extensions do not align to that number. What actually binds is the typed owner, the protocol
schema, and the transition rules.

The owner in the diagram and the
**Boundary two: this map does not replace the migration boundary.** The owner in the diagram and the
implementation language are separate dimensions. When a semantic is already carried by a TypeScript
owner, rebuilding it in Python from this teaching map creates a second source of truth.

Expand All @@ -795,7 +795,7 @@ durable journal, an `effect_ref`, and a provider readback resolver carry that gu
external call is not automatically deduplicated because this chapter mentions reconciliation; settlement
fails closed when the resolver is missing or returns an unknown state.

The diagrams here explain. Before changing a rule, confirm the current typed owner, protocol schema,
**Boundary four: the diagram does not go to the front line.** The diagrams here explain the architecture rather than specifying the implementation. Before changing a rule, confirm the current typed owner, protocol schema,
characterization fixture, and migration boundary.

## Named failures: where the handoff breaks
Expand All @@ -815,7 +815,7 @@ been replaced continuing to write. `needs_rebase` exists as the rejection path f
while the source stays unchanged. The symptom is a persistent UI/CLI disagreement that returns to the old
value on every refresh. Repair the source or builder, then read back.

**Failure four:** A stopped Goal, paused quota, or blocked peer
**Failure four: the reason to stop is not the same as closure.** A stopped Goal, paused quota, or blocked peer
coordination can each stop polling; each is a legal stop. Only
`terminal_no_followup` means "stopped because validated Goal closure was derived." Collapsing them lets a
paused Goal look finished.
Expand All @@ -832,7 +832,7 @@ paused Goal look finished.
caller handles the rejection.
5. **Terminal is a conjunction.** Complete and closed Todo sources, no unresolved frontier, and a
structured `no_followup` intent must all hold.
6. Change a rule only after confirming the typed owner,
6. **A teaching map is not an implementation spec.** Change a rule only after confirming the typed owner,
protocol schema, characterization fixture, and migration boundary.

These six answer one question: **when the mechanisms are split across nine families that can only speak
Expand Down
2 changes: 1 addition & 1 deletion docs/book/en/chapters/source-protocol-map.md
Original file line number Diff line number Diff line change
Expand Up @@ -474,7 +474,7 @@ Before entering the source, confirm these hold on their own:
1. **The owner of a rule is the module that decides legal transitions, not the module that first prints words about it.** If you cannot name the protected invariant, the change is not yet located.
2. **A PR description carries one complete causal chain: source, invariant, decision, projection or effect, receipt, validation.** A slice that can only list function names cannot be reviewed.
3. **Documents describe responsibility ownership; code describes current behavior.** When they conflict, pick the authority by conflict type and make this PR update the other side.
4. Registration plus a real caller contract is the release test; verify with `loopx capability list --format json`.
4. **Code under `loopx/capabilities/<name>/` does not prove the Capability is shipped.** Registration plus a real caller contract is the release test; verify with `loopx capability list --format json`.
5. **Placement precedes implementation.** The capability id, provider id, and built-in or extension-delivered choice come with a written reason before the first line of code.
6. **Tasks come from public entrypoints.** Public Contributor Tasks, Issues, and fixtures are the only source of work you can participate in; live active state and maintainer-local judgment are not.

Expand Down
2 changes: 1 addition & 1 deletion docs/book/en/chapters/source-trace-protocol-chain.md
Original file line number Diff line number Diff line change
Expand Up @@ -491,7 +491,7 @@ For a control-plane failure, verify in order:
After a trace, these should hold on their own:

1. **Every renamed or redefined field comes with a full consumer list.** Updating producers alone is incomplete, and a missing-field fallback counts as a consumer.
2. The test is the first boundary that violates the invariant, not the final return value.
2. **Success at every layer is not evidence that the chain is correct.** The test is the first boundary that violates the invariant, not the final return value.
3. **A missing field's default participates in the decision.** So the contract must state whether absence means reject, repair, or compatibility fallback.
4. **Authority has exactly one canonical source.** Several places may read a field and only one owns it; mistaking a reader for the owner is the most common leftover from a cross-layer change.
5. **Judging authority follows the protocol document; judging current behavior follows the source.** When they conflict, pick by conflict type and make this change update the other side.
Expand Down
2 changes: 1 addition & 1 deletion docs/concepts/interaction-pattern-catalog.md
Original file line number Diff line number Diff line change
Expand Up @@ -2706,7 +2706,7 @@ keep "we stopped supporting this" from becoming "this was never configured".
(`loopx/control_plane/coordination/local_authority_shadow.ts:57`) rather than
disappearing into a transport error, because a rejection that looks like a
transient failure invites a retry loop.
3. One setting is retired; the
3. **Clearing is neither enable nor bootstrap.** One setting is retired; the
replacement capture path is configured on its own terms.
`apply_coordination_shadow_changes` is documented as "Clear retired settings
and configure the transaction-bound shadow independently"
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -127,8 +127,7 @@ fact,使下一轮可以重新计算 frontier:
| 外部写入结果不确定 | effect receipt + provider readback/reconcile | 先确认外部事实,再决定 retry、successor 或 closeout |
| PR merged、closed 或明确不再跟进 | terminal evidence + no-follow-up rationale | monitor 可关闭,后续 Turn 不会继续轮询已经结束的工作 |

它允许
模型、session、host 和外部系统在边界处失败,但不允许丢失已经确认的事实、effect identity
这个 bot 的“稳定执行”允许模型、session、host 和外部系统在边界处失败,但不允许丢失已经确认的事实、effect identity
和下一步恢复路径。长程稳定的目标,是让错误可发现、可归因、可恢复;即使 Agent 犯错,
已提交事实仍然有效,系统仍能形成下一步 frontier。

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -688,6 +688,7 @@ cli_channel -> 下一条 CLI 写回、何时允许 spend
2. 为什么 projection repair 要覆盖正常 delivery?
3. workspace repair 为什么比 capability repair 更晚覆盖?
4. terminal closure 同时检查哪些 todo、monitor、successor、replan 与 acceptance 状态?
5. `action_required=false` 为什么不代表 agent 可以 quiet no-op?

## 代码阅读方法

Expand Down
Loading
Loading