← Files ClaraARCHIVED FILE
modules/studio-archive/scripts/reconcile_open_items.py
15.1 KB · Nov 21, 2026 · 00:11 UTC
"""Import, calculate and deliver one explicitly selected reconciliation.
The agent supplies reviewed mappings; this operation owns the mechanical Archive
sequence. Repeating a request reopens its result without repeating calculation.
"""
from __future__ import annotations
import argparse
import hashlib
import json
import mimetypes
import subprocess
import sys
from pathlib import Path
from typing import Any
__all__ = ["check_sources", "finish_reconciliation", "reconcile", "main"]
SCRIPTS = Path(__file__).resolve().parent
if str(SCRIPTS) not in sys.path:
sys.path.insert(0, str(SCRIPTS))
import archive_core as archive # noqa: E402
def _json(path: Path) -> dict[str, Any]:
return json.loads(path.read_text(encoding="utf-8"))
def _command(script: str, arguments: list[str], log: Path) -> dict[str, Any]:
component = SCRIPTS.parent.parent / "open-item-reconciliation" / "scripts"
product = SCRIPTS.parents[2]
execution_root = None
if (product / "scripts/verified_execution.py").is_file():
sys.path.insert(0, str(product / "scripts"))
from verified_execution import bind_execution_run, release_execution_root
context = Path(arguments[arguments.index("--client-engagement") + 1])
# Use the existing run lease so later review survives a plugin update.
execution_root = bind_execution_run(context.parent, product)
component = execution_root / "modules/open-item-reconciliation/scripts"
try:
with log.open("w", encoding="utf-8") as handle:
# Fixed published component and Python; no shell or caller code.
result = subprocess.run( # nosec B603
[
sys.executable,
"-X",
"utf8",
"-I",
"-B",
str(component / script),
*arguments,
],
stdout=handle,
stderr=subprocess.STDOUT,
check=False,
)
finally:
if execution_root is not None:
release_execution_root(execution_root)
if result.returncode:
raise archive.ArchiveError(
f"Reconciliation {script} failed; retained diagnostics: {log}"
)
# The producer's stdout is a local diagnostic, never an alternate source.
return _json(log) if script == "audit_assurance.py" else {}
def _declarations(output: Path) -> list[dict[str, str]]:
declarations = []
for path in sorted(output.rglob("*")):
if not path.is_file():
continue
relative = path.relative_to(output).as_posix()
declarations.append(
{
"artifact_id": "reconciliation-"
+ hashlib.sha256(relative.encode()).hexdigest()[:32],
"path": relative,
"purpose": f"Reconciliation workpaper or supporting record: {relative}",
"audience": "review",
"media_type": mimetypes.guess_type(path.name)[0]
or "application/octet-stream",
}
)
return declarations
def _delivery(loaded: dict[str, Any], terminal: dict[str, Any]) -> dict[str, Any]:
output = Path(loaded["output_dir"])
final = _json(output / "reconciliation/final_artifacts.json")
reporting = terminal.get("reporting", {})
warnings = []
if (
reporting.get("status") == "unavailable"
or reporting.get("collection_status") == "incomplete"
):
warnings.append(
{
"kind": "data_usage_reporting_incomplete",
"message": "Data-usage measurement is incomplete; the accounting result is unchanged.",
"report_path": str(output / "model_data_report.md"),
}
)
ready = final.get("assurance", {}).get("report_ready", False)
return {
"status": terminal["status"],
"accounting_status": "verified" if ready else "review_required",
"report_ready": ready,
"client_id": loaded["context"]["client_id"],
"engagement_id": loaded["run"]["engagement_id"],
"run_id": loaded["run"]["run_id"],
"output_dir": str(output / "reconciliation"),
"artifacts": [
str(output / "reconciliation" / item["path"])
for item in final["outputs"]
if item.get("kind") in {"xlsx", "docx", "pdf"}
],
"review_handoff": final.get("review_handoff"),
"next_actions": final.get("next_actions", []),
"reporting": reporting,
"warnings": warnings,
}
def finish_reconciliation(
client_id: str,
engagement_id: str,
run_id: str,
*,
state_dir: Path | None = None,
expected_predecessor_checkpoint: str | None = None,
) -> dict[str, Any]:
"""Finish existing work, including an ordinarily reviewed/regenerated draft."""
root = Path(
archive.get_studio_client_folder(client_id, state_dir=state_dir)[
"client_folder"
]["client_root"]
)
loaded = archive.ledger.load_run(root, engagement_id, run_id)
if loaded["context"]["client_id"] != client_id:
raise archive.ArchiveError("Selected run belongs to another client.")
if loaded["run"]["workflow_id"] != "open-item-reconciliation":
raise archive.ArchiveError("Selected run is not an open-item reconciliation.")
output = Path(loaded["output_dir"])
if loaded["run"]["status"] in {"completed", "ready_for_review"}:
terminal = archive.complete_studio_client_workflow(
client_id, engagement_id, run_id, state_dir=state_dir
)
return _delivery(loaded, terminal)
if loaded["run"]["status"] != "running":
raise archive.ArchiveError(
f"Existing run is {loaded['run']['status']}; its evidence is retained."
)
# Keep replay diagnostics outside the sealed package. Reopening a review
# draft never launches the producer or a semantic worker again.
checkpoint_path = output / "reconciliation-review-checkpoint.json"
checkpoint = expected_predecessor_checkpoint
if checkpoint_path.exists():
retained = _json(checkpoint_path)
if retained["run_id"] != run_id or (
checkpoint is not None and checkpoint != retained["content_sha256"]
):
raise archive.ArchiveError("Review checkpoint differs from this run.")
checkpoint = retained["content_sha256"]
replay_arguments = [
"--client-engagement",
str(loaded["context_path"]),
"validate-run-json",
str(output / "reconciliation"),
]
if checkpoint is not None:
replay_arguments.extend(["--expected-predecessor-checkpoint", checkpoint])
replay = _command(
"audit_assurance.py",
replay_arguments,
output / "reconciliation-validation.json",
)
if not replay.get("ok"):
raise archive.ArchiveError("Reconciliation assurance replay did not pass.")
if not replay["assurance"]["report_ready"]:
if not checkpoint_path.exists():
# Retain the verified predecessor outside the mutable review tree.
# Later delivery must replay that same transition, not trust a hash
# supplied by the already-reviewed package.
checkpoint_path.write_text(
json.dumps(
{
"run_id": run_id,
"content_sha256": replay["assurance"]["content_sha256"],
},
indent=2,
)
+ "\n",
encoding="utf-8",
)
reported = archive.ledger._finish_terminal_reporting(loaded)
return _delivery(
loaded, {"status": "review_required", "reporting": reported["reporting"]}
)
if loaded["run"]["status"] == "running":
archive.finalize_studio_client_workflow(
client_id, engagement_id, run_id, _declarations(output), state_dir=state_dir
)
terminal = archive.complete_studio_client_workflow(
client_id, engagement_id, run_id, state_dir=state_dir
)
return _delivery(loaded, terminal)
def check_sources(request: dict[str, Any]) -> dict[str, Any]:
"""Check current cells before imports; source meaning stays agent-selected."""
script = SCRIPTS / "open_items_source_preflight.py"
result = subprocess.run( # nosec B603
[sys.executable, "-X", "utf8", "-I", "-B", str(script)],
input=json.dumps(request),
text=True,
capture_output=True,
check=False,
encoding="utf-8",
)
if result.returncode:
raise archive.ArchiveError("Source preflight failed: " + result.stderr.strip())
return json.loads(result.stdout)
def reconcile(
request: dict[str, Any], *, state_dir: Path | None = None
) -> dict[str, Any]:
"""Run the public workflow once, with explicit sources and reviewed mappings."""
client_id, engagement_id = request["client_id"], request["engagement_id"]
request_id = request["request_id"]
if not isinstance(request_id, str) or not request_id.strip():
raise archive.ArchiveError("A stable request_id is required for resumption.")
if not request["sources"]:
raise archive.ArchiveError("Select the reconciliation sources.")
root = Path(
archive.get_studio_client_folder(client_id, state_dir=state_dir)[
"client_folder"
]["client_root"]
)
headers, _ = archive.ledger._inspect_run_headers(root, engagement_id)
key = archive.ledger._text(request_id, label="request_id", maximum=200)
retained = [row for row in headers if row["idempotency_key"] == key]
if len(retained) > 1:
raise archive.ArchiveError(
"Request identity is ambiguous; retain existing jobs."
)
if retained and retained[0]["status"] != "prepared":
run = retained[0]
if run["workflow_id"] != "open-item-reconciliation":
raise archive.ArchiveError("Request ID belongs to another workflow.")
loaded = archive.ledger._load_run_identity(root, engagement_id, run["run_id"])
if run["status"] in {"completed", "ready_for_review"}:
archive.ledger.validate_run_artifacts(root, engagement_id, run["run_id"])
saved_request = Path(loaded["output_dir"]) / "reconciliation-request.json"
archive.ledger._ordinary_file(
saved_request, label="retained reconciliation request"
)
if _json(saved_request) != request:
raise archive.ArchiveError(
"This request_id already has different mappings or settings; select a new request_id."
)
return finish_reconciliation(
client_id, engagement_id, run["run_id"], state_dir=state_dir
)
check_sources(request)
mappings = {}
input_ids = []
for source in request["sources"]:
mapping = source["mapping"]
imported = archive.import_studio_client_document(
client_id,
Path(source["path"]),
"source",
engagement_id=engagement_id,
expected_sha256=source.get("sha256"),
state_dir=state_dir,
)
receipt = imported["input_receipt"]
relative = f"imports/{receipt['input_id']}/{receipt['stored_name']}"
if relative in mappings and mappings[relative] != mapping:
raise archive.ArchiveError("The same source has conflicting mappings.")
mappings[relative] = mapping
if imported["input_id"] not in input_ids:
input_ids.append(imported["input_id"])
prepared = archive.prepare_studio_client_workflow(
engagement_id,
"open-item-reconciliation",
input_ids=input_ids,
label=request.get("title"),
purpose=request.get("purpose"),
idempotency_key=request_id,
state_dir=state_dir,
)
if prepared["client_id"] != client_id:
raise archive.ArchiveError("Selected engagement belongs to another client.")
run_id = prepared["run"]["run_id"]
output = Path(prepared["client_engagement"]["output_dir"])
retained_request = output / "reconciliation-request.json"
if retained_request.exists() and _json(retained_request) != request:
raise archive.ArchiveError(
"This request_id already has different mappings or settings; select a new request_id."
)
if prepared["run"]["status"] != "prepared":
return finish_reconciliation(
client_id, engagement_id, run_id, state_dir=state_dir
)
archive.start_studio_client_workflow(
client_id, engagement_id, run_id, state_dir=state_dir
)
try:
retained_request.write_text(
json.dumps(request, indent=2) + "\n", encoding="utf-8"
)
assumptions = {
**request.get("assumptions", {}),
"reviewed_source_decisions": mappings,
}
assumptions_path = output / "reconciliation-assumptions.json"
assumptions_path.write_text(
json.dumps(assumptions, indent=2) + "\n", encoding="utf-8"
)
_command(
"raw_input_runner.py",
[
"--client-engagement",
prepared["client_engagement_path"],
"--assumptions-json",
str(assumptions_path),
"--output-subdirectory",
"reconciliation",
"--language",
request.get("language", "it"),
"--title",
request.get("title", "Riconciliazione partite"),
"--narrative",
request.get("narrative", ""),
],
output / "reconciliation-execution.log",
)
return finish_reconciliation(
client_id, engagement_id, run_id, state_dir=state_dir
)
except Exception as exc:
archive.fail_studio_client_workflow(
client_id, engagement_id, run_id, str(exc), state_dir=state_dir
)
raise
def main() -> int:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--request", required=True, type=Path)
parser.add_argument("--state-dir", type=Path)
parser.add_argument(
"--check-sources",
action="store_true",
help="Read-only source capability check; no client or engagement required.",
)
parser.add_argument(
"--finish-run", help="Resume delivery after ordinary review/regeneration."
)
parser.add_argument(
"--expected-predecessor-checkpoint",
help="Separately retained review checkpoint for a run created before automatic checkpoint retention.",
)
args = parser.parse_args()
request = _json(args.request)
if args.check_sources:
result = check_sources(request)
elif args.finish_run:
result = finish_reconciliation(
request["client_id"],
request["engagement_id"],
args.finish_run,
state_dir=args.state_dir,
expected_predecessor_checkpoint=args.expected_predecessor_checkpoint,
)
else:
result = reconcile(request, state_dir=args.state_dir)
print(json.dumps(result, ensure_ascii=False, indent=2))
return 0
if __name__ == "__main__":
raise SystemExit(main())
SHA-256: eb6ed11dbdb89786670db58a767204bbb7a5cc09d3594235f08bb46e1c9344fc