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
28 changes: 24 additions & 4 deletions dispatch.kujo
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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.")
Expand All @@ -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)
Expand All @@ -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,
Expand Down
20 changes: 20 additions & 0 deletions docs/control-boundaries.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <run-id> --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
Expand Down
2 changes: 2 additions & 0 deletions scripts/run_release_gate.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
22 changes: 22 additions & 0 deletions src/core/control_view.kujo
Original file line number Diff line number Diff line change
@@ -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
37 changes: 37 additions & 0 deletions tests/control_view_tests.kujo
Original file line number Diff line number Diff line change
@@ -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")
}
96 changes: 96 additions & 0 deletions tests/revision_bound_approval_tests.sh
Original file line number Diff line number Diff line change
@@ -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.'
Loading