sqlite-task-ledger

A lightweight SQLite-backed task lifecycle ledger for agents, schedulers, workers, and other long-running workflows.

It focuses on a small but practical core:

• append-only status events
• validated task-state transitions
• single terminal-state enforcement
• task snapshot maintenance
• delivery dedupe / cooldown checks
• stale-task queries for watchdogs and heartbeats

Why this exists

A lot of workflow systems need more than simple logs. They need a place to answer questions like:

• What is the current state of task X?
• Did this task already reach a terminal state?
• Is this worker still running or has it gone stale?
• Should I suppress duplicate delivery for this status update?

This project packages that pattern into a small, framework-agnostic module.

Included

• src/sqlite_task_ledger/ledger.py — core ledger implementation
• schema/status_schema.sql — SQLite schema
• examples/basic_usage.py — minimal end-to-end usage
• tests/test_ledger_smoke.py — basic smoke test

What it is good for

• AI/agent task tracking
• scheduler job state tracking
• long-running workflow status reporting
• watchdog / heartbeat recovery
• message dedupe and cooldown handling

Quick example

from pathlib import Path
from sqlite_task_ledger import Ledger, StatusEvent

ledger = Ledger("status_ledger.db")
ledger.init_schema(Path("schema/status_schema.sql").read_text())

ledger.write_event(StatusEvent(
    state="RECEIVED",
    actor="worker-1",
    source="demo",
    req="task_001",
))

ledger.write_event(StatusEvent(
    state="RUNNING",
    actor="worker-1",
    source="demo",
    req="task_001",
    stage="collecting inputs",
))

Design notes

The project intentionally separates:

• event history (task_events)
• latest snapshot (task_state_snapshot)
• delivery records (delivery_log)

That makes it easy to support both:

• append-only audit history
• fast “what is the current state?” lookups

Not included

This public version does not include any product-specific adapters, chat routing logic, or environment-bound constants.

License

MIT