Facts Protocol

Facts is an open protocol for shared knowledge management. It records propositions, revisions, deliberations, decisions, and settlements as signed append-only protocol objects. A proposition becomes an effective fact only when the signed object graph proves recorded consensus.

This repository documents protocol version 0 in implementation-neutral terms. The Rust SDK, CLI, and HTTP implementations are reference implementations, not the definition of the protocol. A conforming implementation in any language must produce the same canonical bytes, validation decisions, state projections, exchange artifacts, and conformance results for the same inputs.

Start Here

• Protocol v0: the core model, terminology, invariants, lifecycle, and security boundaries.
• Encoding and Signing: canonical JSON, canonical Markdown, UUIDs, hashes, COSE signatures, and optional encryption.
• Protocol Objects: the envelope, reusable scalar schemas, object registry, relationships, and non-object records.
• Object Body Reference: field-level body requirements for all v0 object types.
• Validation: fail-closed validation order and error classification.
• Authorization: capabilities, scopes, causal authorization, grants, delegation, revocation, and time handling.
• Consensus and Effective State: deliberations, decisions, settlements, reconciliation, lifecycle projections, and conflict behavior.
• Transport and Sync: HTTPS routes, request and response schemas, bundles, snapshots, commitments, and Merkle proofs.
• Query and Search: canonical queries, score profiles, result ordering, cursors, and completeness claims.
• SDK and CLI Guide: language-neutral guidance for implementing an SDK and a reference CLI.
• Conformance: test levels, fixture expectations, and release gates.
• Glossary: short definitions for protocol terms.
• Source Map: source documents used to derive this repo.

Normative Status

The documents in docs/ are written from versioned Fact protocol source materials and curated summaries.

For version 0, the core specification and named companion specifications are co-authoritative. Fixtures and conformance vectors encode behavior already specified by those documents; they do not invent semantics. Reference implementation details, deployment defaults, database schemas, and UI choices are informative unless a protocol document explicitly adopts one of their fields or algorithms.

Implementation Boundary

The protocol specifies:

• canonical encodings and signatures;
• signed protocol object schemas;
• ledger boundaries and portable identity objects;
• causal authorization and validation;
• deterministic state derivation;
• consensus, settlement, reconciliation, and effective fact behavior;
• transport, synchronization, commitments, proofs, queries, and conformance.

The protocol does not prescribe:

• a programming language;
• a database engine or table layout;
• a CLI command syntax;
• a user interface;
• a notification system;
• private-key storage;
• a real-world identity provider;
• coordinator access-control policy beyond the protocol/transport distinction.

Version

Current documented protocol version: 0.

Current source draft: revision 0.3, dated 2026-07-25.