SOTER Fact Simulator & Ledger — User Guide & Cookbook

Audience

Business analysts, system operators, and other users who want to model organizational behaviors, inject simulated anomalies, and run cryptographic audits with the SOTER Fact Simulator and Cryptographic Ledger (soter_sim).

Goal

Configure, execute, and audit a simulation run: generate mock organizational facts, write them to a secure ledger, and verify or audit them for anomalies.

Prerequisites

• Access to the soter CLI (soter simulator, soter-ledger, soter auditor).
• A Logos-native .scenario file — either a built-in scenario under scenarios/ or a custom one following the schema in Workflow.
• A writable output directory for the ledger (e.g. ledger/<org>/).

Workflow

1. Understand the three components you will operate: the simulator, the ledger, and the auditor.
2. Know the two file formats you will inspect while auditing: Fact Payload (*.fact) and Ledger Block Pointer (*.ledger).
3. Pick a built-in scenario or write a custom Logos-native .scenario describing the organization, process flow, and anomaly rates.
4. Establish a new ledger for the organization.
5. Run the simulator against that ledger.
6. Audit the ledger for cryptographic integrity and process conformance.
7. Generate a conformance report and interpret the results.

1. Components

SOTER is a runtime where every transaction, state transition, and organizational decision is treated as a historical fact. The simulator generates mock operations, writes them to a secure ledger, and checks them for anomalies:

• soter simulator (Fact Generator): Replays realistic process paths based on Logos-native .scenario files, generating data for multi-actor workflows.
• soter-ledger (Secure Journal): An append-only log backing SOTER events. SOTER operates in a dual-mode ledger architecture: a high-performance SQLite database as its primary operational ledger engine, and a visual, plain-text file-system format (.ledger and .fact files) maintained synchronously for educational illustration, visual inspection, and easy debugging (Thin Ledger design).
• soter auditor (Verifier & Auditor): A deterministic audit utility verifying hash integrity, sequence chains, and event-flow conformance on both DB indexes and FS directories.

2. File Formats

You will interact directly with two file formats when auditing SOTER systems.

Fact Payload (*.fact)

Business-centric data representing the actual occurrence. It is decoupled from any cryptographic details:

soter v1

element f-00000001
    type: Fact
    subtype: Interaction
    org: demo-jobbot
    case: candidate-0001
    occurred_at: 2026-04-30T12:00:00Z
    trigger: CandidateSubmittedCV
    actor: Candidate_0001
    consume: []
    produce: [CV_0001]
    source: simulator

Fact files support multiple business subtypes:

• Interaction (action by a human or system actor)
• Signal (asynchronous event trigger)
• Declaration (legal or state declaration)
• Correction (explicit modification of a historical fact referencing corrects:)
• LogicalCompensation (logical rollback of a previous action)

Ledger Block Pointers (*.ledger)

The immutable block index kept by the secure engine, referencing the fact hash and sequencing:

soter v1

element a-00000001
    type: LedgerEntry
    seq: 1
    fact_id: f-00000001
    fact_hash: h-8f828a2a89c93a0c5c3e03...
    recorded_at: 2026-04-30T12:00:03Z
    prev_hash: null
    hash: h-ffb4c59a3f2b8d9c2a8c17...

3. Configuring or Choosing a Scenario

Simulations are configured via declarative Logos-native .scenario files. Unlike the old YAML schema, these files leverage standard Logos indentation-based block syntax and support:

• Present Tense Actions: Simulation actions must use present-tense verbs (e.g., CandidateSubmitCV), distinguishing them from the past-tense Fact events that are recorded in the ledger (e.g., CandidateSubmittedCV).
• Declarative Step Numbering: Each step in the flow is explicitly indexed (e.g., - [1] CandidateSubmitCV) to ensure line-order independence.

Deterministic Scenario Example

soter v1

org demo-jobbot
    type: recruitment_agency
    actors:
        Candidate: 100
        Recruiter: 5
        ParserSystem: 1

scenario jobbot_recruitment
    case_prefix: candidate
    flow:
        - [1] CandidateSubmitCV
        - [2] CVParsed
        - [3] CandidateScore
        - [4] OfferMatch
        - [5] RecruiterReview

    actions:
        CandidateSubmitCV:
            actor: Candidate
            consume: []
            produce: [CV]

        CVParsed:
            actor: ParserSystem
            consume: [CV]
            produce: [ParsedCV]

        CandidateScore:
            actor: ScoringSystem
            consume: [ParsedCV]
            produce: [ScoreCard]

        OfferMatch:
            actor: ScoringSystem
            consume: [ScoreCard]
            produce: [MatchResult]

        RecruiterReview:
            actor: Recruiter
            consume: [MatchResult]
            produce: [ReviewDecision]

    timing:
        min_delay: 5
        max_delay: 600
        max_lag: 120

    anomalies:
        missing_event: 0.01
        duplicate_event: 0.005
        out_of_order_event: 0.005
        wrong_actor: 0.005
        late_event: 0.01
        tamper_attempt: 0.001

Probabilistic Scenario Example

Probabilistic scenarios define alternative paths or gateways with branching weights:

soter v1

org demo-jobbot
    type: recruitment_agency
    actors:
        Candidate: 100
        Recruiter: 5
        ParserSystem: 1

scenario jobbot_recruitment_probabilistic
    case_prefix: candidate
    flow:
        - [1] CandidateSubmitCV
        - [2] CVParsed
        - [3] CandidateScore
        - [4] gateway u-gateway-01
              branch1: [5] OfferMatch (weight: 0.7)
              branch2: [5] ApplicationReject (weight: 0.3)
        - [6] RecruiterReview

    actions:
        CandidateSubmitCV:
            actor: Candidate
            consume: []
            produce: [CV]

        CVParsed:
            actor: ParserSystem
            consume: [CV]
            produce: [ParsedCV]

        CandidateScore:
            actor: ScoringSystem
            consume: [ParsedCV]
            produce: [ScoreCard]

        OfferMatch:
            actor: ScoringSystem
            consume: [ScoreCard]
            produce: [MatchResult]

        ApplicationReject:
            actor: ParserSystem
            consume: [ScoreCard]
            produce: [RejectionNotice]

        RecruiterReview:
            actor: Recruiter
            consume: [MatchResult, RejectionNotice]
            produce: [ReviewDecision]

    timing:
        min_delay: 5
        max_delay: 600
        max_lag: 120

    anomalies:
        missing_event: 0.01
        duplicate_event: 0.005
        out_of_order_event: 0.005
        wrong_actor: 0.005
        late_event: 0.01
        tamper_attempt: 0.001

The simulator includes three reference scenarios reflecting standard organizational environments:

• Recruitment Agency (scenarios/jobbot_recruitment.scenario): models candidate vetting, automated resume parsing, AI scoring, and interview scheduling. CandidateSubmitCV ──> CVParsed ──> CandidateScore ──> OfferMatch ──> RecruiterReview ──> CandidateContact ──> InterviewSchedule
• Administrative Decision (scenarios/municipality_decision.scenario): models formal municipal case registration, document audits, reviews, and decision approvals. ApplicationSubmit ──> FormalCheckStart ──> FormalCheckComplete [──> MissingDocumentsRequest ──> DocumentsReceive] ──> DecisionPrepare ──> DecisionApprove ──> DecisionSend
• Warehouse Fulfillment (scenarios/warehouse_order.scenario): models physical resource reservations, packing, shipping dispatch, and financial billing. OrderReceive ──> MaterialReserve ──> WorkStart ──> QualityCheckPerform ──> ItemPack ──> ItemShip ──> InvoiceIssue

4-7. Establishing, Running, Auditing, and Reporting

Steps 4 through 7 — establishing a ledger, running the simulator, auditing the ledger, and generating a conformance report — use the CLI commands in Commands, in that order.

Commands

# 4. Establish a new ledger for the organization
soter ledger --establish --out ledger/demo-jobbot --org demo-jobbot --checkpoint-interval 100

# 5. Run the simulator against the established ledger
soter simulator --news \
  --scenario scenarios/jobbot_recruitment.scenario \
  --cases 50 \
  --anomaly-rate 0.05 \
  --ledger ledger/demo-jobbot

# 6. Audit the ledger: cryptographic integrity and sequence chains
soter auditor --ledger ledger/demo-jobbot

# 7. Generate an AI-optimized conformance report
soter auditor --report --ledger ledger/demo-jobbot --out reports/jobbot-report.json

Expected Result

After running the workflow, ledger/demo-jobbot contains the SQLite ledger database and its synchronized .fact / .ledger mirror files for every simulated case. soter auditor prints a structured JSON verification report:

{
  "ledger": "ledger/demo-jobbot",
  "valid_integrity": true,
  "valid_merkle": true,
  "facts_count": 350,
  "cases_count": 50,
  "violations": [
    {
      "type": "missing_event",
      "case": "candidate-0007",
      "expected": "CVParsed",
      "severity": "high"
    }
  ]
}

The --report run additionally writes an AI-optimized conformance report to the requested output path, comparing observed and expected flows per case:

{
  "summary": {
    "org": "demo-jobbot",
    "cases": 50,
    "facts": 350,
    "violations_count": 1
  },
  "top_violations": [
    {
      "type": "missing_event",
      "description": "Missing CVParsed before CandidateScored",
      "case": "candidate-0007"
    }
  ],
  "cases": [
    {
      "case": "candidate-0007",
      "expected_flow": ["CandidateSubmittedCV", "CVParsed", "CandidateScored"],
      "observed_flow": ["CandidateSubmittedCV", "CandidateScored"],
      "violations": ["missing_event"]
    }
  ]
}

A valid_integrity and valid_merkle value of true with an empty violations list indicates a clean run; any entries in violations name the anomaly type, the affected case, and its severity.

Troubleshooting

valid_integrity or valid_merkle is false

Cause:

• The scenario's anomalies: block has a non-zero tamper_attempt rate, or the ledger's .fact / .ledger files were edited outside the simulator, breaking the SHA256 hashchain.

Fix:

• Re-run with --anomaly-rate 0 (or a scenario with tamper_attempt: 0) for a clean baseline, and confirm no ledger files were hand-edited.

violations list contains unexpected entries

Cause:

• The scenario's anomalies: block injects missing_event, duplicate_event, out_of_order_event, wrong_actor, or late_event anomalies at the configured rate — this is expected simulator behavior, not necessarily a bug.

Fix:

• Cross-reference each violation's type against the anomaly definitions in Configuring or Choosing a Scenario, and lower the corresponding rate in the scenario file if the anomaly is unwanted for a given run.

Simulator or auditor cannot find the ledger directory

Cause:

• soter simulator or soter auditor was pointed at a --ledger path that was never created with soter ledger --establish.

Fix:

• Run soter ledger --establish --out <path> --org <org> first, then reuse the same <path> for --ledger in later commands.

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.
• CookbookSimulatorDev.md - developer and operator companion guide.
• FactSimulatorArchitectureSpec.md - implementation-level architecture, canonicalization, and verifier specification.
• ArchitectureOverview.md - technical architecture context.