nthlayer-core

Tier 1 of the NthLayer ecosystem. Reliability-critical HTTP API server: verdict store, case management, change-freezes, manifest catalogue, heartbeats, component state.

pip install nthlayer-core
nthlayer serve --host 0.0.0.0 --port 8000

What it is

nthlayer-core is the single source of truth for the NthLayer runtime. It owns the SQLite store, exposes an HTTP API, and is the only component that touches the database. Tier 2 workers (nthlayer-workers) and the Tier 3 operator TUI (nthlayer-bench) talk to core exclusively over HTTP — never directly to SQLite.

Core availability = product availability. Worker failure is degradation; core failure is an outage.

• Stateful, no LLM. Pure transport. Decisions live elsewhere.
• Python · Starlette · uvicorn · SQLite (WAL).
• Apache 2.0 licensed.

Why a single API server

The v1.5 architecture moved away from per-component SQLite databases for two reasons:

1. Lineage and case state need a single consistent view. A verdict written by the measure module must be linkable from a case opened by the bench TUI without cross-DB joins.
2. Workers should be replaceable. Any worker can crash, restart, or be re-deployed without touching shared state. Core holds the state; workers hold cursors.

HTTP API surface

Core exposes the following resources. All responses are JSON. Verdicts are immutable — the outcome_resolution pattern creates a NEW verdict with parent_ids=[original_id] rather than mutating the original.

Priority derivation

Cases without an explicit priority are derived from blast_radius + has_active_incident:

Configuration

For step-by-step deployment, troubleshooting, and Litestream hardening, see docs/deploying.md.

Schema (v1.5.0)

10 tables, string IDs, JSON TEXT content:

• verdicts — immutable records with lineage
• assessments — non-decision component outputs
• cases — bench domain model with lease management
• change_freezes — RBAC §7 freeze documents
• heartbeats — component liveness (upsert per instance)
• component_state — persistent worker state across restarts
• suppressions — suppression audit trail
• rekor_anchors — empty in v1.5; populated in v2 (forward-compat)
• lineage — pre-computed transitive closure for fast ancestor/descendant queries
• schema_meta — schema version

WAL mode + PRAGMA synchronous=NORMAL + busy_timeout=5000. Thread-local connection pool. BEGIN IMMEDIATE for all writes. Retention is policy-driven (verdicts only pruned when old AND no younger descendants AND no surviving case references); rekor_anchors are never pruned.

CLI

nthlayer serve [--host 0.0.0.0] [--port 8000]   # start the HTTP server
nthlayer -V                                       # print version

NthLayer ecosystem

nthlayer-core is one of seven repos. Each component works alone; composition happens through OpenSRM manifests + the core HTTP API.

Licence

Apache 2.0