Extensions — manifest, dependency locks, migrations and safe lifecycle

[zenithruneblade]

Define and rehearse the missing lifecycle between “one local shim registers” and “an extension-bearing Vessel generation is safely installable, migratable and recoverable.”

This is a bounded child of #63. It does not turn #21 registration into a package manager, let extensions run arbitrary Alembic code at import time, or replace the owners in #45 Packaging, #46 Evolution and #47 Persistence.

Starting point: ADR 05 accepts built-in and private coupled paths while deferring the independent package API; ADR 17 requires source-bound packaging; ADR 18 requires an inactive candidate and a new Vessel generation. Current #21 explicitly defers dependency locks, upgrades and migrations.

First working slice

Choose one exact built-in or private coupled extension with a real typed contribution and, if the chosen slice needs persistence, one owned schema change. Then:

• Bind Core revision, extension source revision, activation id, contribution identities, Python/system dependency inputs, relevant locks, platform/base-image inputs and verification plan in one candidate manifest.
• Resolve and build the complete selected body before activation. Detect dependency conflicts, missing inputs, incompatible Core coupling and a changed base before any live mutation.
• Declare extension-owned persistent models separately from registration. Pin the migration lineage/head, ordering dependencies, data owner, runtime-versus-migration credentials and supported source schema.
• Rehearse a fresh install and one supported previous generation on a disposable database with retained rows. Refuse revision collisions, missing dependencies, multiple heads without an admitted merge, and an extension migration that is absent from the selected manifest.
• Verify enable → new generation → contribution/data visible, and disable → new generation → executable contribution absent while retained data follows explicit policy. Disable must not silently drop tables, delete artifacts or unload code from a live Vessel.
• Exercise one failed install/migration/activation. Record whether the declared recovery is rollback, forward repair or containment; do not report a generic “uninstall succeeded” while schema or external effects remain.
• Bind the resulting package/archive/image identities into Packaging — verify a source-bound release candidate on a clean host #45 evidence and use Evolution — rehearse an update and its recovery path #46 for the changed-body activation/recovery rehearsal.
• Document the minimal extension-author journey and conformance checks without promising the deferred independent SDK.

Contract split

Concern	Owner / coordination
Contribution kinds, provenance, registration seal and compatibility tier	ADR 05, #63
Settings/Rune selection and immutable generation	ADR 12, #64, #1/#21
Core and extension schema ownership, transactions and credential separation	ADR 06, #47
Source/dependency/platform locks and artifacts	ADR 17, #45
Candidate compatibility, quiescence, new process generation and recovery	ADR 18, #46
Whole-installation capture/restore	ADR 07, #44
Feature-specific table meaning, retention and destructive deletion	The receiving Core office or Extension Domain; never this generic lifecycle issue

Open decision

Select the first exact extension and determine whether its accepted slice genuinely needs a database migration. If it does, agree the manifest representation and Alembic lineage/ordering contract under ADRs 05/06/17/18 before implementation. Do not invent a dummy migration merely to satisfy this issue.

Later

A stable independent extension API/SDK, remote package discovery, public registry, signature policy, multi-party publication and arbitrary cross-language in-process ABI remain deferred. They require their own accepted contracts and cannot be inferred from a successful private coupled rehearsal.

Verification: isolated build environment; disposable PostgreSQL fresh/upgrade/failure fixtures when applicable; process-generation restart; artifact and recovery receipts. Shared contribution and touched-docs rules: #52.