0.4.3 pre-1.0

How ledger models and period locks work

Published 20 November 2026 · Tested with Evlet 0.4.3 on Python 3.13 · 9 min read

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:

apps/stock/models/stock.py
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 = True stores only an integer id and the declared columns. The model is left out of every HTTP route, generated screen and AI tool.
  • append_only = True makes 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.
  • timestamps and indexes are 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

Terminal
cd depot-project
evlet instance depot
evlet install stock --instance depot
evlet dev --instance depot

Add an item, create a receipt for 40 units dated 10 November and click Receive.

A receipt document in Evlet in the Received state, locked, with item, date and quantity.
The receipt after Receive. The document is locked and one movement is posted.

Check the ledger from the shell. This command reads one snapshot and is safe to run beside the server:

evlet ledger list --instance depot
Model      Table      Rows  Append only  Activity  Timestamps  Period
StockMove  stockmove  1     yes          off       created     on_date

Append only means the database says no

The rule is not only in Python. Open the SQLite file directly and try to change a row:

Python
import sqlite3

db = sqlite3.connect("instances/depot/data/database.sqlite3")
db.execute("update stockmove set qty = 1")
# sqlite3.IntegrityError: stockmove is append only

The 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.

The Periods page in Evlet Controls listing the Receipt model dated by received_on, with all records locked up to 31-10-2026 and the change in the log below.
Controls, Periods. Each lock change is written to the audit log.

Now try to create a receipt dated 15 October through the API:

HTTP 422
{
  "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 forUse a normal model for
High-volume rows that code writes: stock movements, account postings, points, meter readingsRecords people create and edit in screens
Rows that must never change after they are writtenRecords with states, actions or child tables
Balances kept as a cache beside the movementsAnything 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 @release and reverse in @release.exit, in one transaction.
  • append_only is 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.