History and time travel

Any moment, exactly as it was. Gnomon keeps the history of every table you track, so you can read the whole database as it stood at any moment, with the queries you already have, and get the same answer every time. When an agent makes a decision, you can see exactly what it saw.

-- The open invoices at the end of October
select gnomon.use('main', '2026-10-31 23:59');
select sum(amount) from invoices where status = 'open';

select gnomon.use('main');   -- back to now

Nothing about the query changes: same tables, same joins, same views. Only the moment changes.

Naming a momentCopy Anchor Link

A coordinate is exact and replayable; a timestamp is as precise as your heartbeat. Capture one with select gnomon.coordinate_text() and the same read comes back identically, however much has changed since. This is what lets you see exactly what an agent saw.

For one transaction, or behind a pooler, gnomon.begin('main', '2026-10-31 23:59') does the same thing without leaving the session in the past. The past is read-only; writes are refused.

Where a value came fromCopy Anchor Link

select * from gnomon.history('orders', '{"id": 4182}');   -- every version of one row
select * from gnomon.blame('orders', '{"id": 4182}');     -- per field: who last changed it, when and why
select * from gnomon.log();                               -- commits, merges and undos, newest first

Blame answers the question people actually ask: not just when the status became refunded, but which agent did it, in which run and for what reason.

Find the change that broke itCopy Anchor Link

When a check that used to pass starts failing, Gnomon finds the transaction that broke it. It runs the check on the database as it was halfway between the last good moment and now, then halves what's left, until one transaction remains:

gnomon bisect refund_within_total --good '2026-11-12 08:00'

It reports the transaction, who made it, when and why.

UndoCopy Anchor Link

select gnomon.undo_merge(7);                       -- a whole merge
select gnomon.undo(xid);                           -- one transaction
select gnomon.undo_role('gnomon_agent_support_bot', since => '2026-11-13 09:00');

Undo goes through the merge engine, so it puts back exactly the fields that changed. If something written since would be overwritten, it refuses with 40001 rather than guessing. To put a table back as it was at a moment, gnomon.revert('orders', '2026-11-13 15:00').

Valid timeCopy Anchor Link

Some tables need two clocks: when a fact was recorded, and when it was true. Track a table as bitemporal and Gnomon keeps both:

select gnomon.track('price', mode => 'bitemporal');
set gnomon.valid_at = '2026-06-01';   -- prices as they stood in June

Corrections rewrite what was true then without losing what you believed before, and a change dated in the future lands when it comes due.

Keeping history in handCopy Anchor Link

Operations → · The change feed →