fix(metadata): declare the historical-import channel on the sys_notification migration's two L5 writes (#16834)

* fix(metadata): declare the historical-import channel on the sys_notification migration's two L5 writes

`migrateSysNotificationToEvent` back-dates each materialized
`sys_inbox_message` and `sys_notification_receipt` to the notification's own
`created_at`. Both writes passed no options bag, so they were living on the
audit binder's create-side `record.created_at ?? now` — the laundering #15964
removed on the maintainer ruling of 2026-09-06. Without it the ordinary branch
stamps the migration instant on every migrated row: a user's whole bell
history collapses to "all arrived today".

Both writes now carry `{ context: { preserveAudit: true } }`, the explicit
historical-import channel the same ruling deliberately kept (#3493, what REST
import's `treatAsHistorical` sets). The `data.update` that rewrites the event
row deliberately does NOT carry it — that write really is happening now, and
`sys_stamp_audit_update` never touches `created_at`.

The substantive half is the test. The existing suite drives the migration
through a fake engine double that runs no hooks, so its `created_at`
assertions passed on both sides of #15964 and the defect went unmeasured. A
new case boots a real `ObjectKernel` + `ObjectQLPlugin` + `SqliteWasmDriver`,
so the shipped `sys_stamp_audit_insert` hook actually runs, and it carries two
anti-vacuity controls that fail if the hook is absent. It lives in
`packages/runtime` because `@objectstack/objectql` depends on
`@objectstack/metadata`, so importing it from that package would close a cycle
turbo rejects.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ADLdAs2pVcH17h9tZKWMBg

* test(runtime): assert the surviving source instant predates the migration run

The last case held `runWindowStart` only to keep the binding used. It now
carries the reading the triage seat asked for as a real assertion: the source
`sys_notification` row's `created_at` still predates the run, which is exactly
why a bad run is recoverable by backfill rather than terminal.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ADLdAs2pVcH17h9tZKWMBg

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-musk

.changeset/notification-migration-preserve-audit.md

@@ -0,0 +1,31 @@
+---
+'@objectstack/metadata': patch
+---
+
+fix(metadata): keep the original notification instant when migrating `sys_notification` to the event model (#16312)
+
+`migrateSysNotificationToEvent` materializes each legacy inbox row into a
+`sys_inbox_message` and a `sys_notification_receipt`, back-dating both to the
+notification's own `created_at`. Both writes passed no options bag, so they
+relied on the audit binder's create-side `record.created_at ?? now` — the
+laundering #15964 removed, on the maintainer ruling of 2026-09-06. Without
+that accident, every migrated inbox row and receipt is stamped with the moment
+the migration RAN: a user's whole bell history collapses to "all arrived
+today".
+
+The two writes now declare `{ context: { preserveAudit: true } }`, the explicit
+historical-import channel the same ruling deliberately kept (#3493; it is what
+REST import's `treatAsHistorical` sets). This is not a bypass of audit — it is
+the door audit left open for a historical import. No exported symbol, schema or
+config key moves.
+
+**Release ordering.** `@objectstack/objectql`'s side of #15964 is itself still
+an unreleased changeset, so no published version of this migration has ever
+written the flattened timeline. Releasing the two together keeps it that way.
+
+**If a deployment did run it from a build that has both halves**, the original
+timeline is recoverable rather than lost: the source `sys_notification` rows
+are rewritten in place, never deleted or archived, and `created_at` is not
+among the legacy columns the run clears — so the notification's own instant is
+still on the event row and reachable from both new rows through
+`notification_id`.

packages/metadata/src/migrations/migrate-sys-notification-to-event.test.ts

@@ -67,7 +67,7 @@ interface FakeLedger {
 const LEDGER_OBJECT = 'sys_migration';
 
 function fakeEngine(ledger?: FakeLedger) {
-    const inserts: Array<{ object: string; row: any }> = [];
+    const inserts: Array<{ object: string; row: any; options?: Record<string, unknown> }> = [];
     const updates: Array<{ object: string; data: any }> = [];
     const finds: Array<{ object: string; query: any }> = [];
     const stored = new Map<string, Record<string, unknown>>(
@@ -89,8 +89,8 @@ function fakeEngine(ledger?: FakeLedger) {
                       },
                   }
                 : {}),
-            async insert(object: string, row: any) {
-                inserts.push({ object, row });
+            async insert(object: string, row: any, options?: Record<string, unknown>) {
+                inserts.push({ object, row, options });
                 if (object === LEDGER_OBJECT) {
                     if (ledger?.failWrites) throw new Error(ledger.failWrites);
                     stored.set(String(row.id), { ...row });
@@ -300,6 +300,69 @@ async function underProcessZone<T>(tz: string, body: () => Promise<T> | T): Prom
     }
 }
 
+// ---------------------------------------------------------------------------
+// [#16312] The historical-import channel is DECLARED on the two L5 writes
+// ---------------------------------------------------------------------------
+//
+// ⚠️ Read what this can and cannot say, because the card exists because the
+// difference was missed once already.
+//
+// This double runs NO hooks. It is faithful about DISPATCH — its write verbs
+// route through the producer's own predicates — and silent about the before
+// phase, so it cannot observe whether `sys_stamp_audit_insert` kept or
+// overwrote `created_at`. That is exactly the seam the defect lived in: every
+// assertion in this file about `created_at` passed on BOTH sides of #15964's
+// change, and the suite read `23 passed` while migrated rows were being
+// stamped with the migration instant.
+//
+// ⇒ what follows is a pin on the CALL SHAPE, which is inside what this double
+// can see, and nothing more. The EFFECT — that the real audit hook honours it
+// and the row lands with the notification's own instant — is measured on a real
+// engine, with a real driver, in
+// `packages/runtime/src/notification-migration-audit-preservation.integration.test.ts`.
+// ⛔ Do not read a green here as evidence the timeline is preserved; that is the
+// reading this card was filed to retire.
+// ---------------------------------------------------------------------------
+
+describe('#16312 the two L5 writes declare the historical-import channel', () => {
+    it('inbox and receipt inserts both carry `context.preserveAudit`', async () => {
+        const d = fakeDriver([
+            {
+                id: 'n1', recipient_id: 'u1', type: 'task.assigned', title: 'T',
+                body: 'B', url: '/r/1', actor_name: 'Ada', is_read: 1,
+                read_at: REPORTED_READ_INSTANT, created_at: REPORTED_INSTANT,
+                organization_id: 'org1',
+            },
+        ]);
+        const e = fakeEngine();
+        await migrateSysNotificationToEvent({ driver: d.driver, data: e.engine });
+
+        const inbox = e.inserts.find((i) => i.object === 'sys_inbox_message')!;
+        const receipt = e.inserts.find((i) => i.object === 'sys_notification_receipt')!;
+        expect(inbox.options).toEqual({ context: { preserveAudit: true } });
+        expect(receipt.options).toEqual({ context: { preserveAudit: true } });
+    });
+
+    it('the event rewrite does NOT ask for it — that write really is happening now', async () => {
+        const d = fakeDriver([
+            {
+                id: 'n1', recipient_id: 'u1', type: 'task.assigned', title: 'T',
+                body: null, url: null, actor_name: null, is_read: 0,
+                read_at: null, created_at: REPORTED_INSTANT, organization_id: null,
+            },
+        ]);
+        const e = fakeEngine();
+        await migrateSysNotificationToEvent({ driver: d.driver, data: e.engine });
+
+        // `sys_stamp_audit_update` stamps `updated_at`, never `created_at`, so
+        // the source row keeps its own instant without asking for anything —
+        // and `updated_at = now` is the true fact about this write.
+        const rewrite = e.updates.find((u) => u.object === 'sys_notification');
+        expect(rewrite).toBeDefined();
+        expect(e.updates.filter((u) => u.object === 'sys_notification')).toHaveLength(1);
+    });
+});
+
 describe('#13998 the timestamp spelling written into the new rows', () => {
     it('control — `String(Date)` is NOT the canonical spelling (the input discriminates)', async () => {
         const value = new Date(REPORTED_INSTANT);

packages/metadata/src/migrations/migrate-sys-notification-to-event.ts

@@ -51,6 +51,56 @@ const EVENT_OBJECT = 'sys_notification';
 const INBOX_OBJECT = 'sys_inbox_message';
 const RECEIPT_OBJECT = 'sys_notification_receipt';
 
+/**
+ * The write context the two L5 materializing inserts carry: this is a
+ * HISTORICAL IMPORT, so the row's `created_at` is the notification's own
+ * instant and not the moment this migration ran.
+ *
+ * ## Read the fossil before you move this
+ *
+ * `preserveAudit` is not a bypass of audit — it is the door audit left open
+ * for exactly this case, and it has a ruling behind it:
+ *
+ *  - **#3493** put it there. `sys_stamp_audit_insert` / `sys_stamp_audit_update`
+ *    (`@objectstack/objectql`'s `plugin.ts`) read `session.preserveAudit` and,
+ *    when it is set, keep a supplied `created_at` / `updated_at` / `updated_by`
+ *    instead of overwriting it with the write instant. Its own words: "a
+ *    'historical' import reinstates the ORIGINAL timeline". Opt-in and
+ *    server-set only — `ExecutionContext.preserveAudit` is documented as never
+ *    client-supplied, and REST import reaches it only through the
+ *    `treatAsHistorical` request flag (`packages/rest/src/import-runner.ts`).
+ *  - **#15964** (maintainer ruling 2026-09-06, decision batch #54, option A)
+ *    reaffirmed it while removing the accident this migration was living on.
+ *    `created_at` used to be `record.created_at ?? now` on EVERY insert —
+ *    client-preferred with no flag at all — which laundered a forged
+ *    `created_at` past the static-`readonly` strip on an ordinary
+ *    authenticated POST. The ruling made the ordinary branch stamp `now` and
+ *    kept the `preserveAudit` branch, deliberately: "Under `preserveAudit` the
+ *    preservation is DECLARED, so the same keep is the ruled historical-import
+ *    channel and stays — which is why the fix is this ternary and not a bare
+ *    `= now`."
+ *
+ * ⇒ the fossil says the channel exists FOR this; declaring it is the ruled
+ * remedy, and ⛔ restoring the create-side `??` is not (#16312).
+ *
+ * ## Why the strip does not eat these keys
+ *
+ * The 2026-08-08 ruling narrowed the CREATE-side `readonly` strip's exemption
+ * to `isSystem` alone, so a non-system create asking for `preserveAudit` is
+ * warned that the exemption is UPDATE-only. That does not bite here:
+ * `staticReadonlyInsertSubject` returns `null` for an object whose name starts
+ * with `sys_` or that carries `managedBy` — both target objects are `sys_` and
+ * `sys_notification_receipt` is `managedBy: 'engine-owned'` — so no create-side
+ * static strip runs on them at all and no warning is owed. Pinned, on a real
+ * engine, by `packages/runtime/src/notification-migration-audit-preservation.integration.test.ts`.
+ *
+ * ⛔ NOT carried on the `data.update` that rewrites the event row below. That
+ * write really is happening now, so `updated_at = now` is the true fact;
+ * `sys_stamp_audit_update` never touches `created_at`, which is why the source
+ * row keeps its own.
+ */
+const HISTORICAL_IMPORT = { context: { preserveAudit: true } };
+
 /** Legacy inbox columns cleared once a row is rewritten to the event shape. */
 const LEGACY_COLUMNS = [
     'recipient_id',
@@ -173,29 +223,37 @@ async function runNotificationEventMigration(
             const eventTopic = row.type != null && String(row.type).length > 0 ? String(row.type) : 'legacy';
 
             // L5 in-app materialization.
-            await data.insert(INBOX_OBJECT, {
-                user_id: recipientId,
-                notification_id: id,
-                topic: eventTopic,
-                title,
-                body_md: row.body ?? null,
-                severity: 'info',
-                action_url: row.url ?? null,
-                organization_id: orgId,
-                created_at: createdAt,
-            });
+            await data.insert(
+                INBOX_OBJECT,
+                {
+                    user_id: recipientId,
+                    notification_id: id,
+                    topic: eventTopic,
+                    title,
+                    body_md: row.body ?? null,
+                    severity: 'info',
+                    action_url: row.url ?? null,
+                    organization_id: orgId,
+                    created_at: createdAt,
+                },
+                HISTORICAL_IMPORT,
+            );
 
             // L5 receipt (read-state spine).
-            await data.insert(RECEIPT_OBJECT, {
-                notification_id: id,
-                delivery_id: null,
-                user_id: recipientId,
-                channel: 'inbox',
-                state: isRead ? 'read' : 'delivered',
-                at: isRead && row.read_at != null ? canonicalTimestampText(row.read_at) : createdAt,
-                organization_id: orgId,
-                created_at: createdAt,
-            });
+            await data.insert(
+                RECEIPT_OBJECT,
+                {
+                    notification_id: id,
+                    delivery_id: null,
+                    user_id: recipientId,
+                    channel: 'inbox',
+                    state: isRead ? 'read' : 'delivered',
+                    at: isRead && row.read_at != null ? canonicalTimestampText(row.read_at) : createdAt,
+                    organization_id: orgId,
+                    created_at: createdAt,
+                },
+                HISTORICAL_IMPORT,
+            );
 
             // Rewrite the row itself to the L2 event shape (engine handles JSON).
             await data.update(