Data Purging

The "depends" project implements data purging to manage database growth, primarily by automatically removing old events while preserving node states and graph structure. This ensures efficient storage without losing critical configuration data. Events, which log state changes, have a fixed retention period, while other data like nodes and edges persists indefinitely unless manually deleted.

Purging occurs server-side and respects foreign key constraints with cascading deletes where applicable (see Database Schema).

Automatic Event Purging

Events in the events table record state transitions for nodes, including previous/new states, effective states, reasons, and solutions. To prevent unbounded growth, the system deletes events older than 30 days.

The core logic resides in src/purge.ts:

import type { Database } from "bun:sqlite";

const EVENT_RETENTION_DAYS = 30;

export function purgeExpiredEvents(db: Database): number {
  const cutoff = new Date(
    Date.now() - EVENT_RETENTION_DAYS * 24 * 60 * 60 * 1000,
  ).toISOString();

  const result = db
    .query("DELETE FROM events WHERE created_at < ?")
    .run(cutoff);

  return result.changes;
}

• Cutoff Calculation: Computes an ISO timestamp 30 days in the past using milliseconds.
• Query Efficiency: Leverages the index idx_events_ns on (ns_id, created_at) or idx_events_node for fast range deletes.
• Return Value: Number of rows affected (result.changes).

In Operating Modes, the server invokes this hourly:

// from src/server.ts
setInterval(() => purgeExpiredEvents(db), 60 * 60 * 1000);

In Operating Modes, the depends.cc service performs equivalent automated purging. No client-side configuration alters the 30-day retention; it is a project invariant (see Project Invariants).

Nodes themselves do not auto-purge, even if a ttl field exists in the schema. The parseTtl function in src/db.ts supports TTL parsing (e.g., "30s", "1h"), but no automatic expiration logic appears in the codebase. Node states remain queryable indefinitely via Cli like status or events.

Manual Namespace Deletion

To remove all data for a namespace—including nodes, edges, events, and notification rules—use the CLI delete command. This triggers a cascading delete due to foreign key constraints.

depends delete <namespace>

Implementation in src/cli/commands/delete.ts:

• Issues DELETE /namespaces/${ns} via the API.
• Server-side, deleting a namespaces row cascades to child tables (nodes, edges, notification_rules, events).

Confirmation output: Deleted namespace "${ns}" and all its data.

This is irreversible and removes usage stats contributions (see Events Auditing). Use with caution; no soft-delete or archive exists.

Design Decisions

• Events-Only Purging: Focuses on high-volume logs (events) while retaining graph structure (nodes/edges) for status queries and Graph Computation.
• Fixed Retention: 30 days balances debugging needs with storage costs; aligns with monthly [usage](usage.ts) reporting.
• No CLI Purge: Automatic server-side handling avoids misuse; manual deletion targets entire namespaces.
• Hosted Transparency: Users view recent events via depends events (Cli), unaware of backend purging.

For database details, see Database Schema. In Operating Modes, run depends admin for token inspection, but no purge-specific admin tools exist.