@celilo/cli 0.27.0 → 1.1.0

package/CELILO_CORE_MODULES.md

@@ -19,6 +19,19 @@ Each entry: `module id` — what it is — **provides** / **requires** capabilit
 > (**knot-unbound-internal** / **technitium**). Identity comes from **authentik** (`idp`). That's
 > the whole edge: DNS + firewall + ingress + identity, each a swappable provider module.
 
+> How the graph OPENS again: when a consumer is removed, celilo dispatches
+> `on_consumer_removed` to every provider of every capability that consumer
+> declared, and each withdraws what it minted on its behalf
+> (openspec/changes/consumer-removal-cleanup). Providers implementing it:
+> **caddy** and **caddy-internal** (drop the routes, reclaim `/srv/www/<slug>`),
+> **iptables** / **greenwave** / **axon** (drop the forwards and trusted
+> sources), **authentik** (delete the OIDC application), **forgejo**
+> (deregister the CI runner), **generic-cpanel-hosting-provider** (remove the
+> published docroot). Consumers do NOT withdraw their own state any more — a
+> module gives a port or a subnet back by narrowing its own declaration, and
+> departing entirely is the provider's job. A provider that fails to withdraw
+> is marked ERROR; the removal still completes.
+
 ## Network fabric (DNS / firewall / DHCP)
 
 - **axon** — Axon Networks Q1000K ISP router driver (Brightspeed-branded); port-forwarding + public-IP discovery + DHCP DNS + DHCP address-pool bounds via the TR-181 CGI API. **provides:** `firewall`, `dhcp_server`. Fork of **greenwave** — identical protocol, differing only in the vendor extension prefix (`X_AXON_` vs `X_GWS_`/`X_LANTIQ_COM_`). Pick by device: Q1000K → **axon**, C4000XG → **greenwave**. Two device behaviours shape this driver and are not shared by **greenwave** (celilo#739): the router **regenerates** `Pool.1.DNSServers` from its own upstream resolver list every ~15 min and on any config commit, so `setDhcpDns` also writes `Device.DNS.X_AXON_CustomServer` — the *input* to that computation, which survives — and **technitium re-asserts** the pool value on `timer.tick.1m`. Optional `dhcp_pool_start`/`dhcp_pool_end` bound the leased range; set them below the addresses IPAM allocates, because **IPAM has no knowledge of the router's DHCP pool** and nothing otherwise stops the router leasing an address celilo already assigned.
@@ -28,10 +41,12 @@ Each entry: `module id` — what it is — **provides** / **requires** capabilit
 - **technitium** — internal split-horizon DNS resolver + authoritative server (web UI + HTTP API); heavier alternative to knot-unbound. **provides:** `dns_internal`. Ships a base-module-aspect (`modules/technitium/base-module-aspect/`).
 - **namecheap** — public DNS A-record management via Namecheap Dynamic DNS API (HTTP, no browser automation). A caller supplies a NAME and nothing else: the address is the source IP of celilo's own update, re-derived on every assert. Registering `<domain>` also claims `www.<domain>` and vice versa (best effort, reported back as `outputs.companion_fqdn` so the framework's `public_dns` check watches it — Namecheap answers `ErrCount 0` for `www` updates it does not apply). DDNS passwords are keyed by the **registrable domain**, never the FQDN. **provides:** `dns_registrar`.
 - **wireguard** — owns the admin WireGuard tunnel on the firewall host: interface, listen port, peers (as records), and client subnet are module config rather than hand-maintained state. Exposes the listen port and **registers the client subnet as a trusted source**, so VPN reach into the managed zones is in the firewall registry and every converge re-emits it. **REQUIRES the `control-plane-vpn` network and READS its range** (`requires.networks`; `client_subnet` is a `source: system` derive of `network.control-plane-vpn.subnet`). It does not write that network and has no way to — celilo owns the namespace, and the deploy will not reach any hook until the network is defined, asking for a range if one is missing. So `wg0` is attributable the moment it exists. This replaces a declare-before-you-create ordering inside `on_install`, which could only narrow the window and not close it: a consumer that captured config before the hook started could not see a value the hook wrote, whatever order it wrote it in, and that is exactly what left `wg0` unattributable (celilo#759). `health_check` still asserts the declaration matches what the tunnel serves — what it catches now is divergence, celilo's network having changed since the module resolved its config. That same key is what the internal resolver's split-horizon view consumes. Adopts a running tunnel in place (existing key retained; `wg syncconf`, never `wg-quick down`) because that tunnel is the operator's recovery path. **Adoption is a one-time IMPORT and it ENDS.** The marker is `registered_peers` — celilo's own config key, separate from the operator's `peers` so a machine can never rewrite what an operator typed. While that key has never been written the tunnel is not yet celilo's; the deploy that writes it (even as `[]`) CLAIMS the tunnel, importing whatever `[Peer]` blocks are running, and from then on the render is closed-world (`peers` ∪ `registered_peers`) with a `[Peer]` on the box in neither reported as drift by `on_install` and by `health_check`'s `unknown_peers`. An ABSENT `peers` declaration and a declared-EMPTY one are deliberately different (no `default: []` on either variable): they used to be the same value, so the module read every empty list as "adopt what is running", the last peer could not be revoked, and a hand-added peer rode along on every deploy unreported (celilo#765). On a tunnel celilo has not yet claimed, a declared-empty `peers` is REFUSED rather than obeyed — celilo's own variable-default seeding wrote a real `peers = []` row for every install of the previous version that never set one, so on the installed base an empty list cannot be told from a stored default, and obeying it would `wg syncconf` the admin tunnel down to zero peers. **PROVIDES `control_plane_vpn`** so another module can enrol clients without an operator editing YAML: `registerClient` / `revokeClient` write to `registered_peers` — the same key the adoption claim uses — and `getEndpoint` reads the server's public key LIVE off the host rather than storing a copy that could be republished after the key changed. `client_pool` is the range a consumer may allocate from, a strict subset of the client subnet, and `validate_config` REFUSES any operator-declared peer inside it: the two allocators cannot see each other, so the range is divided rather than negotiated, and that check is the only place a bad division is caught. ⚠️ Granting this capability grants fleet-wide reach — the tunnel's client subnet is a registered trusted source, so every client enrolled through it reaches every managed zone. **requires:** `firewall` (and the provider must support trusted-source registration — `iptables` does; the ISP-router drivers `greenwave` and `axon` do not).
+- **wireguard-manager** — self-service enrolment for the control-plane VPN, so adding an administrator's laptop is a web page rather than an operator editing `peers` by hand. A browser generates the WireGuard keypair with WebCrypto and **the private key never leaves it** — celilo never sees it and the app never stores it. The app allocates an address from `client_pool` (the range `wireguard` reserved for a consumer; celilo's IPAM deliberately does not cover VPN clients) and enrols the peer through **`control_plane_vpn`**, so it never edits wireguard's config and cannot reach a peer the operator declared by hand. Its own device list is the app's SQLite, reconciled onto the tunnel by the `reconcile_clients` hook on a `timer.tick.1m` subscription. Two guards make a failed poll harmless and both are structural rather than a check: `planReconcile` accepts only the `read` variant of a discriminated union, so an unreadable poll cannot reach it, and revocation is TOMBSTONE-driven — a device is revoked because the app says it was, never because it is missing from a list — so a short or empty read can only fail to add someone, never cut anyone off. A peer on the tunnel the app does not know and has not tombstoned is reported as an orphan and LEFT ALONE (usually an app restored from an older backup). **REQUIRES `private_web`, never `public_web`**: there is no public record, no ACME certificate and no port forward, and the internal CA's certificate is bundled with each downloaded config so a freshly enrolled device trusts the manager it just connected to. ⚠️ **Everyone enrolled becomes a fleet administrator** — the tunnel's client subnet is a registered trusted source, so the `admin_group` gate on the idp application is the entire access-control story; per-peer narrowing is not possible, because server-side `AllowedIPs` is crypto-key routing rather than access control. Lives in **`app`**, one tier behind `caddy-internal` in `dmz`, and is never reached directly (celilo#879). Enrolment works from INSIDE the fleet only (a device not yet on the VPN cannot reach a manager reachable only over it) — from the LAN through the ingress IP, from a segmented zone at the ingress's dmz address, or over an existing VPN session, and a revocation takes effect at the next reconcile — that interval IS the window in which a revoked device still has reach, which is why the UI shows it pending and why `celilo module run-hook wireguard-manager reconcile_clients` exists. **requires:** `control_plane_vpn` (wireguard), `idp` (authentik), `private_web` (caddy-internal).
 
 ## Public edge (ingress / identity)
 
 - **caddy** — reverse proxy with automatic HTTPS (HTTP-01 ACME); the standard HTTPS ingress. Emits a 301 redirect block for each served name's `www`/apex companion (kept out of the served-hostname set, so a companion never blocks the ACME wait). Its `health_check`'s DNS item is `internal_dns_resolution` — it digs from the management host behind the split-horizon resolver and is evidence about the in-fleet view only; public reachability is the framework's `public_dns` check. **provides:** `public_web`. **requires:** `dns_registrar`, `firewall`.
+- **caddy-internal** — a SECOND Caddy that serves the fleet and nothing else, and is a sibling of **caddy** rather than a mode of it. It never exposes a port on the firewall's EXTERNAL interface, never publishes a public record, and takes its certificates from Caddy's own local CA (`tls internal`) — those absences ARE the capability, and `public_web` cannot express them because it treats an unreachable route as a deploy failure and publishes a public A record to prevent one (design D10). Lives in the **`dmz`** zone, in front of the things it fronts, mirroring the public `caddy` (celilo#879). LAN devices reach it through an IPAM-allocated `internal`-subnet `ingress_ip` that `on_install` passes to `firewall.exposeService({ ingressIp })` — one DNAT on the firewall's INTERNAL side and nothing external, the same mechanism the dmz-resident `dns_internal` resolver has used for `:53` since ISS-0156. Systems already inside `dmz`/`app`/`secure` use its dmz address instead (carried as `zoneRoutableValue` on the internal record), and VPN clients arrive as a registered trusted source. It previously lived in `internal` on the claim that a dmz ingress could not be reached from a LAN without a public port-forward; that conflated a public forward with an internal-side ingress IP, and cost it the ability to serve a browser inside a segmented zone at all. **`getCaCertificate()` is why the contract has a method `public_web` does not** — an internally-issued cert means clients must trust a CA celilo runs, and here that is nearly free because the people who must trust it are the ones who just downloaded a bundle from the service behind it, so the anchor ships with it. **The route table is this module's OWN config (`routes`), never celilo's `web_routes`** (celilo#846): caddy derives its served hostnames from every row of that table, so a private route stored there would be picked up and served PUBLICLY — storage is the privacy boundary, not policy. Route changes reconcile synchronously in the capability call (there is no `routes_changed` event for private routes, and inventing one would only add delay). A consumer cannot register a route on a hostname the ingress is not already configured for: a capability factory gets no capabilities of its own, so it cannot add the internal DNS record a new name would need, and it refuses rather than serving an unresolvable site block. **provides:** `private_web`. **requires:** `dns_internal` — declared under `optional.capabilities` ONLY to route around celilo#854 (the import-time secret gate refuses a consumer over a secret it never reads); `on_install` throws without it.
 - **generic-cpanel-hosting-provider** — publishes static sites into a subfolder of a domain on a cPanel/SSH web host celilo does **not** govern (the host owns the domain, DNS, TLS and web server). Systemless like **namecheap** — no `requires.system`, no zone, no IPAM; it holds credentials for an external party. One provider serves many accounts, resolved by hostname; onboarding takes the account password once, `ssh-copy-id`s celilo's key, then discards it. **provides:** `external_web`.
 - **authentik** — Authentik identity provider with OIDC (Docker Compose: server, worker, Postgres, Redis). **provides:** `idp`. **requires:** `public_web`, `dns_registrar`, `firewall`.
 
@@ -57,6 +72,7 @@ Each entry: `module id` — what it is — **provides** / **requires** capabilit
 ## E2E fixtures & probes (not production apps)
 
 - **hello-foo** / **hello-bar** — hostless single-page sites (one hand-written `site/index.html`, no build step) published at a configurable `domain` + `path`. They exist so the caddy route-lifecycle e2e can put several independent routes on one caddy and watch them interact — celilo-website is the only other static-site module, and one site can't answer "does removing `/` break `/foo`?". **requires:** `public_web`, `dns_registrar`.
+- **hello-private-foo** / **hello-private-bar** — the `private_web` twins of the pair above: hostless single-page sites published through the fleet-only ingress. Two of them for the same reason — one consumer cannot answer "does withdrawing `/foo` leave `/bar` alone?", and per-consumer scoping is exactly what `unregisterRoutes()` promises. Their hook is `private_web ?? public_web` with no branching after it, which is the spec's "same consumer code, either ingress" requirement made executable. **hello-private-foo** additionally calls `getCaCertificate()` and writes the PEM into its own site before publishing — the CA-bundling pattern a real consumer uses, and the only way to observe that the capability returned something usable. **requires:** `private_web`.
 - **source-forge-probe** — hostless e2e probe that exercises the `source_forge` capability (issue/revoke runner token) against a deployed Forgejo. **requires:** `source_forge`.
 - **test-ansible-output** — e2e fixture that runs 25×1s sleep tasks to assert Ansible output streams in real time. Not a real app.
 - **vm-smoke** — throwaway module proving celilo's generic `type: vm` deploy path end-to-end (template clone → cloud-init → Ansible reach). No capabilities.

package/CELILO_SUBSYSTEMS.md

@@ -24,6 +24,7 @@ see `openspec/specs/`. Companion doc: [CELILO_CORE_MODULES.md](./CELILO_CORE_MOD
 ## Allocation & infrastructure selection
 
 - **IPAM (IP/VMID allocation)** — `apps/celilo/src/ipam/allocator.ts` — `allocateIPFromSubnet`, `allocateVMID`, `reserveIP`/`unreserveIP`, `inferZoneFromIP`, `getAllocation`. Auto-wrapper: `apps/celilo/src/ipam/auto-allocator.ts` — `allocateForModule` / `deallocateForModule`.
+- **Ingress IPs (how the LAN reaches a service in a segmented zone)** — `ensureIngressIps` in `apps/celilo/src/templates/generator.ts`, called from `generateTemplates`. A module opts in by declaring an infrastructure variable whose name ENDS IN `ingress_ip` (`dns_ingress_ip` on the resolver, `ingress_ip` on `caddy-internal`); generate allocates and RESERVES a free `internal`-subnet address once and reuses it forever after, and the module's `on_install` passes it to `firewall.exposeService({ ingressIp })`. That renders ONE DNAT on the firewall's internal side and nothing on the external interface — it is not a public port-forward, and conflating the two is what pinned `caddy-internal` into the `internal` zone until celilo#879. Idempotence is load-bearing: re-allocating on a later generate silently moves the address clients use, with every command still reporting success (`apps/celilo/src/templates/ingress-ip.test.ts`).
 - **Infrastructure selection (container-service vs machine pool)** — `apps/celilo/src/services/machine-pool.ts` (`getMachineByHostname`, `addMachine`, `assignModuleToMachine`) and `apps/celilo/src/services/container-service.ts` (`getContainerServiceByName`, `addContainerService`, `verifyContainerService`). Provider API clients: `apps/celilo/src/api-clients/proxmox.ts`, `apps/celilo/src/api-clients/digitalocean.ts`.
 - **Zone detection / system config** — `apps/celilo/src/services/zone-detector.ts` — `detectZoneFromIp` reads `network.<zone>.subnet` from the `systemConfig` table and returns `NetworkZone | 'unknown'`. It answers CONTAINMENT ONLY. It used to return `'external'` on no-match, which conflated "no declared subnet contains this" with "the internet can route to this" — on a firewall with five RFC1918 legs that reported four of them as facing the internet. `'unknown'` is the honest answer; the caller resolves it (see `machine add`: publicly routable → `external`, otherwise fail asking for `--zone`). The subnet-backed zone list is derived from `NETWORK_ZONES` minus `external`, which has no subnet and must never be given one.
 - **Interface classification** — `packages/capabilities/src/interface-classification.ts` — THE shared classifier, used by the backend and every firewall provider module so the two cannot drift apart again. `isPubliclyRoutable(ip)` is a property of the address alone (false for RFC 1918, RFC 6598 carrier-grade NAT, loopback, link-local, multicast, reserved). `classifyInterfaces(interfaces, zones)` assigns each interface `zone → external → alien`, first match winning, where `external` is the RESIDUAL — routable and claimed by no declared zone — and is never subnet-matched. `externalEdge()` returns none/single/**ambiguous** rather than silently picking the first public address. `defaultRouteFinding()` enforces the invariant that the default route leaves through `internal` or `external`. **`subnetContains(cidr, ip)` lives here and is the ONLY implementation** — three existed and disagreed (the backend's mishandled `/0`); the other two are deleted, not aliased. Design: `openspec/changes/firewall-interface-classification/design.md`.
@@ -49,7 +50,7 @@ see `openspec/specs/`. Companion doc: [CELILO_CORE_MODULES.md](./CELILO_CORE_MOD
 
 | capability | impl | provider module(s) |
 |---|---|---|
-| `public_web` | `packages/capabilities/src/public-web.ts` (`createPublicWeb`). **Route lifecycle** is framework-owned at both ends, not per-module: removing a consumer runs `apps/celilo/src/services/web-route-cleanup.ts` (delete rows → reclaim `/srv/www/<slug>` → emit `routes_changed`) whether or not the module has an `on_uninstall`; deploying a provider runs `apps/celilo/src/services/public-web-republish.ts` (re-run every static consumer's `on_install`) so a provider rebuild refills the web roots it destroyed. | caddy |
+| `public_web` | `packages/capabilities/src/public-web.ts` (`createPublicWeb`). **Route lifecycle** is framework-owned at both ends, not per-module: removing a consumer dispatches caddy's `on_consumer_removed` hook (re-render the Caddyfile without that module's routes → reclaim `/srv/www/<slug>`) via the generic **consumer-removal cleanup** below, whether or not the module has an `on_uninstall`; deploying a provider runs `apps/celilo/src/services/public-web-republish.ts` (re-run every static consumer's `on_install`) so a provider rebuild refills the web roots it destroyed. There is no consumer-facing `unregister_routes` — withdrawal is the provider's, by design (openspec/changes/consumer-removal-cleanup D11). | caddy |
 | `idp` | `packages/capabilities/src/idp.ts` | authentik |
 | `dns_registrar` | `packages/capabilities/src/dns-registrar.ts` (`registerHost({ fqdn })` — **there is no way to supply an address**; the provider re-derives it from its own update's source IP on every assert) | namecheap |
 | `external_web` | `packages/capabilities/src/external-web.ts` (`publishStaticSite`). **OFF-FLEET static publishing** — the counterpart to `public_web`. See the in-fleet vs off-fleet note below. | generic-cpanel-hosting-provider |
@@ -61,7 +62,7 @@ see `openspec/specs/`. Companion doc: [CELILO_CORE_MODULES.md](./CELILO_CORE_MOD
 | `notification` | `packages/capabilities/src/notification.ts` (`send`, optional `receive`) | signal (planned) — transports are ordinary modules, both self-hosted and credential-only |
 | `cross_module_read` | `packages/capabilities/src/cross-module-read.ts` | framework (read other modules' capability data) |
 | `control_plane_vpn` | `packages/capabilities/src/control-plane-vpn.ts` (`registerClient`, `revokeClient`, `listClients`, `getEndpoint`). **Its state is NOT in a celilo table** — registrations live in the PROVIDER's own module config under `registered_peers`, kept separate from the operator's `peers` so a machine can never rewrite what an operator typed, and so `revokeClient` structurally cannot reach a declared peer. Do not go looking for a `vpn_clients` table; there isn't one and that is deliberate. Addresses are allocated by the CONSUMER from `client_pool` — celilo's IPAM deliberately does not cover VPN clients. ⚠️ Every client registered here reaches every managed zone: the tunnel's client subnet is a registered trusted source. | wireguard |
-| `private_web` | `packages/capabilities/src/private-web.ts` (`publishStaticSite`, `registerReverseProxy`, `unregisterRoutes`, `getCaCertificate`). **Fleet-only HTTP ingress** — internal DNS, an internally-issued certificate, and no public exposure. A SIBLING of `public_web` rather than a flag on it, because `public_web` treats an unreachable route as a deploy failure and publishes a public record to prevent one. Reuses `public_web`'s request types so a consumer can write `private_web ?? public_web` and call through the union without branching. | caddy-internal (planned) |
+| `private_web` | `packages/capabilities/src/private-web.ts` (`publishStaticSite`, `registerReverseProxy`, `unregisterRoutes`, `getCaCertificate`). **Fleet-only HTTP ingress** — internal DNS, an internally-issued certificate, and no public exposure. A SIBLING of `public_web` rather than a flag on it, because `public_web` treats an unreachable route as a deploy failure and publishes a public record to prevent one. Reuses `public_web`'s request types so a consumer can write `private_web ?? public_web` and call through the union without branching. **MODULE-provided**, unlike `public_web`: the implementation is `modules/caddy-internal/scripts/private-web-functions.ts` (wired via `CAPABILITY_MODULE_MAP`), and the route table lives in that module's own config rather than celilo's `web_routes` — a private route in `web_routes` would be picked up and served by the PUBLIC caddy, which derives its served hostnames from every row (celilo#846). | caddy-internal |
 
 ### In-fleet (`public_web`) vs off-fleet (`external_web`)
 
@@ -179,6 +180,8 @@ runner seam (`execRunner` real / `createMockRunner` for tests) lives in
 - **In-flight operation lock** — `apps/celilo/src/services/module-operations.ts` — `startOperation`/`completeOperation`/`failOperation` record deploy/uninstall/backup/restore in `module_operations`; `refuseIfInFlight`/`checkInFlight` are what backup and restore consult. Deploy and uninstall REGISTER but never check: it is a one-way guard protecting backup/restore consistency, not a general mutex (`openspec/specs/management-server-backup/spec.md` "In-flight operation refusal"). A row stops holding the lock once it is GONE, STOPPED/zombie (`isPidRunnable`, `ps -o state=` — `kill(pid,0)` calls a Ctrl-Z'd process alive), or older than `OPERATION_TTL_MS` (2h). The TTL is not redundancy: a pid is a recycled number, and once the pid space wraps an old row names an unrelated healthy process. Operator surface: `celilo module operations [list|clear] [--abandoned] [--all]` (`apps/celilo/src/cli/commands/module-operations.ts`); `list` shows only what holds the lock, abandoned rows are summarised unless `--abandoned`. Abandoned rows are reclaimed hourly by the `celilo-operations-sweep` bus subscriber (`timer.tick.1h` → `celilo module operations clear`, armed by `ensureOperationsSweepSubscriber` from module registration and `celilo system migrate`). `clear` MARKS rows failed rather than deleting them, and that is load-bearing: the `abandoned_operations` audit reads exactly those released rows to notice one module's operation dying over and over.
 - **Module pause / unpause (control-plane quiescence)** — `apps/celilo/src/services/module-pause.ts` — pure `planPause`/`planUnpause` producing an ordered plan, `executePause`/`executeUnpause` performing it, plus `listPausedModules`/`pausedAmong`/`formatPausedDuration`/`describePausedModule` (the ONE place an age is formatted). CLI: `apps/celilo/src/cli/commands/module-pause.ts` (`celilo module pause|unpause <id> [--cascade] [--stop-infra] [--reason] [--dry-run] [--yes]`). Pausing takes a module out of the CONTROL plane — no dispatched events, no timer hooks, no health checks, alerts suppressed — while leaving the DATA plane running, because capability consumption is deploy-time: every consumer calls `firewall`/`dhcp_server` from `on_install` and nothing calls it while serving. Config, secrets, IPAM/VMID and placement are preserved; `on_uninstall` does NOT run. Quiescence is enforced in two places: pausing drops the module's bus subscriptions (`unregisterModuleSubscriptions`), and `run-named-hook.ts` refuses any non-lifecycle hook for a PAUSED module (`skippedPaused`), which catches the paths that skip the bus — `events resync-subscriptions`, a restore that starts events.db empty, aspect fan-out, public-web republish. `on_install`/`on_uninstall` are exempt by hook NAME (not a caller flag): unpause redeploys through `on_install`, and removing a paused provider needs `on_uninstall`. Unpause always REDEPLOYS (`deployModule`) — that is what rebinds a consumer to a replacement provider and recreates provider-local state from the consumers that own it — and re-registers subscriptions, which a plain deploy does not do. A failed unpause restores `PAUSED` rather than leaving the module live and mis-bound. Cascade order reuses `services/update/dep-graph.ts` unchanged (pause = consumers first, unpause = providers first) and is computed from the GRAPH, never from which modules are currently paused, so a cascade walks THROUGH already-done members and is resumable. See `openspec/changes/module-pause-lifecycle/`.
 - **Provider-removal guard** — `apps/celilo/src/services/remove-guard.ts` — `findRemovalBlockers`/`describeRemovalRefusal`, called from `apps/celilo/src/cli/commands/module-remove.ts`. A PAUSED module is not a dependent (unpause cannot return it to service without a redeploy, and a redeploy re-resolves capabilities), which is what makes a provider swap possible at all. A dependent is one declaring the capability under `requires` **or** `optional` — the same relation `dep-graph.ts` uses, so the guard and the cascade agree on the set; the guard previously read `requires` alone, which let a removal silently orphan `technitium`'s `optional` `dhcp_server`. Refusals name each blocker AND which declaration makes it one. It deliberately does NOT exempt a dependent because another provider of the same capability exists (celilo#683).
+- **Consumer-removal cleanup (every provider is told)** — `apps/celilo/src/services/consumer-cleanup.ts` — pure `planConsumerCleanup` + `loadConsumerCleanupPlan` + `runConsumerCleanup`, called from `apps/celilo/src/cli/commands/module-remove.ts` after `on_uninstall` and before `terraform destroy`. A capability is two-sided: the consumer asks, the provider mints something in ITS world (a caddy site block, a DNAT rule, an OIDC client at authentik, a registered CI runner), and removal only ever touched one side — the FK cascade dropped celilo's row, so the provider's next converge had no way to learn the thing existed. This dispatches the `on_consumer_removed` hook to every provider of every capability the departing module declared under `requires` OR `optional` (the same relation `remove-guard.ts` counts as a dependency edge), **once per provider** rather than once per capability, sorted by provider id. The hook receives one input, `consumer`, and NOTHING else: a provider that cannot answer "what do I hold for this module" without being told has a different defect — the consumer's id was never recorded at mint time. It replaces `services/web-route-cleanup.ts`, which did the same job for exactly one capability, by name, from core. Semantics that are easy to get backwards: **a failed withdrawal never blocks the removal** — the consumer goes and the failing PROVIDER is marked `ERROR` with the departing consumer named in `error_message` (surfaced as a `blocked` finding by `services/audit/undeployed-modules.ts`), because the hook is a full converge and after a failure the provider's state is unknown rather than "one thing missed". **Dispatch continues past a failure**, so one broken provider cannot leave the others holding state. A PAUSED provider is skipped with a warning naming what it keeps (`run-named-hook.ts` refuses non-lifecycle hooks on a paused module, and `on_consumer_removed` must NOT join `LIFECYCLE_HOOKS`), and a never-deployed one is skipped silently. Providers implementing it: caddy, caddy-internal, iptables, greenwave, axon, authentik, forgejo, generic-cpanel-hosting-provider. See `openspec/changes/consumer-removal-cleanup/`.
+- **Firewall registry ownership** — `apps/celilo/src/services/port-forwards.ts` + `apps/celilo/src/services/trusted-sources.ts`. Both stores are bound to the CONSUMING module and stamp `registered_by` themselves; a caller cannot supply it, so a registration is never attributed to the wrong module. Both writes are **declarative**: `replace()` states a consumer's COMPLETE set for a target, so a port or subnet it previously registered and now omits is withdrawn (celilo#855 — before this, a module that exposed `:8080` and redeployed exposing `:9090` kept both, forever). The owner is IN both unique indexes, not merely beside them: two consumers wanting the same forward are two ROWS, so one leaving cannot delete a rule the other still needs; `modules/iptables/scripts/ruleset-renderer.ts` dedupes on the rule tuple so the pair renders once. Neither column is a FK, so `runConsumerCleanup` deletes these rows explicitly after every provider has converged without them.
 - **Backup artifact encryption** — `apps/celilo/src/services/backup-cipher.ts` — `encryptFileToFile`/`decryptFileToFile`, file-in/file-out and streamed, used by every backup writer (`backup-create.ts`) and reader (`backup-restore.ts`, `restore-from-file.ts`). Do NOT route artifacts through `secrets/encryption.ts`: that API is string-in/string-out for short DB values, and feeding it a tar cost base64 (1.33x) then hex (2x) then `JSON.stringify` — ~9x the artifact in memory, which OOM-killed forgejo's 774 MB backup, and a hard ~805 MB ceiling from the max string length that no amount of RAM raises. On-disk format is `magic "CELILOBK" (8) | version (1) | iv (16) | ciphertext | GCM tag (16)`; the tag is a trailer because it does not exist until the last byte is encrypted. `decryptFileToFile` still reads the pre-2026-07 JSON-envelope artifacts, discriminating on the magic bytes — the envelope's own `schemaVersion` cannot serve, as it lives inside the encrypted tar.
 
 ### Paused modules are conspicuous

package/drizzle/0025_port_forward_owner.sql

@@ -0,0 +1,29 @@
+-- Ownership of a firewall registration is a SET, not a label
+-- (openspec/changes/consumer-removal-cleanup, D5a).
+--
+-- `port_forwards` had no owner column at all, so nothing could tell which
+-- consumer a DNAT rule was minted for — the reason removing a module left the
+-- rule on the box with nothing in the registry to explain it.
+--
+-- Adding the column alone would introduce a WORSE bug than it fixes. Both
+-- unique indexes keyed the row WITHOUT an owner, and both stores
+-- delete-then-insert on that tuple, so consumer B registering what consumer A
+-- already has silently replaces A's row. Put an owner beside such an index and
+-- removing B deletes a rule A still needs. So the owner joins the index: two
+-- owners of one forward are two rows, and the row dies exactly when the last
+-- module that wants it goes away. `renderRuleset` dedupes on the rule tuple so
+-- the pair still emits one DNAT rule.
+--
+-- NOT destructive, though Phase 0 would permit it. Existing rows keep serving
+-- with `registered_by = ''` (unattributed): dropping them would empty the
+-- desired-state registry while the boxes keep their applied rules, and the
+-- first firewall converge after the upgrade would then render a ruleset missing
+-- every forward except the one the deploying module just re-registered. The
+-- unattributed rows are adopted the next time their owner re-declares the same
+-- target (see `buildPortForwardStore.replace`).
+
+ALTER TABLE `port_forwards` ADD `registered_by` text DEFAULT '' NOT NULL;--> statement-breakpoint
+DROP INDEX `port_forwards_unique_idx`;--> statement-breakpoint
+CREATE UNIQUE INDEX `port_forwards_unique_idx` ON `port_forwards` (`firewall_ip`,`internal_ip`,`port`,`protocol`,`ingress_ip`,`registered_by`);--> statement-breakpoint
+DROP INDEX `trusted_sources_unique_idx`;--> statement-breakpoint
+CREATE UNIQUE INDEX `trusted_sources_unique_idx` ON `trusted_sources` (`firewall_ip`,`subnet`,`registered_by`);

package/drizzle/meta/_journal.json

@@ -176,6 +176,13 @@
       "when": 1784000000000,
       "tag": "0024_module_pause",
       "breakpoints": true
+    },
+    {
+      "idx": 25,
+      "version": "6",
+      "when": 1784100000000,
+      "tag": "0025_port_forward_owner",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "0.27.0",
+  "version": "1.1.0",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {
@@ -58,7 +58,7 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1109.0",
     "@aws-sdk/lib-storage": "^3.1101.0",
-    "@celilo/capabilities": "^1.5.0",
+    "@celilo/capabilities": "^2.0.0",
     "@celilo/cli-display": "^0.2.0",
     "@celilo/core": "^0.8.1",
     "@celilo/event-bus": "^0.6.0",

package/src/cli/commands/module-remove.ts

@@ -14,7 +14,7 @@ import { capabilities as capabilitiesTable, moduleInfrastructure, modules } from
 import { createGaugeLogger } from '../../hooks/logger';
 import { runNamedHook } from '../../hooks/run-named-hook';
 import { deallocateForModule } from '../../ipam/auto-allocator';
-import { ModuleManifestSchema } from '../../manifest/schema';
+import { type ModuleManifest, ModuleManifestSchema } from '../../manifest/schema';
 import { executeBuildWithProgress } from '../../services/build-stream';
 import { askConfirm, withInterviewSession } from '../../services/bus-interview';
 import {
@@ -22,6 +22,7 @@ import {
   emitUninstallFailed,
   emitUninstallStarted,
 } from '../../services/celilo-events';
+import { loadConsumerCleanupPlan, runConsumerCleanup } from '../../services/consumer-cleanup';
 import { getContainerService, getServiceCredentials } from '../../services/container-service';
 import { completeOperation, failOperation, startOperation } from '../../services/module-operations';
 import {
@@ -29,7 +30,6 @@ import {
   describeRemovalRefusal,
   findRemovalBlockers,
 } from '../../services/remove-guard';
-import { cleanupWebRoutesForModule } from '../../services/web-route-cleanup';
 import { getArg, hasFlag, validateRequiredArgs } from '../parser';
 import { log } from '../prompts';
 import type { CommandResult } from '../types';
@@ -243,28 +243,31 @@ async function performModuleRemove(
     }
   }
 
-  // Reclaim public_web routes BEFORE terraform destroy, so the provider host
-  // is still reachable for the /srv/www cleanup. Runs after on_uninstall so a
-  // module that tears its own routes down still wins (this then no-ops).
+  // Tell every provider whose capability this module consumed that it is
+  // leaving, so each withdraws what it minted on its behalf
+  // (openspec/changes/consumer-removal-cleanup). BEFORE terraform destroy, so
+  // provider hosts are still reachable; AFTER on_uninstall, so a module that
+  // tears its own state down first still wins.
   //
-  // Without this, removal deleted the rows via the FK cascade on `modules.id`
-  // and emitted nothing, so the provider kept serving a route for a module that
-  // no longer existed. See services/web-route-cleanup.ts.
-  try {
-    const routeCleanup = await cleanupWebRoutesForModule({ moduleId, db });
-    if (routeCleanup.routesRemoved > 0) {
-      const reclaimed =
-        routeCleanup.assetDirsRemoved.length > 0
-          ? ` and reclaimed ${routeCleanup.assetDirsRemoved.join(', ')}`
-          : '';
-      log.info(`Removed ${routeCleanup.routesRemoved} web route(s) for ${moduleId}${reclaimed}`);
-    }
-    for (const warning of routeCleanup.warnings) {
-      log.warn(warning);
-    }
-  } catch (error) {
-    const msg = error instanceof Error ? error.message : String(error);
-    log.warn(`Web route cleanup failed (continuing): ${msg}`);
+  // This replaces the by-name `cleanupWebRoutesForModule` call, which did the
+  // same job for exactly one capability. A failed withdrawal never blocks the
+  // removal — the failing PROVIDER is marked ERROR instead (D6).
+  const cleanupLogger = {
+    info: (m: string) => log.info(m),
+    warn: (m: string) => log.warn(m),
+    error: (m: string) => log.warn(m),
+    success: (m: string) => log.info(m),
+  };
+  const cleanup = await runConsumerCleanup(
+    moduleId,
+    loadConsumerCleanupPlan(moduleId, module.manifestData as ModuleManifest, db),
+    db,
+    cleanupLogger,
+  );
+  if (cleanup.failures.length > 0) {
+    log.warn(
+      `${cleanup.failures.length} provider(s) could not withdraw state for '${moduleId}' and are now marked ERROR: ${cleanup.failures.map((f) => f.providerId).join(', ')}. Removal continues; run \`celilo system audit\` to see what each is holding.`,
+    );
   }
 
   // Check if module has infrastructure that needs to be destroyed

package/src/cli/commands/system-audit.ts

@@ -371,7 +371,11 @@ async function buildAuditDeps(onProgress?: (msg: string) => void) {
     backups: { modules: installedBackupInfo },
     abandonedOperations: { records: loadAbandonedOperations(db) },
     undeployedModules: {
-      modules: installed.map((m) => ({ id: m.id, state: m.state })),
+      modules: installed.map((m) => ({
+        id: m.id,
+        state: m.state,
+        errorMessage: m.errorMessage,
+      })),
     },
     unconfiguredModules: {
       modules: installed.map((m) => ({

package/src/cli/commands/system-update.ts

@@ -573,7 +573,11 @@ export async function handleSystemUpdate(
     },
     abandonedOperations: { records: loadAbandonedOperations(db) },
     undeployedModules: {
-      modules: installed.map((m) => ({ id: m.id, state: m.state })),
+      modules: installed.map((m) => ({
+        id: m.id,
+        state: m.state,
+        errorMessage: m.errorMessage,
+      })),
     },
     unconfiguredModules: {
       modules: installed.map((m) => ({
@@ -801,7 +805,11 @@ export function rebuildAuditDepsForRerun(
       })),
     },
     undeployedModules: {
-      modules: installed.map((m) => ({ id: m.id, state: m.state })),
+      modules: installed.map((m) => ({
+        id: m.id,
+        state: m.state,
+        errorMessage: m.errorMessage,
+      })),
     },
     unconfiguredModules: {
       modules: installed.map((m) => ({

package/src/db/schema.ts

@@ -591,19 +591,34 @@ export const portForwards = sqliteTable(
     /** Dedicated INTERNAL ingress IP (ISS-0156); NULL for the normal public path. */
     ingressIp: text('ingress_ip'),
     description: text('description').notNull().default(''),
+    /**
+     * The CONSUMER that registered it, stamped by the store from the calling
+     * module (openspec/changes/consumer-removal-cleanup, D5a). `''` for rows
+     * written before this column existed — unattributed, so no consumer removal
+     * withdraws them.
+     */
+    registeredBy: text('registered_by').notNull().default(''),
     createdAt: integer('created_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
   },
   (table) => ({
-    // One row per (firewall, backend, port, protocol, ingress). The store also
-    // delete-then-inserts on this tuple so a re-expose is an idempotent upsert
-    // (NULL ingress_ip is compared with `is null` there, since SQLite treats
-    // NULLs as distinct in a unique index).
+    // One row per (OWNER, firewall, backend, port, protocol, ingress). The
+    // owner is IN the index, not merely alongside it, and that is the whole
+    // point: without it, consumer B exposing a forward A already has silently
+    // REPLACES A's row, and B leaving then deletes a rule A still needs. Two
+    // owners of one forward are two rows — the set, denormalised into the
+    // table that already exists rather than a second table. `renderRuleset`
+    // dedupes on the rule tuple so the duplicate renders once.
+    //
+    // This is the `dns_registration_consumers` lesson (see below): a single
+    // overwritten owner column is not a label, because what cascades on it
+    // decides when a LIVE record is forgotten.
     forwardUnique: uniqueIndex('port_forwards_unique_idx').on(
       table.firewallIp,
       table.internalIp,
       table.port,
       table.protocol,
       table.ingressIp,
+      table.registeredBy,
     ),
   }),
 );
@@ -632,11 +647,14 @@ export const trustedSources = sqliteTable(
     createdAt: integer('created_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
   },
   (table) => ({
-    // One row per (firewall, subnet) — the store delete-then-inserts on this
-    // tuple so re-registering the same subnet is an idempotent upsert.
+    // One row per (OWNER, firewall, subnet) — same reason the owner is in
+    // `port_forwards_unique_idx`. Two modules trusting the same subnet are two
+    // rows, so one leaving does not revoke the other's reach. The renderer
+    // already dedupes trusted subnets (`new Set`), so the pair renders once.
     trustedSourceUnique: uniqueIndex('trusted_sources_unique_idx').on(
       table.firewallIp,
       table.subnet,
+      table.registeredBy,
     ),
   }),
 );

package/src/hooks/capability-loader.ts

@@ -113,6 +113,16 @@ export const CAPABILITY_MODULE_MAP: Record<string, { script: string; legacyFacto
       script: 'scripts/control-plane-vpn-functions.ts',
       legacyFactoryName: 'default',
     },
+    // MODULE-provided, unlike its sibling public_web above, which the framework
+    // implements (createPublicWeb) against celilo's `web_routes` table. The
+    // asymmetry is deliberate: a private route stored in `web_routes` would be
+    // picked up by the PUBLIC caddy, which derives its served hostnames from
+    // every row of that table — so the provider keeps its own routes and celilo
+    // core holds no private-ingress business at all (celilo#846).
+    private_web: {
+      script: 'scripts/private-web-functions.ts',
+      legacyFactoryName: 'default',
+    },
   };
 
 /**
@@ -247,7 +257,7 @@ export async function loadCapabilityFunctions(
     // buildFirewallChain handles the per-layer wrap with auto-logging
     // internally, so we don't need to wrap the result here.
     if (capName === 'firewall' && allProviders.length > 1) {
-      const firewallInterface = await buildFirewallChain(
+      const { chain, self } = await buildFirewallChain(
         allProviders,
         moduleInfo,
         masterKey,
@@ -256,8 +266,15 @@ export async function loadCapabilityFunctions(
         debugLog,
         consumingModuleId,
       );
-      if (firewallInterface) {
-        result[capName] = firewallInterface;
+      if (chain) {
+        result[capName] = chain;
+      }
+      // The chain hands a CONSUMER the innermost layer, which is not this
+      // provider's own layer when it sits further out. `on_consumer_removed`
+      // must converge THIS firewall, so it gets its own layer by name.
+      if (self) {
+        result.firewall_registry = self;
+        debugLog(`firewall_registry: provider view injected for ${consumingModuleId}`);
       }
       continue;
     }
@@ -359,7 +376,7 @@ export async function loadCapabilityFunctions(
         providerSecrets,
         // Single firewall provider (no upstream chain) still needs the injected
         // port-forward store — the chain path isn't taken when there's one provider.
-        capName === 'firewall' ? buildPortForwardStore(db) : undefined,
+        capName === 'firewall' ? buildPortForwardStore(db, consumingModuleId) : undefined,
         capName === 'firewall' ? loadFirewallZones(db) : undefined,
         // Bound to the CONSUMING module so a trusted-source registration is
         // attributable — reach into every tier must never be anonymous.
@@ -372,6 +389,12 @@ export async function loadCapabilityFunctions(
           wrapWithLogging(capabilityInterface as object, logger, capName),
         );
         debugLog(`${capName}: loaded via legacy factory`);
+        // Sole firewall provider running its OWN hook: the interface just built
+        // IS its layer, so hand it back under the provider-view name too.
+        if (capName === 'firewall' && consumingModuleId === capability.moduleId) {
+          result.firewall_registry = result[capName];
+          debugLog(`firewall_registry: provider view injected for ${consumingModuleId}`);
+        }
       }
     } catch (error) {
       debugLog(
@@ -977,6 +1000,20 @@ function parseInterfaceBaseline(raw: unknown): string[] | undefined {
   return names.length > 0 ? names : undefined;
 }
 
+/**
+ * What a firewall build hands back.
+ *
+ * `chain` is the layer a CONSUMER talks to (the innermost). `self` is the layer
+ * belonging to the module currently running a hook, and is null unless that
+ * module is itself one of the providers — it is what `on_consumer_removed`
+ * converges, and it differs from `chain` whenever the provider sits further out
+ * than the innermost layer.
+ */
+interface FirewallChain {
+  chain: unknown;
+  self: unknown | null;
+}
+
 async function buildFirewallChain(
   allProviders: Array<{
     id: number;
@@ -991,11 +1028,12 @@ async function buildFirewallChain(
   logger: HookLogger,
   debugLog: (msg: string) => void,
   consumingModuleId: string,
-): Promise<unknown> {
+): Promise<FirewallChain> {
   // The shared-core port-forward registry, injected into every firewall provider
   // in the chain so exposeService/converge reconcile against the one canonical
-  // store (openspec/changes/unified-management-no-ssh/proposal.md).
-  const store = buildPortForwardStore(db);
+  // store (openspec/changes/unified-management-no-ssh/proposal.md). Bound to the
+  // CONSUMING module so every forward it declares is attributable (D2).
+  const store = buildPortForwardStore(db, consumingModuleId);
   // Trusted-source registry, bound to the CONSUMING module so a registration is
   // attributable. Only the layers that render their own ruleset receive it.
   const trustedSourceStore = buildTrustedSourceStore(db, consumingModuleId);
@@ -1011,17 +1049,17 @@ async function buildFirewallChain(
 
   if (!hasExternal) {
     debugLog('firewall chain: no provider with external interface found');
-    return null;
+    return { chain: null, self: null };
   }
 
   // Build the leaf (external) firewall first
   const leafModule = db.select().from(modules).where(eq(modules.id, hasExternal.moduleId)).get();
-  if (!leafModule) return null;
+  if (!leafModule) return { chain: null, self: null };
 
   const leafModulePath = join(leafModule.sourcePath, moduleInfo.script);
   if (!existsSync(leafModulePath)) {
     debugLog(`firewall chain: leaf module not found at ${leafModulePath}`);
-    return null;
+    return { chain: null, self: null };
   }
 
   const leafConfig = await loadModuleConfig(hasExternal.moduleId, db);
@@ -1030,7 +1068,7 @@ async function buildFirewallChain(
   const leafExported =
     typeof leafMod.default === 'function' ? leafMod.default : leafMod[moduleInfo.legacyFactoryName];
 
-  if (typeof leafExported !== 'function') return null;
+  if (typeof leafExported !== 'function') return { chain: null, self: null };
 
   // Branded compiled factory (Phase 8 path): call with the canonical
   // context. wrapWithLogging is applied internally so the leaf interface
@@ -1071,8 +1109,15 @@ async function buildFirewallChain(
   // doesn't fit defineCapabilityFunction's single-context shape.
   const downstream = allProviders.filter((p) => p.moduleId !== hasExternal.moduleId);
 
+  // Each layer as its OWN provider sees it, so `on_consumer_removed` converges
+  // the firewall that declares the hook rather than whichever layer a consumer
+  // happens to talk to.
+  const selfLayer = (id: string, iface: unknown): unknown | null =>
+    id === consumingModuleId ? iface : null;
+  let self = selfLayer(hasExternal.moduleId, leafFirewall);
+
   if (downstream.length === 0) {
-    return leafFirewall;
+    return { chain: leafFirewall, self };
   }
 
   let currentUpstream = leafFirewall;
@@ -1147,9 +1192,10 @@ async function buildFirewallChain(
       wrapWithLogging(downstreamFirewall as object, logger, 'firewall'),
       provider.moduleId,
     );
+    self = self ?? selfLayer(provider.moduleId, currentUpstream);
   }
 
-  return currentUpstream;
+  return { chain: currentUpstream, self };
 }
 
 /**

package/src/hooks/define-hook.test.ts

@@ -70,9 +70,6 @@ const fakePublicWeb: PublicWebCapability = {
   async upload_static_assets() {
     return { success: true, filesUploaded: 0, contentHash: 'fake' };
   },
-  async unregister_routes() {
-    return undefined;
-  },
   async getServerIp() {
     return '10.0.10.10';
   },
@@ -298,9 +295,6 @@ describe('defineCapabilityFunction', () => {
         async upload_static_assets() {
           return { success: true, filesUploaded: 0, contentHash: 'x' };
         },
-        async unregister_routes() {
-          return undefined;
-        },
         async getServerIp() {
           return '10.0.10.10';
         },

package/src/hooks/executor.ts

@@ -28,6 +28,7 @@ import {
 } from '@celilo/capabilities';
 import {
   type ContractHookSignature,
+  contractHookSignature,
   resolveContract,
   supportedContractVersions,
 } from '../manifest/contracts';
@@ -435,7 +436,7 @@ export async function invokeHook(
     };
   }
 
-  const signature = contract.hooks[hookName];
+  const signature = contractHookSignature(contract.hooks, hookName);
   if (!signature) {
     return {
       success: false,

package/src/hooks/types.ts

@@ -104,25 +104,17 @@ export interface HookResult {
 }
 
 /**
- * Supported lifecycle hook names.
+ * Supported lifecycle hook names — re-exported from `@celilo/capabilities`,
+ * which owns the one list (celilo#821).
  *
- * Must stay in sync with the canonical hook list in
- * `apps/celilo/src/manifest/contracts/v1.ts` and with the schema's
- * `hooks` block in `apps/celilo/src/manifest/schema.ts`.
+ * This was a second hand-maintained copy, and it had already drifted: it was
+ * missing `reconcile_routes`, so caddy's public_web reconcile hook was a hook
+ * the celilo side of the codebase did not believe in.
  */
-export type HookName =
-  | 'container_created'
-  | 'on_install'
-  | 'on_uninstall'
-  | 'health_check'
-  | 'validate_config'
-  | 'on_backup'
-  | 'on_backup_analyze'
-  | 'on_restore'
-  | 'on_system_event'
-  | 'refresh_registrations'
-  | 'reassert_dhcp_dns'
-  | 'reconcile_clients';
+export type { HookName } from '@celilo/capabilities';
+export { HOOK_NAMES } from '@celilo/capabilities';
+
+import type { HookName } from '@celilo/capabilities';
 
 /**
  * Hook manifest section - maps hook names to definitions

package/src/manifest/contracts/index.ts

@@ -15,6 +15,26 @@ import type { ContractHookSignature, ContractHooks } from './v1';
 
 export type { ContractHooks, ContractHookSignature };
 
+/**
+ * Look up a hook signature by an UNTRUSTED name.
+ *
+ * `ContractHooks` is keyed by `HookName` (celilo#821), which is what makes a
+ * missing or unknown entry a compile error. The executor's `hookName` is a
+ * plain `string` on purpose — it comes from a module manifest, and deciding
+ * whether it names a real hook is precisely what the caller is asking. This
+ * helper is the one place that crossing is expressed, so every other use of
+ * `ContractHooks` stays exact.
+ *
+ * Returns `undefined` for a name the contract does not define; the caller
+ * turns that into "Hook 'x' is not part of celilo_contract 1.0".
+ */
+export function contractHookSignature(
+  hooks: ContractHooks,
+  name: string,
+): ContractHookSignature | undefined {
+  return (hooks as Record<string, ContractHookSignature | undefined>)[name];
+}
+
 /**
  * The shape of a registered contract.
  */