Expand description
§personaldb-protocol
personaldb-protocol is the small, implementation-independent contract shared
by PersonalDB clients, projection builders, and server witnesses.
§Included contracts
- Typed database identifiers, SHA-256 digests, group kinds, and state commitments.
- Domain-separated Ed25519 envelopes and purpose-, scope-, generation-, status-, and log-bound trust policy.
- Commit certificates, committed heads, signed group descriptors, and signed projection derivations.
- Catch-up request and frame types, snapshot request and frame types, signed snapshot target manifests, and watch contracts.
- Protocol bounds for chunks, entries, and catch-up pages.
- Storage-independent authenticated-state primitives that reproduce PersonalDB’s canonical row, table, and database roots.
It deliberately does not provide a database, SQLite access, schemas, RPC clients, object storage, key custody, authorisation decisions, or a background runtime. Implementations remain responsible for authenticating callers, admitting transitions, persisting protocol objects, and enforcing stream state machines.
§Canonical projection delivery
Signed durable objects expose encode_deterministic and decode_canonical.
Canonical decoders decode, validate, deterministically re-encode, and compare
the exact input bytes. Unknown fields, duplicate scalar fields, reordered
fields, non-minimal varints, malformed nested signatures, and other alternate
protobuf encodings therefore fail closed.
Requests and watch notices are transport contracts rather than signed durable objects. A transport maps them to its authenticated HTTP, gRPC, or in-process API. Catch-up and snapshot frames are canonical protobuf records and keep signed evidence opaque until its own strict decoder has accepted it.
§Authenticated state
CanonicalStateValueV1 has the same externally tagged JSON representation as
PersonalDB’s committed values. Primary-key values must be supplied in declared
primary-key order. Stored values must be supplied in managed-schema column
order.
The exported primitives implement this exact sequence:
- Encode the primary-key value array as compact JSON.
- Hash the row key and stored row with their PersonalDB JSON domains.
- Select one of 256 leaves from the first row-key hash byte.
- XOR row hashes in each leaf and bind the accumulator plus row count.
- Build the fixed-depth eight-level sparse table Merkle tree.
- Bind all writable managed table roots, ordered by table name, into the database state root.
The functions are independent of SQLite and storage layout. A server can retain leaf accumulators and nodes in any transactional store, while a client can recompute the same root from projected rows.
§0.2 compatibility
Version 0.2.0 is an intentional clean break from 0.1.0. Commitment fields now
use DatabaseId, Sha256Digest, and DatabaseGroupKind directly, matching
the canonical projection protocol in private PersonalDB commit
276515e624e91d3d0ac9f438d7d3a940ddf2ddb4. There is no raw-field compatibility
facade or dual wire version.
Signing, projection, sync, snapshot, and authenticated-state encodings are covered by fixed vectors and adversarial canonicality tests.
§License
Apache-2.0.
Structs§
- Authenticated
RowV1 - One committed managed row, independent of any storage engine.
- Canonical
Primary KeyV1 - Canonical JSON text for a row’s ordered primary-key values.
- Commit
Certificate V2 - Committed
Head V2 - Database
Id - A stable PersonalDB database identifier.
- Describe
Group Request - Ed25519
Protocol Signer - Ed25519
Public Key - Ed25519
Signature - Group
Descriptor - Head
Notice - KeyGeneration
- KeyId
- KeyTrust
Policy - LogEntry
Core V2 - Merkle
Leaf Accumulator V2 - XOR accumulator and row count for one of the 256 sparse table leaves.
- Personal
DbCatch UpRequest V1 - Personal
DbSnapshot Request V1 - Projection
Definition V1 - A deliberately bounded, immutable PersonalDB projection template.
- Projection
Derivation V1 - Deterministic evidence binding source heads and a projection transition.
- Public
KeyEnvelope V1 - Canonical deterministic-protobuf Ed25519 public-key envelope.
- Public
KeyTrust Record - Public
KeyTrust Store - Sha256
Digest - Signature
Envelope V1 - Canonical deterministic-protobuf signature envelope.
- Signature
Metadata - Signature
Scope - Signed
Projection Derivation V1 - Projection derivation carrying the sole admitted projection-builder signature.
- Signed
Snapshot Target Manifest V1 - Signing
Preimage - Snapshot
Chunk V1 - Snapshot
EndV1 - Snapshot
Header V1 - Snapshot
Target Manifest V1 - Source
Head V1 - State
Commitment V1 - Sync
EndV1 - Sync
Entry Chunk V1 - Sync
Entry EndV1 - Sync
Entry Start V1 - Sync
Error V1 - Sync
Header V1 - Table
Merkle Node V2 - A materialized sparse-Merkle node and the number of rows below it.
- Table
State Root V2 - Final authenticated state for one writable managed table.
- Unsigned
Commit Certificate V2 - Unsigned
Committed Head V2 - Unsigned
Group Descriptor V1 - Verified
Signature - Watch
Request
Enums§
- Authenticated
State Error - Canonical
State Value V1 - Storage-neutral values in the exact externally-tagged JSON representation used by PersonalDB’s authenticated row algorithm.
- Database
Group Kind - Hash
Algorithm - Personal
DbSnapshot Frame V1 - Personal
DbSync Frame V1 - Projection
Definition Mode V1 - Projection
Protocol Error - Protocol
Security Profile - Public
KeyStatus - Signature
Algorithm - Signature
Domain - Signature
Error - Signature
Purpose - Signing
Payload - Snapshot
Compression V1 - Sync
Error Code V1
Constants§
- DATABASE_
ROOT_ DOMAIN_ V1 - ED25519_
PUBLIC_ KEY_ LENGTH - ED25519_
SIGNATURE_ LENGTH - EMPTY_
TABLE_ DOMAIN_ V1 - GROUP_
DESCRIPTOR_ FORMAT_ VERSION_ V1 - MAX_
PROTOCOL_ ID_ BYTES - MAX_
SYNC_ CHUNK_ BYTES - MAX_
SYNC_ ENTRY_ BYTES - MAX_
SYNC_ PAGE_ BYTES - MAX_
SYNC_ PAGE_ ENTRIES - MERKLE_
LEAF_ DOMAIN_ V2 - MERKLE_
NODE_ DOMAIN_ V2 - PROJECTION_
DEFINITION_ FORMAT_ VERSION_ V1 - PROJECTION_
DERIVATION_ FORMAT_ VERSION_ V1 - PROTOCOL_
EVIDENCE_ FORMAT_ VERSION_ V2 - PUBLIC_
KEY_ ENVELOPE_ FORMAT_ VERSION_ V1 - PUBLIC_
KEY_ TRUST_ RECORD_ FORMAT_ VERSION_ V1 - ROW_
KEY_ DOMAIN_ V1 - ROW_
STATE_ DOMAIN_ V1 - SHA256_
DIGEST_ LENGTH - SIGNATURE_
ENVELOPE_ FORMAT_ VERSION_ V1 - STATE_
COMMITMENT_ FORMAT_ VERSION_ V1 - SYNC_
FORMAT_ VERSION_ V1 - TABLE_
MERKLE_ DEPTH_ V2 - The fixed table tree has one leaf for each possible first byte of a row-key hash.
Traits§
- Protocol
Signable - Implement this on typed canonical protocol objects, never on an arbitrary-byte RPC request.
- Protocol
Signature Verifier - Protocol
Signer
Functions§
- canonical_
primary_ key_ json_ v1 - Returns the exact compact JSON text committed as a primary-key string.
- database_
state_ root_ v1 - Computes the database root over all writable managed table roots.
- ed25519_
public_ key_ envelope_ v1_ bytes - empty_
table_ state_ root_ v1 - Root used for a writable managed table with no committed rows.
- merkle_
leaf_ bucket_ v2 - Selects one of 256 leaves from the first byte of the row-key SHA-256 digest.
- merkle_
leaf_ node_ v2 - Materializes a non-empty sparse-Merkle leaf.
- merkle_
parent_ node_ v2 - Materializes one internal sparse-Merkle node.
- row_
key_ hash_ v1 - Hashes a table name and canonical primary-key JSON into the row-key digest.
- row_
state_ hash_ v1 - Hashes the exact committed stored values for one managed row.
- signing_
preimage - Builds the sole PersonalDB signing preimage from canonical bytes or their exact SHA-256.
- table_
state_ root_ v2 - Recomputes a table root from storage-neutral committed rows.
Type Aliases§
- LogIndex
- The zero-based position of an operation in a PersonalDB log.