@a13xu/lucid 1.0.0 → 1.4.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 a13xu
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 a13xu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,99 +1,117 @@
-# @a13xu/lucid
-
-Persistent memory for Claude Code agents, backed by **SQLite + FTS5**.
-
-Stores a knowledge graph (entities, relations, observations) with full-text search — indexed queries under 1ms, no JSON files, no linear scans.
-
-## Install
-
-**Requirements:** Node.js 18+
-
-```bash
-# Run directly (no install needed)
-npx @a13xu/lucid
-
-# Or install globally
-npm install -g @a13xu/lucid
-lucid
-```
-
-### Add to Claude Code
-
-```bash
-claude mcp add --transport stdio lucid -- npx -y @a13xu/lucid
-```
-
-Or add manually to `.mcp.json` in your project root:
-
-```json
-{
-  "mcpServers": {
-    "lucid": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@a13xu/lucid"],
-      "env": {
-        "MEMORY_DB_PATH": "/your/project/.claude/memory.db"
-      }
-    }
-  }
-}
-```
-
-Default DB path: `~/.claude/memory.db`
-
-## Why SQLite + FTS5 instead of JSON?
-
-| | JSON file | SQLite + FTS5 |
-|---|---|---|
-| Search | O(n) linear scan | O(log n) indexed |
-| Write | Rewrite entire file | Atomic incremental |
-| Concurrent reads | Lock entire file | WAL mode |
-| Stemming / unicode | Manual | Built-in |
-
-## Tools (6)
-
-| Tool | Description |
-|---|---|
-| `remember` | Store a fact about an entity (project, person, tool, decision…) |
-| `relate` | Create a directed relationship between two entities |
-| `recall` | Full-text search across all memory (FTS5 + LIKE fallback) |
-| `recall_all` | Return the entire knowledge graph with stats |
-| `forget` | Remove an entity and all its relations |
-| `memory_stats` | DB size, WAL status, entity/relation counts |
-
-### Entity types
-`person` · `project` · `decision` · `pattern` · `tool` · `config` · `bug` · `convention`
-
-### Relation types
-`uses` · `depends_on` · `created_by` · `part_of` · `replaced_by` · `conflicts_with` · `tested_by`
-
-## Usage examples
-
-```
-You:    "Remember that this project uses PostgreSQL with Prisma ORM"
-Claude: [calls remember] → Created "PostgreSQL" [tool]
-
-You:    "What do you know about the database?"
-Claude: [calls recall("database PostgreSQL")] → returns entity + observations
-
-You:    "How are the services connected?"
-Claude: [calls recall_all] → returns full knowledge graph
-```
-
-## Debugging
-
-```bash
-echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{},"clientInfo":{"name":"test","version":"1.0"},"protocolVersion":"2024-11-05"}}' \
-  | npx @a13xu/lucid
-```
-
-In Claude Code: run `/mcp` — you should see `lucid` listed with 6 tools.
-
-## Tech stack
-
-- **Runtime:** Node.js 18+, TypeScript, ES modules
-- **MCP SDK:** `@modelcontextprotocol/sdk`
-- **Database:** `better-sqlite3` (synchronous, no async overhead)
-- **Validation:** `zod`
-- **Transport:** stdio
+# @a13xu/lucid
+
+Memory, code indexing, and validation for Claude Code agents — backed by **SQLite + FTS5**.
+
+Stores a persistent knowledge graph (entities, relations, observations), indexes source files as compressed binary with change detection, and validates code for LLM drift patterns.
+
+## Install
+
+**Requirements:** Node.js 18+
+
+```bash
+# Add to Claude Code (no install needed)
+claude mcp add --transport stdio lucid -- npx -y @a13xu/lucid
+```
+
+Or add to `.mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "lucid": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@a13xu/lucid"],
+      "env": {
+        "MEMORY_DB_PATH": "/your/project/.claude/memory.db"
+      }
+    }
+  }
+}
+```
+
+Default DB path: `~/.claude/memory.db`
+
+## Quick start
+
+```
+1. "Index this project" → init_project() → scans CLAUDE.md, package.json, src/
+2. Write code          → sync_file(path) → compressed + hashed in DB
+3. "Where is X used?"  → grep_code("X") → matching lines only, no full file
+4. "What do we know?"  → recall("query") → knowledge graph search
+```
+
+## Tools (13)
+
+### Memory
+| Tool | Description |
+|---|---|
+| `remember` | Store a fact about an entity (project, person, tool, decision…) |
+| `relate` | Create a directed relationship between two entities |
+| `recall` | Full-text search across all memory (FTS5 + LIKE fallback) |
+| `recall_all` | Return the entire knowledge graph with statistics |
+| `forget` | Remove an entity and all its relations |
+| `memory_stats` | DB size, WAL status, entity/relation counts |
+
+### Code indexing
+| Tool | Description |
+|---|---|
+| `init_project` | Scan project directory and bootstrap knowledge graph. Reads `CLAUDE.md`, `package.json`/`pyproject.toml`, `README.md`, `.mcp.json`, `logic-guardian.yaml`, source files. Also installs a Claude Code hook for auto-sync. |
+| `sync_file` | Index or re-index a single file after writing/editing. Stores compressed binary (zlib-9), skips instantly if SHA-256 hash unchanged. |
+| `sync_project` | Re-index entire project incrementally. Reports compression ratio. |
+| `grep_code` | Regex search across all indexed files. Decompresses binary on-the-fly, returns only matching lines with context — ~20-50 tokens vs reading full files. |
+
+### Logic Guardian
+| Tool | Description |
+|---|---|
+| `validate_file` | Detect LLM drift patterns in a source file: logic inversions, null propagation, type confusion, copy-paste drift, silent exceptions. Supports Python, JS, TS. |
+| `check_drift` | Analyze a code snippet inline without saving to disk. |
+| `get_checklist` | Return the full 5-pass validation protocol (Logic Trace, Contract Verification, Stupid Mistakes, Integration Sanity, Explain It). |
+
+## Why no vectors?
+
+Code has explicit structure — no NLP needed:
+
+| Need | Approach | Tokens |
+|---|---|---|
+| "Where is X defined?" | `grep_code("export.*X")` | ~30 |
+| "What does auth.ts export?" | `recall("auth.ts")` | ~50 |
+| "Project conventions?" | `recall("CLAUDE.md conventions")` | ~80 |
+| Read full file | `Read tool` | ~500-2000 |
+
+Source files are stored as **zlib-deflate level 9 BLOBs** (~70% smaller than plain text). Change detection via SHA-256 means `sync_file` is instant on unchanged files.
+
+## Why SQLite + FTS5?
+
+| | JSON file | SQLite + FTS5 |
+|---|---|---|
+| Search | O(n) linear scan | O(log n) indexed |
+| Write | Rewrite entire file | Atomic incremental |
+| Concurrent reads | Lock entire file | WAL mode |
+| Code storage | Plain text | Compressed BLOB + hash |
+| Change detection | Manual diff | SHA-256 per file |
+
+## Entity types
+`person` · `project` · `decision` · `pattern` · `tool` · `config` · `bug` · `convention`
+
+## Relation types
+`uses` · `depends_on` · `created_by` · `part_of` · `replaced_by` · `conflicts_with` · `tested_by`
+
+## Debugging
+
+```bash
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{},"clientInfo":{"name":"test","version":"1.0"},"protocolVersion":"2024-11-05"}}' \
+  | npx @a13xu/lucid
+```
+
+In Claude Code: run `/mcp` — you should see `lucid` with 13 tools.
+
+## Tech stack
+
+- **Runtime:** Node.js 18+, TypeScript, ES modules
+- **MCP SDK:** `@modelcontextprotocol/sdk`
+- **Database:** `better-sqlite3` (synchronous, WAL mode)
+- **Compression:** Node.js built-in `zlib` (deflate level 9)
+- **Hashing:** SHA-256 via `crypto` (change detection)
+- **Validation:** `zod`
+- **Transport:** stdio

package/build/database.d.ts

@@ -3,7 +3,26 @@ import type { EntityRow, RelationRow } from "./types.js";
 export declare function initDatabase(): Database.Database;
 type Stmt<P extends unknown[], R> = Database.Statement<P, R>;
 type WriteStmt<P extends unknown[]> = Database.Statement<P, unknown>;
+export interface FileContentRow {
+    id: number;
+    filepath: string;
+    content: Buffer;
+    content_hash: string;
+    original_size: number;
+    compressed_size: number;
+    language: string;
+    indexed_at: number;
+}
 export interface Statements {
+    getFileByPath: Stmt<[string], FileContentRow>;
+    upsertFile: WriteStmt<[string, Buffer, string, number, number, string]>;
+    getAllFiles: Stmt<[], Pick<FileContentRow, "filepath" | "content" | "language" | "content_hash">>;
+    deleteFile: WriteStmt<[string]>;
+    fileStorageStats: Stmt<[], {
+        count: number;
+        total_original: number;
+        total_compressed: number;
+    }>;
     getEntityByName: Stmt<[string], EntityRow>;
     insertEntity: WriteStmt<[string, string, string]>;
     updateEntity: WriteStmt<[string, number]>;

package/build/database.js

@@ -30,85 +30,114 @@ export function initDatabase() {
     return db;
 }
 function createSchema(db) {
-    db.exec(`
-    CREATE TABLE IF NOT EXISTS entities (
-      id           INTEGER PRIMARY KEY,
-      name         TEXT NOT NULL UNIQUE COLLATE NOCASE,
-      type         TEXT NOT NULL,
-      observations TEXT NOT NULL DEFAULT '[]',
-      created_at   INTEGER DEFAULT (unixepoch()),
-      updated_at   INTEGER DEFAULT (unixepoch())
-    );
-
-    CREATE TABLE IF NOT EXISTS relations (
-      id            INTEGER PRIMARY KEY,
-      from_entity   INTEGER NOT NULL REFERENCES entities(id) ON DELETE CASCADE,
-      to_entity     INTEGER NOT NULL REFERENCES entities(id) ON DELETE CASCADE,
-      relation_type TEXT NOT NULL,
-      created_at    INTEGER DEFAULT (unixepoch()),
-      UNIQUE(from_entity, to_entity, relation_type)
-    );
-
-    CREATE VIRTUAL TABLE IF NOT EXISTS entities_fts USING fts5(
-      name,
-      type,
-      observations,
-      content='entities',
-      content_rowid='id',
-      tokenize='porter unicode61'
-    );
-
-    CREATE TRIGGER IF NOT EXISTS entities_ai AFTER INSERT ON entities BEGIN
-      INSERT INTO entities_fts(rowid, name, type, observations)
-      VALUES (new.id, new.name, new.type, new.observations);
-    END;
-
-    CREATE TRIGGER IF NOT EXISTS entities_au AFTER UPDATE ON entities BEGIN
-      INSERT INTO entities_fts(entities_fts, rowid, name, type, observations)
-      VALUES('delete', old.id, old.name, old.type, old.observations);
-      INSERT INTO entities_fts(rowid, name, type, observations)
-      VALUES (new.id, new.name, new.type, new.observations);
-    END;
-
-    CREATE TRIGGER IF NOT EXISTS entities_ad AFTER DELETE ON entities BEGIN
-      INSERT INTO entities_fts(entities_fts, rowid, name, type, observations)
-      VALUES('delete', old.id, old.name, old.type, old.observations);
-    END;
-
-    CREATE INDEX IF NOT EXISTS idx_relations_from ON relations(from_entity);
-    CREATE INDEX IF NOT EXISTS idx_relations_to   ON relations(to_entity);
-    CREATE INDEX IF NOT EXISTS idx_entities_type  ON entities(type);
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS entities (
+      id           INTEGER PRIMARY KEY,
+      name         TEXT NOT NULL UNIQUE COLLATE NOCASE,
+      type         TEXT NOT NULL,
+      observations TEXT NOT NULL DEFAULT '[]',
+      created_at   INTEGER DEFAULT (unixepoch()),
+      updated_at   INTEGER DEFAULT (unixepoch())
+    );
+
+    CREATE TABLE IF NOT EXISTS relations (
+      id            INTEGER PRIMARY KEY,
+      from_entity   INTEGER NOT NULL REFERENCES entities(id) ON DELETE CASCADE,
+      to_entity     INTEGER NOT NULL REFERENCES entities(id) ON DELETE CASCADE,
+      relation_type TEXT NOT NULL,
+      created_at    INTEGER DEFAULT (unixepoch()),
+      UNIQUE(from_entity, to_entity, relation_type)
+    );
+
+    CREATE VIRTUAL TABLE IF NOT EXISTS entities_fts USING fts5(
+      name,
+      type,
+      observations,
+      content='entities',
+      content_rowid='id',
+      tokenize='porter unicode61'
+    );
+
+    CREATE TRIGGER IF NOT EXISTS entities_ai AFTER INSERT ON entities BEGIN
+      INSERT INTO entities_fts(rowid, name, type, observations)
+      VALUES (new.id, new.name, new.type, new.observations);
+    END;
+
+    CREATE TRIGGER IF NOT EXISTS entities_au AFTER UPDATE ON entities BEGIN
+      INSERT INTO entities_fts(entities_fts, rowid, name, type, observations)
+      VALUES('delete', old.id, old.name, old.type, old.observations);
+      INSERT INTO entities_fts(rowid, name, type, observations)
+      VALUES (new.id, new.name, new.type, new.observations);
+    END;
+
+    CREATE TRIGGER IF NOT EXISTS entities_ad AFTER DELETE ON entities BEGIN
+      INSERT INTO entities_fts(entities_fts, rowid, name, type, observations)
+      VALUES('delete', old.id, old.name, old.type, old.observations);
+    END;
+
+    CREATE INDEX IF NOT EXISTS idx_relations_from ON relations(from_entity);
+    CREATE INDEX IF NOT EXISTS idx_relations_to   ON relations(to_entity);
+    CREATE INDEX IF NOT EXISTS idx_entities_type  ON entities(type);
+
+    -- Conținut sursă comprimat (zlib deflate nivel 9)
+    CREATE TABLE IF NOT EXISTS file_contents (
+      id              INTEGER PRIMARY KEY,
+      filepath        TEXT NOT NULL UNIQUE,
+      content         BLOB NOT NULL,
+      content_hash    TEXT NOT NULL,
+      original_size   INTEGER NOT NULL,
+      compressed_size INTEGER NOT NULL,
+      language        TEXT NOT NULL DEFAULT 'generic',
+      indexed_at      INTEGER DEFAULT (unixepoch())
+    );
+    CREATE INDEX IF NOT EXISTS idx_fc_filepath ON file_contents(filepath);
+    CREATE INDEX IF NOT EXISTS idx_fc_hash     ON file_contents(content_hash);
   `);
 }
 export function prepareStatements(db) {
     return {
+        // file_contents
+        getFileByPath: db.prepare("SELECT * FROM file_contents WHERE filepath = ?"),
+        upsertFile: db.prepare(`INSERT INTO file_contents (filepath, content, content_hash, original_size, compressed_size, language)
+       VALUES (?, ?, ?, ?, ?, ?)
+       ON CONFLICT(filepath) DO UPDATE SET
+         content = excluded.content,
+         content_hash = excluded.content_hash,
+         original_size = excluded.original_size,
+         compressed_size = excluded.compressed_size,
+         language = excluded.language,
+         indexed_at = unixepoch()`),
+        getAllFiles: db.prepare("SELECT filepath, content, language, content_hash FROM file_contents"),
+        deleteFile: db.prepare("DELETE FROM file_contents WHERE filepath = ?"),
+        fileStorageStats: db.prepare("SELECT COUNT(*) as count, SUM(original_size) as total_original, SUM(compressed_size) as total_compressed FROM file_contents"),
+        // entities
         getEntityByName: db.prepare("SELECT * FROM entities WHERE name = ? COLLATE NOCASE"),
         insertEntity: db.prepare("INSERT INTO entities (name, type, observations) VALUES (?, ?, ?)"),
         // SQL: SET observations = ?, WHERE id = ?  →  2 params
         updateEntity: db.prepare("UPDATE entities SET observations = ?, updated_at = unixepoch() WHERE id = ?"),
         deleteEntity: db.prepare("DELETE FROM entities WHERE name = ? COLLATE NOCASE"),
         getAllEntities: db.prepare("SELECT * FROM entities ORDER BY updated_at DESC"),
-        getRelationsForEntity: db.prepare(`SELECT r.*, ef.name AS from_name, et.name AS to_name
-       FROM relations r
-       JOIN entities ef ON r.from_entity = ef.id
-       JOIN entities et ON r.to_entity = et.id
+        getRelationsForEntity: db.prepare(`SELECT r.*, ef.name AS from_name, et.name AS to_name
+       FROM relations r
+       JOIN entities ef ON r.from_entity = ef.id
+       JOIN entities et ON r.to_entity = et.id
        WHERE r.from_entity = ? OR r.to_entity = ?`),
         insertRelation: db.prepare("INSERT OR IGNORE INTO relations (from_entity, to_entity, relation_type) VALUES (?, ?, ?)"),
-        searchFTS: db.prepare(`SELECT e.* FROM entities_fts
-       JOIN entities e ON entities_fts.rowid = e.id
-       WHERE entities_fts MATCH ?
-       ORDER BY rank
+        searchFTS: db.prepare(`SELECT e.* FROM entities_fts
+       JOIN entities e ON entities_fts.rowid = e.id
+       WHERE entities_fts MATCH ?
+       ORDER BY rank
        LIMIT 20`),
-        searchLike: db.prepare(`SELECT * FROM entities
-       WHERE name LIKE ? OR type LIKE ? OR observations LIKE ?
-       ORDER BY updated_at DESC
+        searchLike: db.prepare(`SELECT * FROM entities
+       WHERE name LIKE ? OR type LIKE ? OR observations LIKE ?
+       ORDER BY updated_at DESC
        LIMIT 20`),
         countEntities: db.prepare("SELECT COUNT(*) as count FROM entities"),
         countRelations: db.prepare("SELECT COUNT(*) as count FROM relations"),
         getWalMode: db.prepare("PRAGMA journal_mode"),
-        getAllRelations: db.prepare(`SELECT r.*, ef.name AS from_name, et.name AS to_name
-       FROM relations r
-       JOIN entities ef ON r.from_entity = ef.id
+        getAllRelations: db.prepare(`SELECT r.*, ef.name AS from_name, et.name AS to_name
+       FROM relations r
+       JOIN entities ef ON r.from_entity = ef.id
        JOIN entities et ON r.to_entity = et.id`),
     };
 }

package/build/guardian/checklist.d.ts

@@ -0,0 +1 @@
+export declare const CHECKLIST = "# Logic Guardian \u2014 Validation Checklist (5 passes)\n\n## Pass 1: Logic Trace\nTrace through the code with CONCRETE values:\n- Happy path   \u2192 real values, write each variable state\n- Empty/zero   \u2192 null, 0, \"\", []\n- Boundary     \u2192 first element, last element, max int, single char\n- Error case   \u2192 network down, file missing, permission denied\n\nSTOP if any trace produces unexpected output. Fix before continuing.\n\n## Pass 2: Contract Verification\n- [ ] Preconditions: what must be true BEFORE this runs? Is it checked?\n- [ ] Postconditions: what must be true AFTER? Can you prove it?\n- [ ] Invariants: what must ALWAYS be true? Does the code maintain it?\n- [ ] Return type: does EVERY code path return the expected type?\n- [ ] Side effects: are all side effects intentional?\n\n## Pass 3: Stupid Mistakes Checklist\n\n### Off-by-one\n- [ ] < vs <= \u2014 verify with boundary values\n- [ ] Array indices \u2014 last is length - 1\n- [ ] Loop iterations \u2014 exactly N times?\n\n### Null/Undefined Propagation\n- [ ] Every .property access \u2014 can the object be null?\n- [ ] Every array index \u2014 can the array be empty?\n- [ ] Every map lookup \u2014 can the key be missing?\n\n### Type Confusion\n- [ ] String vs Number comparisons\n- [ ] Integer vs Float division\n- [ ] Boolean coercion edge cases\n\n### Logic Inversions (THE #1 LLM drift pattern)\n- [ ] if/else \u2014 is the condition testing what you THINK?\n- [ ] Early returns \u2014 does the guard return the RIGHT value?\n- [ ] filter/find/some \u2014 keeping the RIGHT elements?\n- [ ] Error handling \u2014 catching and re-throwing correctly?\n\n### State & Mutation\n- [ ] Mutating shared object when you should copy?\n- [ ] Async state read after it might have changed?\n\n### Copy-Paste Drift\n- [ ] ALL variable names updated in copied blocks?\n- [ ] Conditions changed, not just variable names?\n\n## Pass 4: Integration Sanity\n- [ ] Breaks existing callers?\n- [ ] Imports/exports correct?\n- [ ] If async, all callers awaiting it?\n- [ ] If type changed, all usages updated?\n\n## Pass 5: Explain It Test\nIn ONE sentence: what does this code do?\nIf you can't explain it, or the sentence doesn't match the code \u2192 something is wrong.\n\n## Anti-Drift Triggers\nSTOP if you find yourself thinking:\n- \"This is similar to...\" \u2192 You're pattern-matching. TRACE THE LOGIC.\n- \"This should work because the other one does\" \u2192 VERIFY INDEPENDENTLY.\n- \"I'll just copy and change the names\" \u2192 CHECK EVERY DIFFERENCE.\n- \"The error handling is probably fine\" \u2192 TRACE THE ERROR PATH.\n- \"This is standard boilerplate\" \u2192 Verify it fits this context.\n";

package/build/guardian/checklist.js

@@ -0,0 +1,67 @@
+export const CHECKLIST = `# Logic Guardian — Validation Checklist (5 passes)
+
+## Pass 1: Logic Trace
+Trace through the code with CONCRETE values:
+- Happy path   → real values, write each variable state
+- Empty/zero   → null, 0, "", []
+- Boundary     → first element, last element, max int, single char
+- Error case   → network down, file missing, permission denied
+
+STOP if any trace produces unexpected output. Fix before continuing.
+
+## Pass 2: Contract Verification
+- [ ] Preconditions: what must be true BEFORE this runs? Is it checked?
+- [ ] Postconditions: what must be true AFTER? Can you prove it?
+- [ ] Invariants: what must ALWAYS be true? Does the code maintain it?
+- [ ] Return type: does EVERY code path return the expected type?
+- [ ] Side effects: are all side effects intentional?
+
+## Pass 3: Stupid Mistakes Checklist
+
+### Off-by-one
+- [ ] < vs <= — verify with boundary values
+- [ ] Array indices — last is length - 1
+- [ ] Loop iterations — exactly N times?
+
+### Null/Undefined Propagation
+- [ ] Every .property access — can the object be null?
+- [ ] Every array index — can the array be empty?
+- [ ] Every map lookup — can the key be missing?
+
+### Type Confusion
+- [ ] String vs Number comparisons
+- [ ] Integer vs Float division
+- [ ] Boolean coercion edge cases
+
+### Logic Inversions (THE #1 LLM drift pattern)
+- [ ] if/else — is the condition testing what you THINK?
+- [ ] Early returns — does the guard return the RIGHT value?
+- [ ] filter/find/some — keeping the RIGHT elements?
+- [ ] Error handling — catching and re-throwing correctly?
+
+### State & Mutation
+- [ ] Mutating shared object when you should copy?
+- [ ] Async state read after it might have changed?
+
+### Copy-Paste Drift
+- [ ] ALL variable names updated in copied blocks?
+- [ ] Conditions changed, not just variable names?
+
+## Pass 4: Integration Sanity
+- [ ] Breaks existing callers?
+- [ ] Imports/exports correct?
+- [ ] If async, all callers awaiting it?
+- [ ] If type changed, all usages updated?
+
+## Pass 5: Explain It Test
+In ONE sentence: what does this code do?
+If you can't explain it, or the sentence doesn't match the code → something is wrong.
+
+## Anti-Drift Triggers
+STOP if you find yourself thinking:
+- "This is similar to..." → You're pattern-matching. TRACE THE LOGIC.
+- "This should work because the other one does" → VERIFY INDEPENDENTLY.
+- "I'll just copy and change the names" → CHECK EVERY DIFFERENCE.
+- "The error handling is probably fine" → TRACE THE ERROR PATH.
+- "This is standard boilerplate" → Verify it fits this context.
+`;

package/build/guardian/validator.d.ts

@@ -0,0 +1,21 @@
+export type Severity = "critical" | "high" | "medium" | "low" | "info";
+export interface Issue {
+    file: string;
+    line: number;
+    severity: Severity;
+    driftId: string;
+    message: string;
+    suggestion?: string;
+    snippet?: string;
+}
+export declare function formatIssue(issue: Issue): string;
+export declare function detectLanguage(filepath: string): string;
+export interface ValidationResult {
+    issues: Issue[];
+    filesChecked: number;
+    linesChecked: number;
+    passed: boolean;
+}
+export declare function validateSource(filepath: string, source: string, lang?: string): Issue[];
+export declare function validateFile(filepath: string): Issue[];
+export declare function formatReport(filepath: string, issues: Issue[]): string;