Skip to content

Commit 25e6684

Browse files
authored
docs: add first-principles guide for evaluating data systems (#745)
Add docs/dev/systems.md, a framework for evaluating data systems as an observable contract implemented by physical mechanisms optimized for an expected distribution of work, with worked boundary tests and a reusable evaluation record. Point the AGENTS.md engineering rules at it: validate assumptions about Lance internals against upstream source, and reason about OmniGraph from first principles rather than in database categories. The deny-list drops the custom WAL/transaction-manager clause, which invariant 1 in docs/dev/invariants.md already owns.
1 parent 8281807 commit 25e6684

2 files changed

Lines changed: 636 additions & 4 deletions

File tree

‎AGENTS.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,9 @@ The decision lens is ongoing liability: ask what a design looks like after five
8686
more changes of the same kind. Prefer one source of truth with cheap derived
8787
views. Correctness outranks simplicity, which outranks performance. Demand more
8888
evidence for irreversible format, protocol, and substrate decisions.
89+
Always validate your assumptions and don't assume a certain function/modules/symbol will work in a certain way. Especially always validate your assumptions about Lance internals by reading the implementations in the upstream code.
90+
Reason from first principles about OmniGraph instead of in arbitrary database categories.
91+
Fundamentally, a database is **an observable contract, implemented by physical mechanisms optimized for an expected distribution of work**. Therefore, you should always be explicit and aware what observable contract and distribution of work you are implementing for and what tradeoffs you are making. Read [first principles data systems](docs/dev/systems.md)
8992

9093
The full rules live in [invariants](docs/dev/invariants.md). Keep these in
9194
working memory:
@@ -108,10 +111,7 @@ working memory:
108111
Never acknowledge before durable graph visibility or return silent partial
109112
results.
110113

111-
Do not add a custom WAL/transaction manager, a queue for manifest-derived work,
112-
inline vector/FTS rebuilds, raw public Lance writers, string-built query
113-
semantics, process-local locks advertised as distributed fencing, cloud-only
114-
correctness paths, or a shadow source of truth without an accepted RFC that
114+
Do not add a queue for manifest-derived work, inline vector/FTS rebuilds, raw public Lance writers, string-built query semantics, process-local locks advertised as distributed fencing, cloud-only correctness paths, or a shadow source of truth without an accepted RFC that
115115
changes the invariant.
116116

117117
## Build and test

0 commit comments

Comments
 (0)