chore(spec): flip webhook liveness ledger dead→live + webhook-materialization proof (#3490)

Follow-up to #3489. The materializer bridge made stack-authored webhooks reach
the dispatcher, so the webhook liveness ledger (packages/spec/liveness/webhook.json)
was stale — it still classified all 16 authorable props `dead` from the pre-bridge
"nothing materializes an authored webhook" vantage point. Because `webhook` rides
the SPEC_ONLY_SCHEMAS gate path (walk-only), the liveness CI did NOT catch the
dead→live drift; this updates it by hand.

- Flip the props the materializer + dispatcher consume to `live` with evidence
  (materializer bootstrap-declared-webhooks.ts + dispatcher auto-enqueuer.ts):
  object/isActive/url/triggers/method/name/headers/secret/timeoutMs, plus
  display-only label/description. Drop the `url` authorWarn (authoring is live).
- Keep `dead`: body/payloadFields/includeSession/retryPolicy/tags — folded into
  definition_json by the bridge but parseRow never reads them (no consumer, the
  #1878 delivery-layer worklist). `authentication` stays experimental.
- Add a `webhook-materialization` ADR-0054 high-risk proof class (proof-registry.mts,
  bound to webhook.object) + its dogfood proof: bootStack with the messaging +
  webhook plugins but NO realtime, asserting the sys_webhook row materializes with
  object→object_name / isActive→active. Pins the #3461 integration seam (the bridge
  was first gated behind the realtime dispatch guard, silently materializing nothing).
- Refresh the stale "enforce-or-remove pending #3461" prose in check-liveness.mts
  and webhook.json's _note (the disconnect is closed by #3489).

Verified: liveness gate green (webhook 17 classified: live 11 / dead 5 / exp 1;
webhook-materialization proof resolves) and red-proofed (breaking the proof tag →
exit 1); the dogfood proof passes (logs confirm hasRealtime:false yet the row
materializes). Liveness-ledger + gate assets and the private dogfood package only —
no package release.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: os-zhuang

.changeset/webhook-liveness-ledger-flip.md

@@ -0,0 +1,23 @@
+---
+---
+
+chore(spec): flip webhook liveness ledger dead→live + webhook-materialization ADR-0054 proof (#3490)
+
+Follow-up to #3489 (the materializer bridge). Now that stack-authored webhooks
+are materialized into dispatchable `sys_webhook` rows, the props the materializer
++ dispatcher actually consume flip from `dead` to `live` in
+`packages/spec/liveness/webhook.json` (`object`/`isActive`/`url`/`triggers`/
+`method`/`name`/`headers`/`secret`/`timeoutMs` + display-only `label`/
+`description`); `body`/`payloadFields`/`includeSession`/`retryPolicy`/`tags` stay
+`dead` (folded into `definition_json` but never read — the #1878 delivery-layer
+worklist) and `authentication` stays `experimental`. The `url` authorWarn is
+dropped (authoring is live now).
+
+Adds a `webhook-materialization` ADR-0054 high-risk proof class (bound to
+`webhook.object`) with a `@objectstack/dogfood` proof that boots the real stack
+WITHOUT realtime and asserts the row materializes — pinning the #3461 integration
+seam (the bridge was first gated behind the realtime dispatch guard).
+
+Liveness-ledger + gate assets (`packages/spec/liveness` + `scripts/liveness`, not
+in the published spec runtime) and the private `@objectstack/dogfood` package
+only — no package release.

packages/qa/dogfood/package.json

@@ -19,6 +19,8 @@
     "@objectstack/plugin-audit": "workspace:*",
     "@objectstack/plugin-auth": "workspace:*",
     "@objectstack/plugin-security": "workspace:*",
+    "@objectstack/plugin-webhooks": "workspace:*",
+    "@objectstack/service-messaging": "workspace:*",
     "@objectstack/service-storage": "workspace:*",
     "@objectstack/spec": "workspace:*",
     "@objectstack/verify": "workspace:*"

packages/qa/dogfood/test/fixtures/webhook-materialization-fixture.ts

@@ -0,0 +1,59 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// Webhook materialization fixture — the deterministic ADR-0054 proof for the
+// `webhook-materialization` high-risk class.
+//
+// A webhook prop is `live` in the ledger because a stack-authored `webhooks:`
+// entry is materialized into a dispatchable `sys_webhook` row on boot
+// (#3461/#3489) — but "materialized" is not "reads the schema". The authored
+// value crosses manifest-decomposition → the ObjectQL registry (type `webhook`)
+// → `bootstrapDeclaredWebhooks` → `engine.insert('sys_webhook')`, and the break
+// can live in any seam: the bridge was first gated BEHIND the realtime/messaging
+// dispatch guard, so a boot without realtime silently materialized nothing (the
+// exact silent no-op #3461 set out to kill). This fixture authors ONE webhook
+// against ONE object, with ZERO dependence on an example app, so the proof can
+// assert the runtime outcome: the sys_webhook row exists with the spec→runtime
+// remap applied (`object`→`object_name`, `isActive`→`active`).
+
+import { defineStack } from '@objectstack/spec';
+import { ObjectSchema, Field } from '@objectstack/spec/data';
+import { defineWebhook } from '@objectstack/spec/automation';
+
+/** The one object the authored webhook subscribes to. */
+export const WmTask = ObjectSchema.create({
+  name: 'wm_task',
+  // [ADR-0090 D1] grandfather stamp: this fixture's gate under test is webhook
+  // materialization, not owner-sharing — keep RLS out of the way.
+  sharingModel: 'public_read_write',
+  label: 'WM Task',
+  pluralLabel: 'WM Tasks',
+  fields: {
+    name: Field.text({ label: 'Name', required: true }),
+  },
+});
+
+/**
+ * The stack-authored webhook. `object` (spec) must land as `object_name`
+ * (runtime col) and `isActive` as `active` — the remap the proof asserts.
+ */
+export const wmTaskChanged = defineWebhook({
+  name: 'wm_task_changed',
+  label: 'WM Task Changed',
+  object: 'wm_task',
+  triggers: ['create', 'update'],
+  url: 'https://hooks.example/wm-task',
+  isActive: true,
+});
+
+export const webhookFixtureStack = defineStack({
+  manifest: {
+    id: 'com.dogfood.webhook_fixture',
+    namespace: 'wm',
+    version: '0.0.0',
+    type: 'app',
+    name: 'Webhook Materialization Fixture',
+    description: 'Single-object app that authors one webhook to prove stack `webhooks:` entries materialize into dispatchable sys_webhook rows (ADR-0054, #3461).',
+  },
+  objects: [WmTask],
+  webhooks: [wmTaskChanged],
+});

packages/qa/dogfood/test/webhook-materialization.dogfood.test.ts

@@ -0,0 +1,70 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// WEBHOOK MATERIALIZATION proof (ADR-0054), exercised end-to-end through the
+// real in-process stack.
+//
+// @proof: webhook-materialization
+// ADR-0054 runtime proof for the webhook-materialization high-risk class.
+// Referenced by the liveness ledger entry `webhook.object`
+// (packages/spec/liveness/webhook.json); the spec liveness gate fails if this
+// tag is removed. See proof-registry.mts.
+//
+// A webhook prop being `live` means the materializer + dispatcher READ it —
+// necessary but not sufficient. This boots the real stack with the webhook +
+// messaging plugins, authors a webhook via the app config's `webhooks:` array,
+// and asserts the observable runtime outcome: a dispatchable `sys_webhook` row
+// materialized on boot with the spec→runtime remap applied (`object`→
+// `object_name`, `isActive`→`active`). It also pins the #3461 integration bug:
+// the fixture boots WITHOUT realtime, so a materializer re-gated behind the
+// dispatch guard would materialize nothing and this proof would fail.
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { bootStack, type VerifyStack } from '@objectstack/verify';
+import { MessagingServicePlugin } from '@objectstack/service-messaging';
+import { WebhookOutboxPlugin } from '@objectstack/plugin-webhooks';
+import { webhookFixtureStack } from './fixtures/webhook-materialization-fixture.js';
+
+const SYSTEM_CTX = { isSystem: true, positions: [], permissions: [] };
+
+describe('objectstack verify WEBHOOK: authored webhook materializes into sys_webhook (#webhook-materialization)', () => {
+  let stack: VerifyStack;
+
+  beforeAll(async () => {
+    // `extraPlugins` mirrors the capability plugins `objectstack serve` mounts
+    // for `requires: ['webhooks']` — messaging first (WebhookOutboxPlugin
+    // depends on it), then the webhook plugin. Deliberately NO realtime service:
+    // materialization must run on the data engine alone (bootDeclaredWebhooks),
+    // independent of the auto-enqueue dispatch prerequisites.
+    stack = await bootStack(webhookFixtureStack, {
+      extraPlugins: [new MessagingServicePlugin(), new WebhookOutboxPlugin()],
+    });
+  }, 60_000);
+
+  afterAll(async () => {
+    await stack?.stop();
+  });
+
+  it('materializes the stack-authored webhook into a sys_webhook row (object→object_name, isActive→active)', async () => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const engine = (await stack.kernel.getServiceAsync('objectql')) as any;
+    const rows = await engine.find('sys_webhook', {
+      filter: { name: 'wm_task_changed' },
+      context: SYSTEM_CTX,
+    });
+
+    expect(rows, 'authored webhook was NOT materialized into a sys_webhook row').toHaveLength(1);
+    const row = rows[0];
+
+    // The remaps that are the whole point of the bridge.
+    expect(row.object_name, 'spec `object` did not remap to runtime `object_name`').toBe('wm_task');
+    expect(row.active, 'spec `isActive:true` did not remap to runtime `active`').toBeTruthy();
+
+    // Boot-seeded provenance (seed-not-clobber): a package row, not admin.
+    expect(row.managed_by).toBe('package');
+
+    // The full envelope is stashed for the dispatcher's advanced-config read.
+    const defn = JSON.parse(row.definition_json);
+    expect(defn.object).toBe('wm_task');
+    expect(defn.triggers).toEqual(['create', 'update']);
+  });
+});