fix(audit,messaging): provision system tables at kernel:ready (#2253)

os-zhuang · claude · web-flow · commit 68390c2929a8 · 2026-06-24T06:05:05.000+08:00
sys_activity / sys_inbox_message / sys_notification_receipt (and their
sibling system objects) are lazy-created on first WRITE, so a freshly
provisioned env that READS them first — the home page's recent-activity
feed and the Console inbox/notifications bell — hits SQLite
"no such table". The engine logs that as a `Find operation failed` ERROR
on every load (the UI degrades to empty, but the log is noisy and can
mask real errors).

AuditPlugin and MessagingServicePlugin now call engine.syncObjectSchema()
for their own objects in a kernel:ready hook, creating the tables up
front so a new env is consistent from the start. syncObjectSchema is
idempotent (creates only when the table is absent) and guarded, so it is
a safe no-op when boot-time schema sync already provisioned the tables or
when the engine exposes no on-demand DDL. The messaging hook runs
independently of reliableDelivery (the inbox tables are needed either
way). Adds unit tests in both packages.

Co-authored-by: Claude Opus 4.8 &lt;noreply@anthropic.com&gt;
diff --git a/packages/plugins/plugin-audit/src/audit-plugin.test.ts b/packages/plugins/plugin-audit/src/audit-plugin.test.ts
@@ -0,0 +1,90 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect } from 'vitest';
+import { AuditPlugin } from './audit-plugin.js';
+
+/**
+ * Regression coverage: a freshly provisioned env READS sys_activity (the home
+ * page's recent-activity feed) before anything has WRITTEN to it. The plugin's
+ * objects are otherwise lazy-created on first write, so the read used to hit
+ * SQLite "no such table" — logged by the engine as a `Find operation failed`
+ * ERROR on every load. AuditPlugin now provisions its system tables at
+ * kernel:ready so a new env is consistent from the start.
+ */
+
+/**
+ * A fake engine that models the lazy-table behavior: `find()` throws
+ * "no such table" until `syncObjectSchema()` has created it. No `registerHook`,
+ * so `installAuditWriters()` early-returns and we stay focused on provisioning.
+ */
+function makeFakeEngine() {
+  const tables = new Set<string>();
+  const synced: string[] = [];
+  const engine = {
+    async syncObjectSchema(name: string) {
+      synced.push(name);
+      tables.add(name);
+    },
+    async find(object: string) {
+      if (!tables.has(object)) throw new Error(`no such table: ${object}`);
+      return [] as unknown[];
+    },
+  };
+  return { engine, synced };
+}
+
+function makeCtx(engine: unknown) {
+  const services = new Map<string, unknown>([
+    ['objectql', engine],
+    ['manifest', { register() {} }],
+  ]);
+  const readyHooks: Array<() => Promise<void> | void> = [];
+  const logger = {
+    info() {}, warn() {}, error() {}, debug() {},
+    child() { return logger; },
+  };
+  const ctx = {
+    logger,
+    getService(name: string) { return services.get(name); },
+    registerService(name: string, svc: unknown) { services.set(name, svc); },
+    hook(event: string, fn: () => Promise<void> | void) {
+      if (event === 'kernel:ready') readyHooks.push(fn);
+    },
+  } as any;
+  return { ctx, fireReady: async () => { for (const fn of readyHooks) await fn(); } };
+}
+
+describe('AuditPlugin — system table provisioning', () => {
+  it('creates sys_audit_log / sys_activity / sys_comment on kernel:ready', async () => {
+    const { engine, synced } = makeFakeEngine();
+    const { ctx, fireReady } = makeCtx(engine);
+
+    const plugin = new AuditPlugin();
+    await plugin.init(ctx);
+    await plugin.start(ctx);
+
+    // Before kernel:ready the table is absent — the read that the activity feed
+    // performs would throw the "no such table" the engine logs as an ERROR.
+    await expect(engine.find('sys_activity')).rejects.toThrow(/no such table/);
+
+    await fireReady();
+
+    expect(synced).toEqual(
+      expect.arrayContaining(['sys_audit_log', 'sys_activity', 'sys_comment']),
+    );
+    // The activity-feed read now degrades to empty instead of throwing.
+    await expect(engine.find('sys_activity')).resolves.toEqual([]);
+  });
+
+  it('skips provisioning gracefully when the engine has no syncObjectSchema', async () => {
+    // An engine/driver without on-demand DDL (e.g. a federated-only kernel)
+    // must not blow up start().
+    const engine = { async find() { return []; } };
+    const { ctx, fireReady } = makeCtx(engine);
+
+    const plugin = new AuditPlugin();
+    await plugin.init(ctx);
+    await plugin.start(ctx);
+    await expect(fireReady()).resolves.toBeUndefined();
+  });
+});
diff --git a/packages/plugins/plugin-audit/src/audit-plugin.ts b/packages/plugins/plugin-audit/src/audit-plugin.ts
@@ -93,6 +93,10 @@ export class AuditPlugin implements Plugin {
         ctx.logger.warn('AuditPlugin: ObjectQL engine not available — audit writers NOT installed');
         return;
       }
+      // Create the physical tables for this plugin's system objects up-front so
+      // a freshly provisioned env is consistent from the start (see
+      // provisionSystemTables).
+      await this.provisionSystemTables(engine, ctx);
       // Resolve the messaging service lazily at hook time so collaboration
       // @mention / assignment notifications go through the ADR-0030 single
       // ingress (emit) instead of writing sys_notification directly. Messaging
@@ -109,4 +113,36 @@ export class AuditPlugin implements Plugin {
       ctx.logger.info('AuditPlugin: audit + activity writers installed');
     });
   }
+
+  /**
+   * Provision the physical tables for this plugin's system objects up-front.
+   *
+   * sys_audit_log / sys_activity / sys_comment are otherwise lazy-created on
+   * first WRITE (the SQL driver issues DDL when the first row is inserted). A
+   * freshly provisioned env that READS one first — the home page's recent-
+   * activity feed queries sys_activity before any mutation has happened — hits
+   * SQLite "no such table", which the engine logs as a `Find operation failed`
+   * ERROR on every load. The UI degrades to an empty feed, but the log is noisy
+   * and can mask real errors. Creating the tables at kernel:ready (once the
+   * engine + registry are ready) makes a new env consistent from the start.
+   *
+   * `syncObjectSchema` is idempotent — the SQL driver only creates a table when
+   * it is absent (and alters to add columns) — so this is safe on every boot,
+   * and a no-op for objects whose table already exists. Per-object failures are
+   * isolated so one bad object can't block the rest.
+   */
+  private async provisionSystemTables(engine: IDataEngine, ctx: PluginContext): Promise<void> {
+    // `syncObjectSchema` lives on the concrete ObjectQL engine, not the
+    // IDataEngine contract; engines/drivers without on-demand DDL (e.g. an
+    // in-memory test double) simply skip provisioning.
+    const sync = (engine as unknown as { syncObjectSchema?: (name: string) => Promise<void> }).syncObjectSchema;
+    if (typeof sync !== 'function') return;
+    for (const obj of [SysAuditLog, SysActivity, SysComment]) {
+      try {
+        await sync.call(engine, obj.name);
+      } catch (err) {
+        ctx.logger.warn(`AuditPlugin: could not provision ${obj.name} storage — ${(err as Error)?.message ?? err}`);
+      }
+    }
+  }
 }
diff --git a/packages/services/service-messaging/src/messaging-service-plugin.test.ts b/packages/services/service-messaging/src/messaging-service-plugin.test.ts
@@ -93,3 +93,59 @@ describe('MessagingServicePlugin', () => {
         expect(messaging.getRegisteredChannels()).toEqual([]);
     });
 });
+
+/**
+ * A ctx that supports `kernel:ready` hooks plus an engine modelling the
+ * lazy-table behavior: `find()` throws "no such table" until
+ * `syncObjectSchema()` has created it. Mirrors the audit-plugin coverage.
+ */
+function provisionCtx() {
+    const tables = new Set<string>();
+    const synced: string[] = [];
+    const engine = {
+        async syncObjectSchema(name: string) { synced.push(name); tables.add(name); },
+        async find(object: string) {
+            if (!tables.has(object)) throw new Error(`no such table: ${object}`);
+            return [] as unknown[];
+        },
+        async insert() { return {}; },
+        async findOne() { return null; },
+        async update() { return {}; },
+        async delete() { return {}; },
+    };
+    const services = new Map<string, unknown>([
+        ['data', engine],
+        ['manifest', { register() {} }],
+    ]);
+    const readyHooks: Array<() => Promise<void> | void> = [];
+    const logger = { info() {}, warn() {}, error() {}, debug() {}, child() { return logger; } };
+    const ctx = {
+        logger,
+        getService(name: string) { return services.get(name); },
+        registerService(name: string, svc: unknown) { services.set(name, svc); },
+        hook(event: string, fn: () => Promise<void> | void) {
+            if (event === 'kernel:ready') readyHooks.push(fn);
+        },
+    } as any;
+    return { ctx, engine, synced, fireReady: async () => { for (const fn of readyHooks) await fn(); } };
+}
+
+describe('MessagingServicePlugin — system table provisioning', () => {
+    it('creates the inbox + receipt tables on kernel:ready', async () => {
+        const { ctx, engine, synced, fireReady } = provisionCtx();
+        // reliableDelivery/retention off so only the provisioning hook runs.
+        await new MessagingServicePlugin({ reliableDelivery: false, retentionDays: 0 }).init(ctx);
+
+        // Before kernel:ready the inbox read throws the "no such table" the
+        // engine logs as `Find operation failed`.
+        await expect(engine.find('sys_inbox_message')).rejects.toThrow(/no such table/);
+
+        await fireReady();
+
+        expect(synced).toEqual(
+            expect.arrayContaining(['sys_inbox_message', 'sys_notification_receipt']),
+        );
+        await expect(engine.find('sys_inbox_message')).resolves.toEqual([]);
+        await expect(engine.find('sys_notification_receipt')).resolves.toEqual([]);
+    });
+});
diff --git a/packages/services/service-messaging/src/messaging-service-plugin.ts b/packages/services/service-messaging/src/messaging-service-plugin.ts
@@ -175,6 +175,22 @@ export class MessagingServicePlugin implements Plugin {
             ],
         });
 
+        // Provision the physical tables for this service's system objects
+        // up-front, once the engine is ready. The inbox channel materializes
+        // sys_inbox_message + sys_notification_receipt rows on first delivery,
+        // so the tables are otherwise lazy-created on first WRITE — a freshly
+        // provisioned env that READS the inbox / notifications before any
+        // message has been delivered hits "no such table", logged as a
+        // `Find operation failed` ERROR on every page load. Runs independently
+        // of `reliableDelivery` (the inbox tables are needed either way) and is
+        // idempotent. See {@link provisionSystemTables}.
+        if (typeof ctx.hook === 'function') {
+            ctx.hook('kernel:ready', async () => {
+                const engine = getData();
+                if (engine) await this.provisionSystemTables(engine, ctx);
+            });
+        }
+
         // Email channel (ADR-0030 P3): register when an `email` service is
         // present. Resolved at kernel:ready so init order with the email plugin
         // doesn't matter; absent email ⇒ no channel (a notify(channels:['email'])
@@ -278,6 +294,41 @@ export class MessagingServicePlugin implements Plugin {
         );
     }
 
+    /**
+     * Provision the physical tables for this service's system objects up-front.
+     *
+     * These objects are lazy-created on first WRITE (the SQL driver issues DDL
+     * when the first row is inserted), so an env that READS them first — the
+     * Console bell / inbox queries sys_inbox_message + sys_notification_receipt
+     * before any notification has been delivered — hits "no such table", which
+     * the engine logs as a `Find operation failed` ERROR on every page load.
+     * Creating the tables at kernel:ready makes a new env consistent from the
+     * start. Idempotent (the driver only creates a table when absent), so it is
+     * safe on every boot; per-object failures are isolated.
+     */
+    private async provisionSystemTables(engine: IDataEngine, ctx: PluginContext): Promise<void> {
+        // `syncObjectSchema` lives on the concrete ObjectQL engine, not the
+        // IDataEngine contract; engines without on-demand DDL skip provisioning.
+        const sync = (engine as unknown as { syncObjectSchema?: (name: string) => Promise<void> }).syncObjectSchema;
+        if (typeof sync !== 'function') return;
+        const objects = [
+            InboxMessage,
+            NotificationReceipt,
+            NotificationDelivery,
+            NotificationPreference,
+            NotificationSubscription,
+            NotificationTemplate,
+            HttpDelivery,
+        ];
+        for (const obj of objects) {
+            try {
+                await sync.call(engine, (obj as { name: string }).name);
+            } catch (err) {
+                ctx.logger.warn(`[messaging] could not provision ${(obj as { name: string }).name} storage — ${(err as Error)?.message ?? err}`);
+            }
+        }
+    }
+
     /** Stop the dispatcher loop + retention sweep on shutdown. */
     async stop(): Promise<void> {
         await this.dispatcher?.stop();
