@schedulespark/observability 0.0.2-beta-1-0-0

package/dist/storage/migrations.js

@@ -0,0 +1,238 @@
+export /**
+        * All versioned migrations, applied in order.
+        */ const migrations = [
+    {
+        id: "0001_init",
+        sql: (schema) => `
+      CREATE TABLE IF NOT EXISTS ${schema}.issues (
+        id text PRIMARY KEY,
+        fingerprint text NOT NULL UNIQUE,
+        title text NOT NULL,
+        level text NOT NULL,
+        status text NOT NULL DEFAULT 'unresolved',
+        event_count integer NOT NULL DEFAULT 0,
+        first_seen timestamptz NOT NULL,
+        last_seen timestamptz NOT NULL
+      );
+
+      CREATE TABLE IF NOT EXISTS ${schema}.events (
+        id text PRIMARY KEY,
+        issue_id text NOT NULL REFERENCES ${schema}.issues(id) ON DELETE CASCADE,
+        fingerprint text NOT NULL,
+        level text NOT NULL,
+        message text NOT NULL,
+        error_type text,
+        stack_trace text,
+        context jsonb NOT NULL DEFAULT '{}'::jsonb,
+        captured_at timestamptz NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS events_issue_id_idx ON ${schema}.events (issue_id);
+      CREATE INDEX IF NOT EXISTS events_captured_at_idx ON ${schema}.events (captured_at DESC);
+      CREATE INDEX IF NOT EXISTS issues_last_seen_idx ON ${schema}.issues (last_seen DESC);
+    `
+    },
+    {
+        id: "0002_assignee_comments",
+        sql: (schema) => `
+      ALTER TABLE ${schema}.issues ADD COLUMN IF NOT EXISTS assignee text;
+
+      CREATE TABLE IF NOT EXISTS ${schema}.comments (
+        id text PRIMARY KEY,
+        issue_id text NOT NULL REFERENCES ${schema}.issues(id) ON DELETE CASCADE,
+        author text NOT NULL,
+        body text NOT NULL,
+        created_at timestamptz NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS comments_issue_id_idx ON ${schema}.comments (issue_id);
+    `
+    },
+    {
+        id: "0003_spans",
+        sql: (schema) => `
+      CREATE TABLE IF NOT EXISTS ${schema}.spans (
+        id text PRIMARY KEY,
+        trace_id text NOT NULL,
+        parent_id text,
+        name text NOT NULL,
+        status text NOT NULL,
+        started_at timestamptz NOT NULL,
+        duration_ms integer NOT NULL,
+        tags jsonb NOT NULL DEFAULT '{}'::jsonb
+      );
+
+      CREATE INDEX IF NOT EXISTS spans_trace_id_idx ON ${schema}.spans (trace_id);
+      CREATE INDEX IF NOT EXISTS spans_transactions_idx ON ${schema}.spans (started_at DESC)
+        WHERE parent_id IS NULL;
+    `
+    },
+    {
+        id: "0004_projects",
+        sql: (schema) => `
+      CREATE TABLE IF NOT EXISTS ${schema}.projects (
+        id text PRIMARY KEY,
+        name text NOT NULL,
+        api_key text UNIQUE,
+        created_at timestamptz NOT NULL DEFAULT now()
+      );
+
+      INSERT INTO ${schema}.projects (id, name, api_key, created_at)
+      VALUES ('default', 'Default', NULL, now())
+      ON CONFLICT (id) DO NOTHING;
+
+      ALTER TABLE ${schema}.issues
+        ADD COLUMN IF NOT EXISTS project_id text NOT NULL DEFAULT 'default' REFERENCES ${schema}.projects(id);
+      ALTER TABLE ${schema}.events
+        ADD COLUMN IF NOT EXISTS project_id text NOT NULL DEFAULT 'default' REFERENCES ${schema}.projects(id);
+
+      -- Fingerprints are now unique per-project, not globally.
+      ALTER TABLE ${schema}.issues DROP CONSTRAINT IF EXISTS issues_fingerprint_key;
+      CREATE UNIQUE INDEX IF NOT EXISTS issues_project_fingerprint_idx
+        ON ${schema}.issues (project_id, fingerprint);
+
+      CREATE INDEX IF NOT EXISTS issues_project_id_idx ON ${schema}.issues (project_id);
+      CREATE INDEX IF NOT EXISTS events_project_id_idx ON ${schema}.events (project_id);
+    `
+    },
+    {
+        id: "0005_breadcrumbs",
+        sql: (schema) => `
+      ALTER TABLE ${schema}.events
+        ADD COLUMN IF NOT EXISTS breadcrumbs jsonb NOT NULL DEFAULT '[]'::jsonb;
+    `
+    },
+    {
+        id: "0006_saved_views",
+        sql: (schema) => `
+      CREATE TABLE IF NOT EXISTS ${schema}.saved_views (
+        id text PRIMARY KEY,
+        name text NOT NULL,
+        filters jsonb NOT NULL DEFAULT '{}'::jsonb,
+        created_at timestamptz NOT NULL DEFAULT now()
+      );
+    `
+    },
+    {
+        id: "0007_logs",
+        sql: (schema) => `
+      CREATE TABLE IF NOT EXISTS ${schema}.logs (
+        id text PRIMARY KEY,
+        project_id text NOT NULL DEFAULT 'default' REFERENCES ${schema}.projects(id),
+        level text NOT NULL,
+        message text NOT NULL,
+        context jsonb NOT NULL DEFAULT '{}'::jsonb,
+        logged_at timestamptz NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS logs_logged_at_idx ON ${schema}.logs (logged_at DESC);
+      CREATE INDEX IF NOT EXISTS logs_project_id_idx ON ${schema}.logs (project_id);
+    `
+    },
+    {
+        id: "0008_metric_points_raw",
+        sql: (schema) => `
+      CREATE TABLE IF NOT EXISTS ${schema}.metric_points_raw (
+        id text PRIMARY KEY,
+        project_id text NOT NULL DEFAULT 'default' REFERENCES ${schema}.projects(id),
+        name text NOT NULL,
+        kind text NOT NULL,
+        value double precision NOT NULL,
+        tags jsonb NOT NULL DEFAULT '{}'::jsonb,
+        recorded_at timestamptz NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS metric_points_raw_recorded_at_idx ON ${schema}.metric_points_raw (recorded_at DESC);
+      CREATE INDEX IF NOT EXISTS metric_points_raw_name_idx ON ${schema}.metric_points_raw (project_id, name);
+    `
+    },
+    {
+        id: "0009_metric_rollups",
+        sql: (schema) => `
+      CREATE TABLE IF NOT EXISTS ${schema}.metric_rollups (
+        id text PRIMARY KEY,
+        project_id text NOT NULL DEFAULT 'default' REFERENCES ${schema}.projects(id),
+        name text NOT NULL,
+        kind text NOT NULL,
+        bucket_start timestamptz NOT NULL,
+        bucket_size text NOT NULL,
+        tags jsonb NOT NULL DEFAULT '{}'::jsonb,
+        sum double precision NOT NULL,
+        count integer NOT NULL,
+        min double precision NOT NULL,
+        max double precision NOT NULL
+      );
+
+      -- jsonb equality identifies "this metric/tag-combination/bucket" for the rollup upsert.
+      CREATE UNIQUE INDEX IF NOT EXISTS metric_rollups_unique_bucket_idx
+        ON ${schema}.metric_rollups (project_id, name, tags, bucket_start, bucket_size);
+      CREATE INDEX IF NOT EXISTS metric_rollups_name_idx ON ${schema}.metric_rollups (project_id, name);
+    `
+    }
+];
+/**
+ * Ensures the observability schema, migration-tracking table, and all pending
+ * migrations exist. Safe to call concurrently from multiple pools/processes against
+ * the same database (e.g. a Node SDK client and a dashboard server booting at the same
+ * time): a Postgres advisory lock, scoped to the schema name, serializes migration
+ * runs so `CREATE SCHEMA IF NOT EXISTS` races can never produce a duplicate-key error.
+ */
+export async function migrate(pool, quotedSchema) {
+    const client = await pool.connect();
+    try {
+        await withAdvisoryLock(client, quotedSchema, () => runMigrations(client, quotedSchema));
+    }
+    finally {
+        client.release();
+    }
+}
+/**
+ * Runs a function while holding a session-scoped Postgres advisory lock keyed by the
+ * schema name, releasing it afterward even if the function throws.
+ */
+async function withAdvisoryLock(client, quotedSchema, run) {
+    await client.query("SELECT pg_advisory_lock(hashtext($1)::bigint)", [quotedSchema]);
+    try {
+        await run();
+    }
+    finally {
+        await client.query("SELECT pg_advisory_unlock(hashtext($1)::bigint)", [quotedSchema]);
+    }
+}
+/**
+ * Creates the schema and migration-tracking table if needed, then applies any
+ * migrations that haven't been recorded yet.
+ */
+async function runMigrations(client, quotedSchema) {
+    await client.query(`CREATE SCHEMA IF NOT EXISTS ${quotedSchema}`);
+    await client.query(`
+    CREATE TABLE IF NOT EXISTS ${quotedSchema}._migrations (
+      id text PRIMARY KEY,
+      applied_at timestamptz NOT NULL DEFAULT now()
+    )
+  `);
+    for (const migration of migrations) {
+        await applyIfPending(client, quotedSchema, migration);
+    }
+}
+/**
+ * Applies a single migration inside a transaction if it hasn't been recorded yet.
+ */
+async function applyIfPending(client, quotedSchema, migration) {
+    const { rows } = await client.query(`SELECT id FROM ${quotedSchema}._migrations WHERE id = $1`, [migration.id]);
+    if (rows.length > 0) {
+        return;
+    }
+    try {
+        await client.query("BEGIN");
+        await client.query(migration.sql(quotedSchema));
+        await client.query(`INSERT INTO ${quotedSchema}._migrations (id) VALUES ($1)`, [
+            migration.id
+        ]);
+        await client.query("COMMIT");
+    }
+    catch (error) {
+        await client.query("ROLLBACK");
+        throw error;
+    }
+}

package/dist/storage/pool.d.ts

@@ -0,0 +1,30 @@
+import { Pool } from "pg";
+/**
+ * Options for connecting the observability storage layer to a Postgres database.
+ */
+export interface StorageOptions {
+    connectionString: string;
+    schema?: string;
+}
+/**
+ * A connected storage handle: the underlying pool, the quoted schema identifier every
+ * query is scoped to, and a `ready` promise that resolves once migrations have been
+ * applied (or rejects if they failed). Every query function awaits `ready` first, so
+ * it's always safe to query a handle immediately after `createStorage()` returns.
+ */
+export interface StorageHandle {
+    pool: Pool;
+    schema: string;
+    quotedSchema: string;
+    ready: Promise<void>;
+}
+/**
+ * Opens a connection pool for the observability database, scoped to its own schema so
+ * it can coexist safely inside a host application's existing database, and starts
+ * migrating that schema in the background (never blocking the caller).
+ */
+export declare function createStorage(options: StorageOptions): StorageHandle;
+/**
+ * Closes the underlying connection pool. Safe to call during graceful shutdown.
+ */
+export declare function closeStorage(handle: StorageHandle): Promise<void>;

package/dist/storage/pool.js

@@ -0,0 +1,28 @@
+import { Pool } from "pg";
+import { migrate } from "./migrations.js";
+import { quoteSchemaIdentifier } from "./schema-ident.js";
+const DEFAULT_SCHEMA = "observability";
+/**
+ * Opens a connection pool for the observability database, scoped to its own schema so
+ * it can coexist safely inside a host application's existing database, and starts
+ * migrating that schema in the background (never blocking the caller).
+ */
+export function createStorage(options) {
+    const schema = options.schema ?? DEFAULT_SCHEMA;
+    const quotedSchema = quoteSchemaIdentifier(schema);
+    const pool = new Pool({ connectionString: options.connectionString });
+    pool.on("error", (error) => {
+        console.error("[observability] idle Postgres client error", error);
+    });
+    const ready = migrate(pool, quotedSchema);
+    // Mark the rejection as handled so Node doesn't warn/crash if a caller never
+    // awaits `ready` themselves; the real rejection is still observable through it.
+    ready.catch(() => undefined);
+    return { pool, schema, quotedSchema, ready };
+}
+/**
+ * Closes the underlying connection pool. Safe to call during graceful shutdown.
+ */
+export async function closeStorage(handle) {
+    await handle.pool.end();
+}

package/dist/storage/projects.d.ts

@@ -0,0 +1,17 @@
+import type { StorageHandle } from "./pool.js";
+import type { Project } from "../core/index.js";
+/**
+ * Creates a new project with a freshly generated API key, used by ingestion clients
+ * to identify which project an event belongs to.
+ */
+export declare function createProject(handle: StorageHandle, name: string): Promise<Project>;
+/**
+ * Lists all projects, oldest first (so the auto-created `default` project sorts
+ * first).
+ */
+export declare function listProjects(handle: StorageHandle): Promise<Project[]>;
+/**
+ * Looks up the project an ingestion API key belongs to, or `null` if it doesn't match
+ * any configured project.
+ */
+export declare function findProjectByApiKey(handle: StorageHandle, apiKey: string): Promise<Project | null>;

package/dist/storage/projects.js

@@ -0,0 +1,31 @@
+import { randomBytes, randomUUID } from "node:crypto";
+import { mapProjectRow } from "./rows.js";
+const API_KEY_BYTES = 24;
+/**
+ * Creates a new project with a freshly generated API key, used by ingestion clients
+ * to identify which project an event belongs to.
+ */
+export async function createProject(handle, name) {
+    await handle.ready;
+    const { rows } = await handle.pool.query(`INSERT INTO ${handle.quotedSchema}.projects (id, name, api_key, created_at)
+     VALUES ($1, $2, $3, now()) RETURNING *`, [randomUUID(), name, randomBytes(API_KEY_BYTES).toString("hex")]);
+    return mapProjectRow(rows[0]);
+}
+/**
+ * Lists all projects, oldest first (so the auto-created `default` project sorts
+ * first).
+ */
+export async function listProjects(handle) {
+    await handle.ready;
+    const { rows } = await handle.pool.query(`SELECT * FROM ${handle.quotedSchema}.projects ORDER BY created_at ASC`);
+    return rows.map(mapProjectRow);
+}
+/**
+ * Looks up the project an ingestion API key belongs to, or `null` if it doesn't match
+ * any configured project.
+ */
+export async function findProjectByApiKey(handle, apiKey) {
+    await handle.ready;
+    const { rows } = await handle.pool.query(`SELECT * FROM ${handle.quotedSchema}.projects WHERE api_key = $1`, [apiKey]);
+    return rows.length > 0 ? mapProjectRow(rows[0]) : null;
+}

package/dist/storage/queries.d.ts

@@ -0,0 +1,48 @@
+import type { StorageHandle } from "./pool.js";
+import type { CapturedEvent, CaptureInput, Comment, Issue, IssueStatus } from "../core/index.js";
+/**
+ * Result of recording a single captured event.
+ */
+export interface RecordEventResult {
+    event: CapturedEvent;
+    issue: Issue;
+    isNewIssue: boolean;
+    isRegression: boolean;
+}
+/**
+ * Records a captured event: upserts the owning issue (creating it on first
+ * occurrence, bumping its counters otherwise) and inserts the event row, all inside a
+ * single transaction so the two stay consistent. Events default to the `"default"`
+ * project when the caller doesn't configure multi-project support, so this is a
+ * purely additive parameter.
+ */
+export declare function recordEvent(handle: StorageHandle, input: CaptureInput, projectId?: string): Promise<RecordEventResult>;
+/**
+ * Lists issues ordered by most recently seen, optionally filtered by status and/or a
+ * case-insensitive substring match on the title.
+ */
+export declare function listIssues(handle: StorageHandle, options?: {
+    status?: IssueStatus;
+    q?: string;
+    limit?: number;
+    projectId?: string;
+}): Promise<Issue[]>;
+/**
+ * Fetches a single issue, its most recent events, and its comments, or `null` if it
+ * doesn't exist (or belongs to a different project than `projectId`, when given).
+ */
+export declare function getIssueWithEvents(handle: StorageHandle, issueId: string, projectId?: string): Promise<{
+    issue: Issue;
+    events: CapturedEvent[];
+    comments: Comment[];
+} | null>;
+/**
+ * Updates an issue's workflow status, returning the updated issue or `null` if it
+ * doesn't exist.
+ */
+export declare function updateIssueStatus(handle: StorageHandle, issueId: string, status: IssueStatus): Promise<Issue | null>;
+/**
+ * Assigns (or unassigns, with `null`) an issue, returning the updated issue or `null`
+ * if it doesn't exist.
+ */
+export declare function assignIssue(handle: StorageHandle, issueId: string, assignee: string | null): Promise<Issue | null>;

package/dist/storage/queries.js

@@ -0,0 +1,146 @@
+import { randomUUID } from "node:crypto";
+import { computeFingerprint } from "../core/fingerprint.js";
+import { DEFAULT_PROJECT_ID } from "../core/index.js";
+import { listComments } from "./comments.js";
+import { deriveTitle, mapEventRow, mapIssueRow } from "./rows.js";
+const DEFAULT_ISSUE_LIST_LIMIT = 100;
+const DEFAULT_EVENT_LIST_LIMIT = 50;
+/**
+ * Records a captured event: upserts the owning issue (creating it on first
+ * occurrence, bumping its counters otherwise) and inserts the event row, all inside a
+ * single transaction so the two stay consistent. Events default to the `"default"`
+ * project when the caller doesn't configure multi-project support, so this is a
+ * purely additive parameter.
+ */
+export async function recordEvent(handle, input, projectId = DEFAULT_PROJECT_ID) {
+    await handle.ready;
+    const data = { input, fingerprint: computeFingerprint(input), now: new Date(), projectId };
+    const client = await handle.pool.connect();
+    try {
+        await client.query("BEGIN");
+        const issueRow = await upsertIssue(client, handle.quotedSchema, data);
+        const eventRow = await insertEvent(client, handle.quotedSchema, data);
+        await client.query("COMMIT");
+        return {
+            event: mapEventRow(eventRow),
+            issue: mapIssueRow(issueRow),
+            isNewIssue: issueRow.event_count === 1,
+            isRegression: issueRow.event_count > 1 && issueRow.previous_status === "resolved"
+        };
+    }
+    catch (error) {
+        await client.query("ROLLBACK");
+        throw error;
+    }
+    finally {
+        client.release();
+    }
+}
+/**
+ * Inserts a new issue row for a fingerprint or, if one already exists, bumps its
+ * event count and last-seen timestamp. A fresh event on a previously `resolved`
+ * issue automatically reopens it (back to `unresolved`) — `ignored` issues are left
+ * alone, since that status is a deliberate "don't tell me about this" choice rather
+ * than "this is fixed." The pre-update status is returned as `previous_status` so the
+ * caller can detect that reopen and fire a distinct regression alert.
+ */
+async function upsertIssue(client, quotedSchema, data) {
+    const { rows } = await client.query(`WITH previous AS (
+       SELECT status FROM ${quotedSchema}.issues WHERE project_id = $2 AND fingerprint = $3
+     )
+     INSERT INTO ${quotedSchema}.issues
+       (id, project_id, fingerprint, title, level, status, event_count, first_seen, last_seen)
+     VALUES ($1, $2, $3, $4, $5, 'unresolved', 1, $6, $6)
+     ON CONFLICT (project_id, fingerprint) DO UPDATE SET
+       event_count = ${quotedSchema}.issues.event_count + 1,
+       last_seen = $6,
+       status = CASE
+         WHEN ${quotedSchema}.issues.status = 'resolved' THEN 'unresolved'
+         ELSE ${quotedSchema}.issues.status
+       END
+     RETURNING ${quotedSchema}.issues.*, (SELECT status FROM previous) AS previous_status`, [randomUUID(), data.projectId, data.fingerprint, deriveTitle(data.input), data.input.level, data.now]);
+    return rows[0];
+}
+/**
+ * Inserts a single event row, linked to its issue by fingerprint.
+ */
+async function insertEvent(client, quotedSchema, data) {
+    const { rows } = await client.query(`INSERT INTO ${quotedSchema}.events
+       (id, issue_id, project_id, fingerprint, level, message, error_type, stack_trace, context, breadcrumbs, captured_at)
+     VALUES (
+       $1,
+       (SELECT id FROM ${quotedSchema}.issues WHERE project_id = $2 AND fingerprint = $3),
+       $2, $3, $4, $5, $6, $7, $8, $9, $10
+     )
+     RETURNING *`, [
+        randomUUID(),
+        data.projectId,
+        data.fingerprint,
+        data.input.level,
+        data.input.message,
+        data.input.errorType ?? null,
+        data.input.stackTrace ?? null,
+        data.input.context ?? {},
+        JSON.stringify(data.input.breadcrumbs ?? []),
+        data.now
+    ]);
+    return rows[0];
+}
+/**
+ * Lists issues ordered by most recently seen, optionally filtered by status and/or a
+ * case-insensitive substring match on the title.
+ */
+export async function listIssues(handle, options = {}) {
+    await handle.ready;
+    const params = [];
+    const conditions = [];
+    if (options.projectId) {
+        params.push(options.projectId);
+        conditions.push(`project_id = $${String(params.length)}`);
+    }
+    if (options.status) {
+        params.push(options.status);
+        conditions.push(`status = $${String(params.length)}`);
+    }
+    if (options.q) {
+        params.push(`%${options.q}%`);
+        conditions.push(`title ILIKE $${String(params.length)}`);
+    }
+    params.push(options.limit ?? DEFAULT_ISSUE_LIST_LIMIT);
+    const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+    const { rows } = await handle.pool.query(`SELECT * FROM ${handle.quotedSchema}.issues ${where} ORDER BY last_seen DESC LIMIT $${String(params.length)}`, params);
+    return rows.map(mapIssueRow);
+}
+/**
+ * Fetches a single issue, its most recent events, and its comments, or `null` if it
+ * doesn't exist (or belongs to a different project than `projectId`, when given).
+ */
+export async function getIssueWithEvents(handle, issueId, projectId) {
+    await handle.ready;
+    const params = projectId ? [issueId, projectId] : [issueId];
+    const { rows: issueRows } = await handle.pool.query(`SELECT * FROM ${handle.quotedSchema}.issues WHERE id = $1 ${projectId ? "AND project_id = $2" : ""}`, params);
+    if (issueRows.length === 0) {
+        return null;
+    }
+    const { rows: eventRows } = await handle.pool.query(`SELECT * FROM ${handle.quotedSchema}.events WHERE issue_id = $1 ORDER BY captured_at DESC LIMIT $2`, [issueId, DEFAULT_EVENT_LIST_LIMIT]);
+    const comments = await listComments(handle, issueId);
+    return { issue: mapIssueRow(issueRows[0]), events: eventRows.map(mapEventRow), comments };
+}
+/**
+ * Updates an issue's workflow status, returning the updated issue or `null` if it
+ * doesn't exist.
+ */
+export async function updateIssueStatus(handle, issueId, status) {
+    await handle.ready;
+    const { rows } = await handle.pool.query(`UPDATE ${handle.quotedSchema}.issues SET status = $2 WHERE id = $1 RETURNING *`, [issueId, status]);
+    return rows.length > 0 ? mapIssueRow(rows[0]) : null;
+}
+/**
+ * Assigns (or unassigns, with `null`) an issue, returning the updated issue or `null`
+ * if it doesn't exist.
+ */
+export async function assignIssue(handle, issueId, assignee) {
+    await handle.ready;
+    const { rows } = await handle.pool.query(`UPDATE ${handle.quotedSchema}.issues SET assignee = $2 WHERE id = $1 RETURNING *`, [issueId, assignee]);
+    return rows.length > 0 ? mapIssueRow(rows[0]) : null;
+}

package/dist/storage/retention.d.ts

@@ -0,0 +1,28 @@
+import type { StorageHandle } from "./pool.js";
+/**
+ * Result of a prune operation.
+ */
+export interface PruneResult {
+    deletedEvents: number;
+}
+/**
+ * Deletes events older than the given retention window, keeping their owning issues
+ * (and aggregate counts) intact — only the individual event detail rows (stack
+ * traces, context) are dropped. A stopgap against unbounded table growth ahead of
+ * proper rollup tables: since this writes into the caller's own database, nothing
+ * prunes it automatically unless the deployer schedules this themselves (CLI `prune`
+ * or a direct call).
+ */
+export declare function pruneEvents(handle: StorageHandle, olderThanDays: number): Promise<PruneResult>;
+/**
+ * Result of pruning old log lines.
+ */
+export interface PruneLogsResult {
+    deletedLogs: number;
+}
+/**
+ * Deletes log lines older than the given retention window. Logs are typically much
+ * higher-volume than events, so this is a separate operation with its own (usually
+ * shorter) retention window rather than folding into `pruneEvents`.
+ */
+export declare function pruneLogs(handle: StorageHandle, olderThanDays: number): Promise<PruneLogsResult>;

package/dist/storage/retention.js

@@ -0,0 +1,29 @@
+/**
+ * Deletes events older than the given retention window, keeping their owning issues
+ * (and aggregate counts) intact — only the individual event detail rows (stack
+ * traces, context) are dropped. A stopgap against unbounded table growth ahead of
+ * proper rollup tables: since this writes into the caller's own database, nothing
+ * prunes it automatically unless the deployer schedules this themselves (CLI `prune`
+ * or a direct call).
+ */
+export async function pruneEvents(handle, olderThanDays) {
+    if (!Number.isInteger(olderThanDays) || olderThanDays <= 0) {
+        throw new Error(`olderThanDays must be a positive integer, got ${String(olderThanDays)}`);
+    }
+    await handle.ready;
+    const { rowCount } = await handle.pool.query(`DELETE FROM ${handle.quotedSchema}.events WHERE captured_at < now() - ($1 || ' days')::interval`, [olderThanDays]);
+    return { deletedEvents: rowCount ?? 0 };
+}
+/**
+ * Deletes log lines older than the given retention window. Logs are typically much
+ * higher-volume than events, so this is a separate operation with its own (usually
+ * shorter) retention window rather than folding into `pruneEvents`.
+ */
+export async function pruneLogs(handle, olderThanDays) {
+    if (!Number.isInteger(olderThanDays) || olderThanDays <= 0) {
+        throw new Error(`olderThanDays must be a positive integer, got ${String(olderThanDays)}`);
+    }
+    await handle.ready;
+    const { rowCount } = await handle.pool.query(`DELETE FROM ${handle.quotedSchema}.logs WHERE logged_at < now() - ($1 || ' days')::interval`, [olderThanDays]);
+    return { deletedLogs: rowCount ?? 0 };
+}