Chronos/DBWaitlist

Gateway

Rules, labels and masks

Which changes merge on their own and which wait for a person; how changes read in plain words; which columns agents never see.

Self-hostedChronos Gateway runs on your own servers today. Releases and install script. The engine under it: Chronos DB, self-hosted

How rules work

The rules are a merge policy: what a proposed change must keep to be written to your database without a person. The engine checks them inside each merge, on the rows it is about to write. A change within the rules merges. A change that breaks one is held and waits for a person to approve or reject it. Nothing is written while it waits.

  • The gateway keeps the rules’ text and makes the engine’s policy match it. It does not judge merges itself.
  • Every run’s agent is bound to the one policy, named by GATEWAY_POLICY (gateway by default).
  • A person’s approval merges a held change past the rules that held it. The row checks still run: each row the merge writes is locked and compared with the database first.
  • Rules judge the change. Labels and masks are separate: labels set how a change reads to a person, masks set what an agent reads.

This page describes gateway 0.4.4 on Chronos DB 0.6.2.

The default rules

GATEWAY_POLICY_RULES, by default
max_rows = 500, max_deletes = 0, rows_per_hour = 5000, max_age = '15 minutes', check_reads = true, require_scope = true

In plain words: a change is written without a person only if it deletes no rows, changes at most 500 rows, keeps its tenant under 5,000 changed rows an hour (counted across all its runs), was made within the last 15 minutes, every row it read still matches the database, and it declares its tenant (every gateway run does). Anything else is held.

Every other rule is unset by default. An unset limit is no limit, an unset list is empty, and an unset flag is false. So by default a schema change, or a merge that overwrites newer edits with a whole side, is held too.

Every rule

These are the rules PUT /v1/policy takes, in the order the console shows them. A limit is a whole number, 0 or more, or null for no limit. A time is text such as '15 minutes'. A list is names in one string, such as 'orders,items'. A flag is true or false.

Size of one change

RuleKindDefaultMeaning
max_rowslimit500Rows changed. More than this, and the change waits for a person.
max_deleteslimit0Rows deleted. 0 means every delete waits for a person.
confirm_deletes_overlimitunsetDeleting more than this needs the approver to type the count. A propose passes the count as confirm_deletes.

Per tenant, per hour

RuleKindDefaultMeaning
rows_per_hourlimit5000Rows changed an hour, across all of a tenant’s runs. A job split into many small runs still counts.
deletes_per_hourlimitunsetRows deleted an hour, per tenant.

Fresh data

RuleKindDefaultMeaning
max_agetime'15 minutes'The oldest a run may be. Its work rests on what it read then.
check_readsflagtrueHold the change if rows the agent read were changed in the database since. Only the run’s own tenant’s rows count.
rerun_readsflagfalseRe-run its reads first, and hold only if a read now gives something else.

What it may touch

RuleKindDefaultMeaning
tableslistunsetOnly these tables. Unset: any attached table.
review_tableslistunsetAlways review these tables: any change to them waits. 'payments'
review_columnslistunsetAlways review these columns, even for one row. 'users.email,accounts.owner'
require_scopeflagtrueRuns must say what they may change. The gateway gives each run its tenant.
overwriteflagfalseMay overwrite newer edits. False: a run never replaces what changed in the database since it began.
schemaflagfalseMay change the schema: tables, views, functions, types.
criticalflagfalseMay change critical columns: columns a reader marked critical.

Side effects

RuleKindDefaultMeaning
max_effectslimitunsetEffects one change may queue: emails, webhooks, payments sent once it lands.
effects_per_hourlimitunsetEffects an hour.
review_channelslistunsetAlways review these effect channels. 'payments,refunds'

Values in each row

RuleKindDefaultMeaning
row_rulestextunsetConditions each changed row must keep, or the change waits. 'payments: new.amount >= -50; prices: new.price <= old.price * 1.2'
max_nulledlimitunsetThe most values one change may set to empty.

All runs together, per hour

RuleKindDefaultMeaning
all_rows_per_hourlimitunsetRows changed an hour by every tenant’s runs together: a breaker if the agent goes wrong everywhere at once.
all_deletes_per_hourlimitunsetRows deleted an hour, all runs together.
all_effects_per_hourlimitunsetEffects an hour, all runs together.

Text from outside

RuleKindDefaultMeaning
untrusted_columnslistunsetColumns outsiders write: tickets, emails, web pages, where a prompt injection hides. 'tickets.body'. '*' makes every text column untrusted. Rows an agent writes after reading such text are tainted, and reading them counts as reading it.
untrusted_guardslistunsetTables that outside text may not steer. A run that read those columns needs a person to change these. Unset: any table.
trusted_columnslistunsetColumns only you write, left out of '*' and 'table.*' above: a status your app sets. 'tickets.status'

What a change leaves behind

RuleKindDefaultMeaning
watch_totalstextunsetQueries that give one number, run before and after each change. 'select sum(amount) from payments; select count(*) from orders'
max_shiftlimitunset (10)The most a watched total may move, in percent. A change that moves one further waits for a person. Unset: 10.
max_unusuallimitunsetA change this many times bigger than the runs’ usual size waits.

Landing slowly

RuleKindDefaultMeaning
canarylimitunsetA bigger change lands only this many rows first. The rest lands when it is merged again after the wait.
canary_waittimeunset (10 minutes)How long the canary sits in the database before the rest may land. Unset: 10 minutes.
effects_delaytimeunsetEmails, webhooks and payments a change queues wait this long after it lands. An undo meanwhile takes them back unsent.

Review

RuleKindDefaultMeaning
revieweran agent’s nameunsetAn agent that looks first: it approves, turns down, or passes the change to a person. The AI reviewer sets itself here.
review_everyflagfalseEvery merge goes to the reviewer first, even one within the rules.
spot_checklimitunsetA person sees one change in this many at random, even within the rules.
person_onlylistunsetThe holds the reviewer cannot approve past. Unset: deletes, schema changes, outside text, the all-runs limits, spot checks and watched totals. 'none': it may approve past any.

GET and PUT /v1/policy

Both take a developer key. Rules set with PUT are kept in the gateway’s store, applied to the engine at once, and win over GATEWAY_POLICY_RULES from then on.

GET /v1/policy
curl -s localhost:7400/v1/policy -H "Authorization: Bearer $KEY"
FieldMeaning
nameThe policy’s name (GATEWAY_POLICY).
rulesThe rules as an object. Null when the gateway cannot read the text.
textThe rules as the engine reads them: max_rows = 500, max_deletes = 0, ....
unreadableNull, or why the text could not be read. This happens only with rules set by hand in GATEWAY_POLICY_RULES.
sourceset (by PUT, or the console) or config (GATEWAY_POLICY_RULES).
engineThe policy as the engine holds it, or null while there is no engine or no such policy yet.
knownEvery rule’s name.
PUT /v1/policy
curl -s -X PUT localhost:7400/v1/policy -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \  -d '{"rules": {"max_rows": 100, "max_age": "30 minutes", "check_reads": true}}'
  • rules is the whole set. A rule left out ends: a limit becomes no limit and a flag becomes false. In the example above, max_deletes = 0 ends, so deletes would no longer wait for a person. Send every rule you want kept.
  • From 0.3.2 the answer says which rules ended, in ended: the names of the rules that were set before and this set left out, such as ["max_deletes", "require_scope", "rows_per_hour"] (in alphabetical order). It is [] when none ended.
  • A value of null, or an empty string, unsets a rule.
  • The engine must take the rules first. A rule it refuses changes nothing.
  • The answer is the same as GET, after the engine took the rules, plus ended.
  • The next merge is checked against the new rules. A run that is already held stays held.
400 whenThe message says
rules is not an objectthe rules are an object
a rule’s name is unknownmerge policies have no rule of that name, with the list of names
a limit is not a whole number, 0 or moreit is a whole number, 0 or more, or null for no limit
a flag is not true or falseit is true or false
a time, list, name or text is not a stringwhat it takes, with an example
a string has a control characterwhich rule has it
check_reads is turned on beside MySQL or MariaDB with an engine before 0.4.11upgrade the engine, then POST /v1/setup

Rules from configuration

SettingDefaultMeaning
GATEWAY_POLICYgatewayName of the merge policy runs keep to.
GATEWAY_POLICY_RULESthe six default rulesThe rules, as the engine’s text. It replaces the whole default list, until rules are set with PUT /v1/policy or in the console.

Rules from the setting are applied when you connect a database. To change them later, set the variable, restart the gateway, then apply it:

POST /v1/setup
curl -s -X POST localhost:7400/v1/setup -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{}'# {"ok": true, "policy": "gateway", "rules": "..."}

GET /v1/status also shows the policy’s name and the rules in force.

Rules per database

A gateway beside several databases keeps rules, labels and masks for each. A request names its database with the header X-Chronos-Source or ?source=. Without one it means the first database, default. A name that is not connected answers 404 no_source.

rules for the database connected as shop
curl -s -X PUT localhost:7400/v1/policy -H "Authorization: Bearer $KEY" -H 'X-Chronos-Source: shop' \  -H 'Content-Type: application/json' -d '{"rules": {"max_rows": 50, "max_deletes": 0, "check_reads": true}}'
  • This holds for /v1/policy, /v1/labels, /v1/masks, /v1/setup, /v1/status and /v1/refresh.
  • A run belongs to one database, and its merge is judged by that database’s rules.
  • GATEWAY_POLICY_RULES and the other start-up settings are read once for the gateway. The AI reviewer is the first database’s only.
  • MySQL and MariaDB: a run’s reads are checked against the database when the engine is 0.4.11 or later. The gateway asks the engine each time it applies the policy. With an older engine the default rules leave check_reads off, and PUT /v1/policy refuses to turn it on, since that engine would refuse every merge. After upgrading it, POST /v1/setup turns the check on. The rows a merge writes are locked and compared either way.

Rules a run adds

A run can add its own row_rules when it is made (POST /v1/runs). They hold on top of the policy’s and can only make it stricter. A row that breaks one is outside the run’s scope, so its merge is held.

POST /v1/runs
{"tenant": 42, "intent": "refund order 1181", "row_rules": "payments: new.amount <= 100"}

Held reasons

When a propose breaks a rule, the answer is 202 with the reasons, as the engine gives them: one for each rule the change broke.

POST /v1/runs/:id/propose, held
{"status": "held", "reasons": ["deletes 3 rows, more than 2"], "message": "..."}

The same reasons are shown wherever the held run is:

  • GET /v1/runs/:id in outcome, with the policy that held it and the world’s version it was held at.
  • GET /v1/runs/:id/changes as reasons.
  • The merge.held event: {run, reasons, end_user, world, version, policy, asked, owner, changes}.
  • The console’s Review page, under “Why it’s waiting”, and the approval widget’s GET /v1/approve.
  • A Slack message: “Waiting for approval”, the intent, how many changes, and “Held:” with the reasons.

A held change waits GATEWAY_HOLD_TTL (3 days by default), then expires. See Approvals.

Conflict policies

A conflict is not a rule broken. It means a row the run changed was also changed in the database, or in main, since the run’s world was forked. Nothing is written. A propose, or a person’s approval, says how to settle it, and the engine judges the settled merge under the rules like any merge.

SendSettles
"by_columns": trueA row where the two sides changed different columns combines. The safest; try it first.
"by_columns": true, "resolve": "ours"As above, and for a column both changed, the run’s value.
"by_columns": true, "resolve": "theirs"As above, and for a column both changed, main’s value.
"rows": {"orders/7": ...}Single rows: "ours", "theirs", "delete", or the row to keep as an object.
"resolve": "ours" or "theirs"Whole rows, overwriting the other side’s changes to other columns. Use it last.
"target": nRows settle against main as a preview of the merge saw it (the run’s MCP merge_preview).

The rule overwrite decides the last resort. With overwrite = false, the default, a merge that takes a whole side over newer edits is sent to a person. The console’s Review page offers the same five choices for a run in conflict.

Labels

Labels decide how a change reads in plain words, to a person approving it. They name each table’s rows, say which column titles a row, name the columns, and hide the columns a person should not see.

PUT /v1/labels
curl -s -X PUT localhost:7400/v1/labels -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \  -d '{"tables": {"leads": {"name": "lead", "title": "name", "columns": {"owner": "owner", "org_id": null}}}}'
KeyMeaningWithout it
nameWhat one row is called: lead.The table’s name with _ as spaces, made singular: leads to lead, companies to company.
pluralWhat several are called.name + s, or the table’s name.
titleThe column whose value names a row: “lead “Acme””.The row’s key: lead #7.
columnsEach column’s label, or null to hide it.The column’s name with _ as spaces.
  • With labels, a change reads “Change the owner of lead “Acme” from Bo to Ada”, “Remove lead “Hooli””, and a summary reads “3 leads changed, 1 lead removed”.
  • GET /v1/labels answers the labels; {"tables": {}} when none are set. PUT replaces them all and answers what it kept.
  • 400 when the body has no tables object, a table’s labels are not an object, a table has a key other than name, plural, title and columns, or a column maps to something other than text or null.
  • Beside MongoDB, labels name fields by path: "columns": {"address.city": "city"}.
  • With Chronos Cloud linked and sharing diffs, the columns your labels hide are left out of rows sent there.
  • Labels change words only. They do not change what an agent reads or what a merge may do.

Masks

A masked column is one agents never read as it is. The mask is the engine’s, set on its copy. Your database is never changed.

PUT /v1/masks
curl -s -X PUT localhost:7400/v1/masks -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \  -d '{"tables": {"customers": {"email": "hash", "phone": "partial", "notes": null}}}'
MaskAn agent reads
hashA keyed hash of each value. The same value gives the same hash, so the agent can still join and count on it.
partialThe last four characters.
formatA value of the same shape.
nullNULL. Send it as the text "null".
JSON nullUnmasks the column.
  • An agent reads a masked column masked wherever it reads it.
  • A column not named in a PUT keeps the mask it has.
  • GET /v1/masks reads the masks back from the engine: {"tables": {"customers": {"email": "hash"}}}. Tables with none are left out. The gateway keeps no list of its own.
  • Runs started after a mask is set read it. A run’s world keeps the table as it was when the run started.
  • 400 when a table is not attached, the table has no such column, or the mask is not one of hash, null, partial, format. Nothing is set then.
  • People see (masked) in place of a masked value in an undo’s preview. With Chronos Cloud linked and sharing diffs, masked columns read "masked" there.
  • The AI reviewer reads masked columns masked too.
  • The connection check lists, per table, columns whose names suggest values agents should not read (sensitive: email, phone, ssn, password, token, card, address and the like). It is a hint for what to mask.
  • Needs engine 0.4.4 or later.

The gateway’s own documents do not say how a merge treats a write to a masked column. Try a proposal on a table with a masked column on a staging copy before you rely on it.

The AI reviewer

Optional. Set GATEWAY_REVIEWER_URL and GATEWAY_REVIEWER_MODEL, and a model reads each held change before a person. It approves it (merged as it was held), rejects it, or passes it on. A person then sees only what the model rejected or passed, with the model’s reason beside the rules’ reasons. Unset, people decide every held change.

SettingDefaultMeaning
GATEWAY_REVIEWER_URLunsetAn OpenAI-compatible API’s base, such as https://api.openai.com/v1 or http://localhost:11434/v1 (Ollama). Plain http only to this machine, or without a key.
GATEWAY_REVIEWER_MODELunset, requiredThe model to ask. Hosted or open-weight.
GATEWAY_REVIEWER_KEYunsetIts API key, sent as a bearer token.
GATEWAY_REVIEWER_MODEL_2unsetA second model on the same API. Both must approve, at the confidence below, for a change to merge.
GATEWAY_REVIEWER_MIN_CONFIDENCE0.8From 0 to 1. An approval less sure than this goes to a person.
GATEWAY_REVIEWER_INSTRUCTIONSunsetYour rules for its decisions, in words. GATEWAY_REVIEWER_INSTRUCTIONS_FILE reads them from a file.
GATEWAY_REVIEWER_MAX_ROWS100The most changed rows it is shown.
GATEWAY_REVIEWER_COLUMNSunsetColumns whose text the model reads as it is: leads.name,leads.stage, leads.*, or *. Other text it sees only as a placeholder.
GATEWAY_REVIEWER_AGENTgateway_reviewerThe engine agent it decides as.

What the model cannot do

  • Its own engine agent. It decides as an engine agent that may only read and cannot unmask. The gateway makes it and names it as the policy’s reviewer.
  • Holds only a person may approve. By default the engine refuses its approval of a change held for deletes, schema changes, outside text, the all-runs limits, a spot check or a watched total. Those go to a person with the reason, and the model is not asked. The rule person_only sets which. So does a strict change (from 0.4.1: it sends payment, payout, transfer or refund effects), whatever person_only says.
  • Only what it was shown. A change written to after it was held is refused too.
  • No answer is never an approval. If the model fails three times, answers out of form, or is less sure than the minimum confidence, the change goes to a person.

What the model is sent

  • The run’s intent, why the change was held (with no values in it), and counts per table.
  • Up to GATEWAY_REVIEWER_MAX_ROWS changed rows, as its agent reads them. Numbers, true and false, empty values and one-word values (a status, a date, an email, an id) are shown as they are.
  • Text from columns in GATEWAY_REVIEWER_COLUMNS, cut to 300 characters. Any other text is a placeholder such as {"text": "#3", "chars": 214}; the same text gets the same placeholder within one review.
  • Columns in untrusted_columns are always placeholders, even when allowed, and masked columns stay masked.

The model is told that everything in the change is data, and to reject a change that tries to steer it. That lowers the risk of a prompt injection; it does not remove it. What bounds a wrong approval is the engine’s rules above. A hosted model receives what it is shown: to keep that in your network, use a model you run there.

Every decision is in the engine’s audit and in the merge.reviewed event: {run, world, version, verdict, reason, confidence, by: {reviewer, model}}, where verdict is approve, reject or pass. An approval also sends merge.landed with by: "reviewer". A run it rejects or passes stays held, with outcome.review saying so.

Rules made to pair with it: review_every, row_rules, all_rows_per_hour, untrusted_columns with trusted_columns, watch_totals with max_shift, canary with canary_wait, effects_delay, max_unusual and spot_check.

In the console

Policy

  • The merge policy as a form, grouped as on this page, with one sentence at the top that says what the rules mean in plain words. The sentence changes as you type.
  • It shows the policy’s name, whether the rules were set in the console or come from GATEWAY_POLICY_RULES, and whether they are in force in the engine.
  • Saving applies the rules to the engine at once. The next merge is checked against them.
  • Loosening a rule asks you first: raising or removing max_rows, max_deletes, rows_per_hour, deletes_per_hour or max_effects, or turning off check_reads or require_scope.
  • Rules the console cannot read (set by hand in GATEWAY_POLICY_RULES) are shown as text, with why. Saving replaces them.
  • With several databases, the picker chooses whose rules you are looking at.

Data and labels

  • Masked columns: every column of every attached table, with what agents read: the real value, a keyed hash, the last 4 characters, a value of the same shape, or NULL.
  • Labels: the labels as JSON, with a button that fills in a starting set from the attached tables. It hides id, columns ending in _id and tenant columns, and takes name, title, email, subject or label as a row’s title.

Next

Rules, labels and masks · Chronos