Spec registry

Foundational contract: authored truth lives only in markdown (+ YAML frontmatter); machine-consumable truth is compiler-emitted JSON only; every artifact is a deterministic function of (config, file contents); a typed authority graph governs who-owns-what.

The architecture thesis and the app shell. Encore.ts is kept as the application framework while its managed-infrastructure coupling is severed: in-process hiqlite replaces Redis, CoreLedger on libSQL/Turso replaces Encore SQLDatabase, and rauthy ships inside the app image as the OIDC IdP. One Docker image plus one volume is a complete authenticated application. This spec owns the repo-shell units (Encore app manifest, TypeScript and test configuration, the health service) and anchors the root package; each subsystem is governed by its own spec (002-007). This repository is enrahitu (EnRaHiTu: Encore.ts + rauthy + hiqlite + Turso; formerly enrahi / enrahi-kit): the Encore toolchain is vendored and driven directly via napi-rs instead of through the encore CLI (spec 008), and the repo doubles as the template chassis the Statecraft factory stamps (spec 009).

The hiqlite runtime embedded in the Node process: a napi-rs cdylib (@enrahitu/hiqlite-native) exposing init/health, TTL'd KV, and counters, plus the thin `hiq` Encore service that starts the node at service load and fronts the addon over HTTP. Replaces Redis for cache and rate-limit state with zero extra processes.

The durable data layer: stage-3 @Entity/@Column decorators over a LedgerDriver interface, with a libSQL driver speaking a local SQLite file by default and Turso embedded-replica sync (syncUrl + authToken) when configured. ensureSchema() creates tables from decorator metadata; typed repositories give find/save ergonomics. Replaces Encore SQLDatabase so no managed database is required to develop, build, or ship.

The authentication core, re-based from template-encore apps/api onto enrahitu's own substrate: stateless RS256 JWT access tokens in httpOnly cookies, rotated DB-backed refresh tokens, CSRF double-submit, roles, and audit records on CoreLedger; login rate limiting on hiqlite counters. Drivers are pluggable: mock (dev) here, rauthy OIDC in spec 005 (which owns backend/auth/rauthy.ts inside this spec's directory claim).

rauthy as the OIDC IdP, reached exclusively through the app's own origin: the idp service mounts /auth/* as a raw passthrough proxy onto rauthy (RAUTHY_UPSTREAM, default 127.0.0.1:8081), so issuer, callback, and SPA share one origin with no CORS. backend/auth/rauthy.ts is the OIDC authorization-code + PKCE driver (login redirect + callback) plugged into spec 004's driver registry. Dev runs rauthy via docker compose with the same declarative client bootstrap the container uses in prod.

The minimal frontend: a Vue 3 + Vite SPA (login, OIDC callback handoff, /me, logout) built from frontend/ into backend/web/dist, and the `web` Encore service that serves the built bundle as static files from the app's own origin. No separate frontend host: the same container serves UI, API, and IdP.

The deliverable image: one container running rauthy (loopback :8081) and the Encore app (:8080) under a die-together entrypoint, all durable state on a single /data volume, every secret self-provisioned at first boot. scripts/docker-build.sh builds from a clean git worktree of HEAD, injects the cross-built addon, the built SPA, and production node_modules, runs `encore build docker`, asserts the base-image entrypoint, and layers rauthy + the entrypoint on top.

The enrahitu fork point: the Encore runtime is vendored (upstream encoredev/encore @ v1.57.9) and driven directly via napi-rs, removing the encore CLI from every flow. vendor/encore/ carries the rust core (runtimes/core), the napi bindings crate (runtimes/js, built into encore-runtime.node), the TS parser/compiler (tsparser, the tsparser-encore binary), miniredis (a core path dependency), and the published encore.dev JS runtime package (the app's encore.dev dep is a file: link into it). The build drivers (build, dev run, esbuild bundling, infra-config augmentation, linux cross-build) were relocated to @enrahitu/toolchain (packages/toolchain/, spec 018); this spec retains the vendored source of record they build from.

The explicit, versioned interface between this template and the Statecraft factory. The factory learns how to stamp, verify, and package an app from this chassis by reading template.toml and nothing else. This replaces the implicit coupling that plagued the factory-encore / template-encore pair, where the shared assumption (the encore CLI, plus folklore about repo layout) lived in two codebases at once and drift surfaced only at stamp time. v0 shipped the contract file with verify and package verbs live; scaffold landed with the repoInit absorption (spec 014, contract 0.4.0) and deploy is permanently fleet-owned.

template-encore (the previous chassis, stamped by factory-encore) still owns four capabilities this template does not have: born-green CI workflows, the born-with certificate + agentic posture flow, Pages deployment, and repoInit seeding. This spec enumerates the absorption line items with their source locations and target shapes. When all four land here, template-encore retires as a chassis and the enrahitu repo is the only template the Statecraft factory stamps. LI-1 done 2026-07-14 (born-green stamp proven); each item flips to done individually.

The Postgres LedgerDriver that spec 003 stages as future work. The forcing function is the Statecraft control plane: it is itself an EnRaHiTu app but carries webhook bursts, audit writes, and multi-tenant state, so it runs CoreLedger-on-Postgres while stamped customer apps run CoreLedger-on-libSQL/Turso. Same decorator surface, different driver; the "scaling is a driver swap, not a rewrite" thesis is validated by running the exact spec 003 test suite, unchanged, against both drivers. Selection is by URL scheme; the driver owns dialect DDL, `?`-to-`$n` placeholder translation, and a minimal forward-only migration runner.

Every stamped app is born with a provenance certificate that states, at the moment of stamping, what it was stamped from and what agentic posture it was born under. The template owns the certificate's schema and its validator; the factory (statecraft) owns emission. This lands the reserved [provenance] contract table from spec 009 §3.3 and is absorption line item LI-2 of spec 010. Lineage: the born-with cert + agenticPostureBinding flow proven in the template-encore era; the design facts an implementer needs are inlined here, no external archive required.

An optional, off-by-default GitHub Pages workflow that stamped apps are born with: it publishes the built SPA (backend/web/dist) as a static preview site when the repo owner enables Pages. Absorption line item LI-3 of spec 010. Not a contract verb: it is CI-side, not factory-side. The workflow must be inert (skip cleanly, not fail) in repos where Pages is disabled, which is the default posture.

Moves stamping logic from "factory-side folklore" into the template itself: a scaffold verb the factory (or a human) invokes inside a fresh clone of this repo to turn it into a named app. Slot substitution, lockfile discipline, registry regeneration, and certificate placement all live in one script with one contract entry. Absorption line item LI-4 of spec 010; fills the scaffold verb reserved by spec 009 §3.2 and bumps the contract to 0.4.0.

Makes the frontend slot real by adding a second allowed value: react-rr7. A parallel SPA source directory (frontend-react/, React 19 + React Router v7 in SPA/data-router mode + Vite) builds into the same backend/web/dist that the web static service serves, hitting the same auth and API endpoints as the Vue SPA (spec 006). The scaffold verb selects the flavor at stamp time; the chassis never ships both to a stamped app.

The single-container image (spec 007) currently ships arm64 only, matching the development Macs. Fleet targets (Hetzner x86 nodes, most customer clusters) need linux/amd64. This spec extends the cross-build pipeline (scripts/encore/build-runtime-linux.sh and scripts/docker-build.sh already take an arch argument) to produce and verify an amd64 image, and wires an optional CI path so the capability cannot silently rot. Owed item carried from the enrahi phase-7 close-out.

The rauthy driver's full browser round-trip (SPA -> same-origin /auth proxy -> rauthy login UI -> OIDC callback -> app session cookie) has been exercised by hand but never by an automated end-to-end test; this was the standing owed item from the enrahi phase close-out. This spec adds a Playwright-driven e2e that boots the app plus the dev rauthy (docker compose, spec 005), completes a real password login in a real browser engine, and asserts the session, profile, and logout behavior. Kept out of the default verify verb; runs as its own npm script and an optional scheduled CI job.

The heavy invariants leave the template tree and become versioned npm packages with prebuilt binaries: @enrahitu/toolchain (the vendored Encore build drivers + encore-runtime.node + tsparser, per-platform) and @enrahitu/hiqlite-native (the addon, prebuilt). The template drops from ~780 tracked files to a surface a developer can read in one sitting, and a chassis upgrade becomes a devDependency bump instead of a tree re-import. Decided 2026-07-14 to land BEFORE statecraft's app-shell import (statecraft spec 002), so the first template consumer never duplicates the fat tree. The build contract is unchanged where it matters: a stamped app still builds with npm + cargo-free installs and NO proprietary tool; the Statecraft CLI never becomes a build daemon.

After spec 018 sheds the toolchain payload, the remaining tree is restructured into two directories a developer understands at first glance: frontend/ (the SPA, one directory per flavor lifecycle) and backend/ (every Encore.ts service plus the shared lib and CoreLedger). Decided 2026-07-14, chosen over client/apis and app/services because frontend/backend is the pair with zero ambiguity. All Encore.ts concerns co-locate under backend/, which is what makes the chassis easy to reason about; everything else at the root is contract, packaging, or governance. Lands before statecraft spec 002 so the first template consumer imports the simple shape.

Foundational contract: authored truth lives only in markdown (+ YAML frontmatter); machine-consumable truth is compiler-emitted JSON only; every artifact is a deterministic function of (config, file contents); a typed authority graph governs who-owns-what. This repository is born governed: the spine exists before the first line of product code.

The product thesis and the consolidation record. statecraft is the control plane for governed AI-native software delivery: intent becomes a governed spec, the factory stamps an application from the EnRaHiTu template, the fleet operates the resulting hermetic containers, and the customer's code lives in the customer's GitHub org the entire time. statecraft is itself the first production EnRaHiTu app: one container, embedded rauthy as the platform IdP, hiqlite in-process, CoreLedger for durable state (on Postgres via enrahitu spec 011). This spec records what consolidates here from the OAP era and the milestone ladder that orders the build.

statecraft becomes a running EnRaHiTu app: the slimmed chassis from statecrafting/enrahitu is brought into this repo (the two-directory backend/ + frontend/ layout, CoreLedger, auth baseline, rauthy proxy, health, packaging, verify workflow; the Encore toolchain and the hiqlite addon arrive as pinned @enrahitu/* npm packages, not vendored source), stamped with app name "statecraft". After this spec the control plane boots, authenticates, and tests green; every later service spec (004+) adds Encore services onto this shell. This is deliberate dogfooding: the platform is stamped from the same template it will stamp for customers.

The control plane runs CoreLedger on the Postgres driver while stamped customer apps stay on libSQL/Turso: same decorator API, different driver, selected by URL scheme. The driver itself is enrahitu spec 011 and lives in the chassis (core/ledger/postgres.ts); this spec is the consuming side: local Postgres for dev, config wiring, the migration posture for control-plane tables, and proof that the whole chassis test suite passes on both drivers inside this repo.

The tenancy spine of milestone M2: a user authenticates against the control plane (embedded rauthy, chassis auth), creates a tenant, and installs the statecraft GitHub App into their own GitHub org; from then on everything the platform does for them keys off the installation_id and happens inside their org. Nobody joins our org; code sovereignty is the product's first-class property. This spec owns the tenants service: tenant + installation records on CoreLedger, the App installation handshake, webhook receipt, and an installation-token mint helper the factory (spec 005) consumes.

The factory turns "customer wants an app named X" into a born-green repo in the customer's GitHub org: clone the pinned enrahitu template, read its template.toml contract (and nothing else), run the scaffold verb with the slot values, emit the born-with certificate and anchor it in the governance ledger, then land it: create a new repo and push (create mode) or open a pull request onto an existing repo (adopt mode), and watch the born-with verify workflow until green. Completes milestone M2 together with spec 004. The contract boundary is absolute: any factory behavior that depends on template internals beyond template.toml is a defect.

Milestone M3: operate stamped apps. The unit of placement is "one EnRaHiTu container + one volume + one ingress" on the existing hetzner-k3s cluster. deployd-api-rs (the OAP-era Rust K8s orchestrator, axum + hiqlite) donates its orchestration core as a napi-rs addon (the hiqlite-native pattern): the axum HTTP layer disappears, the K8s knowledge stays. A fleet/ Encore service exposes deploy / status / update / backup over the addon. Done-when is a fleet of ten stamped apps on one box with update and backup exercised.

Replaces the chassis's placeholder Vue SPA with the control plane's real face: a Vite + React Router v7 single-page app served by the chassis web service from web/dist, same-origin with the API and the embedded rauthy IdP. v1 surface: login, tenant list/create, GitHub App install flow, stamp launcher + job progress, fleet table with operation buttons. The platform UI is deliberately NOT a template flavor: it owes nothing to template stack choices (thesis §3).

The platform's tamper-evident memory and its decision spine, built on the four crates extracted from OAP's policy-kernel: attest-ledger (tamper-evident record chain + signed anchors), canonical-keysort-json (byte-identical canonical JSON), action-gate (pure deterministic Gate over an ordered Check registry), and trust-window (rolling-window trust scorer mapping to graduated privilege). A napi-rs addon wraps the Rust crates; a governance/ Encore service exposes record/verify/gate/trust APIs that factory (005) and fleet (006) call at their privileged moments. This is the platform's differentiator: not that it deploys apps, but that every privileged act is gated, recorded, and independently verifiable.

Give statecraft its own deployment story so the spec-governed control plane runs on the statecraft-owned cluster (spec 010) with no dependency on the open-agentic-platform (OAP) chart, CD, or secret set. Publish the single-container image to statecraft's own GHCR namespace (stage 1, done), then stand the control plane up on the 010 cluster as a platform-grade K8s deployment reachable at app.statecraft.ing, wired to the real Encore secret contract and seeded with its own rauthy client. Port the OAP CI tooling worth keeping (AI PR review + changelog, the PR gate pattern), adapted to be OAP-free.

statecraft does not own the cluster it runs on: the nodes are named for OAP, and Flux reconciles this cluster from the open-agentic-platform repository. Build a statecraft-owned hetzner-k3s cluster alongside the existing one, reconciled by Flux from a statecraft-owned GitOps tree, with one documented secret source that generates both the local-dev `.env` and the SOPS-encrypted cluster secrets Flux decrypts in-cluster. Stand up the platform services (cert-manager, ingress-nginx, rauthy, Postgres, NSQ, minio, prometheus/grafana), cut DNS when proven, then delete the old cluster. Blue-green at the cluster level: rollback is a DNS change.

Foundational contract: authored truth lives only in markdown (+ YAML frontmatter); machine-consumable truth is compiler-emitted JSON only; every artifact is a deterministic function of (config, file contents); a typed authority graph governs who-owns-what. This repository is born governed: the spine exists before the first line of product code.

The successor to OPC (the retired Tauri desktop cockpit): a single binary named statecraft that exposes the platform's governance verbs twice, as CLI subcommands for humans and as an MCP server for agents. The MCP face is the product's genuinely unique surface: any agent (Claude Code first) operates natively under Statecraft governance, requesting approvals, checking spec-code coupling, and triggering factory stages. This is milestone M4 in the Statecraft ladder; the spec records the thesis and the decided constraints so the repo is born governed ahead of its build.

The Rust crate for the single binary named statecraft: clap-based command tree, layered configuration (flags > env > config file), structured output discipline (human tables on TTY, JSON with --output json), and a CI workflow (fmt, clippy -D warnings, test, release build). No network calls yet; spec 003 adds auth and the API client. After this spec, `cargo install --path .` yields a binary whose skeleton every later verb hangs off.

The binary learns to authenticate against a Statecraft control plane and speak its API. Auth v1 is a browser-assisted session-cookie handoff (the control plane's chassis auth is cookie based, and the embedded rauthy exposes OIDC; the exact mechanism is DECIDE-AT-IMPLEMENTATION between OAuth device-flow-style polling and a localhost callback, constrained below). Tokens/cookies are stored in a 0600 credentials file, never in the config file. An api module gives every later verb a typed, authenticated request path with consistent error mapping.

The CLI face becomes useful: the stub commands from spec 002 gain real implementations over the API client, mirroring the control plane's tenants (statecraft spec 004), factory (spec 005), and fleet (spec 006) services. Every verb has a stable JSON output shape, because spec 005 exposes these same verbs as MCP tools and the JSON is the shared contract between both faces.

Milestone M4's core: `statecraft mcp` runs a Model Context Protocol server over stdio exposing the governance verbs as tools, so a coding agent (Claude Code first) operates under Statecraft governance natively: listing tenants, launching and watching stamps, inspecting and operating fleets, all with the same auth, the same guards, and the same JSON shapes as the CLI face. The MCP face is not a privileged side door: it calls the identical verb layer from spec 004, and destructive guards (explicit posture, confirm-name) pass through to the agent verbatim.

The upgrade half of the 2026-07-14 packaging decision: templates stay small because the chassis ships as versioned npm packages (enrahitu spec 018), and upgrading a stamped app is a verb, not a migration project. `statecraft template upgrade`, run in a stamped app checkout, reads template.toml, bumps the chassis package pins, applies template-shipped codemods, runs the contract verify verb, and commits on a branch. The CLI orchestrates; all structure knowledge stays in the template and its packages. This verb is the boundary that keeps the CLI from ever becoming a build daemon.

Foundational contract: authored truth lives only in markdown (+ YAML frontmatter); machine-consumable truth is compiler-emitted JSON only; every artifact is a deterministic function of (config, file contents); a typed authority graph governs who-owns-what. This repository is born governed: the spine exists before the first line of product code.

The marketing and docs site, built as a fully static React Router v7 app (framework mode, prerendered, no SSR at runtime) deployed to GitHub Pages under statecraft.ing. Amended 2026-07-14: React Router v7 replaces the earlier Astro choice, harvesting the OAP-era statecraft web app (ecosystem content, the spec-registry viewer) and keeping the whole product family on one frontend stack. The registry viewer runs over build-time-baked shards from the public repos, so the site stays static and every claim stays checkable. The apex DNS cutover is authorized: the legacy control plane no longer owns the domain.

The words on the site at launch. One index page that states what Statecraft is in the builder's own register (creator-led, OSS-credible, no startup theater), a product-family section presenting the roster owned by spec 003, and an honest status section tied to the public milestone ladder. The positioning facts are inlined here so the implementing session needs no external archive.

The canonical registry of the Statecraft product family: each repo's name, role, SPDX license, and URL, encoded once in app/lib/product-family.ts and consumed by the index family section, the footer, and the /registry viewer's repoMeta lookup. This spec gives that module a single explicit owner so a roster change (a repo added, removed, or re-described) is an ordinary authoring edit here plus the module, with no coupling waiver and no edit to the scaffold (001) or launch-content (002) specs. It owns the roster data, not the rendering.

Restores the richer marketing experience the OAP-era statecraft web app carried, ported onto the static apex: a products/architecture page, a papers index with a full whitepaper reader (sticky TOC, reading-progress, scroll-spy, inline references) and an interactive clickable-SVG architecture explorer, and a get-started walkthrough. It expands the site chrome (Products, Papers, Get Started in the nav) and adds a sign-in link that hands off to the control plane's Rauthy OIDC flow at app.statecraft.ing/auth/rauthy. All content is re-authored to be truthful and checkable against the current public repos (no fabricated hashes, spec counts, signatures, or dead subsystems): the OAP name becomes Statecraft, and factory-encore / template-encore become enrahitu. The site stays fully static and prerendered, with zero runtime off-origin requests; sign-in is a plain outbound link, not an auth flow this site runs.