SOTER Fact Simulator & Ledger — Developer & Operator Guide

Audience

Developers, maintainers, and system operators who need to install, build, extend, or run verification tests on the SOTER Fact Simulator and Cryptographic Ledger framework (soter_sim).

Goal

Set up a working development environment, understand the ledger's cryptographic mechanics well enough to extend it safely, add or tune simulation scenarios, and validate changes with the test suite.

Prerequisites

• A Python interpreter and the venv module.
• A local checkout of the SOTER repository.
• Editable install of the package with the dev extras group (pip install -e ".[dev]").

Workflow

1. Create and activate a Python virtual environment, then install SOTER in editable mode with the dev extras.
2. Review the ledger's dual-mode architecture and hash verification formula before touching ledger or auditor code.
3. Extend or tune simulation scenarios by editing the anomalies: block of a Logos-native .scenario file in scenarios/.
4. Run the verification test suite — the full suite, targeted modules, or with coverage — before considering a change complete.

1. Development Environment Setup

To begin extending SOTER or running the simulation pipeline locally, set up a Python virtual environment and install dependencies in editable mode. See Commands for the exact steps.

2. Ledger Architecture & Cryptographic Mechanics

SOTER uses a dual-mode ledger model built for auditability and transparency:

1. Primary Database Storage (SQLite):
2. High performance for runtime querying and transaction processing.
3. Leverages canonical database constraints to maintain historical data consistency.
4. Plain-Text File-System Mirror (Thin Ledger):
5. Visual, plaintext .ledger (hash chain metadata) and .fact (business payload) files are synchronized live during execution.
6. Designed for easy developer inspections, visual grep audits, and education.

For each block entry in the ledger, the entry hash is computed as:

$$\text{Entry Hash} = \text{SHA256}(\text{seq} \mathbin{\Vert} \text{fact_id} \mathbin{\Vert} \text{fact_hash} \mathbin{\Vert} \text{recorded_at} \mathbin{\Vert} \text{prev_hash})$$

This forms a cryptographic hashchain where any tampering with a single historical fact invalidates all subsequent block hashes.

3. Extending Simulation Scenarios

Developers can customize simulation behavior by editing or introducing scenarios in the scenarios/ directory. Specific business rule violations or technical anomalies are injected by adjusting the rates in the anomalies: block of a Logos-native .scenario file:

• missing_event: Skips a step in the defined normal_flow.
• duplicate_event: Appends an identical duplicate event immediately after the original.
• out_of_order_event: Swaps the chronological order of two contiguous steps.
• wrong_actor: Assigns an invalid actor role to execute a specific event.
• late_event: Introduces significant delay between the physical occurrence (occurred_at) and registry log recording (recorded_at).
• tamper_attempt: Generates inconsistent block pointers or mismatched hashes to test detector sensitivity.

4. Running Verification Test Suites

Developers must validate any codebase changes against SOTER's unit and integration tests: the full suite, targeted modules such as the compiler pipeline or fact verification loader, and coverage across SOTER modules. See Commands for the exact invocations.

Commands

# 1. Establish python environment
python -m venv .venv
source .venv/bin/activate

# 2. Install SOTER in development mode with test packages
pip install -e ".[dev]"

# 3. Run all tests
pytest

# 4. Run specific modules
pytest tests/unit/pipeline/test_loader.py
pytest tests/unit/test_multitenancy.py

# 5. Run code coverage
pytest --cov=modules tests/

Expected Result

The virtual environment activates cleanly and soter is importable from the editable install. The full pytest run completes with no failing tests. Targeted module runs (test_loader.py, test_multitenancy.py) pass in isolation, and the coverage run reports results for all SOTER modules without collection errors.

Troubleshooting

pip install -e ".[dev]" fails or soter cannot be imported

Cause:

• The dev extras group was not installed, or the virtual environment was not activated before installing.

Fix:

• Re-activate the virtual environment (source .venv/bin/activate) and re-run pip install -e ".[dev]" exactly as documented.

Hashchain verification fails after a manual ledger edit

Cause:

• Any change to a historical fact_hash, recorded_at, or prev_hash value breaks the SHA256 hashchain from that block forward — this is by design, matching the tamper_attempt anomaly.

Fix:

• Do not hand-edit .ledger files. Regenerate the ledger from the simulator, or add a tamper_attempt case to a scenario and confirm the auditor reports the expected integrity violation instead of editing data by hand.

Injected anomalies are not detected by tests

Cause:

• The anomaly rate in the scenario's anomalies: block may be too low to trigger within a small test run, or the targeted test module does not cover the anomaly type under test.

Fix:

• Temporarily raise the relevant anomaly rate (e.g. tamper_attempt) in the scenario file, or run pytest tests/unit/pipeline/test_loader.py directly to confirm detector sensitivity for that anomaly type.

Related Documents

• DocumentationStyleGuide.md - writing profile and document-type rules.
• GuideTemplate.md - guide document template.
• ManualsIndex.md - guide and manual index.
• CookbooksIndex.md - cookbook index.
• CookbookSimulatorUser.md - user and analyst companion guide.
• FactSimulatorArchitectureSpec.md - implementation-level architecture, canonicalization, and verifier specification.
• ArchitectureOverview.md - technical architecture context.