@happyvertical/smrt-core 0.40.70 → 0.42.0

package/dist/system/retention.d.ts

@@ -0,0 +1,237 @@
+import { DatabaseInterface } from '@happyvertical/sql';
+/** Retention for the append-only change feed (`_smrt_changes`). */
+export interface ChangeFeedRetentionPolicy {
+    /** Run this task (default `true`). */
+    enabled?: boolean;
+    /** Drop entries older than this many days (default 30). */
+    maxAgeDays?: number;
+    /** Additionally keep at most this many newest entries (default: unbounded). */
+    maxRows?: number;
+}
+/** Retention for AI usage telemetry (`_smrt_ai_usage`). */
+export interface AiUsageRetentionPolicy {
+    /** Run this task (default `true`). */
+    enabled?: boolean;
+    /** Drop records older than this many days (default 90). */
+    maxAgeDays?: number;
+    /** Additionally keep at most this many newest records (default: unbounded). */
+    maxRows?: number;
+}
+/** Retention for remembered context entries (`_smrt_contexts`). */
+export interface ContextsRetentionPolicy {
+    /** Run this task (default `true`). */
+    enabled?: boolean;
+}
+/** Retention for the dispatch queue (`_smrt_dispatch`). */
+export interface DispatchRetentionPolicy {
+    /** Run this task (default `true`). */
+    enabled?: boolean;
+    /** Drop completed dispatches processed more than this many days ago (default 30). */
+    completedOlderThanDays?: number;
+    /** Drop failed dispatches last touched more than this many days ago (default 90). */
+    failedOlderThanDays?: number;
+}
+/**
+ * Retention policy for a sweep.
+ *
+ * Every table is pruned by default; set a table's entry to `false` (or
+ * `{ enabled: false }`) to opt that table out, or `enabled: false` at the top
+ * level to opt the whole sweep out.
+ */
+export interface RetentionPolicy {
+    /** Run the sweep at all (default `true`). */
+    enabled?: boolean;
+    /** Report what would be pruned without deleting anything (default `false`). */
+    dryRun?: boolean;
+    /** `_smrt_changes` retention, or `false` to skip. */
+    changes?: ChangeFeedRetentionPolicy | false;
+    /** `_smrt_ai_usage` retention, or `false` to skip. */
+    aiUsage?: AiUsageRetentionPolicy | false;
+    /** `_smrt_contexts` expiry enforcement, or `false` to skip. */
+    contexts?: ContextsRetentionPolicy | false;
+    /** `_smrt_dispatch` retention, or `false` to skip. */
+    dispatch?: DispatchRetentionPolicy | false;
+    /**
+     * Enable/disable individual tasks contributed through
+     * {@link registerRetentionTask}, keyed by task name. Unlisted tasks run.
+     */
+    tasks?: Record<string, boolean>;
+}
+/**
+ * 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`.
+ */
+export declare const DEFAULT_RETENTION_POLICY: {
+    changes: ChangeFeedRetentionPolicy;
+    aiUsage: AiUsageRetentionPolicy;
+    contexts: ContextsRetentionPolicy;
+    dispatch: DispatchRetentionPolicy;
+};
+/** Per-run inputs handed to every retention task. */
+export interface RetentionTaskContext {
+    /** Count what would be deleted instead of deleting it. */
+    dryRun: boolean;
+    /** Sweep start time — every task derives its cutoffs from this one clock. */
+    now: Date;
+}
+/** What one task did (or why it did nothing). */
+export interface RetentionTaskResult {
+    /** Task name, unique within a sweep. */
+    task: string;
+    /** Rows deleted, or — under `dryRun` — rows that would be deleted. */
+    pruned: number;
+    /**
+     * Why the task did no work: `disabled` (policy opted it out) or
+     * `unavailable` (the table does not exist in this database).
+     */
+    skipped?: 'disabled' | 'unavailable';
+    /** Message of the error this task failed with, if any. */
+    error?: string;
+    /** Optional per-bucket breakdown (e.g. completed vs failed dispatches). */
+    details?: Record<string, number>;
+}
+/** What a task returns; a bare number is shorthand for `{ pruned }`. */
+export type RetentionTaskOutcome = number | {
+    pruned: number;
+    details?: Record<string, number>;
+};
+/**
+ * A retention task contributed by a package that owns its own tables.
+ *
+ * Tasks must honour `context.dryRun` — a task that deletes during a dry run
+ * makes the whole preview a lie.
+ */
+export interface RetentionTask {
+    /** Unique name; also the {@link RetentionPolicy.tasks} opt-out key. */
+    name: string;
+    /** One-line description surfaced by `smrt db:prune --json`. */
+    description?: string;
+    /** Perform (or, under `dryRun`, count) the deletion. */
+    run(db: DatabaseInterface, context: RetentionTaskContext): Promise<RetentionTaskOutcome>;
+}
+/**
+ * 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}.
+ */
+export declare function registerRetentionTask(task: RetentionTask): void;
+/** Remove a registered retention task. Returns `true` if one was removed. */
+export declare function unregisterRetentionTask(name: string): boolean;
+/** Registered retention tasks, ordered by name for deterministic sweeps. */
+export declare function getRetentionTasks(): RetentionTask[];
+/** Drop every registered retention task (test helper). */
+export declare function clearRetentionTasks(): void;
+/** Bounds for {@link pruneAiUsage}. At least one bound is required. */
+export interface AiUsageRetention {
+    /** Delete records older than this many milliseconds. */
+    maxAgeMs?: number;
+    /**
+     * Keep at most this many newest records (by `created_at`).
+     *
+     * A ceiling, not a floor: combined with `maxAgeMs`, the two bounds union
+     * — a row past the age cutoff is deleted regardless of `maxRows`, so
+     * `maxRows` never resurrects rows the age bound already excludes. If every
+     * row is already older than `maxAgeMs`, a finite `maxRows` keeps none of
+     * them; it does not guarantee `maxRows` survivors independent of age. (A
+     * `maxRows` that overrode age this way would defeat the reason `maxAgeMs`
+     * usually exists in the first place — a compliance/privacy deletion
+     * deadline that a row-count floor should not be able to postpone.)
+     *
+     * Rows sharing the cutoff timestamp all survive, so the retained count can
+     * exceed `maxRows` by the size of one timestamp tie.
+     */
+    maxRows?: number;
+    /**
+     * Restrict the prune to one tenant: a string matches that tenant, `null`
+     * matches the global (tenant-less) records. Omit to prune every tenant.
+     */
+    tenantId?: string | null;
+    /** Count matching records without deleting them. */
+    dryRun?: boolean;
+    /** Clock for the age cutoff (default: now). */
+    now?: Date;
+}
+/**
+ * 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).
+ */
+export declare function pruneAiUsage(db: DatabaseInterface, retention: AiUsageRetention): Promise<{
+    pruned: number;
+}>;
+/**
+ * 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).
+ */
+export declare function pruneExpiredContexts(db: DatabaseInterface, options?: {
+    now?: Date;
+    dryRun?: boolean;
+}): Promise<{
+    pruned: number;
+}>;
+/** Aggregate outcome of one {@link runRetentionSweep} call. */
+export interface RetentionSweepResult {
+    /** Whether this run only counted rows. */
+    dryRun: boolean;
+    /** Sweep start time, ISO-8601. */
+    startedAt: string;
+    /** Wall-clock duration of the sweep. */
+    durationMs: number;
+    /** Total rows pruned (or matched) across all tasks. */
+    pruned: number;
+    /** Per-task outcomes, in execution order. */
+    tasks: RetentionTaskResult[];
+    /** Whether any task failed — the sweep never throws for a task failure. */
+    failed: boolean;
+}
+/**
+ * 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.
+ */
+export declare function runRetentionSweep(db: DatabaseInterface, policy?: RetentionPolicy): Promise<RetentionSweepResult>;
+//# sourceMappingURL=retention.d.ts.map

package/dist/system/retention.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retention.d.ts","sourceRoot":"","sources":["../../src/system/retention.ts"],"names":[],"mappings":"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"}