Workflow Registry and Qualified Packages

1. The real problem: a version label is not qualification evidence

Assume a workflow called support-summary:3 passes every check today. Tomorrow its prompt changes from p12 to p13, its route policy admits a new model, or a dependency is replaced by different bytes under the same semantic version. A registry that keys qualification only by a human name or tag can silently keep QUALIFIED on content that the previous evidence never evaluated.

This lesson builds a registry that separates human aliases from executable identity. A package is QUALIFIED only when its immutable digest and every decisive version/reference match the recorded qualification bundle. Decisive drift creates a new candidate; it never edits the old qualified record in place.

2. Separate alias, package identity, and evidence identity

invoice-v3, prod, and stable are useful for humans, but they are mutable aliases. Package identity must instead bind to a digest of the canonical manifest. Evidence identity is a third layer: the qualification bundle must state exactly which package digest, model qualification, serving evidence, and dependency digests it evaluated.

Use aliases for discoverability, digests for identity, and evidence bundles for qualification. None substitutes for the others.

3. Minimum Qualified Workflow Package manifest

A practical manifest should record at least: package_name, human_alias, package_digest, workflow_spec_version, prompt_version, schema_version, adapter_version, route_policy_version, cost_policy_version, model_qualification_ref, serving_evidence_ref, dependency_digests, environment_requirements, qualification_bundle_ref, status, promotion_record, requalification_triggers, and rollback_digest.

This is a decision boundary, not just inventory. If a decisive field changes, the new package needs new evidence. Presentation-only metadata that does not enter canonical identity must be explicitly classified as non-decisive.

4. What do digests and tags prove?

The OCI Image Manifest uses descriptors and digests for content-addressable artifacts, while the OCI Distribution specification defines a digest as a hash-derived content identifier and a tag as a human-readable manifest reference. That is a useful registry design pattern: a tag may move; a digest names exact content. cite:OCI-IMAGE-MANIFEST cite:OCI-DISTRIBUTION

MAKNOW uses OCI only as an immutable identity reference pattern. This lesson does not require workflow packages to be OCI images, and OCI does not define MAKNOW's qualification state machine.

5. What counts as a decisive dependency?

Anything able to change behavior, safety, contracts, routing, cost, or execution results is decisive: workflow spec, prompt, output schema, adapter, route policy, cost policy, model qualification reference, serving configuration, and dependency digest. If route-policy-r7 becomes r8 and r8 permits a new model, the old qualification is insufficient even when workflow and prompt bytes stay unchanged.

Semantic version text is not enough. Different content under the same version string is still different identity and must trigger requalification.

6. What must the qualification bundle bind to?

The bundle must contain an auditable snapshot of the package digest and every decisive reference. QUALIFIED is allowed only when the observed package exactly matches that snapshot and all referenced evidence remains valid, current, and non-revoked.

Saying “this workflow was tested before” is insufficient. You must identify which exact bytes/configuration, environment, qualification references, time, and policy were evaluated.

7. Registry lifecycle states

Keep distinct states: DRAFT for incomplete manifests, CANDIDATE for complete packages lacking enough evidence, QUALIFIED for exact package/evidence match, NEEDS_REQUALIFICATION for decisive drift, SUSPENDED for temporarily invalid evidence or incident review, and REVOKED for packages that must no longer be promoted or executed.

Transitions must be event-driven and auditable. No state is inferred merely from a tag or a recent successful run.

8. Promotion from Candidate to Qualified

Promotion has four gates: 1) a complete canonical manifest; 2) computed immutable digest; 3) resolved decisive references with traceable evidence; 4) exact qualification-bundle match. After PASS, the registry appends a promotion record from candidate_digest → QUALIFIED with evidence references and timestamp.

The old qualified record is immutable. A new release gets a new record. An alias may later repoint to the new digest, but alias movement does not create qualification.

9. Mutable aliases and the “same version” trap

Suppose support-summary:3 pointed to sha256:AAA yesterday and AAA was qualified. Today the same alias points to sha256:BBB. A downstream system that looks up qualification by alias can incorrectly inherit AAA's evidence onto BBB.

The correct path is digest-bound execution. If an alias is resolved, compare the resolved digest with the qualified digest. A mismatch means NEEDS_REQUALIFICATION or blocked execution, never silent inheritance.

10. Dependency and model-route drift

Changing a decisive reference creates a new candidate even if package name and top-level version are unchanged. In the transfer case, workflow/prompt/schema bytes remain fixed but the route policy now permits a model with no qualification reference. The result is not QUALIFIED; it is NEEDS_REQUALIFICATION until the new path gains evidence or the policy rolls back.

A successful run on the old model proves nothing about the newly admitted path.

11. Suspension, revocation, and rollback

If a qualification reference expires, is revoked, or enters incident review, the package may become SUSPENDED even when its own digest is unchanged. REVOKED means execution/promotion must stop. These states differ from NEEDS_REQUALIFICATION, which normally follows package or dependency drift.

Rollback must name a previously qualified digest, not a prior mutable tag. Record both the rollback target and reason.

12. Lab: eight deterministic lifecycle fixtures

The lab has eight deterministic cases. The baseline exact-matches every reference and becomes QUALIFIED. Other cases vary one dimension at a time: alias repoint, prompt drift, dependency digest drift, route-policy drift with missing model qualification, incomplete qualification bundle, alias rename with unchanged digest, and revoked evidence.

Implement evaluate(case) and return exactly eight fields: package_identity_state, alias_state, dependency_state, qualification_evidence_state, lifecycle_state, executable_state, rollback_state, and reason_class.

13. Wrong shortcuts

Three shortcuts are forbidden: “the tag is unchanged, so qualification is unchanged”; “the last run was green, so every dependency is qualified”; and “the semantic version matches, so the bytes match.” Each disconnects evidence from identity.

A registry entry itself does not prove quality or safety. The registry binds externally produced evidence to an exact package and enforces lifecycle rules.

14. What must an audit record reconstruct?

A useful event records: alias resolution, canonical package digest, decisive references compared, qualification bundle digest target, exact mismatch, before/after state, actor/policy that promoted or suspended, and rollback digest.

If a reviewer cannot reconstruct the decision from the registry record alone, the system is not evidence-closed.

15. Exit checklist and transfer

Before PASS, ask: Does downstream execute a digest-qualified reference? Does every decisive change trigger requalification? Is alias rename distinct from alias repoint? Do revoked/stale evidence states remain explicit? Does rollback point to an immutable digest?

Transfer exercise: change route policy to admit a new model without a qualification reference while workflow/prompt/schema bytes stay unchanged. Show why the unchanged top-level tag cannot transfer the old QUALIFIED state to the new path, and list the evidence needed to return to QUALIFIED.