@happyvertical/smrt-core 0.40.70 → 0.42.0

package/dist/system/retention.js

@@ -0,0 +1,497 @@
+import { toSafeInteger } from "../utils/safe-integer.js";
+import { detectEngine } from "../schema/ddl/index.js";
+import { pruneChangeFeed } from "../change-feed.js";
+import { createLogger } from "@happyvertical/logger";
+//#region src/system/retention.ts
+/**
+* System-table retention — bounded growth for framework-owned tables (#2375).
+*
+* Several `_smrt_*` tables are append-only by construction and were, until
+* this module, unbounded by default: `_smrt_changes` grew one row per
+* framework save/delete, `_smrt_ai_usage` one row per AI call (persistence is
+* on by default, see `config.ts`), `_smrt_contexts` accumulated rows whose
+* `expires_at` nothing ever enforced, and `_smrt_dispatch` retained completed
+* work until an operator remembered to run `smrt dispatch:cleanup`.
+*
+* This module supplies the missing half:
+*
+* - {@link pruneAiUsage} — the retention API `_smrt_ai_usage` never had.
+* - {@link pruneExpiredContexts} — enforcement for `_smrt_contexts.expires_at`.
+* - {@link runRetentionSweep} — one entry point that applies a documented,
+*   opt-out {@link RetentionPolicy} across every framework-owned table, plus
+*   any task other packages contribute via {@link registerRetentionTask}
+*   (`@happyvertical/smrt-jobs` registers job/job-event cleanup;
+*   `@happyvertical/smrt-users` registers session and token expiry).
+*
+* Scheduling is the caller's: `smrt db:prune` is the cron entry point, and a
+* running `TaskRunner` sweeps on an interval unless configured otherwise.
+*
+* ## Failure policy
+*
+* A sweep is maintenance, not a transaction. One failing task never aborts the
+* rest — the failure is captured on that task's {@link RetentionTaskResult}
+* and the sweep continues. Callers decide what a partial sweep means; the CLI
+* exits non-zero when any task failed.
+*
+* ## Predicate indexes
+*
+* Every predicate below is indexed by the system DDL in `system/schema.ts`
+* (`_smrt_contexts(expires_at)`, `_smrt_ai_usage(tenant_id, created_at)`,
+* `_smrt_dispatch(status, processed_at)` / `(status, updated_at)`) or by the
+* jobs compatibility path in `system/compatibility.ts`
+* (`_smrt_jobs(status, completed_at)`, `_smrt_job_events(created_at)`).
+* A new retention predicate must ship with its index.
+*
+* @see https://github.com/happyvertical/smrt/issues/2375
+* @packageDocumentation
+*/
+var logger = createLogger({ level: "info" });
+/** Milliseconds in a day — the unit every retention policy is expressed in. */
+var MS_PER_DAY = 1440 * 60 * 1e3;
+/**
+* Documented retention defaults.
+*
+* Chosen to be generous relative to every in-tree consumer: change-feed
+* cursors resync automatically past the window, AI usage outlives a monthly
+* billing cycle by two months, and dispatch keeps a full quarter of failures
+* for forensics. Applications that need longer history raise these; those that
+* need none set the table to `false`.
+*/
+var DEFAULT_RETENTION_POLICY = {
+	changes: { maxAgeDays: 30 },
+	aiUsage: { maxAgeDays: 90 },
+	contexts: {},
+	dispatch: {
+		completedOlderThanDays: 30,
+		failedOlderThanDays: 90
+	}
+};
+var RETENTION_TASKS_KEY = Symbol.for("smrt.retention-tasks");
+/**
+* Names {@link builtInTasks} always uses for the four framework-owned tables.
+*
+* Reserved against contributed tasks: `RetentionTaskResult.task` is
+* documented unique within a sweep, and a contributed task sharing one of
+* these names would collide with a built-in result — silently, since nothing
+* else in the sweep loop checks for it — and would also be unreachable
+* through {@link RetentionPolicy.tasks}, which only ever sees the *last*
+* task run under that name, never the built-in one (opting a built-in table
+* out goes through its own dedicated policy field instead).
+*/
+var RESERVED_TASK_NAMES = /* @__PURE__ */ new Set([
+	"changes",
+	"ai-usage",
+	"contexts",
+	"dispatch"
+]);
+/**
+* The task registry, held on `globalThis` rather than in module scope.
+*
+* Contributing packages resolve their own copy of `@happyvertical/smrt-core`
+* whenever a consumer's install is not fully deduped, and the CLI resolves a
+* third. A module-local `Map` would give each of them a private, empty
+* registry — the task would register in one and the sweep would run in
+* another. `ObjectRegistry` is on `globalThis` for the same reason.
+*/
+function registeredTasks() {
+	const root = globalThis;
+	root[RETENTION_TASKS_KEY] ??= /* @__PURE__ */ new Map();
+	return root[RETENTION_TASKS_KEY];
+}
+/**
+* Register a retention task so {@link runRetentionSweep} includes it.
+*
+* Registering a task does not schedule anything — a task only runs when
+* something calls {@link runRetentionSweep}, and the policy can still turn it
+* off by name. Re-registering the same name replaces the previous task, which
+* keeps module re-evaluation (HMR, repeated test imports) idempotent.
+*
+* @throws If `task.name` is empty, or is one of the four built-in table
+*   names (`changes`, `ai-usage`, `contexts`, `dispatch`) — see
+*   {@link RESERVED_TASK_NAMES}.
+*/
+function registerRetentionTask(task) {
+	if (!task.name) throw new Error("registerRetentionTask requires a non-empty task name");
+	if (RESERVED_TASK_NAMES.has(task.name)) throw new Error(`registerRetentionTask: "${task.name}" is a built-in task name (reserved: ${[...RESERVED_TASK_NAMES].join(", ")})`);
+	registeredTasks().set(task.name, task);
+}
+/** Remove a registered retention task. Returns `true` if one was removed. */
+function unregisterRetentionTask(name) {
+	return registeredTasks().delete(name);
+}
+/** Registered retention tasks, ordered by name for deterministic sweeps. */
+function getRetentionTasks() {
+	return [...registeredTasks().values()].sort((left, right) => left.name.localeCompare(right.name));
+}
+/** Drop every registered retention task (test helper). */
+function clearRetentionTasks() {
+	registeredTasks().clear();
+}
+/** Name of the AI usage telemetry table. */
+var AI_USAGE_TABLE = "_smrt_ai_usage";
+/** Name of the remembered-context table. */
+var CONTEXTS_TABLE = "_smrt_contexts";
+/**
+* Prune AI usage telemetry to bound `_smrt_ai_usage` growth.
+*
+* `_smrt_ai_usage` gains one row per AI call and persistence is on by default,
+* so a busy deployment writes millions of rows a year with nothing to remove
+* them. Both bounds may be combined; each is applied independently and the
+* returned count is the total deleted.
+*
+* Predicates are covered by `idx_smrt_ai_usage_tenant_created`
+* (`tenant_id, created_at`) — the same index the subscriptions billing meter
+* needs for its `tenant_id + created_at` range scan.
+*
+* @param db - Database holding the system tables.
+* @param retention - At least one of `maxAgeMs` / `maxRows`.
+* @returns Number of records deleted (or, under `dryRun`, matched).
+*/
+async function pruneAiUsage(db, retention) {
+	const { maxAgeMs, maxRows, dryRun = false } = retention;
+	if (maxAgeMs == null && maxRows == null) throw new Error("pruneAiUsage requires maxAgeMs and/or maxRows");
+	if (maxAgeMs != null && (!Number.isFinite(maxAgeMs) || maxAgeMs < 0)) throw new Error(`pruneAiUsage maxAgeMs must be >= 0, got ${maxAgeMs}`);
+	if (maxRows != null && (!Number.isFinite(maxRows) || maxRows < 0)) throw new Error(`pruneAiUsage maxRows must be >= 0, got ${maxRows}`);
+	const now = retention.now ?? /* @__PURE__ */ new Date();
+	const scope = tenantScopeClause(retention);
+	let pruned = 0;
+	const alreadyCounted = {
+		conditions: [],
+		params: []
+	};
+	if (maxAgeMs != null) {
+		const cutoff = new Date(now.getTime() - maxAgeMs).toISOString();
+		pruned += await deleteFrom(db, AI_USAGE_TABLE, [...scope.conditions, "created_at < ?"], [...scope.params, cutoff], dryRun);
+		alreadyCounted.conditions.push("created_at >= ?");
+		alreadyCounted.params.push(cutoff);
+	}
+	if (maxRows != null) {
+		const keep = Math.floor(maxRows);
+		if (keep === 0) pruned += await deleteFrom(db, AI_USAGE_TABLE, [...scope.conditions, ...alreadyCounted.conditions], [...scope.params, ...alreadyCounted.params], dryRun);
+		else {
+			const cutoff = (await selectOne(db, `SELECT created_at FROM ${AI_USAGE_TABLE}
+         ${whereClause(scope.conditions)}
+         ORDER BY created_at DESC
+         LIMIT 1 OFFSET ${keep - 1}`, scope.params))?.created_at;
+			if (cutoff != null) pruned += await deleteFrom(db, AI_USAGE_TABLE, [
+				...scope.conditions,
+				"created_at < ?",
+				...alreadyCounted.conditions
+			], [
+				...scope.params,
+				cutoff,
+				...alreadyCounted.params
+			], dryRun);
+		}
+	}
+	return { pruned };
+}
+/**
+* Delete context entries whose `expires_at` has passed.
+*
+* `remember({ expiresAt })` has always stored the expiry and never acted on
+* it. Enforcement is deliberately prune-side only: `recall()`/`recallAll()`
+* keep their documented "expiry is not applied at read time" contract, so this
+* bounds storage without changing read semantics for existing callers.
+* (`LearningMemory` filters expired rows itself.)
+*
+* Rows with a `NULL` `expires_at` never expire and are never touched.
+* The predicate is covered by `idx_smrt_contexts_expires_at`.
+*
+* @param db - Database holding the system tables.
+* @param options.now - Clock for the expiry comparison (default: now).
+* @param options.dryRun - Count matching rows without deleting them.
+* @returns Number of expired entries deleted (or, under `dryRun`, matched).
+*/
+async function pruneExpiredContexts(db, options = {}) {
+	return { pruned: await deleteFrom(db, CONTEXTS_TABLE, ["expires_at IS NOT NULL", "expires_at < ?"], [(options.now ?? /* @__PURE__ */ new Date()).toISOString()], options.dryRun ?? false) };
+}
+/**
+* Apply a {@link RetentionPolicy} across every framework-owned table.
+*
+* Built-in tasks run first, in a fixed order (`changes`, `ai-usage`,
+* `contexts`, `dispatch`), followed by tasks registered via
+* {@link registerRetentionTask} in name order. Tables that do not exist in
+* this database are reported as `skipped: 'unavailable'` rather than failing —
+* a sweep must be safe to run against a partially bootstrapped database.
+*
+* @param db - Database holding the system tables.
+* @param policy - Overrides on {@link DEFAULT_RETENTION_POLICY}.
+* @returns Per-task and aggregate counts; never throws for a task failure.
+*/
+async function runRetentionSweep(db, policy = {}) {
+	const startedAt = /* @__PURE__ */ new Date();
+	const dryRun = policy.dryRun ?? false;
+	if (policy.enabled === false) return {
+		dryRun,
+		startedAt: startedAt.toISOString(),
+		durationMs: 0,
+		pruned: 0,
+		tasks: [],
+		failed: false
+	};
+	const context = {
+		dryRun,
+		now: startedAt
+	};
+	const tasks = [];
+	for (const builtIn of builtInTasks(policy)) {
+		if (!builtIn.task) {
+			tasks.push({
+				task: builtIn.name,
+				pruned: 0,
+				skipped: "disabled"
+			});
+			continue;
+		}
+		tasks.push(await runTask(db, builtIn.table, builtIn.task, context));
+	}
+	for (const task of getRetentionTasks()) {
+		if (policy.tasks?.[task.name] === false) {
+			tasks.push({
+				task: task.name,
+				pruned: 0,
+				skipped: "disabled"
+			});
+			continue;
+		}
+		tasks.push(await runTask(db, null, task, context));
+	}
+	const pruned = tasks.reduce((total, task) => total + task.pruned, 0);
+	const failed = tasks.some((task) => task.error !== void 0);
+	logger.info("[smrt] retention sweep complete", {
+		dryRun,
+		pruned,
+		failed,
+		tasks: tasks.map((task) => `${task.task}=${task.pruned}`).join(" ")
+	});
+	return {
+		dryRun,
+		startedAt: startedAt.toISOString(),
+		durationMs: Date.now() - startedAt.getTime(),
+		pruned,
+		tasks,
+		failed
+	};
+}
+/**
+* Run one task, converting an absent table or a thrown error into a result.
+*
+* `requiredTable` is checked before the task runs so a sweep against a
+* database that never bootstrapped a given system table reports
+* `unavailable` instead of surfacing an engine-specific "no such table".
+*/
+async function runTask(db, requiredTable, task, context) {
+	try {
+		if (requiredTable && !await tableExists(db, requiredTable)) return {
+			task: task.name,
+			pruned: 0,
+			skipped: "unavailable"
+		};
+		const outcome = await task.run(db, context);
+		return typeof outcome === "number" ? {
+			task: task.name,
+			pruned: outcome
+		} : {
+			task: task.name,
+			pruned: outcome.pruned,
+			details: outcome.details
+		};
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		logger.warn(`[smrt] retention task "${task.name}" failed: ${message}`);
+		return {
+			task: task.name,
+			pruned: 0,
+			error: message
+		};
+	}
+}
+/** Resolve a per-table policy entry, or `null` when it is opted out. */
+function resolveEntry(entry, defaults) {
+	if (entry === false) return null;
+	const merged = {
+		...defaults,
+		...entry ?? {}
+	};
+	return merged.enabled === false ? null : merged;
+}
+/** The framework-owned tasks, in their fixed execution order. */
+function builtInTasks(policy) {
+	return [
+		{
+			name: "changes",
+			table: "_smrt_changes",
+			task: changeFeedTask(policy)
+		},
+		{
+			name: "ai-usage",
+			table: AI_USAGE_TABLE,
+			task: aiUsageTask(policy)
+		},
+		{
+			name: "contexts",
+			table: CONTEXTS_TABLE,
+			task: contextsTask(policy)
+		},
+		{
+			name: "dispatch",
+			table: "_smrt_dispatch",
+			task: dispatchTask(policy)
+		}
+	];
+}
+function changeFeedTask(policy) {
+	const config = resolveEntry(policy.changes, DEFAULT_RETENTION_POLICY.changes);
+	if (!config) return null;
+	return {
+		name: "changes",
+		description: "Prune the append-only change feed (_smrt_changes)",
+		run: async (db, context) => {
+			const { pruned } = await pruneChangeFeed(db, {
+				maxAgeMs: config.maxAgeDays == null ? void 0 : config.maxAgeDays * MS_PER_DAY,
+				maxRows: config.maxRows,
+				dryRun: context.dryRun
+			});
+			return pruned;
+		}
+	};
+}
+function aiUsageTask(policy) {
+	const config = resolveEntry(policy.aiUsage, DEFAULT_RETENTION_POLICY.aiUsage);
+	if (!config) return null;
+	return {
+		name: "ai-usage",
+		description: "Prune AI usage telemetry (_smrt_ai_usage)",
+		run: async (db, context) => {
+			const { pruned } = await pruneAiUsage(db, {
+				maxAgeMs: config.maxAgeDays == null ? void 0 : config.maxAgeDays * MS_PER_DAY,
+				maxRows: config.maxRows,
+				dryRun: context.dryRun,
+				now: context.now
+			});
+			return pruned;
+		}
+	};
+}
+function contextsTask(policy) {
+	if (!resolveEntry(policy.contexts, DEFAULT_RETENTION_POLICY.contexts)) return null;
+	return {
+		name: "contexts",
+		description: "Delete expired context entries (_smrt_contexts)",
+		run: async (db, context) => {
+			const { pruned } = await pruneExpiredContexts(db, {
+				now: context.now,
+				dryRun: context.dryRun
+			});
+			return pruned;
+		}
+	};
+}
+function dispatchTask(policy) {
+	const config = resolveEntry(policy.dispatch, DEFAULT_RETENTION_POLICY.dispatch);
+	if (!config) return null;
+	return {
+		name: "dispatch",
+		description: "Prune processed dispatch queue rows (_smrt_dispatch)",
+		run: async (db, context) => {
+			const { DispatchCollection } = await import("../dispatch/collections/Dispatches.js");
+			const result = await DispatchCollection.cleanup(db, {
+				completedOlderThanDays: config.completedOlderThanDays,
+				failedOlderThanDays: config.failedOlderThanDays,
+				dryRun: context.dryRun
+			});
+			return {
+				pruned: result.completedDeleted + result.failedDeleted,
+				details: {
+					completed: result.completedDeleted,
+					failed: result.failedDeleted
+				}
+			};
+		}
+	};
+}
+function getQueryRows(result) {
+	if (Array.isArray(result)) return result;
+	if (result && typeof result === "object" && "rows" in result) {
+		const rows = result.rows;
+		if (Array.isArray(rows)) return rows;
+	}
+	return [];
+}
+function getDatabaseUrl(db) {
+	return db.url || db.config?.url || "";
+}
+/**
+* Rewrite `?` placeholders to `$n` on PostgreSQL.
+*
+* Retention SQL is written once in the portable `?` form; only the binding
+* syntax differs between engines.
+*/
+function bindPlaceholders(db, sql) {
+	if (detectEngine(getDatabaseUrl(db), db.type) !== "postgres") return sql;
+	let index = 0;
+	return sql.replace(/\?/g, () => `$${++index}`);
+}
+function whereClause(conditions) {
+	return conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+}
+function tenantScopeClause(retention) {
+	if (!("tenantId" in retention)) return {
+		conditions: [],
+		params: []
+	};
+	if (retention.tenantId === void 0) return {
+		conditions: [],
+		params: []
+	};
+	if (retention.tenantId === null) return {
+		conditions: ["tenant_id IS NULL"],
+		params: []
+	};
+	return {
+		conditions: ["tenant_id = ?"],
+		params: [retention.tenantId]
+	};
+}
+async function selectOne(db, sql, params) {
+	return getQueryRows(await db.query(bindPlaceholders(db, sql), ...params))[0];
+}
+/**
+* Count matching rows, then delete them unless this is a dry run.
+*
+* Counting first gives a usable number on every adapter — `rowCount` is not
+* reliably populated across the engines SMRT supports — and is what makes
+* `dryRun` a genuine preview of the same predicate rather than an estimate of
+* a different one.
+*
+* The count and the delete are two statements and deliberately not a
+* transaction: a maintenance sweep must not hold a write lock over a large
+* delete. The returned figure is therefore approximate under concurrent
+* writers, exactly as `pruneChangeFeed` documents.
+*/
+async function deleteFrom(db, table, conditions, params, dryRun) {
+	const where = whereClause(conditions);
+	const total = toSafeInteger((await selectOne(db, `SELECT COUNT(*) AS total FROM ${table} ${where}`, params))?.total ?? 0, "Retention count");
+	if (total <= 0) return 0;
+	if (!dryRun) await db.query(bindPlaceholders(db, `DELETE FROM ${table} ${where}`), ...params);
+	return total;
+}
+/** Best-effort table probe used to report `unavailable` rather than throwing. */
+async function tableExists(db, table) {
+	try {
+		if (typeof db.tableExists === "function") return await db.tableExists(table);
+	} catch {
+		return false;
+	}
+	try {
+		await db.query(`SELECT 1 FROM ${table} LIMIT 1`);
+		return true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+export { DEFAULT_RETENTION_POLICY, clearRetentionTasks, getRetentionTasks, pruneAiUsage, pruneExpiredContexts, registerRetentionTask, runRetentionSweep, unregisterRetentionTask };
+
+//# sourceMappingURL=retention.js.map

package/dist/system/retention.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retention.js","names":[],"sources":["../../src/system/retention.ts"],"sourcesContent":["/**\n * System-table retention — bounded growth for framework-owned tables (#2375).\n *\n * Several `_smrt_*` tables are append-only by construction and were, until\n * this module, unbounded by default: `_smrt_changes` grew one row per\n * framework save/delete, `_smrt_ai_usage` one row per AI call (persistence is\n * on by default, see `config.ts`), `_smrt_contexts` accumulated rows whose\n * `expires_at` nothing ever enforced, and `_smrt_dispatch` retained completed\n * work until an operator remembered to run `smrt dispatch:cleanup`.\n *\n * This module supplies the missing half:\n *\n * - {@link pruneAiUsage} — the retention API `_smrt_ai_usage` never had.\n * - {@link pruneExpiredContexts} — enforcement for `_smrt_contexts.expires_at`.\n * - {@link runRetentionSweep} — one entry point that applies a documented,\n *   opt-out {@link RetentionPolicy} across every framework-owned table, plus\n *   any task other packages contribute via {@link registerRetentionTask}\n *   (`@happyvertical/smrt-jobs` registers job/job-event cleanup;\n *   `@happyvertical/smrt-users` registers session and token expiry).\n *\n * Scheduling is the caller's: `smrt db:prune` is the cron entry point, and a\n * running `TaskRunner` sweeps on an interval unless configured otherwise.\n *\n * ## Failure policy\n *\n * A sweep is maintenance, not a transaction. One failing task never aborts the\n * rest — the failure is captured on that task's {@link RetentionTaskResult}\n * and the sweep continues. Callers decide what a partial sweep means; the CLI\n * exits non-zero when any task failed.\n *\n * ## Predicate indexes\n *\n * Every predicate below is indexed by the system DDL in `system/schema.ts`\n * (`_smrt_contexts(expires_at)`, `_smrt_ai_usage(tenant_id, created_at)`,\n * `_smrt_dispatch(status, processed_at)` / `(status, updated_at)`) or by the\n * jobs compatibility path in `system/compatibility.ts`\n * (`_smrt_jobs(status, completed_at)`, `_smrt_job_events(created_at)`).\n * A new retention predicate must ship with its index.\n *\n * @see https://github.com/happyvertical/smrt/issues/2375\n * @packageDocumentation\n */\n\nimport { createLogger } from '@happyvertical/logger';\nimport type { DatabaseInterface } from '@happyvertical/sql';\nimport { pruneChangeFeed } from '../change-feed.js';\nimport { detectEngine } from '../schema/ddl/index.js';\nimport { toSafeInteger } from '../utils/safe-integer.js';\n\nconst logger = createLogger({ level: 'info' });\n\n/** Milliseconds in a day — the unit every retention policy is expressed in. */\nconst MS_PER_DAY = 24 * 60 * 60 * 1000;\n\n// ============================================================================\n// Policy\n// ============================================================================\n\n/** Retention for the append-only change feed (`_smrt_changes`). */\nexport interface ChangeFeedRetentionPolicy {\n  /** Run this task (default `true`). */\n  enabled?: boolean;\n  /** Drop entries older than this many days (default 30). */\n  maxAgeDays?: number;\n  /** Additionally keep at most this many newest entries (default: unbounded). */\n  maxRows?: number;\n}\n\n/** Retention for AI usage telemetry (`_smrt_ai_usage`). */\nexport interface AiUsageRetentionPolicy {\n  /** Run this task (default `true`). */\n  enabled?: boolean;\n  /** Drop records older than this many days (default 90). */\n  maxAgeDays?: number;\n  /** Additionally keep at most this many newest records (default: unbounded). */\n  maxRows?: number;\n}\n\n/** Retention for remembered context entries (`_smrt_contexts`). */\nexport interface ContextsRetentionPolicy {\n  /** Run this task (default `true`). */\n  enabled?: boolean;\n}\n\n/** Retention for the dispatch queue (`_smrt_dispatch`). */\nexport interface DispatchRetentionPolicy {\n  /** Run this task (default `true`). */\n  enabled?: boolean;\n  /** Drop completed dispatches processed more than this many days ago (default 30). */\n  completedOlderThanDays?: number;\n  /** Drop failed dispatches last touched more than this many days ago (default 90). */\n  failedOlderThanDays?: number;\n}\n\n/**\n * Retention policy for a sweep.\n *\n * Every table is pruned by default; set a table's entry to `false` (or\n * `{ enabled: false }`) to opt that table out, or `enabled: false` at the top\n * level to opt the whole sweep out.\n */\nexport interface RetentionPolicy {\n  /** Run the sweep at all (default `true`). */\n  enabled?: boolean;\n  /** Report what would be pruned without deleting anything (default `false`). */\n  dryRun?: boolean;\n  /** `_smrt_changes` retention, or `false` to skip. */\n  changes?: ChangeFeedRetentionPolicy | false;\n  /** `_smrt_ai_usage` retention, or `false` to skip. */\n  aiUsage?: AiUsageRetentionPolicy | false;\n  /** `_smrt_contexts` expiry enforcement, or `false` to skip. */\n  contexts?: ContextsRetentionPolicy | false;\n  /** `_smrt_dispatch` retention, or `false` to skip. */\n  dispatch?: DispatchRetentionPolicy | false;\n  /**\n   * Enable/disable individual tasks contributed through\n   * {@link registerRetentionTask}, keyed by task name. Unlisted tasks run.\n   */\n  tasks?: Record<string, boolean>;\n}\n\n/**\n * Documented retention defaults.\n *\n * Chosen to be generous relative to every in-tree consumer: change-feed\n * cursors resync automatically past the window, AI usage outlives a monthly\n * billing cycle by two months, and dispatch keeps a full quarter of failures\n * for forensics. Applications that need longer history raise these; those that\n * need none set the table to `false`.\n */\nexport const DEFAULT_RETENTION_POLICY: {\n  changes: ChangeFeedRetentionPolicy;\n  aiUsage: AiUsageRetentionPolicy;\n  contexts: ContextsRetentionPolicy;\n  dispatch: DispatchRetentionPolicy;\n} = {\n  changes: { maxAgeDays: 30 },\n  aiUsage: { maxAgeDays: 90 },\n  contexts: {},\n  dispatch: { completedOlderThanDays: 30, failedOlderThanDays: 90 },\n};\n\n// ============================================================================\n// Tasks\n// ============================================================================\n\n/** Per-run inputs handed to every retention task. */\nexport interface RetentionTaskContext {\n  /** Count what would be deleted instead of deleting it. */\n  dryRun: boolean;\n  /** Sweep start time — every task derives its cutoffs from this one clock. */\n  now: Date;\n}\n\n/** What one task did (or why it did nothing). */\nexport interface RetentionTaskResult {\n  /** Task name, unique within a sweep. */\n  task: string;\n  /** Rows deleted, or — under `dryRun` — rows that would be deleted. */\n  pruned: number;\n  /**\n   * Why the task did no work: `disabled` (policy opted it out) or\n   * `unavailable` (the table does not exist in this database).\n   */\n  skipped?: 'disabled' | 'unavailable';\n  /** Message of the error this task failed with, if any. */\n  error?: string;\n  /** Optional per-bucket breakdown (e.g. completed vs failed dispatches). */\n  details?: Record<string, number>;\n}\n\n/** What a task returns; a bare number is shorthand for `{ pruned }`. */\nexport type RetentionTaskOutcome =\n  | number\n  | { pruned: number; details?: Record<string, number> };\n\n/**\n * A retention task contributed by a package that owns its own tables.\n *\n * Tasks must honour `context.dryRun` — a task that deletes during a dry run\n * makes the whole preview a lie.\n */\nexport interface RetentionTask {\n  /** Unique name; also the {@link RetentionPolicy.tasks} opt-out key. */\n  name: string;\n  /** One-line description surfaced by `smrt db:prune --json`. */\n  description?: string;\n  /** Perform (or, under `dryRun`, count) the deletion. */\n  run(\n    db: DatabaseInterface,\n    context: RetentionTaskContext,\n  ): Promise<RetentionTaskOutcome>;\n}\n\nconst RETENTION_TASKS_KEY = Symbol.for('smrt.retention-tasks');\n\n/**\n * Names {@link builtInTasks} always uses for the four framework-owned tables.\n *\n * Reserved against contributed tasks: `RetentionTaskResult.task` is\n * documented unique within a sweep, and a contributed task sharing one of\n * these names would collide with a built-in result — silently, since nothing\n * else in the sweep loop checks for it — and would also be unreachable\n * through {@link RetentionPolicy.tasks}, which only ever sees the *last*\n * task run under that name, never the built-in one (opting a built-in table\n * out goes through its own dedicated policy field instead).\n */\nconst RESERVED_TASK_NAMES = new Set([\n  'changes',\n  'ai-usage',\n  'contexts',\n  'dispatch',\n]);\n\n/**\n * The task registry, held on `globalThis` rather than in module scope.\n *\n * Contributing packages resolve their own copy of `@happyvertical/smrt-core`\n * whenever a consumer's install is not fully deduped, and the CLI resolves a\n * third. A module-local `Map` would give each of them a private, empty\n * registry — the task would register in one and the sweep would run in\n * another. `ObjectRegistry` is on `globalThis` for the same reason.\n */\nfunction registeredTasks(): Map<string, RetentionTask> {\n  const root = globalThis as typeof globalThis & {\n    [RETENTION_TASKS_KEY]?: Map<string, RetentionTask>;\n  };\n  root[RETENTION_TASKS_KEY] ??= new Map<string, RetentionTask>();\n  return root[RETENTION_TASKS_KEY];\n}\n\n/**\n * Register a retention task so {@link runRetentionSweep} includes it.\n *\n * Registering a task does not schedule anything — a task only runs when\n * something calls {@link runRetentionSweep}, and the policy can still turn it\n * off by name. Re-registering the same name replaces the previous task, which\n * keeps module re-evaluation (HMR, repeated test imports) idempotent.\n *\n * @throws If `task.name` is empty, or is one of the four built-in table\n *   names (`changes`, `ai-usage`, `contexts`, `dispatch`) — see\n *   {@link RESERVED_TASK_NAMES}.\n */\nexport function registerRetentionTask(task: RetentionTask): void {\n  if (!task.name) {\n    throw new Error('registerRetentionTask requires a non-empty task name');\n  }\n  if (RESERVED_TASK_NAMES.has(task.name)) {\n    throw new Error(\n      `registerRetentionTask: \"${task.name}\" is a built-in task name (reserved: ${[...RESERVED_TASK_NAMES].join(', ')})`,\n    );\n  }\n  registeredTasks().set(task.name, task);\n}\n\n/** Remove a registered retention task. Returns `true` if one was removed. */\nexport function unregisterRetentionTask(name: string): boolean {\n  return registeredTasks().delete(name);\n}\n\n/** Registered retention tasks, ordered by name for deterministic sweeps. */\nexport function getRetentionTasks(): RetentionTask[] {\n  return [...registeredTasks().values()].sort((left, right) =>\n    left.name.localeCompare(right.name),\n  );\n}\n\n/** Drop every registered retention task (test helper). */\nexport function clearRetentionTasks(): void {\n  registeredTasks().clear();\n}\n\n// ============================================================================\n// AI usage retention\n// ============================================================================\n\n/** Bounds for {@link pruneAiUsage}. At least one bound is required. */\nexport interface AiUsageRetention {\n  /** Delete records older than this many milliseconds. */\n  maxAgeMs?: number;\n  /**\n   * Keep at most this many newest records (by `created_at`).\n   *\n   * A ceiling, not a floor: combined with `maxAgeMs`, the two bounds union\n   * — a row past the age cutoff is deleted regardless of `maxRows`, so\n   * `maxRows` never resurrects rows the age bound already excludes. If every\n   * row is already older than `maxAgeMs`, a finite `maxRows` keeps none of\n   * them; it does not guarantee `maxRows` survivors independent of age. (A\n   * `maxRows` that overrode age this way would defeat the reason `maxAgeMs`\n   * usually exists in the first place — a compliance/privacy deletion\n   * deadline that a row-count floor should not be able to postpone.)\n   *\n   * Rows sharing the cutoff timestamp all survive, so the retained count can\n   * exceed `maxRows` by the size of one timestamp tie.\n   */\n  maxRows?: number;\n  /**\n   * Restrict the prune to one tenant: a string matches that tenant, `null`\n   * matches the global (tenant-less) records. Omit to prune every tenant.\n   */\n  tenantId?: string | null;\n  /** Count matching records without deleting them. */\n  dryRun?: boolean;\n  /** Clock for the age cutoff (default: now). */\n  now?: Date;\n}\n\n/** Name of the AI usage telemetry table. */\nconst AI_USAGE_TABLE = '_smrt_ai_usage';\n\n/** Name of the remembered-context table. */\nconst CONTEXTS_TABLE = '_smrt_contexts';\n\n/**\n * Prune AI usage telemetry to bound `_smrt_ai_usage` growth.\n *\n * `_smrt_ai_usage` gains one row per AI call and persistence is on by default,\n * so a busy deployment writes millions of rows a year with nothing to remove\n * them. Both bounds may be combined; each is applied independently and the\n * returned count is the total deleted.\n *\n * Predicates are covered by `idx_smrt_ai_usage_tenant_created`\n * (`tenant_id, created_at`) — the same index the subscriptions billing meter\n * needs for its `tenant_id + created_at` range scan.\n *\n * @param db - Database holding the system tables.\n * @param retention - At least one of `maxAgeMs` / `maxRows`.\n * @returns Number of records deleted (or, under `dryRun`, matched).\n */\nexport async function pruneAiUsage(\n  db: DatabaseInterface,\n  retention: AiUsageRetention,\n): Promise<{ pruned: number }> {\n  const { maxAgeMs, maxRows, dryRun = false } = retention;\n\n  if (maxAgeMs == null && maxRows == null) {\n    throw new Error('pruneAiUsage requires maxAgeMs and/or maxRows');\n  }\n  if (maxAgeMs != null && (!Number.isFinite(maxAgeMs) || maxAgeMs < 0)) {\n    throw new Error(`pruneAiUsage maxAgeMs must be >= 0, got ${maxAgeMs}`);\n  }\n  if (maxRows != null && (!Number.isFinite(maxRows) || maxRows < 0)) {\n    throw new Error(`pruneAiUsage maxRows must be >= 0, got ${maxRows}`);\n  }\n\n  const now = retention.now ?? new Date();\n  const scope = tenantScopeClause(retention);\n  let pruned = 0;\n\n  // Rows the age bound already accounted for. Redundant when they were really\n  // deleted, load-bearing under `dryRun`, where they were not — without it the\n  // row bound would count the same records a second time.\n  const alreadyCounted: { conditions: string[]; params: unknown[] } = {\n    conditions: [],\n    params: [],\n  };\n\n  if (maxAgeMs != null) {\n    const cutoff = new Date(now.getTime() - maxAgeMs).toISOString();\n    pruned += await deleteFrom(\n      db,\n      AI_USAGE_TABLE,\n      [...scope.conditions, 'created_at < ?'],\n      [...scope.params, cutoff],\n      dryRun,\n    );\n    alreadyCounted.conditions.push('created_at >= ?');\n    alreadyCounted.params.push(cutoff);\n  }\n\n  if (maxRows != null) {\n    const keep = Math.floor(maxRows);\n    if (keep === 0) {\n      pruned += await deleteFrom(\n        db,\n        AI_USAGE_TABLE,\n        [...scope.conditions, ...alreadyCounted.conditions],\n        [...scope.params, ...alreadyCounted.params],\n        dryRun,\n      );\n    } else {\n      // The oldest retained row's timestamp is the cutoff. `LIMIT 1 OFFSET n`\n      // is portable across every supported engine, unlike the\n      // `LIMIT ALL`/`LIMIT -1` spellings of \"all rows past an offset\".\n      const boundary = await selectOne(\n        db,\n        `SELECT created_at FROM ${AI_USAGE_TABLE}\n         ${whereClause(scope.conditions)}\n         ORDER BY created_at DESC\n         LIMIT 1 OFFSET ${keep - 1}`,\n        scope.params,\n      );\n      const cutoff = boundary?.created_at;\n      if (cutoff != null) {\n        pruned += await deleteFrom(\n          db,\n          AI_USAGE_TABLE,\n          [...scope.conditions, 'created_at < ?', ...alreadyCounted.conditions],\n          [...scope.params, cutoff, ...alreadyCounted.params],\n          dryRun,\n        );\n      }\n    }\n  }\n\n  return { pruned };\n}\n\n/**\n * Delete context entries whose `expires_at` has passed.\n *\n * `remember({ expiresAt })` has always stored the expiry and never acted on\n * it. Enforcement is deliberately prune-side only: `recall()`/`recallAll()`\n * keep their documented \"expiry is not applied at read time\" contract, so this\n * bounds storage without changing read semantics for existing callers.\n * (`LearningMemory` filters expired rows itself.)\n *\n * Rows with a `NULL` `expires_at` never expire and are never touched.\n * The predicate is covered by `idx_smrt_contexts_expires_at`.\n *\n * @param db - Database holding the system tables.\n * @param options.now - Clock for the expiry comparison (default: now).\n * @param options.dryRun - Count matching rows without deleting them.\n * @returns Number of expired entries deleted (or, under `dryRun`, matched).\n */\nexport async function pruneExpiredContexts(\n  db: DatabaseInterface,\n  options: { now?: Date; dryRun?: boolean } = {},\n): Promise<{ pruned: number }> {\n  const now = (options.now ?? new Date()).toISOString();\n  const pruned = await deleteFrom(\n    db,\n    CONTEXTS_TABLE,\n    ['expires_at IS NOT NULL', 'expires_at < ?'],\n    [now],\n    options.dryRun ?? false,\n  );\n  return { pruned };\n}\n\n// ============================================================================\n// Sweep\n// ============================================================================\n\n/** Aggregate outcome of one {@link runRetentionSweep} call. */\nexport interface RetentionSweepResult {\n  /** Whether this run only counted rows. */\n  dryRun: boolean;\n  /** Sweep start time, ISO-8601. */\n  startedAt: string;\n  /** Wall-clock duration of the sweep. */\n  durationMs: number;\n  /** Total rows pruned (or matched) across all tasks. */\n  pruned: number;\n  /** Per-task outcomes, in execution order. */\n  tasks: RetentionTaskResult[];\n  /** Whether any task failed — the sweep never throws for a task failure. */\n  failed: boolean;\n}\n\n/**\n * Apply a {@link RetentionPolicy} across every framework-owned table.\n *\n * Built-in tasks run first, in a fixed order (`changes`, `ai-usage`,\n * `contexts`, `dispatch`), followed by tasks registered via\n * {@link registerRetentionTask} in name order. Tables that do not exist in\n * this database are reported as `skipped: 'unavailable'` rather than failing —\n * a sweep must be safe to run against a partially bootstrapped database.\n *\n * @param db - Database holding the system tables.\n * @param policy - Overrides on {@link DEFAULT_RETENTION_POLICY}.\n * @returns Per-task and aggregate counts; never throws for a task failure.\n */\nexport async function runRetentionSweep(\n  db: DatabaseInterface,\n  policy: RetentionPolicy = {},\n): Promise<RetentionSweepResult> {\n  const startedAt = new Date();\n  const dryRun = policy.dryRun ?? false;\n\n  if (policy.enabled === false) {\n    return {\n      dryRun,\n      startedAt: startedAt.toISOString(),\n      durationMs: 0,\n      pruned: 0,\n      tasks: [],\n      failed: false,\n    };\n  }\n\n  const context: RetentionTaskContext = { dryRun, now: startedAt };\n  const tasks: RetentionTaskResult[] = [];\n\n  for (const builtIn of builtInTasks(policy)) {\n    if (!builtIn.task) {\n      tasks.push({ task: builtIn.name, pruned: 0, skipped: 'disabled' });\n      continue;\n    }\n    tasks.push(await runTask(db, builtIn.table, builtIn.task, context));\n  }\n\n  for (const task of getRetentionTasks()) {\n    if (policy.tasks?.[task.name] === false) {\n      tasks.push({ task: task.name, pruned: 0, skipped: 'disabled' });\n      continue;\n    }\n    tasks.push(await runTask(db, null, task, context));\n  }\n\n  const pruned = tasks.reduce((total, task) => total + task.pruned, 0);\n  const failed = tasks.some((task) => task.error !== undefined);\n\n  logger.info('[smrt] retention sweep complete', {\n    dryRun,\n    pruned,\n    failed,\n    tasks: tasks.map((task) => `${task.task}=${task.pruned}`).join(' '),\n  });\n\n  return {\n    dryRun,\n    startedAt: startedAt.toISOString(),\n    durationMs: Date.now() - startedAt.getTime(),\n    pruned,\n    tasks,\n    failed,\n  };\n}\n\n/**\n * Run one task, converting an absent table or a thrown error into a result.\n *\n * `requiredTable` is checked before the task runs so a sweep against a\n * database that never bootstrapped a given system table reports\n * `unavailable` instead of surfacing an engine-specific \"no such table\".\n */\nasync function runTask(\n  db: DatabaseInterface,\n  requiredTable: string | null,\n  task: RetentionTask,\n  context: RetentionTaskContext,\n): Promise<RetentionTaskResult> {\n  try {\n    if (requiredTable && !(await tableExists(db, requiredTable))) {\n      return { task: task.name, pruned: 0, skipped: 'unavailable' };\n    }\n\n    const outcome = await task.run(db, context);\n    return typeof outcome === 'number'\n      ? { task: task.name, pruned: outcome }\n      : { task: task.name, pruned: outcome.pruned, details: outcome.details };\n  } catch (error) {\n    const message = error instanceof Error ? error.message : String(error);\n    logger.warn(`[smrt] retention task \"${task.name}\" failed: ${message}`);\n    return { task: task.name, pruned: 0, error: message };\n  }\n}\n\n/** Resolve a per-table policy entry, or `null` when it is opted out. */\nfunction resolveEntry<T extends { enabled?: boolean }>(\n  entry: T | false | undefined,\n  defaults: T,\n): T | null {\n  if (entry === false) return null;\n  const merged = { ...defaults, ...(entry ?? {}) };\n  return merged.enabled === false ? null : merged;\n}\n\n/** A built-in task plus the table it needs and whether policy enabled it. */\ninterface BuiltInRetentionTask {\n  name: string;\n  table: string;\n  task: RetentionTask | null;\n}\n\n/** The framework-owned tasks, in their fixed execution order. */\nfunction builtInTasks(policy: RetentionPolicy): BuiltInRetentionTask[] {\n  return [\n    { name: 'changes', table: '_smrt_changes', task: changeFeedTask(policy) },\n    { name: 'ai-usage', table: AI_USAGE_TABLE, task: aiUsageTask(policy) },\n    { name: 'contexts', table: CONTEXTS_TABLE, task: contextsTask(policy) },\n    { name: 'dispatch', table: '_smrt_dispatch', task: dispatchTask(policy) },\n  ];\n}\n\nfunction changeFeedTask(policy: RetentionPolicy): RetentionTask | null {\n  const config = resolveEntry<ChangeFeedRetentionPolicy>(\n    policy.changes,\n    DEFAULT_RETENTION_POLICY.changes,\n  );\n  if (!config) return null;\n\n  return {\n    name: 'changes',\n    description: 'Prune the append-only change feed (_smrt_changes)',\n    run: async (db, context) => {\n      const { pruned } = await pruneChangeFeed(db, {\n        maxAgeMs:\n          config.maxAgeDays == null\n            ? undefined\n            : config.maxAgeDays * MS_PER_DAY,\n        maxRows: config.maxRows,\n        dryRun: context.dryRun,\n      });\n      return pruned;\n    },\n  };\n}\n\nfunction aiUsageTask(policy: RetentionPolicy): RetentionTask | null {\n  const config = resolveEntry<AiUsageRetentionPolicy>(\n    policy.aiUsage,\n    DEFAULT_RETENTION_POLICY.aiUsage,\n  );\n  if (!config) return null;\n\n  return {\n    name: 'ai-usage',\n    description: 'Prune AI usage telemetry (_smrt_ai_usage)',\n    run: async (db, context) => {\n      const { pruned } = await pruneAiUsage(db, {\n        maxAgeMs:\n          config.maxAgeDays == null\n            ? undefined\n            : config.maxAgeDays * MS_PER_DAY,\n        maxRows: config.maxRows,\n        dryRun: context.dryRun,\n        now: context.now,\n      });\n      return pruned;\n    },\n  };\n}\n\nfunction contextsTask(policy: RetentionPolicy): RetentionTask | null {\n  const config = resolveEntry<ContextsRetentionPolicy>(\n    policy.contexts,\n    DEFAULT_RETENTION_POLICY.contexts,\n  );\n  if (!config) return null;\n\n  return {\n    name: 'contexts',\n    description: 'Delete expired context entries (_smrt_contexts)',\n    run: async (db, context) => {\n      const { pruned } = await pruneExpiredContexts(db, {\n        now: context.now,\n        dryRun: context.dryRun,\n      });\n      return pruned;\n    },\n  };\n}\n\nfunction dispatchTask(policy: RetentionPolicy): RetentionTask | null {\n  const config = resolveEntry<DispatchRetentionPolicy>(\n    policy.dispatch,\n    DEFAULT_RETENTION_POLICY.dispatch,\n  );\n  if (!config) return null;\n\n  return {\n    name: 'dispatch',\n    description: 'Prune processed dispatch queue rows (_smrt_dispatch)',\n    run: async (db, context) => {\n      // Imported lazily: the dispatch collection pulls in the whole dispatch\n      // module graph, which this module must not force onto callers that only\n      // prune system tables.\n      const { DispatchCollection } = await import(\n        '../dispatch/collections/Dispatches.js'\n      );\n      const result = await DispatchCollection.cleanup(db, {\n        completedOlderThanDays: config.completedOlderThanDays,\n        failedOlderThanDays: config.failedOlderThanDays,\n        dryRun: context.dryRun,\n      });\n      return {\n        pruned: result.completedDeleted + result.failedDeleted,\n        details: {\n          completed: result.completedDeleted,\n          failed: result.failedDeleted,\n        },\n      };\n    },\n  };\n}\n\n// ============================================================================\n// SQL helpers\n// ============================================================================\n\nfunction getQueryRows(result: unknown): Record<string, unknown>[] {\n  if (Array.isArray(result)) {\n    return result as Record<string, unknown>[];\n  }\n  if (result && typeof result === 'object' && 'rows' in result) {\n    const rows = (result as { rows?: unknown }).rows;\n    if (Array.isArray(rows)) {\n      return rows as Record<string, unknown>[];\n    }\n  }\n  return [];\n}\n\nfunction getDatabaseUrl(db: DatabaseInterface): string {\n  return db.url || (db as { config?: { url?: string } }).config?.url || '';\n}\n\n/**\n * Rewrite `?` placeholders to `$n` on PostgreSQL.\n *\n * Retention SQL is written once in the portable `?` form; only the binding\n * syntax differs between engines.\n */\nfunction bindPlaceholders(db: DatabaseInterface, sql: string): string {\n  const engine = detectEngine(\n    getDatabaseUrl(db),\n    (db as { type?: string }).type,\n  );\n  if (engine !== 'postgres') return sql;\n\n  let index = 0;\n  return sql.replace(/\\?/g, () => `$${++index}`);\n}\n\nfunction whereClause(conditions: string[]): string {\n  return conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';\n}\n\nfunction tenantScopeClause(retention: AiUsageRetention): {\n  conditions: string[];\n  params: unknown[];\n} {\n  if (!('tenantId' in retention)) return { conditions: [], params: [] };\n  if (retention.tenantId === undefined) return { conditions: [], params: [] };\n  if (retention.tenantId === null) {\n    return { conditions: ['tenant_id IS NULL'], params: [] };\n  }\n  return { conditions: ['tenant_id = ?'], params: [retention.tenantId] };\n}\n\nasync function selectOne(\n  db: DatabaseInterface,\n  sql: string,\n  params: unknown[],\n): Promise<Record<string, unknown> | undefined> {\n  const rows = getQueryRows(\n    await db.query(bindPlaceholders(db, sql), ...params),\n  );\n  return rows[0];\n}\n\n/**\n * Count matching rows, then delete them unless this is a dry run.\n *\n * Counting first gives a usable number on every adapter — `rowCount` is not\n * reliably populated across the engines SMRT supports — and is what makes\n * `dryRun` a genuine preview of the same predicate rather than an estimate of\n * a different one.\n *\n * The count and the delete are two statements and deliberately not a\n * transaction: a maintenance sweep must not hold a write lock over a large\n * delete. The returned figure is therefore approximate under concurrent\n * writers, exactly as `pruneChangeFeed` documents.\n */\nasync function deleteFrom(\n  db: DatabaseInterface,\n  table: string,\n  conditions: string[],\n  params: unknown[],\n  dryRun: boolean,\n): Promise<number> {\n  const where = whereClause(conditions);\n  const countRow = await selectOne(\n    db,\n    `SELECT COUNT(*) AS total FROM ${table} ${where}`,\n    params,\n  );\n  const total = toSafeInteger(countRow?.total ?? 0, 'Retention count');\n  if (total <= 0) return 0;\n\n  if (!dryRun) {\n    await db.query(\n      bindPlaceholders(db, `DELETE FROM ${table} ${where}`),\n      ...params,\n    );\n  }\n\n  return total;\n}\n\n/** Best-effort table probe used to report `unavailable` rather than throwing. */\nasync function tableExists(\n  db: DatabaseInterface,\n  table: string,\n): Promise<boolean> {\n  try {\n    if (typeof db.tableExists === 'function') {\n      return await db.tableExists(table);\n    }\n  } catch {\n    return false;\n  }\n\n  try {\n    await db.query(`SELECT 1 FROM ${table} LIMIT 1`);\n    return true;\n  } catch {\n    return false;\n  }\n}\n"],"mappings":"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"}