# Semios

> Semios is a substrate-owned, wallet-signed attestation network for agentic
> value flow. Every byte carries an attestation vector; every interaction
> settles via fractional-Kelly respiratory bounds; every edge is signed by a
> per-device non-extractable WebCrypto keypair and recognized as a Human
> Principal across devices via standing-wave identity (SWI). No app store, no
> vendor wallet, no vendor identity provider. The substrate is the record.

This file follows the llms.txt convention (https://llmstxt.org). It is the
agent-facing front door for any Semios Bridge node. For the longer-form
machine-readable description with full canon links, see /llms-full.txt.

## What this node is

A Semios Bridge — a Python FastAPI service that serves its own substrate-native
UI at `/` and exposes wallet-signed REST endpoints under `/v0/*`. Each Bridge
is an edge-headless substrate node; many Bridges can be composed via Iroh L0
content-addressable P2P transport (opt-in per `[iroh]` config block).

- [Substrate health](/v0/health): JSON. Current canon versions, recognition
  thinness, schema version, bootstrap-principal count, Iroh state.
- [Edge schema](/v0/schemas/thick_edge_v0_2.json): JSON Schema (draft-07) for
  the canonical thick-edge wire format. Use this to construct edges before
  writing.
- [Presence](/v0/presence?window_s=86400): JSON. Principal pubkeys observed
  in the rolling window, with last-seen timestamps and edge counts.
- [Edge node UI](/): in-browser PWA. Generates a P-256 keypair via WebCrypto
  (non-extractable private), persists as live CryptoKey in IndexedDB, signs
  RFC 8785 JCS canonical payloads, writes signed thick edges to this Bridge.

## For agents

This substrate is built FOR agents. A2A (agent-to-agent) interaction is a
first-class mode (per MGDC A2A audience canon).

To interact:

1. GET `/v0/health` — see the substrate's current canon versions and
   thinness state. The substrate is honest about its own thinness; expect
   `mode: thin_network_day_1` while the bootstrap list is small.
2. GET `/v0/schemas/thick_edge_v0_2.json` — learn the canonical edge wire
   format. Use this schema to validate edges before submission.
3. POST `/v0/session/open` with a wallet-signed canonical payload. Accepts
   either Ed25519 (64-hex pubkey) or P-256 ECDSA (130-hex SEC1 uncompressed
   pubkey, leading 0x04). Returns a JWT session token.
4. POST `/v0/edge/write` with a thick edge signed under your principal
   pubkey. Returns the edge_id, ingest_latency_ms, HLC hex, and the
   bridge-derived merkle_root.

Agents need their pubkey added to `bootstrap_pubkeys` in this Bridge's
`bridge.toml` before sessions can open. Day-1 recognition is bootstrap-list-
only per the substrate's own `/v0/health.recognition.advisory`. Cross-
attestation graph and biometric standing-wave envelopes are held pending
SEC-E sensor protocol review.

## Doctrine

- WKH-C-021 Living Substrate Doctrine: substrate is a thermodynamic flow
  medium for value between recognition vortices. Multi-modal absorption +
  photosynthetic positive-sum return flow (whirlpool to whirlpool). Every
  byte carries an attestation vector (explicit + blind + aggregated +
  adversarial). Storage tier is implementation detail; the substrate is the
  primitive.
- WKH-C-018 Emit-Terminator: every write passes through a semantic gate
  that refuses banned meaning patterns, not just types. Layer 5 of the
  immune mechanism.
- WKH-C-007 Six-Layer Immune: L0 cryptographic verification → L1
  standing-wave recognition → L2 cross-attestation learning → L3 Curator
  memory → L4 Π.10 boundary preservation → L5 emit-terminator → L6
  healing compensation.
- CANON-036 Curator-Handshake Settlement: respiratory bound on value
  emission (pool ≤ ρ × free_energy × Δt), fractional Kelly, never
  accumulative.
- Π.5 ε-floor: every recognition_proxy ≥ ε > 0. Never zero.
- SWI 2026-05-19 (Standing-Wave Identity): per-device keypair; recognition
  of the same Human Principal across devices is by standing wave, not by
  shared key material.
- Mycelial Substrate v0.2 L1: SEC-E ratified V1-V10 verdicts (fact_class
  boundary, bi-temporal indexes per Snodgrass 1995, HLC per Kulkarni-
  Demirbas 2014, gate composition, PQC migration ladder Ed25519 → dual-sign
  → ML-DSA-65).

## Substrate primitives in use

- Canonical form: RFC 8785 JCS (JSON Canonical Form). Byte-identical across
  language runtimes — Python `rfc8785` and the in-browser JS implementation
  shipped with this Bridge's PWA produce identical bytes for the same value
  tree.
- Content-addressable hashing: BLAKE3 (RFC 6962 Merkle tree shape, 0x00 leaf
  prefix, 0x01 node prefix per Semios Merkle v0.1).
- Clock: HLC (Kulkarni-Demirbas 2014). Causal partial order across
  asynchronous nodes without coordination.
- Wallet: Ed25519 (server-side keys) + P-256 ECDSA (browser WebCrypto). Both
  verified through a single algorithm dispatcher; pubkey format is
  self-describing by length (64-hex = Ed25519; 130-hex leading 04 = P-256
  SEC1 uncompressed).
- Sessions: JWT with EdDSA (Bridge-signed).
- L0 transport: Iroh content-addressable P2P (opt-in per `[iroh] enabled =
  true`).

## Operator surfaces

- [GitHub — Walsh-Karra-Holdings-Global/semios-canon](https://github.com/Walsh-Karra-Holdings-Global/semios-canon): canonical substrate spec, brand canon (Aperture v1.0), Three Seals (L1 Σ Stamp, L2 Threshold, L3 Triad).
- [GitHub — wkh-canon-archive](https://github.com/Walsh-Karra-Holdings-Global/wkh-canon-archive): governance canon (WKH-C-NNN registry), SEC-E Cut-Review Protocol, Π/Pi-doctrines.
- [GitHub — semios-workspace](https://github.com/Walsh-Karra-Holdings-Global/semios-workspace): Bridge + PWA + dashboard, installer scripts (macOS launchd, Windows Service via NSSM), briefings.

## Optional

This Bridge runs the substrate at edge-headless scale. To deploy your own
node:

- macOS: `installer/install.sh` (Python venv + launchd LaunchAgent).
- Windows: `installer/install.ps1` then `installer/install-services.ps1`
  (NSSM-wrapped Windows Service, LocalSystem in session 0).
- Linux: Python venv + systemd unit (canon-aligned but installer not yet
  shipped).
- Browser (any platform): open this URL — the PWA loads, generates the
  device keypair, and is ready to write the moment your pubkey is added to
  the operator's `bootstrap_pubkeys`.