STEP 1
LABEL
Identify · 5 lines of Dockerfile
Attach OCI standard labels (org.opencontainers.image.*) and R2K labels (com.releaseasknowledge.*) to declare release identity.
Ship knowledge with the artifact, not just the binary · R2K v1
The past decade pipelined our code — git, CI/CD, registries, helm. The next decade will pipeline everything around code.
The knowledge in your team's heads ships when a new version goes out ──
but that knowledge does not travel with the image.
The R2K Thesis
From "ship a binary" to "ship knowledge" — R2K v1 unfolds as four incrementally-adoptable steps. Each has its own tooling and validation.
Attach OCI standard labels (org.opencontainers.image.*) and R2K labels (com.releaseasknowledge.*) to declare release identity.
At build time, dump OpenAPI / DB schema / config / SBOM into /r2k/, with /r2k/index.yaml as the entry index.
Diff two releases' snapshots across assets, producing a unified change.yaml. One plugin per asset class.
Correlate diffs across assets into risk insight. Plug in LLMs, rule engines, or policy-as-code; emit an R2K badge.
R2K is not a product. Not a tool. Not a vendor. It is a thesis with eight principles — a description of how software releases should work, and rarely do.
The OCI image stores L1 (LABEL) + L2 (snapshots: API spec, DB schema, config) — these are facts. L3 (Change Manifest) is intelligence — computed from facts, not baked into the image.
git: commits store snapshots; diffs are computed.
SBOM: stores component lists; vulnerability scans are computed.
R2K does to OCI images what git does to source code.
API spec, config schema, migration plan, SBOM should ship, version, and circulate alongside the image — collected automatically at build time, not written by hand after the fact.
Knowledge like "which API broke", "which migration is dangerous", "which config is now required" cannot live in engineers' heads or PR descriptions. It must be structurally extracted at build time and made machine-readable.
Use OCI Referrers when you can. Use CycloneDX when you can. Use OpenAPI when you can. R2K integrates the outputs of existing industry tools — it does not reinvent them.
R2K serves support, sales, customer DevOps, auditors, and compliance teams — not developers (who already have git, PRs, Slack). Every output assumes the reader cannot read code or git logs.
High-frequency lightweight queries (version, case_type) use LABEL indexes (~50ms). Low-frequency heavy queries (SBOM, test report) use metadata layers (~300ms). Full deep queries use the Change Manifest.
R2K does not require a CI/CD rewrite. Start with 5 lines of Dockerfile at Level 1 — every level has independent value, adoption is incremental.
Change Manifest, License Manifest, Network Contract — structured yaml/json bridges tools, organizations, and human/machine readability. More precise than release notes, more current than wikis, more traceable than Slack threads.
Like SLSA, R2K is adopted gradually. Each level stands alone — "We are R2K Level 2" is as legitimate as "We are SLSA Level 3".
Docker LABEL · build-arg
All production images carry OCI standard labels (org.opencontainers.image.*) plus the R2K namespace (com.releaseasknowledge.*); any scanner reads them in milliseconds.
/r2k/* snapshots · index.yaml
+ OpenAPI, DB schema, config, SBOM, and runtime manifest baked into /r2k/, with index.yaml listing every asset and its sha256 for tamper detection.
change.yaml · diff plugin SPI
+ Unified change.yaml across API/DB/Config/SBOM. L3 is derived intelligence — computed from L1+L2; Mode A pre-computed / Mode B on-demand (see below).
OCI Referrers · badge · cross-org
+ Fully OCI 1.1, R2K artifacts travel across organizations, customer-side reads them offline, and an R2K badge (Level + Mode) is published.
L1 = Identify · L2 = Trust · L3 = Understand · L4 = Share
Turns "shipping software" into "shipping interpretable change intelligence".
L3 is derived intelligence — but when it gets derived has two legitimate options. R2K v1 introduces Mode A / Mode B so the same spec serves air-gap ISVs and SaaS vendors alike.
Computed in CI · attached to image
CI computes the Change Manifest ahead of time and attaches it to the image. Customer side needs no Diff Engine service.
Fit Air-gap on-prem ISVs; customer DevOps cannot reach back to vendor
Cost from→to pair is locked; rule upgrades require rebuild
Computed at query time
CI attaches only L1+L2 snapshots; the Diff Engine computes at query time. Any from→to combination is queryable.
Fit SaaS, connected enterprise, open-source tools
Cost First query slightly slower (cacheable); host the Diff Engine
For major releases, ship both: Mode A's default-pair manifest baked into the image (so air-gap customers can use it directly), and L2 snapshots kept complete (so connected customers can recompute any other combination via Mode B). The underlying mechanism is identical — what differs is when the manifest is computed.
| Dimension | Mode A | Mode B | Both |
|---|---|---|---|
| Air-gap friendly | ✓ Perfect | ✗ Service required | ✓ |
| Arbitrary from→to | ✗ Locked | ✓ Full | ✓ |
| Auto-benefit from rule updates | ✗ Needs rebuild | ✓ Automatic | △ Partial |
| CI integration complexity | ✓ Simple | ✓ Simple | △ Medium |
| Customer-side complexity | ✓ Simple | △ Connection required | △ Path-dependent |
| Best for | ISV / on-prem | SaaS | Hybrid |
R2K as a framework does not prescribe which — but Principle 1 (facts vs intelligence) makes both modes legitimate. The choice depends on whether your customer side can reach your service.
Clear boundaries make a thesis useful. R2K overlaps with several existing concepts but solves a different problem.
Want to go deeper into R2K? Here's a curated reading list — spec, narrative essays, and platform-specific re-tellings. Cite freely, share widely, push back hard.
A manifesto without action is decoration. Pick the path that fits where you are right now.
x-yourco-*) or new diff plugins.