Chronos/DBWaitlist

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 UNIQUE or FOREIGN KEY constraint, or sets NOT 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 UNIQUE column references refuses to merge while main has added a row referencing it.
  • UNDO MERGE is checked as a merge is. It refuses to delete a parent that a row added since references; with SKIP CHANGED it 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 w past 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 RUN list 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:

SET MERGE AS DELTA
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 is 0A000.
  • 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 past MIN or MAX refuses 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 RUN shows such rows as combined delta.

FORECAST CONFLICTS

See clashes before anyone merges. Nothing changes.

FORECAST CONFLICTS
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. combinable when only delta columns overlap.
  • read-write: a row one world read (a world with check_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
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 p as it is and the children before it. Per row: applied, combined-delta, conflict or escrow-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 into p as one merge and the children are discarded. Returns CONSOLIDATE 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 bound 23514, a merge policy, a child written to meanwhile) discards the scratch, and p and 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 second CONSOLIDATE p while one runs.
  • After a crash between the final merge and the discards, the next open (or CONSOLIDATE p) discards the children whose rows are in p already, and a merge of one is refused (55000). Nothing merges twice.
  • Refused: a child with forks of its own (2BP01); a world in ONLY CHILDREN that is not p’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:

arbitrateThe 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
newestthe newer world
oldestthe older world
failno 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
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 a uri, the content’s sha256 (hex) and a note. The database adds an id, when, and who attached it (the agent, or person).
  • 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, decide, merge
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 merged

PROPOSE 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), conflicts or refused.
  • 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. WITHDRAW frees 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’s person_only. So, unlike REVIEW 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 merged in the merge’s own log record, beside its ledger row, so a crash can no longer leave it approved with 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_window of proposing it (15 minutes unless set). The reviewer and admin agents are refused (42501). Past the window it is expired (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. INTO another 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
explain merge world w;   -- section, item, detail: everything its merge would do, and why

One 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 and SHOW 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) or FOR 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 last retention row: 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 OUTCOMES counts 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

SettingMeaning
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.
arbitratepriority (the default), newest, oldest or fail: how CONSOLIDATE ... USING ARBITRATION settles a row two children both changed.
strict_channelsFrom 0.6.2. Effect channels that make a proposal strict, on top of payment*, payout*, transfer*, refund* and review_channels. Default: none.
strict_windowFrom 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
verify ledger;   -- seq, ok, detail: one row per entry
  • VERIFY LEDGER recomputes the chain and returns a row per entry: seq, ok, and detail for one that does not hold. It needs what VERIFY DATABASE needs: admin for an agent.
  • Operation ids. A merge given an operation id (the HTTP merge op’s operation) 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 gives 23505.
  • 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 opBodyReply
attach_evidencebranch, and kind, uri, sha256, note (or evidence: {kind, uri, sha256, note}){ok, evidence}
proposebranch, into{ok, proposal}
proposals{proposals}
decide_proposalid, verdict (approve or reject), reason{ok}
withdraw_proposalid{ok}
merge_proposalid{ok, merged}
merge…and operation: the caller’s id for this merge into mainas before

MCP adds the tools propose, attach_evidence and explain_merge.

Codes

SQLSTATEWhen
23514A delta column past its escrow bound.
23505An operation id given again with another way of settling rows.
40001A conflict; a certificate that changed since the proposal (changed since proposal); a strict proposal whose target was committed to since (superseded (strict_target)).
55000A 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).
55P03MERGE PROPOSAL of a world transferred away from its proposer.
42501An agent approving its own proposal or world, or any agent approving a strict one; rights taken away before MERGE PROPOSAL.
2BP01CONSOLIDATE with a child that has forks of its own.
22023A world in ONLY CHILDREN that is not a child; a strict proposal INTO a world other than its parent.
0A000SET MERGE AS DELTA on a column that is not a number.

Next

Merges: proposals and the ledger · Chronos