Cartridge — a concept in the SKaiNET universe

App-agnostic (structural: no product logic inside) and open-source (a licensing/business choice about the weights) are two different axes, and the contract only requires the first. A cartridge can be app-agnostic with open weights, or app-agnostic with commercially licensed / encrypted weights (Integrity, provenance, and weight-only updates, "Encrypted weights") that only decrypt once the host resolves a valid entitlement key. What must never happen is licensing terms leaking into the cartridge as code — a license-check, a call-home, a feature gate keyed off a product identity. Those are application policy and belong in the adapter or a provisioning service.

A cartridge is a derived work of everything it bundles: model weights (usually derived from a published checkpoint), calibration data, vendored runtime code, tokenizers. The manifest therefore records, per artifact, a license (SPDX expression or a marker like proprietary / community-restricted) and derived_from (what upstream it descends from). The cartridge’s declared effective license MUST be satisfiable given all of them — attribution carried, share- alike honored, notices shipped, usage caps respected. A build-time license gate enforcing this is Phase-2 tooling (roadmap); the manifest fields exist now.

Worked reality checks from the existing cartridges:

The descriptor’s license field states the effective license: an SPDX id for open weights; proprietary or a license/entitlement URL for gated ones (paired with an encryption block on the relevant artifact); NOASSERTION for a not-yet-remediated package — which conformance tooling treats as a failure, by design.

Performance and quality are measured on the stated target and reported honestly, including when they are not good enough (a cartridge may be RTF ≈ 2 on one ABI and ≈ 0.25 on another — both are true, both are stated). measured_on names the device/run; methodology points at the workload definition so the number is falsifiable, and internal infrastructure details (device IPs, hostnames) stay out of public descriptors.

flavors (ADR-014) is how one package covers several independently-addressable, independently-measured identities — Moonshine ships one AAR with an English base and a German flavor (different upstream checkpoints, different measured RTF); FunctionGemma ships one AAR with a Vulkan base and a CPU flavor (4× slower, no accelerator required). The base descriptor’s own fields stay the default flavor unchanged, so a host that predates ADR-014 still resolves correctly against them — flavors is purely additive. A flavor field, when present, replaces the base’s field of the same name in full (no deep merge); a host treats {base} ∪ {each flavor} as the complete set of identities the package exposes, applying every per-descriptor rule (mandatory quality for task=asr, etc.) to each one individually.

Every artifact a cartridge bundles (native runtime, model weights, tokenizer, calibration side data, the capability descriptor itself) is identified by a SHA-256 digest, not by name or path alone. A manifest lists every artifact’s role, path, digest, size, and license (Licensing: two rules, Rule 2), plus provenance (producer, build time, build inputs). The manifest’s own digest is computed over its canonical JSON with the signatures field excluded — that digest is what gets signed, and it is also how one manifest pins another: by digest, never by a mutable tag.

Granularity rule: an artifact is addressable only if it is a distinct file. A blob baked into a compiled binary (the ORT Moonshine cartridge bakes its 21.4 MB Silero VAD model in as a C array) is covered only by the containing binary’s digest — meaning it cannot be weight-updated or license-tracked independently. Cartridge builds SHOULD keep model data as file artifacts; where baking in is unavoidable, the manifest records the containing binary’s derived_from accordingly.

The manifest carries one or more detached signatures (keyid, alg, signer, signature, signed_at). Ed25519 over the manifest digest is the default choice: small keys and signatures, fast to verify on a constrained device. A host verifies a cartridge before load by: recomputing every artifact digest and comparing it to the manifest, recomputing the manifest digest, and checking the signature(s) against a trust store of keys it already holds for that cartridge id — pinned at provisioning time or delivered via the registry (OQ4), never shipped inside the artifact it is meant to authenticate. Where verification actually runs, per deployment shape, is defined in the threat model — for the common build-time-staged shape it is the CI staging step, not the device, that runs this check.

A runnable proof lives in examples/: schema, signed example manifests, and verify_manifest.py (stdlib+openssl, no crypto dependency). Legitimate manifests verify; flipping a single field breaks the signature.

[direction] — modeled and schema-supported; no producing pipeline exists yet in this ecosystem. The design is here so the first fine-tune or federated round lands in a prepared shape, not so anyone believes it runs today.

The runtime + tokenizer + code of a cartridge changes rarely; the weights are expected to change often — a new fine-tune, a quantization pass, or a federated-learning aggregation round. Weight-only updates are modeled as a distinct, separately-signed object:

Verification gate (v0.2 — replaces the v0.1 wording). A weight update is supposed to change outputs — "parity with the previous weights" is a vacuous check. What a weight update MUST pass before publication:

This also motivates a second trust role: the party allowed to sign a base cartridge (the publisher) is not necessarily the party allowed to sign a weight update for it (a training/aggregation service). A host’s trust policy authorizes keys per role per cartridge id — the shape TUF uses for root vs. targets keys (OQ6). The worked example signs the base with a publisher key and a federated round-17 update with a separate aggregator key.

Signing proves authenticity and integrity; it does not provide confidentiality. For weights that are commercially sensitive, the manifest supports an optional encryption block on a weights artifact: an algorithm (e.g. AES-256-GCM) and a key reference — never the key itself — that the host resolves through its own provisioning (a secure element, a device key store). Encryption and signing are independent controls.

This pattern already exists in this codebase for a different target: SKaiNET’s Minerva secure-MCU export (skainet-compile-minerva in SKaiNET) provisions a device key outside the generated bundle, redacts key material from its manifest, and verifies inference against that key. The cartridge manifest generalizes exactly that pattern — external key, redacted from the shipped artifact, resolved by the host at load — to NPU/ORT/IREE cartridges.

Packaging needs an explicit build step (a Gradle task in the JVM/Android world) that per declared target: resolves the matching cartridge variant, verifies its manifest (Integrity, provenance, and weight-only updates), stages its artifacts into the app bundle, and generates the typed bindings (typed facade) from the descriptor. Precedents already working in SKaiNET: Minerva’s gated host-verification task and the NPU cartridge builder’s convert-then-verify flow. If a declared target has no compatible cartridge for a required capability, the build step is where that surfaces — as a build-time warning or failure, not a runtime crash on a user’s device.

An artifact marked delivery in the manifest (ADR-009: Google Play Asset Delivery, Apple On-Demand Resources/Background Assets) is verified here exactly like any other — the only difference is where the staging step puts it afterward: a platform asset pack instead of the main bundle. See threat-model.adoc, Shape A′ for what changes (and what doesn’t) about verification once such an artifact lands on-device.

Selection among candidate cartridges for a required capability, per target:

family (v0.2) replaces v0.1’s fallback_of. fallback_of made the fallback enumerate the natives it stood in for — so every new native cartridge forced an edit + re-sign + re-release of its fallback, and the worked example (Moonshine standing in for Whisper) violated the "same model family" definition anyway. Under v0.2:

A portal that lists cartridges (searchable by descriptor fields) and serves them: content-addressed artifact storage, a resolvable "channel" per cartridge id (latest-stable, round-latest) that a consumer resolves to one immutable, signed digest before ever trusting it — the channel name is never itself what’s verified, the same discipline a container tag needs against --digest — and a directory of trust roots (OQ4, OQ6). For a commercially licensed cartridge, the hub is the entitlement gate: the descriptor stays publicly listed, but resolving the weights artifact’s key_ref requires a valid entitlement — it gates bytes, not metadata.

No hub required. A cartridge’s source repo (the shape the two reference cartridges already follow) bundles the packaging step itself, so git clone && <build> produces a conformant package locally.

This unlocks a trust path independent of signatures: if the build is reproducible, a consumer can rebuild from source and check that their own artifact digests match the digests in a manifest signed upstream, verifying the cartridge without trusting the channel it arrived through at all. Sign what a consumer can’t feasibly rebuild (encrypted commercial weights, a large training run); let reproducibility carry the rest. Whether today’s builders are actually deterministic end-to-end is OQ11.

For a single company shipping to its own products, the common case: build once (through step 7 — package + signed manifest) and drop the package, as-is, onto whatever artifact storage the company already operates — Artifactory/Nexus, a GitLab/GitHub Package Registry, an S3 bucket — no dedicated search UI, entitlement gate, or discovery portal. Consumers already know which cartridge id/version they need and pull it directly.

This is Mode A with the discovery-and-entitlement layer removed, not a lesser version of it. What survives unchanged is the only part that matters for trust: the manifest and its signature(s) still get verified before load. For a single-publisher internal setting the trust store is trivial: pin the company’s own key(s) once — baked into build images, provisioned on managed devices. This is the practical answer to OQ4 for the internal audience.

"Can I replace Whisper with Moonshine?" splits into two questions with different answers — the two planes made concrete.

Cartridge-level (binary-plane) compatibility rarely holds across model families, and isn’t the goal. The Whisper-on-NPU cartridge and the Moonshine engines are all task: asr, but their io shapes differ structurally: batch 4 s log-mel window vs. streaming PCM chunks; [en, de] vs. [en]; different tokenizers. None of that is a bug — the descriptor exists so the difference is machine-readable and honest, not so unrelated cartridges fake an identical tensor API.

Profile-plane compatibility is the actual swap point. The application never talks to a cartridge’s raw io; the adapter absorbs the difference behind one stable, per-task interface — the task profile. In the first consumer app today both adapters implement the same closed voice-engine contract and the app discovers whichever is wired in by reflection; the public asr/v1 profile formalizes exactly that seam without the app-specific residue.

What a swap costs. The profile hides the shape difference; it cannot hide a capability difference. Moving from Whisper to an English-only streaming engine means losing German and changing the UX from one final transcript to incremental results — a real product change, surfaced as a descriptor diff and accepted explicitly, never silently.