@pella-labs/pinakes 0.1.0

package/dist/db/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/db/schema.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAMH;;;;;;;;GAQG;AACH,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAGjB,CAAC;AAOH;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkCnB,CAAC;AAOF;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiBnB,CAAC;AAMF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqBpB,CAAC;AAMF;;;;;;;;GAQG;AACH,eAAO,MAAM,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgBjB,CAAC;AAMF;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAOjB,CAAC;AAMH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAQlB,CAAC;AAMH,MAAM,MAAM,MAAM,GAAG,OAAO,OAAO,CAAC,YAAY,CAAC;AACjD,MAAM,MAAM,SAAS,GAAG,OAAO,OAAO,CAAC,YAAY,CAAC;AACpD,MAAM,MAAM,OAAO,GAAG,OAAO,QAAQ,CAAC,YAAY,CAAC;AACnD,MAAM,MAAM,UAAU,GAAG,OAAO,QAAQ,CAAC,YAAY,CAAC;AACtD,MAAM,MAAM,MAAM,GAAG,OAAO,OAAO,CAAC,YAAY,CAAC;AACjD,MAAM,MAAM,SAAS,GAAG,OAAO,OAAO,CAAC,YAAY,CAAC;AACpD,MAAM,MAAM,QAAQ,GAAG,OAAO,KAAK,CAAC,YAAY,CAAC;AACjD,MAAM,MAAM,WAAW,GAAG,OAAO,KAAK,CAAC,YAAY,CAAC;AAEpD;;;GAGG;AACH,eAAO,MAAM,SAAS,4FAQZ,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,iBAAiB,6CAA8C,CAAC"}

package/dist/db/schema.js

@@ -0,0 +1,259 @@
+import { sql } from 'drizzle-orm';
+import { sqliteTable, text, integer, index, primaryKey } from 'drizzle-orm/sqlite-core';
+/**
+ * KG-MCP Drizzle schema (presearch.md §2.3, CLAUDE.md §Database Rules).
+ *
+ * 8 logical tables + `kg_meta` for schema versioning. Two of the eight are
+ * virtual tables (`kg_chunks_fts`, `kg_chunks_vec`) that drizzle-kit can't
+ * model — they're created via raw SQL appended to the initial migration in
+ * src/db/migrations. The drizzle code below covers the 7 regular tables
+ * plus kg_meta.
+ *
+ * Invariants this schema MUST preserve:
+ *
+ * - `kg_nodes.id` is `sha1(scope + ':' + source_uri + ':' + section_path)`,
+ *   set by the ingester (NOT auto-generated). Re-ingesting the same
+ *   markdown produces identical ids — Phase 2's idempotent upsert relies
+ *   on this. The DB never sees the hashing logic; it just stores the value
+ *   and enforces uniqueness via the PK.
+ *
+ * - `kg_chunks.id` is `sha1(node_id + ':' + chunk_index)`, same idea.
+ *
+ * - `chunk_sha = sha1(chunk_text)` is the LOAD-BEARING field for the
+ *   per-chunk skip-unchanged optimization (CLAUDE.md §Database Rules #3,
+ *   Loop 6.5 A4). On a Pharos wiki-updater whole-file rewrite we look up
+ *   the existing chunk_shas for the file's nodes and only re-embed chunks
+ *   whose sha changed. Without this, every turn re-embeds 60 chunks ×
+ *   ~50ms = 3s of blocking work that competes with the active coding LLM
+ *   for Ollama. Do not remove this column.
+ *
+ * - `last_accessed_at` on `kg_nodes` exists for the Phase 5 personal-KG
+ *   LRU eviction (Loop 6.5 A2). Phase 2 just stamps it on insert/update.
+ *
+ * - `source_sha` on `kg_nodes` is the file-level hash; staleness detection
+ *   on the query path compares this against the current on-disk hash.
+ *
+ * - All FK relationships use `ON DELETE CASCADE` so deleting a node cleans
+ *   up its chunks and edges in one statement (verified by schema test #5).
+ *   Foreign keys are enforced via PRAGMA foreign_keys=ON, mandatory on
+ *   every connection in client.ts.
+ */
+// ----------------------------------------------------------------------------
+// kg_meta — schema versioning + bookkeeping
+// ----------------------------------------------------------------------------
+/**
+ * Tiny key/value table holding `schema_version`, `last_full_rebuild`, and
+ * any other one-off bookkeeping. Sized for handfuls of rows.
+ *
+ * Stamped at first openDb() call by client.ts if absent. The schema_version
+ * value lets us detect drift on startup and either run new migrations or
+ * (in the worst case for sqlite-vec breaking changes) drop + rebuild the
+ * vec virtual table from markdown.
+ */
+export const kgMeta = sqliteTable('kg_meta', {
+    key: text('key').primaryKey(),
+    value: text('value'),
+});
+// ----------------------------------------------------------------------------
+// kg_nodes — markdown sections + concept entities (Phase 2 only writes
+// kind='section' rows; Phase 4 adds entities, Phase 6 adds gaps)
+// ----------------------------------------------------------------------------
+/**
+ * One row per markdown section. The "primary unit" of the KG — chunks belong
+ * to nodes, edges connect nodes.
+ *
+ * `kind` is open-ended for forward compatibility:
+ *   - `'section'` — the only kind Phase 2 writes; one per ATX heading
+ *   - `'entity' | 'concept' | 'decision' | 'log_entry' | 'gap'` — Phase 4-6
+ *
+ * `section_path` is the ATX heading hierarchy joined by ` / ` (e.g.
+ * `"Authentication / Login flow"` for an `## Login flow` under `# Authentication`).
+ * Empty string for top-of-file content above any heading.
+ *
+ * `content` stores the full section markdown (heading + body). Chunks are
+ * derived from this and stored separately in kg_chunks. We keep both because
+ * `kg_execute` callers may want the whole section (`kg.get(node_id)`) instead
+ * of paragraph-sized chunks.
+ */
+export const kgNodes = sqliteTable('kg_nodes', {
+    /** sha1(scope + ':' + source_uri + ':' + section_path), set by ingester */
+    id: text('id').primaryKey(),
+    /** 'project' | 'personal' — enforced at app layer, not as a CHECK */
+    scope: text('scope').notNull(),
+    /** file:// URL of the source markdown file */
+    sourceUri: text('source_uri').notNull(),
+    /** Heading hierarchy joined by ' / '; empty string for pre-heading content */
+    sectionPath: text('section_path').notNull(),
+    /** 'section' for Phase 2; widens in Phase 4+ */
+    kind: text('kind').notNull().default('section'),
+    /** Heading text (H1/H2/H3 string), null for pre-heading content */
+    title: text('title'),
+    /** Full section markdown (heading + body) */
+    content: text('content').notNull(),
+    /** sha1 of the entire source file (for staleness detection) */
+    sourceSha: text('source_sha').notNull(),
+    /** Cached token count of `content` for fast budget math */
+    tokenCount: integer('token_count').notNull(),
+    /** Provenance confidence: 'extracted' (default), 'inferred' (AI-generated), 'ambiguous' (flagged) */
+    confidence: text('confidence').notNull().default('extracted'),
+    /** Unix epoch ms of first insert */
+    createdAt: integer('created_at').notNull(),
+    /** Unix epoch ms of last update */
+    updatedAt: integer('updated_at').notNull(),
+    /** Unix epoch ms of last read access — Phase 5 LRU eviction (Loop 6.5 A2) */
+    lastAccessedAt: integer('last_accessed_at').notNull(),
+}, (t) => [
+    index('idx_kg_nodes_scope_uri').on(t.scope, t.sourceUri),
+    index('idx_kg_nodes_last_accessed').on(t.lastAccessedAt),
+]);
+// ----------------------------------------------------------------------------
+// kg_edges — wikilinks, citations, supersedes, etc. (Phase 4+ writes; Phase 2
+// just creates the table for migration completeness)
+// ----------------------------------------------------------------------------
+/**
+ * Directed edges between nodes. Composite primary key on
+ * `(src_id, dst_id, edge_kind)` so the same pair can have multiple edge
+ * kinds (e.g. one node both `cites` and `supersedes` another).
+ *
+ * Phase 2 doesn't populate this table — Phase 4 extracts wikilinks during
+ * markdown parsing. The table exists now so the migration is complete and
+ * Phase 4 doesn't have to add it as a separate migration.
+ */
+export const kgEdges = sqliteTable('kg_edges', {
+    srcId: text('src_id')
+        .notNull()
+        .references(() => kgNodes.id, { onDelete: 'cascade' }),
+    dstId: text('dst_id')
+        .notNull()
+        .references(() => kgNodes.id, { onDelete: 'cascade' }),
+    /** 'wikilink' | 'cites' | 'supersedes' | 'contradicts' | 'mentions' | 'derived_from' */
+    edgeKind: text('edge_kind').notNull(),
+}, (t) => [
+    primaryKey({ columns: [t.srcId, t.dstId, t.edgeKind] }),
+    index('idx_kg_edges_src').on(t.srcId),
+    index('idx_kg_edges_dst').on(t.dstId),
+]);
+// ----------------------------------------------------------------------------
+// kg_chunks — paragraph-level splits of nodes
+// ----------------------------------------------------------------------------
+/**
+ * One row per ~500-token chunk derived from a node's `content`. The
+ * chunker (src/ingest/parse/chunk.ts) splits on paragraph boundaries and
+ * accumulates until adding the next paragraph would exceed `target_tokens`.
+ *
+ * The implicit SQLite `rowid` (auto-assigned for tables without
+ * INTEGER PRIMARY KEY) is what FTS5 and sqlite-vec join on:
+ *   - `kg_chunks_fts` is `content='kg_chunks', content_rowid='rowid'`
+ *   - `kg_chunks_vec.rowid` matches `kg_chunks.rowid`
+ *
+ * `chunk_sha = sha1(text)` is the per-chunk skip-unchanged key. On a
+ * file rewrite, the ingester compares each new chunk's chunk_sha against
+ * the existing chunk_shas for the file's nodes; matching chunks reuse
+ * the existing embedding (no embedder call), only changed chunks get
+ * re-embedded. This is the load-bearing optimization for Pharos's
+ * whole-file-rewrite-per-turn pattern (CLAUDE.md §Database Rules #3).
+ */
+export const kgChunks = sqliteTable('kg_chunks', {
+    /** sha1(node_id + ':' + chunk_index) */
+    id: text('id').primaryKey(),
+    /** FK to kg_nodes; cascade-delete cleans up chunks when a node goes away */
+    nodeId: text('node_id')
+        .notNull()
+        .references(() => kgNodes.id, { onDelete: 'cascade' }),
+    /** 0-based position within the node's chunk list */
+    chunkIndex: integer('chunk_index').notNull(),
+    /** The chunk's text content */
+    text: text('text').notNull(),
+    /** sha1(text) — load-bearing for per-chunk skip-unchanged */
+    chunkSha: text('chunk_sha').notNull(),
+    /** Cached token count for fast budget math */
+    tokenCount: integer('token_count').notNull(),
+    /** Unix epoch ms of insert */
+    createdAt: integer('created_at').notNull(),
+}, (t) => [index('idx_kg_chunks_node').on(t.nodeId)]);
+// ----------------------------------------------------------------------------
+// kg_log — append-only event log (Karpathy log.md materialized)
+// ----------------------------------------------------------------------------
+/**
+ * Append-only event stream. Phase 2 writes:
+ *   - `'ingest:done'` — successful file ingest
+ *   - `'ingest:error'` — failed file ingest
+ *   - `'rebuild:start' | 'rebuild:done'` — full-rebuild markers
+ *
+ * `payload` is opaque JSON shaped per `kind`. The reader is the LLM via
+ * `kg.log.recent(n, opts)` in Phase 4+; Phase 2 just appends.
+ */
+export const kgLog = sqliteTable('kg_log', {
+    id: integer('id').primaryKey({ autoIncrement: true }),
+    /** Unix epoch ms */
+    ts: integer('ts').notNull(),
+    /** 'project' | 'personal' */
+    scope: text('scope').notNull(),
+    /** Event kind, e.g. 'ingest:done' */
+    kind: text('kind').notNull(),
+    /** Source URI for ingest events; null for non-file events */
+    sourceUri: text('source_uri'),
+    /** Opaque JSON payload, shape per `kind` */
+    payload: text('payload'),
+}, (t) => [index('idx_kg_log_ts').on(sql `${t.ts} DESC`)]);
+// ----------------------------------------------------------------------------
+// kg_gaps — detected concept gaps (Phase 6+ writes; Phase 2 creates table)
+// ----------------------------------------------------------------------------
+/**
+ * Concept gaps detected by the Phase 6 gap-detection sub-agent. Phase 2
+ * creates the table; Phase 6 wires the writes.
+ *
+ * `mentions_count` lets the dashboard prioritize gaps that appear across
+ * multiple turns. `resolved_at` is set when a gap is closed (either by
+ * the LLM writing about the topic or by a manual dismissal).
+ */
+export const kgGaps = sqliteTable('kg_gaps', {
+    id: integer('id').primaryKey({ autoIncrement: true }),
+    scope: text('scope').notNull(),
+    topic: text('topic').notNull(),
+    firstSeenAt: integer('first_seen_at').notNull(),
+    mentionsCount: integer('mentions_count').notNull().default(1),
+    resolvedAt: integer('resolved_at'),
+});
+// ----------------------------------------------------------------------------
+// kg_audit — every tool call (Phase 5 wires writes; Phase 2 creates table)
+// ----------------------------------------------------------------------------
+/**
+ * Audit log of every MCP tool call. Phase 5 wires the dispatcher to write
+ * one row per call as part of the privacy invariant verification surface
+ * (CLAUDE.md §Security #7). Phase 2 creates the table.
+ *
+ * NB: per CLAUDE.md §Security #7, the JSONL mirror path differs by scope —
+ * project rows mirror to `.pharos/kg-audit.jsonl` (in the repo, safe for
+ * `git add .`), personal/both rows mirror to `~/.pharos/profile/kg-audit.jsonl`.
+ * Personal-scope audit rows go to a separate kg_audit table in the personal
+ * DB, never the project DB. This split is enforced at the app layer.
+ */
+export const kgAudit = sqliteTable('kg_audit', {
+    id: integer('id').primaryKey({ autoIncrement: true }),
+    ts: integer('ts').notNull(),
+    toolName: text('tool_name').notNull(),
+    scopeRequested: text('scope_requested').notNull(),
+    callerCtx: text('caller_ctx'),
+    responseTokens: integer('response_tokens'),
+    error: text('error'),
+});
+/**
+ * The list of all schema-managed tables, useful for the schema test that
+ * verifies the migration creates every expected table.
+ */
+export const KG_TABLES = [
+    'kg_meta',
+    'kg_nodes',
+    'kg_edges',
+    'kg_chunks',
+    'kg_log',
+    'kg_gaps',
+    'kg_audit',
+];
+/**
+ * The two virtual tables created via raw SQL in the migration (drizzle-kit
+ * doesn't emit virtual table DDL). Schema test verifies they exist.
+ */
+export const KG_VIRTUAL_TABLES = ['kg_chunks_fts', 'kg_chunks_vec'];
+//# sourceMappingURL=schema.js.map

package/dist/db/schema.js.map

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

package/dist/db/types.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared types for KG-MCP query results.
+ *
+ * Phase 2 introduces this file to decouple the tool handlers from any
+ * single store implementation. Phase 1's `MemoryStore` defined `Chunk`
+ * inline; Phase 2's `Repository` returns the same shape, and the tool
+ * handlers import from here. When `MemoryStore` is deleted in Pass 4
+ * step 32, this file becomes the canonical source.
+ */
+export type Scope = 'project' | 'personal' | 'both';
+/**
+ * A retrieval-shaped chunk. Mirrors what Phase 1's `MemoryStore` returned
+ * so the existing 13 spike tests stay green across the swap. Field shape
+ * is locked — adding fields is fine; renaming/removing breaks the
+ * sandbox host bindings (`kg.search` returns `{id, text, source_uri}`)
+ * and the spike test asserting that shape.
+ */
+export interface Chunk {
+    /** Deterministic id — Phase 1: sha1(`relative_path:index`); Phase 2: sha1(`node_id:chunk_index`) */
+    id: string;
+    /** Chunk text content (paragraph(s) up to the chunker's target token count) */
+    text: string;
+    /** `file://` URL of the source markdown file */
+    source_uri: string;
+    /** 0-based position within the source node's chunk list */
+    chunk_index: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/db/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/db/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,MAAM,KAAK,GAAG,SAAS,GAAG,UAAU,GAAG,MAAM,CAAC;AAEpD;;;;;;GAMG;AACH,MAAM,WAAW,KAAK;IACpB,oGAAoG;IACpG,EAAE,EAAE,MAAM,CAAC;IACX,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;CACrB"}

package/dist/db/types.js

@@ -0,0 +1,11 @@
+/**
+ * Shared types for KG-MCP query results.
+ *
+ * Phase 2 introduces this file to decouple the tool handlers from any
+ * single store implementation. Phase 1's `MemoryStore` defined `Chunk`
+ * inline; Phase 2's `Repository` returns the same shape, and the tool
+ * handlers import from here. When `MemoryStore` is deleted in Pass 4
+ * step 32, this file becomes the canonical source.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/db/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/db/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/gaps/detector.d.ts

@@ -0,0 +1,67 @@
+import type { Database as BetterSqliteDatabase } from 'better-sqlite3';
+/**
+ * Gap detector for KG-MCP Phase 6.
+ *
+ * After an ingest transaction commits, scans the new node's content for
+ * concept mentions. A "concept" is a term referenced via bold (`**term**`),
+ * wikilinks (`[[term]]`), or backtick-quoted identifiers that appears ≥3
+ * times across the entire KG but has no dedicated `kg_nodes` row (i.e., no
+ * node whose title matches the concept).
+ *
+ * Upserts into `kg_gaps` with `topic`, `first_seen_at`, `mentions_count`.
+ * When a node is later created with a matching title, `resolved_at` is set.
+ *
+ * This is a read-only detection surface — the LLM fills gaps by calling
+ * `kg.project.write()` to create wiki pages, and re-indexing resolves
+ * the gap automatically.
+ */
+/**
+ * Extract candidate concept strings from markdown content.
+ *
+ * Sources:
+ * - Bold text: `**term**` or `__term__`
+ * - Wikilinks: `[[term]]` or `[[term|display]]`
+ * - Backtick-quoted terms: `` `term` `` (single backtick only, not code fences)
+ *
+ * Returns deduplicated, normalized (lowercase, trimmed) set.
+ */
+export declare function extractConcepts(content: string): Set<string>;
+/**
+ * Run gap detection after an ingest transaction commits.
+ *
+ * For each concept extracted from the ingested content:
+ * 1. Count how many chunks across the KG contain the concept (case-insensitive)
+ * 2. Check if a node with a matching title already exists
+ * 3. If ≥3 mentions and no dedicated node → upsert into `kg_gaps`
+ *
+ * Also resolves any existing gaps that now have a dedicated node.
+ *
+ * @param writer  The writer DB connection (same transaction context as ingest).
+ * @param scope   'project' or 'personal'.
+ * @param content The full file content that was just ingested.
+ * @param nodesTitles Titles of all nodes that were just ingested (for resolution check).
+ */
+export declare function detectGaps(writer: BetterSqliteDatabase, scope: string, content: string, nodesTitles: string[]): {
+    gaps_created: number;
+    gaps_resolved: number;
+};
+/**
+ * Resolve gaps whose topics match any of the given node titles.
+ * Sets `resolved_at` to now for matching unresolved gaps.
+ */
+export declare function resolveGaps(writer: BetterSqliteDatabase, scope: string, nodesTitles: string[]): number;
+export interface GapRow {
+    id: number;
+    topic: string;
+    first_seen_at: number;
+    mentions_count: number;
+    resolved_at: number | null;
+}
+/**
+ * Query gaps for a scope. Returns unresolved by default; pass
+ * `resolved: true` to include resolved gaps.
+ */
+export declare function queryGaps(reader: BetterSqliteDatabase, scope: string, opts?: {
+    resolved?: boolean;
+}): GapRow[];
+//# sourceMappingURL=detector.d.ts.map

package/dist/gaps/detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detector.d.ts","sourceRoot":"","sources":["../../src/gaps/detector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,IAAI,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAIvE;;;;;;;;;;;;;;;GAeG;AAMH;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CA6B5D;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,oBAAoB,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EAAE,GACpB;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAsEjD;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,oBAAoB,EAC5B,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EAAE,GACpB,MAAM,CAkBR;AAMD,MAAM,WAAW,MAAM;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;;GAGG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,oBAAoB,EAC5B,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GAC5B,MAAM,EAAE,CAiBV"}

package/dist/gaps/detector.js

@@ -0,0 +1,160 @@
+import { logger } from '../observability/logger.js';
+/**
+ * Gap detector for KG-MCP Phase 6.
+ *
+ * After an ingest transaction commits, scans the new node's content for
+ * concept mentions. A "concept" is a term referenced via bold (`**term**`),
+ * wikilinks (`[[term]]`), or backtick-quoted identifiers that appears ≥3
+ * times across the entire KG but has no dedicated `kg_nodes` row (i.e., no
+ * node whose title matches the concept).
+ *
+ * Upserts into `kg_gaps` with `topic`, `first_seen_at`, `mentions_count`.
+ * When a node is later created with a matching title, `resolved_at` is set.
+ *
+ * This is a read-only detection surface — the LLM fills gaps by calling
+ * `kg.project.write()` to create wiki pages, and re-indexing resolves
+ * the gap automatically.
+ */
+// ----------------------------------------------------------------------------
+// Concept extraction
+// ----------------------------------------------------------------------------
+/**
+ * Extract candidate concept strings from markdown content.
+ *
+ * Sources:
+ * - Bold text: `**term**` or `__term__`
+ * - Wikilinks: `[[term]]` or `[[term|display]]`
+ * - Backtick-quoted terms: `` `term` `` (single backtick only, not code fences)
+ *
+ * Returns deduplicated, normalized (lowercase, trimmed) set.
+ */
+export function extractConcepts(content) {
+    const concepts = new Set();
+    // Bold: **term** or __term__
+    const boldRe = /\*\*([^*]+)\*\*|__([^_]+)__/g;
+    for (const m of content.matchAll(boldRe)) {
+        const term = (m[1] ?? m[2] ?? '').trim().toLowerCase();
+        if (term.length >= 2 && term.length <= 100)
+            concepts.add(term);
+    }
+    // Wikilinks: [[term]] or [[term|display]]
+    const wikilinkRe = /\[\[([^\]|]+)(?:\|[^\]]+)?\]\]/g;
+    for (const m of content.matchAll(wikilinkRe)) {
+        const term = (m[1] ?? '').trim().toLowerCase();
+        if (term.length >= 2 && term.length <= 100)
+            concepts.add(term);
+    }
+    // Backtick terms (single backtick, not code fences)
+    const backtickRe = /(?<!`)(`[^`\n]+?`)(?!`)/g;
+    for (const m of content.matchAll(backtickRe)) {
+        const raw = m[1] ?? '';
+        const term = raw.slice(1, -1).trim().toLowerCase();
+        // Only keep multi-char, non-code-looking terms (no spaces in very long strings)
+        if (term.length >= 2 && term.length <= 60 && !/[{}();=]/.test(term)) {
+            concepts.add(term);
+        }
+    }
+    return concepts;
+}
+// ----------------------------------------------------------------------------
+// Gap detection + resolution
+// ----------------------------------------------------------------------------
+/**
+ * Run gap detection after an ingest transaction commits.
+ *
+ * For each concept extracted from the ingested content:
+ * 1. Count how many chunks across the KG contain the concept (case-insensitive)
+ * 2. Check if a node with a matching title already exists
+ * 3. If ≥3 mentions and no dedicated node → upsert into `kg_gaps`
+ *
+ * Also resolves any existing gaps that now have a dedicated node.
+ *
+ * @param writer  The writer DB connection (same transaction context as ingest).
+ * @param scope   'project' or 'personal'.
+ * @param content The full file content that was just ingested.
+ * @param nodesTitles Titles of all nodes that were just ingested (for resolution check).
+ */
+export function detectGaps(writer, scope, content, nodesTitles) {
+    let gapsCreated = 0;
+    let gapsResolved = 0;
+    // Phase 1: resolve existing gaps whose topics match newly-ingested node titles
+    gapsResolved = resolveGaps(writer, scope, nodesTitles);
+    // Phase 2: detect new gaps from concepts in the ingested content
+    const concepts = extractConcepts(content);
+    if (concepts.size === 0) {
+        return { gaps_created: gapsCreated, gaps_resolved: gapsResolved };
+    }
+    const countChunkMentions = writer.prepare(`SELECT count(*) AS c FROM kg_chunks ch
+       JOIN kg_nodes n ON ch.node_id = n.id
+      WHERE n.scope = ? AND ch.text LIKE '%' || ? || '%' COLLATE NOCASE`);
+    const findDedicatedNode = writer.prepare(`SELECT id FROM kg_nodes WHERE scope = ? AND LOWER(title) = ? LIMIT 1`);
+    // kg_gaps doesn't have a unique constraint on (scope, topic).
+    // Check if the gap already exists and update or insert accordingly.
+    const findGap = writer.prepare(`SELECT id, resolved_at FROM kg_gaps WHERE scope = ? AND topic = ? LIMIT 1`);
+    const insertGap = writer.prepare(`INSERT INTO kg_gaps (scope, topic, first_seen_at, mentions_count)
+     VALUES (?, ?, ?, ?)`);
+    const updateGapCount = writer.prepare(`UPDATE kg_gaps SET mentions_count = ?, resolved_at = NULL WHERE id = ?`);
+    const now = Date.now();
+    for (const concept of concepts) {
+        // Count mentions across the KG
+        const row = countChunkMentions.get(scope, concept);
+        const count = row?.c ?? 0;
+        if (count < 3)
+            continue;
+        // Check for a dedicated node
+        const dedicated = findDedicatedNode.get(scope, concept);
+        if (dedicated)
+            continue;
+        // Upsert the gap
+        const existing = findGap.get(scope, concept);
+        if (existing) {
+            // Update mention count; reopen if previously resolved
+            updateGapCount.run(count, existing.id);
+        }
+        else {
+            insertGap.run(scope, concept, now, count);
+            gapsCreated++;
+        }
+    }
+    if (gapsCreated > 0 || gapsResolved > 0) {
+        logger.info({ scope, gapsCreated, gapsResolved, conceptsScanned: concepts.size }, 'gap detection complete');
+    }
+    return { gaps_created: gapsCreated, gaps_resolved: gapsResolved };
+}
+/**
+ * Resolve gaps whose topics match any of the given node titles.
+ * Sets `resolved_at` to now for matching unresolved gaps.
+ */
+export function resolveGaps(writer, scope, nodesTitles) {
+    if (nodesTitles.length === 0)
+        return 0;
+    const now = Date.now();
+    let resolved = 0;
+    const resolveStmt = writer.prepare(`UPDATE kg_gaps SET resolved_at = ?
+      WHERE scope = ? AND LOWER(topic) = ? AND resolved_at IS NULL`);
+    for (const title of nodesTitles) {
+        if (!title)
+            continue;
+        const info = resolveStmt.run(now, scope, title.toLowerCase());
+        resolved += info.changes;
+    }
+    return resolved;
+}
+/**
+ * Query gaps for a scope. Returns unresolved by default; pass
+ * `resolved: true` to include resolved gaps.
+ */
+export function queryGaps(reader, scope, opts) {
+    if (opts?.resolved) {
+        return reader
+            .prepare(`SELECT id, topic, first_seen_at, mentions_count, resolved_at
+           FROM kg_gaps WHERE scope = ? ORDER BY mentions_count DESC`)
+            .all(scope);
+    }
+    return reader
+        .prepare(`SELECT id, topic, first_seen_at, mentions_count, resolved_at
+         FROM kg_gaps WHERE scope = ? AND resolved_at IS NULL
+         ORDER BY mentions_count DESC`)
+        .all(scope);
+}
+//# sourceMappingURL=detector.js.map

package/dist/gaps/detector.js.map

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

package/dist/gate/budget.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Token-counting budget gate.
+ *
+ * Implements CLAUDE.md §API Rules #6 budget math:
+ *
+ *   envelope_reserve = 500          // bytes set aside for meta/logs/stale_files
+ *   safety_margin    = 0.9          // js-tiktoken is an estimator, not an oracle
+ *   available        = floor((max_tokens - envelope_reserve) * safety_margin)
+ *
+ * At the default `max_tokens=5000` the available budget for result bodies is:
+ *   floor((5000 - 500) * 0.9) = 4050 tokens
+ *
+ * Truncation is greedy by rank: keep the highest-ranked item whole if it fits;
+ * otherwise emit a `too_large` sentinel so the caller can re-query with a
+ * higher `max_tokens` or fetch the node directly by id.
+ *
+ * The sentinel pattern is Loop 6.5 A3 / presearch.md D22. A single oversize
+ * item must NOT blackhole the whole response — we report its id + uri and
+ * let the LLM decide what to do next.
+ *
+ * Token counting uses the `p50k_base` encoder — close enough to Claude's
+ * tokenization for budgeting purposes, and the 10% safety margin absorbs the
+ * estimation error between tokenizers.
+ */
+export declare const ENVELOPE_RESERVE_TOKENS = 500;
+export declare const SAFETY_MARGIN = 0.9;
+/**
+ * Count tokens in a UTF-8 string.
+ *
+ * Fast path (long strings): return a character-based over-estimate. This
+ * is strictly a ceiling — we'd rather emit a few extra `results_truncated`
+ * responses than block the event loop for minutes on tokenization.
+ *
+ * Slow path (short strings): use the real p50k_base encoder for an exact
+ * count. This is what matters for normal-size response bodies.
+ *
+ * The encoder is initialized once at module load and shared across calls.
+ */
+export declare function countTokens(text: string): number;
+/**
+ * Given a user-facing `max_tokens` budget, compute the internal result-body
+ * budget after subtracting the envelope reserve and applying the safety
+ * margin. Always returns a non-negative integer.
+ */
+export declare function computeInternalBudget(maxTokens: number): number;
+/**
+ * A too-large sentinel replaces a single item that would exceed the budget
+ * on its own. The shape is deliberately minimal — id + source_uri so the
+ * caller can re-query, plus the original token count so they can size a new
+ * `max_tokens` request.
+ */
+export interface TooLargeSentinel {
+    too_large: true;
+    id: string;
+    source_uri: string;
+    tokens: number;
+}
+export interface FitResult<T> {
+    kept: Array<T | TooLargeSentinel>;
+    truncated: boolean;
+    tokensUsed: number;
+    tokensBudgeted: number;
+}
+/**
+ * Greedy rank-order truncation. Iterates `items` in the order given (caller
+ * is responsible for ranking first), measures each one's serialized token
+ * count, and keeps items until the next one would exceed the internal
+ * budget.
+ *
+ * If a single item's token count alone exceeds the budget, it is replaced
+ * with a `too_large` sentinel and counted as zero body tokens (the sentinel
+ * itself is tiny — ~20 tokens). The iteration then continues so that smaller
+ * items after the oversize one can still land in the response.
+ *
+ * @param items       Results, pre-ranked (highest rank first).
+ * @param maxTokens   User-facing `max_tokens` budget from the tool call.
+ * @param serialize   How to turn one item into the text we'll count. Usually
+ *                    `JSON.stringify`. Broken out so the caller can include
+ *                    framing (commas, wrapping object keys) in the count.
+ * @param idOf        Read the item's id for sentinel construction.
+ * @param uriOf       Read the item's source uri for sentinel construction.
+ */
+export declare function fitResults<T>(items: T[], maxTokens: number, serialize: (item: T) => string, idOf: (item: T) => string, uriOf: (item: T) => string): FitResult<T>;
+/**
+ * Count tokens in an already-serialized response body without running the
+ * fit loop. Used by the tool handlers to populate `meta.tokens_used` after
+ * the envelope has been built.
+ */
+export declare function countEnvelopeTokens(envelopeJson: string): number;
+//# sourceMappingURL=budget.d.ts.map