How ledger models and period locks work
Accounting and stock systems share one rule: what is posted does not change. You correct a mistake with a new entry, and once a period is closed nobody writes into it. Evlet has both ideas in the framework. This article builds a small stock ledger to show how they work.
The idea
There are two kinds of tables in a business app:
- Documents that people create and edit in forms: a receipt, an invoice, a transfer.
- Ledgers that hold the movements those documents cause. People never edit them. Only code writes them.
In Evlet a ledger is still a model, declared and migrated like any other, with ledger = True. It is stored lean and has no public surface: no forms, no API routes, no MCP tools.
The code
Create an app with evlet setup depot-project --app stock, remove the starter model and add this file:
from evlet import Date, Decimal, Link, Model, Rule, State, Text, release
ACCESS = {
"admin": Rule(("read", "create", "update", "delete")),
"editor": Rule(("read", "create", "update")),
"viewer": Rule(("read",)),
}
class Item(Model):
permissions = ACCESS
title = Text(required=True, max_length=120, label="Name")
class StockMove(Model):
item = Link(Item, required=True)
on_date = Date(required=True)
qty = Decimal(scale=2, required=True)
reason = Text(default="")
class Meta:
ledger = True # lean table, no forms, no API
append_only = True # the database refuses UPDATE and DELETE
timestamps = "created"
indexes = [("item", "on_date")]
period = "on_date" # closed periods apply to every writer
class Receipt(Model):
permissions = ACCESS
item = Link(Item, required=True)
received_on = Date(required=True)
qty = Decimal(scale=2, required=True, minimum=0)
docstate = State(
State.Step("draft", "Draft"),
State.Step("received", "Received", color="green", release=True),
State.Step("cancelled", "Cancelled", color="rose", final=True),
rules=(
State.Rule("draft", "received", "Receive"),
State.Rule("received", "cancelled", "Cancel", by=("admin",), remark="required"),
),
show="bar",
)
@release
def post(self):
self.context.session.create(
StockMove, item=self.item, on_date=self.received_on, qty=self.qty, reason="Receipt")
@release.exit
def reverse(self):
self.context.session.create(
StockMove, item=self.item, on_date=self.received_on, qty=-self.qty, reason="Receipt cancelled")
class Meta:
period = "received_on"
list_fields = ("item", "received_on", "qty", "docstate")The ledger model
StockMove has four fields and five settings:
ledger = Truestores only an integer id and the declared columns. The model is left out of every HTTP route, generated screen and AI tool.append_only = Truemakes the database itself refuse UPDATE and DELETE on the table.period = "on_date"places each row in a period by its date, so a lock date applies to it.timestampsandindexesare plain storage options.
The document that posts
Receipt is an ordinary document. Its received step has release=True. Entering a released step runs the @release hook, which writes the movement in the same transaction as the move. If anything fails, both roll back.
Leaving the released step runs @release.exit, which posts the opposite movement. The original row stays. Evlet refuses to create a model that declares @release without a matching exit while a rule can leave the released step, so a posting always has its reversal.
Run it
cd depot-project
evlet instance depot
evlet install stock --instance depot
evlet dev --instance depotAdd an item, create a receipt for 40 units dated 10 November and click Receive.

Check the ledger from the shell. This command reads one snapshot and is safe to run beside the server:
Model Table Rows Append only Activity Timestamps Period
StockMove stockmove 1 yes off created on_dateAppend only means the database says no
The rule is not only in Python. Open the SQLite file directly and try to change a row:
import sqlite3
db = sqlite3.connect("instances/depot/data/database.sqlite3")
db.execute("update stockmove set qty = 1")
# sqlite3.IntegrityError: stockmove is append onlyThe same happens for DELETE. Someone with direct file access could still remove the triggers, which is why records that need stronger evidence can also turn on a tamper-evident hash chain in their Activity.
You will also notice that the quantity is stored as the integer 4000 for 40.00. Evlet stores decimals as scaled integers, so sums are exact.
Close a period
An admin opens Controls, then Periods, picks a date and clicks Lock. Here every record dated on or before 31 October 2026 is closed.

Now try to create a receipt dated 15 October through the API:
{
"error": "Validation failed",
"fields": {
"received_on": "This date is in a closed period (locked up to 31-10-2026)"
}
}The lock is read inside the writing transaction and applies to every writer: the browser, the API, an AI tool, a job, and trusted Python such as the @release hook above. A draft receipt dated in the closed period cannot be received, because the movement it would post is dated in that period too.
Models can also lock per company or branch with Meta.period_scope, so one entity can close its books before another.
When to use a ledger model
| Use a ledger model for | Use a normal model for |
|---|---|
| High-volume rows that code writes: stock movements, account postings, points, meter readings | Records people create and edit in screens |
| Rows that must never change after they are written | Records with states, actions or child tables |
| Balances kept as a cache beside the movements | Anything an API or AI tool must reach directly |
The repository's ledger benchmark inserted 1,000,000 rows into an append-only ledger at about 49,000 rows per second on a laptop. See the ledger guide for batch inserts, transaction locks and a worked balance example.
Summary
- Documents post to ledgers in
@releaseand reverse in@release.exit, in one transaction. append_onlyis enforced by the database.- A period lock stops every writer, including your own code.
Next: build the invoicing app, or see everything in the framework.
Last updated . Checked against Evlet 0.4.3.