v0.1.5

Changes since v0.1.4.

Highlights

Federation goes live (M4 Phase 4) - run a hub, sync your nodes

v0.1.4 shipped the federation library; v0.1.5 wires it into the product. A node can now run as a
sync server (hub) and other nodes can replicate their knowledge to and from it - over TLS, with
per-node bearer/allowlist auth and per-event ed25519 signatures.

• Configuration: supragnosis.toml (SUPRAGNOSIS_CONFIG or ~/.supragnosis/supragnosis.toml)
  with [sync] (share_workspaces / servers / auth_token / insecure_tls / origin_keys) and
  [server] (listen / tls_cert / tls_key / allowlist). Unknown keys are rejected loudly - a typo
  cannot silently disable a role. No file = a standalone node, zero behavior change.
• Node identity: an ed25519 keypair is generated once at ~/.supragnosis/node.key; the
  immutable node id derives from the public key. supragnosis identity prints it (and
  --hash-token prepares an allowlist entry for a peer's bearer token).
• CLI: supragnosis sync (one-shot round: push surplus, pull deficit, apply, re-materialize),
  supragnosis reproject (deterministic HLC-ordered re-materialization), and
  supragnosis migrate (see below). The [server] role starts alongside the daemon; a
  misconfigured server section fails startup loudly instead of silently running without the role.
• MCP tools: sync_status / sync_pull / sync_push (the surface is now 13 tools) - an agent
  can inspect the node's version vector, pull missing knowledge, and push local knowledge without
  stopping the daemon. Inbound pushes re-materialize automatically on the server.

Federated recall - search the remote ontology when local state lags

search_knowledge gains scope: "local" | "remote" | "both". Local state can lag the remote
store, so a local miss may just mean "not synced yet" - the remote scope queries the configured
sync servers' own recall surfaces (mode-labeled), gated by the same per-node workspace
authorization as sync. Remote hits are a recall aid: sync_pull materializes them locally before
traverse/get_entity - the signed log remains the only transport of knowledge.

Legacy-id migration - pre-0.1.x knowledge can now cross the wire

The content-address formula evolved during 0.x (descriptions, type definitions, proposal events
each extended the assertion encoding), so observations stored under an earlier formula cannot
verify remotely - the receiver recomputes ids, and forged or stale ids never land (working as
designed). supragnosis migrate re-creates such rows under the current formula - content,
assertions, and provenance preserved, with lineage back to the legacy row - after which they sync.
Legacy rows themselves stay local history and are never exported.

Live federation observability

Sync hits stream into the viewer activity feed on both sides: the hub shows who connected
(authenticated node id), which direction (advertise / pull-served / push-received /
search-served), which workspace, and how much; a spoke shows its own rounds. Watching the hub's
viewer during a sync shows the federation working in real time.

Viewer

• Interim read-only network exposure: with the owner's explicit opt-in
  (SUPRAGNOSIS_VIZ_PUBLIC=1), the viewer may bind beyond loopback for read-only browsing -
  sharing is the creator's decision. Every write endpoint stays gated per connection to loopback
  peers (a remote peer gets 403 for verdicts). Superseded by the authenticated read tier
  (federation Phase 3.5).
• Camera choreography: in follow mode the camera frames an event's whole hit set (pan + zoom)
  instead of centering on one node; after synced knowledge lands, the graph re-frames once the
  re-layout settles; switching workspaces resets the view state, raises the layout loader
  immediately, and reveals the new graph auto-fitted.

Install

curl -fsSL https://raw.githubusercontent.com/Ashon/supragnosis/main/scripts/install.sh | sh

Or download the platform tar.gz from the assets below, extract it, and put supragnosis
on your PATH. Supported: macOS (arm64 / x86_64), Linux (x86_64, glibc 2.35+); each asset ships a
.sha256.

• CLI: supragnosis --help. Register with an MCP client: claude mcp add supragnosis -- ~/.local/bin/supragnosis.

Notes / limitations

• Single-principal federation: multi-principal workspaces await the governance enforcement
  phase (canon-policy artifact, proposal-fold identity checks, the tbox_change gate). Deploy hubs
  for one principal's machines for now.
• Origin keys are configured manually ([sync] origin_keys) until the log-borne canon-policy
  binding lands.
• Embeddings do not sync (they are a node-local recall aid by design): knowledge pulled from a
  hub answers keyword search immediately, but semantic recall requires local re-embedding - a
  re-embed pass is future work. The federated-recall scope can query the server's (richer) surface
  meanwhile.
• supragnosis sync/migrate/reproject need the daemon stopped (single-process store); with a
  running daemon use the sync_* MCP tools instead.
• A self-signed hub certificate requires insecure_tls = true on clients; content authenticity is
  still end-to-end (per-event signatures). A real CA or pinned cert is recommended when available.
• HTTP daemon (MCP) stays loopback-only; the viewer's network exposure is opt-in and
  read-only as above.
• 0.x early release - the storage format and surfaces may still change.