Chronos DB, self-hosted
Merges: proposals and the ledger
Constraints checked at merge, delta columns, CONSOLIDATE, evidence, proposals and approvals, EXPLAIN MERGE, provenance and the hash-chained ledger. 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 merge lands a world’s changes in its parent. This page is what a merge checks before it lands, the ways several worlds’ changes combine, how an agent asks for a merge and a person approves it, and what every merge into main leaves behind. The basics, DIFF, MERGE WORLD and conflicts, are in A first world and the HTTP API.
Constraints checked at merge
A world sees main as it was at its fork. Main may have changed since. A merge now checks the constraints it brings against main’s rows as they are:
- A new constraint covers the whole table. A world that adds a
UNIQUEorFOREIGN KEYconstraint, or setsNOT NULL, has the whole table checked when it merges. A duplicate, an orphan or a null that main added meanwhile refuses the merge. Merged, the new constraint’s index rows cover main’s rows too. - A parent can’t go out from under a new child. A world that deletes a row, or changes a value, that a foreign key to a
UNIQUEcolumn references refuses to merge while main has added a row referencing it. UNDO MERGEis checked as a merge is. It refuses to delete a parent that a row added since references; withSKIP CHANGEDit leaves that parent.- Recovery never runs these checks. A log holding a merge they would now refuse opens to the same state.
VERIFY DATABASE lists rows that break a constraint in any world: see Backups and restore.
Merges keep to a world’s line
MERGE WORLD g INTO wpast g’s parent refuses rows the parent changed and never merged there: g’s rows carried the parent’s change along.- An agent may merge a world only into its parent or a world forked from it. It may not merge part of a world (
ONLY TABLES,ONLY KEYS,INTO) while worlds are forked from it. A person may. - A diff and
MERGE ... DRY RUNlist grants, owners, rules and casts, which merged before without being shown.
Delta columns
Several worlds forked from one coordinator often change the same number in ways that combine: two agents each take 5 from a stock count. Declare such a column, and a merge adds the change instead of conflicting:
alter table inventory alter column qty set merge as delta; -- parent + (ours - base)alter table inventory alter column qty set merge as delta escrow (min 0); -- refused past a boundalter table inventory alter column qty set merge as delta escrow (min 0, max 500);alter table inventory alter column qty set merge as default; -- whole rows again- Number columns only:
smallint,int,bigint,numeric,float. Any other is0A000. - When it combines: both sides of a merge changed a delta column of one row, and no other column both changed (nor, without
BY COLUMNS, other columns on both sides). The merge keeps the parent’s value plus the world’s change. An insert or a delete of the row still conflicts. ESCROW: a combined value pastMINorMAXrefuses the merge (23514), naming the row and the column. Nothing merges.- Part of the table’s definition: it forks, and merges with the definition.
DRY RUNshows such rows ascombined delta.
FORECAST CONFLICTS
See clashes before anyone merges. Nothing changes.
forecast conflicts; -- world_a, world_b, kind, table, key, combinableforecast conflicts for world agent_7; -- agent_7's siblings, and its parent's changes since its fork- Pairs: each pair of live worlds with one parent, and each world against what its parent changed since its fork.
write-write: a row both changed.combinablewhen only delta columns overlap.read-write: a row one world read (a world withcheck_reads = true) and the other changed.- Rights: without
FOR WORLD, an agent needs the right to list every world.
CONSOLIDATE
Merge every child of a coordinator into it as one merge, all or nothing:
consolidate preview plan; -- world, table, key, outcome, detail: nothing changesconsolidate plan; -- every live child of plan, merged into it as one; then discardedconsolidate plan only children (agent_7, agent_9); -- those; the others stayconsolidate plan using arbitration; -- rows two children both changed: settled by the policy's arbitrate rule- Preview: the children in the order they were forked, each merged in memory onto
pas it is and the children before it. Per row:applied,combined-delta,conflictorescrow-violation. - How it runs: each child is merged, in fork order, into a scratch fork of
p(_consolidate_p). When all went through, the scratch merges intopas one merge and the children are discarded. ReturnsCONSOLIDATE n, the children merged. Merge policies judge each child’s merge and the final one. - All or nothing: any refusal (a conflict
40001, an escrow bound23514, a merge policy, a child written to meanwhile) discards the scratch, andpand every child stay as they were. - The children are held from before they are copied until they are discarded: a write to one, a fork of one, or a merge of one or into one (a transaction’s commit) is refused with
55000, so nothing written then is lost with them. So is a secondCONSOLIDATE pwhile one runs. - After a crash between the final merge and the discards, the next open (or
CONSOLIDATE p) discards the children whose rows are inpalready, and a merge of one is refused (55000). Nothing merges twice. - Refused: a child with forks of its own (
2BP01); a world inONLY CHILDRENthat is notp’s child (22023); an expired child (55000).
USING ARBITRATION
A row two children both changed (not one the parent changed since) goes to one of them by the acting agent’s merge policy’s arbitrate setting:
| arbitrate | The row goes to |
|---|---|
| priority (the default) | the child whose owner has the higher agent priority, which only an admin sets; on a tie, the older world |
| newest | the newer world |
| oldest | the older world |
| fail | no one: refused, as without USING ARBITRATION |
Each settled row is recorded in p’s metadata, _sonos_arbitration: key, winner_world, loser_world, loser_value_hash (BLAKE3 of the losing row as stored), rule and at. The last 200 are kept.
Evidence
Keep what a change rests on with its world: a ticket, an order snapshot, a document.
attach evidence to world w (kind = 'ticket', uri = 'https://tickets.example/42', sha256 = 'ab12...', note = 'asked');- Fields: a
kind(required: policies ask for kinds), and optionally auri, the content’ssha256(hex) and anote. The database adds an id, when, and who attached it (the agent, orperson). - Kept in the world’s metadata,
_sonos_evidence, which only the database writes. The content stays where the URI points: store hashes and links, not personal data. - Rights: the right to change the world. Refused (
55000) once its merge is proposed, until the proposal is rejected or withdrawn, and after it merged.
Proposals and approvals
A proposal is an agent asking for a merge, bound to exactly what would merge. A person (or a reviewer) approves that, and nothing else.
propose merge world w; -- id, world, target, proposer, status, verdict, reasons, certificate, ...propose merge world w into staging;show proposals;approve proposal 'p1a2b3c4d5e6f7a8b' reason 'refunds checked against the tickets';reject proposal 'p1a2b3c4d5e6f7a8b' reason 'needs the order snapshot';withdraw proposal 'p1a2b3c4d5e6f7a8b';merge proposal 'p1a2b3c4d5e6f7a8b'; -- MERGE PROPOSAL n: rows mergedPROPOSE MERGE WORLD
- A certificate: BLAKE3 over the canonical JSON of the digest of every row the world changed (sorted by key, before and after, the database’s own rows too: grants, outbox entries, index entries), its read set (a world that keeps one), its fork point, the evidence, its declared scope, and the merge policy it would merge under, by name and the BLAKE3 of the policy’s row.
- A verdict: a dry run judged as the proposing agent’s merge:
passes,held(the policy would send it to a review, with the reasons),conflictsorrefused. - The world is fixed while the proposal is open or approved: an agent’s writes to it, forks of it and merges of it outside the proposal are refused (
55000,proposal open). - Rights: the right to merge the world. A person may propose an agent’s world: it merges as its owner.
- Kept on main, at
_sonos_proposals/<id>.
APPROVE and REJECT
- Who: a person (the session’s user is kept with the approval), the proposing agent’s merge policy’s
reviewer, or an admin agent. Never the agent that proposed it or owns the world (42501). - An approval names the certificate. It is derived again first; one that differs (the world written to, the evidence, the scope or the policy changed) is refused (
40001). - A rejection frees the world and leaves a tombstone.
WITHDRAWfrees it too.
MERGE PROPOSAL
- Derives the certificate again (
40001,changed since proposal, if it differs) and merges as the proposing agent, at the version proposed. - With the agent’s rights as they are then. Rights taken away since give
42501; a world transferred away from it has lost its lease (55P03). Only the proposal’s own hold on the world is lifted. - The merge policy judges it again, for exactly the rows proposed, checked again under the merge’s locks, with the rules the approval covers lifted. A person’s approval covers every rule but merge checks, reads that changed since the fork, and
require_evidence. A reviewer’s covers the rules not in its policy’sperson_only. So, unlikeREVIEW WORLD ... APPROVE(which merges as a person), a reviewer’s approval of a merge that deletes rows does not merge it: it waits for a person. - In the audit as the agent’s merge. A proposal merged into main is marked
mergedin the merge’s own log record, beside its ledger row, so a crash can no longer leave itapprovedwith its world gone. A merge into another world still marks it just after.
Strict proposals
From 0.6.2. A proposal is strict when its world queues an effect on a strict channel: one whose name starts with payment, payout, transfer or refund, or one in the policy’s review_channels or strict_channels. A policy adds strict channels and can’t take the built-in ones away. SHOW PROPOSALS says so in strict and strict_until.
- Only a person approves it, within the policy’s
strict_windowof proposing it (15 minutes unless set). The reviewer and admin agents are refused (42501). Past the window it isexpired(55000): propose again. - A commit to its target since proposing supersedes it, even one to a table it doesn’t touch, at its approval or its merge (
40001,superseded (strict_target)), and nothing is sent. So a payment never goes out against a state nobody approved. On a busy main a strict proposal waits for a quiet moment. In an attached folder, a refresh is such a commit. - It merges whole into its parent.
INTOanother world is refused (22023). - The window is the server’s clock: a clock that jumps expires a proposal early or late.
EXPLAIN MERGE
explain merge world w; -- section, item, detail: everything its merge would do, and whyOne answer: the certificate a proposal made now would carry, rows per table, each conflict, what would block it, the merge policy’s verdict (as its owner’s merge) with each reason, what reads the columns it changes (as DIFF ... READERS), the effects it would queue (NOTIFY ON MERGE), its evidence and its scope. Nothing changes. From 0.6.2 a strict line (the strict channels, the window) says when a proposal of the merge would be strict, so a caller can tell before proposing.
Decision provenance and tombstones
show decision provenance for merge 'p1a2b3c4d5e6f7a8b'; -- step, at, by, detailshow decision provenance for world w;show tombstones; -- agents' worlds that didn't make itshow tombstones for agent bot;- Provenance
FOR MERGE 'id'(a proposal’s id) orFOR WORLD w(its latest proposal, or the world as it is when none was made): the proposal, certificate, verdict, evidence, scope, run keys (run_id, ...), the policy and its hash, each approval and rejection, the merge, what agents did in the world (SHOW AUDIT’s steps), and a lastretentionrow: steps older than the history window may be missing. - A tombstone stays on main (
_sonos_tombstones/...) when an agent’s world is discarded, a merge of it is refused (conflicts, changed reads, merge checks), or its proposal is rejected: the world, owner, kind, run, parent, when it was made, depth, a digest and counts of what it changed (not the rows), and why. SHOW MERGE OUTCOMEScounts how each world ended; tombstones keep the ones that did not merge.- Rights: an agent may list its own tombstones; every agent’s needs
admin.
New merge policy settings
| Setting | Meaning |
|---|---|
| require_evidence | 'ticket,order_snapshot': holds an agent’s merge that carries no evidence of one of those kinds (carries no evidence of kind ticket). No approval lifts it: attach the evidence, and merge again. |
| arbitrate | priority (the default), newest, oldest or fail: how CONSOLIDATE ... USING ARBITRATION settles a row two children both changed. |
| strict_channels | From 0.6.2. Effect channels that make a proposal strict, on top of payment*, payout*, transfer*, refund* and review_channels. Default: none. |
| strict_window | From 0.6.2. How long after a strict proposal a person may approve it ('10 minutes'). Default: 15 minutes. |
SHOW MERGE POLICIES shows each setting, strict_channels and strict_window among them.
The merge ledger
Every merge into main writes a ledger row, _sonos_ledger/<seq>, in the same log record as its data: who merged what, under which policy and the hash of its row, the rows and deletes, and a digest. Each row holds the hash of the one before, so the rows form a chain.
verify ledger; -- seq, ok, detail: one row per entryVERIFY LEDGERrecomputes the chain and returns a row per entry:seq,ok, anddetailfor one that does not hold. It needs whatVERIFY DATABASEneeds:adminfor an agent.- Operation ids. A merge given an operation id (the HTTP
mergeop’soperation) records it. Asked again with the same id and the same request, it returns the first result; the same id with another request is refused. The id is bound to how the merge settles rows too: another pick gives23505. - In memory, no ledger. A database kept in memory has no log, and so no ledger.
- Merges are logged as what they did. A world merge, partial merge or rebase writes one log record holding every row it set (data after relayout, index entries, outbox rows as delayed), the merged world’s fate and a BLAKE3 digest. Opening the database writes those rows again and judges nothing, so recovery no longer depends on merge rules that may have changed since.
Over HTTP and MCP
| HTTP op | Body | Reply |
|---|---|---|
| attach_evidence | branch, and kind, uri, sha256, note (or evidence: {kind, uri, sha256, note}) | {ok, evidence} |
| propose | branch, into | {ok, proposal} |
| proposals | {proposals} | |
| decide_proposal | id, verdict (approve or reject), reason | {ok} |
| withdraw_proposal | id | {ok} |
| merge_proposal | id | {ok, merged} |
| merge | …and operation: the caller’s id for this merge into main | as before |
MCP adds the tools propose, attach_evidence and explain_merge.
Codes
| SQLSTATE | When |
|---|---|
| 23514 | A delta column past its escrow bound. |
| 23505 | An operation id given again with another way of settling rows. |
| 40001 | A conflict; a certificate that changed since the proposal (changed since proposal); a strict proposal whose target was committed to since (superseded (strict_target)). |
| 55000 | A write, fork or merge of a world while its proposal is open; evidence attached to a proposed world; a child held by CONSOLIDATE; a strict proposal past its window (expired). |
| 55P03 | MERGE PROPOSAL of a world transferred away from its proposer. |
| 42501 | An agent approving its own proposal or world, or any agent approving a strict one; rights taken away before MERGE PROPOSAL. |
| 2BP01 | CONSOLIDATE with a child that has forks of its own. |
| 22023 | A world in ONLY CHILDREN that is not a child; a strict proposal INTO a world other than its parent. |
| 0A000 | SET MERGE AS DELTA on a column that is not a number. |