Skip to content
Merged
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 @@ -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:<proposal-packet-ref>`;
- `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,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -99,11 +99,16 @@ proposal 必须引用 evidence packet 的稳定指纹,并显式标记

### `decision_review_receipt_v0`

结算层记录四种 disposition:
结算层记录五种 disposition:

- `approve`、`reject`、`defer` 必须精确回读现有 `user_gate` event,且 gate scope
必须是 `direction:action:<proposal-packet-ref>`;
- `no_change` 必须有显式 semantic rebase 证明,不创建 gate。
- `no_change` 必须有显式无实质变化的 semantic rebase 证明,不创建 gate;
- `observed` 记录已评审的新事实,不提出或授权动作;必须有 material-change
rebase,且不能携带 proposal 或 gate 引用。

空 rebase 不能结算。采集或读取来源本身不证明语义评审;预览与执行使用相同的证据链
校验,在任何写入前拒绝不完整或不匹配的证明。

该 receipt 只证明“这批证据已评审或没有实质影响”,允许在 lifecycle writeback
验证后推进私有 source cursor;它不是 outcome,也不创造动作权限。
Expand Down
12 changes: 8 additions & 4 deletions loopx/capabilities/decision_context/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ flowchart LR
READ["Bounded scan + exact read<br/>freshness · revision · conflicts"]
EVIDENCE["Evidence packet<br/>accepted · rejected · stale · conflicting"]
PROPOSAL["Decision proposal<br/>recommendation · alternatives · stop list"]
REVIEW["Review settlement<br/>approve · reject · defer · no change"]
REVIEW["Review settlement<br/>approve · reject · defer · observed · no change"]
CORE["LoopX lifecycle<br/>todo · user gate · event"]
OUTCOME["Outcome receipt<br/>later observed result"]
MEMORY["Reward Memory<br/>reviewed reusable experience"]
Expand Down Expand Up @@ -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 |
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
9 changes: 6 additions & 3 deletions loopx/capabilities/decision_context/README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ flowchart LR
READ["有界扫描 + exact read<br/>freshness · revision · conflict"]
EVIDENCE["Evidence packet<br/>采纳 · 拒绝 · 过期 · 冲突"]
PROPOSAL["Decision proposal<br/>建议 · 备选 · stop list"]
REVIEW["Review settlement<br/>approve · reject · defer · no change"]
REVIEW["Review settlement<br/>approve · reject · defer · observed · no change"]
CORE["LoopX lifecycle<br/>todo · user gate · event"]
OUTCOME["Outcome receipt<br/>后续真实结果"]
MEMORY["Reward Memory<br/>经评审的可复用经验"]
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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。
Expand Down
12 changes: 11 additions & 1 deletion loopx/capabilities/decision_context/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -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."
),
)
Expand All @@ -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)
Expand Down Expand Up @@ -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()
Expand Down
13 changes: 13 additions & 0 deletions loopx/capabilities/decision_context/cursor_commit.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
12 changes: 7 additions & 5 deletions loopx/capabilities/decision_context/packets.py
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@
"reject",
"defer",
"no_change",
"observed",
}

# Refs #5136, direction 3: "does this text carry a local path?" is decided once
Expand Down Expand Up @@ -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(
Expand All @@ -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,
Expand All @@ -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] = {
Expand Down
25 changes: 22 additions & 3 deletions loopx/capabilities/decision_context/review_settlement.py
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -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,
)
Expand All @@ -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")
Expand All @@ -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 "")
Expand All @@ -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(
Expand All @@ -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)
Expand Down
68 changes: 68 additions & 0 deletions tests/capabilities/test_decision_context_capture.py
Original file line number Diff line number Diff line change
Expand Up @@ -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 (
Expand Down Expand Up @@ -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)
Expand Down
23 changes: 21 additions & 2 deletions tests/capabilities/test_decision_context_packets.py
Original file line number Diff line number Diff line change
Expand Up @@ -350,15 +350,34 @@ 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",
decision_id="decision:example",
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.",
Expand Down
Loading
Loading