Artifact Lifecycle Contract

Weight files encode tensors. The schema-v1 sidecar records what the artifact is, which base and tokenizer it belongs to, and what is safe to do next. TinyGPTIO owns this small JSON contract.

Sidecar discovery

The sidecar always travels with the artifact:

model.tinygpt
model.tinygpt.artifact-manifest.json

adapter.lora
adapter.lora.artifact-manifest.json

mlx-package/
  artifact-manifest.json
  config.json
  ...

File manifests use the artifact filename in artifact_path. Directory manifests use ".". All receipt paths are relative. Copying the artifact and its sidecar together is therefore sufficient for discovery in a new location.

Schema v1

{
  "schema_version": 1,
  "artifact": {
    "id": "pace-planner-sft-v1",
    "revision": "recipe-v1"
  },
  "kind": "adapter",
  "artifact_path": "pace-planner-sft-v1.lora",
  "base": {
    "id": "Qwen/Qwen3-4B-Instruct-2507",
    "revision": "cdbee75f17c01a7cc42f958dc650907174af0554"
  },
  "tokenizer": {
    "id": "Qwen/Qwen3-4B-Instruct-2507",
    "revision": "cdbee75f17c01a7cc42f958dc650907174af0554",
    "chat_template": "chatml"
  },
  "history": [
    {
      "action": "sft",
      "tool": "posttrainllm",
      "detail": "method=sft-lora; steps=400; rank=16"
    }
  ],
  "runtimes": ["native-hf-load"],
  "next": ["merge", "convert", "eval", "serve"],
  "receipts": [
    { "kind": "eval", "path": "receipts/eval.json" }
  ],
  "created_at": "2026-09-23T00:00:00Z"
}

Allowed kinds are base-model, adapter, training-checkpoint, and deploy-package. Legal next actions are resume-exactly, warm-restart, merge, convert, eval, and serve.

resume-exactly is a strict claim. It requires a pinned checkpoint identity and persisted optimizer, scheduler, and RNG state. A weight checkpoint without all four advertises warm-restart, never exact resume.

Producer and consumer rules

Producers write weights or package contents first, then atomically write the manifest. Native checkpoints, factory SFT adapters, manifest-aware finetuning, and MLX exports follow this ordering.

Consumers validate before loading model bytes:

• sample and hf-load --sample require eval plus a compatible runtime.
• serve requires serve plus a compatible runtime.
• adapter consumers compare the pinned adapter base with the selected base and refuse a proven mismatch before applying adapter weights.
• factory training evidence requires artifact.json.lifecycle_manifest to name the adjacent sidecar. publish-check validates the same sidecar and its artifact/base identities.

Malformed manifests, unsafe paths, unsupported runtimes, and illegal actions fail closed. A valid adapter whose selected base lacks enough identity to prove the binding emits an explicit warning rather than pretending it was verified.

Privacy boundary

The manifest contains bounded metadata, not training content. History is limited to 64 single-line steps; receipts are limited to 64 relative paths. Absolute/traversing paths, credential-like values, prompt/completion payloads, multiline logs, and oversized fields are rejected. Store evaluation detail in the referenced receipt, subject to that receipt’s own privacy contract.

Legacy migration

Artifacts without a sidecar remain loadable and produce a lifecycle/base verification is unavailable warning. The runtime does not infer a revision, template, recipe, or receipt for them.

To migrate an artifact, create a sidecar only from known evidence and copy it beside the artifact. If any identity is unknown, keep the artifact legacy. A plausible but invented revision is more dangerous than an explicit warning.