ADR-006: Extract Ledger Protocol as an Independent Fact Kernel

Status

Accepted

Context

The SOTER ledger proof of concept lives inside the SOTER repository as modules/ledger.

That implementation proves the concept, but keeping fact-journal mechanics tightly coupled to the model translator and ontological analyzer violates single responsibility. It also prevents external systems, such as SEOS and SELECT, from using the fact log independently.

Decision

Extract fact-writing logic into a separate protocol layer under the working name Ledger Protocol.

SOTER remains a verifier and reconciler over accepted ledger records. It does not own the generic append-only fact protocol.

Rationale

Existing systems such as EventStoreDB, Datomic, and immudb overlap with parts of the need, but they do not define SOTER's exact contract:

• strict separation of occurred_at and system-owned recorded_at,
• hash-chain or Merkle semantics aligned with SOTER facts,
• save-first behavior where syntactically valid events are recorded before later interpretation.

The extracted layer should define a minimal protocol and allow file, SQLite, PostgreSQL, or transparency-log backends.

Consequences

Positive

• SEOS and SELECT can submit JSON events without depending on SOTER internals.
• SOTER's core becomes cleaner.
• Ledger commands can be simpler and auditor-facing.

Negative

• A new package or repository must be maintained.
• SOTER's verification loop must adapt to the extracted protocol.
• Migration from the proof of concept requires careful data handling.

Neutral or Operational

• The protocol separates business time from system time.
• recorded_at is owned by the ledger clock at durable append time.
• SOTER reads sealed records through a CLI, API, or SDK.

Alternatives Considered

Keep Ledger Inside SOTER

Rejected because it couples generic fact recording to SOTER-specific interpretation.

Adopt an Existing Event Store Directly

Rejected for the core protocol because existing products do not define SOTER's full semantic contract. They may still be used as storage backends.

Migration or Adoption

The existing proof-of-concept module should become the first implementation of the extracted protocol. External clients should integrate through the protocol, not through SOTER internals.

Related Documents

• DocumentationStyleGuide.md
• writing profile and document-type rules.
• AdrTemplate.md - ADR document template.
• AdrIndex.md - architecture decision record index.
• AkashaLedgerOverview.md - ledger documentation entry point.