fix(plugin-webhooks): round 2 — the boot report and docs only; the activation door's refusal and the reader verdict go

The activation door's 200 -> 503 narrowing is the maintainer's to rule, so
packages/runtime is back to main's bytes, and the declared-webhook reader's
dispatch verdict (its only consumer was that door) is removed.

Claude-Session: https://claude.ai/code/session_011TdZ8GjixNZFLz1xJD9zzK
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

.changeset/24910-declared-webhook-undeliverable.md

@@ -1,22 +1,20 @@
 ---
 '@objectstack/plugin-webhooks': patch
-'@objectstack/runtime': patch
 ---
 
-fix(plugin-webhooks,runtime): a declared webhook that the deployment can never deliver is reported at `error` once at boot, and the activation door refuses to switch it on
+fix(plugin-webhooks): a declared webhook that the deployment can never deliver is reported once at boot, at `error`, with the consequence and the fix
 
 Clause-②: no
 
 The webhook auto-enqueuer reads record events only from the realtime service. A stack with `requires: ['webhooks']` and no `'realtime'` therefore never delivers a declared webhook.
 
 - **Before.**
   - The boot logged one `WARN [webhook-auto-enqueuer] disabled — ObjectQL, Realtime, or Messaging service not available`. The line named no webhook, gave no consequence and gave no fix.
-  - `POST /api/v1/security/_activation/webhook/NAME` with `{ "enabled": true }` answered `200 { enabled: true }` and wrote the activation row.
-  - Every record write still answered 200, and no delivery row was ever written.
-- **After** (`@objectstack/plugin-webhooks`). When the stack declares at least one webhook, the boot logs one `error` line instead of the warning. The line names each declared webhook and says that none of them will be delivered while record writes keep succeeding. It names the missing service and the fix, for example "add 'realtime' to `requires`". A stack that declares no webhook gets the same `warn` as before.
-- **After** (`@objectstack/runtime`). On such a deployment, switching a declared webhook ON through the activation door answers `503` with `error.code: 'SERVICE_UNAVAILABLE'` and writes nothing. The message gives the same reason and fix as the boot line. Switching one OFF still answers `200` and writes the row. A name nothing declares is still `404`. The authority checks still answer first.
+  - Every record write still answered 200, the declaration still read active, and no delivery row was ever written.
+- **After.** When the stack declares at least one webhook, the boot logs one `error` line instead of the warning. The line names each declared webhook and says none of them will be delivered while record writes keep succeeding. It names the missing service and the fix, for example "add 'realtime' to `requires`". A stack that declares no webhook gets the same `warn` as before.
 - **Unchanged.**
-  - Every deployment whose auto-enqueuer runs: switching on and off and delivery behave as before.
-  - A host that constructs `WebhookOutboxPlugin` with `autoEnqueue: false` gets no new log line and no new refusal. It has turned the enqueuer off itself, and redelivery still reads the switch.
-  - `os validate` and `os build` are unchanged. They still accept a stack that declares webhooks without these tokens.
+  - Every deployment whose auto-enqueuer runs.
+  - A host that constructs `WebhookOutboxPlugin` with `autoEnqueue: false` gets no new log line. It turned the enqueuer off itself.
+  - `os validate` and `os build`: they still accept a stack that declares webhooks without these tokens.
+  - The activation door (`POST /api/v1/security/_activation/webhook/NAME`): it answers exactly as before.
 - **What to do.** A stack that declares webhooks needs `requires` to include both `'webhooks'` and `'realtime'`.

content/docs/automation/webhooks.mdx

@@ -109,15 +109,14 @@ requires: ['automation', 'triggers', 'webhooks', 'realtime'],
 
 - `'webhooks'` mounts `plugin-webhooks`: the declared-webhook reader, the
   auto-enqueuer and the redeliver door. Without it nothing reads the
-  declaration, and the activation door answers `503 SERVICE_UNAVAILABLE`
-  because no declared-webhook reader is bound.
+  declaration at all.
 - `'realtime'` mounts the realtime service, which is the auto-enqueuer's only
   source of record events: the engine publishes `data.record.*` through it, and
   nothing else feeds the enqueuer (§4.1). With `'webhooks'` and without
-  `'realtime'` the declaration is read but never dispatched. The boot logs one
-  `error` that names each declared webhook and the missing token. The
-  activation door then refuses to switch a declared webhook on, answering
-  `503 SERVICE_UNAVAILABLE` with the same reason. Switching one off still works.
+  `'realtime'` the declaration is read but never dispatched. Record writes still
+  succeed and no delivery is ever enqueued. The boot logs one `error` that names
+  each declared webhook and the missing token. Switching a declared webhook on
+  through the activation door delivers nothing on such a deployment either.
 
 The outbox itself comes from `messaging`, which every boot mounts unless it runs
 with `--preset minimal`. A scaffolded app's `requires` is

packages/plugins/plugin-webhooks/src/auto-enqueuer-disabled-report.test.ts

@@ -2,8 +2,7 @@
 
 /**
  * [#24910] A kernel with `webhooks` and without `realtime` delivers no declared
- * webhook — and says so ONCE, at `error`, and its declared-webhook reader tells
- * the activation door so.
+ * webhook — and now says so ONCE, at `error`, with the consequence and the fix.
  *
  * ## The defect
  *
@@ -25,14 +24,13 @@
  * the realtime service is a stand-in, and only on the legs that mount one.
  *
  *  1. Declared webhook, no realtime: one `error` naming the webhook, `realtime`
- *     and the fix; no `disabled` warn; the reader's `dispatchUnavailable()`
- *     names `realtime`; and a record write enqueues nothing (the loss itself).
- *  2. CONTROL, the same stack with realtime: no error, the reader answers
- *     `null`, and the same write enqueues one delivery — so leg 1's zero is the
- *     missing service and not a fixture that cannot deliver.
+ *     and the fix; no `disabled` warn; and a record write enqueues nothing (the
+ *     loss itself).
+ *  2. CONTROL, the same stack with realtime: no error, and the same write
+ *     enqueues its deliveries — so leg 1's zero is the missing service and not a
+ *     fixture that cannot deliver.
  *  3. No declared webhook, no realtime: the `warn` it always was, no `error`.
- *  4. `autoEnqueue: false`: the host's own choice — nothing reported, and the
- *     reader answers `null` (its redelivery reads the switch).
+ *  4. `autoEnqueue: false`: the host's own choice — nothing reported.
  */
 
 import { afterEach, describe, expect, it, vi } from 'vitest';
@@ -205,20 +203,18 @@ describe('[#24910] the auto-enqueuer disabled on a stack that declares webhooks'
 
         expect(enqueuerStarted).toBe(false);
         expect(reader).toBeInstanceOf(DeclaredWebhookSource);
-        expect(reader.dispatchUnavailable()).toContain("add 'realtime' to `requires`");
         // The reader still answers the declaration — it is only dispatch that is missing.
         expect((await reader.declaredWebhookNamed(HOOK))?.active).toBe(true);
 
         await writeRecord();
         expect(outbox.enqueued).toEqual([]);
     });
 
-    it('CONTROL — the same stack with realtime: no error, the reader answers null, and the same write is delivered', async () => {
-        const { plugin, reader, enqueuerStarted, writeRecord, outbox } = await boot({ realtime: true });
+    it('CONTROL — the same stack with realtime: no error, and the same write is delivered', async () => {
+        const { plugin, enqueuerStarted, writeRecord, outbox } = await boot({ realtime: true });
 
         expect(plugin.lines('error', '[webhook-auto-enqueuer]')).toEqual([]);
         expect(enqueuerStarted).toBe(true);
-        expect(reader.dispatchUnavailable()).toBeNull();
 
         await writeRecord();
         expect(outbox.enqueued.map((d) => [d.refId, d.label])).toEqual([
@@ -228,22 +224,19 @@ describe('[#24910] the auto-enqueuer disabled on a stack that declares webhooks'
     });
 
     it('no declared webhook, no realtime: the warn it always was, never the error', async () => {
-        const { plugin, reader } = await boot({ declare: false });
+        const { plugin } = await boot({ declare: false });
 
         expect(plugin.lines('error', '[webhook-auto-enqueuer]')).toEqual([]);
         const warns = plugin.lines('warn', 'auto-enqueuer] disabled');
         expect(warns).toHaveLength(1);
         expect(warns[0].meta).toMatchObject({ hasEngine: true, hasRealtime: false, hasMessaging: true });
-        // Deployment-wide: a webhook declared later still could not be switched on here.
-        expect(reader.dispatchUnavailable()).toContain("'realtime'");
     });
 
-    it('`autoEnqueue: false` is the host\'s own composition: nothing reported, and the reader answers null', async () => {
-        const { plugin, reader, enqueuerStarted } = await boot({ plugin: { autoEnqueue: false } });
+    it('`autoEnqueue: false` is the host\'s own composition: nothing reported', async () => {
+        const { plugin, enqueuerStarted } = await boot({ plugin: { autoEnqueue: false } });
 
         expect(plugin.lines('error', '[webhook-auto-enqueuer]')).toEqual([]);
         expect(plugin.lines('warn', '[webhook-auto-enqueuer]')).toEqual([]);
         expect(enqueuerStarted).toBe(false);
-        expect(reader.dispatchUnavailable()).toBeNull();
     });
 });

packages/plugins/plugin-webhooks/src/declared-webhooks.ts

@@ -136,25 +136,6 @@ export interface DeclaredWebhookReader {
     declaredWebhookNamed(name: string): Promise<DeclaredWebhook | null>;
 }
 
-/**
- * [#24910] Whether a declared webhook switched ON is delivered on this
- * deployment at all — the question the activation door asks before it answers
- * `enabled: true`. Its own interface, beside {@link DeclaredWebhookReader}
- * rather than inside it: the dispatcher and the redelivery veto read
- * declarations, and only the door asks about dispatch.
- */
-export interface DeclaredWebhookDispatch {
-    /**
-     * Why no declared webhook is delivered on this deployment — the
-     * auto-enqueuer is disabled because a service it needs is missing — in one
-     * sentence that names the composition fix; `null` when it runs. Also `null`
-     * when the host turned auto-enqueue off itself (`autoEnqueue: false`): that
-     * is a deliberate composition whose own code enqueues, and redelivery reads
-     * the switch there.
-     */
-    dispatchUnavailable(): string | null;
-}
-
 /**
  * The raw declared `webhook` items, registry first, metadata service second.
  * Never throws: a reader that cannot answer yields nothing from that reader.
@@ -179,9 +160,10 @@ export function readDeclaredWebhookItems(engine: unknown, metadataService: unkno
 }
 
 /**
- * [#24910] The distinct `name`s of the raw declared items — what a boot report
- * names when the declared webhooks cannot be dispatched. Read the way
- * {@link readDeclaredWebhookItems} reads them; never throws.
+ * [#24910] The distinct `name`s of the raw declared items — what the boot
+ * report names when the auto-enqueuer cannot run, so nothing declared would be
+ * delivered. Read the way {@link readDeclaredWebhookItems} reads them; never
+ * throws.
  */
 export function readDeclaredWebhookNames(engine: unknown, metadataService: unknown): string[] {
     const names = new Set<string>();
@@ -194,30 +176,18 @@ export function readDeclaredWebhookNames(engine: unknown, metadataService: unkno
 
 /**
  * The reader the plugin binds: the declarations from
- * {@link readDeclaredWebhookItems}, the switch from the activation ledger, and
- * (for the activation door) whether this deployment dispatches them at all.
+ * {@link readDeclaredWebhookItems}, the switch from the activation ledger.
  */
-export class DeclaredWebhookSource implements DeclaredWebhookReader, DeclaredWebhookDispatch {
+export class DeclaredWebhookSource implements DeclaredWebhookReader {
     /** Names already reported as failing validation — said once per process. */
     private readonly invalidReported = new Set<string>();
 
-    /**
-     * @param dispatchGap - [#24910] Why the auto-enqueuer is not running on
-     *   this kernel, or `null` when it runs. The plugin decides it at
-     *   `kernel:ready`, BEFORE this reader is bound, so the door never reads a
-     *   verdict the boot has not reached yet.
-     */
     constructor(
         private readonly engine: unknown,
         private readonly metadataService: unknown,
         private readonly logger?: Logger,
-        private readonly dispatchGap: string | null = null,
     ) {}
 
-    dispatchUnavailable(): string | null {
-        return this.dispatchGap;
-    }
-
     async list(): Promise<DeclaredWebhook[]> {
         const parsed = this.parseDeclared();
         if (parsed.length === 0) return [];

packages/plugins/plugin-webhooks/src/webhook-outbox-plugin.ts

@@ -149,8 +149,8 @@ type AutoEnqueueWiring =
 
 /**
  * [#24910] Why the auto-enqueuer is not running, and the composition change
- * that starts it, as one sentence. The boot report and the activation door's
- * refusal both say exactly this, so the two can never name different fixes.
+ * that starts it, as one sentence: the reason and the fix the boot report owes
+ * (AGENTS.md "Degradation log levels").
  */
 function autoEnqueueGapReason(gap: AutoEnqueueGap): string {
     const missing: string[] = [];
@@ -286,23 +286,18 @@ export class WebhookOutboxPlugin implements Plugin {
 
         if (typeof (ctx as any).hook === 'function') {
             (ctx as any).hook('kernel:ready', async () => {
-                // [#24910] Whether the auto-enqueuer can run is decided FIRST,
-                // before the declared-webhook reader is bound below, so the
-                // activation door reads the verdict from the reader's birth and
-                // never a "dispatching" the boot has not established.
-                const wiring = this.resolveAutoEnqueueWiring(ctx, autoEnqueueOpt);
                 // The table's write doors, the legacy-secret sweep and the
-                // declared-webhook reader — this only needs the data
+                // declared-webhook reader FIRST — this only needs the data
                 // engine, so it must not be gated behind the auto-enqueue
                 // dispatch prerequisites (realtime + messaging).
-                await this.bootWebhookTable(ctx, wiring);
+                await this.bootWebhookTable(ctx);
                 // [#22756] The redelivery veto, and beside it the `webhooks`
                 // service — gated on the engine and messaging alone, like the
                 // step above, and never on the auto-enqueue prerequisites. It
                 // runs before the enqueuer writes its first row (#8069), and
                 // before the mount below is mounted.
                 this.bootRedeliverDoor(ctx, autoEnqueueOpt);
-                await this.bootAutoEnqueue(ctx, autoEnqueueOpt, wiring);
+                await this.bootAutoEnqueue(ctx, autoEnqueueOpt);
                 this.registerAdminRoutes(ctx);
             });
         }
@@ -372,7 +367,7 @@ export class WebhookOutboxPlugin implements Plugin {
      * dispatches nothing. Runs before {@link bootAutoEnqueue}, which reads the
      * reader bound here.
      */
-    private async bootWebhookTable(ctx: PluginContext, wiring: AutoEnqueueWiring): Promise<void> {
+    private async bootWebhookTable(ctx: PluginContext): Promise<void> {
         const engine = this.tryGetService<IDataEngine>(ctx, ['objectql', 'data']);
         if (!engine) {
             ctx.logger.warn?.('[webhook] sys_webhook write doors and the declared-webhook reader not bound — no data engine available');
@@ -397,13 +392,7 @@ export class WebhookOutboxPlugin implements Plugin {
         bindWebhookLegacyCleartextGate(engine as any, ctx.logger as any);
         let metadataService: IMetadataService | undefined;
         try { metadataService = ctx.getService<IMetadataService>('metadata'); } catch { /* optional */ }
-        // [#24910] Born knowing whether this kernel dispatches what it reads.
-        this.declaredSource = new DeclaredWebhookSource(
-            engine,
-            metadataService,
-            ctx.logger as any,
-            wiring.kind === 'gap' ? autoEnqueueGapReason(wiring.gap) : null,
-        );
+        this.declaredSource = new DeclaredWebhookSource(engine, metadataService, ctx.logger as any);
         ctx.registerService(DECLARED_WEBHOOKS_SLOT, this.declaredSource);
         // And the declared-name guard: a row that took a declared name would
         // withhold the declaration for the whole deployment, so no non-system
@@ -462,8 +451,7 @@ export class WebhookOutboxPlugin implements Plugin {
             ctx.logger.error?.(
                 `[webhook-auto-enqueuer] the ${declared.length} webhook${declared.length === 1 ? '' : 's'} this stack `
                     + `declares (${declared.join(', ')}) will NEVER be delivered: record writes still succeed and nothing `
-                    + `else reports the loss, but no delivery is ever enqueued — ${autoEnqueueGapReason(gap)} Until then the `
-                    + 'activation door refuses to switch a declared webhook on.',
+                    + `else reports the loss, but no delivery is ever enqueued — ${autoEnqueueGapReason(gap)}`,
                 undefined,
                 { ...gap, declared },
             );
@@ -478,8 +466,8 @@ export class WebhookOutboxPlugin implements Plugin {
     private async bootAutoEnqueue(
         ctx: PluginContext,
         opt: boolean | AutoEnqueuerOptions,
-        wiring: AutoEnqueueWiring,
     ): Promise<void> {
+        const wiring = this.resolveAutoEnqueueWiring(ctx, opt);
         if (wiring.kind === 'off') return;
         if (wiring.kind === 'gap') {
             this.reportAutoEnqueueGap(ctx, wiring.gap);