← Files ClaraARCHIVED FILE
modules/studio-archive/scripts/input_verification.py
7.91 KB · Nov 21, 2026 · 00:11 UTC
"""Read-only verification of selected portable Archive inputs.
Receipt seals, IDs and byte hashes are mechanically verifiable. Document
meaning, version lineage and professional approval are deliberately not inferred.
"""
from __future__ import annotations
import re
from collections.abc import Mapping, Sequence
from datetime import datetime, timezone
from pathlib import Path
from typing import Any
import client_ledger as ledger
__all__ = ["verify_inputs"]
_INPUT_ID = re.compile(r"input_[0-9a-f]{24}")
_SHA256 = re.compile(r"[0-9a-f]{64}")
_MAX_SELECTION = 100
def _selection(
input_ids: Sequence[str],
expected_receipts: Sequence[Mapping[str, Any]] | None,
) -> tuple[list[str], dict[str, str] | None]:
if (
not isinstance(input_ids, (list, tuple))
or not 1 <= len(input_ids) <= _MAX_SELECTION
or any(
not isinstance(item, str) or _INPUT_ID.fullmatch(item) is None
for item in input_ids
)
or len(set(input_ids)) != len(input_ids)
):
raise ledger.LedgerError("Select 1 to 100 distinct exact input IDs.")
selected = list(input_ids)
if expected_receipts is None:
return selected, None
if not isinstance(expected_receipts, (list, tuple)):
raise ledger.LedgerError("Expected receipts must be an array.")
expected: dict[str, str] = {}
for item in expected_receipts:
if (
not isinstance(item, Mapping)
or set(item) != {"input_id", "content_sha256"}
or not isinstance(item["input_id"], str)
or item["input_id"] not in selected
or item["input_id"] in expected
or not isinstance(item["content_sha256"], str)
or _SHA256.fullmatch(item["content_sha256"]) is None
):
raise ledger.LedgerError(
"Expected receipts require one input_id and content_sha256 "
"copied from each selected input's prior receipt."
)
expected[item["input_id"]] = item["content_sha256"]
if set(expected) != set(selected):
raise ledger.LedgerError("Expected receipts must cover every selected input.")
return selected, expected
def verify_inputs(
client_root: Path,
client_id: str,
engagement_id: str,
input_ids: Sequence[str],
*,
expected_receipts: Sequence[Mapping[str, Any]] | None = None,
require_exact_input_set: bool = False,
) -> dict[str, Any]:
"""Verify selected receipt/byte identities without editing the client tree.
Optional prior receipt seals establish preservation against that supplied
baseline. Exact-set checking additionally reads all inputs in this engagement.
This is an observation at verification time, not a lock on future file changes.
"""
selected, expected = _selection(input_ids, expected_receipts)
if not isinstance(require_exact_input_set, bool):
raise ledger.LedgerError("require_exact_input_set must be boolean.")
client = ledger.load_client_manifest(client_root)
engagement = ledger.load_engagement_manifest(client_root, engagement_id)
if client["client_id"] != client_id or engagement["client_id"] != client_id:
raise ledger.LedgerError("Selected engagement belongs to another client.")
results: list[dict[str, Any]] = []
failures: list[dict[str, Any]] = []
for input_id in selected:
try:
receipt = ledger.load_input_receipt(client_root, engagement_id, input_id)
# Reuse the supported reader; raw receipt JSON intentionally omits
# hydrated paths. Recheck metadata after the complete byte read.
after = ledger.load_input_receipt(
client_root, engagement_id, input_id, verify_bytes=False
)
if after != receipt:
raise ledger.LedgerError("Input receipt changed during verification.")
except (ledger.LedgerError, OSError) as exc:
failure = {
"input_id": input_id,
"code": "input_verification_failed",
"message": str(exc),
}
failures.append(failure)
results.append(
{"input_id": input_id, "status": "failed", "failure": failure}
)
continue
baseline_matches = (
receipt["content_sha256"] == expected[input_id]
if expected is not None
else None
)
result = {
"input_id": input_id,
"status": "verified" if baseline_matches is not False else "failed",
"receipt_valid": True,
"controlled_bytes_match_receipt": True,
"expected_receipt_matches": baseline_matches,
"receipt": receipt,
}
if baseline_matches is False:
failure = {
"input_id": input_id,
"code": "expected_receipt_mismatch",
"message": "Current receipt differs from the supplied prior receipt.",
}
failures.append(failure)
result["failure"] = failure
results.append(result)
input_set_matches = None
current_input_ids = None
if require_exact_input_set:
try:
inventory = ledger.list_inputs(client_root, engagement_id)
current_input_ids = sorted(item["input_id"] for item in inventory)
input_set_matches = current_input_ids == sorted(selected)
# Revalidate selected receipt identities against the final listing.
earlier = {
item["input_id"]: item["receipt"]
for item in results
if "receipt" in item
}
if any(
item["input_id"] in earlier and item != earlier[item["input_id"]]
for item in inventory
):
raise ledger.LedgerError("Selected inputs changed during verification.")
if not input_set_matches:
failures.append(
{
"code": "input_set_mismatch",
"message": "Engagement inputs differ from the exact selected set.",
"missing_input_ids": sorted(
set(selected) - set(current_input_ids)
),
"additional_input_ids": sorted(
set(current_input_ids) - set(selected)
),
}
)
except (ledger.LedgerError, OSError) as exc:
input_set_matches = False
failures.append(
{"code": "input_inventory_verification_failed", "message": str(exc)}
)
if ledger.load_engagement_manifest(client_root, engagement_id) != engagement:
failures.append(
{
"code": "engagement_changed",
"message": "Engagement changed during verification.",
}
)
verified = not failures
return {
"schema_version": "vera.input_verification.v1",
"status": "verified" if verified else "blocked",
"verified": verified,
"checked_at": datetime.now(timezone.utc).isoformat(),
"client_id": client_id,
"engagement_id": engagement_id,
"engagement_status": engagement["status"],
"selected_input_count": len(selected),
"inputs": results,
"expected_receipts_checked": expected is not None,
"require_exact_input_set": require_exact_input_set,
"input_set_matches": input_set_matches,
"current_input_ids": current_input_ids,
"failures": failures,
"source_archive_mutated": False,
"document_contents_returned": False,
"not_checked": [
"external_originals",
"folder_delivery_tree",
"document_meaning_and_authored_lineage",
"historical_import_retry_outcome",
"workflow_outputs_and_readable_navigation",
"visual_and_professional_acceptance",
],
}
SHA-256: 00d4ac63e8ee22553b51c709f38c2917a088e0435961465a244503af5255ce8f