Architecture

USL is layered:

usl-convert (TS)        cross-harness conversion  ── depends on ASP schema
      │
usl-capture (Rust)      live capture: file-boundary ingest + framing
      │  depends on
usl-core (Rust)         storage engine: append-only, crash-recoverable, schema-agnostic

• usl-core owns the on-disk format, the query API, durability, and recovery.
• usl-capture frames arbitrary byte streams into complete lines and appends them as records.
• usl-convert maps harness-native formats to and from the ASP canonical schema.
• usl-fuse (paused) was the FUSE mount layer — blocked by the lack of a usable FUSE on macOS 26.

RFC 0001 adds a query plane above the canonical ASP projection: SessionQL/Query IR, rebuildable structured and search sidecars, fixed asOfSeq snapshots, lineage, Insights, subscriptions, Resume descriptors, and an optional read-only SQL attachment. These are draft contracts, not yet all implemented in usl-core.

Interactive diagram

The full isometric architecture map shows modules, districts, data flows, and source-backed implementation notes:

Open the architecture map

The map is derived from docs/architecture/wiki/ and rebuilt by docs/architecture/verify.mjs; every claim traces to a source file with a content hash. Run npm run lint:architecture to verify freshness after code changes.