The complete Context Fabric Standard specification for implementers. Schemas, wire formats, protocols, and conformance requirements.
All CFS primitives are defined with precise schemas. Implementations MUST validate against these schemas. Canonical encoding uses Protocol Buffers with deterministic serialization.
message Record {
string record_id = 1; // Stable unique ID (UUIDv7 recommended)
string tenant_id = 2; // Tenant isolation boundary
repeated string labels = 3; // Type classification
map<string, Value> props = 4; // Key-value properties
Timestamp created_at = 5; // System time of creation
bytes integrity = 6; // SHA-256 of canonical encoding
}record_id: MUST be globally unique, MUST NOT change after creation.
integrity: Hash of deterministic protobuf encoding excluding this field.
message Link {
string link_id = 1; // Unique link identifier
string type = 2; // Relationship predicate from registry
string source = 3; // Source record_id
string target = 4; // Target record_id
map<string, Value> props = 5; // Relationship attributes
Interval valid = 6; // When this relationship was true
Interval system = 7; // When this was known (append-only)
string assertion_id = 8; // Provenance reference
bytes integrity = 9;
}
message Interval {
Timestamp from = 1; // Inclusive start
Timestamp to = 2; // Exclusive end (MAX for open)
}valid: Application time - when the relationship was true in reality.
system: Transaction time - when this record entered the system.
message View {
string view_id = 1;
Query base_query = 2; // Records/links to include
FieldMask field_mask = 3; // Which properties are visible
repeated string policy_refs = 4; // Governing policies
RefreshMode refresh_mode = 5;
Timestamp expires_at = 6; // Optional cache expiry
}
enum RefreshMode {
LIVE = 0; // Always current
CACHED = 1; // May be stale within TTL
SNAPSHOT = 2; // Point-in-time frozen
}message Tool {
string tool_id = 1;
string name = 2;
string description = 3;
Schema input_schema = 4; // JSON Schema for inputs
Schema output_schema = 5; // JSON Schema for outputs
repeated string required_permissions = 6;
repeated SideEffect side_effects = 7;
AuditLevel audit_level = 8;
}
message SideEffect {
string type = 1; // create, update, delete, external
string resource_pattern = 2; // What's affected
}
enum AuditLevel {
MINIMAL = 0; // ID + timestamp only
STANDARD = 1; // + inputs/outputs summary
FULL = 2; // Complete input/output capture
}message Receipt {
string receipt_id = 1; // Unique, immutable
Principal actor = 2; // Who performed action
Action action = 3; // What was done
repeated string targets = 4; // What was affected
Timestamp timestamp = 5; // System time
map<string, string> context = 6; // Request ID, session, etc.
bytes prev_hash = 7; // Chain to previous receipt
bytes integrity = 8; // Hash for tamper detection
}
message Principal {
string id = 1;
PrincipalType type = 2; // HUMAN, AGENT, SERVICE, SYSTEM
string auth_context = 3; // How authenticated
}
enum Action {
READ = 0;
WRITE = 1;
INVOKE = 2;
APPROVE = 3;
SYNC = 4;
}message Policy {
string policy_id = 1;
Effect effect = 2; // ALLOW or DENY
PrincipalMatcher principal = 3;
ResourceMatcher resource = 4;
repeated Condition conditions = 5;
int32 priority = 6; // Higher = evaluated first
Interval valid = 7; // When policy applies
}
enum Effect {
ALLOW = 0;
DENY = 1;
}
message Condition {
string attribute = 1; // e.g., "time.hour"
string operator = 2; // e.g., "between"
repeated Value operands = 3;
}message Gate {
string gate_id = 1;
repeated Requirement requirements = 2;
repeated string unlocks = 3; // Capabilities/resources gated
GateStatus status = 4;
repeated Evidence evidence = 5;
Timestamp expires_at = 6; // When unlock lapses
}
message Requirement {
string id = 1;
string description = 2;
Query check = 3; // How to verify
bool satisfied = 4;
}
message Evidence {
string requirement_id = 1;
string receipt_id = 2; // Proof of satisfaction
Timestamp verified_at = 3;
}
enum GateStatus {
LOCKED = 0;
PENDING = 1; // Some requirements met
UNLOCKED = 2;
}All CFS data MUST be serializable to canonical Protocol Buffers for integrity verification. Deterministic serialization rules:
For transport, implementations MAY use:
Integrity hashes MUST be computed on the canonical protobuf encoding, regardless of transport format.
Artifacts use content addressing with multihash:
multihash = <hash-function-code> + <digest-length> + <digest>
Recommended: SHA-256 (0x12) with 32-byte digest
Example: 0x1220 + 64 hex chars
All timestamps use protobuf google.protobuf.Timestamp:
seconds=0, nanos=0seconds=MAX_INT64Querying context with bitemporal semantics:
message QueryRequest {
Query query = 1;
Timestamp as_of_valid = 2; // Valid time (default: now)
Timestamp as_of_system = 3; // System time (default: now)
int32 limit = 4;
string cursor = 5; // For pagination
FieldMask fields = 6; // Which properties to return
}
message QueryResponse {
repeated Record records = 1;
repeated Link links = 2;
string next_cursor = 3;
Receipt receipt = 4; // Proof of access
}Safe writes with human-in-the-loop:
// Step 1: Propose
message ProposeRequest {
repeated Mutation mutations = 1;
string intent = 2; // Why this change
repeated string citations = 3; // Source artifacts
}
message ProposeResponse {
string proposal_id = 1;
Diff diff = 2; // What would change
repeated string affected = 3; // Impacted records
}
// Step 2: Review (external, human or policy)
// Step 3: Apply
message ApplyRequest {
string proposal_id = 1;
string approver = 2; // Who approved
string approval_ref = 3; // Evidence of approval
}
message ApplyResponse {
bool success = 1;
repeated Receipt receipts = 2;
string commit_id = 3;
}Incremental replication between planes:
message SyncRequest {
string source_plane = 1;
string cursor = 2; // Last sync position
SyncFilter filter = 3; // What to include
int32 batch_size = 4;
}
message SyncResponse {
repeated SyncEntry entries = 1;
string next_cursor = 2;
bool has_more = 3;
}
message SyncEntry {
oneof entry {
Record record = 1;
Link link = 2;
Artifact artifact_meta = 3;
}
string commit_id = 4;
Timestamp commit_time = 5;
}To claim CFS conformance, implementations MUST pass the conformance test suite and meet these requirements:
MUST-001 All primitives MUST validate against the core schemas.
MUST-002 Implementations MUST compute and verify integrity hashes using canonical protobuf encoding.
MUST-003 Links and versioned data MUST support AS-OF queries on both valid-time and system-time axes.
MUST-004 Corrections MUST append new records, never mutate existing ones. System intervals MUST only close, never reopen.
MUST-005 All reads and writes MUST produce receipts with valid actor, action, targets, and integrity hash.
MUST-006 Views MUST respect policy filters. Denied access MUST NOT leak data through error messages or timing.
MUST-007 Implementations MUST support import/export in the canonical format. Round-trip MUST preserve all data and integrity hashes.
SHOULD-001 Implementations SHOULD maintain a merkle tree of receipts for tamper-evident audit trails.
The conformance test suite is available at github.com/helaix/cfs-conformance. Run the suite against your implementation to verify compliance.
CFS is extensible. Custom types, predicates, and schemas can be added through the registry mechanism.
Custom record labels, link types, and property schemas are registered in a schema registry. Each entry has a namespace, version, and schema definition.
message SchemaEntry {
string namespace = 1; // e.g., "com.glitchy"
string name = 2; // e.g., "IncidentReport"
string version = 3; // Semver
Schema schema = 4; // JSON Schema
SchemaEntry supersedes = 5; // Previous version
}Custom relationship predicates with cardinality and validity constraints:
message LinkType {
string namespace = 1;
string predicate = 2; // e.g., "escalated_to"
string source_label = 3; // Required source type
string target_label = 4; // Required target type
Cardinality cardinality = 5; // ONE_TO_ONE, ONE_TO_MANY, etc.
}Schema evolution follows these rules: