diff --git a/loopx/control_plane/effect_runtime_handlers.ts b/loopx/control_plane/effect_runtime_handlers.ts index 862f1b739d..e58f4242f5 100644 --- a/loopx/control_plane/effect_runtime_handlers.ts +++ b/loopx/control_plane/effect_runtime_handlers.ts @@ -273,6 +273,7 @@ export function createEffectRuntimeHandlers( ["turn_journal.find_settlement", lazyHandler(() => import("./turn_driver/turn_journal_query.ts"), ({findTurnJournalBySettlement}) => findTurnJournalBySettlement)], ["turn_journal.find_instance", lazyHandler(() => import("./turn_driver/turn_journal_query.ts"), ({findTurnJournalByInstance}) => findTurnJournalByInstance)], ["turn_journal.observed_capabilities", lazyHandler(() => import("./turn_driver/turn_journal_query.ts"), ({readTurnJournalCapabilities}) => readTurnJournalCapabilities)], + ["turn_journal.evidence_chain", lazyHandler(() => import("./turn_driver/turn_journal_query.ts"), ({readTurnJournalEvidenceChain}) => readTurnJournalEvidenceChain)], ["todo.priority.plan", lazyHandler(() => import("./todos/priority.ts"), ({evaluateTodoPriority}) => evaluateTodoPriority)], ["todo.read", lazyHandler(() => import("./todos/read_transport.ts"), ({readTodoRuntime}) => readTodoRuntime)], ["capabilities.periodic_report.progress.select", lazyHandler(() => import("./capabilities/periodic_report_progress.ts"), ({selectPeriodicReportProgress}) => selectPeriodicReportProgress)], diff --git a/loopx/control_plane/turn_driver/journal_store.py b/loopx/control_plane/turn_driver/journal_store.py index 7f6ded60c0..54bf6c38d4 100644 --- a/loopx/control_plane/turn_driver/journal_store.py +++ b/loopx/control_plane/turn_driver/journal_store.py @@ -216,3 +216,36 @@ def turn_journal_observed_capabilities( if not isinstance(observed, list) or not all(isinstance(item, str) for item in observed): return None return observed + + +def turn_journal_evidence_chain( + runtime_root: Path, + *, + settlement_identity: Mapping[str, Any], + goal_ref: Mapping[str, Any] | None = None, +) -> dict[str, Any]: + """Read the exact journal-backed evaluation spine without inferring progress.""" + + request = { + "runtime_root": str(runtime_root.resolve()), + "settlement_identity": dict(settlement_identity), + } + if goal_ref is not None: + request["goal_ref"] = dict(goal_ref) + payload = effect_runtime_result("turn_journal.evidence_chain", request) + if ( + not isinstance(payload, dict) + or set(payload) != {"schema_version", "availability", "evidence_chain"} + or payload.get("schema_version") != "loopx_turn_journal_evidence_chain_v0" + or payload.get("availability") not in {"recorded", "missing"} + or ( + payload["availability"] == "recorded" + and not isinstance(payload.get("evidence_chain"), dict) + ) + or ( + payload["availability"] == "missing" + and payload.get("evidence_chain") is not None + ) + ): + raise RuntimeError("TypeScript Turn journal evidence-chain shape mismatch") + return dict(payload) diff --git a/loopx/control_plane/turn_driver/turn_journal_query.ts b/loopx/control_plane/turn_driver/turn_journal_query.ts index 6ddf11cdfd..c5d8f04f18 100644 --- a/loopx/control_plane/turn_driver/turn_journal_query.ts +++ b/loopx/control_plane/turn_driver/turn_journal_query.ts @@ -23,11 +23,48 @@ import { jsonObject, parseJsonSource, parsedSourceNumberTokens, requireJsonObjec import { interpretTurnJournal, parseTurnJournalGoalBinding, + transactionPhases, } from "./turn_journal.ts"; interface JournalEvidence { turn_key: string; observed_capabilities: string[] | null; + evidence_chain: TurnJournalEvidenceChain; +} + +export const TURN_JOURNAL_EVIDENCE_CHAIN_SCHEMA_VERSION = + "loopx_turn_journal_evidence_chain_v0"; + +type EvidenceAvailability = "recorded" | "missing" | "unknown" | "not_applicable"; + +interface JournalEvidenceFact { + availability: EvidenceAvailability; + value: JsonObject | null; +} + +export interface TurnJournalEvidenceChain { + settlement_identity: JsonObject; + turn_key: string; + status: string; + result_kind: string | null; + completed_phases: string[]; + failed_phase: string | null; + phases: Array<{ + phase: string; + completed: boolean; + failed: boolean; + }>; + host_result: JournalEvidenceFact; + task_validation: JournalEvidenceFact; + writeback: JournalEvidenceFact; + settlement_result: JournalEvidenceFact; + receipt: JournalEvidenceFact; +} + +export interface TurnJournalEvidenceChainReadback { + schema_version: typeof TURN_JOURNAL_EVIDENCE_CHAIN_SCHEMA_VERSION; + availability: "recorded" | "missing"; + evidence_chain: TurnJournalEvidenceChain | null; } function decodeIdentity(value: unknown): BoundSettlementIdentity { @@ -75,6 +112,83 @@ function observedCapabilities(envelope: JsonObject): string[] { return [...observed]; } +function journalEvidenceFact( + value: unknown, + phase: string, + completedPhases: readonly string[], + journalStatus: string, + failedPhase: string | null, +): JournalEvidenceFact { + const recorded = jsonObject(value); + const completed = completedPhases.includes(phase); + if (recorded !== null && (completed || failedPhase === phase)) { + return { availability: "recorded", value: recorded }; + } + if (completed || failedPhase === phase) { + return { availability: "missing", value: null }; + } + const phaseIndex = transactionPhases.indexOf(phase); + const failedIndex = failedPhase === null ? -1 : transactionPhases.indexOf(failedPhase); + if ( + journalStatus === "stopped" || + (journalStatus === "failed" && failedIndex >= 0 && failedIndex < phaseIndex) + ) { + return { availability: "not_applicable", value: null }; + } + return { availability: "unknown", value: null }; +} + +function receiptFact( + value: unknown, + journalStatus: string, +): JournalEvidenceFact { + const recorded = jsonObject(value); + if (recorded !== null) return { availability: "recorded", value: recorded }; + if (["committed", "stopped", "failed", "scheduler_action_required"].includes(journalStatus)) { + return { availability: "missing", value: null }; + } + return { availability: "unknown", value: null }; +} + +function projectEvidenceChain( + journal: JsonObject, + turnKey: string, + identity: BoundSettlementIdentity, + completedPhases: string[], + journalStatus: string, +): TurnJournalEvidenceChain { + const receipt = jsonObject(journal.receipt); + const failedPhase = typeof receipt?.failed_phase === "string" + ? receipt.failed_phase + : null; + return { + settlement_identity: settlementIdentityPayload(identity), + turn_key: turnKey, + status: journalStatus, + result_kind: typeof journal.result_kind === "string" ? journal.result_kind : null, + completed_phases: [...completedPhases], + failed_phase: failedPhase, + phases: transactionPhases.map(phase => ({ + phase, + completed: completedPhases.includes(phase), + failed: failedPhase === phase, + })), + host_result: journalEvidenceFact( + journal.host_result, "typed_result", completedPhases, journalStatus, failedPhase, + ), + task_validation: journalEvidenceFact( + journal.task_validation, "validation", completedPhases, journalStatus, failedPhase, + ), + writeback: journalEvidenceFact( + journal.writeback, "durable_writeback", completedPhases, journalStatus, failedPhase, + ), + settlement_result: journalEvidenceFact( + journal.settlement_result, "durable_writeback", completedPhases, journalStatus, failedPhase, + ), + receipt: receiptFact(journal.receipt, journalStatus), + }; +} + // A lost Host acknowledgement may retain the wake address before the caller // has seen the selected Todo or replan. Its only permitted result is a locator // for the original journal. Settlement and capability reads remain fully bound. @@ -140,6 +254,13 @@ function evidenceForJournal( ? observedCapabilities(turnPlanWorkSource(plan ?? {}, sourceNumberTokens(journal, parsedSourceNumberTokens(journal, numbers)).filter(({path}) => path[0] === "plan" && path[1] === "work_contract") .map(({path, token}) => [path.slice(2), token])).work) : null, + evidence_chain: projectEvidenceChain( + journal, + turnKey, + actual, + inspection.completed_phases, + inspection.journal_status, + ), }; } @@ -236,3 +357,24 @@ export async function readTurnJournalCapabilities(params: JsonObject): Promise<{ ); return { observed_capabilities: evidence?.observed_capabilities ?? null }; } + +/** Exact, read-only facts for evaluators; no field implies execution, progress, or causality. */ +export async function readTurnJournalEvidenceChain( + params: JsonObject, +): Promise { + const identity = decodeIdentity(params.settlement_identity); + const goalRef = Object.hasOwn(params, "goal_ref") + ? decodeGoalRef(params.goal_ref) + : null; + if (goalRef !== null && goalRef.goalId.value !== identity.goal_id) { + throw new EffectRuntimeRequestError( + "Turn journal query GoalRef conflicts with its settlement identity", + ); + } + const evidence = await queryTurnJournal(params.runtime_root, identity, goalRef); + return { + schema_version: TURN_JOURNAL_EVIDENCE_CHAIN_SCHEMA_VERSION, + availability: evidence === null ? "missing" : "recorded", + evidence_chain: evidence?.evidence_chain ?? null, + }; +} diff --git a/tests/control_plane/test_turn_journal_observed_capabilities.py b/tests/control_plane/test_turn_journal_observed_capabilities.py index 34d8bf2e3e..07a3938bc2 100644 --- a/tests/control_plane/test_turn_journal_observed_capabilities.py +++ b/tests/control_plane/test_turn_journal_observed_capabilities.py @@ -11,6 +11,7 @@ from loopx.control_plane.turn_driver import journal_store from loopx.control_plane.turn_driver import turn_journal_runtime from loopx.control_plane.turn_driver.journal_store import ( + turn_journal_evidence_chain, turn_journal_observed_capabilities, write_turn_journal_checkpoint, ) @@ -178,6 +179,70 @@ def _observed( return turn_journal_observed_capabilities(runtime, **kwargs) +def test_typescript_evidence_chain_is_available_through_python_readback( + tmp_path: Path, +) -> None: + _commit_journal_via_typescript_writer(tmp_path, _journal()) + + readback = turn_journal_evidence_chain( + tmp_path, + settlement_identity=_completion_identity(), + ) + assert readback["availability"] == "recorded" + chain = readback["evidence_chain"] + assert chain["settlement_identity"] == _completion_identity() + assert chain["turn_key"] == TURN_KEY + assert chain["completed_phases"] == TRANSACTION_PHASES + assert all(phase["completed"] for phase in chain["phases"]) + + +def test_evidence_chain_wrapper_preserves_exact_identity_and_missingness( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, +) -> None: + requests: list[tuple[str, dict[str, Any]]] = [] + expected = { + "schema_version": "loopx_turn_journal_evidence_chain_v0", + "availability": "missing", + "evidence_chain": None, + } + + def readback(method: str, params: dict[str, Any]) -> dict[str, Any]: + requests.append((method, params)) + return expected + + monkeypatch.setattr(journal_store, "effect_runtime_result", readback) + assert turn_journal_evidence_chain( + tmp_path, + settlement_identity=_completion_identity(), + goal_ref=GOAL_REF_A, + ) == expected + assert requests == [("turn_journal.evidence_chain", { + "runtime_root": str(tmp_path.resolve()), + "settlement_identity": _completion_identity(), + "goal_ref": GOAL_REF_A, + })] + + +@pytest.mark.parametrize("payload", [ + {}, + {"schema_version": "unknown", "availability": "missing", "evidence_chain": None}, + { + "schema_version": "loopx_turn_journal_evidence_chain_v0", + "availability": "recorded", + "evidence_chain": None, + }, +]) +def test_evidence_chain_wrapper_rejects_transport_shape_drift( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, payload: dict[str, Any], +) -> None: + monkeypatch.setattr(journal_store, "effect_runtime_result", lambda *_args, **_kwargs: payload) + with pytest.raises(RuntimeError, match="evidence-chain shape mismatch"): + turn_journal_evidence_chain( + tmp_path, + settlement_identity=_completion_identity(), + ) + + def test_typescript_committed_journal_lends_boundary_capabilities( tmp_path: Path, ) -> None: diff --git a/tests/control_plane_ts/effect_runtime_handlers.test.ts b/tests/control_plane_ts/effect_runtime_handlers.test.ts index 1dc0733f2e..b2d1d8373d 100644 --- a/tests/control_plane_ts/effect_runtime_handlers.test.ts +++ b/tests/control_plane_ts/effect_runtime_handlers.test.ts @@ -53,6 +53,13 @@ test("runtime boundary rejects malformed journal inspection request", async () = ); }); +test("runtime exposes settlement-addressed Turn evidence-chain readback", async () => { + await assert.rejects( + dispatchEffectRuntimeMethod(handlers, "turn_journal.evidence_chain", {}), + /settlement_identity must be an object/, + ); +}); + test("runtime exposes the native task-lease acquire transaction", async () => { await assert.rejects( dispatchEffectRuntimeMethod(handlers, "task_lease.acquire.native", { diff --git a/tests/control_plane_ts/turn_journal_query.test.ts b/tests/control_plane_ts/turn_journal_query.test.ts index ac2dd6bc28..c4036a66ea 100644 --- a/tests/control_plane_ts/turn_journal_query.test.ts +++ b/tests/control_plane_ts/turn_journal_query.test.ts @@ -6,7 +6,11 @@ import test, { type TestContext } from "node:test"; import { EffectRuntimeConflictError, EffectRuntimeRequestError } from "../../loopx/control_plane/effect_runtime_errors.ts"; import { commitTurnJournal } from "../../loopx/control_plane/turn_driver/turn_journal_effects.ts"; -import { findTurnJournalBySettlement, readTurnJournalCapabilities } from "../../loopx/control_plane/turn_driver/turn_journal_query.ts"; +import { + findTurnJournalBySettlement, + readTurnJournalCapabilities, + readTurnJournalEvidenceChain, +} from "../../loopx/control_plane/turn_driver/turn_journal_query.ts"; const phases = ["host_execute", "typed_result", "validation", "durable_writeback", "quota_spend", "scheduler_apply", "scheduler_ack"]; const selector = { goal_id: "goal", agent_id: "actor", todo_id: "todo_task", turn_instance_id: "turn-7" }; @@ -50,17 +54,159 @@ const capabilities = ( settlement_identity, ...(goal_ref === undefined ? {} : { goal_ref }), }); +const evidenceChain = ( + runtime_root: string, + settlement_identity: unknown = identity, + goal_ref?: unknown, +) => + readTurnJournalEvidenceChain({ + runtime_root, + settlement_identity, + ...(goal_ref === undefined ? {} : { goal_ref }), + }); test("missing history is a read-only observation", async t => { const { root, directory } = await fixture(t); assert.deepEqual(await lookup(root), { turn_key: null }); assert.deepEqual(await capabilities(root), { observed_capabilities: null }); + assert.deepEqual(await evidenceChain(root), { + schema_version: "loopx_turn_journal_evidence_chain_v0", + availability: "missing", + evidence_chain: null, + }); assert.deepEqual(await readdir(directory), []); await rm(directory, { recursive: true }); assert.deepEqual(await lookup(root), { turn_key: null }); await assert.rejects(readdir(directory), { code: "ENOENT" }); }); +test("an admitted plan without completed execution phases remains unknown", async t => { + const { root, path } = await fixture(t); + const value = journal(); + value.status = "in_progress"; + value.completed_phases = []; + Object.assign(value.plan, { replan_context: { planned_work: ["inspect"] } }); + Object.assign(value, { + host_result: { work_evidence: ["unconfirmed artifact"] }, + task_validation: { status: "passed" }, + }); + await writeFile(path, JSON.stringify(value)); + + const readback = await evidenceChain(root); + assert.equal(readback.availability, "recorded"); + const chain = readback.evidence_chain!; + assert.equal(chain.result_kind, null); + assert.ok(chain.phases.every(phase => !phase.completed && !phase.failed)); + for (const fact of [ + chain.host_result, + chain.task_validation, + chain.writeback, + chain.settlement_result, + chain.receipt, + ]) { + assert.deepEqual(fact, { availability: "unknown", value: null }); + } + assert.ok(!("replan_context" in chain)); +}); + +test("the evidence chain aligns recorded execution, validation and settlement facts", async t => { + const { root, path } = await fixture(t); + const value = journal(goalRefA); + const hostResult = { + schema_version: "loopx_turn_result_v0", + turn_key: key, + result_kind: "validated_progress", + completed_phases: phases.slice(0, 2), + path_delta_mode: "unchanged", + work_evidence: ["artifact: decoder output changed"], + validation_evidence: ["test: protocol and memory-safety checks passed"], + progress_observation: { + schema_version: "typed_progress_observation_v0", + result_class: "advanced", + work_item_id: "todo_task", + fingerprint: "decoder-progress", + }, + }; + const taskValidation = { + schema_version: "loopx_turn_task_validation_v0", + ok: true, + status: "passed", + validator_kind: "command", + summary: "independent checks passed", + }; + const writeback = { completion: { todo_id: "todo_task", status: "in_progress" } }; + const settlementResult = { + value: { result_kind: "validated_progress" }, + receipts: [{ step_kind: "durable_writeback", status: "committed", effect_id: identity.effect_id }], + failure: null, + }; + const receipt = { turn_key: key, completed_phases: [...phases], failed_phase: null }; + Object.assign(value, { + result_kind: "validated_progress", + host_result: hostResult, + task_validation: taskValidation, + validation_stage: "task_postcondition", + writeback, + settlement_result: settlementResult, + receipt, + }); + await writeFile(path, JSON.stringify(value)); + + const readback = await evidenceChain(root, identity, goalRefA); + assert.equal(readback.availability, "recorded"); + assert.deepEqual(readback.evidence_chain, { + settlement_identity: identity, + turn_key: key, + status: "committed", + result_kind: "validated_progress", + completed_phases: phases, + failed_phase: null, + phases: phases.map(phase => ({ phase, completed: true, failed: false })), + host_result: { availability: "recorded", value: hostResult }, + task_validation: { availability: "recorded", value: taskValidation }, + writeback: { availability: "recorded", value: writeback }, + settlement_result: { availability: "recorded", value: settlementResult }, + receipt: { availability: "recorded", value: receipt }, + }); +}); + +test("terminal stop makes later writeback and settlement facts not applicable", async t => { + const { root, path } = await fixture(t); + const value = journal(); + value.status = "stopped"; + value.completed_phases = phases.slice(0, 3); + Object.assign(value, { + result_kind: "blocked", + host_result: { result_kind: "blocked", work_evidence: null, validation_evidence: null }, + task_validation: { status: "not_required" }, + receipt: { turn_key: key, completed_phases: phases.slice(0, 3), failed_phase: null }, + }); + await writeFile(path, JSON.stringify(value)); + + const chain = (await evidenceChain(root)).evidence_chain!; + assert.deepEqual(chain.writeback, { availability: "not_applicable", value: null }); + assert.deepEqual(chain.settlement_result, { availability: "not_applicable", value: null }); + assert.equal(chain.host_result.availability, "recorded"); + assert.equal(chain.task_validation.availability, "recorded"); + assert.equal(chain.receipt.availability, "recorded"); +}); + +test("completed phases with absent facts preserve missingness", async t => { + const { root, path } = await fixture(t); + await writeFile(path, JSON.stringify(journal())); + + const chain = (await evidenceChain(root)).evidence_chain!; + for (const fact of [ + chain.host_result, + chain.task_validation, + chain.writeback, + chain.settlement_result, + chain.receipt, + ]) { + assert.deepEqual(fact, { availability: "missing", value: null }); + } +}); + test("real writer prefixes remain discoverable; only terminal history lends capabilities", async t => { const { root, path, directory } = await fixture(t); for (const count of [0, 2, 3, 4, 5, 7]) {