Deterministic_Clearing_Financial

Deterministic, audit-grade experimental pipeline for execution admissibility under delayed clearing.

The paper baseline/spec lives in overall_baseline.md.

Goals (why this exists)

• Determinism: identical config + seed + schedule ⇒ identical trace hash.
• Auditability: every ADMIT/PROHIBIT decision is replayable and explainable.
• No-hindsight: experiments are driven by serialized schedules and pre-registered configs.
• Operator-real semantics: event schema and baselines match exchange-edge realities (ack vs exec vs clearing, bust/correct, duplicates/resends).

Repo layout

• overall_baseline.md: paper spec + semantics + experiment matrix.
• src/dcp/: deterministic simulator and baseline implementations.
• configs/: run configs and experiment presets.
• schemas/: config schema(s).
• scripts/: helper scripts (run, verify).
• runs/: generated outputs (ignored by git).

Quickstart (Windows PowerShell)

Create a virtualenv and install deps:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .

Run an example experiment (creates a new run directory under runs/):

python -m dcp run --config configs/experiments/exp_a_delayed_clearing.yaml

Verify a run (recompute and compare trace hash):

python -m dcp verify --run runs\<RUN_ID>

Ingest / replay demo (drop-copy shaped log)

Convert a drop-copy-like JSONL log into a canonical schedule and run a fair suite (SUT + baselines) on it:

# 1) ingest external-ish log -> canonical schedule
python -m dcp ingest --input samples/dropcopy_sample.jsonl --output runs\tmp_ingest_schedule.jsonl

# 2) execute SUT + baselines on the ingested schedule (no schedule regeneration)
python -m dcp suite --config configs/preregistered/expA_delayed_clearing.yaml --out-root runs\ingest_demo --schedule-input runs\tmp_ingest_schedule.jsonl

Outputs (what to expect)

Each run directory contains:

• config.resolved.json: normalized config used for the run.
• schedule.jsonl: serialized schedule (protocol-legal) used for the run.
• schedule.sha256: deterministic hash over the schedule file.
• trace.jsonl: decision trace records.
• trace.sha256: deterministic hash over the trace file.
• metrics.json: summary metrics (violations, admit rate, latency stats, etc.).
• contract.json: audit-grade run manifest (environment + policy pointers + artifact hashes).

Status

This repo currently focuses on building top-tier experimental artifacts first (config, schedules, trace format, replay, hashing). The SUT logic can start simple and be refined without changing the artifact contract.

C++ proof point (optional)

If you want to demonstrate C++ competency and keep a clean port path, see cpp/ for a small utility (dcp_verify) that verifies trace.jsonl against trace.sha256 using a self-contained SHA-256 implementation.

Copyright © 2026 Zachary Larkin. All rights reserved.

This manuscript, including all text, figures, tables, experimental designs, methodologies, and derived results, is the original work of the author and is currently under preparation for submission to a peer-reviewed journal.

No part of this manuscript may be copied, distributed, reproduced, posted, translated, adapted, or incorporated into other works, whether in whole or in part, without the prior written consent of the author. This restriction applies to both academic and commercial use, including use in articles, preprints, theses, dissertations, coursework, presentations, or derivative research.

This document is shared solely for purposes of review, feedback, or evaluation. No license or right of use is granted, implied, or inferred.

Upon publication, copyright will remain with the author except as required by the publishing journal’s standard copyright or license agreement.