From e83f034077ef46e138cf3ac59603a9f91d410ab5 Mon Sep 17 00:00:00 2001 From: Robert DeVore Date: Tue, 13 Oct 2026 14:26:46 -0400 Subject: [PATCH] Bind legacy approval decisions to authoritative control revisions --- dispatch.kujo | 28 ++++++-- docs/control-boundaries.md | 20 ++++++ scripts/run_release_gate.sh | 2 + src/core/control_view.kujo | 22 ++++++ tests/control_view_tests.kujo | 37 ++++++++++ tests/revision_bound_approval_tests.sh | 96 ++++++++++++++++++++++++++ 6 files changed, 201 insertions(+), 4 deletions(-) create mode 100644 src/core/control_view.kujo create mode 100644 tests/control_view_tests.kujo create mode 100644 tests/revision_bound_approval_tests.sh diff --git a/dispatch.kujo b/dispatch.kujo index dd00056..303e2a5 100644 --- a/dispatch.kujo +++ b/dispatch.kujo @@ -1,3 +1,4 @@ +from src.core.control_view import build_control_view from src.core.retained_recovery import inspect_retained_run, plan_retained_reconciliation, apply_retained_reconciliation from src.bridge.sdk_adapter import custom_provider_api_key_env_allowed, custom_provider_endpoint_allowed, call_agent_model from src.cli.bundled_workflow import bundled_workflow_path, normalize_config_path @@ -1089,6 +1090,7 @@ func run_inspect(command_args) { payload := { "command": "inspect", "ok": true, + "control": build_control_view(run_state), "run_id": run_state["run_id"], "output_root": output_root, "contract": contract, @@ -1561,6 +1563,27 @@ func run_resume_decision(command_args) { recovered := reconcile_control_journal(run_state) if recovered["ok"] == false {exit_error(to_json(recovered["error"]))} run_state = recovered["run_state"] + decision_digest := sha256(to_json(decision)) + decision_history := dict_get_or(run_state, "human_decisions", {}) + if type(decision_history) != "dict" {decision_history = {}} + revision_bound := key_exists(decision, "expected_state_revision") + if has_key(decision_history, decision_id) { + receipt := decision_history[decision_id] + retained_digest := dict_get_or(receipt, "decision_sha256", "") + if retained_digest != "" { + if retained_digest != decision_digest {exit_error("decision_conflict: decision_id is bound to a different payload")} + if dict_get_or(receipt, "status", "") != "applied" {exit_error("control_recovery_required: retained decision is not applied; do not replay automatically")} + release_run_lock(lock) + print(to_json({"status": "already_applied", "run_id": run_id, "decision_id": decision_id})) + return + } + if revision_bound {exit_error("control_recovery_required: legacy receipt cannot prove an exact decision payload")} + } + if revision_bound { + expected_revision := decision["expected_state_revision"] + if type(expected_revision) != "int"||expected_revision < 1 {exit_error("invalid_resume_request: expected_state_revision must be a positive integer")} + if expected_revision != dict_get_or(run_state, "revision", 0) {exit_error("stale_resume_decision: expected_state_revision does not match current run state")} + } human_event := dict_get_or(run_state, "human_intervention", {}) if dict_get_or(human_event, "event_id", "") != event_id||dict_get_or(dict_get_or(human_event, "run", {}), "step_id", "") != step_id { exit_error("Resume request does not match the currently suspended event and step.") @@ -1572,10 +1595,6 @@ func run_resume_decision(command_args) { if expected_decision_id == ""||decision_id != expected_decision_id { exit_error("Resume request decision_id does not match the current approval.") } - decision_history := dict_get_or(run_state, "human_decisions", {}) - if type(decision_history) != "dict" { - decision_history := {} - } if has_key(decision_history, decision_id)&&dict_get_or(decision_history[decision_id], "status", "") == "claimed" {exit_error("control_recovery_required: decision was claimed; do not replay automatically")} if has_key(decision_history, decision_id)&&dict_get_or(decision_history[decision_id], "status", "") == "applied" { release_run_lock(lock) @@ -1590,6 +1609,7 @@ func run_resume_decision(command_args) { topic := dict_get_or(dict_get_or(run_state, "input", {}), "topic", "") workflow := dispatch_resolve_resume_workflow(run_state, "", topic, false) decision_history[decision_id] := { + "decision_sha256": decision_digest, "event_id": event_id, "step_id": step_id, "decision": decision_value, diff --git a/docs/control-boundaries.md b/docs/control-boundaries.md index b414d74..1254951 100644 --- a/docs/control-boundaries.md +++ b/docs/control-boundaries.md @@ -66,6 +66,26 @@ attempt's tool context as `reexecution_descriptor` with materializing the clean environment. Inspectable-only descriptors and unsafe non-idempotent targets are rejected. +`inspect --json` adds a `control` observation with schema +`kujo.control-view/v1`, `available: true`, `run_id`, `state_revision`, `run_status`, and the complete +`human_intervention` and `current_control_boundary` objects (or `null`). It uses +the authoritative state loader, including SQLite when present. If the serialized +control view exceeds 64 KiB, it returns `available: false` and +`reason: control_view_limit` instead of a partial approval object. This snapshot +is not an authorization or a journal reconciliation: it can become stale as soon +as it is read. Resume still validates under the run lock. + +Legacy approval decisions may now include a positive integer +`expected_state_revision`. A mismatch is rejected before the decision is claimed. +Omitting it preserves the legacy admission contract. All newly claimed legacy +decisions retain a digest of the parsed JSON payload. Redelivering an identical +applied decision returns `already_applied`, even after another gate opens; +changing the payload under that decision ID returns `decision_conflict`. +New claimed or failed receipts require explicit recovery and are never retried by +redelivery. A revision-bound request cannot use a historical receipt without a +digest as proof of an exact match. Actor metadata is attribution from the trusted +local caller; embedding it does not authenticate a human or grant permission. + Effect classes are `unknown`, `none`, `local_reversible`, `external_idempotent`, `external_non_idempotent`, and `destructive`. They do not imply rollback. They only constrain retry admission. Dispatch never claims diff --git a/scripts/run_release_gate.sh b/scripts/run_release_gate.sh index 5e8d74b..24dff05 100755 --- a/scripts/run_release_gate.sh +++ b/scripts/run_release_gate.sh @@ -166,6 +166,8 @@ run_suite effect_assurance_schema "$KUJO_BIN" run tests/effect_assurance_schema. run_suite effect_assurance env KUJO_BIN="$KUJO_BIN" node tests/effect_assurance_integration.mjs run_suite ability_assurance env KUJO_BIN="$KUJO_BIN" bash tests/ability_assurance_integration.sh run_suite reexecution_lifecycle "$KUJO_BIN" run tests/reexecution_lifecycle_fixture.kujo +run_suite control_view "$KUJO_BIN" test-run tests/control_view_tests.kujo -v +run_suite revision_bound_approval env KUJO_BIN="$KUJO_BIN" bash tests/revision_bound_approval_tests.sh run_suite resume_policy env KUJO_BIN="$KUJO_BIN" bash tests/resume_policy_tests.sh run_suite decision_claim env KUJO_BIN="$KUJO_BIN" bash tests/decision_claim_contract.sh run_suite sdk_adapter "$KUJO_BIN" test-run tests/sdk_adapter_tests.kujo -v diff --git a/src/core/control_view.kujo b/src/core/control_view.kujo new file mode 100644 index 0000000..2888b83 --- /dev/null +++ b/src/core/control_view.kujo @@ -0,0 +1,22 @@ +from src.core.utils import dict_get_or + +# An observation of the authoritative loaded revision, never a resume grant. +# Preserve complete control objects or refuse the projection; truncating IDs or +# evidence would create a misleading basis for a controller's review. +func build_control_view(run_state) { + view := { + "schema": "kujo.control-view/v1", + "available": true, + "run_id": dict_get_or(run_state, "run_id", ""), + "state_revision": dict_get_or(run_state, "revision", 0), + "run_status": dict_get_or(run_state, "status", ""), + "human_intervention": dict_get_or(run_state, "human_intervention", null), + "current_control_boundary": dict_get_or(run_state, "current_control_boundary", null) + } + if byte_length(to_json(view)) > 65536 { + return {"schema": "kujo.control-view/v1", "available": false, "reason": "control_view_limit"} + } + return view +} + +export build_control_view := build_control_view diff --git a/tests/control_view_tests.kujo b/tests/control_view_tests.kujo new file mode 100644 index 0000000..bcbe5fc --- /dev/null +++ b/tests/control_view_tests.kujo @@ -0,0 +1,37 @@ +test_setup { + from src.core.control_view import build_control_view +} + +test "control view retains complete approval identity and revision" { + event := {"event_id": "review-one", "security": {"decision_id": "decision-one"}} + boundary := {"boundary_id": "boundary-one", "status": "open"} + view := build_control_view({"run_id": "run-one", "revision": 42, "status": "paused", "human_intervention": event, "current_control_boundary": boundary}) + assert_true(view["available"]) + assert_equal(view["state_revision"], 42) + assert_equal(to_json(view["human_intervention"]), to_json(event)) + assert_equal(to_json(view["current_control_boundary"]), to_json(boundary)) +} + +test "oversized control objects are refused rather than truncated" { + large := "x" + for index in range(17) {large = large + large} + view := build_control_view({"run_id": "run-one", "revision": 42, "human_intervention": {"summary": large}}) + assert_false(view["available"]) + assert_equal(view["reason"], "control_view_limit") + assert_equal(has_key(view, "human_intervention"), 0) +} + +test "absent control objects stay absent" { + view := build_control_view({"run_id": "run-one", "revision": 1, "status": "completed"}) + assert_true(view["available"]) + assert_equal(view["human_intervention"], null) + assert_equal(view["current_control_boundary"], null) +} + +test "control view limit counts UTF-8 bytes" { + large := "界" + for index in range(15) {large = large + large} + view := build_control_view({"run_id": "run-one", "revision": 42, "human_intervention": {"summary": large}}) + assert_false(view["available"]) + assert_equal(view["reason"], "control_view_limit") +} diff --git a/tests/revision_bound_approval_tests.sh b/tests/revision_bound_approval_tests.sh new file mode 100644 index 0000000..c742cd3 --- /dev/null +++ b/tests/revision_bound_approval_tests.sh @@ -0,0 +1,96 @@ +#!/usr/bin/env bash +set -euo pipefail +cd "$(dirname "$0")/.." +KUJO_BIN="${KUJO_BIN:-kujo}" +root="tests/tmp/revision-bound-approval-$$" +mkdir -p "$root" +export DISPATCH_POLICY_PROFILE=development DISPATCH_OFFLINE_FIXTURE=true +# The same observation preserves native v2 boundary evidence without converting it. +case_root="$root/v2-view" +mkdir -p "$case_root" +"$KUJO_BIN" run tests/resume_policy_fixture.kujo "$case_root" v2 direct +run_id="$(jq -r .run_id "$case_root/decision.json")" +"$KUJO_BIN" run dispatch.kujo inspect "$run_id" --output-root "$case_root" --json > "$case_root/inspect.json" +jq -e --slurpfile state "$case_root/$run_id/state.json" '.control.available and .control.human_intervention == $state[0].human_intervention and .control.current_control_boundary == $state[0].current_control_boundary and .control.state_revision == $state[0].revision' "$case_root/inspect.json" >/dev/null +for backend in filesystem sqlite; do + case_root="$root/$backend" + mkdir -p "$case_root" + DISPATCH_STATE_BACKEND="$backend" "$KUJO_BIN" run tests/resume_policy_fixture.kujo "$case_root" v1 two-gates + run_id="$(jq -r .run_id "$case_root/decision.json")" + cp "$case_root/$run_id/state.json" "$case_root/before.json" + if [[ "$backend" == sqlite ]]; then + # The database remains authoritative even without a backend environment hint. + printf '{"status":"corrupted"}' > "$case_root/$run_id/state.json" + fi + "$KUJO_BIN" run dispatch.kujo inspect "$run_id" --output-root "$case_root" --json > "$case_root/inspect.json" + jq -e --slurpfile state "$case_root/before.json" '.control.available and .control.state_revision == $state[0].revision and .control.human_intervention == $state[0].human_intervention and .control.run_status == "paused"' "$case_root/inspect.json" >/dev/null + cp "$case_root/$run_id/state.json" "$case_root/snapshot-before.json" + revision="$(jq .control.state_revision "$case_root/inspect.json")" + jq --argjson revision "$revision" '. + {expected_state_revision:$revision}' "$case_root/decision.json" > "$case_root/bound.json" + for invalid in 0 -1 1.5 '"1"' null true; do + jq --argjson revision "$invalid" '.expected_state_revision=$revision' "$case_root/bound.json" > "$case_root/invalid.json" + if "$KUJO_BIN" run dispatch.kujo resume-decision "$case_root/invalid.json" --output-root "$case_root" > "$case_root/invalid.log" 2>&1; then exit 1; fi + grep -q 'invalid_resume_request' "$case_root/invalid.log" + done + jq '.expected_state_revision += 1' "$case_root/bound.json" > "$case_root/stale.json" + if "$KUJO_BIN" run dispatch.kujo resume-decision "$case_root/stale.json" --output-root "$case_root" > "$case_root/stale.log" 2>&1; then exit 1; fi + grep -q stale_resume_decision "$case_root/stale.log" + cmp "$case_root/snapshot-before.json" "$case_root/$run_id/state.json" + "$KUJO_BIN" run dispatch.kujo inspect "$run_id" --output-root "$case_root" --json > "$case_root/inspect-after-stale.json" + cmp "$case_root/inspect.json" "$case_root/inspect-after-stale.json" + "$KUJO_BIN" run dispatch.kujo resume-decision "$case_root/bound.json" --output-root "$case_root" > "$case_root/applied.log" + jq -e '.status == "paused" and .human_intervention.run.step_id == "gate-two" and ([.steps[] | select(.id == "downstream")][0].status == "pending")' "$case_root/$run_id/state.json" >/dev/null + cp "$case_root/$run_id/state.json" "$case_root/after.json" + "$KUJO_BIN" run dispatch.kujo resume-decision "$case_root/bound.json" --output-root "$case_root" > "$case_root/duplicate.log" + grep -q already_applied "$case_root/duplicate.log" + jq '.response="changed review"' "$case_root/bound.json" > "$case_root/conflict.json" + if "$KUJO_BIN" run dispatch.kujo resume-decision "$case_root/conflict.json" --output-root "$case_root" > "$case_root/conflict.log" 2>&1; then exit 1; fi + grep -q decision_conflict "$case_root/conflict.log" + cmp "$case_root/after.json" "$case_root/$run_id/state.json" +done +echo 'Revision-bound approvals: authoritative inspection, stale/invalid refusal, exact duplicate recovery, conflict and second-gate isolation passed.' + +# Older receipts cannot establish exact-payload equality for a revision-bound caller. +case_root="$root/legacy-receipt" +mkdir -p "$case_root" +"$KUJO_BIN" run tests/resume_policy_fixture.kujo "$case_root" v1 direct +run_id="$(jq -r .run_id "$case_root/decision.json")" +revision="$(jq .revision "$case_root/$run_id/state.json")" +decision_id="$(jq -r .decision_id "$case_root/decision.json")" +jq --argjson revision "$revision" '. + {expected_state_revision:$revision}' "$case_root/decision.json" > "$case_root/bound.json" +jq --arg id "$decision_id" '.human_decisions[$id]={status:"applied"}' "$case_root/$run_id/state.json" > "$case_root/legacy.json" +cp "$case_root/legacy.json" "$case_root/$run_id/state.json" +if "$KUJO_BIN" run dispatch.kujo resume-decision "$case_root/bound.json" --output-root "$case_root" > "$case_root/refused.log" 2>&1; then exit 1; fi +grep -q 'legacy receipt cannot prove' "$case_root/refused.log" +cmp "$case_root/legacy.json" "$case_root/$run_id/state.json" +"$KUJO_BIN" run dispatch.kujo resume-decision "$case_root/decision.json" --output-root "$case_root" > "$case_root/legacy.log" +grep -q already_applied "$case_root/legacy.log" + +# New claimed/failed receipts may be inspected but never replayed by redelivery. +case_root="$root/filesystem" +run_id="$(jq -r .run_id "$case_root/decision.json")" +decision_id="$(jq -r .decision_id "$case_root/decision.json")" +for status in claimed failed; do + jq --arg id "$decision_id" --arg status "$status" '.human_decisions[$id].status=$status' "$case_root/after.json" > "$case_root/uncertain.json" + cp "$case_root/uncertain.json" "$case_root/$run_id/state.json" + if "$KUJO_BIN" run dispatch.kujo resume-decision "$case_root/bound.json" --output-root "$case_root" > "$case_root/uncertain.log" 2>&1; then exit 1; fi + grep -q control_recovery_required "$case_root/uncertain.log" + cmp "$case_root/uncertain.json" "$case_root/$run_id/state.json" +done +echo 'Historical receipts retain compatibility; revision-bound ambiguity and uncertain claims fail closed.' + +# The shipped first-run templates all expose v1 approvals. Complete them using +# the inspected revision and exact event, never the blanket --yes option. +for template in research-report crud-reliability approval-handoff; do + case_root="$root/template-$template" + mkdir -p "$case_root" + "$KUJO_BIN" run dispatch.kujo demo 'Revision-bound first-run tour' --workflow "$template" --non-interactive --policy-profile production --output-root "$case_root" > "$case_root/start.log" + run_id="$(sed -n 's/^Run ID: //p' "$case_root/start.log")" + "$KUJO_BIN" run dispatch.kujo inspect "$run_id" --output-root "$case_root" --json > "$case_root/inspect.json" + jq -e '.control.available and .control.run_status == "paused" and .control.human_intervention.schema_version == "1.0"' "$case_root/inspect.json" >/dev/null + jq '.control | {run_id, expected_state_revision:.state_revision, step_id:.human_intervention.run.step_id, event_id:.human_intervention.event_id, decision_id:.human_intervention.security.decision_id, decision:"approve"}' "$case_root/inspect.json" > "$case_root/bound.json" + "$KUJO_BIN" run dispatch.kujo resume-decision "$case_root/bound.json" --output-root "$case_root" --policy-profile production > "$case_root/resume.log" + "$KUJO_BIN" run dispatch.kujo inspect "$run_id" --output-root "$case_root" --json > "$case_root/completed.json" + jq -e '.control.run_status == "completed" and ([.steps[] | select(.status != "completed" and .status != "skipped")] | length == 0)' "$case_root/completed.json" >/dev/null +done +echo 'All three shipped offline templates completed through revision-bound approval.'