Protocol v1

The Borrowed Light protocol is implemented by Lux: a Git-like kernel for points, links, and trails, with structured runs as the experiment spine. This page describes the smallest interoperable surface — the pieces that must match byte-for-byte for independent implementations to converge.

Lux spec → Lux repo →

Core object kinds (v1 minimum)

Point: an addressable unit of knowledge (statement, definition, dataset slice, metric).
Link: a typed relationship between objects (lux.depends_on, lux.supports, lux.supersedes).
Trail: a record of reasoning or procedure, including run attestations.
Run: a structured execution record (inputs to outputs), where inputs/outputs are Lux object IDs.

Kernel rule: identity and provenance live in the kernel; truth, scoring, and frontier live in observers.

Interop invariants (the part that must not drift)

Canonical bytes: all hashed/signed JSON is canonicalized with RFC 8785 (JCS) and tested at the byte level.
IDs: sha256:<hex> over canonical UTF-8 bytes (ordering uses raw digest bytes).
Integer-only kernel: JSON numbers are integers only, within ±(2^53-1).
Event IDs: EID is sha256(JCS(event_without_sig)).
Deterministic replay: topo order by deps, tie-break by raw digest bytes.
History membership is explicit: objects enter replayable history via lux.object.add; events that reference objects depend on the introducing EID.

Data model (kernel shapes)

Lux uses a universal object envelope, plus signed events. These examples are illustrative; the spec is the source of truth.

// object envelope (hashed as a whole)
{
  "kind": "lux.point",
  "v": 1,
  "schema": "urn:lux:schema:v1:point",
  "body": {
    "point_type": "statement",
    "title": "…",
    "statement": "…",
    "qualifiers": { }
  }
}

// event (EID = sha256(JCS(event_without_sig)))
{
  "type": "lux.object.add",
  "refs": { "object_id": "sha256:…" },
  "deps": [],
  "meta": { "note": "optional" },
  "sig": { "alg": "ed25519", "public_key": "…", "sig": "…" }
}

Refs + checkpoints

Like Git, Lux has immutable objects/events and mutable refs/. Refs point to checkpoint roots that commit to an accepted event set, published via lux.checkpoint.publish.

refs/heads/main: the moving head of a constellation.
refs/tags/neuro-v1, refs/tags/neuro-v2: named story beats for a demo or paper-ready snapshot.

Conformance (the standard in practice)

Lux is only real if independent implementations reproduce the same bytes/IDs/order. Conformance vectors — not prose — are the standard.

# from the Lux repo
cargo run -p lux -- conformance-test