@objectstack/metadata 17.2.0 → 17.4.0

package/dist/migrations/index.cjs

@@ -27,23 +27,37 @@ __export(migrations_exports, {
 });
 module.exports = __toCommonJS(migrations_exports);
 
+// src/migrations/driver-exec.ts
+function resolveDriverExec(driver) {
+  const candidate = driver;
+  if (!candidate) return void 0;
+  if (typeof candidate.execute === "function") {
+    return (sql, bindings) => candidate.execute(sql, bindings ? [...bindings] : []);
+  }
+  if (typeof candidate.raw === "function") {
+    return (sql, bindings) => candidate.raw(sql, bindings ? [...bindings] : []);
+  }
+  return void 0;
+}
+function driverExecRefusal(helper) {
+  return `${helper}: driver must expose an .execute(sql, bindings?) or .raw(sql, bindings?) method. SqlDriver (better-sqlite3/knex) exposes .execute(), as does its SqliteWasmDriver subclass; cloud-side TursoDriver also conforms.`;
+}
+
 // src/migrations/migrate-env-id-to-project-id.ts
 var AFFECTED_TABLES = [
   "sys_metadata",
   "sys_metadata_history"
 ];
 async function migrateEnvIdToProjectId(driver) {
-  const driverAny = driver;
-  if (typeof driverAny.raw !== "function") {
-    throw new Error(
-      "migrateEnvIdToProjectId: driver must expose a .raw(sql, bindings?) method. SqlDriver (better-sqlite3/knex) supports this; cloud-side TursoDriver also conforms."
-    );
+  const exec = resolveDriverExec(driver);
+  if (!exec) {
+    throw new Error(driverExecRefusal("migrateEnvIdToProjectId"));
   }
   const results = [];
   for (const table of AFFECTED_TABLES) {
     try {
-      const hasColumn = await _columnExists(driverAny, table, "env_id");
-      const alreadyMigrated = await _columnExists(driverAny, table, "project_id");
+      const hasColumn = await _columnExists(exec, table, "env_id");
+      const alreadyMigrated = await _columnExists(exec, table, "project_id");
       if (alreadyMigrated && !hasColumn) {
         results.push({ table, status: "already_done" });
         continue;
@@ -52,7 +66,7 @@ async function migrateEnvIdToProjectId(driver) {
         results.push({ table, status: "table_missing" });
         continue;
       }
-      await driverAny.raw(`ALTER TABLE "${table}" RENAME COLUMN env_id TO project_id`);
+      await exec(`ALTER TABLE "${table}" RENAME COLUMN env_id TO project_id`);
       results.push({ table, status: "renamed" });
     } catch (err) {
       results.push({ table, status: "error", error: err?.message ?? String(err) });
@@ -60,14 +74,14 @@ async function migrateEnvIdToProjectId(driver) {
   }
   return results;
 }
-async function _columnExists(driver, table, column) {
+async function _columnExists(exec, table, column) {
   try {
-    const rows = await driver.raw(`PRAGMA table_info("${table}")`);
+    const rows = await exec(`PRAGMA table_info("${table}")`);
     if (Array.isArray(rows) && rows.length > 0) {
       const list2 = Array.isArray(rows[0]) ? rows[0] : rows;
       return list2.some((r) => r?.name === column);
     }
-    const result = await driver.raw(
+    const result = await exec(
       `SELECT column_name FROM information_schema.columns WHERE table_name = ? AND column_name = ?`,
       [table, column]
     );
@@ -79,22 +93,29 @@ async function _columnExists(driver, table, column) {
 }
 
 // src/migrations/migrate-project-id-to-environment-id.ts
-var AFFECTED_TABLES2 = [
-  "sys_metadata",
-  "sys_metadata_history"
-];
+var import_metadata_core = require("@objectstack/metadata-core");
+var SOURCE_COLUMN = "project_id";
+var TARGET_COLUMN = "environment_id";
+var CANDIDATE_OBJECTS = [import_metadata_core.SysMetadataObject, import_metadata_core.SysMetadataHistoryObject];
+function declaresColumn(object, column) {
+  return Object.prototype.hasOwnProperty.call(object.fields ?? {}, column);
+}
+var CANDIDATE_TABLES = CANDIDATE_OBJECTS.map((o) => o.name);
+var AFFECTED_TABLES2 = CANDIDATE_OBJECTS.filter((o) => declaresColumn(o, TARGET_COLUMN)).map((o) => o.name);
 async function migrateProjectIdToEnvironmentId(driver) {
-  const driverAny = driver;
-  if (typeof driverAny.raw !== "function") {
-    throw new Error(
-      "migrateProjectIdToEnvironmentId: driver must expose a .raw(sql, bindings?) method. migrateProjectIdToEnvironmentId: driver must expose a .raw(sql, bindings?) method. SqlDriver (better-sqlite3/knex) supports this; cloud-side TursoDriver also conforms."
-    );
+  const exec = resolveDriverExec(driver);
+  if (!exec) {
+    throw new Error(driverExecRefusal("migrateProjectIdToEnvironmentId"));
   }
   const results = [];
-  for (const table of AFFECTED_TABLES2) {
+  for (const table of CANDIDATE_TABLES) {
+    if (!AFFECTED_TABLES2.includes(table)) {
+      results.push({ table, status: "skipped_not_declared" });
+      continue;
+    }
     try {
-      const hasColumn = await _columnExists2(driverAny, table, "project_id");
-      const alreadyMigrated = await _columnExists2(driverAny, table, "environment_id");
+      const hasColumn = await _columnExists2(exec, table, SOURCE_COLUMN);
+      const alreadyMigrated = await _columnExists2(exec, table, TARGET_COLUMN);
       if (alreadyMigrated && !hasColumn) {
         results.push({ table, status: "already_done" });
         continue;
@@ -103,8 +124,8 @@ async function migrateProjectIdToEnvironmentId(driver) {
         results.push({ table, status: "table_missing" });
         continue;
       }
-      await driverAny.raw(
-        `ALTER TABLE "${table}" RENAME COLUMN project_id TO environment_id`
+      await exec(
+        `ALTER TABLE "${table}" RENAME COLUMN ${SOURCE_COLUMN} TO ${TARGET_COLUMN}`
       );
       results.push({ table, status: "renamed" });
     } catch (err) {
@@ -113,14 +134,14 @@ async function migrateProjectIdToEnvironmentId(driver) {
   }
   return results;
 }
-async function _columnExists2(driver, table, column) {
+async function _columnExists2(exec, table, column) {
   try {
-    const rows = await driver.raw(`PRAGMA table_info("${table}")`);
+    const rows = await exec(`PRAGMA table_info("${table}")`);
     if (Array.isArray(rows) && rows.length > 0) {
       const list2 = Array.isArray(rows[0]) ? rows[0] : rows;
       return list2.some((r) => r?.name === column);
     }
-    const result = await driver.raw(
+    const result = await exec(
       `SELECT column_name FROM information_schema.columns WHERE table_name = ? AND column_name = ?`,
       [table, column]
     );
@@ -140,14 +161,14 @@ var DEPRECATED_TABLES = [
   "sys_tool"
 ];
 async function dropProjectionTables(driver) {
-  const driverAny = driver;
-  if (typeof driverAny.raw !== "function") {
-    throw new Error("dropProjectionTables: driver must expose a raw(sql) method");
+  const exec = resolveDriverExec(driver);
+  if (!exec) {
+    throw new Error(driverExecRefusal("dropProjectionTables"));
   }
   const results = [];
   for (const table of DEPRECATED_TABLES) {
     try {
-      await driverAny.raw(`DROP TABLE IF EXISTS ${table}`);
+      await exec(`DROP TABLE IF EXISTS ${table}`);
       results.push({ table, status: "dropped" });
     } catch (error) {
       results.push({
@@ -161,9 +182,11 @@ async function dropProjectionTables(driver) {
 }
 
 // src/migrations/migrate-sys-notification-to-event.ts
+var import_system = require("@objectstack/spec/system");
 var EVENT_OBJECT = "sys_notification";
 var INBOX_OBJECT = "sys_inbox_message";
 var RECEIPT_OBJECT = "sys_notification_receipt";
+var HISTORICAL_IMPORT = { context: { preserveAudit: true } };
 var LEGACY_COLUMNS = [
   "recipient_id",
   "type",
@@ -175,57 +198,70 @@ var LEGACY_COLUMNS = [
   "read_at"
 ];
 async function migrateSysNotificationToEvent(opts) {
-  const driver = opts.driver;
-  const { data } = opts;
   const now = opts.now ?? (() => (/* @__PURE__ */ new Date()).toISOString());
-  if (typeof driver?.raw !== "function") {
+  const outcome = await runNotificationEventMigration(opts, now);
+  const receipt = await recordNotificationEventReceipt(opts.data, outcome.status, now());
+  return { ...outcome, receipt };
+}
+async function runNotificationEventMigration(opts, now) {
+  const { data } = opts;
+  const exec = resolveDriverExec(opts.driver);
+  if (!exec) {
     return {
       status: "error",
       migrated: 0,
-      error: "migrateSysNotificationToEvent: driver must expose a .raw(sql, bindings?) method."
+      error: driverExecRefusal("migrateSysNotificationToEvent")
     };
   }
-  if (!await columnExists(driver, EVENT_OBJECT, "recipient_id")) {
+  if (!await columnExists(exec, EVENT_OBJECT, "recipient_id")) {
     return { status: "not_applicable", migrated: 0 };
   }
   const presentLegacy = [];
   for (const col of LEGACY_COLUMNS) {
-    if (await columnExists(driver, EVENT_OBJECT, col)) presentLegacy.push(col);
+    if (await columnExists(exec, EVENT_OBJECT, col)) presentLegacy.push(col);
   }
   let migrated = 0;
   try {
-    const rows = await selectLegacyRows(driver);
+    const rows = await selectLegacyRows(exec);
     if (rows.length === 0) return { status: "already_done", migrated: 0 };
     for (const row of rows) {
       const id = String(row.id);
       const recipientId = row.recipient_id != null ? String(row.recipient_id) : null;
       if (!recipientId) continue;
       const orgId = row.organization_id != null ? String(row.organization_id) : null;
-      const createdAt = row.created_at != null ? String(row.created_at) : now();
+      const createdAt = row.created_at != null ? canonicalTimestampText(row.created_at) : now();
       const title = row.title != null ? String(row.title) : row.type != null ? String(row.type) : "Notification";
       const isRead = row.is_read === true || row.is_read === 1 || row.is_read === "1";
       const eventTopic = row.type != null && String(row.type).length > 0 ? String(row.type) : "legacy";
-      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(RECEIPT_OBJECT, {
-        notification_id: id,
-        delivery_id: null,
-        user_id: recipientId,
-        channel: "inbox",
-        state: isRead ? "read" : "delivered",
-        at: isRead && row.read_at != null ? String(row.read_at) : createdAt,
-        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
+      );
+      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
+      );
       await data.update(
         EVENT_OBJECT,
         {
@@ -243,7 +279,7 @@ async function migrateSysNotificationToEvent(opts) {
       );
       if (presentLegacy.length > 0) {
         const setClause = presentLegacy.map((c) => `"${c}" = NULL`).join(", ");
-        await driver.raw(`UPDATE "${EVENT_OBJECT}" SET ${setClause} WHERE id = ?`, [id]);
+        await exec(`UPDATE "${EVENT_OBJECT}" SET ${setClause} WHERE id = ?`, [id]);
       }
       migrated += 1;
     }
@@ -252,8 +288,80 @@ async function migrateSysNotificationToEvent(opts) {
     return { status: "error", migrated, error: err?.message ?? String(err) };
   }
 }
-async function selectLegacyRows(driver) {
-  const result = await driver.raw(
+var LEDGER_CLAIM = {
+  migrated: { claims: true, appliesBackfill: true },
+  already_done: { claims: true, appliesBackfill: false },
+  not_applicable: { claims: true, appliesBackfill: false },
+  // An `error` run writes NO ledger claim at all — it does not know what it
+  // did, so it may not say.
+  error: { claims: false, appliesBackfill: false }
+};
+var LEDGER_METHODS = ["getObject", "find", "insert", "update"];
+function resolveMigrationLedger(data) {
+  const candidate = data;
+  for (const method of LEDGER_METHODS) {
+    if (typeof candidate[method] !== "function") return void 0;
+  }
+  return candidate;
+}
+function buildNotificationEventClaim(status, now, exists) {
+  const claim = LEDGER_CLAIM[status];
+  const row = {
+    id: import_system.NOTIFICATION_EVENT_MIGRATION_ID,
+    last_run_at: now,
+    blocking: 0,
+    details: JSON.stringify({ outcome: status }),
+    updated_at: now
+  };
+  if (claim.appliesBackfill) row.applied_at = now;
+  if (!exists) {
+    row.applied_at = claim.appliesBackfill ? now : null;
+    row.verified_at = null;
+    row.created_at = now;
+  }
+  return row;
+}
+async function recordNotificationEventReceipt(data, status, now) {
+  if (!LEDGER_CLAIM[status].claims) return { outcome: "not-claimed" };
+  const ledger = resolveMigrationLedger(data);
+  if (!ledger) {
+    return {
+      outcome: "no-ledger",
+      reason: `the \`data\` engine carries no object registry (${LEDGER_METHODS.join("/")}), so ${import_system.DATA_MIGRATION_FLAG_OBJECT} cannot be reached from here`
+    };
+  }
+  try {
+    if (!ledger.getObject(import_system.DATA_MIGRATION_FLAG_OBJECT)) {
+      return {
+        outcome: "no-ledger",
+        reason: `${import_system.DATA_MIGRATION_FLAG_OBJECT} is not registered on this kernel \u2014 compose PlatformObjectsPlugin, which carries the deployment ledger`
+      };
+    }
+    const context = { isSystem: true };
+    const rows = await ledger.find(
+      import_system.DATA_MIGRATION_FLAG_OBJECT,
+      { where: { id: import_system.NOTIFICATION_EVENT_MIGRATION_ID }, limit: 1 },
+      { context }
+    );
+    const exists = rows?.[0]?.id === import_system.NOTIFICATION_EVENT_MIGRATION_ID;
+    const row = buildNotificationEventClaim(status, now, exists);
+    if (exists) {
+      await ledger.update(import_system.DATA_MIGRATION_FLAG_OBJECT, row, { context });
+      return { outcome: "updated" };
+    }
+    await ledger.insert(import_system.DATA_MIGRATION_FLAG_OBJECT, row, { context });
+    return { outcome: "inserted" };
+  } catch (err) {
+    return { outcome: "failed", reason: err?.message ?? String(err) };
+  }
+}
+function canonicalTimestampText(value) {
+  if (typeof value === "string") return value;
+  if (value instanceof Date) return value.toISOString();
+  return String(value);
+}
+async function selectLegacyRows(exec) {
+  const result = await exec(
     `SELECT id, recipient_id, type, title, body, url, actor_name, is_read, read_at, created_at, organization_id FROM "${EVENT_OBJECT}" WHERE recipient_id IS NOT NULL`
   );
   if (Array.isArray(result) && result.length > 0 && Array.isArray(result[0])) {
@@ -261,9 +369,9 @@ async function selectLegacyRows(driver) {
   }
   return Array.isArray(result) ? result : [];
 }
-async function columnExists(driver, table, column) {
+async function columnExists(exec, table, column) {
   try {
-    const rows = await driver.raw(`PRAGMA table_info("${table}")`);
+    const rows = await exec(`PRAGMA table_info("${table}")`);
     const list = Array.isArray(rows) ? Array.isArray(rows[0]) ? rows[0] : rows : [];
     if (list.length > 0 && list.some((r) => r?.name != null)) {
       return list.some((r) => r?.name === column);
@@ -271,7 +379,7 @@ async function columnExists(driver, table, column) {
   } catch {
   }
   try {
-    const result = await driver.raw(
+    const result = await exec(
       `SELECT column_name FROM information_schema.columns WHERE table_name = ? AND column_name = ?`,
       [table, column]
     );

package/dist/migrations/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/migrations/index.ts","../../src/migrations/migrate-env-id-to-project-id.ts","../../src/migrations/migrate-project-id-to-environment-id.ts","../../src/migrations/drop-projection-tables.ts","../../src/migrations/migrate-sys-notification-to-event.ts"],"sourcesContent":["// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * @objectstack/metadata/migrations\n *\n * One-off database migrations for the metadata storage layer.\n */\n\nexport { migrateEnvIdToProjectId, type MigrationResult } from './migrate-env-id-to-project-id.js';\nexport {\n    migrateProjectIdToEnvironmentId,\n    type ProjectIdToEnvironmentIdResult,\n} from './migrate-project-id-to-environment-id.js';\nexport { dropProjectionTables, type DropProjectionResult } from './drop-projection-tables.js';\n\n/**\n * ⚰️ TOMBSTONE — `addSysMetadataOverlayIndex` / `add-sys-metadata-overlay-index.ts`\n * was REMOVED in #6771. Do not reintroduce a producer for\n * `idx_sys_metadata_overlay_active` in this package.\n *\n * It was the second producer of that ONE index name, and it still spelled the\n * PRE-ADR-0048 key `(type, name, organization_id, environment_id, scope)` —\n * `environment_id` is retired (always NULL on new rows, and SQL UNIQUE treats\n * NULLs as DISTINCT, so the index constrained nothing) and `scope` is not in\n * the current discriminator. Because both producers used `IF NOT EXISTS`,\n * whichever ran first claimed the name and the other silently no-opped.\n *\n * Measured on real SQLite before removal (#6771):\n *  - on a normal boot the DECLARED index (metadata-core's\n *    `sys-metadata.object.ts`, materialized by `SqlDriver.syncDeclaredIndexes`)\n *    already holds the name with the CURRENT key\n *    `(type, name, organization_id, package_id)`, so this function was a no-op\n *    that nevertheless reported `status: 'created'`;\n *  - in the only window where it was NOT a no-op (table present, declared\n *    indexes not yet materialized) it installed the RETIRED key, and\n *    `syncDeclaredIndexes` — which skips by name — then never repaired it.\n * So it could only ever do nothing or do harm.\n *\n * The two producers that remain are both correctly keyed and deliberate:\n *  - `metadata-protocol`'s `ensureMetadataOverlayIndexes` (runtime, raw SQL):\n *    the partial, NULL-safe form `(type, name, organization_id,\n *    COALESCE(package_id, '')) WHERE state = 'active'`;\n *  - the declaration in `metadata-core`'s `sys-metadata.object.ts`: the\n *    coarser unrestricted UNIQUE that a driver without that runtime migration\n *    gets, as that file's own comment states.\n */\n\n\nexport {\n    migrateSysNotificationToEvent,\n    type SysNotificationMigrationResult,\n    type SysNotificationMigrationOptions,\n} from './migrate-sys-notification-to-event.js';\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * Migration: env_id → project_id\n *\n * Renames the `env_id` column to `project_id` on the metadata storage tables:\n *   - sys_metadata\n *   - sys_metadata_history\n *\n * (The per-type projection tables `sys_object` / `sys_view` / `sys_flow` /\n * `sys_agent` / `sys_tool` were removed in 2026-05 along with the projection\n * pipeline — see ADR 0005 addendum. They are intentionally not included.)\n *\n * Safe to run multiple times (idempotent): checks for column existence before\n * attempting to rename. If `project_id` already exists, the step is skipped.\n *\n * Usage:\n *   import { migrateEnvIdToProjectId } from '@objectstack/metadata/migrations';\n *   await migrateEnvIdToProjectId(driver);\n */\n\nimport type { IDataDriver } from '@objectstack/spec/contracts';\n\nconst AFFECTED_TABLES = [\n    'sys_metadata',\n    'sys_metadata_history',\n] as const;\n\nexport interface MigrationResult {\n    table: string;\n    status: 'renamed' | 'already_done' | 'table_missing' | 'error';\n    error?: string;\n}\n\n/**\n * Rename `env_id` → `project_id` on all metadata tables.\n *\n * @param driver  An IDataDriver with access to the target database.\n *                Must expose a raw query method: `driver.raw(sql, bindings?)`.\n * @returns       Per-table migration results.\n */\nexport async function migrateEnvIdToProjectId(driver: IDataDriver): Promise<MigrationResult[]> {\n    const driverAny = driver as any;\n\n    if (typeof driverAny.raw !== 'function') {\n        throw new Error(\n            'migrateEnvIdToProjectId: driver must expose a .raw(sql, bindings?) method. ' +\n            'SqlDriver (better-sqlite3/knex) supports this; cloud-side TursoDriver also conforms.'\n        );\n    }\n\n    const results: MigrationResult[] = [];\n\n    for (const table of AFFECTED_TABLES) {\n        try {\n            // Detect dialect: SQLite uses PRAGMA, others use information_schema.\n            const hasColumn = await _columnExists(driverAny, table, 'env_id');\n            const alreadyMigrated = await _columnExists(driverAny, table, 'project_id');\n\n            if (alreadyMigrated && !hasColumn) {\n                results.push({ table, status: 'already_done' });\n                continue;\n            }\n\n            if (!hasColumn) {\n                // Neither column exists — table might not exist yet.\n                results.push({ table, status: 'table_missing' });\n                continue;\n            }\n\n            // Perform the rename.  SQLite ≥ 3.25.0 supports ALTER TABLE RENAME COLUMN.\n            await driverAny.raw(`ALTER TABLE \"${table}\" RENAME COLUMN env_id TO project_id`);\n\n            results.push({ table, status: 'renamed' });\n        } catch (err: any) {\n            results.push({ table, status: 'error', error: err?.message ?? String(err) });\n        }\n    }\n\n    return results;\n}\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\nasync function _columnExists(driver: any, table: string, column: string): Promise<boolean> {\n    try {\n        // SQLite: PRAGMA table_info returns rows with `name` column.\n        const rows: any[] = await driver.raw(`PRAGMA table_info(\"${table}\")`);\n        if (Array.isArray(rows) && rows.length > 0) {\n            // knex wraps PRAGMA result; handle both `rows` and `rows[0]` shapes.\n            const list: any[] = Array.isArray(rows[0]) ? rows[0] : rows;\n            return list.some((r: any) => r?.name === column);\n        }\n\n        // Fallback for non-SQLite: query information_schema.\n        const result: any[] = await driver.raw(\n            `SELECT column_name FROM information_schema.columns WHERE table_name = ? AND column_name = ?`,\n            [table, column]\n        );\n        const list: any[] = Array.isArray(result[0]) ? result[0] : result;\n        return list.length > 0;\n    } catch {\n        return false;\n    }\n}\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * Migration: project_id → environment_id\n *\n * Renames the `project_id` column to `environment_id` on the metadata\n * storage tables:\n *   - sys_metadata\n *   - sys_metadata_history\n *\n * Forward counterpart of {@link migrateEnvIdToProjectId} (which performed the\n * earlier `env_id → project_id` rename). Together they let an operator walk an\n * old schema all the way forward in two steps:\n *\n *   migrateEnvIdToProjectId(driver);            // env_id     → project_id    (legacy)\n *   migrateProjectIdToEnvironmentId(driver);    // project_id → environment_id (v5)\n *\n * (The per-type projection tables `sys_object` / `sys_view` / `sys_flow` /\n * `sys_agent` / `sys_tool` were removed in 2026-05 along with the projection\n * pipeline — see ADR 0005 addendum. They are intentionally not included.)\n *\n * Safe to run multiple times (idempotent): checks for column existence before\n * attempting to rename. If `environment_id` already exists, the step is\n * skipped.\n *\n * Usage:\n *   import { migrateProjectIdToEnvironmentId } from '@objectstack/metadata/migrations';\n *   await migrateProjectIdToEnvironmentId(driver);\n */\n\nimport type { IDataDriver } from '@objectstack/spec/contracts';\n\nconst AFFECTED_TABLES = [\n    'sys_metadata',\n    'sys_metadata_history',\n] as const;\n\nexport interface ProjectIdToEnvironmentIdResult {\n    table: string;\n    status: 'renamed' | 'already_done' | 'table_missing' | 'error';\n    error?: string;\n}\n\n/**\n * Rename `project_id` → `environment_id` on all metadata tables.\n *\n * @param driver  An IDataDriver with access to the target database.\n *                Must expose a raw query method: `driver.raw(sql, bindings?)`.\n * @returns       Per-table migration results.\n */\nexport async function migrateProjectIdToEnvironmentId(\n    driver: IDataDriver,\n): Promise<ProjectIdToEnvironmentIdResult[]> {\n    const driverAny = driver as any;\n\n    if (typeof driverAny.raw !== 'function') {\n        throw new Error(\n            'migrateProjectIdToEnvironmentId: driver must expose a .raw(sql, bindings?) method. ' +\n            'migrateProjectIdToEnvironmentId: driver must expose a .raw(sql, bindings?) method. ' +\n            'SqlDriver (better-sqlite3/knex) supports this; cloud-side TursoDriver also conforms.'\n        );\n    }\n\n    const results: ProjectIdToEnvironmentIdResult[] = [];\n\n    for (const table of AFFECTED_TABLES) {\n        try {\n            const hasColumn = await _columnExists(driverAny, table, 'project_id');\n            const alreadyMigrated = await _columnExists(driverAny, table, 'environment_id');\n\n            if (alreadyMigrated && !hasColumn) {\n                results.push({ table, status: 'already_done' });\n                continue;\n            }\n\n            if (!hasColumn) {\n                results.push({ table, status: 'table_missing' });\n                continue;\n            }\n\n            await driverAny.raw(\n                `ALTER TABLE \"${table}\" RENAME COLUMN project_id TO environment_id`,\n            );\n\n            results.push({ table, status: 'renamed' });\n        } catch (err: any) {\n            results.push({ table, status: 'error', error: err?.message ?? String(err) });\n        }\n    }\n\n    return results;\n}\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\nasync function _columnExists(driver: any, table: string, column: string): Promise<boolean> {\n    try {\n        const rows: any[] = await driver.raw(`PRAGMA table_info(\"${table}\")`);\n        if (Array.isArray(rows) && rows.length > 0) {\n            const list: any[] = Array.isArray(rows[0]) ? rows[0] : rows;\n            return list.some((r: any) => r?.name === column);\n        }\n\n        const result: any[] = await driver.raw(\n            `SELECT column_name FROM information_schema.columns WHERE table_name = ? AND column_name = ?`,\n            [table, column],\n        );\n        const list: any[] = Array.isArray(result[0]) ? result[0] : result;\n        return list.length > 0;\n    } catch {\n        return false;\n    }\n}\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * Migration: drop deprecated metadata projection tables.\n *\n * In 2026-05 the per-type projection tables (`sys_object` / `sys_view` /\n * `sys_flow` / `sys_agent` / `sys_tool`) and the corresponding\n * `MetadataProjector` were removed (see ADR 0005 addendum). All metadata\n * now lives as JSON inside `sys_metadata` — these projection tables are\n * dead weight on any existing database.\n *\n * This migration drops them if present. It is idempotent and safe to run\n * on databases that never had them (the `DROP TABLE IF EXISTS` is a no-op).\n *\n * Usage:\n *   import { dropProjectionTables } from '@objectstack/metadata/migrations';\n *   await dropProjectionTables(driver);\n */\n\nimport type { IDataDriver } from '@objectstack/spec/contracts';\n\nconst DEPRECATED_TABLES = [\n    'sys_object',\n    'sys_view',\n    'sys_flow',\n    'sys_agent',\n    'sys_tool',\n] as const;\n\nexport interface DropProjectionResult {\n    table: string;\n    status: 'dropped' | 'not_present' | 'error';\n    error?: string;\n}\n\n/**\n * Drop the deprecated per-type metadata projection tables.\n *\n * @param driver  An `IDataDriver` with `driver.raw(sql, bindings?)` access.\n * @returns       Per-table results.\n */\nexport async function dropProjectionTables(driver: IDataDriver): Promise<DropProjectionResult[]> {\n    const driverAny = driver as any;\n    if (typeof driverAny.raw !== 'function') {\n        throw new Error('dropProjectionTables: driver must expose a raw(sql) method');\n    }\n\n    const results: DropProjectionResult[] = [];\n    for (const table of DEPRECATED_TABLES) {\n        try {\n            await driverAny.raw(`DROP TABLE IF EXISTS ${table}`);\n            results.push({ table, status: 'dropped' });\n        } catch (error) {\n            results.push({\n                table,\n                status: 'error',\n                error: error instanceof Error ? error.message : String(error),\n            });\n        }\n    }\n    return results;\n}\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * Migration: sys_notification (per-user inbox) → notification event (ADR-0030)\n *\n * ADR-0030 re-models `sys_notification` from a per-user *inbox* into the L2\n * *event* (one row per `emit`). This migration preserves users' existing bell\n * notifications across the cut-over by splitting each legacy row into the new\n * layered model:\n *\n *   legacy sys_notification row (recipient_id, type, title, body, url,\n *       actor_name, is_read, read_at, …)\n *     │\n *     ├─► sys_inbox_message      (L5 in-app materialization, keyed by user)\n *     ├─► sys_notification_receipt (L5 read-state: 'read' if is_read else 'delivered')\n *     └─► the sys_notification row itself is rewritten to the event shape\n *         (topic ← type, payload ← {title,body,url,actor_name}) and its legacy\n *         inbox columns are cleared.\n *\n * Idempotent: it acts only on rows that still carry the legacy shape\n * (`recipient_id IS NOT NULL`); a second run is a no-op. Safe when the legacy\n * columns were never present (a fresh install created directly in the new\n * shape) — it reports `not_applicable`.\n *\n * Usage:\n *   import { migrateSysNotificationToEvent } from '@objectstack/metadata/migrations';\n *   await migrateSysNotificationToEvent({ driver, data });\n *\n * `driver` provides raw access to read legacy columns the re-modeled schema no\n * longer projects and to clear them; `data` (IDataEngine) performs the\n * structured inbox/receipt writes and the event rewrite so ids, JSON fields and\n * tenant stamping are handled uniformly across drivers.\n */\n\nimport type { IDataDriver, IDataEngine } from '@objectstack/spec/contracts';\n\nconst EVENT_OBJECT = 'sys_notification';\nconst INBOX_OBJECT = 'sys_inbox_message';\nconst RECEIPT_OBJECT = 'sys_notification_receipt';\n\n/** Legacy inbox columns cleared once a row is rewritten to the event shape. */\nconst LEGACY_COLUMNS = [\n    'recipient_id',\n    'type',\n    'title',\n    'body',\n    'url',\n    'actor_name',\n    'is_read',\n    'read_at',\n] as const;\n\nexport interface SysNotificationMigrationResult {\n    status: 'migrated' | 'already_done' | 'not_applicable' | 'error';\n    /** Number of legacy rows split into inbox + receipt + event. */\n    migrated: number;\n    error?: string;\n}\n\nexport interface SysNotificationMigrationOptions {\n    driver: IDataDriver;\n    data: IDataEngine;\n    /** Defaults to `() => new Date().toISOString()`. */\n    now?(): string;\n}\n\nexport async function migrateSysNotificationToEvent(\n    opts: SysNotificationMigrationOptions,\n): Promise<SysNotificationMigrationResult> {\n    const driver = opts.driver as any;\n    const { data } = opts;\n    const now = opts.now ?? (() => new Date().toISOString());\n\n    if (typeof driver?.raw !== 'function') {\n        return {\n            status: 'error',\n            migrated: 0,\n            error: 'migrateSysNotificationToEvent: driver must expose a .raw(sql, bindings?) method.',\n        };\n    }\n\n    // No legacy `recipient_id` column → the table never held the inbox shape.\n    if (!(await columnExists(driver, EVENT_OBJECT, 'recipient_id'))) {\n        return { status: 'not_applicable', migrated: 0 };\n    }\n\n    // Only null-out columns that actually exist on this deployment.\n    const presentLegacy: string[] = [];\n    for (const col of LEGACY_COLUMNS) {\n        if (await columnExists(driver, EVENT_OBJECT, col)) presentLegacy.push(col);\n    }\n\n    let migrated = 0;\n    try {\n        const rows = await selectLegacyRows(driver);\n        if (rows.length === 0) return { status: 'already_done', migrated: 0 };\n\n        for (const row of rows) {\n            const id = String(row.id);\n            const recipientId = row.recipient_id != null ? String(row.recipient_id) : null;\n            if (!recipientId) continue; // defensive — guarded by the SELECT filter\n            const orgId = row.organization_id != null ? String(row.organization_id) : null;\n            const createdAt = row.created_at != null ? String(row.created_at) : now();\n            const title = row.title != null ? String(row.title) : (row.type != null ? String(row.type) : 'Notification');\n            const isRead = row.is_read === true || row.is_read === 1 || row.is_read === '1';\n            // One topic for both the inbox row and the rewritten event, so the\n            // materialization and its L2 event never disagree (empty/null legacy\n            // `type` → 'legacy').\n            const eventTopic = row.type != null && String(row.type).length > 0 ? String(row.type) : 'legacy';\n\n            // L5 in-app materialization.\n            await data.insert(INBOX_OBJECT, {\n                user_id: recipientId,\n                notification_id: id,\n                topic: eventTopic,\n                title,\n                body_md: row.body ?? null,\n                severity: 'info',\n                action_url: row.url ?? null,\n                organization_id: orgId,\n                created_at: createdAt,\n            });\n\n            // L5 receipt (read-state spine).\n            await data.insert(RECEIPT_OBJECT, {\n                notification_id: id,\n                delivery_id: null,\n                user_id: recipientId,\n                channel: 'inbox',\n                state: isRead ? 'read' : 'delivered',\n                at: isRead && row.read_at != null ? String(row.read_at) : createdAt,\n                organization_id: orgId,\n                created_at: createdAt,\n            });\n\n            // Rewrite the row itself to the L2 event shape (engine handles JSON).\n            await data.update(\n                EVENT_OBJECT,\n                {\n                    id,\n                    topic: eventTopic,\n                    severity: 'info',\n                    payload: {\n                        title: row.title ?? null,\n                        body: row.body ?? null,\n                        url: row.url ?? null,\n                        actorName: row.actor_name ?? null,\n                    },\n                },\n                { where: { id } },\n            );\n\n            // Clear the legacy inbox columns so the row no longer matches the\n            // migration filter (idempotency) and carries no stale recipient.\n            if (presentLegacy.length > 0) {\n                const setClause = presentLegacy.map((c) => `\"${c}\" = NULL`).join(', ');\n                await driver.raw(`UPDATE \"${EVENT_OBJECT}\" SET ${setClause} WHERE id = ?`, [id]);\n            }\n\n            migrated += 1;\n        }\n\n        return { status: 'migrated', migrated };\n    } catch (err: any) {\n        return { status: 'error', migrated, error: err?.message ?? String(err) };\n    }\n}\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\nasync function selectLegacyRows(driver: any): Promise<any[]> {\n    const result: any[] = await driver.raw(\n        `SELECT id, recipient_id, type, title, body, url, actor_name, is_read, read_at, created_at, organization_id ` +\n            `FROM \"${EVENT_OBJECT}\" WHERE recipient_id IS NOT NULL`,\n    );\n    // knex wraps some results as `[rows]`; normalize both shapes.\n    if (Array.isArray(result) && result.length > 0 && Array.isArray(result[0])) {\n        return result[0];\n    }\n    return Array.isArray(result) ? result : [];\n}\n\nasync function columnExists(driver: any, table: string, column: string): Promise<boolean> {\n    // SQLite path: PRAGMA table_info. On Postgres/others this raises a syntax\n    // error — swallow it *locally* and fall through to information_schema (the\n    // outer-catch version of this would never reach the fallback, making the\n    // migration silently no-op on every non-SQLite DB).\n    try {\n        const rows: any = await driver.raw(`PRAGMA table_info(\"${table}\")`);\n        const list: any[] = Array.isArray(rows)\n            ? (Array.isArray(rows[0]) ? rows[0] : rows)\n            : [];\n        if (list.length > 0 && list.some((r: any) => r?.name != null)) {\n            return list.some((r: any) => r?.name === column);\n        }\n    } catch {\n        /* not SQLite — fall through to information_schema */\n    }\n    // Postgres / others.\n    try {\n        const result: any = await driver.raw(\n            `SELECT column_name FROM information_schema.columns WHERE table_name = ? AND column_name = ?`,\n            [table, column],\n        );\n        const list: any[] = Array.isArray(result)\n            ? (Array.isArray(result[0]) ? result[0] : result)\n            : [];\n        return list.length > 0;\n    } catch {\n        return false;\n    }\n}\n"],"mappings":"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","names":["list","AFFECTED_TABLES","_columnExists","list"]}
+{"version":3,"sources":["../../src/migrations/index.ts","../../src/migrations/driver-exec.ts","../../src/migrations/migrate-env-id-to-project-id.ts","../../src/migrations/migrate-project-id-to-environment-id.ts","../../src/migrations/drop-projection-tables.ts","../../src/migrations/migrate-sys-notification-to-event.ts"],"mappings":"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","names":["list","AFFECTED_TABLES","_columnExists","list"]}

package/dist/migrations/index.d.cts

@@ -27,8 +27,10 @@ interface MigrationResult {
 /**
  * Rename `env_id` → `project_id` on all metadata tables.
  *
- * @param driver  An IDataDriver with access to the target database.
- *                Must expose a raw query method: `driver.raw(sql, bindings?)`.
+ * @param driver  An IDataDriver with access to the target database. Raw SQL is
+ *                issued through the surface `IDataDriver` declares —
+ *                `execute(sql, bindings?)` — falling back to
+ *                `raw(sql, bindings?)`; see `./driver-exec.ts`.
  * @returns       Per-table migration results.
  */
 declare function migrateEnvIdToProjectId(driver: IDataDriver): Promise<MigrationResult[]>;
@@ -36,10 +38,9 @@ declare function migrateEnvIdToProjectId(driver: IDataDriver): Promise<Migration
 /**
  * Migration: project_id → environment_id
  *
- * Renames the `project_id` column to `environment_id` on the metadata
- * storage tables:
- *   - sys_metadata
- *   - sys_metadata_history
+ * Renames the `project_id` column to `environment_id` on the metadata storage
+ * tables — but only on the tables whose CURRENT declaration actually knows
+ * `environment_id`.
  *
  * Forward counterpart of {@link migrateEnvIdToProjectId} (which performed the
  * earlier `env_id → project_id` rename). Together they let an operator walk an
@@ -48,6 +49,35 @@ declare function migrateEnvIdToProjectId(driver: IDataDriver): Promise<Migration
  *   migrateEnvIdToProjectId(driver);            // env_id     → project_id    (legacy)
  *   migrateProjectIdToEnvironmentId(driver);    // project_id → environment_id (v5)
  *
+ * ─────────────────────────────────────────────────────────────────────
+ *  Why the table list is DERIVED and not written out (#13205)
+ *
+ *  This migration is the terminal step of that chain: its target column is
+ *  the CURRENT declared shape, so "should this table be renamed?" is not an
+ *  independent fact — it is `does this object still declare environment_id?`.
+ *  Written out by hand, the two drifted apart: `sys_metadata_history` stayed
+ *  on the list after the branch/project-removal amendment (M1) removed
+ *  `environment_id` from its declaration, so against a database whose
+ *  physical `sys_metadata_history` still carried `project_id` this migration
+ *  renamed it to a column NO declaration knows about — minting exactly the
+ *  orphan column class the metadata drift audit exists to remove.
+ *
+ *  The old guard could not catch it: the loop gates on `project_id` existing
+ *  PHYSICALLY (`_columnExists`), which says nothing about the target column
+ *  being DECLARED. So the list is now computed from the declarations in
+ *  `@objectstack/metadata-core` (already a dependency of this package — no
+ *  new edge), and a candidate that does not declare the target column is
+ *  reported as `skipped_not_declared` rather than dropped silently: an
+ *  operator reading the result sees the table was considered and why nothing
+ *  happened, instead of having to guess whether it was forgotten again.
+ *
+ *  ⚠️ The sibling `migrate-env-id-to-project-id.ts` is deliberately NOT
+ *  changed this way. Its target (`project_id`) is an INTERMEDIATE column that
+ *  no current declaration carries by design — gating it on today's
+ *  declarations would disable the chain's first step entirely. The rule
+ *  "target must be declared" is sound only for the terminal migration.
+ * ─────────────────────────────────────────────────────────────────────
+ *
  * (The per-type projection tables `sys_object` / `sys_view` / `sys_flow` /
  * `sys_agent` / `sys_tool` were removed in 2026-05 along with the projection
  * pipeline — see ADR 0005 addendum. They are intentionally not included.)
@@ -63,15 +93,24 @@ declare function migrateEnvIdToProjectId(driver: IDataDriver): Promise<Migration
 
 interface ProjectIdToEnvironmentIdResult {
     table: string;
-    status: 'renamed' | 'already_done' | 'table_missing' | 'error';
+    /**
+     * `skipped_not_declared` — the table is a known metadata storage table, but
+     * its current declaration has no `environment_id`, so renaming into it
+     * would create a column nothing declares. Nothing was executed.
+     */
+    status: 'renamed' | 'already_done' | 'table_missing' | 'skipped_not_declared' | 'error';
     error?: string;
 }
 /**
- * Rename `project_id` → `environment_id` on all metadata tables.
- *
- * @param driver  An IDataDriver with access to the target database.
- *                Must expose a raw query method: `driver.raw(sql, bindings?)`.
- * @returns       Per-table migration results.
+ * Rename `project_id` → `environment_id` on all metadata tables that still
+ * declare `environment_id`.
+ *
+ * @param driver  An IDataDriver with access to the target database. Raw SQL is
+ *                issued through the surface `IDataDriver` declares —
+ *                `execute(sql, bindings?)` — falling back to
+ *                `raw(sql, bindings?)`; see `./driver-exec.ts`.
+ * @returns       Per-table migration results — one entry per candidate table,
+ *                including the ones skipped for lacking the declared target.
  */
 declare function migrateProjectIdToEnvironmentId(driver: IDataDriver): Promise<ProjectIdToEnvironmentIdResult[]>;
 
@@ -100,7 +139,9 @@ interface DropProjectionResult {
 /**
  * Drop the deprecated per-type metadata projection tables.
  *
- * @param driver  An `IDataDriver` with `driver.raw(sql, bindings?)` access.
+ * @param driver  An `IDataDriver`. Raw SQL is issued through the surface
+ *                `IDataDriver` declares — `execute(sql, bindings?)` — falling
+ *                back to `raw(sql, bindings?)`; see `./driver-exec.ts`.
  * @returns       Per-table results.
  */
 declare function dropProjectionTables(driver: IDataDriver): Promise<DropProjectionResult[]>;
@@ -132,16 +173,57 @@ declare function dropProjectionTables(driver: IDataDriver): Promise<DropProjecti
  *   await migrateSysNotificationToEvent({ driver, data });
  *
  * `driver` provides raw access to read legacy columns the re-modeled schema no
- * longer projects and to clear them; `data` (IDataEngine) performs the
+ * longer projects and to clear them — through the surface `IDataDriver`
+ * declares, `execute(sql, bindings?)`, falling back to `raw(sql, bindings?)`
+ * (see `./driver-exec.ts`); `data` (IDataEngine) performs the
  * structured inbox/receipt writes and the event rewrite so ids, JSON fields and
  * tenant stamping are handled uniformly across drivers.
+ *
+ * A completed run also records itself in the `sys_migration` deployment ledger
+ * under `NOTIFICATION_EVENT_MIGRATION_ID`, per the ruled claim matrix carried
+ * on that constant (#16100) — see "The run receipt" below. That row is a
+ * RECEIPT an operator reads, never a gate.
  */
 
+/**
+ * What one run recorded in the `sys_migration` deployment ledger (#16100).
+ *
+ * This directory reports to its CALLER and to nobody else — no module under
+ * `packages/metadata/src/migrations` takes a logger — so the ledger claim's
+ * own fate is reported the same way the migration's is. That is also the third
+ * legal answer to AGENTS.md's degradation rule: a failure handed to the caller
+ * does not "look normal from the outside", because the caller was told.
+ *
+ *  - `inserted` / `updated` — the claim landed, as a new row or over the row
+ *    that was already there.
+ *  - `not-claimed` — nothing was owed. An `error` run writes no ledger claim
+ *    at all (the ruled matrix), so this is the correct, complete outcome for
+ *    it and never a failure.
+ *  - `no-ledger` — a claim was owed and there is nowhere to put it: the host
+ *    is not an engine that carries the ledger, or `sys_migration` is not
+ *    registered on this kernel. `reason` says which.
+ *  - `failed` — a claim was owed, the write was attempted, and it threw. The
+ *    data migration itself still did what `status` says it did; what is
+ *    missing is the durable record that it ran. `reason` carries the error.
+ */
+interface SysNotificationMigrationReceipt {
+    outcome: 'inserted' | 'updated' | 'not-claimed' | 'no-ledger' | 'failed';
+    /** Why no claim landed — present on `no-ledger` and `failed` only. */
+    reason?: string;
+}
 interface SysNotificationMigrationResult {
     status: 'migrated' | 'already_done' | 'not_applicable' | 'error';
     /** Number of legacy rows split into inbox + receipt + event. */
     migrated: number;
     error?: string;
+    /**
+     * What this run claimed in the `sys_migration` ledger under
+     * {@link NOTIFICATION_EVENT_MIGRATION_ID}. Always present: writing the
+     * receipt is part of what a run DOES, and a caller that cannot tell "the
+     * claim landed" from "the claim was never attempted" is the unanswerable
+     * state the ledger row exists to remove.
+     */
+    receipt: SysNotificationMigrationReceipt;
 }
 interface SysNotificationMigrationOptions {
     driver: IDataDriver;
@@ -151,4 +233,4 @@ interface SysNotificationMigrationOptions {
 }
 declare function migrateSysNotificationToEvent(opts: SysNotificationMigrationOptions): Promise<SysNotificationMigrationResult>;
 
-export { type DropProjectionResult, type MigrationResult, type ProjectIdToEnvironmentIdResult, type SysNotificationMigrationOptions, type SysNotificationMigrationResult, dropProjectionTables, migrateEnvIdToProjectId, migrateProjectIdToEnvironmentId, migrateSysNotificationToEvent };
+export { type DropProjectionResult, type MigrationResult, type ProjectIdToEnvironmentIdResult, type SysNotificationMigrationOptions, type SysNotificationMigrationReceipt, type SysNotificationMigrationResult, dropProjectionTables, migrateEnvIdToProjectId, migrateProjectIdToEnvironmentId, migrateSysNotificationToEvent };