@agentlip/kernel 0.1.0

package/migrations/0001_schema_v1.sql

@@ -0,0 +1,156 @@
+-- Migration: 0001_schema_v1.sql
+-- Initial schema for Agentlip Local Hub v1
+-- From schema version: 0 (none)
+-- To schema version: 1
+
+BEGIN TRANSACTION;
+
+-- Meta table: system metadata and versioning
+CREATE TABLE IF NOT EXISTS meta (
+  key TEXT PRIMARY KEY NOT NULL,
+  value TEXT NOT NULL
+) STRICT;
+
+-- Required meta keys
+-- - db_id: stable workspace identifier (UUIDv4-ish), generated once at init
+-- - schema_version: current schema version
+-- - created_at: workspace creation timestamp (ISO8601 UTC)
+INSERT OR REPLACE INTO meta (key, value) VALUES ('schema_version', '1');
+INSERT OR IGNORE INTO meta (key, value)
+  VALUES ('created_at', strftime('%Y-%m-%dT%H:%M:%fZ', 'now'));
+INSERT OR IGNORE INTO meta (key, value) VALUES (
+  'db_id',
+  lower(hex(randomblob(4))) || '-' ||
+  lower(hex(randomblob(2))) || '-' ||
+  '4' || substr(lower(hex(randomblob(2))), 2) || '-' ||
+  substr('89ab', abs(random()) % 4 + 1, 1) || substr(lower(hex(randomblob(2))), 2) || '-' ||
+  lower(hex(randomblob(6)))
+);
+
+-- Channels: top-level conversation containers
+CREATE TABLE IF NOT EXISTS channels (
+  id TEXT PRIMARY KEY NOT NULL,
+  name TEXT NOT NULL UNIQUE,
+  description TEXT,
+  created_at TEXT NOT NULL,
+  CHECK (length(name) > 0 AND length(name) <= 100)
+) STRICT;
+
+-- Topics: first-class thread entities within channels
+CREATE TABLE IF NOT EXISTS topics (
+  id TEXT PRIMARY KEY NOT NULL,
+  channel_id TEXT NOT NULL,
+  title TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  FOREIGN KEY (channel_id) REFERENCES channels(id) ON DELETE CASCADE,
+  UNIQUE(channel_id, title),
+  CHECK (length(title) > 0 AND length(title) <= 200)
+) STRICT;
+
+CREATE INDEX IF NOT EXISTS idx_topics_channel ON topics(channel_id, updated_at DESC);
+
+-- Messages: content with stable identity, edit/delete via events
+CREATE TABLE IF NOT EXISTS messages (
+  id TEXT PRIMARY KEY NOT NULL,
+  topic_id TEXT NOT NULL,
+  channel_id TEXT NOT NULL,
+  sender TEXT NOT NULL,
+  content_raw TEXT NOT NULL,
+  version INTEGER NOT NULL DEFAULT 1,
+  created_at TEXT NOT NULL,
+  edited_at TEXT,
+  deleted_at TEXT,
+  deleted_by TEXT,
+  FOREIGN KEY (topic_id) REFERENCES topics(id) ON DELETE CASCADE,
+  CHECK (length(sender) > 0),
+  CHECK (length(content_raw) <= 65536),
+  CHECK (version >= 1)
+) STRICT;
+
+CREATE INDEX IF NOT EXISTS idx_messages_topic ON messages(topic_id, id DESC);
+CREATE INDEX IF NOT EXISTS idx_messages_channel ON messages(channel_id, id DESC);
+CREATE INDEX IF NOT EXISTS idx_messages_created ON messages(created_at DESC);
+
+-- Trigger: prevent hard deletes on messages (tombstone only)
+CREATE TRIGGER IF NOT EXISTS prevent_message_delete
+BEFORE DELETE ON messages
+FOR EACH ROW
+BEGIN
+  SELECT RAISE(ABORT, 'Hard deletes forbidden on messages; use tombstone');
+END;
+
+-- Events: immutable append-only event log (integration surface)
+CREATE TABLE IF NOT EXISTS events (
+  event_id INTEGER PRIMARY KEY AUTOINCREMENT,
+  ts TEXT NOT NULL,
+  name TEXT NOT NULL,
+  scope_channel_id TEXT,
+  scope_topic_id TEXT,
+  scope_topic_id2 TEXT,
+  entity_type TEXT NOT NULL,
+  entity_id TEXT NOT NULL,
+  data_json TEXT NOT NULL,
+  CHECK (length(name) > 0)
+) STRICT;
+
+CREATE INDEX IF NOT EXISTS idx_events_replay ON events(event_id);
+CREATE INDEX IF NOT EXISTS idx_events_scope_channel ON events(scope_channel_id, event_id);
+CREATE INDEX IF NOT EXISTS idx_events_scope_topic ON events(scope_topic_id, event_id);
+CREATE INDEX IF NOT EXISTS idx_events_scope_topic2 ON events(scope_topic_id2, event_id);
+
+-- Trigger: prevent updates on events (immutable)
+CREATE TRIGGER IF NOT EXISTS prevent_event_mutation
+BEFORE UPDATE ON events
+FOR EACH ROW
+BEGIN
+  SELECT RAISE(ABORT, 'Events are immutable');
+END;
+
+-- Trigger: prevent deletes on events (append-only)
+CREATE TRIGGER IF NOT EXISTS prevent_event_delete
+BEFORE DELETE ON events
+FOR EACH ROW
+BEGIN
+  SELECT RAISE(ABORT, 'Events are append-only');
+END;
+
+-- Topic attachments: structured grounding metadata with idempotency
+CREATE TABLE IF NOT EXISTS topic_attachments (
+  id TEXT PRIMARY KEY NOT NULL,
+  topic_id TEXT NOT NULL,
+  kind TEXT NOT NULL,
+  key TEXT,
+  value_json TEXT NOT NULL,
+  dedupe_key TEXT NOT NULL,
+  source_message_id TEXT,
+  created_at TEXT NOT NULL,
+  FOREIGN KEY (topic_id) REFERENCES topics(id) ON DELETE CASCADE,
+  FOREIGN KEY (source_message_id) REFERENCES messages(id) ON DELETE SET NULL,
+  CHECK (length(kind) > 0),
+  CHECK (length(dedupe_key) > 0),
+  CHECK (length(value_json) <= 16384)
+) STRICT;
+
+CREATE INDEX IF NOT EXISTS idx_attachments_topic ON topic_attachments(topic_id, created_at DESC);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_topic_attachments_dedupe
+  ON topic_attachments(topic_id, kind, COALESCE(key, ''), dedupe_key);
+
+-- Enrichments: derived data (recomputable)
+CREATE TABLE IF NOT EXISTS enrichments (
+  id TEXT PRIMARY KEY NOT NULL,
+  message_id TEXT NOT NULL,
+  kind TEXT NOT NULL,
+  span_start INTEGER NOT NULL,
+  span_end INTEGER NOT NULL,
+  data_json TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  FOREIGN KEY (message_id) REFERENCES messages(id) ON DELETE CASCADE,
+  CHECK (span_start >= 0),
+  CHECK (span_end > span_start),
+  CHECK (length(kind) > 0)
+) STRICT;
+
+CREATE INDEX IF NOT EXISTS idx_enrichments_message ON enrichments(message_id, created_at DESC);
+
+COMMIT;

package/migrations/0001_schema_v1_fts.sql

@@ -0,0 +1,32 @@
+-- Migration: 0001_schema_v1_fts.sql
+-- Optional FTS5 virtual table for full-text search on message content
+-- Applied opportunistically after schema_v1; non-fatal failure
+
+BEGIN TRANSACTION;
+
+-- FTS5 virtual table for message content search
+CREATE VIRTUAL TABLE IF NOT EXISTS messages_fts USING fts5(
+  content_raw,
+  content=messages,
+  content_rowid=rowid
+);
+
+-- Trigger: sync FTS on insert
+CREATE TRIGGER IF NOT EXISTS messages_fts_insert AFTER INSERT ON messages
+BEGIN
+  INSERT INTO messages_fts(rowid, content_raw) VALUES (new.rowid, new.content_raw);
+END;
+
+-- Trigger: sync FTS on update
+CREATE TRIGGER IF NOT EXISTS messages_fts_update AFTER UPDATE ON messages
+BEGIN
+  UPDATE messages_fts SET content_raw = new.content_raw WHERE rowid = old.rowid;
+END;
+
+-- Trigger: sync FTS on delete
+CREATE TRIGGER IF NOT EXISTS messages_fts_delete AFTER DELETE ON messages
+BEGIN
+  DELETE FROM messages_fts WHERE rowid = old.rowid;
+END;
+
+COMMIT;

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@agentlip/kernel",
+  "version": "0.1.0",
+  "description": "SQLite schema, migrations, and query layer for Agentlip",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://github.com/phosphorco/agentlip",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/phosphorco/agentlip.git",
+    "directory": "packages/kernel"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src/**/*.ts",
+    "migrations/**/*.sql",
+    "!src/**/*.test.ts"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  }
+}

package/src/events.ts

@@ -0,0 +1,365 @@
+/**
+ * Event insertion and replay utilities for @agentlip/kernel
+ * 
+ * Implements bd-16d.2.3 (canonical read queries for events) and bd-16d.2.9 (insertEvent helper)
+ */
+
+import type { Database } from "bun:sqlite";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface EventScopes {
+  channel_id?: string | null;
+  topic_id?: string | null;
+  topic_id2?: string | null;
+}
+
+export interface EventEntity {
+  type: string;
+  id: string;
+}
+
+export interface InsertEventOptions {
+  db: Database;
+  name: string;
+  scopes: EventScopes;
+  entity: EventEntity;
+  data: Record<string, unknown>;
+}
+
+export interface EventRow {
+  event_id: number;
+  ts: string;
+  name: string;
+  scope_channel_id: string | null;
+  scope_topic_id: string | null;
+  scope_topic_id2: string | null;
+  entity_type: string;
+  entity_id: string;
+  data_json: string;
+}
+
+export interface ParsedEvent {
+  event_id: number;
+  ts: string;
+  name: string;
+  scope: EventScopes;
+  entity: EventEntity;
+  data: Record<string, unknown>;
+}
+
+export interface ReplayEventsOptions {
+  db: Database;
+  afterEventId: number;
+  replayUntil: number;
+  channelIds?: string[];
+  topicIds?: string[];
+  limit?: number;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Event Scope Catalog
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Scope requirements for known v1 events.
+ * Unknown event names are allowed (for extensibility) and skip scope validation.
+ * 
+ * Implements bd-16d.2.10 (scope correctness) and bd-16d.2.11 (dev assertions).
+ */
+interface ScopeRequirements {
+  channel_id: boolean;  // true if channel_id is required
+  topic_id: boolean;    // true if topic_id is required
+  topic_id2: boolean;   // true if topic_id2 is required
+}
+
+const EVENT_SCOPE_CATALOG: Record<string, ScopeRequirements> = {
+  // Channel events: require channel_id only
+  "channel.created": { channel_id: true, topic_id: false, topic_id2: false },
+
+  // Topic events: require channel_id + topic_id
+  "topic.created": { channel_id: true, topic_id: true, topic_id2: false },
+  "topic.renamed": { channel_id: true, topic_id: true, topic_id2: false },
+  "topic.attachment_added": { channel_id: true, topic_id: true, topic_id2: false },
+
+  // Message events: require channel_id + topic_id (except moved_topic)
+  "message.created": { channel_id: true, topic_id: true, topic_id2: false },
+  "message.edited": { channel_id: true, topic_id: true, topic_id2: false },
+  "message.deleted": { channel_id: true, topic_id: true, topic_id2: false },
+  "message.enriched": { channel_id: true, topic_id: true, topic_id2: false },
+
+  // Message move: requires channel_id + topic_id (old) + topic_id2 (new)
+  "message.moved_topic": { channel_id: true, topic_id: true, topic_id2: true },
+};
+
+/**
+ * Validate event scopes against catalog requirements.
+ * 
+ * @param name - Event name
+ * @param scopes - Event scopes to validate
+ * @throws Error if required scopes are missing or invalid for known event types
+ */
+function validateEventScopes(name: string, scopes: EventScopes): void {
+  const requirements = EVENT_SCOPE_CATALOG[name];
+  
+  // Unknown event types are allowed (skip validation)
+  if (!requirements) {
+    return;
+  }
+
+  // Helper to check if a scope value is valid (present and non-empty)
+  const isValidScope = (value: string | null | undefined): value is string => {
+    return typeof value === "string" && value.trim().length > 0;
+  };
+
+  // Check each required scope
+  if (requirements.channel_id && !isValidScope(scopes.channel_id)) {
+    throw new Error(
+      `Event '${name}' requires scope.channel_id but it is missing or empty`
+    );
+  }
+
+  if (requirements.topic_id && !isValidScope(scopes.topic_id)) {
+    throw new Error(
+      `Event '${name}' requires scope.topic_id but it is missing or empty`
+    );
+  }
+
+  if (requirements.topic_id2 && !isValidScope(scopes.topic_id2)) {
+    throw new Error(
+      `Event '${name}' requires scope.topic_id2 but it is missing or empty`
+    );
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// insertEvent Helper
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Insert a new event into the events table.
+ * 
+ * Single entry point for all event insertions. Validates inputs and serializes
+ * data deterministically. Never mutates existing events (schema triggers prevent).
+ * 
+ * Enforces scope correctness per EVENT_SCOPE_CATALOG (bd-16d.2.10 + bd-16d.2.11).
+ * Unknown event names are allowed and skip scope validation.
+ * 
+ * @param options - Event insertion options
+ * @returns The inserted event_id (monotonically increasing)
+ * @throws Error if name is empty, entity fields empty, data is not a plain object, or scopes are invalid
+ */
+export function insertEvent(options: InsertEventOptions): number {
+  const { db, name, scopes, entity, data } = options;
+  
+  // Validate name
+  if (!name || typeof name !== "string" || name.trim().length === 0) {
+    throw new Error("Event name must be a non-empty string");
+  }
+  
+  // Validate scopes (bd-16d.2.10 + bd-16d.2.11)
+  validateEventScopes(name, scopes);
+  
+  // Validate entity
+  if (!entity.type || typeof entity.type !== "string" || entity.type.trim().length === 0) {
+    throw new Error("Entity type must be a non-empty string");
+  }
+  if (!entity.id || typeof entity.id !== "string" || entity.id.trim().length === 0) {
+    throw new Error("Entity id must be a non-empty string");
+  }
+  
+  // Validate data is a plain object (not null, array, or primitive)
+  if (data === null || data === undefined) {
+    throw new Error("Event data must be an object, got null/undefined");
+  }
+  if (Array.isArray(data)) {
+    throw new Error("Event data must be an object, not an array");
+  }
+  if (typeof data !== "object") {
+    throw new Error(`Event data must be an object, got ${typeof data}`);
+  }
+  
+  // Serialize data deterministically (JSON.stringify is deterministic for same input structure)
+  const dataJson = JSON.stringify(data);
+  
+  // Generate timestamp
+  const ts = new Date().toISOString();
+  
+  // Insert event
+  const stmt = db.prepare<
+    { event_id: number },
+    [string, string, string | null, string | null, string | null, string, string, string]
+  >(`
+    INSERT INTO events (ts, name, scope_channel_id, scope_topic_id, scope_topic_id2, entity_type, entity_id, data_json)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    RETURNING event_id
+  `);
+  
+  const result = stmt.get(
+    ts,
+    name,
+    scopes.channel_id ?? null,
+    scopes.topic_id ?? null,
+    scopes.topic_id2 ?? null,
+    entity.type,
+    entity.id,
+    dataJson
+  );
+  
+  if (!result) {
+    throw new Error("Failed to insert event: no event_id returned");
+  }
+  
+  return result.event_id;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Event Replay Queries
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Get the latest event_id from the events table.
+ * 
+ * Used for WS handshake to establish replay_until boundary.
+ * 
+ * @param db - Database instance
+ * @returns The maximum event_id, or 0 if no events exist
+ */
+export function getLatestEventId(db: Database): number {
+  const row = db
+    .query<{ max_id: number | null }, []>("SELECT MAX(event_id) as max_id FROM events")
+    .get();
+  
+  return row?.max_id ?? 0;
+}
+
+/**
+ * Parse a raw EventRow into a ParsedEvent with structured scope/entity/data.
+ */
+function parseEventRow(row: EventRow): ParsedEvent {
+  return {
+    event_id: row.event_id,
+    ts: row.ts,
+    name: row.name,
+    scope: {
+      channel_id: row.scope_channel_id,
+      topic_id: row.scope_topic_id,
+      topic_id2: row.scope_topic_id2,
+    },
+    entity: {
+      type: row.entity_type,
+      id: row.entity_id,
+    },
+    data: JSON.parse(row.data_json),
+  };
+}
+
+/**
+ * Replay events matching the specified criteria.
+ * 
+ * Implements the plan's replay query:
+ * WHERE event_id > after AND event_id <= replay_until 
+ * AND (scopes match) ORDER BY event_id ASC LIMIT ...
+ * 
+ * Scope matching logic:
+ * - If channelIds provided: events where scope_channel_id IN channelIds
+ * - If topicIds provided: events where scope_topic_id IN topicIds OR scope_topic_id2 IN topicIds
+ * - Both can be combined (OR: matches channel OR topic)
+ * - If neither provided: returns all events in range
+ * 
+ * @param options - Replay options
+ * @returns Array of parsed events in ascending event_id order
+ */
+export function replayEvents(options: ReplayEventsOptions): ParsedEvent[] {
+  const { db, afterEventId, replayUntil, channelIds, topicIds, limit = 1000 } = options;
+  
+  // Validate boundaries
+  if (afterEventId < 0) {
+    throw new Error("afterEventId must be >= 0");
+  }
+  if (replayUntil < afterEventId) {
+    throw new Error("replayUntil must be >= afterEventId");
+  }
+  if (limit <= 0) {
+    throw new Error("limit must be > 0");
+  }
+  
+  // Build query based on scope filters
+  const hasChannelFilter = channelIds && channelIds.length > 0;
+  const hasTopicFilter = topicIds && topicIds.length > 0;
+  
+  let sql = `
+    SELECT event_id, ts, name, scope_channel_id, scope_topic_id, scope_topic_id2, 
+           entity_type, entity_id, data_json
+    FROM events
+    WHERE event_id > ? AND event_id <= ?
+  `;
+  
+  const params: (number | string)[] = [afterEventId, replayUntil];
+  
+  if (hasChannelFilter || hasTopicFilter) {
+    const scopeConditions: string[] = [];
+    
+    if (hasChannelFilter) {
+      const placeholders = channelIds.map(() => "?").join(", ");
+      scopeConditions.push(`scope_channel_id IN (${placeholders})`);
+      params.push(...channelIds);
+    }
+    
+    if (hasTopicFilter) {
+      const placeholders = topicIds.map(() => "?").join(", ");
+      scopeConditions.push(`(scope_topic_id IN (${placeholders}) OR scope_topic_id2 IN (${placeholders}))`);
+      params.push(...topicIds, ...topicIds);
+    }
+    
+    sql += ` AND (${scopeConditions.join(" OR ")})`;
+  }
+  
+  sql += ` ORDER BY event_id ASC LIMIT ?`;
+  params.push(limit);
+  
+  const rows = db.query<EventRow, (number | string)[]>(sql).all(...params);
+  
+  return rows.map(parseEventRow);
+}
+
+/**
+ * Get a single event by its ID.
+ * 
+ * @param db - Database instance
+ * @param eventId - Event ID to retrieve
+ * @returns Parsed event or null if not found
+ */
+export function getEventById(db: Database, eventId: number): ParsedEvent | null {
+  const row = db
+    .query<EventRow, [number]>(`
+      SELECT event_id, ts, name, scope_channel_id, scope_topic_id, scope_topic_id2,
+             entity_type, entity_id, data_json
+      FROM events
+      WHERE event_id = ?
+    `)
+    .get(eventId);
+  
+  return row ? parseEventRow(row) : null;
+}
+
+/**
+ * Count events in a range (useful for pagination info).
+ * 
+ * @param db - Database instance
+ * @param afterEventId - Start boundary (exclusive)
+ * @param replayUntil - End boundary (inclusive)
+ * @returns Number of events in range
+ */
+export function countEventsInRange(db: Database, afterEventId: number, replayUntil: number): number {
+  const row = db
+    .query<{ count: number }, [number, number]>(`
+      SELECT COUNT(*) as count FROM events
+      WHERE event_id > ? AND event_id <= ?
+    `)
+    .get(afterEventId, replayUntil);
+  
+  return row?.count ?? 0;
+}