Git-backed Ledger Specification | GitHub Agentic Workflows
Skip to main content Git-backed Ledger Specification Version : 1.1 Status : Working Draft Editor : GitHub Agentic Workflows Team Abstract Section titled “Abstract” This specification defines bounded, deterministic, append-only JSONL ledgers with disposable query projections. It specifies standalone tools.ledger configuration, record identity, per-job responsibilities, built-in state models, concurrent reconstruction, compaction, retirement, configuration limits, the validated transactions consumed by trusted persistence, and the adversarial review of the feature.
1. Conformance and terminology Section titled “1. Conformance and terminology” The key words MUST , MUST NOT , REQUIRED , SHALL , SHALL NOT , SHOULD , and MAY in this document are to be interpreted as described in RFC 2119 and RFC 8174. Agent is the untrusted workflow process that reads a disposable projection and requests mutations through configured ledger safe-output tools. Record is one immutable version-1 JSON object.
Shard is a JSONL file containing immutable records. Projection is disposable SQLite state reconstructed from shards. Coverage declaration says that a replacement shard contains all records from one or more source shards. Stable shard is a closed shard not created by the current persistence run. Validated transactions are the versioned artifact of accepted ledger mutations produced by safe-output validation. Agent job is the workflow job that prepares read-only projections and runs the agent.
Persistence job is the trusted push_ledger_changes job that revalidates transactions, reconciles the latest ledger branch, and pushes durable records. Safe-outputs job is the trusted job that ingests and handles safe outputs. 2. Data model and integrity Section titled “2. Data model and integrity” An implementation MUST serialize each record as canonical JSON followed by one newline. A record MUST contain exactly version , id , type , timestamp , parents , payload , and sha . sha MUST be the SHA-256 digest of the canonical record with sha omitted.
Record IDs and shard IDs MUST use UUID version 4 syntax. Timestamps MUST be canonical UTC ISO 8601 strings. Parent hashes MUST be unique, sorted, and bounded. Readers MUST ignore malformed lines and report diagnostics without discarding valid records. A ledger MUST enforce configured record, shard, patch, and shard-count limits before acknowledging a mutation. File writes MUST use regular, non-symlink files, atomic publication where a new shard is created, and fsync for the file and containing directory.
3. Job responsibilities Section titled “3. Job responsibilities” Ledger work is split across jobs with different privileges. An implementation MUST NOT move a responsibility to a less trusted job. Job Trust Ledger responsibilities Credentials Agent job preparation Trusted Fetches canonical ledger history, validates records, and creates disposable read-only SQLite projections Repository read access Agent execution Untrusted Queries projections and queues mutations through the configured ledger safe-output tools; MUST NOT write canonical files No ledger-branch write token Safe-outputs job Trusted Validates requested mutations and emits the versioned transaction artifact; does not persist ledger records Safe-output tokens Persistence job Trusted Revalidates transactions, reconciles the latest ledger branch, commits and pushes accepted records.
It MUST NOT compact. Ledger-branch contents: write token Maintenance plan job Untrusted Per ledger: reads the ledger branch, uses built-in segment selection, and emits a compaction plan artifact contents: read only Maintenance apply job Trusted Per ledger: validates the hostile plan against the latest ledger state and atomically applies it contents: write ; never runs user JavaScript The agent job MUST NOT perform compaction, retirement, or persistence.
The safe-outputs job MUST NOT mutate ledger storage. An immediate safe-output response MUST NOT imply durability: an accepted request becomes durable only after the persistence job succeeds. The persistence job MUST treat transaction artifacts and restored ledger files as untrusted input and revalidate both. The persistence job MUST run only after the safe-outputs job succeeds. Skipped, failed, or cancelled safe outputs MUST NOT trigger persistence.
If downloading validated transactions fails, reconciliation MUST NOT run and the persistence job MUST fail rather than treating missing transactions as an empty batch. 4. Built-in behavior and script restrictions Section titled “4. Built-in behavior and script restrictions” Custom ledger replay and compaction scripts are not supported. Domain-specific constraints MUST be expressed as value schemas on supported built-in types.
4.1 Memory validation script Section titled “4.1 Memory validation script” repo-memory.validation.script runs after normalization and before commit. It MUST run in a separate Node process with a bounded timeout and a sanitized environment, and a non-zero exit MUST fail persistence (fail-closed), because it is a policy gate on what is about to be pushed. This separate file-storage validator is not a ledger replay or compaction extension point.
Removing custom ledger scripts MUST NOT disable it. 4.2 Built-in compaction selection Section titled “4.2 Built-in compaction selection” Compaction is owned by Agentic Maintenance (section 5.3), never by the agent or persistence job. The maintenance plan job MUST use the built-in deterministic segment-selection policy and MUST reject tools.ledger.<name>.compaction.script . Its output is a proposal: the trusted apply job independently revalidates the resulting plan.
Eligible segments MUST be considered in segment-ID order, with at most max-segments selected and their union bounded by max-segment-kb . Segments that do not fit MUST be skipped. Fewer than two selected segments MUST result in no compaction. 4.3 Built-in replay Section titled “4.3 Built-in replay” The only supported declared types are log , set , map , table , counter , and notes . Unknown types and any replay configuration MUST be rejected.
Type Supported operations Derived state columns log append(value) position , value set add(value) , remove(value) identity , value map put(key, value) , delete(key) key , value table insert(value) , update(key, patch) , upsert(value) , delete(key) key , value counter increment(name, amount) , decrement(name, amount) name , value notes note(subject, note, reason, citations) , vote(note_id, vote, reason?) notes , note_citations , note_votes , note_state Replay MUST apply canonical topological record order, breaking ties between simultaneously ready records by SHA-256 lexical order.
The state table MUST be disposable and read-only to the agent; canonical JSONL records remain authoritative. Invalid built-in operations MUST fail projection preparation, not silently fall back to generic records. Value schemas MUST validate values rather than operation envelopes. A table MUST declare a string primary-key field through key ; other types MUST NOT declare key . Table inserts MUST reject duplicate keys, updates MUST require an existing key and preserve the primary key, and upserts MUST replace the entire row.
Set membership MUST use canonical JSON equality. Counter amounts MUST be nonnegative safe integers, and resulting arithmetic MUST remain within the safe-integer range. Counters and notes MUST NOT accept value schemas. Notes MUST include at least one valid repository citation. Notes and votes MUST remain immutable records; the derived note_state view reports vote counts and timestamps, not truth or authority. Consumers MUST verify cited evidence against current repository state before relying on a note.
The map type exposes ledger_map_put and ledger_map_delete ; notes exposes ledger_note_add and ledger_note_vote . Other types use typed ledger_append operations. Ledgers without a declared type retain the generic records projecti
The rest of this page is on the live site.