@objectstack/plugin-webhooks 16.0.0 → 17.0.0-rc.0

package/src/bootstrap-declared-webhooks.test.ts

@@ -0,0 +1,283 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * bootstrapDeclaredWebhooks — the ingestion bridge that closes #3461.
+ *
+ * Verifies that stack/connector-declared `webhook` metadata (spec shape:
+ * `object` / `isActive`) is materialized into `sys_webhook` data rows
+ * (`object_name` / `active` / `definition_json`), idempotently and without
+ * clobbering admin edits — and that the dispatcher then sees those rows.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+import { AutoEnqueuer, type HttpEnqueueFn } from './auto-enqueuer.js';
+import { bootstrapDeclaredWebhooks } from './bootstrap-declared-webhooks.js';
+import { bindWebhookProvenanceStamp } from './webhook-provenance.js';
+
+// ---------------------------------------------------------------------------
+// Fakes
+// ---------------------------------------------------------------------------
+
+interface HookEntry {
+  event: string;
+  handler: (ctx: any) => any;
+  object?: string;
+  packageId?: string;
+}
+
+/**
+ * A small engine fake that mirrors the real ObjectQL surface the bridge and
+ * provenance hook touch: `find({ filter | where })`, `insert`, update-by-id (the
+ * patch carries `id`, no `where`), a `_registry.listItems(type)` for declared
+ * metadata, and `beforeUpdate` hooks that run inside `update()`.
+ */
+class FakeEngine {
+  rows: Record<string, any[]> = {};
+  private hooks: HookEntry[] = [];
+  private declared: Record<string, any[]> = {};
+
+  constructor(seed?: { rows?: Record<string, any[]>; declared?: Record<string, any[]> }) {
+    if (seed?.rows) this.rows = JSON.parse(JSON.stringify(seed.rows));
+    if (seed?.declared) this.declared = JSON.parse(JSON.stringify(seed.declared));
+  }
+
+  // Declared-metadata registry (where manifest decomposition parks stack.webhooks).
+  get _registry() {
+    return {
+      listItems: (type: string) => (this.declared[type] ?? []).map((content) => ({ content })),
+    };
+  }
+
+  private matches(row: any, cond?: Record<string, any>): boolean {
+    if (!cond) return true;
+    return Object.entries(cond).every(([k, v]) => row[k] === v);
+  }
+
+  async find(name: string, q?: any): Promise<any[]> {
+    const all = this.rows[name] ?? [];
+    const cond = q?.filter ?? q?.where;
+    const out = all.filter((r) => this.matches(r, cond));
+    return typeof q?.limit === 'number' ? out.slice(0, q.limit) : out;
+  }
+  async findOne(name: string, q?: any): Promise<any> {
+    return (await this.find(name, q))[0] ?? null;
+  }
+  async insert(name: string, data: any): Promise<any> {
+    const arr = (this.rows[name] = this.rows[name] ?? []);
+    arr.push({ ...data });
+    return data;
+  }
+  async update(name: string, data: any, opts?: any): Promise<any> {
+    // Run beforeUpdate hooks (the provenance stamp lives here).
+    const id = data?.id ?? opts?.where?.id;
+    const ctx = { input: { id, data }, session: opts?.context };
+    for (const h of this.hooks) {
+      if (h.event === 'beforeUpdate' && (!h.object || h.object === name)) {
+        await h.handler(ctx);
+      }
+    }
+    const arr = this.rows[name] ?? [];
+    const cond = opts?.where ?? (id ? { id } : undefined);
+    for (const r of arr) {
+      if (this.matches(r, cond)) Object.assign(r, data);
+    }
+    return { affected: 0 };
+  }
+  async delete(): Promise<any> {
+    return { affected: 0 };
+  }
+  async count(name: string): Promise<number> {
+    return (this.rows[name] ?? []).length;
+  }
+  async aggregate(): Promise<any[]> {
+    return [];
+  }
+
+  registerHook(event: string, handler: (ctx: any) => any, options?: Record<string, any>): void {
+    this.hooks.push({ event, handler, object: options?.object, packageId: options?.packageId });
+  }
+  unregisterHooksByPackage(packageId: string): number {
+    const before = this.hooks.length;
+    this.hooks = this.hooks.filter((h) => h.packageId !== packageId);
+    return before - this.hooks.length;
+  }
+}
+
+class FakeRealtime {
+  private subs = new Map<string, { handler: any; opts?: any }>();
+  private n = 0;
+  async publish(event: any): Promise<void> {
+    for (const sub of this.subs.values()) {
+      const o = sub.opts ?? {};
+      if (o.object && event.object !== o.object) continue;
+      await sub.handler(event);
+    }
+  }
+  async subscribe(_channel: string, handler: any, opts?: any): Promise<string> {
+    const id = `s-${++this.n}`;
+    this.subs.set(id, { handler, opts });
+    return id;
+  }
+  async unsubscribe(id: string): Promise<void> {
+    this.subs.delete(id);
+  }
+}
+
+const ADMIN_CTX = { isSystem: false, positions: [], permissions: [] };
+
+function declaredWebhook(over: Record<string, any> = {}): any {
+  return {
+    name: 'task_changed',
+    label: 'Task Changed',
+    object: 'showcase_task',
+    triggers: ['create', 'update'],
+    url: 'https://hooks.example/task',
+    method: 'POST',
+    isActive: true,
+    ...over,
+  };
+}
+
+async function flush() {
+  await new Promise((r) => setTimeout(r, 0));
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('bootstrapDeclaredWebhooks', () => {
+  it('materializes a declared webhook into a sys_webhook row (object→object_name, isActive→active)', async () => {
+    const engine = new FakeEngine({ declared: { webhook: [declaredWebhook()] } });
+    const res = await bootstrapDeclaredWebhooks(engine as any, null);
+
+    expect(res).toEqual({ seeded: 1, skipped: 0 });
+    const rows = engine.rows['sys_webhook'];
+    expect(rows).toHaveLength(1);
+    const row = rows[0];
+    expect(row.name).toBe('task_changed');
+    expect(row.object_name).toBe('showcase_task'); // object → object_name
+    expect(row.active).toBe(true); // isActive → active
+    expect(row.method).toBe('post'); // lowercased to match the select options
+    expect(row.managed_by).toBe('package');
+    expect(row.customized).toBe(false);
+    // Full validated envelope stashed for the enqueuer's advanced-config read.
+    const defn = JSON.parse(row.definition_json);
+    expect(defn.object).toBe('showcase_task');
+    expect(defn.timeoutMs).toBe(30000); // default filled by WebhookSchema.parse
+  });
+
+  it('maps isActive:false → active:false so a placeholder webhook ships inactive', async () => {
+    const engine = new FakeEngine({ declared: { webhook: [declaredWebhook({ isActive: false })] } });
+    await bootstrapDeclaredWebhooks(engine as any, null);
+    expect(engine.rows['sys_webhook'][0].active).toBe(false);
+  });
+
+  it('is idempotent — a second boot updates in place, never duplicates', async () => {
+    const engine = new FakeEngine({ declared: { webhook: [declaredWebhook()] } });
+    await bootstrapDeclaredWebhooks(engine as any, null);
+    await bootstrapDeclaredWebhooks(engine as any, null);
+    expect(engine.rows['sys_webhook']).toHaveLength(1);
+  });
+
+  it('propagates a declared change to a pristine (non-customized) row', async () => {
+    const engine = new FakeEngine({ declared: { webhook: [declaredWebhook()] } });
+    await bootstrapDeclaredWebhooks(engine as any, null);
+
+    engine['declared'].webhook = [declaredWebhook({ url: 'https://hooks.example/task-v2' })];
+    await bootstrapDeclaredWebhooks(engine as any, null);
+
+    expect(engine.rows['sys_webhook']).toHaveLength(1);
+    expect(engine.rows['sys_webhook'][0].url).toBe('https://hooks.example/task-v2');
+  });
+
+  it('seed-not-clobber: an admin edit (customized) survives the next boot', async () => {
+    const engine = new FakeEngine({ declared: { webhook: [declaredWebhook()] } });
+    bindWebhookProvenanceStamp(engine as any);
+    await bootstrapDeclaredWebhooks(engine as any, null);
+
+    // Admin deactivates the noisy webhook through the CRUD door (non-system).
+    const id = engine.rows['sys_webhook'][0].id;
+    await engine.update('sys_webhook', { id, active: false }, { context: ADMIN_CTX });
+    expect(engine.rows['sys_webhook'][0].customized).toBe(true); // hook stamped it
+
+    // Redeploy re-runs the seeder — the declared row is still active:true, but
+    // the admin's active:false must win.
+    await bootstrapDeclaredWebhooks(engine as any, null);
+    expect(engine.rows['sys_webhook'][0].active).toBe(false);
+  });
+
+  it('never overwrites an admin-authored row that collides by name', async () => {
+    const engine = new FakeEngine({
+      rows: {
+        sys_webhook: [
+          { id: 'admin-1', name: 'task_changed', url: 'https://admin.example', active: true, managed_by: 'admin', customized: false },
+        ],
+      },
+      declared: { webhook: [declaredWebhook()] },
+    });
+    const res = await bootstrapDeclaredWebhooks(engine as any, null);
+    expect(res).toEqual({ seeded: 0, skipped: 1 });
+    expect(engine.rows['sys_webhook']).toHaveLength(1);
+    expect(engine.rows['sys_webhook'][0].url).toBe('https://admin.example'); // untouched
+  });
+
+  it('skips an invalid declared webhook (bad URL) with a warning, without crashing boot', async () => {
+    const warn = vi.fn();
+    const engine = new FakeEngine({
+      declared: { webhook: [declaredWebhook({ name: 'good' }), declaredWebhook({ name: 'bad', url: 'not-a-url' })] },
+    });
+    const res = await bootstrapDeclaredWebhooks(engine as any, null, { warn });
+
+    expect(res.seeded).toBe(1); // the good one still lands
+    expect(res.skipped).toBe(1);
+    expect(engine.rows['sys_webhook'].map((r) => r.name)).toEqual(['good']);
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('failed validation'), expect.objectContaining({ name: 'bad' }));
+  });
+
+  it('is a no-op when nothing is declared', async () => {
+    const engine = new FakeEngine();
+    const res = await bootstrapDeclaredWebhooks(engine as any, null);
+    expect(res).toEqual({ seeded: 0, skipped: 0 });
+    expect(engine.rows['sys_webhook']).toBeUndefined();
+  });
+
+  it('end-to-end: a declared webhook, once materialized, dispatches on a matching data event', async () => {
+    const engine = new FakeEngine({
+      declared: {
+        webhook: [
+          declaredWebhook({
+            triggers: ['create'],
+            secret: 'shh',
+            headers: { 'X-Env': 'prod' },
+          }),
+        ],
+      },
+    });
+    await bootstrapDeclaredWebhooks(engine as any, null);
+
+    const realtime = new FakeRealtime();
+    const calls: any[] = [];
+    const enqueue: HttpEnqueueFn = async (input) => {
+      calls.push(input);
+      return 'id';
+    };
+    const ae = new AutoEnqueuer(engine as any, realtime as any, enqueue, { refreshIntervalMs: 0 });
+    await ae.start();
+
+    await realtime.publish({
+      type: 'data.record.created',
+      object: 'showcase_task',
+      payload: { recordId: 't-1' },
+      timestamp: '2026-05-24T00:00:00.000Z',
+    });
+    await flush();
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0].url).toBe('https://hooks.example/task');
+    // headers + secret came from the definition_json envelope the bridge wrote.
+    expect(calls[0].signingSecret).toBe('shh');
+    expect(calls[0].headers).toEqual({ 'X-Env': 'prod' });
+    await ae.stop();
+  });
+});

package/src/bootstrap-declared-webhooks.ts

@@ -0,0 +1,205 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * bootstrapDeclaredWebhooks — materialize stack/connector-declared `webhooks`
+ * into `sys_webhook` rows so the dispatcher can actually see them (closes #3461).
+ *
+ * ## The disconnect this closes
+ * The spec authoring surface (`WebhookSchema` — `defineStack({ webhooks })`,
+ * `@objectstack/spec/automation/webhook`) declares `object` / `isActive`, and
+ * is generically decomposed into the ObjectQL registry at boot as metadata
+ * type `webhook`. But the runtime dispatcher ({@link AutoEnqueuer}) reads
+ * `sys_webhook` DATA rows (`object_name` / `active`), which until now were only
+ * ever written by hand through the object's CRUD UI. Nothing bridged the two —
+ * so authoring `webhooks:` on a stack produced metadata artifacts that never
+ * became dispatchable rows (a silent no-op; ADR-0078). This seeder is that
+ * missing ingestion path.
+ *
+ * ## Shape translation (authoring → runtime row)
+ * The spec shape diverges from the runtime column names; we map only at this
+ * boundary and stash the full validated envelope in `definition_json` (whence
+ * the enqueuer reads headers / secret / timeout):
+ *   - `object`     → `object_name`
+ *   - `isActive`   → `active`
+ *   - `triggers` / `url` / `method` / `label` / `description` → same-named columns
+ *   - the entire parsed {@link Webhook} → `definition_json` (JSON string)
+ *
+ * Each item is validated through `WebhookSchema.parse()` first — this gives the
+ * spec schema a real consumer (defaults for `method`/`isActive`/`timeoutMs` get
+ * applied) and rejects malformed authoring with a warning instead of crashing
+ * boot.
+ *
+ * ## Seed-not-clobber (mirrors sys_sharing_rule, #2909)
+ * `sys_webhook` is admin-editable (`managedBy: 'config'`). Declared webhooks
+ * ship with the app/package, so they seed with `managed_by: 'package'`
+ * provenance and re-seed on every boot — but a row an admin has created
+ * (`managed_by: 'admin'`) or edited (`customized: true`, stamped by
+ * {@link bindWebhookProvenanceStamp}) is never overwritten. Most importantly,
+ * an admin's `active: false` on a noisy webhook survives redeploys.
+ *
+ * MUST run before {@link AutoEnqueuer.start} so the enqueuer's first cache
+ * refresh already sees the declared rows.
+ */
+
+import type { IDataEngine } from '@objectstack/spec/contracts';
+import { WebhookSchema, type Webhook } from '@objectstack/spec/automation';
+
+/** System write context — the boot seeder is not an admin authoring action. */
+const SYSTEM_CTX = { isSystem: true, positions: [], permissions: [] } as const;
+
+interface Logger {
+  info?: (msg: string, meta?: unknown) => void;
+  warn?: (msg: string, meta?: unknown) => void;
+}
+
+/** Random id with a stable prefix — mirrors the sharing-rule seeder. */
+function uid(prefix: string): string {
+  const g: any = globalThis as any;
+  if (g.crypto?.randomUUID) return `${prefix}_${g.crypto.randomUUID()}`;
+  return `${prefix}_${Math.random().toString(36).slice(2, 10)}`;
+}
+
+/**
+ * Read declared `webhook` items from the ObjectQL registry (where the manifest
+ * decomposition parks `stack.webhooks`), falling back to the metadata service.
+ * Items may be wrapped as `{ content }` — unwrap to the raw authoring object.
+ */
+function readDeclared(engine: any, metadataService: any, type: string): any[] {
+  try {
+    const reg = engine?._registry;
+    if (reg?.listItems) {
+      const items = (reg.listItems(type) ?? []).map((i: any) => i?.content ?? i).filter(Boolean);
+      if (items.length > 0) return items;
+    }
+  } catch {
+    /* fall through to metadata service */
+  }
+  try {
+    const listed = metadataService?.list?.(type);
+    const arr = typeof (listed as any)?.then === 'function' ? [] : (listed ?? []);
+    return Array.isArray(arr) ? arr.map((i: any) => i?.content ?? i).filter(Boolean) : [];
+  } catch {
+    return [];
+  }
+}
+
+export interface BootstrapDeclaredWebhooksResult {
+  seeded: number;
+  skipped: number;
+}
+
+/**
+ * Materialize declared webhooks into `sys_webhook`. Idempotent and safe to run
+ * on every boot.
+ */
+export async function bootstrapDeclaredWebhooks(
+  engine: IDataEngine,
+  metadataService: any,
+  logger?: Logger,
+  subscriptionsObject = 'sys_webhook',
+): Promise<BootstrapDeclaredWebhooksResult> {
+  const declared = readDeclared(engine, metadataService, 'webhook');
+  if (declared.length === 0) return { seeded: 0, skipped: 0 };
+
+  const now = new Date().toISOString();
+  let seeded = 0;
+  let skipped = 0;
+
+  for (const raw of declared) {
+    // Validate + fill defaults through the canonical spec schema. A real
+    // consumer at last — a malformed webhook warns and is skipped, never
+    // crashing boot.
+    let wh: Webhook;
+    try {
+      wh = WebhookSchema.parse(raw);
+    } catch (err: any) {
+      logger?.warn?.('[webhook] declared webhook failed validation — skipped', {
+        name: (raw as any)?.name,
+        error: err?.message ?? String(err),
+      });
+      skipped += 1;
+      continue;
+    }
+
+    try {
+      const existing = await engine.find(subscriptionsObject, {
+        filter: { name: wh.name },
+        limit: 1,
+        context: SYSTEM_CTX,
+      } as any);
+      const row: any = Array.isArray(existing) ? existing[0] : undefined;
+
+      if (row) {
+        // Admin owns a same-named row, or has edited this seeded one — never
+        // clobber. `active: false` on a noisy webhook must survive redeploys.
+        if (row.managed_by === 'admin') {
+          logger?.warn?.('[webhook] declared name collides with an admin-authored row — seed skipped', {
+            name: wh.name,
+          });
+          skipped += 1;
+          continue;
+        }
+        if (row.customized === true) {
+          skipped += 1;
+          continue;
+        }
+        const patch = {
+          id: row.id,
+          ...mapWebhookToRow(wh),
+          // Adopt pristine/legacy (pre-provenance) rows so future boots
+          // recognize them as package-managed.
+          managed_by: 'package',
+          updated_at: now,
+        };
+        await engine.update(subscriptionsObject, patch, { context: SYSTEM_CTX } as any);
+        seeded += 1;
+        continue;
+      }
+
+      const newRow = {
+        id: uid('whk'),
+        ...mapWebhookToRow(wh),
+        managed_by: 'package',
+        customized: false,
+        created_at: now,
+        updated_at: now,
+      };
+      await engine.insert(subscriptionsObject, newRow, { context: SYSTEM_CTX } as any);
+      seeded += 1;
+    } catch (err: any) {
+      logger?.warn?.('[webhook] declared webhook seed failed', {
+        name: wh.name,
+        error: err?.message ?? String(err),
+      });
+      skipped += 1;
+    }
+  }
+
+  logger?.info?.('[webhook] declared webhooks materialized into sys_webhook', {
+    seeded,
+    skipped,
+    total: declared.length,
+  });
+  return { seeded, skipped };
+}
+
+/**
+ * Translate a validated {@link Webhook} into `sys_webhook` column values.
+ * `object → object_name`, `isActive → active`; the full envelope is stashed in
+ * `definition_json` for the enqueuer's advanced-config read (headers/secret/…).
+ */
+function mapWebhookToRow(wh: Webhook): Record<string, unknown> {
+  return {
+    name: wh.name,
+    label: wh.label ?? wh.name,
+    object_name: wh.object ?? null,
+    triggers: wh.triggers ?? [],
+    url: wh.url,
+    // Store lowercase to match the object's Field.select option values
+    // (get/post/…); the enqueuer upper-cases before delivery either way.
+    method: String(wh.method ?? 'POST').toLowerCase(),
+    description: wh.description ?? null,
+    active: wh.isActive !== false,
+    definition_json: JSON.stringify(wh),
+  };
+}

package/src/sys-webhook.object.ts

@@ -10,19 +10,25 @@ import { ObjectSchema, Field } from '@objectstack/spec/data';
  * Studio UI without code changes. The canonical Zod schema for the
  * `definition_json` envelope lives at `@objectstack/spec/automation/webhook`.
  *
- * One row per `name`. The automation runtime
- * (`@objectstack/service-automation`, built-in `http_request` node) loads
- * active rows on boot + on `sys_webhook:changed` events, registers
- * `afterInsert` / `afterUpdate` / `afterDelete` listeners for the
- * targeted object, and dispatches outbound HTTP calls when matching
- * record events fire.
+ * ## Two authoring doors, one row
+ * Rows land here two ways, distinguished by the `managed_by` provenance column:
+ *   - **admin** — created/edited directly through this object's CRUD UI.
+ *   - **package** — declared in code (`defineStack({ webhooks })` /
+ *     `defineWebhook()`) and materialized on boot by
+ *     `bootstrapDeclaredWebhooks` (#3461). Re-seeded every boot, but an admin
+ *     edit stamps `customized: true` and freezes the row (seed-not-clobber,
+ *     mirrors `sys_sharing_rule` #2909).
+ *
+ * One row per `name`. This plugin's {@link AutoEnqueuer} loads active rows on
+ * boot + on `sys_webhook:changed` events, and turns matching `data.record.*`
+ * events into deliveries on the shared `service-messaging` HTTP outbox
+ * (ADR-0018 M3 — `sys_http_delivery`, drained by the messaging dispatcher).
  *
  * Ownership (ADR-0029 K2.a): this object is **owned by
- * `@objectstack/plugin-webhooks`** — the plugin that consumes these rows —
- * alongside its sibling `sys_webhook_delivery`. It used to live in the
- * `@objectstack/platform-objects` monolith and be imported here; the
- * definition now lives with its owner so the plugin ships both data and
- * behavior as one unit.
+ * `@objectstack/plugin-webhooks`** — the plugin that consumes these rows. It
+ * used to live in the `@objectstack/platform-objects` monolith and be imported
+ * here; the definition now lives with its owner so the plugin ships both data
+ * and behavior as one unit.
  *
  * Platform-wide on purpose: every project (standalone, single-tenant,
  * cloud) can integrate with external systems (Slack, Stripe, internal
@@ -43,7 +49,7 @@ export const SysWebhook = ObjectSchema.create({
   // create/edit/delete so admins can at least toggle `active` and edit
   // simple URL/method fields without round-tripping through code.
   userActions: { create: true, edit: true, delete: true, import: false },
-  description: 'Outbound HTTP webhook subscription. Authored via defineWebhook() in code or the Studio editor; executed by the HTTP connector plugin.',
+  description: 'Outbound HTTP webhook subscription. Declared in code via defineStack({ webhooks }) / defineWebhook() (materialized into rows on boot) or authored directly in the Studio editor; dispatched by the webhook auto-enqueuer onto the shared HTTP outbox.',
   displayNameField: 'name',
   nameField: 'name', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
   titleFormat: '{label}',
@@ -174,6 +180,38 @@ export const SysWebhook = ObjectSchema.create({
       group: 'Definition',
     }),
 
+    // ── Provenance (#3461 — record-authoritative seed-not-clobber) ──
+    // Mirrors sys_sharing_rule (#2909). Both columns are `readonly`: the
+    // engine strips them from non-system payloads (forge/clear-proof), while
+    // bootstrapDeclaredWebhooks and the provenance stamp hook write with
+    // isSystem. Deliberately NOT a write gate: webhooks are a first-class admin
+    // authoring/tuning surface — admins may edit or deactivate a package row;
+    // the seeder simply stops overwriting it once `customized` is stamped.
+    managed_by: Field.select(
+      ['platform', 'package', 'admin'],
+      {
+        label: 'Managed By',
+        required: false,
+        readonly: true,
+        defaultValue: 'admin',
+        description:
+          'Record provenance: platform = framework built-in / package = app/package-declared ' +
+          '(boot-seeded from defineStack webhooks) / admin = created in Setup.',
+        group: 'System',
+      },
+    ),
+
+    customized: Field.boolean({
+      label: 'Customized',
+      required: false,
+      readonly: true,
+      defaultValue: false,
+      description:
+        'Set when an admin edits a package-declared webhook; boot seeding will no longer ' +
+        'overwrite the row (a deactivated noisy webhook survives redeploys). Meaningless on admin rows.',
+      group: 'System',
+    }),
+
     created_at: Field.datetime({
       label: 'Created At',
       required: true,

package/src/translations/bundle-ownership.test.ts

@@ -0,0 +1,41 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// Bundle-ownership guard (#2834 ⑤ / ADR-0029 D8): this package's generated
+// object-translation bundles must carry ONLY objects its extract config
+// (`scripts/i18n-extract.config.ts`) actually imports. When an object moves to
+// another package, its translations move with it — a leftover copy here
+// silently DIES on the next `os i18n extract` run, taking curated translations
+// with it (the sys_audit_log incident). This test turns that silent loss into a
+// red build: an object present in the bundle but not in the ownership list below
+// means either (a) the extract config gained an object — add it here — or (b) a
+// moved/removed object's keys were left behind — remove them from the bundles
+// (or migrate them to the owning package), then keep this list in sync.
+
+import { describe, it, expect } from 'vitest';
+import { enObjects } from './en.objects.generated.js';
+
+// Objects the extract config (scripts/i18n-extract.config.ts) imports —
+// keep the two lists in sync when adding/moving objects.
+const OWNED_OBJECTS = new Set([
+  'sys_webhook',
+]);
+
+describe('objects translation bundle ownership (ADR-0029 D8)', () => {
+  it('the en bundle contains no objects owned by other packages', () => {
+    const strays = Object.keys(enObjects).filter((o) => !OWNED_OBJECTS.has(o));
+    expect(
+      strays,
+      `bundle carries objects this package's extract config does not own: ${strays.join(', ')} — ` +
+        'their curated translations would be silently deleted on the next `os i18n extract`. ' +
+        'Remove the dead block from the four locale bundles, or add the object to the extract config + this list.',
+    ).toEqual([]);
+  });
+
+  it('every owned object is present in the bundle (extract config regression)', () => {
+    const missing = [...OWNED_OBJECTS].filter((o) => !(o in enObjects));
+    expect(
+      missing,
+      `objects the extract config should emit are missing from the bundle: ${missing.join(', ')} — was an import dropped from scripts/i18n-extract.config.ts?`,
+    ).toEqual([]);
+  });
+});