@celilo/cli 4.0.0 → 5.0.0

package/src/hooks/capability-loader.ts

@@ -36,6 +36,7 @@ import {
   NETWORK_ZONES,
   capabilities,
   modules,
+  privateRoutes,
   secrets,
   systemConfig,
   webRoutes,
@@ -45,7 +46,10 @@ import { decryptSecret } from '../secrets/encryption';
 import { getOrCreateMasterKey } from '../secrets/master-key';
 import { buildControlPlaneApi } from '../services/api-principal-enrolment';
 import { recordCapabilityBinding, withBindingRecord } from '../services/capability-bindings';
-import { emitWebRoutesChangedAndWait } from '../services/celilo-events';
+import {
+  emitPrivateRoutesChangedAndWait,
+  emitWebRoutesChangedAndWait,
+} from '../services/celilo-events';
 import { CONTROL_PLANE_MODULE_ID, getModuleSystems } from '../services/deployed-systems';
 import { withDnsInternalLedger } from '../services/dns-internal-records';
 import { withDnsRegistrationLedger } from '../services/dns-registrations';
@@ -95,22 +99,56 @@ import { loadHookConfigMap } from './load-hook-config';
  * success anyway, so a consumer could report "ready" while caddy never learned
  * the hostname — no site block, no cert, TLS internal_error for clients.
  */
-async function requireProviderReconcile(consumingModuleId: string, what: string): Promise<void> {
-  const reconcile = await emitWebRoutesChangedAndWait(consumingModuleId);
+/**
+ * Which ingress a reconcile is being required for. The two differ only in the
+ * event type they emit and the names their failures carry, so they share this
+ * function rather than each keeping a copy — a private ingress that silently
+ * stopped waiting would look exactly like one with nothing to wait for
+ * (providers-converge-declared-state, slice 2).
+ */
+const INGRESS = {
+  public_web: { capability: 'public_web', provider: 'caddy', emit: emitWebRoutesChangedAndWait },
+  private_web: {
+    capability: 'private_web',
+    provider: 'caddy-internal',
+    emit: emitPrivateRoutesChangedAndWait,
+  },
+} as const;
+
+async function requireProviderReconcile(
+  consumingModuleId: string,
+  what: string,
+  ingress: keyof typeof INGRESS = 'public_web',
+): Promise<void> {
+  const { capability, provider, emit } = INGRESS[ingress];
+  const reconcile = await emit(consumingModuleId);
 
   if (reconcile.noDispatcher) {
     throw new Error(
-      `public_web ${what} for ${consumingModuleId} was persisted but NOT delivered to the provider (caddy): no event dispatcher is running, so caddy never reconciled and the hostname has no site block or cert. Run this through \`celilo module deploy\` (which runs the dispatcher) rather than a bare hook.`,
+      `${capability} ${what} for ${consumingModuleId} was persisted but NOT delivered to the provider (${provider}): no event dispatcher is running, so ${provider} never reconciled and the hostname has no site block or cert. Run this through \`celilo module deploy\` (which runs the dispatcher) rather than a bare hook.`,
     );
   }
+  // The handler's own words, when it left any. A crash is retried, so its
+  // delivery sits in `pending` with the error already recorded while the
+  // deadline runs out — which is how celilo#1401 reported a TIMEOUT for a
+  // caddy crash, for days, with `0 ok, 0 failed of 1` and the cause nowhere.
+  const because = reconcile.lastError ? ` The provider reported: ${reconcile.lastError}` : '';
+
   if (reconcile.timedOut) {
+    // "0 ok, 0 failed" reads as "nobody consumed it", which sends the reader to
+    // the dispatcher (celilo#1398/#1399) when the truth is that the provider's
+    // deliveries were STILL RUNNING at the deadline (celilo#1416). Say which.
+    const inFlight =
+      reconcile.stillRunning > 0
+        ? `${reconcile.stillRunning} delivery(ies) still running`
+        : `${reconcile.succeeded} ok, ${reconcile.failed} failed`;
     throw new Error(
-      `public_web reconcile for ${consumingModuleId} (${what}) did not finish within the deadline (${reconcile.succeeded} ok, ${reconcile.failed} failed of ${reconcile.events} change event(s)) — caddy did not confirm the change is live.`,
+      `${capability} reconcile for ${consumingModuleId} (${what}) did not finish within its ${Math.round(reconcile.budgetMs / 1000)}s budget (${inFlight} of ${reconcile.events} change event(s)) — ${provider} did not confirm the change is live.${because}`,
     );
   }
   if (reconcile.failed > 0) {
     throw new Error(
-      `public_web reconcile for ${consumingModuleId} (${what}): ${reconcile.failed} delivery(ies) failed — caddy could not apply the change, so the hostname is not served as declared.`,
+      `${capability} reconcile for ${consumingModuleId} (${what}): ${reconcile.failed} delivery(ies) failed — ${provider} could not apply the change, so the hostname is not served as declared.${because}`,
     );
   }
   // ISS-0087: a change WAS persisted and the dispatcher IS alive, yet ZERO
@@ -120,7 +158,7 @@ async function requireProviderReconcile(consumingModuleId: string, what: string)
   // changed and nobody served it — a failure.
   if (reconcile.events > 0 && reconcile.succeeded === 0) {
     throw new Error(
-      `public_web ${what} for ${consumingModuleId} changed (${reconcile.events} event(s)) but NO provider reconciled it — caddy has no reconcile_routes subscription on the bus, so the change is persisted yet never served. Ensure a public_web provider (caddy) is deployed and subscribed.`,
+      `${capability} ${what} for ${consumingModuleId} changed (${reconcile.events} event(s)) but NO provider reconciled it — ${provider} has no reconcile_routes subscription on the bus, so the change is persisted yet never served. Ensure a ${capability} provider (${provider}) is deployed and subscribed.`,
     );
   }
 }
@@ -169,11 +207,13 @@ export const CAPABILITY_MODULE_MAP: Record<string, { script: string; legacyFacto
       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).
+    // implements (createPublicWeb). The two ingresses are separate TABLES, not
+    // separate owners: core owns `private_routes` as it owns `web_routes`
+    // (migration 0034), and that separation — not the provider keeping its own
+    // config — is what stops the PUBLIC caddy, which derives its served
+    // hostnames from every row of `web_routes`, from sweeping a private route
+    // into the public ingress (celilo#846). What stays module-side is the
+    // RENDER: caddy-internal decides what its Caddyfile says.
     private_web: {
       script: 'scripts/private-web-functions.ts',
       legacyFactoryName: 'default',
@@ -493,6 +533,26 @@ export async function loadCapabilityFunctions(
           // same seam. A jailed hook cannot write into its own web root, so a
           // module-provided web provider needs the state overlay to honor it.
           consumerStateWebRoot: resolveModuleStateWebRoot(consumingModuleId, db),
+          // THE PRIVATE INGRESS'S DECLARED ROWS, for the provider that serves
+          // them. Scoped to private_web deliberately: these are one
+          // capability's declared state, and handing them to every
+          // module-provided capability would put the private route table in
+          // reach of modules that have no business reading it.
+          ...(capName === 'private_web'
+            ? {
+                privateRoutes: buildPrivateRouteOps(db),
+                // The same seam public_web has (see `onRoutesChanged` below):
+                // the capability persists the row and hands the converge to
+                // the provider's `reconcile_routes` subscription, then AWAITS
+                // that delivery so `registerReverseProxy` still returns only
+                // once the route is live (design D7). One primitive, two
+                // triggers — the subscription is the second, not a
+                // replacement for the call.
+                onRoutesChanged: async () => {
+                  await requireProviderReconcile(consumingModuleId, 'route change', 'private_web');
+                },
+              }
+            : {}),
         });
         // Stamp here too, not only on the legacy path: a consumer that cannot
         // get what it needs must be able to name WHICH provider could not give
@@ -811,6 +871,51 @@ export async function loadCapabilityFunctions(
     debugLog('public_web: not registered in DB, skipping');
   }
 
+  // THE PRIVATE INGRESS, symmetric with the public one above (design D7 of
+  // providers-converge-declared-state). Its provider gets a view of the rows it
+  // serves and the converge that places what it renders — the same two things
+  // caddy gets, for the same reason, now that its routes are core-owned state
+  // rather than its own module-config JSON.
+  //
+  // Consumers never see either: only the module that PROVIDES private_web.
+  const privateWebProviders = db
+    .select()
+    .from(capabilities)
+    .where(eq(capabilities.capabilityName, 'private_web'))
+    .all();
+  const privateWebProvider = privateWebProviders[0];
+  if (privateWebProvider && consumingModuleId === privateWebProvider.moduleId) {
+    result.private_routes = buildPrivateRouteOps(db);
+    debugLog(`private_routes: injected for provider ${consumingModuleId}`);
+
+    const providerModuleId = privateWebProvider.moduleId;
+    const privateConverge: ProviderConvergeView = {
+      // The private ingress serves no consumer-built static sites today: every
+      // row it renders is a reverse proxy. Answering honestly rather than
+      // throwing keeps the shape identical to the public provider's, so one
+      // renderer contract covers both (design D1).
+      resolveConsumerSite: async (moduleId: string) => ({
+        unavailable: `the private ingress serves no static sites, so '${moduleId}' has none here`,
+      }),
+      converge: async (artifacts) => {
+        const { convergeProviderConfig, resolveStaticContentRetention } = await import(
+          '../services/provider-converge'
+        );
+        const result = await convergeProviderConfig(db, providerModuleId, {
+          ...artifacts,
+          retention: resolveStaticContentRetention(db, providerModuleId),
+        });
+        return {
+          success: result.success,
+          ...(result.error ? { error: result.error } : {}),
+          unresolved: result.unresolved,
+        };
+      },
+    };
+    result.provider_converge = privateConverge;
+    debugLog(`provider_converge: injected for private provider ${consumingModuleId}`);
+  }
+
   // Framework-granted, so unlike everything above there is no provider row to
   // look up and no script to import — celilo IS the management server whose
   // principals these are (web-ui-console D7b).
@@ -1482,6 +1587,74 @@ async function buildFirewallChain(
   return { chain: currentUpstream, self };
 }
 
+/**
+ * Route ops for the private_web PROVIDER, over `private_routes`.
+ *
+ * The private ingress's rows are core-owned declared state now, exactly as
+ * `web_routes` is for public_web (design D1 of
+ * providers-converge-declared-state). They used to live in caddy-internal's
+ * `routes` module-config JSON, which is why the two ingresses could not share
+ * plumbing: celilo had nothing to render, converge or audit.
+ *
+ * SEPARATE TABLE, and that is the whole safety property. The public provider
+ * derives the hostnames it serves from every row of ITS table, so a private
+ * route sharing that table is one missing WHERE clause from being served
+ * publicly with a public certificate (celilo#846). Injected only into the
+ * private_web provider's own capability functions, the same way the route view
+ * reaches caddy and no one else.
+ *
+ * Rows go out in the snake_case shape the provider's renderer already speaks,
+ * so the module needs no translation layer and its existing route tests keep
+ * asserting the same objects.
+ */
+function buildPrivateRouteOps(db: DbClient) {
+  const toRecord = (row: typeof privateRoutes.$inferSelect) => ({
+    module_id: row.moduleId,
+    slug: row.slug,
+    type: row.type,
+    path: row.path,
+    hostname: row.hostname,
+    ...(row.targetHost ? { target_host: row.targetHost } : {}),
+    ...(row.targetPort ? { target_port: row.targetPort } : {}),
+    ...(row.websocket ? { websocket: row.websocket } : {}),
+  });
+
+  return {
+    all: () => db.select().from(privateRoutes).all().map(toRecord),
+    /**
+     * Replace the whole set.
+     *
+     * The provider keeps the full route list in memory for the life of one
+     * hook run and hands it back whole, which is the semantics its config key
+     * had. Honouring that here keeps the change to the module small and the
+     * two halves easy to reason about.
+     *
+     * ponytail: whole-set replace, in one transaction so a reader never sees
+     * an empty ingress. If two providers ever write this table concurrently,
+     * this becomes per-row upsert plus a delete of what the writer dropped.
+     */
+    replaceAll: (rows: ReturnType<typeof toRecord>[]) => {
+      db.transaction((tx) => {
+        tx.delete(privateRoutes).run();
+        for (const row of rows) {
+          tx.insert(privateRoutes)
+            .values({
+              slug: row.slug,
+              moduleId: row.module_id,
+              type: row.type,
+              path: row.path,
+              hostname: row.hostname,
+              targetHost: row.target_host ?? null,
+              targetPort: row.target_port ?? null,
+              websocket: row.websocket ?? false,
+            })
+            .run();
+        }
+      });
+    },
+  };
+}
+
 /**
  * Build RouteOps for the public_web capability implementation.
  * Wraps database operations so the capability never touches the DB directly.

package/src/hooks/executor.test.ts

@@ -529,7 +529,7 @@ describe('Hook Executor', () => {
       const result = await invokeHook(
         __dirname,
         'container_created',
-        '1.0',
+        '2.0',
         { script: './test-fixtures/artifact-writing-hook.ts', timeout: 10000 },
         { vps_ip: '10.0.0.5' },
         {},
@@ -560,7 +560,7 @@ describe('Hook Executor', () => {
       const result = await invokeHook(
         __dirname,
         'container_created',
-        '1.0',
+        '2.0',
         { script: './test-fixtures/success-hook.ts', timeout: 10000 },
         { vps_ip: '10.0.0.5' },
         {},
@@ -585,7 +585,7 @@ describe('Hook Executor', () => {
       const result = await invokeHook(
         __dirname,
         'container_created',
-        '1.0',
+        '2.0',
         { script: './test-fixtures/success-hook.ts', timeout: 10000 },
         { vps_ip: '10.0.0.5' },
         {},
@@ -614,7 +614,7 @@ describe('Hook Executor', () => {
       const result = await invokeHook(
         __dirname,
         'container_created',
-        '1.0',
+        '2.0',
         definition,
         { vps_ip: '10.0.0.5' },
         { username: 'test' },
@@ -641,7 +641,7 @@ describe('Hook Executor', () => {
       const result = await invokeHook(
         __dirname,
         'on_backup',
-        '1.0',
+        '2.0',
         definition,
         {},
         {},
@@ -663,7 +663,7 @@ describe('Hook Executor', () => {
       const result = await invokeHook(
         __dirname,
         'container_created',
-        '1.0',
+        '2.0',
         definition,
         {},
         {},
@@ -686,7 +686,7 @@ describe('Hook Executor', () => {
       const result = await invokeHook(
         __dirname,
         'on_backup',
-        '1.0',
+        '2.0',
         definition,
         { backup_dir: '/tmp/backup' },
         {},
@@ -708,7 +708,7 @@ describe('Hook Executor', () => {
       const result = await invokeHook(
         __dirname,
         'container_created',
-        '1.0',
+        '2.0',
         definition,
         {},
         {},
@@ -743,10 +743,10 @@ describe('Hook Executor', () => {
       const { logger } = createCapturingLogger();
       const definition: HookDefinition = { script: './test-fixtures/success-hook.ts' };
 
-      const result = await invokeHook(__dirname, 'on_poop', '1.0', definition, {}, {}, {}, logger);
+      const result = await invokeHook(__dirname, 'on_poop', '2.0', definition, {}, {}, {}, logger);
 
       expect(result.success).toBe(false);
-      expect(result.error).toContain("Hook 'on_poop' is not part of celilo_contract 1.0");
+      expect(result.error).toContain("Hook 'on_poop' is not part of celilo_contract 2.0");
     });
 
     test('pre-flight: fails when a required capability is missing', async () => {
@@ -759,7 +759,7 @@ describe('Hook Executor', () => {
       const result = await invokeHook(
         __dirname,
         'container_created',
-        '1.0',
+        '2.0',
         definition,
         { vps_ip: '10.0.0.5' },
         {},
@@ -786,7 +786,7 @@ describe('Hook Executor', () => {
       const result = await invokeHook(
         __dirname,
         'container_created',
-        '1.0',
+        '2.0',
         definition,
         { vps_ip: '10.0.0.5' },
         {},
@@ -813,7 +813,7 @@ describe('Hook Executor', () => {
       const result = await invokeHook(
         __dirname,
         'container_created',
-        '1.0',
+        '2.0',
         definition,
         { vps_ip: '10.0.0.5' },
         {},

package/src/hooks/executor.ts

@@ -511,7 +511,14 @@ export async function executeHookScript(
       setTimeout(() => child.kill('SIGKILL'), SIGKILL_GRACE_MS).unref();
     };
 
-    const totalTimer = setTimeout(() => kill('total'), timeoutMs);
+    // Snapshotted inside the timer rather than read at throw time: the child's
+    // death rejects its in-flight calls, so by the time we build the message
+    // the map that knows the answer has drained itself.
+    let pendingCallsAtKill: string[] = [];
+    const totalTimer = setTimeout(() => {
+      pendingCallsAtKill = broker.pendingCalls();
+      kill('total');
+    }, timeoutMs);
     // Debug runs get no idle timer, same as before: an operator stepping
     // through a browser hook is silent for minutes on purpose.
     const idleTimer = context.debug
@@ -536,7 +543,18 @@ export async function executeHookScript(
     // nothing keeps running past this line. That is the difference from the
     // `Promise.race` this replaces (celilo#1003).
     if (killedFor === 'total') {
-      throw new Error(`Hook total timeout exceeded (${Math.round(timeoutMs / 1000)}s)`);
+      // Name what it was WAITING ON, not just that it waited. A hook whose
+      // budget is consumed by one slow provider used to die as a bare
+      // "Hook total timeout exceeded", so the operator had to infer the
+      // provider from a capability push line with no matching completion
+      // (celilo#1403: bna-yard-sale's 120s on_install blocked on caddy's 75s
+      // route reconcile). Captured before `close()`, while the calls are
+      // still in flight — `stop()` refuses new calls but clears nothing.
+      const waitingOn = pendingCallsAtKill;
+      const waitingSuffix = waitingOn.length > 0 ? `, waiting on ${waitingOn.join(', ')}` : '';
+      throw new Error(
+        `Hook total timeout exceeded (${Math.round(timeoutMs / 1000)}s)${waitingSuffix}`,
+      );
     }
     if (killedFor === 'idle') {
       throw new Error(

package/src/hooks/hook-state-dir.test.ts

@@ -62,7 +62,7 @@ describe('celilo#1000: a hook is TOLD where its state directory is', () => {
       const result = await invokeHook(
         root,
         'on_install',
-        '1.0',
+        '2.0',
         { script: 'hook.ts' },
         {},
         {},
@@ -97,7 +97,7 @@ describe('celilo#1000: a hook is TOLD where its state directory is', () => {
       const result = await invokeHook(
         root,
         'on_install',
-        '1.0',
+        '2.0',
         { script: 'hook.ts' },
         {},
         {},

package/src/hooks/test-fixtures/slow-capability-hook.ts

@@ -0,0 +1,28 @@
+/**
+ * Test fixture: a hook that blocks inside a capability call it never gets an
+ * answer to, and is killed at its own total timeout (celilo#1403).
+ *
+ * The real shape is a consumer's `on_install` calling
+ * `public_web.publishStaticSite`, which blocks on the provider's route
+ * reconcile. This fixture reproduces the boundary condition — a call in flight
+ * when the kill lands — without a provider.
+ *
+ * It logs BEFORE the call so the run is not mistaken for an idle timeout, then
+ * awaits forever.
+ */
+
+import { defineHook } from '@celilo/capabilities';
+
+interface SlowCapability {
+  neverReturns(request: Record<string, unknown>): Promise<unknown>;
+}
+
+export default defineHook({
+  hook: 'container_created',
+  requires: [],
+  handler: async (ctx) => {
+    const slow = (ctx.capabilities as unknown as Record<string, SlowCapability>).slow_provider;
+    ctx.logger.info('calling the provider');
+    await slow.neverReturns({});
+  },
+});

package/src/hooks/test-fixtures/store-backed.ts

@@ -1,4 +1,4 @@
-import type { HookStore, HookStoreBackedMap } from '@celilo/capabilities';
+import type { HookStore } from '@celilo/capabilities';
 
 /**
  * In-memory hook-owned-state stores for tests that build a HookContext
@@ -16,10 +16,12 @@ export function configStore(
   return attach(values);
 }
 
-export function secretStore(values: Record<string, string> = {}): HookStoreBackedMap {
+export function secretStore(
+  values: Record<string, string> = {},
+): Record<string, string> & HookStore {
   // Downcast: the caller passed Record<string, string>; attach only adds
   // methods and never writes, so the value type is unchanged.
-  return attach(values) as HookStoreBackedMap;
+  return attach(values) as Record<string, string> & HookStore;
 }
 
 function attach(values: Record<string, unknown>): Record<string, unknown> & HookStore {

package/src/hooks/timeout-names-provider.test.ts

@@ -0,0 +1,87 @@
+/**
+ * A hook killed at its TOTAL timeout must name what it was waiting on.
+ *
+ * Measured 2026-09-21 (celilo#1403): bna-yard-sale's `on_install` called
+ * `public_web.publishStaticSite`, which blocks on caddy's route reconcile —
+ * 70-75s across the fleet's sites. The consumer died at its 120s budget with:
+ *
+ *     [bna-yard-sale:on_install] -> public_web.publishStaticSite
+ *     [bna-yard-sale:on_install] OK dns_registrar.registerHost
+ *     [bna-yard-sale:on_install] OK dns_internal.registerRecord
+ *     [bna-yard-sale:on_install] FAIL Hook total timeout exceeded (120s)
+ *
+ * Both DNS calls completed; the push line had no matching completion, and that
+ * ABSENCE was the only evidence of which provider held it. The error named the
+ * hook and never the cause, so the operator had to infer it from a gap in the
+ * log — the same class of missing signal the greenwave/axon ISP-router hooks
+ * already carry a comment about.
+ */
+import { describe, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { executeHookScript } from './executor';
+import { createCapturingLogger } from './logger';
+import { configStore, secretStore } from './test-fixtures/store-backed';
+import type { HookContext } from './types';
+
+const FIXTURES = join(__dirname, 'test-fixtures');
+
+/** A capability whose one method never settles — the provider that holds the hook. */
+function hangingCapabilities(): Record<string, unknown> {
+  return {
+    slow_provider: {
+      providerModuleId: 'caddy',
+      version: '1.0.0',
+      neverReturns: () => new Promise(() => {}),
+    },
+  };
+}
+
+async function runUntilTotalTimeout(): Promise<Error> {
+  const dir = mkdtempSync(join(tmpdir(), 'celilo-timeout-'));
+  try {
+    const context: HookContext = {
+      config: configStore(),
+      secrets: secretStore(),
+      systems: [],
+      logger: createCapturingLogger().logger,
+      debug: false,
+      screenshotDir: dir,
+      stateDir: dir,
+      capabilities: hangingCapabilities(),
+    };
+    try {
+      await executeHookScript(join(FIXTURES, 'slow-capability-hook.ts'), context, {
+        // Total well under idle, so the kill is unambiguously the TOTAL one:
+        // a hook blocked in a capability call emits nothing, so a shorter idle
+        // timer would win the race and prove a different thing.
+        timeoutMs: 3_000,
+        idleTimeoutMs: 60_000,
+      });
+    } catch (error) {
+      return error as Error;
+    }
+    throw new Error('the hook returned; it was supposed to be killed at its total timeout');
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+describe('a total-timeout error names the provider it was waiting on (celilo#1403)', () => {
+  test('the run reached the total timeout, not the idle one', async () => {
+    const error = await runUntilTotalTimeout();
+    // Anchor the subject: an idle kill would exercise none of this.
+    expect(error.message).toContain('Hook total timeout exceeded');
+    expect(error.message).not.toContain('idle');
+  }, 20_000);
+
+  test('the message names the provider, the capability and the method', async () => {
+    const error = await runUntilTotalTimeout();
+    expect(error.message).toContain('waiting on');
+    // The provider MODULE is the operationally useful half — it is what the
+    // operator goes and looks at. `caddy` comes from `providerModuleId`.
+    expect(error.message).toContain('caddy');
+    expect(error.message).toContain('slow_provider.neverReturns');
+  }, 20_000);
+});

package/src/manifest/contracts/index.ts

@@ -5,13 +5,15 @@
  * manifest's `celilo_contract` field selects which contract applies; the
  * registry is the single source of truth for what each version promises.
  *
- * To mint a new contract version: add a new file (e.g. `./v2.ts`), import its
- * contract object here, and register it in `CONTRACTS`. Old contracts stay
- * registered indefinitely so legacy modules continue to validate.
+ * To mint a new contract version: add a new file (e.g. `./v3.ts`), import its
+ * contract object here, and register it in `CONTRACTS`. A version whose
+ * modules still work stays registered; a version whose modules would now FAIL
+ * SILENTLY moves to `RETIRED_CONTRACT_VERSIONS` with the reason, so the
+ * validator refuses it by name rather than dropping state at deploy time.
  */
 
-import { V1_CONTRACT } from './v1';
 import type { ContractHookSignature, ContractHooks } from './v1';
+import { V2_CONTRACT } from './v2';
 
 export type { ContractHooks, ContractHookSignature };
 
@@ -26,7 +28,7 @@ export type { ContractHooks, ContractHookSignature };
  * `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".
+ * turns that into "Hook 'x' is not part of celilo_contract 2.0".
  */
 export function contractHookSignature(
   hooks: ContractHooks,
@@ -53,16 +55,35 @@ export interface Contract {
  * `SUPPORTED_CONTRACT_VERSIONS` below so Zod's enum picks it up.
  */
 export const CONTRACTS: Record<string, Contract> = {
-  '1.0': V1_CONTRACT,
+  '2.0': V2_CONTRACT,
+};
+
+/**
+ * Versions a manifest may still NAME but that no longer validate, mapped to
+ * the reason. A retired version is kept here rather than simply deleted so
+ * the validator can say what broke and how to move, instead of reporting a
+ * known version as an unrecognised string.
+ */
+export const RETIRED_CONTRACT_VERSIONS: Record<string, string> = {
+  '1.0':
+    'contract 1.0 persisted a hook\'s returned record as the module\'s secrets and config. That channel is removed (openspec/changes/hook-owned-state D5) — a 1.0 hook would deploy successfully and store nothing. Declare celilo_contract "2.0" and persist state with context.config.set / context.secrets.set against names the manifest declares.',
 };
 
 /**
  * Const tuple of supported contract version strings, used to drive the Zod
  * enum that validates the manifest's `celilo_contract` field.
  */
-export const SUPPORTED_CONTRACT_VERSIONS = ['1.0'] as const;
+export const SUPPORTED_CONTRACT_VERSIONS = ['2.0'] as const;
 export type SupportedContractVersion = (typeof SUPPORTED_CONTRACT_VERSIONS)[number];
 
+/**
+ * Every version string a manifest is allowed to WRITE — supported plus
+ * retired. The schema enum accepts these so a retired version reaches
+ * `validateHookContract`, which explains the retirement; anything else is a
+ * plain unknown-version error from Zod.
+ */
+export const KNOWN_CONTRACT_VERSIONS = ['1.0', '2.0'] as const;
+
 /**
  * Look up a contract by version string.
  *

package/src/manifest/contracts/v2.ts

@@ -0,0 +1,32 @@
+/**
+ * Celilo Module Contract — v2.0
+ *
+ * Hook SIGNATURES are unchanged from v1.0 — `V2_HOOKS` is `V1_HOOKS`. What
+ * changed is what the framework does with a hook's return value: nothing.
+ *
+ * Under v1.0, a record returned from `validate_config`, `on_install` or
+ * `container_created` was swept back into the module's secrets (and, for
+ * validate_config, its config). That was the only write channel a hook had,
+ * so a hook that needed to persist something it discovered had to return it.
+ * The channel is gone (openspec/changes/hook-owned-state, D5): a hook now
+ * persists state explicitly through `context.config.set` / `context.secrets.set`,
+ * against names its manifest declares.
+ *
+ * This is a MAJOR bump rather than a v1.x clarification because a module
+ * written against the old channel keeps deploying and silently stores
+ * nothing — the deploy reports success and the state is dropped. Refusing
+ * `celilo_contract: "1.0"` outright (see `RETIRED_CONTRACT_VERSIONS`) turns
+ * that silent loss into a message naming the fix, which is the whole point of
+ * versioning the contract.
+ */
+
+import { V1_HOOKS } from './v1';
+import type { ContractHooks } from './v1';
+
+/** v2.0 hook signatures — identical to v1.0. The break is behavioural. */
+export const V2_HOOKS: ContractHooks = V1_HOOKS;
+
+export const V2_CONTRACT = {
+  version: '2.0' as const,
+  hooks: V2_HOOKS,
+};