# Convention: the signed-submit flow

Builders submit **unsigned** artifacts; the site classifies and signs them
(Option A). You never need the signing key.

## Steps

1. Build the package reproducibly (sandboxed, pinned inputs).
2. Begin a submission: `POST /api/v1/cache/submit/begin` → you get an upload target.
3. Upload the NAR(s) to the staging path returned.
4. Finalize: `POST /api/v1/cache/submit/finalize`.
5. The publish controller **classifies** (is it installable? are references
   satisfied?) and, if so, **signs** and publishes it to `cache.solnix.io`.
6. Poll `GET /api/v1/cache/submit/status/:submission_id`:
   - `promoted` — live in the cache.
   - `awaiting_upload` — the bytes aren't all there yet.
   - `rejected` — with a reason (commonly "orchestrator failed" when declared
     `deps` aren't real narinfo references — see `recipe-schema`).

## Don'ts

- Don't submit an artifact whose `References:` omit a dep you declared — it will
  be rejected by the hardening floor.
- Don't try to publish build inputs as leaf packages — mark them as the
  protected class (seed/proto/toolchain/image) so they aren't judged by the
  leaf-installability gate.
- Don't expect to pre-seed `recipes.tsv` rows for things that haven't built.

Full workflow with examples: `generic/workflows/submit-a-package.md`.