kolm  /  spec  /  codebase

kolm codebase: the production architecture in one sitting.

An honest map of the shipped runtime. Modules, trust boundaries, persistence, compile pipeline, and CLI surface, with line counts and source links.

kolm engineering . hello@kolm.ai

v1.0 . 2026-05-15 . citeable as kolm.ai/spec/codebase . source github.com/sneaky-hippo/kolmogorov-stack

1. Layout

kolm is a Node.js monolith. There is no microservice fan-out, no proprietary runtime, no Kubernetes assumption. One container serves the web surface, the API, and the compile orchestrator. A second container serves the GPU compile pool when LoRA training is requested; the CPU monolith remains the front door.

Total runtime surface is ~16k lines of plain JavaScript. The number is deliberate. We trade C++ throughput for an audit surface a single engineer can read in one sitting, which is the same trade Redis and SQLite made for the same reason. A regulated buyer who wants to walk every line before pinning a version can.

2. Request flow

A typical inference request crosses these boundaries:

client (CLI / browser / curl)
  --> Vercel edge (TLS, HSTS, CSP, X-Forwarded-* headers)
  --> Railway container (Node 20 process)
  --> server.js (Express, trust proxy=2, body-parser, route mount)
  --> src/router.js (auth middleware: parse API key, resolve tenant, rate-limit)
  --> route handler (compile, run, publish, pull, ...)
  --> src/store.js (atomic JSON write) | src/artifact.js (zip+hash) | src/receipt.js (HMAC)
  --> response (JSON or octet-stream)

The header chain is honored exactly twice: the trust-proxy hop count is 2 (Vercel + Railway), and X-Forwarded-Host is parsed for URL emission so publish responses show kolm.ai, not the upstream Railway hostname. No request reaches a handler without a tenant resolution; admin endpoints require a separate x-admin-token header.

3. Trust boundaries

Routes are partitioned into four classes by the middleware in src/auth.js:

The soft-auth pattern is load-bearing for the hub: the public discovery surface (kolm.ai/hub) and the authenticated owner surface (kolm pull org/private-artifact) hit the same URL with different headers. A 404 distinguishes "this artifact does not exist" from "you cannot see it," which is the same disclosure choice GitHub and Hugging Face make for private repos.

Cross-tenant isolation is enforced at the store layer, not at the handler layer. Every findOne / update / all call carries a tenant_id filter; a route handler cannot bypass it because the helper does not accept an admin override. Admin overrides live in a separate surface (src/admin.js) with its own audit trail.

4. Persistence

kolm today persists every durable byte to one of two places: the local container filesystem under ./data/ (JSON-on-disk) or inside a built .kolm zip file. There is no external database in the critical path; no Redis; no S3 in the request hot path. Capacity is bounded by the Railway volume.

The store layer writes are atomic in the POSIX-rename sense: every mutation produces a .bak sibling, then fs.renameSync swaps the new file into place. A process crash mid-write leaves the previous good state on disk. An in-memory LRU (src/cache.js, 2048 entries) shadows reads for hot paths.

This shape works because the durable surface is small: 8 JSON files, each well under the size at which streaming scans become slow. The pragmatic ceiling is on the order of 10k artifacts per tenant before we migrate to object storage; the plan is documented separately in the internal storage spec. The point of this section is to be honest about the shape today: JSON on disk, atomic rename, no replication, single container. Buyers who need replicated storage today should pin the enterprise plan, which runs the same code over Postgres + S3.

5. The compile pipeline

A compile is a 4-stage in-process orchestrator (src/compile.js):

1. Recall — optional namespace query. Pulls grounding chunks from the recipe registry. Skipped if the spec is fully self-contained.
2. Distill — pattern-mode synthesis (src/synthesis.js). Deterministic by construction. Optional Claude-mode is gated by ANTHROPIC_API_KEY and produces non-deterministic output; this is flagged in the receipt.
3. Decompose — snapshots the public recipe registry as the recipe pack pinned into the artifact.
4. Package — buildAndZip in src/artifact.js. Double-pass zip pass to give the K-score size axis stable bytes. Deterministic mtimes (epoch 0). Manifest hashed last.

The compile is fire-and-forget on the long-running stages: the HTTP handler returns a 200 + job_id immediately, and the orchestrator runs under setImmediate. The CLI polls GET /v1/compile/:id for status. On serverless deployments (Vercel, Lambda) the orchestrator runs synchronously instead, because the function process dies on res.end().

The compile is K-gated at the package stage: if the computed K-score falls below the recipe-declared min_k (default 0.85), the artifact is not written and the job ends in status=failed.kgate with the score breakdown in the failure body. Buyers see a precise reason ("accuracy axis 0.71 below floor 0.85") rather than a generic compile failure.

6. The CLI

The CLI is one file, cli/kolm.js, 9k lines. It ships as the kolm bin via npm i -g github:sneaky-hippo/kolmogorov-stack. Verbs available today:

The CLI has no third-party runtime dependency except a thin node-fetch shim for < Node 18 environments. Everything else is stdlib.

7. The verifier

A standalone verifier for the .kolm format ships at packages/sdk-ts. It is 262 lines of TypeScript, uses only node:crypto + node:fs/promises + node:zlib, and validates: deterministic ZIP structure, per-entry SHA-256, manifest CID, HMAC receipt chain. The CLI shells out to this same surface internally so verifier behavior is single-sourced. A buyer can ship the verifier into their compliance stack without taking a dependency on the kolm runtime.

Python and Rust verifiers (packages/sdk-python, packages/sdk-rust) implement the same surface against the same interop test pack. Byte-identical canonical-JSON, byte-identical CIDs, byte-identical receipt verification results across all three.

8. The hub

The verifiable central artifact hub (kolm.ai/hub) is four endpoints in src/router.js:

• POST /v1/hub/publish — auth + 20/min rate limit + 25MB cap + idempotent on SHA + 409 on name conflict with different SHA.
• GET /v1/hub — public list with q search and limit filter.
• GET /v1/hub/:owner/:name — metadata. 200 for anon on public artifacts, 404 for anon on private, 200 for owner on either.
• GET /v1/hub/:owner/:name/download — octet-stream + X-Kolm-Sha256 header for client-side verify.

Handles look like org/artifact-name@sha256:64ec88ca. The SHA suffix is optional in the URL space (the route is 2-segment) but the CLI parses it client-side and fails closed if the downloaded bytes hash differently. The pattern is the same as Docker image digests: a pin you can put in a Dockerfile and know the bits match the audit.

9. Receipts and the audit trail

Every compile and every run emits a receipt. Compile receipts live inside the .kolm (receipt.json + the 4-ring HMAC chain in artifact.kolm/credential.json). Run receipts append to data/invocations.json server-side and are returned in the JSON body to the CLI. Both kinds share the same HMAC-over-canonical-JSON shape defined in RS-1 §3.

The X-Audit-Chain response header on every /v1/run/* response gives a 12-byte prefix of the receipt HMAC so a buyer can grep their proxy logs for forged traffic later. The receipt secret is per-tenant; an issuer or any party with the shared secret can re-verify the chain offline.

10. What this codebase is not

To be useful, this page has to be honest about what we do not do today:

• No durable storage in the open-source runtime. The default deployment writes JSON to a container disk. The enterprise plan runs the same code over Postgres + S3; the source for that adapter lives in a separate private repo.
• No external queue. Compile jobs run on the same Node process that serves HTTP. The GPU compile path enqueues to a managed queue when the request crosses into a real LoRA training job, but the orchestrator entry is still the monolith.
• No load balancer in the open-source path. One container, vertically scaled. The enterprise path runs N containers behind a CDN.
• No proprietary inference engine. Local inference goes through llama.cpp or the buyer's chosen runtime. We do not ship our own kernels.
• No telemetry phoning home. The shipped binary never emits to a kolm-controlled endpoint. The hub is opt-in. Audit logs stay on the buyer's disk.

11. Reading order

If you have an hour to verify the surface, read in this order:

1. server.js (330 LOC) — the entire HTTP shape.
2. src/auth.js (~700 LOC) — trust boundaries and tenant resolution.
3. src/router.js (3,644 LOC) — every route handler. Search for PUBLIC_API to find the soft-auth list.
4. src/artifact.js (567 LOC) — the canonical-JSON manifest builder and ZIP layout.
5. src/receipt.js (~180 LOC) — HMAC chain. Constant-time compare.
6. cli/kolm.js (9k LOC) — only if you want to verify CLI behavior.

Total: about 5k LOC of load-bearing server code. A staff engineer reads it cold in an afternoon.

12. License

The entire codebase is Apache-2.0. The RS-1 spec is MIT. The intent is that any runtime — ours, a competitor's, an academic project — can implement the format without asking permission and ship the verifier in a regulated stack without legal review.