diff --git a/docs/reference/protocols/decision-context-architecture-v0.md b/docs/reference/protocols/decision-context-architecture-v0.md index eee82aaf99..17b1943404 100644 --- a/docs/reference/protocols/decision-context-architecture-v0.md +++ b/docs/reference/protocols/decision-context-architecture-v0.md @@ -75,11 +75,16 @@ packet fingerprint and requires authority confirmation. It is not Core truth. ### `decision_review_receipt_v0` -The settlement layer records one of four dispositions: +The settlement layer records one of five dispositions: - `approve`, `reject`, and `defer` exact-read an existing `user_gate` event whose scope is `direction:action:`; -- `no_change` requires an explicit semantic rebase receipt and creates no gate. +- `no_change` requires an explicit no-material-change semantic rebase and creates no gate; +- `observed` records reviewed material facts without proposing or authorizing an + action. It requires a material-change rebase and rejects proposal/gate references. + +An empty rebase cannot be settled. Reading or capturing source items alone does +not prove semantic review; previews validate the same evidence chain before any write. The receipt proves that the evidence batch was reviewed or found immaterial. It allows private source cursors to advance after validated lifecycle writeback, diff --git a/docs/reference/protocols/decision-context-architecture-v0.zh-CN.md b/docs/reference/protocols/decision-context-architecture-v0.zh-CN.md index f8a06b2525..2d34333ccf 100644 --- a/docs/reference/protocols/decision-context-architecture-v0.zh-CN.md +++ b/docs/reference/protocols/decision-context-architecture-v0.zh-CN.md @@ -99,11 +99,16 @@ proposal 必须引用 evidence packet 的稳定指纹,并显式标记 ### `decision_review_receipt_v0` -结算层记录四种 disposition: +结算层记录五种 disposition: - `approve`、`reject`、`defer` 必须精确回读现有 `user_gate` event,且 gate scope 必须是 `direction:action:`; -- `no_change` 必须有显式 semantic rebase 证明,不创建 gate。 +- `no_change` 必须有显式无实质变化的 semantic rebase 证明,不创建 gate; +- `observed` 记录已评审的新事实,不提出或授权动作;必须有 material-change + rebase,且不能携带 proposal 或 gate 引用。 + +空 rebase 不能结算。采集或读取来源本身不证明语义评审;预览与执行使用相同的证据链 +校验,在任何写入前拒绝不完整或不匹配的证明。 该 receipt 只证明“这批证据已评审或没有实质影响”,允许在 lifecycle writeback 验证后推进私有 source cursor;它不是 outcome,也不创造动作权限。 diff --git a/loopx/capabilities/decision_context/README.md b/loopx/capabilities/decision_context/README.md index 735a8d7fea..bafe99c45a 100644 --- a/loopx/capabilities/decision_context/README.md +++ b/loopx/capabilities/decision_context/README.md @@ -33,7 +33,7 @@ flowchart LR READ["Bounded scan + exact read
freshness · revision · conflicts"] EVIDENCE["Evidence packet
accepted · rejected · stale · conflicting"] PROPOSAL["Decision proposal
recommendation · alternatives · stop list"] - REVIEW["Review settlement
approve · reject · defer · no change"] + REVIEW["Review settlement
approve · reject · defer · observed · no change"] CORE["LoopX lifecycle
todo · user gate · event"] OUTCOME["Outcome receipt
later observed result"] MEMORY["Reward Memory
reviewed reusable experience"] @@ -106,7 +106,7 @@ change touches. | `assembler.py` | Deterministic authority rebase, advisory recall assembly, `decision_source_coverage_v0` | | `freshness.py` | Per-source freshness reports and capture host health projection | | `packets.py` | Public-safe evidence, proposal, review and outcome packets | -| `review_settlement.py` | Owner-gated or quiet settlement of one assembly | +| `review_settlement.py` | Owner-gated or evidence-only settlement of one assembly | | `cursor_commit.py` | Validated private cursor commit after settlement | | `private_state.py` | Private cursor and pending-settlement file IO | | `outcome_feedback.py` | Audited feedback from outcomes into Reward Memory | @@ -137,7 +137,7 @@ To add an observable field: |---|---|---| | `decision_evidence_packet_v0` | What should the decision trust now? | Changed facts, accepted recall, stale/rejected claims, conflicts, revisions, provider health | | `decision_proposal_v0` | What should happen next? | Objective scores, recommendation, alternatives, actions, stop list | -| `decision_review_receipt_v0` | What did the owner decide about the proposal? | Approve/reject/defer gate evidence, or an explicit quiet no-change settlement | +| `decision_review_receipt_v0` | How was the evidence or proposal reviewed? | Approve/reject/defer gate evidence, observed facts without action authority, or explicit quiet no-change | | `decision_outcome_receipt_v0` | What happened after the decision? | Accepted decision, transitions, outcomes, invalidated assumptions, review time | The evidence packet is intended to be deterministic and auditable. The @@ -332,7 +332,11 @@ loopx decision-context settle-review \ ``` For an explicit semantic `no_change`, omit `--proposal-json` and -`--source-event-id`; no user gate is created. Preview by omitting `--execute`. +`--source-event-id`; no user gate is created. For reviewed new facts that do not +propose an action, also pass `--disposition observed`. This requires a material +semantic rebase; an empty rebase cannot settle, and collection alone is not +review. An observed receipt is not a quiet no-op and does not confirm authority +or approve any proposal. Preview by omitting `--execute`. These commands write only the caller-selected private pending/cursor state and the existing local rollout event log. They grant no trading, external action, or other irreversible authority. Removing the private profile disables the diff --git a/loopx/capabilities/decision_context/README.zh-CN.md b/loopx/capabilities/decision_context/README.zh-CN.md index eca959320e..6663beae7a 100644 --- a/loopx/capabilities/decision_context/README.zh-CN.md +++ b/loopx/capabilities/decision_context/README.zh-CN.md @@ -31,7 +31,7 @@ flowchart LR READ["有界扫描 + exact read
freshness · revision · conflict"] EVIDENCE["Evidence packet
采纳 · 拒绝 · 过期 · 冲突"] PROPOSAL["Decision proposal
建议 · 备选 · stop list"] - REVIEW["Review settlement
approve · reject · defer · no change"] + REVIEW["Review settlement
approve · reject · defer · observed · no change"] CORE["LoopX lifecycle
todo · user gate · event"] OUTCOME["Outcome receipt
后续真实结果"] MEMORY["Reward Memory
经评审的可复用经验"] @@ -122,7 +122,7 @@ exact-read 完整度和未覆盖的 P0 source 投影为公开安全的回执。` |---|---|---| | `decision_evidence_packet_v0` | 这次决策现在应该相信什么? | changed facts、采纳的召回、过期/拒绝 claim、冲突、revision、provider health | | `decision_proposal_v0` | 下一步建议做什么? | objective score、推荐决策、备选方案、行动、stop list | -| `decision_review_receipt_v0` | Owner 如何处理这次建议? | approve/reject/defer 的 gate 证据,或显式 quiet no-change settlement | +| `decision_review_receipt_v0` | 本次事实或建议如何完成评审? | approve/reject/defer 的 gate 证据、无行动权限的 observed 新事实,或显式 quiet no-change | | `decision_outcome_receipt_v0` | 决策之后实际发生了什么? | 接受的决策、状态迁移、真实结果、失效假设、复核时间 | Evidence packet 尽量确定性和可审计;proposal 明确只是建议;review receipt @@ -291,7 +291,10 @@ loopx decision-context settle-review \ ``` 显式语义 `no_change` 不传 `--proposal-json` 和 `--source-event-id`,也不会创建 -user gate。去掉 `--execute` 即为预览。这些命令只写调用方指定的私有 pending/ +user gate。已读到新事实但不提出行动时,另传 `--disposition observed`:必须已有 +material-change 语义 rebase,空 rebase 或仅采集正文不能结算。此 receipt 不属于 +quiet no-op,也不确认行动权限或批准任何 proposal。 +去掉 `--execute` 即为预览。这些命令只写调用方指定的私有 pending/ cursor 状态和现有本地 rollout event log。 移除私有 profile 即关闭入口;删除尚未结算的 pending checkpoint 不会改变 active cursor。 diff --git a/loopx/capabilities/decision_context/cli.py b/loopx/capabilities/decision_context/cli.py index 30652b6ce6..ece48d0629 100644 --- a/loopx/capabilities/decision_context/cli.py +++ b/loopx/capabilities/decision_context/cli.py @@ -243,7 +243,7 @@ def register_decision_context_commands( settle_review = commands.add_parser( "settle-review", help=( - "Exact-read a user-gate event or semantic no-change result, append " + "Validate a user-gate decision or evidence-only review, append " "validated writeback, and CAS-commit private cursors." ), ) @@ -256,6 +256,15 @@ def register_decision_context_commands( settle_review.add_argument("--event-log", required=True) settle_review.add_argument("--proposal-json") settle_review.add_argument("--source-event-id") + settle_review.add_argument( + "--disposition", + choices=("no_change", "observed"), + help=( + "Evidence-only review: observed records new facts without action " + "authority; no_change requires explicit no-change proof. Omit for " + "a user-gate decision, whose disposition is read from its event." + ), + ) settle_review.add_argument("--actor-ref", required=True) settle_review.add_argument("--reason-code", required=True) settle_review.add_argument("--summary", required=True) @@ -427,6 +436,7 @@ def handle_decision_context_command( actor_ref=args.actor_ref, reason_code=args.reason_code, summary=args.summary, + disposition=args.disposition, proposal=proposal, source_event_id=( str(args.source_event_id).strip() diff --git a/loopx/capabilities/decision_context/cursor_commit.py b/loopx/capabilities/decision_context/cursor_commit.py index 3c4bee4688..24829d86e7 100644 --- a/loopx/capabilities/decision_context/cursor_commit.py +++ b/loopx/capabilities/decision_context/cursor_commit.py @@ -252,6 +252,19 @@ def _validate_review_packet_chain( raise ValueError( "decision-context no_change settlement lacks semantic proof" ) + elif disposition == "observed": + semantic_rebase = packet.get("semantic_rebase") + if ( + not isinstance(semantic_rebase, Mapping) + or semantic_rebase.get("schema_version") + != DECISION_SEMANTIC_REBASE_RECEIPT_SCHEMA_VERSION + or semantic_rebase.get("status") != "material_change" + or semantic_rebase.get("quiet_noop_allowed") is not False + or proposal is not None + ): + raise ValueError( + "decision-context observed settlement lacks material review" + ) else: if ( proposal is None diff --git a/loopx/capabilities/decision_context/packets.py b/loopx/capabilities/decision_context/packets.py index 351473f7b4..1440148e18 100644 --- a/loopx/capabilities/decision_context/packets.py +++ b/loopx/capabilities/decision_context/packets.py @@ -39,6 +39,7 @@ "reject", "defer", "no_change", + "observed", } # Refs #5136, direction 3: "does this text carry a local path?" is decided once @@ -480,11 +481,12 @@ def build_decision_review_receipt( gate_todo_id: str | None = None, source_event_id: str | None = None, ) -> dict[str, Any]: - """Record one reviewed proposal or an explicit semantic no-change result. + """Record a proposal decision or an evidence-only semantic review. Review settlement is deliberately separate from outcome observation. A user may approve, reject, or defer a proposal before its real-world outcome - exists, while a semantic no-change result needs no user authority at all. + exists. Observing new facts and recording no material change both need no + user-gate authority; neither authorizes an action. """ normalized_disposition = _compact_token( @@ -493,9 +495,9 @@ def build_decision_review_receipt( ) if normalized_disposition not in DECISION_REVIEW_DISPOSITIONS: raise ValueError( - "disposition must be approve, reject, defer, or no_change" + "disposition must be approve, reject, defer, no_change, or observed" ) - gated = normalized_disposition != "no_change" + gated = normalized_disposition in {"approve", "reject", "defer"} gated_values = { "proposal_packet_ref": proposal_packet_ref, "gate_todo_id": gate_todo_id, @@ -512,7 +514,7 @@ def build_decision_review_receipt( ) elif any(value is not None for value in gated_values.values()): raise ValueError( - "no_change review receipt must not reference a proposal or user gate" + f"{normalized_disposition} review receipt must not reference a proposal or user gate" ) packet: dict[str, Any] = { diff --git a/loopx/capabilities/decision_context/review_settlement.py b/loopx/capabilities/decision_context/review_settlement.py index 7d57b9b6ee..7c4b16f00e 100644 --- a/loopx/capabilities/decision_context/review_settlement.py +++ b/loopx/capabilities/decision_context/review_settlement.py @@ -1,4 +1,4 @@ -"""Owner-gated or quiet settlement for one Decision Context assembly.""" +"""Owner-gated or evidence-only settlement for one Decision Context assembly.""" from __future__ import annotations @@ -9,6 +9,7 @@ from ...rollout_event_log import append_rollout_event, build_rollout_event from .assembler import DecisionContextAssembly from .cursor_commit import ( + _validate_review_packet_chain, commit_profile_decision_cursors, resolve_decision_review_source_event, ) @@ -31,9 +32,15 @@ def settle_profile_decision_review( summary: str, proposal: Mapping[str, Any] | None = None, source_event_id: str | None = None, + disposition: str | None = None, execute: bool = False, ) -> dict[str, Any]: - """Settle a reviewed proposal or an explicit semantic no-change result.""" + """Settle a proposal decision or an explicitly reviewed evidence update. + + Gated dispositions come only from the exact user-gate event. Without a + gate, callers may explicitly observe new facts or retain the legacy + semantic no-change default. Neither path confers action authority. + """ packet = assembly.public_packet() evidence = packet.get("evidence_packet") @@ -46,6 +53,8 @@ def settle_profile_decision_review( proposal_ref: str | None = None gate_todo_id: str | None = None if source_event_id is not None: + if disposition is not None: + raise ValueError("evidence-only disposition cannot accompany a user-gate event") if proposal is None: raise ValueError("gated decision review requires a proposal") proposal_ref = str(proposal.get("packet_ref") or "") @@ -59,7 +68,9 @@ def settle_profile_decision_review( else: if proposal is not None: raise ValueError("proposal settlement requires a user-gate event") - disposition = "no_change" + disposition = disposition if disposition is not None else "no_change" + if disposition not in {"no_change", "observed"}: + raise ValueError("proposal disposition requires a user-gate event") recorded_at = str(packet.get("observed_at") or "") review_receipt = build_decision_review_receipt( @@ -75,6 +86,14 @@ def settle_profile_decision_review( gate_todo_id=gate_todo_id, source_event_id=source_event_id, ) + # Validate semantic proof before preview success or any event append. + # Cursor commit revalidates this chain together with profile/cursor CAS. + _validate_review_packet_chain( + assembly=assembly, + proposal=proposal, + review_receipt=review_receipt, + event_log_path=lifecycle_event_log_path, + ) artifact_refs = [evidence_ref, str(review_receipt["packet_ref"])] if proposal_ref is not None: artifact_refs.append(proposal_ref) diff --git a/tests/capabilities/test_decision_context_capture.py b/tests/capabilities/test_decision_context_capture.py index f27fd79c4f..b1370e870a 100644 --- a/tests/capabilities/test_decision_context_capture.py +++ b/tests/capabilities/test_decision_context_capture.py @@ -3,12 +3,14 @@ import json import sqlite3 from dataclasses import replace +from datetime import datetime, timedelta import pytest from loopx.capabilities.decision_context import ( DecisionEvidenceRecords, settle_profile_decision_review, + write_private_pending_decision_settlement, ) from loopx.cli import main from loopx.capabilities.decision_context.capture import ( @@ -120,6 +122,72 @@ def test_stale_revision_cannot_be_silently_consumed(setup): assert not args["cursor_path"].exists() +def test_material_review_cli_releases_capture_without_authorizing_action(setup, capsys, monkeypatch): + args, _, authority = setup + captured = capture_profile_sources(**args, execute=True) + assert captured["pending_batch_count"] == 1 + reads = [] + + def rebase(collection): + current = collection.authority[0] + reads.append(current.content) + return DecisionEvidenceRecords(changed_facts=({ + "fact_id": "fact:status", + "summary": "The source reports a new status.", + "source_ref": current.source_ref, + "source_revision": current.source_revision, + "observed_at": current.observed_at, + "freshness": "current", + "authority": "first_party", + },)) + + assembly = assemble_captured_decision_evidence( + **args, batch_id=1, decision_id="review-facts", rebase=rebase, + ) + assert reads == ["private-body-not-for-spool"] + assert not args["cursor_path"].exists() + pending = args["spool_path"].parent / "pending.json" + events = args["spool_path"].parent / "events.jsonl" + write_private_pending_decision_settlement(pending, assembly) + command = [ + "--format", "json", "decision-context", "settle-review", + "--goal-id", args["goal_id"], "--agent-id", args["agent_id"], + "--profile", str(args["profile_path"]), + "--cursor-state", str(args["cursor_path"]), + "--pending-settlement", str(pending), "--event-log", str(events), + "--disposition", "observed", "--actor-ref", "agent:example-agent", + "--reason-code", "new_facts_reviewed", + "--summary", "New facts were reviewed without proposing an action.", + ] + assert main(command) == 0 + preview = json.loads(capsys.readouterr().out) + assert preview["executed"] is False + assert not events.exists() + assert not args["cursor_path"].exists() + assert main([*command, "--execute"]) == 0 + settled = json.loads(capsys.readouterr().out) + assert settled["disposition"] == "observed" + assert settled["quiet_noop"] is False + assert settled["review_receipt"]["authority_confirmed"] is False + assert settled["review_receipt"]["gate_todo_id"] is None + assert settled["cursor_commit"]["readback_verified"] is True + assert "private-body-not-for-spool" not in json.dumps(settled) + assert str(authority) not in json.dumps(settled) + assert all(json.loads(line)["event_kind"] == "validation" + for line in events.read_text().splitlines()) + assert capture_profile_sources(**args, execute=True)["pending_batch_count"] == 0 + authority.write_text("another-private-change") + next_at = datetime.fromisoformat(captured["sources"][0]["last_checked_at"]) + timedelta(hours=1) + + class NextCaptureClock(datetime): + @classmethod + def now(cls, tz=None): + return next_at + + monkeypatch.setattr("loopx.capabilities.decision_context.capture.datetime", NextCaptureClock) + assert capture_profile_sources(**args, execute=True)["pending_batch_count"] == 1 + + def test_binding_change_holds_existing_state(setup): args, payload, _ = setup capture_profile_sources(**args, execute=True) diff --git a/tests/capabilities/test_decision_context_packets.py b/tests/capabilities/test_decision_context_packets.py index 44102033c8..04cc55989b 100644 --- a/tests/capabilities/test_decision_context_packets.py +++ b/tests/capabilities/test_decision_context_packets.py @@ -350,7 +350,26 @@ def test_no_change_review_receipt_is_quiet_and_has_no_gate() -> None: assert receipt["quiet_noop"] is True -def test_no_change_review_receipt_rejects_user_gate_refs() -> None: +def test_observed_review_records_facts_without_authorizing_action() -> None: + receipt = build_decision_review_receipt( + goal_id="goal:example", + decision_id="decision:example", + evidence_packet_ref="decision-evidence-example", + recorded_at=REVIEW_AT, + disposition="observed", + actor_ref="agent:decision-advisor", + reason_code="new_facts_reviewed", + summary="New source facts were reviewed; no action was authorized.", + ) + assert receipt["authority_confirmation_required"] is False + assert receipt["authority_confirmed"] is False + assert receipt["outcome_observation_required"] is False + assert receipt["quiet_noop"] is False + assert receipt["source_event_id"] is None + + +@pytest.mark.parametrize("disposition", ["no_change", "observed"]) +def test_evidence_only_review_receipt_rejects_user_gate_refs(disposition: str) -> None: with pytest.raises(ValueError, match="must not reference"): build_decision_review_receipt( goal_id="goal:example", @@ -358,7 +377,7 @@ def test_no_change_review_receipt_rejects_user_gate_refs() -> None: evidence_packet_ref="decision-evidence-example", proposal_packet_ref="decision-proposal-example", recorded_at=REVIEW_AT, - disposition="no_change", + disposition=disposition, actor_ref="agent:decision-advisor", reason_code="no_material_change", summary="No material change.", diff --git a/tests/capabilities/test_decision_context_runtime.py b/tests/capabilities/test_decision_context_runtime.py index 9e45293984..c52bd04aa7 100644 --- a/tests/capabilities/test_decision_context_runtime.py +++ b/tests/capabilities/test_decision_context_runtime.py @@ -1473,6 +1473,39 @@ def test_review_settlement_rejects_gate_bound_to_another_proposal( assert not cursors.exists() +@pytest.mark.parametrize("rebase", [ + lambda _: DecisionEvidenceRecords(), + lambda _: DecisionEvidenceRecords(semantic_no_change=True), +]) +@pytest.mark.parametrize("execute", [False, True]) +def test_observed_settlement_requires_material_review_before_any_write( + tmp_path: Path, rebase: Any, execute: bool, +) -> None: + authority = tmp_path / "authority.md" + authority.write_text(PRIVATE_CONTENT, encoding="utf-8") + profile = write_profile(tmp_path / "profile.json", authority) + cursors = tmp_path / "cursors.json" + event_log = tmp_path / "events.jsonl" + _, assembly = assemble_profile_decision_evidence( + goal_id="example-decision-goal", agent_id="example-agent", + profile_path=profile, cursor_path=cursors, + decision_id="decision:adoption", observed_at=OBSERVED_AT, + before=BEFORE, rebase=rebase, + ) + assert assembly is not None + with pytest.raises(ValueError, match="observed settlement lacks material review"): + settle_profile_decision_review( + goal_id="example-decision-goal", agent_id="example-agent", + profile_path=profile, cursor_path=cursors, assembly=assembly, + lifecycle_event_log_path=event_log, + actor_ref="agent:decision-advisor", reason_code="new_facts_reviewed", + summary="New facts were reviewed.", disposition="observed", + execute=execute, + ) + assert not cursors.exists() + assert not event_log.exists() + + def test_prepare_and_settle_no_change_cli_crosses_turns_without_private_output( tmp_path: Path, capsys: pytest.CaptureFixture[str],