Skip to main content

​
Compliance Evidence Binder Spec

Status: LOCKED (Contract Only — No Implementation)
Purpose: Define enterprise ledger and hash version protocol before Phase 8S.

​
1. Ledger Record Contract: process_runs

This table is not yet implemented. This spec defines the contract for future Phase 8S work.

​
Primary Key

  • run_id (UUID)

​
Logical Idempotency Key

  • (tenant_id, period_label, batch_id)

​
Required Columns

Identity:
ColumnTypeNotes
tenant_idSTRINGTenant isolation
org_idSTRINGOrg scoping (nullable)
batch_idSTRINGBatch identifier
period_labelDATEYYYY-MM-01
run_idSTRINGUUID primary key
State:
ColumnTypeNotes
statusSTRINGRUNNING | SUCCEEDED | FAILED
created_atTIMESTAMPRecord creation
started_atTIMESTAMPRun start
completed_atTIMESTAMPRun completion
error_codeSTRINGIf FAILED
error_messageSTRINGSanitized; no PHI
Reproducibility:
ColumnTypeNotes
inputs_hashSTRINGREQUIRED; Hash Version Protocol
raw_hashSTRINGPhase 9 required
config_snapshot_hashSTRINGPhase 9 required
Snapshot Anchors:
ColumnTypeNotes
stage1_snapshot_refSTRINGReference to stage1 output
stage3_snapshot_refSTRINGReference to stage3 output
stage1_row_countINT64Row count
stage3_row_countINT64Row count
Audit:
ColumnTypeNotes
request_idSTRINGRequest correlation
trace_idSTRINGDistributed trace
actor_user_idSTRINGUser identifier
actor_emailSTRINGHashed if needed
DQ:
ColumnTypeNotes
dq_statusSTRINGNOT_RUN | PASS | FAIL
dq_results_jsonSTRINGDQ results

​
2. Hash Version Protocol (inputs_hash)

inputs_hash MUST include version for enterprise-grade reproducibility. 
hash_version = "IHv1"

​
Specification

inputs_hash is SHA256 over canonical_json of: 
{
  "hash_version": "IHv1",
  "tenant_id": "...",
  "period_label": "...",
  "batch_id": "...",
  "ingestion_template_id": "...",
  "mapped_header_contract": {...},
  "file_metadata": {...},
  "period_authority_config": {...},
  "config_snapshot_identifiers": {...}
}

​
Rules

  • canonical_json must sort keys deterministically.
  • hash_version MUST change if hashing logic changes.
  • Any change in canonicalization rules requires bumping hash_version.
  • Old runs remain immutable and interpretable.
This prevents:
  • Hash collision across algorithm changes
  • Drift between old and new canonicalization logic
  • Silent reproducibility breakage

​
3. Exactly-Once Semantics

Server must enforce:
ConditionBehavior
RUNNING existsPROCESS_ALREADY_RUNNING
SUCCEEDED + same inputs_hashReturn prior summary
Different inputs_hashCreate new run_id

​
4. Binder UI (Future)

Placeholder for future Compliance Evidence Binder UI structure. Not implemented.