Expand description
The Constitution — what this engine guarantees, in a form a client can check.
neSQL (the query language and CLI) ships as a separate artifact from NEDB (the engine). The two are versioned independently and will routinely be at different versions on one machine. So “can this CLI drive this engine?” has to be answerable by asking the engine, not by reading anything the CLI brought with it.
§The failure mode this module exists to design out
The tempting implementation of “grammar verification” is: the CLI ships a copy of the grammar, hashes it at startup, and prints VERIFIED. That proves exactly one thing — the CLI can read its own disk. It says nothing about the engine on the other end of the socket, which is the only party whose grammar actually decides whether a query parses. A client that self-hashes is strictly worse than one that does not check at all, because it reports confidence it has not earned.
So verification here is a two-party comparison. The engine publishes a
Constitution describing the language and formats IT implements; the
client sends a ClientClaim describing what IT needs; and
check_compatibility is evaluated ON THE ENGINE, against the engine’s own
tables. The client never gets to supply the thing it is being checked
against.
§What is in it
formats— wire/on-disk formats, name + integer version.capabilities— named features. Additive and stable: a name, once shipped, keeps its meaning forever, and new ones are appended.invariants— the semantic promises, each with a stable id. These are the rules a client may build on; they are transcribed from the modules that enforce them, not invented here.grammar_digest— a digest of an explicit structural description of NQL.
Hash construction follows the house pattern from crate::root: BLAKE2b-512
truncated to 32 bytes, every variable-length field preceded by its length as
u64 little-endian, and a distinct domain tag per kind of input.
Structs§
- Client
Claim - What a client says it needs.
- Constitution
- Everything this engine guarantees, packaged for a client to verify against.
- Format
Version - A format this engine implements, by name and integer version.
- Invariant
- A semantic promise, with an id stable across engine versions.
Enums§
Functions§
- check_
compatibility - Decide whether a client can drive THIS engine.
- constitution
- This engine’s Constitution.
- digest
- Stable digest of this engine’s whole Constitution.
- grammar_
digest - The digest of the grammar THIS ENGINE implements.