kolm  /  spec  /  kolm-format v1

The .kolm file format, v1.

A deterministic, content-addressable ZIP container for a compiled task recipe. Versioned, citeable, community-feedback open. Apache-2.0.

kolm engineering . hello@kolm.ai

v1.0 . 2026-05-16 . citeable as kolm.ai/spec/kolm-format-v1 . feedback github issue

1. Container

A .kolm is a standard ZIP archive (PKWARE APPNOTE 6.3.10, store-only compression) holding text-only members. The compression is fixed at STORE (no DEFLATE) so the inner bytes are directly verifiable without re-decompressing.

Why ZIP. Every operating system already has a working unzip implementation. kolm eject <art>.kolm uses adm-zip on Node; a curious operator can run unzip -l my.kolm on Linux/macOS or open it in Windows Explorer. There is no proprietary container.

Order in the archive central directory MUST be lexicographic. File mtimes MUST be set to 1980-01-01 00:00:00 UTC (the ZIP epoch) so two compiles of the same spec at different times produce byte-identical archives.

2. Canonical JSON

Every JSON entry in the archive uses a canonical encoding: UTF-8 without BOM, object keys sorted ASCII-ascending at every depth, no trailing whitespace, no comments, numeric form integer | decimal | -decimal without exponent. The pseudocode:

function canonicalize(value) {
  if (value === null || typeof value !== 'object') return JSON.stringify(value);
  if (Array.isArray(value)) return '[' + value.map(canonicalize).join(',') + ']';
  const keys = Object.keys(value).sort();
  return '{' + keys.map(function (k) {
    return JSON.stringify(k) + ':' + canonicalize(value[k]);
  }).join(',') + '}';
}

This is the same canonicalization RFC 8785 prescribes for JCS; we deliberately match it so external tooling (HSM signing, blockchain anchoring, third-party verifiers) can reuse off-the-shelf JCS implementations.

3. manifest.json

The manifest enumerates every other entry and binds them by content hash. A consuming runtime MUST recompute each entry's sha256 before trusting the artifact.

{
  "spec": "kolm-manifest-1",
  "artifact_id": "phi-redactor",
  "version": "1.0.0",
  "created_at": "2026-05-16T00:00:00Z",
  "files": [
    {"path": "spec.json",       "sha256": "<hex>", "size": 4831},
    {"path": "recipes/rcp_phi_redactor_v1.js", "sha256": "<hex>", "size": 1422},
    {"path": "pack.json",       "sha256": "<hex>", "size": 612},
    {"path": "index.json",      "sha256": "<hex>", "size": 188},
    {"path": "evals.json",      "sha256": "<hex>", "size": 2204},
    {"path": "k_score.json",    "sha256": "<hex>", "size": 322},
    {"path": "receipt.json",    "sha256": "<hex>", "size": 491}
  ]
}

4. Recipes

A recipe is a JavaScript function with the signature generate(input, lib). The runtime evaluates it inside a sandbox with no access to require, fs, net, process, or globalThis — only the lib object kolm injects (defined in src/library.js).

function generate(input, lib) {
  // 'input' is whatever the caller passed:  { text: string } by convention,
  // but arbitrary JSON is accepted.
  // 'lib' is a small fixed dictionary:
  //   lib.patterns    regex primitives (email, phone, url, date, ipv4, price)
  //   lib.pack        the artifact's bundled pack.json (may be undefined)
  //   lib.params      caller-supplied extras (params.extra_categories, etc.)
  //   lib.parseFloatSafe   helper that returns NaN instead of 0 on bad input
  //   lib.zscore, lib.vote, lib.any, lib.all   small stat helpers
  // Recipes return any JSON-serializable value.
}

Determinism rule. A recipe MUST be a pure function of (input, lib). No Date.now(), no Math.random() (unless seeded through lib.params), no syscalls. The K-score loop runs each eval case 3x and rejects non-determinism with a score-zero penalty.

5. K-score

The K-score is the gate. Compiles that fall below the gate (default 0.85) emit a .kolm with k_score.gate_passed: false AND exit non-zero from kolm compile, so CI fails. The five axes:

Composite: K = 0.40A + 0.15S + 0.15L + 0.15C + 0.15V. The k-score page has worked examples; the methodology doc defines edge cases.

6. receipt.json — the HMAC chain

Every .kolm ships a four-ring HMAC chain that re-signs as you reach inward: manifest -> spec -> recipes -> pack. The outer ring binds the artifact identity; the inner rings let a verifier prove which subset they checked. Verification uses crypto.timingSafeEqual to defeat timing oracles.

{
  "spec": "rs-1-receipt",
  "version": 1,
  "rings": [
    {"name": "manifest", "hmac_sha256": "<64-hex>", "covers": ["manifest.json"]},
    {"name": "spec",     "hmac_sha256": "<64-hex>", "covers": ["spec.json", "k_score.json"]},
    {"name": "recipes",  "hmac_sha256": "<64-hex>", "covers": ["recipes/*"]},
    {"name": "pack",     "hmac_sha256": "<64-hex>", "covers": ["pack.json", "index.json", "evals.json"]}
  ],
  "signer": {"kid": "<tenant-key-id>", "alg": "HMAC-SHA256"},
  "issued_at": "2026-05-16T00:00:00Z"
}

The HMAC key defaults to a per-user secret at ~/.kolm/config.json. Teams sharing a signing key set RECIPE_RECEIPT_SECRET in env so receipts verify across machines without trusting any individual user.

7. Loading and running

Any conforming runtime (the kolm CLI, the kolm server, the MCP adapter, the edge SDK, a third-party port) MUST execute these steps in order before producing a result:

1. Open the ZIP; refuse if compression method != STORE on any entry.
2. Read manifest.json; recompute sha256 over every listed file; refuse on mismatch.
3. Read receipt.json; verify the four-ring HMAC chain with timingSafeEqual; refuse on mismatch.
4. Read k_score.json; refuse if gate_passed === false AND caller did not pass --allow-failing.
5. Read spec.json; load each recipes/<id>.js; sandbox-instantiate.
6. Bind lib.pack = pack.json if present; lib.index = index.json if present.
7. Call recipe.generate(input, lib). Return the value.

Failures at steps 1-4 return exit 5 (CHECKSUM_FAIL). Failures at step 5-7 return exit 2 (RUNTIME). The CLI also surfaces a one-line diagnostic on stderr so an operator does not have to grep the JSON for "why".

8. Stability guarantees

v1.0 is frozen against the following promises through at least 2027-12-31:

• No breaking changes to manifest layout. Entries may be added but existing keys keep their meaning.
• Canonical JSON stays RFC 8785-compatible. A v1 reader will keep verifying v1 artifacts forever.
• K-score formula is fixed. The 0.40 / 0.15 x 4 weighting will not move within v1. A new weighting ships as v2.
• Receipt chain remains HMAC-SHA256 + four rings. Ed25519 receipts are planned for v2 as a side-by-side option, not a replacement.
• Apache-2.0 licensed. The spec is free to implement; the reference implementation is free to fork.

9. What this format is not

Honesty section. .kolm is explicitly out of scope for:

• Model weights. If a recipe wraps a base model, the model weights ship separately. .kolm stores the spec, the recipe code, and the receipt; it does not store gigabytes of tensor data.
• Prompt history. The artifact has no notion of conversation. Distillation captures live elsewhere (see /learn/distill-openai-usage).
• Telemetry. A loaded .kolm never phones home. The runtime decides whether to ship a receipt to a hub; the artifact itself has no network surface.
• Encryption. Files inside the ZIP are plaintext. If the contents are sensitive, encrypt the ZIP itself or the storage medium. Receipts and HMAC chain do not equal confidentiality.

10. Reference implementation

The reference implementation lives in this repo:

• Writer: src/artifact.js — takes a spec + eval results, emits a .kolm file.
• Reader: src/artifact-runner.js — loads a .kolm from disk, verifies, evaluates.
• Receipt: src/receipt.js — canonical-JSON HMAC-SHA256 with timing-safe verify.
• Library injected at runtime: src/library.js — the lib object recipes receive.
• CLI surface: cli/kolm.js — compile, inspect, run, eject, verify, publish, pull.

A third-party reader in Go, Rust, or Python is on the roadmap for v1.1; community ports are welcome and will be linked from this page once they pass the v1 conformance suite (under scripts/conformance/ in the repo).

11. Worked example

The kolm-verified/phi-redactor artifact from /hub is the canonical reference example. 5.4 KB, K-score 0.988, gate 0.85, license Apache-2.0. To inspect it byte-for-byte:

curl -fLO https://kolm.ai/registry-pack/phi-redactor.kolm
shasum -a 256 phi-redactor.kolm
# sha256 here matches the manifest entry on /hub

kolm inspect phi-redactor.kolm
# K-score: 0.988  base: none  gate: 0.85  recipes: 1

kolm eject phi-redactor.kolm --out ./phi-extracted
ls phi-extracted/
# manifest.json  spec.json  recipes/  pack.json  receipt.json  k_score.json  EJECT_README.md