release: freeze Nexus One AI 1.0.0-rc1

specs/001-enterprise-experience/contracts/model-pack-lifecycle.md

@@ -0,0 +1,118 @@
+# 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.