[SKEEP-007]: Cartridge blueprints

[michalharakal]

Proposal document: docs/modules/ROOT/pages/skeep/007-cartridge-blueprints.adoc ()
Status: Draft
Branch: feature/skeep-007-cartridge-blueprints

Filed here because the change is to the cartridge specification; the number comes from the
SKaiNET SKEEP series and is registered there.

Trigger

• Docs structure for a long-lived area — a new normative chapter, two new JSON Schemas and the first tutorial section of the spec home.
• Compatibility / migration policy — spec v0.3 → v0.4: new optional manifest provenance fields; existing cartridges stay valid.
• Compiler / graph-export / runtime integration — the recipe pins the StableHLO export and the StableHLO → IREE compile step.

Summary

Today a cartridge carries its weights and compiled artifacts inside the package, pinned by digest. The spec says nothing about how those artifacts are produced: no download source, no conversion or quantization steps, no toolchain pin; "Developing a cartridge" is prose and OQ11 (reproducible builds) is open. That blocks publishing cartridges whose weights cannot or should not be redistributed from a source repository.

This proposal adds cartridge blueprints. A blueprint is the open part of a cartridge — API, descriptor template and a machine-readable recipe (fetch → convert → quantize → export StableHLO → compile → pack → sign → verify) with every source pinned by revision and SHA-256 and the toolchain pinned by version — and MUST NOT contain weights or compiled binaries. Materialization turns a blueprint plus a materialization profile (target, flavor, licence acceptance, declared inputs, signing key, optional source mirror) into a regular, spec-conforming cartridge whose manifest records the blueprint as provenance. The same mechanism covers private materialization: an organization builds full cartridges from a public blueprint and distributes them through its own registry (Mode C) without forking.

A design record is needed because this defines new terms, new schemas and a new relationship between source repositories and distributed packages that later cartridges, tools (atlas, hub) and adapters will rely on.

Related DARC features

• First two blueprints, in SKaiNET-developers/skainet-cartridge-blueprints (to be published): asr-moonshine-v2-streaming, nlu-functiongemma-270m.
• Gradle plugin sk.ainet.cartridge.blueprint (materializer reference implementation).
• Spec OQ11 (reproducible builds), OQ2 (carrier), ADR-012 (pack_dir), distribution Modes B and C.

Sub-issues

• SKEEP-007 proposal document + ADR-015
• blueprints.adoc normative chapter (terms, MUST/SHOULD, private materialization)
• cartridge-blueprint.schema.json, materialization-profile.schema.json, worked example
• Manifest schema: provenance.blueprint, provenance.materialization; verify_manifest.py example
• Spec v0.4: index.adoc cross-references, changelog, nav, roadmap, README
• Guides: tutorial "Build a cartridge from a blueprint", how-to "Materialize privately", explanation "Blueprint vs cartridge"

Status upkeep

• Proposal registered in the docs nav and the SKaiNET "Current Proposals" table
• Maintainer moved status to Accepted
• Implementation PR(s) linked here and flipped the proposal's Status: to Implemented