> > > SpecAkashaLedgerTechnicalSpec

Akasha Ledger Technical Spec

Purpose

Akasha is the append-only factual ledger layer for the SOTER ecosystem.

SOTER interprets, verifies, reconciles, and projects facts against organizational models. Akasha records factual testimony and preserves an auditable history that SOTER can later interpret.

The architectural distinction is:

Akasha = independent layer for durable, ordered, verifiable fact history
SOTER  = model, interpretation, verification, reconciliation, and projection

The ledger should be independent for the same reason Git is independent from the source code it tracks:

Git != source code
Git = history protocol for source code

Akasha != SOTER
Akasha = history protocol for organizational facts

SOTER should not own truth. It should be one of the systems that writes to, reads from, and reasons over a lower factual layer. Akasha should be treated as a protocol and semantic contract first, and as a storage implementation second.

Scope

This specification defines:

the protocol-level split of responsibilities between Akasha and SOTER;
the minimal canonical fact format;
the MVP and target backend architecture;
the validation boundary between technical integrity (Akasha) and organizational meaning (SOTER);
ingestion classification and receipts;
the minimal CLI surface;
the version and repository-extraction plan for the ledger.

Non-Goals

Akasha v0 must not become:

a custom distributed database;
a blockchain;
a general-purpose query engine;
a replacement for PostgreSQL or SQLite;
the whole SOTER runtime;
a semantic interpreter of organizational truth.

Akasha stores and verifies factual testimony. SOTER interprets that testimony.

Terminology

Term	Meaning
`fact`	A single append-only record of testimony, identified by `id`.
`stream`	The named sequence a fact belongs to (e.g. `seos.project.cost`).
`sequence`	The fact's ordinal position within its stream.
`occurred_at`	Bitemporal field: when the event is said to have happened.
`recorded_at`	Bitemporal field: when the fact was recorded in the system.
`previous_hash`	Hash of the prior fact in the chain; enables hash-chain verification.
`hash`	Canonical hash of the current fact.
`corrects`	Reference(s) to an existing fact this fact corrects.
`causation_id` / `correlation_id`	Identifiers linking related facts across a causal or correlated chain.
`evidence`	Reference(s) to supporting material (files, documents) backing a fact.
Domain fact	A fact accepted as organizationally meaningful testimony.
Operational fact	An ingestion event recorded without becoming a domain fact.
Receipt	Durable acknowledgment returned to a sender for a submission.

Model or Contract

Responsibilities

Akasha owns:

fact IDs
stream ordering
occurred_at and recorded_at
observer/source metadata
payload envelope
evidence references
causation and correlation IDs
correction references
sequence numbers
previous-hash links
fact hashes
optional signatures
append-only storage rules
verification of hash-chain integrity
import/export of factual logs

SOTER owns:

Logos models
organizational ontology
semantic validation
process and capability interpretation
dissonance detection
Providence Loop and Evolution Loop behavior
reconciliation proposals
visual and document projections
UI and workflow around detected divergence

Backend Technology Landscape

Several mature technologies overlap with parts of Akasha, but none should define the first version:

Technology	Strength	Fit for Akasha	Use Now?
File + SQLite	Simple, inspectable, portable	Very good for MVP	Yes
PostgreSQL append-only tables	Mature transactional storage	Good production backend	Later
EventStoreDB / KurrentDB	Event sourcing, replay, projections	Useful reference or optional backend	Optional
Datomic	Immutable facts and time-aware queries	Philosophically aligned, stack mismatch	No for MVP
immudb	Tamper-evident database	Possible proof-heavy backend	Later
Google Trillian	Verifiable transparency log	Strong for Merkle proofs	Later
Blockchain	Distributed consensus	Misaligned for local MVP	No

The practical conclusion:

Akasha protocol and semantics: build internally.
Akasha storage engine: use mature components through adapters.

MVP Architecture

Akasha v0.1 should be deliberately small:

canonical .fact.yaml or .fact.jsonl log
SQLite index/projection
append-only write path
hash-chain verification
bitemporal fields
correction references
CLI command named ledger
verify, export, and import
integration point for SOTER verifier

Do not build custom storage infrastructure beyond what is needed for local files and SQLite indexing.

Target Architecture

                SOTER
     verifier / reconciler / Logos
                  ^
                  | Akasha API
                  v
          Akasha Protocol Layer
    fact schema / bitemporality / correction
    hash chain / proof / append rules
                  ^
                  | backend adapter
                  v
  +---------------+---------------+---------------+
  | file+SQLite   | PostgreSQL    | immudb        |
  | local/dev     | production    | proof-heavy   |
  +---------------+---------------+---------------+
                  |
             future: Trillian

Ingestion Classes

Akasha should distinguish:

received payload
saved raw payload
rejected oversized payload
invalid framing
invalid encoding
invalid syntax
valid envelope but invalid hash chain
accepted domain fact
accepted operational fact
rejected with receipt

The sender should receive a durable receipt with a submission ID, timestamp, raw hash when possible, and current status.

CLI Surface

Minimal CLI surface:

ledger init
ledger append path/to/fact.yaml
ledger verify
ledger status
ledger export
ledger import
ledger receipt <submission_id>

Later versions can add:

ledger serve
ledger replay
ledger project
ledger anchor
ledger sign

Rules

Follow "save first, interpret later": submitted testimony should be recorded or rejected through an explicit, auditable boundary. This does not mean accepting unlimited garbage.
An uninterpretable input can become an operational ingestion event without becoming a domain fact.
Do not build custom storage infrastructure beyond what is needed for local files and SQLite indexing in the MVP.
Use the name "Akasha" carefully in public-facing material. In technical documentation, always pair the name with a concrete description, e.g. "Akasha, the append-only fact ledger protocol."

Examples

Minimal fact format:

id: fact_01J...
stream: seos.project.cost
type: cost.registered

occurred_at: "2026-05-30T10:15:00+02:00"
recorded_at: "2026-05-30T10:15:08+02:00"

observer:
  system: seos
  actor_id: user_...

subject:
  id: employee_...
  role: accountant

action:
  id: RegisterCost
  model_ref: soter://models/project_cost#RegisterCost

objects:
  - id: project_...
    role: context
  - id: cost_...
    role: output
  - id: document_...
    role: evidence

payload:
  amount: 123.45
  currency: PLN
  category: hosting

evidence:
  - type: file
    uri: sha256:...

causation_id: null
correlation_id: corr_...
corrects: []

sequence: 42
previous_hash: "..."
hash: "..."
signature: null

Validation

Akasha validates technical integrity:

the fact has required fields
timestamps are parseable
stream and sequence rules are satisfied
previous_hash points to the expected prior fact
hash matches the canonical representation
corrects references an existing fact when required
signatures are valid when enabled
the append-only invariant is preserved

Akasha does not decide whether RegisterCost is valid in the organizational model.

SOTER validates semantic and organizational meaning:

RegisterCost exists in the Logos model
the performer is a valid subject
required evidence exists
outputs match the declared process
policy allows or rejects missing fields
the fact creates, resolves, or modifies dissonance
the model should be amended

This separation keeps the ledger stable even when SOTER's ontology evolves.

Compatibility

Version Plan

Akasha v0.1

local CLI
canonical fact schema
file-based canonical log
SQLite index
hash chain
verification command
proof-lite receipts
SOTER integration

Akasha v0.2

PostgreSQL backend
HTTP/API server
ingestion from SEOS and SELECT
replay and projections
operational dashboards

Akasha v0.3

optional immudb or Trillian backend
Merkle proofs
external anchoring
signatures
multi-writer governance

Repository Boundary

Akasha can start inside the SOTER repository as a logically separate module. Extraction to a separate repository makes sense after the protocol, schema, and CLI stabilize.

Recommended path:

Define Akasha inside SOTER.
Stabilize the fact schema and verification rules.
Add a standalone ledger CLI.
Use SOTER as the first client.
Extract to a separate repository when external clients become plausible.

Final Decision

Akasha should be independent from SOTER at the conceptual and protocol level. For the MVP, build the protocol, schema, CLI, file log, SQLite index, and hash-chain verification in the SOTER repository. Avoid custom databases and avoid binding the concept to any single storage product.

Open Questions

When does the protocol, schema, and CLI count as "stable enough" to trigger extraction to a separate repository?
Should Akasha v0.3 adopt immudb, Google Trillian, both as pluggable adapters, or neither, for the proof-heavy backend?
What signature scheme and multi-writer governance model will v0.3 use?