119 lines
8.2 KiB
Markdown
119 lines
8.2 KiB
Markdown
# Model-Pack Lifecycle Contract
|
|
|
|
## Scope and Invariants
|
|
|
|
This contract governs separately signed optional model packs after an appliance has completed its
|
|
base installation. It applies to Workstation and every Server tier. A model pack is data and runtime
|
|
metadata, not boot media, a platform update, or a license. Installing or retaining a pack MUST NOT
|
|
grant entitlement, change product category/tier, silently replace the platform runtime, or make the
|
|
base appliance dependent on removable media.
|
|
|
|
All operations use the durable phases `received`, `verifying`, `quarantined`, `staged`, `activating`,
|
|
`active`, `deactivating`, `removed`, `failed_safe`, or `recovery_required`. The appliance records the
|
|
pack manifest digest, operation/correlation ID, actor, timestamps, compatibility decision, referenced
|
|
content digests, storage changes and terminal result without recording license secrets or model data.
|
|
|
|
## Import and Quarantine
|
|
|
|
1. Copy incoming bytes into a non-executable, non-runtime-visible quarantine directory on the target
|
|
filesystem. Partial copies use a unique operation path and are never content-addressed as trusted.
|
|
2. Enforce configured quarantine capacity before copy and reserve activation plus rollback headroom.
|
|
3. Verify trust/revocation policy, detached signature, schema, compatibility, entitlement,
|
|
architecture/runtime prerequisites, every object digest and unpacked-size declaration before any
|
|
object becomes usable by a model runtime.
|
|
4. Reject archives with absolute paths, traversal, links escaping staging, special devices,
|
|
duplicate/conflicting paths, undeclared content, decompression beyond declared limits, or unsafe
|
|
ownership/mode metadata.
|
|
5. On verification failure, preserve the manifest, reason code and bounded diagnostic evidence.
|
|
Payload bytes remain quarantined for the approved investigation period or are securely deleted by
|
|
policy; they MUST NOT enter the trusted object store.
|
|
6. An interrupted copy or verification resumes only after revalidating the received extent and then
|
|
repeats complete verification. The previously active model set remains unchanged.
|
|
|
|
Quarantine reason codes include `signature_invalid`, `key_untrusted`, `key_revoked`,
|
|
`policy_stale`, `manifest_invalid`, `object_digest_mismatch`, `archive_unsafe`, `incompatible`,
|
|
`not_entitled`, `insufficient_space`, and `interrupted_incomplete`.
|
|
|
|
## Content-Addressed Sharing and Activation
|
|
|
|
Verified immutable objects enter a trusted store keyed by algorithm and digest. A transaction creates
|
|
or increments references only after all objects for the pack are present. Sharing is allowed only for
|
|
byte-identical objects with the same digest; filenames, model names or upstream revisions alone are
|
|
not identity. Each active pack has an immutable installation record that maps its manifest digest to
|
|
all object digests and its activation metadata.
|
|
|
|
Activation writes a complete side-by-side runtime view and atomically publishes that view. Health
|
|
validation MUST prove local discovery and the declared smoke inference without network access. Until
|
|
validation passes, the prior active view and its references remain rollback-protected. Failure removes
|
|
the candidate view/references or marks `recovery_required`; it never leaves a partly visible pack.
|
|
|
|
A pack MAY depend on another pack only through exact artifact ID plus accepted version range and
|
|
required object/capability declarations in its signed manifest. Dependency cycles fail closed. The
|
|
importer MUST show the full dependency and additional-space plan before confirmation and MUST NOT
|
|
fetch a missing dependency from a network.
|
|
|
|
## Deactivation, Uninstall and Garbage Collection
|
|
|
|
Deactivation removes a pack from runtime selection without deleting its trusted objects. Uninstall is
|
|
an explicit authorized operation and MUST:
|
|
|
|
1. show affected active profiles, dependent packs, freed-space estimate and whether model-created
|
|
customer data is retained;
|
|
2. block while active operations use the pack unless the operator safely drains/cancels them;
|
|
3. block removal of a required dependency unless dependents are removed in the same approved plan;
|
|
4. atomically publish a runtime view without the pack, validate the remaining model set, and only then
|
|
decrement its object references; and
|
|
5. retain audit/evidence and customer-created data according to policy. Uninstalling model weights
|
|
MUST NOT silently delete prompts, indexes, fine-tunes, evaluations or other customer data.
|
|
|
|
Garbage collection deletes only trusted objects with zero active, staged, dependency, rollback,
|
|
evidence-hold or support-hold references. It uses a mark-and-sweep plan recorded before deletion,
|
|
rechecks references inside the deletion transaction, and records actual reclaimed bytes. Interrupted
|
|
garbage collection is idempotent: immutable objects are either present and digest-valid or absent and
|
|
unreferenced. Object-store reconciliation MUST detect missing referenced objects and orphaned objects;
|
|
missing referenced content blocks model readiness, while orphans remain unavailable until reviewed.
|
|
|
|
## Entitlement and License Change
|
|
|
|
Entitlement is evaluated independently at every activation and runtime selection. A valid installed
|
|
pack can therefore be `installed_inactive` when the current license, category, tier or policy does not
|
|
authorize use.
|
|
|
|
| Change | Required behavior |
|
|
|---|---|
|
|
| License expires or is revoked | Stop new inference for affected packs after the approved continuity rule; safely finish/cancel in-flight work; retain weights and customer data during the approved grace/appeal period |
|
|
| Replacement license restores entitlement | Re-evaluate installed pack without re-import; activate only after current trust, compatibility and health checks pass |
|
|
| Tier/category downgrade | Disable affected packs; do not relabel them as a lower tier or delete them automatically |
|
|
| Tier/category upgrade | Previously installed pack may become eligible but requires explicit activation and current checks |
|
|
| Machine rehost | Pack bytes may be migrated only through an approved signed export/import or original media; entitlement is re-evaluated on the target |
|
|
| Pack redistribution license changes upstream | Existing signed release remains governed by its captured license/notice and Cezen distribution decision; new distribution stops until legal approval, without remotely deleting customer content |
|
|
| Security withdrawal | Signed withdrawal/trust policy blocks new activation and states whether deactivation or removal is mandatory; customer data and evidence remain recoverable |
|
|
|
|
Model media MUST carry the exact upstream license text, required notices, redistribution decision and
|
|
source/revision attribution used for that release. A later license-text change cannot mutate an
|
|
already signed pack; it requires a new pack version or withdrawal record.
|
|
|
|
## Interruption and Recovery Evidence
|
|
|
|
Acceptance tests MUST interrupt: media copy, archive extraction, object-store commit, reference
|
|
transaction, runtime-view switch, health validation, uninstall view switch, reference decrement and
|
|
garbage collection. For each point, evidence proves one declared result: safe resume, safe restart,
|
|
automatic rollback, or `recovery_required` with an intact previous view. Tests also cover two packs
|
|
sharing objects, dependency removal refusal, license downgrade/restore, malicious archives, partial
|
|
media, insufficient quarantine/activation space, orphan reconciliation and a missing referenced
|
|
object.
|
|
|
|
Gate 5 passes only when the installed-pack inventory, object reference graph, runtime-visible view,
|
|
entitlement decision, actual disk usage and evidence record agree after every clean and interrupted
|
|
scenario. Independent review is required before general release.
|
|
|
|
## Owner Decisions Still Required
|
|
|
|
- Quarantine location, byte quota, failed-payload retention and secure-deletion policy.
|
|
- Trusted object-store layout, transaction mechanism, reference database and reconciliation owner.
|
|
- Drain/cancel timeout, activation smoke inference and rollback retention window.
|
|
- Customer-data classification and retention/export behavior for pack-created artifacts.
|
|
- License expiry continuity/grace, downgrade and rehost behavior, plus legal owner for redistribution.
|
|
- Security-withdrawal authority and mandatory-deactivation/removal conditions.
|
|
- Garbage-collection schedule, low-disk trigger, evidence/support holds and break-glass recovery owner.
|