@celilo/cli 2.3.0 → 3.1.0

package/src/hooks/test-fixtures/store-writing-hook.ts

@@ -3,25 +3,32 @@
  * the process boundary — set/get round trip on both stores, delete, a
  * committed transaction, a discarded transaction, and the undeclared-name
  * throw the whole design exists to produce.
+ *
+ * Reports through a JSON file in its state directory: hook return values
+ * are no longer carried anywhere (hook-owned-state D5), and the state
+ * directory is the sanctioned place a hook hands structured data to its
+ * caller.
  */
 
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { defineHook } from '@celilo/capabilities';
 
 export default defineHook({
   hook: 'on_install',
   requires: [],
   handler: async (ctx) => {
-    const outputs: Record<string, unknown> = {};
+    const report: Record<string, unknown> = {};
 
     // Round trip on each store.
     await ctx.secrets.set('bot_token', 'token-value');
-    outputs.secretRoundTrip = await ctx.secrets.get('bot_token');
+    report.secretRoundTrip = await ctx.secrets.get('bot_token');
 
     await ctx.config.set('public_ip', '203.0.113.7');
-    outputs.configRoundTrip = await ctx.config.get('public_ip');
+    report.configRoundTrip = await ctx.config.get('public_ip');
 
     // The map surface still answers from the values the context carried.
-    outputs.mapRead = ctx.config.mapOnlyValue;
+    report.mapRead = ctx.config.mapOnlyValue;
 
     // Delete removes; deleting a declared-but-never-written name is a no-op.
     // (An UNDECLARED name on delete throws — that is 3.4, tested below.
@@ -29,15 +36,15 @@ export default defineHook({
     await ctx.secrets.delete('bot_token');
     await ctx.secrets.set('api_key', 'to-delete');
     await ctx.secrets.delete('api_key');
-    outputs.deletedIsGone = await ctx.secrets.get('api_key');
+    report.deletedIsGone = await ctx.secrets.get('api_key');
 
     // Committed transaction: both writes land.
     await ctx.secrets.transaction((s) => {
       s.set('bot_token', 'committed-a');
       s.set('api_key', 'committed-b');
     });
-    outputs.transactionA = await ctx.secrets.get('bot_token');
-    outputs.transactionB = await ctx.secrets.get('api_key');
+    report.transactionA = await ctx.secrets.get('bot_token');
+    report.transactionB = await ctx.secrets.get('api_key');
 
     // Discarded transaction: nothing lands, including the overwrite of the
     // committed value above.
@@ -47,17 +54,19 @@ export default defineHook({
         throw new Error('hook failed midway');
       });
     } catch (error) {
-      outputs.discarded = (error as Error).message;
+      report.discarded = (error as Error).message;
     }
-    outputs.afterDiscard = await ctx.secrets.get('bot_token');
+    report.afterDiscard = await ctx.secrets.get('bot_token');
 
     // An undeclared name throws, naming the module and the declared set.
     try {
       await ctx.secrets.set('not_declared', 'x');
     } catch (error) {
-      outputs.undeclaredSecret = (error as Error).message;
+      report.undeclaredSecret = (error as Error).message;
     }
 
-    return outputs;
+    // Hand the report to the caller through the state directory, the one
+    // channel a hook still has.
+    writeFileSync(join(ctx.stateDir as string, 'report.json'), JSON.stringify(report));
   },
 });

package/src/hooks/test-fixtures/success-hook.ts

@@ -2,9 +2,10 @@
  * Test fixture: successful hook script. Migrated to defineHook in
  * HOOK_API_V2 Phase 8 — the executor now requires the brand.
  *
- * Uses `hook: 'container_created'` because that hook's contract output
- * is `SecretCapturingHookOutput` (Record<string, unknown> | void), so
- * returning an `api_key` field is allowed.
+ * Declares `hook: 'container_created'` and returns void: hook return
+ * values are no longer persisted or consumed (hook-owned-state D5), so a
+ * hook reports through the logger and, where a test needs structured data
+ * back, through a file written to its state directory.
  */
 
 import { defineHook } from '@celilo/capabilities';
@@ -15,6 +16,5 @@ export default defineHook({
   handler: async (ctx) => {
     ctx.logger.info('Starting test hook');
     ctx.logger.success('Test hook completed');
-    return { api_key: `test-key-for-${(ctx.vps_ip as string | undefined) ?? 'unknown'}` };
   },
 });

package/src/manifest/contracts/v1.ts

@@ -71,15 +71,8 @@ export interface ContractHookSignature {
  * a name added to `HOOK_NAMES` without an entry here is a type error, and an
  * entry here for a name that is not a hook is one too. It was `Record<string,
  * …>`, which is why the drift went unnoticed for months.
- *
- * `on_upstream_publish` is named explicitly because it is NOT a `HookName` — an
- * array of build-bus match rules rather than an invokable hook. It has a
- * signature here because the executor passes its payload as env vars and the
- * contract is where that is written down.
  */
-export type ContractHooks = Record<HookName, ContractHookSignature> & {
-  on_upstream_publish: ContractHookSignature;
-};
+export type ContractHooks = Record<HookName, ContractHookSignature>;
 
 /**
  * Contract v1.0 — current canonical hook signatures.
@@ -370,14 +363,26 @@ export const V1_HOOKS: ContractHooks = {
     outputs: {},
   },
   /**
-   * Build-bus upstream publish hook. The executor passes the
-   * PublishEvent fields as env vars (CELILO_EVENT_PAYLOAD,
-   * CELILO_EVENT_PACKAGE_NAME, etc.) rather than as named inputs
-   * here — see openspec/changes/build-bus-poll-cd/proposal.md Phase 4 + the hook-dispatch executor.
-   * No structured outputs; hook reports success via exit code.
+   * Build-bus upstream publish hook (module-orchestrator-primitives slice 7).
+   * An ordinary hook: the build-bus receiver daemon dispatches it through the
+   * executor, jailed, with the verified PublishEvent as the `event` input in
+   * the hook's typed context. It used to be a bash script reached by env vars
+   * (`CELILO_EVENT_*`) on a second, unjailed execution path.
+   *
+   * `event` is a required input, which by the contract's own rule would be a
+   * breaking change needing a v2.0 contract. No v2 is minted because no module
+   * declares this hook as an invokable script: the only in-tree consumer was
+   * celilo-mgmt's bash entry, deleted in the same slice, and the dispatcher
+   * that invoked the old form never went through this table at all. The v1
+   * entry is being corrected to describe the shape the executor now actually
+   * passes, in the same @celilo/cli major that changes the manifest field's
+   * shape (tasks.md 7.6).
    */
   on_upstream_publish: {
-    inputs: {},
+    inputs: {
+      /** The verified PublishEvent, as received from the build bus. */
+      event: { required: true },
+    },
     outputs: {},
   },
 };

package/src/manifest/json-schema-roundtrip.test.ts

@@ -45,7 +45,7 @@ function findActiveManifests(): string[] {
   const manifests: string[] = [];
 
   for (const entry of entries) {
-    if (entry === 'archive' || entry.startsWith('.')) continue;
+    if (entry === '__archive__' || entry.startsWith('.')) continue;
     const dir = join(MODULES_DIR, entry);
     if (!statSync(dir).isDirectory()) continue;
     const manifestPath = join(dir, 'manifest.yml');

package/src/manifest/schema.ts

@@ -105,6 +105,25 @@ export const SecretGenerateSchema = z.object({
   identity: z.string().optional(),
 });
 
+/**
+ * A recorded decision that a module needs no health check
+ * (openspec/changes/health-waiver-mechanism, D2). All three fields are
+ * required: an anonymous or undated waiver is a check that disappeared.
+ * Strict — an unknown field must fail manifest load, not silently vanish.
+ */
+export const HealthWaiverSchema = z
+  .object({
+    /** The human's words, recorded verbatim. */
+    reason: z.string().min(1),
+    /** Who made the decision. */
+    by: z.string().min(1),
+    /** When — an ISO date. */
+    at: z.string().refine((value) => !Number.isNaN(Date.parse(value)), {
+      message: 'health_waiver.at must be an ISO date string',
+    }),
+  })
+  .strict();
+
 export const SecretDeclareSchema = z.object({
   name: z.string().min(1),
   // `string-map` is `Record<string, string>` (e.g. domain → password). It's
@@ -304,14 +323,17 @@ export const HealthCheckHookSchema = LifecycleHookSchema.extend({
 
 /**
  * Build-bus upstream-publish hook. Fires when a publish event lands
- * on the local event bus from the receiver daemon
- * ([[openspec/changes/build-bus-poll-cd/proposal.md]] Phase 4). Each module can declare multiple
- * entries, each with its own match rule + action script.
+ * on the local event bus from the receiver daemon. Each module can declare
+ * multiple entries, each with its own match rule, so one manifest can react
+ * to two different packages with two different scripts (celilo-mgmt did
+ * exactly that) without the hook itself having to filter.
  *
- * The action script runs with `CELILO_EVENT_PAYLOAD` in its env (the
- * full PublishEvent as JSON), plus `CELILO_EVENT_PACKAGE_NAME` /
- * `CELILO_EVENT_PACKAGE_VERSION` for the common fields. Exit status
- * non-zero is logged but doesn't propagate to the publisher.
+ * As of module-orchestrator-primitives slice 7 the script is an ordinary
+ * TypeScript `defineHook` module dispatched through the executor, jailed,
+ * with the verified PublishEvent as the `event` input in the hook's typed
+ * context. It used to be a bash path spawned detached on a second execution
+ * path with celilo's whole `process.env` (design D6). That path is gone; the
+ * match rules survive as receiver-side trigger filtering.
  */
 export const UpstreamPublishHookSchema = z.object({
   /** Optional display label for logs / `celilo subscribers status`. */
@@ -328,9 +350,13 @@ export const UpstreamPublishHookSchema = z.object({
       package_pattern: z.string().optional(),
     })
     .default({}),
-  /** Path to the action script, relative to the module directory. */
+  /**
+   * Path to the hook script, relative to the module directory. A TypeScript
+   * `defineHook` module; the hook receives the verified PublishEvent as its
+   * `event` input. A shell script is not a hook language.
+   */
   script: z.string().min(1),
-  /** Seconds before the script is killed. Default: 600. */
+  /** Milliseconds before the hook is killed. Default: 600000. */
   timeout: z.number().positive().optional(),
 });
 
@@ -368,19 +394,23 @@ const LIFECYCLE_HOOK_SCHEMAS = {
   list_peers: LifecycleHookSchema.optional(),
   reconcile_peers: LifecycleHookSchema.optional(),
   sweep_revisions: LifecycleHookSchema.optional(),
+  /**
+   * The one HookName whose schema entry is an ARRAY (see
+   * UpstreamPublishHookSchema): multiple match-rule entries per manifest,
+   * dispatched per event by the build-bus receiver daemon through the
+   * ordinary executor. Deliberately not a LifecycleHookSchema.
+   */
+  on_upstream_publish: z.array(UpstreamPublishHookSchema).optional(),
 } satisfies Record<HookName, z.ZodTypeAny>;
 
 /**
- * What `manifest.hooks` accepts: every lifecycle hook, plus
- * `on_upstream_publish`, which is deliberately not a `HookName` — an ARRAY of
- * build-bus match rules dispatched by the receiver daemon rather than a hook
- * `runNamedHook` can invoke. It is spread in here rather than living in
- * `LIFECYCLE_HOOK_SCHEMAS` so the `satisfies` above stays exact.
- * See [[openspec/changes/build-bus-poll-cd/proposal.md]] Phase 4.
+ * What `manifest.hooks` accepts: every lifecycle hook, each derived from the
+ * one list (celilo#821). `on_upstream_publish` lives in
+ * `LIFECYCLE_HOOK_SCHEMAS` with the rest now that it is a HookName; its array
+ * entry is commented there.
  */
 const HOOK_SCHEMAS = {
   ...LIFECYCLE_HOOK_SCHEMAS,
-  on_upstream_publish: z.array(UpstreamPublishHookSchema).optional(),
 };
 
 /**
@@ -794,6 +824,25 @@ export const ModuleManifestSchema = z
       .strict()
       .optional(),
 
+    /**
+     * A recorded, first-class decision that this module needs no health
+     * check (openspec/changes/health-waiver-mechanism, D1-D4).
+     *
+     * A waiver is NOT `skip`. `skip` says a check could not run this
+     * time. A waiver says a human decided this module needs no check,
+     * and records WHO and WHY. It annotates the module's `unmeasured`
+     * audit finding; the severity stays `unmeasured` and the fleet
+     * verdict stays UNKNOWN. It never re-greens the board.
+     *
+     * It lives here rather than in operator state because it must
+     * survive reinstall, reprovision and registry publish, and because
+     * `git diff` should show the decision changing. There is no expiry
+     * by design: a lapsed waiver would silently re-green, which is the
+     * failure being guarded. Revisiting the decision is a new manifest
+     * edit, not a timer.
+     */
+    health_waiver: HealthWaiverSchema.optional(),
+
     build: z
       .object({
         /** Inline shell command to build the module (run via bash -c). Mutually exclusive with script. */
@@ -1003,6 +1052,7 @@ export type VariableType = z.infer<typeof VariableTypeSchema>;
 export type AnsibleCollection = z.infer<typeof AnsibleCollectionSchema>;
 export type SystemResource = z.infer<typeof SystemResourceSchema>;
 export type SystemDeclaration = z.infer<typeof SystemDeclarationSchema>;
+export type HealthWaiver = z.infer<typeof HealthWaiverSchema>;
 export type BaseModuleAspect = NonNullable<ModuleManifest['base_module_aspect']>;
 export type BaseModuleAspectTrigger = BaseModuleAspect['triggers'][number];
 

package/src/manifest/validate.test.ts

@@ -1673,3 +1673,50 @@ requires:
     });
   });
 });
+
+describe('health_waiver (openspec/changes/health-waiver-mechanism)', () => {
+  const base = `\n${CONTRACT_LINE}\nid: namecheap\nname: Namecheap\nversion: 1.0.0\n`;
+
+  test('accepts a well-formed waiver and keeps all three fields', () => {
+    const result = validateManifest(
+      `${base}\nhealth_waiver:\n  reason: "API-only: a real check is hard and may not be worth forcing"\n  by: peba\n  at: "2026-09-09"\n`,
+    );
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.health_waiver).toEqual({
+        reason: 'API-only: a real check is hard and may not be worth forcing',
+        by: 'peba',
+        at: '2026-09-09',
+      });
+    }
+  });
+
+  test('rejects an unknown field inside the waiver (strict)', () => {
+    const result = validateManifest(
+      `${base}\nhealth_waiver:\n  reason: r\n  by: peba\n  at: "2026-09-09"\n  expires: "2027-01-01"\n`,
+    );
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.errors.some((e) => e.message.toLowerCase().includes('unrecognized'))).toBe(
+        true,
+      );
+    }
+  });
+
+  test('rejects a waiver with no reason', () => {
+    const result = validateManifest(`${base}\nhealth_waiver:\n  by: peba\n  at: "2026-09-09"\n`);
+    expect(result.success).toBe(false);
+  });
+
+  test('rejects a waiver with no by', () => {
+    const result = validateManifest(`${base}\nhealth_waiver:\n  reason: r\n  at: "2026-09-09"\n`);
+    expect(result.success).toBe(false);
+  });
+
+  test('rejects a waiver whose at is not a date', () => {
+    const result = validateManifest(
+      `${base}\nhealth_waiver:\n  reason: r\n  by: peba\n  at: not-a-date\n`,
+    );
+    expect(result.success).toBe(false);
+  });
+});

package/src/policy/capability-shape-baseline.ts

@@ -28,77 +28,125 @@
 export interface CapabilityShape {
   /** The contract version this hash was recorded at. */
   readonly version: string;
-  /** sha256 of the printed interface plus the capability's table declaration. */
+  /** sha256 of the printed interface, the table declaration, and the request types. */
   readonly hash: string;
+  /**
+   * Canonical request/result type member text, so the regenerate script can
+   * classify a request-contract change as breaking (removed member, optional
+   * → required, type change → MAJOR) or additive (optional addition → minor)
+   * before it writes. Without this, a regenerate could absorb a request break
+   * into a patch, which is exactly how celilo#1361 shipped.
+   */
+  readonly requests: string;
 }
 
 export const CAPABILITY_SHAPE_BASELINE: Readonly<Record<string, CapabilityShape>> = {
   public_web: {
-    version: '3.2.0',
-    hash: 'a353bf184552f1ed82e5d97c9b4609dc243718c20051a9446d8dc7174561db50',
+    version: '4.0.0',
+    hash: 'fa79b68744eea9506db431b9eb51bb0472736864ddeea7524af9945f4bf4f1b0',
+    requests:
+      '[{kind:"alias",members:[{name:"_self",optional:false,type:"Record<string, string | number | boolean>"}],name:"ClientConfig"},{kind:"interface",members:[{name:"defaultHostname",optional:false,type:"string"},{name:"getServerIp",optional:false,type:"Promise<string>"},{name:"publishStaticSite",optional:false,type:"Promise<PublishStaticSiteResult>"},{name:"register_route",optional:false,type:"Promise<RegisterRouteResult>"},{name:"registerReverseProxy",optional:false,type:"Promise<RegisterReverseProxyResult>"},{name:"upload_static_assets",optional:false,type:"Promise<UploadStaticAssetsResult>"}],name:"PublicWebCapability"},{kind:"interface",members:[{name:"clientConfig",optional:true,type:"ClientConfig"},{name:"hostname",optional:true,type:"string"},{name:"path",optional:false,type:"string"},{name:"spaFallback",optional:true,type:"boolean"}],name:"PublishStaticSiteRequest"},{kind:"interface",members:[{name:"contentHash",optional:false,type:"string"},{name:"filesUploaded",optional:false,type:"number"},{name:"path",optional:false,type:"string"},{name:"success",optional:false,type:"boolean"}],name:"PublishStaticSiteResult"},{kind:"interface",members:[{name:"hostname",optional:true,type:"string"},{name:"path",optional:false,type:"string"},{name:"targetHost",optional:false,type:"string"},{name:"targetPort",optional:false,type:"number"},{name:"websocket",optional:true,type:"boolean"}],name:"RegisterReverseProxyRequest"},{kind:"interface",members:[{name:"path",optional:false,type:"string"},{name:"success",optional:false,type:"boolean"}],name:"RegisterReverseProxyResult"},{kind:"interface",members:[{name:"hostname",optional:true,type:"string"},{name:"path",optional:false,type:"string"},{name:"targetHost",optional:true,type:"string"},{name:"targetPort",optional:true,type:"number"},{name:"type",optional:false,type:"\'static\' | \'reverse_proxy\'"},{name:"websocket",optional:true,type:"boolean"}],name:"RegisterRouteRequest"},{kind:"interface",members:[{name:"caddyPath",optional:true,type:"string"},{name:"success",optional:false,type:"boolean"}],name:"RegisterRouteResult"},{kind:"interface",members:[{name:"path",optional:false,type:"string"}],name:"UploadStaticAssetsRequest"},{kind:"interface",members:[{name:"contentHash",optional:false,type:"string"},{name:"filesUploaded",optional:false,type:"number"},{name:"success",optional:false,type:"boolean"}],name:"UploadStaticAssetsResult"}]',
   },
   idp: {
     version: '1.2.0',
-    hash: '99eee190ed670f53595554335f23e1745b872e3226dc9ffdb1d0bf6397d6013a',
+    hash: 'dcb5758d18f18abb8f705c37b894dcdc49c93c34b939d74c4cb32b2818b009c9',
+    requests:
+      '[{kind:"interface",members:[{name:"client_name",optional:false,type:"string"},{name:"client_type",optional:true,type:"\'public\' | \'confidential\'"},{name:"groups",optional:true,type:"string[]"},{name:"redirect_uris",optional:false,type:"string[]"},{name:"scopes",optional:true,type:"string[]"}],name:"CreateOidcClientRequest"},{kind:"interface",members:[{name:"application_slug",optional:false,type:"string"},{name:"client_id",optional:false,type:"string"},{name:"client_secret",optional:false,type:"string"},{name:"provider_id",optional:false,type:"number"}],name:"CreateOidcClientResult"},{kind:"interface",members:[{name:"description",optional:true,type:"string"},{name:"identifier",optional:false,type:"string"},{name:"username",optional:false,type:"string"}],name:"CreateTokenRequest"},{kind:"interface",members:[{name:"created",optional:false,type:"boolean"},{name:"token",optional:false,type:"string"}],name:"CreateTokenResult"},{kind:"interface",members:[{name:"email",optional:false,type:"string"},{name:"groups",optional:true,type:"string[]"},{name:"password",optional:false,type:"string"},{name:"username",optional:false,type:"string"}],name:"CreateUserRequest"},{kind:"interface",members:[{name:"created",optional:false,type:"boolean"},{name:"user_id",optional:false,type:"number"}],name:"CreateUserResult"},{kind:"interface",members:[{name:"create_oidc_client",optional:false,type:"Promise<CreateOidcClientResult>"},{name:"create_token",optional:false,type:"Promise<CreateTokenResult>"},{name:"create_user",optional:false,type:"Promise<CreateUserResult>"},{name:"list_tokens",optional:false,type:"Promise<TokenInfo[]>"},{name:"revoke_oidc_client",optional:false,type:"Promise<void>"},{name:"revoke_token",optional:false,type:"Promise<RevokeTokenResult>"}],name:"IdpCapability"},{kind:"interface",members:[{name:"username",optional:false,type:"string"}],name:"ListTokensRequest"},{kind:"interface",members:[{name:"client_id",optional:false,type:"string"}],name:"RevokeOidcClientRequest"},{kind:"interface",members:[{name:"identifier",optional:false,type:"string"}],name:"RevokeTokenRequest"},{kind:"interface",members:[{name:"revoked",optional:false,type:"boolean"}],name:"RevokeTokenResult"},{kind:"interface",members:[{name:"description",optional:false,type:"string"},{name:"expires",optional:false,type:"string | null"},{name:"expiring",optional:false,type:"boolean"},{name:"identifier",optional:false,type:"string"}],name:"TokenInfo"}]',
   },
   dns_registrar: {
     version: '4.0.0',
-    hash: 'f5d02196a3394ec71d865beb45825160103800baf632293a769a6e72dc76236a',
+    hash: '5108a4dc2df0b4c78862c922df596156a58f04c64d81a65947724720e732b50c',
+    requests:
+      '[{kind:"interface",members:[{name:"registerHost",optional:false,type:"Promise<HookResult>"}],name:"DnsRegistrarCapability"},{kind:"interface",members:[{name:"artifactPaths",optional:true,type:"string[]"},{name:"duration",optional:false,type:"number"},{name:"error",optional:true,type:"string"},{name:"outputs",optional:false,type:"Record<string, unknown>"},{name:"success",optional:false,type:"boolean"}],name:"HookResult"},{kind:"interface",members:[{name:"fqdn",optional:false,type:"string"}],name:"RegisterHostRequest"}]',
   },
   firewall: {
     version: '1.1.0',
-    hash: '564a83ebf8ca937faf955afc4f7bf4278fe9ed01694f0237bfbc38e2eff38408',
+    hash: 'f8c1c43b7d53193ae5b1e7cb7420a91efdb5e02f5bcd9add094aad66c0ec4104',
+    requests:
+      '[{kind:"interface",members:[{name:"description",optional:false,type:"string"},{name:"externalPort",optional:false,type:"number"},{name:"internalIp",optional:false,type:"string"},{name:"internalPort",optional:false,type:"number"},{name:"protocol",optional:false,type:"string"}],name:"ExposedService"},{kind:"interface",members:[{name:"description",optional:false,type:"string"},{name:"ingressIp",optional:true,type:"string"},{name:"internalIp",optional:false,type:"string"},{name:"ports",optional:false,type:"PortOrRange[]"},{name:"protocol",optional:true,type:"Protocol"}],name:"ExposeServiceRequest"},{kind:"interface",members:[{name:"externalIp",optional:false,type:"string"},{name:"natIp",optional:false,type:"string"}],name:"ExposeServiceResult"},{kind:"interface",members:[{name:"exposeService",optional:false,type:"Promise<ExposeServiceResult>"},{name:"listExposedServices",optional:false,type:"Promise<ExposedService[]>"},{name:"listTrustedSources",optional:true,type:"Promise<TrustedSource[]>"},{name:"providerModuleId",optional:true,type:"string"},{name:"registerTrustedSource",optional:true,type:"Promise<void>"}],name:"FirewallCapability"},{kind:"alias",members:[{name:"_self",optional:false,type:"number | {\\n    start: number;\\n    end: number;\\n}"}],name:"PortOrRange"},{kind:"alias",members:[{name:"_self",optional:false,type:"\'TCP\' | \'UDP\'"}],name:"Protocol"},{kind:"interface",members:[{name:"description",optional:false,type:"string"},{name:"subnets",optional:false,type:"string[]"}],name:"RegisterTrustedSourceRequest"},{kind:"interface",members:[{name:"description",optional:false,type:"string"},{name:"registeredBy",optional:false,type:"string"},{name:"subnet",optional:false,type:"string"}],name:"TrustedSource"}]',
   },
   source_forge: {
     version: '1.0.0',
-    hash: '3bc797cf8c2990c61723fb680299f6a1d4b99ac42fd0371dd9dc64d05c588991',
+    hash: 'cb005fe21e69f0984b03b862b2739ef07f868d363fd3a925feadf8e865620916',
+    requests:
+      '[{kind:"interface",members:[{name:"owner",optional:true,type:"string"},{name:"repo",optional:true,type:"string"},{name:"runnerName",optional:false,type:"string"},{name:"scope",optional:true,type:"SourceForgeScope"}],name:"IssueRunnerTokenRequest"},{kind:"interface",members:[{name:"token",optional:false,type:"string"}],name:"IssueRunnerTokenResult"},{kind:"interface",members:[{name:"defaultBranch",optional:true,type:"string"},{name:"publishToken",optional:false,type:"string"},{name:"repo",optional:false,type:"string"},{name:"requiredChecks",optional:true,type:"string[]"}],name:"RegisterRepoRequest"},{kind:"interface",members:[{name:"protectedBranch",optional:false,type:"string"},{name:"repo",optional:false,type:"string"}],name:"RegisterRepoResult"},{kind:"interface",members:[{name:"issue_runner_token",optional:false,type:"Promise<IssueRunnerTokenResult>"},{name:"registerRepo",optional:false,type:"Promise<RegisterRepoResult>"}],name:"SourceForgeCapability"},{kind:"alias",members:[{name:"_self",optional:false,type:"\'instance\' | \'org\' | \'user\' | \'repo\'"}],name:"SourceForgeScope"}]',
   },
   registry_publish: {
     version: '1.0.0',
-    hash: '693e7d08e9f105acd90dd00f8f9282ab3508def16e48237b47bc0ccba7885679',
+    hash: 'fd8a9fd097ab03fc6e4989099a8bf8ad011d2f0e641ecb9d7c8152504de3ce7a',
+    requests:
+      '[{kind:"interface",members:[{name:"repo",optional:false,type:"string"},{name:"scope",optional:false,type:"string"}],name:"MintScopedTokenRequest"},{kind:"interface",members:[{name:"token",optional:false,type:"string"}],name:"MintScopedTokenResult"},{kind:"interface",members:[{name:"mintScopedToken",optional:false,type:"Promise<MintScopedTokenResult>"},{name:"revokeRepo",optional:false,type:"Promise<void>"}],name:"RegistryPublishCapability"},{kind:"interface",members:[{name:"repo",optional:false,type:"string"}],name:"RevokeRepoRequest"}]',
   },
   dhcp_server: {
     version: '1.0.0',
-    hash: '291a247d98bc11b18ab34d40b520bec679b95a031cbd674d513b313559fa3288',
+    hash: 'fc5751082942224c9343cb0a1455669b7a32d5442a8ae912efe88bd82b7648ae',
+    requests:
+      '[{kind:"interface",members:[{name:"getDnsServers",optional:false,type:"Promise<string[]>"},{name:"getDomainName",optional:false,type:"Promise<string>"},{name:"setDnsServers",optional:false,type:"Promise<void>"},{name:"setDomainName",optional:false,type:"Promise<void>"}],name:"DhcpServerCapability"}]',
   },
   dns_internal: {
     version: '1.1.0',
-    hash: 'af72e861a23f6c81fe9a1a679121b7d3ea87ac5e8167efa20d5d6323010e5fef',
+    hash: 'd15a5ead445269d29ca46460268c1746892ef7d613688ac809b8a3d3395c675c',
+    requests:
+      '[{kind:"interface",members:[{name:"deleteRecord",optional:false,type:"Promise<void>"},{name:"reconcileViews",optional:true,type:"Promise<void>"},{name:"registerRecord",optional:false,type:"Promise<void>"},{name:"registerTransferPeer",optional:true,type:"Promise<void>"}],name:"DnsInternalCapability"},{kind:"interface",members:[{name:"host",optional:false,type:"string"},{name:"type",optional:false,type:"string"},{name:"value",optional:false,type:"string"},{name:"zone",optional:true,type:"string"},{name:"zoneRoutableValue",optional:true,type:"string"}],name:"DnsRecordRequest"},{kind:"interface",members:[{name:"moduleId",optional:false,type:"string"},{name:"serverIp",optional:false,type:"string"}],name:"TransferPeer"},{kind:"interface",members:[{name:"host",optional:false,type:"string"},{name:"ip",optional:false,type:"string"}],name:"ViewOverride"}]',
   },
   external_web: {
-    version: '1.0.0',
-    hash: '7396028ace76938f4e892e6ef8a53450183cdbcf8dff3ce767724bd9b2276dae',
+    version: '2.0.0',
+    hash: 'a906dc2a6645eb5da2dfa05d832a42e20f5defa8c1af300a67d6c8ef853b8ea4',
+    requests:
+      '[{kind:"interface",members:[{name:"publishStaticSite",optional:false,type:"Promise<PublishExternalSiteResult>"}],name:"ExternalWebCapability"},{kind:"interface",members:[{name:"hostname",optional:true,type:"string"},{name:"path",optional:false,type:"string"},{name:"spaFallback",optional:true,type:"boolean"}],name:"PublishExternalSiteRequest"},{kind:"interface",members:[{name:"filesUploaded",optional:false,type:"number"},{name:"path",optional:false,type:"string"},{name:"success",optional:false,type:"boolean"}],name:"PublishExternalSiteResult"}]',
   },
   notification: {
     version: '1.0.0',
-    hash: '40629722b397a314d65a448a618d600fc8560c4aae0767dd7324d497d4cc9d41',
+    hash: '9d98b38d007b6d190fff6d243b38e871aeb707da2e48e3c111c3cfcc70ab75da',
+    requests:
+      '[{kind:"interface",members:[{name:"body",optional:false,type:"string"},{name:"messageId",optional:false,type:"string"},{name:"receivedAt",optional:false,type:"number"},{name:"senderAddress",optional:false,type:"string"}],name:"InboundMessage"},{kind:"interface",members:[{name:"receive",optional:true,type:"Promise<ReceiveResult>"},{name:"send",optional:false,type:"Promise<SendNotificationResult>"}],name:"NotificationCapability"},{kind:"interface",members:[{name:"cursor",optional:false,type:"string | null"},{name:"messages",optional:false,type:"InboundMessage[]"}],name:"ReceiveResult"},{kind:"interface",members:[{name:"address",optional:false,type:"string"},{name:"body",optional:false,type:"string"},{name:"token",optional:true,type:"string"}],name:"SendNotificationRequest"},{kind:"interface",members:[{name:"messageId",optional:false,type:"string"}],name:"SendNotificationResult"}]',
   },
   control_plane_vpn: {
     version: '1.0.0',
-    hash: '2f7f81d0b3ecb2ab6822dbc9bf837a933b25e0e157eb94d0b9b8e801417f8f14',
+    hash: '742a739054bb351cda8586c5079ccb5877c22227afc57643c59152a746234e7b',
+    requests:
+      '[{kind:"interface",members:[{name:"getEndpoint",optional:false,type:"Promise<ControlPlaneVpnEndpoint>"},{name:"listClients",optional:false,type:"Promise<RegisteredClient[]>"},{name:"registerClient",optional:false,type:"Promise<RegisterClientResult>"},{name:"revokeClient",optional:false,type:"Promise<RevokeClientResult>"}],name:"ControlPlaneVpnCapability"},{kind:"interface",members:[{name:"clientPool",optional:false,type:"string"},{name:"endpoint",optional:false,type:"string"},{name:"serverPublicKey",optional:false,type:"string"}],name:"ControlPlaneVpnEndpoint"},{kind:"interface",members:[{name:"address",optional:false,type:"string"},{name:"label",optional:false,type:"string"},{name:"publicKey",optional:false,type:"string"}],name:"RegisterClientRequest"},{kind:"interface",members:[{name:"created",optional:false,type:"boolean"}],name:"RegisterClientResult"},{kind:"interface",members:[{name:"address",optional:false,type:"string"},{name:"label",optional:false,type:"string"},{name:"publicKey",optional:false,type:"string"},{name:"registeredAt",optional:false,type:"string"}],name:"RegisteredClient"},{kind:"interface",members:[{name:"publicKey",optional:false,type:"string"}],name:"RevokeClientRequest"},{kind:"interface",members:[{name:"revoked",optional:false,type:"boolean"}],name:"RevokeClientResult"}]',
   },
   control_plane_api: {
     version: '1.0.0',
-    hash: '2c5d41d37a9a828a8b9a6dc633a2d48f24670d0831d879ec18426f0f9f8e5be5',
+    hash: '189860acaa746326bdb6e9cd3a5c6af6bbb2f94ce37d84cc7faab01c69f7fb30',
+    requests:
+      '[{kind:"interface",members:[{name:"enrol_principal",optional:false,type:"Promise<EnrolPrincipalResult>"},{name:"revoke_principal",optional:false,type:"Promise<RevokePrincipalResult>"}],name:"ControlPlaneApiCapability"},{kind:"interface",members:[{name:"name",optional:false,type:"string"},{name:"publicKey",optional:false,type:"string"}],name:"EnrolPrincipalRequest"},{kind:"interface",members:[{name:"created",optional:false,type:"boolean"},{name:"grants",optional:false,type:"string[]"},{name:"name",optional:false,type:"string"}],name:"EnrolPrincipalResult"},{kind:"interface",members:[{name:"name",optional:false,type:"string"}],name:"RevokePrincipalRequest"},{kind:"interface",members:[{name:"revoked",optional:false,type:"boolean"}],name:"RevokePrincipalResult"}]',
   },
   private_web: {
-    version: '1.0.0',
-    hash: '0eddb82f821fe3c7fbd503d55a24c3d5a22369af8b22de06570a371d5f485c03',
+    version: '2.0.0',
+    hash: 'fb301f5e55ca14fdb0ede0d428d2ac72eabed77e277de8c795eaa0b955695483',
+    requests:
+      '[{kind:"alias",members:[{name:"_self",optional:false,type:"Record<string, string | number | boolean>"}],name:"ClientConfig"},{kind:"interface",members:[{name:"defaultHostname",optional:false,type:"string"},{name:"getCaCertificate",optional:false,type:"Promise<string>"},{name:"publishStaticSite",optional:false,type:"Promise<PublishStaticSiteResult>"},{name:"registerReverseProxy",optional:false,type:"Promise<RegisterReverseProxyResult>"}],name:"PrivateWebCapability"},{kind:"interface",members:[{name:"clientConfig",optional:true,type:"ClientConfig"},{name:"hostname",optional:true,type:"string"},{name:"path",optional:false,type:"string"},{name:"spaFallback",optional:true,type:"boolean"}],name:"PublishStaticSiteRequest"},{kind:"interface",members:[{name:"contentHash",optional:false,type:"string"},{name:"filesUploaded",optional:false,type:"number"},{name:"path",optional:false,type:"string"},{name:"success",optional:false,type:"boolean"}],name:"PublishStaticSiteResult"},{kind:"interface",members:[{name:"hostname",optional:true,type:"string"},{name:"path",optional:false,type:"string"},{name:"targetHost",optional:false,type:"string"},{name:"targetPort",optional:false,type:"number"},{name:"websocket",optional:true,type:"boolean"}],name:"RegisterReverseProxyRequest"},{kind:"interface",members:[{name:"path",optional:false,type:"string"},{name:"success",optional:false,type:"boolean"}],name:"RegisterReverseProxyResult"}]',
   },
   cross_module_read: {
     version: '1.0.0',
-    hash: 'e152f0738c88a7105b6057037f350ce0bbcbfc5c4ccbccc3af60f1cf3f1904af',
+    hash: 'a8af728f3f3ec7bff57934fe6b4313eb58a32afa606f6a8d2b9923a9e492dd58',
+    requests:
+      '[{kind:"interface",members:[{name:"granted",optional:false,type:"true"}],name:"CrossModuleReadCapability"}]',
   },
   celilo_module_deploy_worker: {
     version: '1.0.0',
-    hash: '0b0e1f26aab0ebcf5d28283b9c5ba711f6d182f8f7ad474379c4ab02c354a2b8',
+    hash: '51fe35fc321520b37532478490a956c34b97ed3592ee59b3a0f8aed4b8b96672',
+    requests:
+      '[{kind:"alias",members:[{name:"_self",optional:false,type:"{\\n    accepted: true;\\n    moduleId: string | null;\\n} | {\\n    accepted: false;\\n    reason: string;\\n}"}],name:"DestroyInstanceOutcome"},{kind:"interface",members:[{name:"instanceKey",optional:false,type:"string"},{name:"submodule",optional:false,type:"string"}],name:"DestroyInstanceRequest"},{kind:"alias",members:[{name:"_self",optional:false,type:"{\\n    accepted: true;\\n    moduleId: string;\\n} | {\\n    accepted: false;\\n    reason: string;\\n}"}],name:"InstanceRequestOutcome"},{kind:"alias",members:[{name:"_self",optional:false,type:"(typeof INSTANCE_STATES)[number]"}],name:"InstanceState"},{kind:"interface",members:[{name:"answers",optional:true,type:"Record<string, unknown>"},{name:"config",optional:true,type:"Record<string, unknown>"},{name:"instanceKey",optional:false,type:"string"},{name:"label",optional:true,type:"string"},{name:"submodule",optional:false,type:"string"}],name:"InstantiateRequest"},{kind:"interface",members:[{name:"states",optional:true,type:"readonly InstanceState[]"},{name:"submodule",optional:true,type:"string"}],name:"ListInstancesRequest"},{kind:"interface",members:[{name:"destroy",optional:false,type:"Promise<DestroyInstanceOutcome>"},{name:"instantiate",optional:false,type:"Promise<InstanceRequestOutcome>"},{name:"list",optional:false,type:"Promise<ModuleInstance[]>"}],name:"ModuleDeployWorkerCapability"},{kind:"interface",members:[{name:"failureReason",optional:false,type:"string | null"},{name:"instanceKey",optional:false,type:"string"},{name:"label",optional:false,type:"string | null"},{name:"moduleId",optional:false,type:"string"},{name:"retryable",optional:false,type:"boolean | null"},{name:"state",optional:false,type:"InstanceState"},{name:"submodule",optional:false,type:"string"}],name:"ModuleInstance"}]',
   },
   web_routes: {
     version: '1.0.0',
-    hash: 'bbf6435528a799e205270681e0ffc34f4007efbf04240138d4b69594a2515dbb',
+    hash: '5ae5e43d2948a37dfc23a5aef490f4ef459c8b4ef09719c42961eea73b8da5ff',
+    requests:
+      '[{kind:"interface",members:[{name:"getAllRoutes",optional:false,type:"Promise<WebRoute[]>"},{name:"getRoutes",optional:false,type:"Promise<WebRoute[]>"}],name:"RouteReadView"},{kind:"interface",members:[{name:"contentHash",optional:false,type:"string | null"},{name:"createdAt",optional:false,type:"Date"},{name:"hostname",optional:false,type:"string"},{name:"id",optional:false,type:"number"},{name:"moduleId",optional:false,type:"string"},{name:"path",optional:false,type:"string"},{name:"slug",optional:false,type:"string"},{name:"targetHost",optional:false,type:"string | null"},{name:"targetPort",optional:false,type:"number | null"},{name:"type",optional:false,type:"\'static\' | \'reverse_proxy\'"},{name:"updatedAt",optional:false,type:"Date"},{name:"websocket",optional:false,type:"boolean"}],name:"WebRoute"}]',
   },
   firewall_registry: {
     version: '2.0.0',
-    hash: 'db266155107b9eba88dbff576f979069e012e10a6dfb80de4544f809d1157bfb',
+    hash: 'd7a587e961500f1bc464c4a3427dd2ec85c7f80c1ed11a9c64beeb0decea524c',
+    requests:
+      '[{kind:"interface",members:[{name:"converge",optional:false,type:"Promise<void>"},{name:"withdrawConsumer",optional:false,type:"Promise<void>"}],name:"FirewallProviderView"}]',
+  },
+  provider_converge: {
+    version: '1.0.0',
+    hash: '1d828d70433ce4a15a73072883abad0c2acfef92c059bf40432b792722eb7d97',
+    requests:
+      '[{kind:"alias",members:[{name:"_self",optional:false,type:"{\\n    sourceDir: string;\\n    overlayDir?: string;\\n} | {\\n    unavailable: string;\\n}"}],name:"ConsumerSiteResolution"},{kind:"interface",members:[{name:"content",optional:false,type:"string"},{name:"path",optional:false,type:"string"}],name:"ProviderConfigFile"},{kind:"interface",members:[{name:"converge",optional:false,type:"Promise<{\\n    success: boolean;\\n    error?: string;\\n    unresolved: string[];\\n}>"},{name:"resolveConsumerSite",optional:false,type:"Promise<ConsumerSiteResolution>"}],name:"ProviderConvergeView"},{kind:"interface",members:[{name:"contentHash",optional:false,type:"string"},{name:"hostnames",optional:false,type:"string[]"},{name:"moduleId",optional:false,type:"string"},{name:"overlayDir",optional:true,type:"string"},{name:"slug",optional:false,type:"string"},{name:"sourceDir",optional:false,type:"string"}],name:"ProviderSiteRequest"}]',
   },
 };

package/src/policy/capability-shape-drift.test.ts

@@ -27,7 +27,15 @@ import { CAPABILITY_CONTRACT_VERSIONS } from '@celilo/capabilities';
 import { is } from 'drizzle-orm';
 import { SQLiteTable, getTableConfig } from 'drizzle-orm/sqlite-core';
 import * as dbSchema from '../db/schema';
-import { capabilitySubjects, shapeHash, tablesOf } from './capability-shape';
+import {
+  type RequestTypeShape,
+  capabilitySubjects,
+  classifyRequestChange,
+  requestTypes,
+  requestsKey,
+  shapeHash,
+  tablesOf,
+} from './capability-shape';
 import { CAPABILITY_SHAPE_BASELINE } from './capability-shape-baseline';
 
 /** Physical table name → the drizzle table the running code declares. */
@@ -160,3 +168,47 @@ describe('Scan B — a shape change carries a version bump', () => {
     expect(drifted).toEqual([]);
   });
 });
+
+describe('Scan C — a request-contract change carries a MAJOR bump', () => {
+  const majorOf = (version: string): number =>
+    Number.parseInt(version.replace(/^v/, '').split('-')[0].split('.')[0], 10) || 0;
+
+  /**
+   * The regenerate script refuses to absorb a breaking request diff (removed
+   * member, optional → required, type change) without a major bump. This test
+   * is the same predicate against the COMMITTED baseline, so hand-editing the
+   * fixture does not route around the script — and it is what makes the rule
+   * a gate rather than a convention (celilo#1361, where `sourceDir` left three
+   * request types with no version move at all).
+   */
+  test('a request-shape change against the baseline means the major moved', () => {
+    const versions = CAPABILITY_CONTRACT_VERSIONS as Record<string, string>;
+    const violations: string[] = [];
+    for (const capability of capabilitySubjects().keys()) {
+      const recorded = CAPABILITY_SHAPE_BASELINE[capability];
+      if (!recorded) continue;
+      if (recorded.requests === undefined) {
+        violations.push(
+          `${capability}: baseline has no requests field. Re-run bun run apps/celilo/scripts/regenerate-capability-shape-baseline.ts`,
+        );
+        continue;
+      }
+      const current = requestsKey(capability);
+      if (current === recorded.requests) continue;
+      const change = classifyRequestChange(
+        JSON.parse(recorded.requests) as RequestTypeShape[],
+        requestTypes(capability),
+      );
+      if (
+        change.kind === 'breaking' &&
+        majorOf(recorded.version) >= majorOf(versions[capability])
+      ) {
+        violations.push(
+          `${capability}: request contract changed without a MAJOR bump (${change.reasons.join('; ')}). ` +
+            `Bump CAPABILITY_CONTRACT_VERSIONS.${capability} and regenerate the baseline.`,
+        );
+      }
+    }
+    expect(violations).toEqual([]);
+  });
+});