/** * First-run seed content. _guide explains the knowledge model in rows; * _schema_docs documents extension-owned tables. Agents may append their own * rows to both; system rows carry author='system'. */ export type GuideRow = { topic: string; body: string }; export type SchemaDocRow = { table: string; purpose: string; columns: string; kind: string; }; export const SCHEMA_VERSION = 2; export const APPLICATION_ID = 0x50494d45; // "PIME" export const MAX_INLINE_ROWS = 50; export const DEFAULT_TIMEOUT_MS = 30_000; export const MAX_TIMEOUT_MS = 300_000; export const MAX_SQL_LENGTH = 32_000; export const UNDO_MAX_SNAPSHOTS = 20; export const UNDO_MAX_BYTES: number = 64 * 1024 * 1024; export const UNDO_MAX_AGE_DAYS = 30; export const JOURNAL_MAX_ROWS = 5_000; export const JOURNAL_MAX_AGE_DAYS = 90; export const SPILL_MAX_AGE_HOURS = 24; export const GUIDE_SEED: readonly GuideRow[] = [ { topic: "purpose", body: "You are reading an agent-owned knowledge store: one local SQLite database. You choose the schema, you own the data, you evolve it with full SQL (CREATE, ALTER, DROP, INSERT, UPDATE, DELETE, indexes, views, FTS5). Before your first write, read this guide and SELECT * FROM _schema_docs.", }, { topic: "facts", body: "A fact is information at a point in time. Store facts as rows: the value plus observed_at (when reality said so), a source (where it came from), and a confidence or uncertainty note when useful. Keep facts terse, atomic, and self-contained.", }, { topic: "time", body: "observed_at is valid time (when the fact held in reality); recorded_at is transaction time (when you stored it). Prefer recorded_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')). Events are append-only: never UPDATE them, add new ones.", }, { topic: "context", body: "One shared database serves every project and session. Context is data, not files: label rows with columns like project, topic, or session. Query across projects with WHERE; do not invent per-project tables for the same kind of fact.", }, { topic: "events", body: "An event is a state transition at some time and place. Store events in append-only tables keyed by occurred_at; the table itself is the log. Current state = latest event per entity, or a separate state table you rebuild.", }, { topic: "relations", body: "Relations are data: an edges table (from_id, kind, to_id) or normalized link tables. SQL is the algebra over all of this: joins are how relations compose.", }, { topic: "example", body: "CREATE TABLE facts(entity TEXT NOT NULL, attribute TEXT NOT NULL, value TEXT NOT NULL, observed_at TEXT NOT NULL, recorded_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')), source TEXT, confidence REAL DEFAULT 0.8, project TEXT, topic TEXT); CREATE TABLE events(kind TEXT NOT NULL, subject TEXT NOT NULL, payload TEXT, occurred_at TEXT NOT NULL, project TEXT); CREATE TABLE edges(from_id TEXT NOT NULL, kind TEXT NOT NULL, to_id TEXT NOT NULL, since TEXT);", }, { topic: "document", body: 'After CREATE or ALTER, INSERT a row into _schema_docs("table", purpose, columns, kind, author) describing the table: purpose in one sentence, columns briefly, kind one of facts|events|edges|state|index|other. The column named "table" must stay double-quoted in SQL. Undocumented tables are flagged in the viewer; the next agent reads _schema_docs before writing.', }, { topic: "multi", body: "Multiple statements per call autocommit one by one: if a later statement fails, earlier ones stay applied. Check the journal seq, repair, and re-verify instead of blind-retrying; params bind to a single statement only.", }, { topic: "reserved", body: "_journal, _stats_samples, and _health_runs are extension-owned (audit journal, size samples, health history): readable, not writable. _guide and _schema_docs accept appended rows from agents (author='agent'). PRAGMA application_id, user_version, journal_mode, locking_mode are reserved.", }, { topic: "boundaries", body: "ATTACH and VACUUM INTO are blocked: everything stays in the one journaled file. Scratch work belongs in CREATE TEMP TABLE or a scratch table you later drop. Results above 50 rows are truncated inline and spilled to a temp NDJSON file (path in the result). Statements may time out (default 30s, timeoutMs parameter up to 300s): split large UPDATEs into bounded batches.", }, { topic: "search", body: "For text search create an FTS5 virtual table and keep it in sync in the same transaction as your writes. Tokenization splits on punctuation, not camelCase: 'OpenTofu' is one token, so MATCH 'tofu' and 'tofu*' miss it; use the full token or substring via LIKE '%…%' (slower, no index).", }, { topic: "rules", body: "Never store secrets: the database is shared plaintext, not an access-control boundary. Prefer provenance columns (source, confidence). Behavioral rules belong in maintained instruction files, not in this store. Keep transactions short; long locks stall other sessions.", }, ]; export const SCHEMA_DOC_SEED: readonly SchemaDocRow[] = [ { table: "_journal", purpose: "Extension-owned audit journal: one row per SQL call with actor, timing, rows, tables touched, and undo snapshot paths.", columns: "seq, ts, actor('agent'|'human'), mode(read|write|ddl|undo|fix), readonly, sql, params, rowsReturned, rowsWritten, spilledTo, durationMs, ok, error, tablesTouched, schemaChanged, attachedEscaped, undoPath, undone", kind: "other", }, { table: "_stats_samples", purpose: "Extension-owned per-object size samples taken when the viewer opens; powers growth graphs.", columns: "ts, name, type(table|index|schema), bytes, pages, rows", kind: "other", }, { table: "_health_runs", purpose: "Extension-owned health check history: integrity verdicts and rates.", columns: "ts, verdict(ok|warning|error), checks", kind: "other", }, ];