Chronos/DBWaitlist

Chronos DB, self-hosted

Worlds for long tasks

Expiry at use, nesting limits, rights on one world, handing a world over, budgets, durable worlds, pinned checkpoints, RESUME and AT WORLD. Next release.

Self-hostedChronos DB is one binary you run yourself. Releases and install script. To put agents on a database you already run, with approvals: Chronos Gateway

Which release

A world is an instant, isolated copy of the database that an agent works in and merges back. The first world shows the basics. This page is about worlds that live a long time: an agent working for hours, handing work to helpers, coming back after a restart. Everything here is SQL, run on the Postgres port or in the shell.

Expiry, at use

a world’s time
alter world agent_7 set ttl '1 hour';   -- capped at its parent's; its forks' shortened to italter world agent_7 reset ttl;          -- never expires (agents need admin for either)
  • Read-only the moment its time is up. A write, MERGE WORLD from it or into it, MERGE ... INTO, a fork of it, and a COMMIT of a transaction that wrote in it are refused with 55000. Before, only the background sweeper (every 30 s) ended a world, so it took writes until then.
  • Reads keep working until the sweeper discards it, read-only transactions included. The sweeper discards it with every world forked from it, and the transactions open in them, the deepest first.
  • A fork never outlives its parent. Its expiry is capped at the parent’s when it is forked (an agent’s world_ttl too) and whenever its TTL is set or reset. Shortening a parent’s TTL shortens its forks’ that would outlive it; lengthening it leaves theirs as they are.

How deep, how many

nesting limits
alter system set max_depth = 4;      -- forks between a world and main, at most (0: no limit)alter system set max_children = 50;  -- live forks of one world, at most (main's are counted by max_worlds)create agent bot with (can = 'read,fork,write_own', max_depth = 2, max_children = 10);  -- per agent too
  • Depth: a world forked from main is 1 deep. A fork past max_depth is refused with 54000.
  • Children: max_children counts the live forks of one world. Main’s forks are counted by max_worlds instead.
  • Both are database settings (ALTER SYSTEM) and agent settings. A transaction’s own world counts toward neither.

Rights on one world

An agent may change its own worlds. To let another agent help with one, grant it rights on that world alone:

GRANT and REVOKE ON WORLD
grant write, merge on world agent_7 to helper until '2026-12-01 09:00+00';  -- READ, WRITE, MERGE, FORKrevoke write on world agent_7 from helper;
  • What they cover: READ, WRITE, MERGE and FORK in w and every world forked from it, besides the agent’s own rights. Never in main: a grant on main is refused, and merging into main still needs write_main.
  • MERGE is the right to merge the world. Merging a fork of w into w takes MERGE and WRITE on w.
  • Who may grant: only rights the grantor holds on w. What it holds only by a grant it hands on for no longer than its own lasts. The database’s own users and admins grant any.
  • UNTIL: a grant past it counts for nothing.
  • Who may revoke: w’s owner, the grantor, or an admin. Revoking does not take back what the grantee granted on.
  • Where they are kept: in the world’s metadata (_sonos_grants). Both statements are in SHOW SECURITY AUDIT.

Handing a world over

TRANSFER WORLD
transfer world agent_7 to reviewer_bot;   -- world, owner, epoch
  • Who: w’s owner or an admin. The new owner must be able to change the worlds it owns (write_own), be of the world’s tenant if the world is held to one, and have room under its max_worlds.
  • The lease epoch (_sonos_epoch, 0 for a world never transferred) moves on by one.
  • The old owner is fenced. Its writes and merges of the world get 55P03 (lease lost), whatever rights it has, until the world is transferred back to it.
  • Attached to a database, the world is written back as its new owner’s role (pg_role).
  • Audited, as grants are.

Budgets

a world’s budget
create world trial with (budget_rows = 10000, budget_statements = 500);alter world trial set (budget_rows = 20000);   -- the database's own users and admins only
  • budget_rows counts table rows written, not index entries. budget_statements counts writes: each statement that changes rows, each HTTP put or batch.
  • They count as it happens, in the world and every world forked from it, transactions included whether they commit or not. Past the budget the statement is refused with 53400 and writes nothing.
  • A fork’s budget is at most what its parent, and each world above it, has left (53400 if more).
  • Kept in memory. After a restart the counts start again from zero.

Durable worlds

Writes to a world other than main are normally kept in memory and logged in batches, so a crash can lose them and flags the world (see What is durable, and when). A durable world waits for the disk as main does:

a durable world
create world task_9 with (durable, check_reads = true);alter world task_9 set (durable = true);   -- or turn it on later
  • Each write it acknowledges is on disk first, in the same group fsync as main’s; so are merges into it, its rebases and its metadata. A crash loses none, so the world is not flagged at the next open and its merge needs no version.
  • Turning it on puts the writes it held in memory on disk first.
  • Its read set too. A durable world that checks its reads logs what it read at the end of each statement that read something new, before the answer goes out. After a crash its merge is checked as usual instead of held for reads the database lost.
  • synchronous_commit = off waits for nothing, main included.

Pinned checkpoints and rollback

checkpoints
checkpoint world task_9 as step3 pin '1 day';   -- kept for a day, past history_retentioncheckpoint world task_9 as step3;               -- taken again without PIN: the pin goes, the label names the newer momentrollback world task_9 to checkpoint step3;      -- back to it (RESTORE WORLD ... TO CHECKPOINT does the same)
  • PIN '<interval>' keeps the world as it is now (its tree’s pages) until the pin runs out, whatever history_retention drops.
  • Without PIN, a checkpoint is a moment in history, gone with it.
  • A label taken again replaces it, with PIN or without.
  • On disk only: a database kept in memory refuses a pin (0A000).

Where a world is: SHOW WORLD STATE and RESUME

An agent coming back to a world, after a restart or from another process, asks where it stands:

SHOW WORLD STATE and RESUME
show world state task_9;                     -- world, version, epoch, durable, flagged, check_reads, stale_reads, parent_changes, tokenresume world task_9 token 'w1a2b...:12:0';   -- the same, once the token still holds
ColumnWhat it says
versionWrites since the fork. A merge into the world that changes it (a child’s, a partial merge, a transaction’s commit) moves it on too.
epochHow many times the world was transferred.
durable, flagged, check_readsAs set; flagged after a crash lost writes.
stale_readsWhat the world read that changed in its parent since (a world that checks its reads).
parent_changesHow many rows its parent changed since its fork point.
token<world id>:<version>:<epoch>: what to hand to RESUME next time.

RESUME WORLD w TOKEN answers as SHOW WORLD STATE when nothing moved. A write or a merge into the world since gives 40001; another epoch (the world was handed to another holder) 55P03; another world’s token or a malformed one 22023. Without TOKEN it is SHOW WORLD STATE.

Reading another world: AT WORLD

cross-world reads
-- another world's table, in the same query as this world's (read only)select a.sku, a.price as before, b.price as afterfrom prices a join prices at world pricing_17 b using (sku)where a.price <> b.price;select * from prices at world 'pricing_17@-1 hour';   -- a world as it was
  • AT WORLD w after a table in FROM, before or after its alias, reads that table as w has it now: its rows and its definition there. 'name@when' reads it as it was. Several worlds can be joined in one query.
  • Read only. UPDATE, DELETE and INSERT refuse a target AT WORLD (0A000). A write may read another world in its FROM or USING.
  • Rights hold there too. An agent needs the right to read each world it names (42501); another session’s transaction is no one else’s. Row security, an agent’s tenant and masked columns apply to the other world’s table as to its own.
  • Not in the read set. What is read there goes in no world’s read set.
  • Every world of a set: AT WORLDS OF SET s. See World sets.

Codes

SQLSTATEWhen
55000A write, merge, fork or commit in a world whose time is up.
54000A fork past max_depth or max_children.
53400A write past a world’s budget, or a fork’s budget above what its parent has left.
55P03The old owner of a transferred world writes or merges it; a RESUME token of another epoch.
40001A RESUME token whose version moved on.
22023A RESUME token of another world, or malformed.
0A000A pinned checkpoint in memory; a write to a table AT WORLD.
42501A grant on main; reading a world the agent may not read.

Next

Worlds for long tasks · Chronos