Contracts in AngaraBase

Goal

Explain what the term “contract” means in AngaraBase, the levels of contracts that exist, and the mechanisms used to enforce them. This page is for users, DBAs, and new contributors: to make it clear when reading documentation, code, or error messages what guarantees can be relied upon, and what is explicitly outside the contract.

What We Mean by a Contract

A contract in AngaraBase is an explicit promise about the observable behavior of a component: what it takes as input, what it returns, what guarantees it provides, and how it behaves when boundaries are violated. A contract is not “best intentions” or “how it usually works” — it is a formalized agreement that both sides must adhere to: the implementation and the caller (or client).

A contract has three key properties:

Explicitness. The contract is documented in a single canonical source — not in a chat, not in a code comment, not in the “shared understanding of the team.”
Verifiability. Compliance with the contract is verified automatically: by tests, types, metrics, or lint checks.
Fail-closed. When a contract boundary is violated, the system returns an explicit error (with a known code), rather than “somehow continuing to work.”

If something in the system is not covered by a contract, it is explicitly marked as roadmap, experimental, or known limitation. Behavior outside a contract can change without a deprecation cycle.

Levels of Contracts

AngaraBase has several levels of contracts, each with its own source of truth and method of verification.

1. SQL Contract (External, for the User)

What is supported is supported fully. What is not supported returns an explicit SQLSTATE (0A000 feature_not_supported, etc.) rather than a silent bypass or distorted result.

Source: SQL Compatibility Overview, Known Issues and SQLSTATE.
Verification: pinned compat suite, regression tests for every documented SQLSTATE.
What this means in practice: a client can catch psycopg.errors.FeatureNotSupported and know exactly that they hit a documented limitation, not a bug.

2. Configuration Contract

Every config key has a type, a default value, a range of acceptable values, and defined behavior for absence or invalid values.

Source: Configuration, Configuration schema reference.
Verification: the parser rejects unknown/invalid keys on startup (fail-closed), rather than silently ignoring them.
Changing the semantics of a key goes through a deprecation cycle (see WRITING_RULES.md §9a).

3. Operational Contract

Metrics, USDT probes, names of sys.* views, backup/restore formats, log formats, and runbook output — all of these are public names that monitoring and operator automation rely on.

Source: System tables, Observability metrics checklist, Backup and restore, USDT/eBPF probes.
Principle: every resource boundary (buffer pool RAM budget, transaction write-set limit, snapshot age, etc.) must have a Prometheus metric and explicit fail-closed behavior on violation. A boundary without observability is not a contract.

4. Internal API Contracts (For Contributors)

Each core subsystem has a public Rust trait defining its semantics: TableEngine, PageProvider, TransactionLogSink, StorageIo, etc. Without implementing the contract, the code won’t compile — this is an “honest checked promise,” not just a “developer’s word.”

Source: doc-comments on traits, Architecture overview, API Boundaries.
Verification: Rust compiler + property-tests for invariants + layering lints (Core doesn’t depend on Adapters/Tooling).

5. Documentation Contract (Anti-drift)

Documentation is part of the code. Any change to a public contract (SQL surface, config keys, metrics, SQLSTATE, subsystem names, protective defaults, init/upgrade sequence) must be accompanied by an update to AngaraBook in the same PR.

Source: WRITING_RULES.md §8 — Anti-drift contract.
Verification: pre-commit / CI run tools/docs/lint_angarabook_public.py, tools/docs/check_public_build_security.py and mark drift as blocking.

How We Enforce Contracts

A contract without an enforcement mechanism is just a declaration. AngaraBase uses multiple layers of enforcement working together.

The Type System as the First Line of Defense

Result<T, Error> instead of panics. unwrap() / expect() are forbidden in production code.
Bounded generics and trait objects instead of dynamic dispatch where invariants can be encoded at the type level.
No-panic policy: the server does not crash on user input — it returns an SQLSTATE.

Restrictive by Default + Fail-closed

Every component with a resource boundary must define:

its boundary (e.g., buffer_pool_size_mb, txn_max_write_set_mb, max_concurrent_queries),
behavior upon violation (an explicit error with a known SQLSTATE),
the reaction of the caller code (Reaction Propagation Contract).

No boundary and no fail-closed behavior — no merge.

Pinned Tests and Golden Datasets

The contract for SQL compatibility and client compatibility is verified by pinned tests, not a “compatibility percentage.” If a test is pinned — changing behavior requires either updating the test with a justification, or rolling back the change.

More details: Testing and validation baseline, Golden dataset management, CI reproducibility contract.

Deprecation Cycle

When a contract is phased out, it does not silently disappear. A unified cycle is applied: Active → Deprecated → Removed, with at least one major release between Deprecated and Removed; before v1.0 — at least two minor versions. Every phase change is an atomic PR (code + AngaraBook + Migration steps).

Full procedure: WRITING_RULES.md §9a — Deprecation policy. Public list of all deprecated/removed contracts: Known Issues and SQLSTATE.

Security Gate as Fail-closed for Documentation

Public builds of AngaraBook pass through a security gate: links to internal directories (RFC/development/spec/rules) and paths with /internal/ are forbidden. Internal content is hidden via  ...  blocks; the preprocessor fails closed on nested/unclosed markers.

What This Means for the User

Predictable Behavior. If behavior is documented, it is stable within a major release. If documented as a limitation with an SQLSTATE, it will return exactly that SQLSTATE, rather than “sometimes working.”
Safe Client Code. You can catch specific SQLSTATEs and build retry/error handling logic without heuristics or parsing text messages.
Clear Upgrades. Changing the behavior of a public contract goes through an explicit deprecation cycle with migration steps; you see what will change and when, well in advance.
Observable Guarantees. Every resource boundary has a metric; you can see utilization and rejects before they become incidents.

What This Means for Developers and Contributors

Compiler Contract, Not Review Comment. If an invariant can be encoded in a trait or type, it is encoded. Code review catches what the compiler cannot.
Single Source of Truth per Knowledge Type. No need to “search for the current truth across multiple documents”: there is a single canonical owner for each layer of the contract.
Predictable Debt Management. A deprecated contract is tracked in reference/known-issues.md, and if not resolved in one PR, in the technical debt registry with a status of scheduled <target-train>.
Anti-drift in a Single PR. Change the behavior — update AngaraBook right there. No “update docs later.”

What Is Not a Contract

To avoid false expectations, explicitly: the following are not considered contracts:

internal module names, filenames, and private core functions (can change during refactoring without deprecation);
behavior of features with status: experimental frontmatter or --experimental-* CLI flags — they were never considered stable;
error message texts (the contract is the SQLSTATE and its meaning, not the text);
undocumented side effects noticed empirically (“it works for me if…”);
benchmarks and numerical latency values — this is observability, not a performance claim (a performance claim requires a pinned benchmark, see tools/perf_pack/).

If you rely on any of these in production, it is technical debt on the client side, and a future AngaraBase update will expose it.

Keyboard shortcuts

AngaraBook