amalfa 1.0.35 → 1.0.37

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Polyvis Project Contributors
+Copyright (c) 2026 Virtual Information Systems 
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -133,7 +133,7 @@ bun install
 
 3. **Generate MCP config**:
    ```bash
-   bun run scripts/setup_mcp.ts
+   amalfa setup-mcp
    ```
 
 4. **Add to Claude Desktop**: Copy the JSON output to:

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "amalfa",
-	"version": "1.0.35",
+	"version": "1.0.37",
 	"description": "Local-first knowledge graph engine for AI agents. Transforms markdown into searchable memory with MCP protocol.",
 	"license": "MIT",
 	"homepage": "https://github.com/pjsvis/amalfa#readme",
@@ -45,9 +45,9 @@
 	"devDependencies": {
 		"@biomejs/biome": "2.3.8",
 		"@types/bun": "1.3.4",
-		"only-allow": "^1.2.2",
-		"pino-pretty": "^13.1.3",
-		"typescript": "^5.9.3"
+		"only-allow": "1.2.2",
+		"pino-pretty": "13.1.3",
+		"typescript": "5.9.3"
 	},
 	"scripts": {
 		"precommit": "bun run scripts/maintenance/pre-commit.ts",
@@ -64,9 +64,12 @@
 	},
 	"dependencies": {
 		"@modelcontextprotocol/sdk": "1.25.2",
+		"drizzle-kit": "0.31.8",
+		"drizzle-orm": "0.45.1",
 		"fastembed": "2.0.0",
-		"graphology": "^0.26.0",
-		"graphology-library": "^0.8.0",
-		"pino": "^10.1.0"
+		"graphology": "0.26.0",
+		"graphology-library": "0.8.0",
+		"hono": "4.11.3",
+		"pino": "10.1.0"
 	}
 }

package/src/README.md

@@ -0,0 +1,51 @@
+amalfa/src/README.md
+```
+
+# Source Directory
+
+## Purpose
+
+This directory contains the core source code for the Amalfa project. Amalfa is an AI-powered documentation and knowledge management system that evolved from patterns discovered in the PolyVis project. The system enables agents and users to maintain living documentation through brief-debrief-playbook workflows.
+
+## Key Files
+
+- `cli.ts` - Main CLI entry point for the application
+- `cli/` - CLI command implementations
+- `config/` - Configuration management and loading
+- `core/` - Core application logic and services
+- `daemon/` - Background services (Vector Daemon, Sonar Agent)
+- `mcp/` - Model Context Protocol server implementation
+- `pipeline/` - Data processing pipelines
+- `resonance/` - Knowledge graph and semantic services
+- `types/` - TypeScript type definitions
+- `utils/` - Utility functions and helpers
+
+## Patterns
+
+### Module Organization
+Each major feature area has its own directory with a colocated README documenting its purpose, key exports, and stability status.
+
+### Configuration
+- Uses `amalfa.config.ts` for user configuration
+- Supports JSON fallback (`amalfa.config.json`)
+- Configuration is loaded via `config/` module
+
+### CLI Architecture
+- Main entry: `cli.ts`
+- Commands are implemented as subdirectories in `cli/`
+- Uses a command pattern for extensibility
+
+### Service Architecture
+- Daemon processes run in `daemon/` for long-running services
+- MCP server in `mcp/` provides external API access
+- Resonance services in `resonance/` handle knowledge graph operations
+
+## ⚠️ Stability
+
+This module is stable and intentionally designed.
+Do NOT refactor, rewrite, or change the architecture without:
+1. Consulting the user first
+2. Having a documented, compelling reason
+3. Understanding WHY the current design exists
+
+If something looks "wrong," it may be intentional. Ask before you chop.

package/src/cli/README.md

@@ -0,0 +1,29 @@
+amalfa/src/cli/README.md
+
+
+# CLI Directory
+
+## Purpose
+Command-line interface implementation for Amalfa, providing the primary user-facing interface for interacting with the system.
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `index.ts` | CLI entry point and command routing |
+| `commands/` | Individual command implementations |
+
+## Patterns
+
+- Uses a command pattern for extensibility
+- Supports subcommands for different operations
+- Consistent help and argument parsing
+
+## ⚠️ Stability
+This module is stable and intentionally designed.
+Do NOT refactor, rewrite, or change the architecture without:
+1. Consulting the user first
+2. Having a documented, compelling reason
+3. Understanding WHY the current design exists
+
+If something looks "wrong," it may be intentional. Ask before you chop.

package/src/config/README.md

@@ -0,0 +1,43 @@
+amalfa/src/config/README.md
+```
+
+# Configuration Directory
+
+## Purpose
+The `config/` directory handles configuration loading, validation, and management for the Amalfa application. It provides a unified interface for accessing configuration values from TypeScript and JSON configuration files.
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `index.ts` | Main export barrel and configuration interface |
+| `loader.ts` | Configuration file loading logic |
+| `validator.ts` | Schema validation for configuration values |
+| `defaults.ts` | Default configuration values |
+
+## Patterns
+
+### Configuration Loading
+- Primary: `amalfa.config.ts` (TypeScript module)
+- Fallback: `amalfa.config.json` (JSON format)
+- Environment variables can override config values
+
+### Validation
+- Uses schema validation to ensure configuration integrity
+- Provides helpful error messages for missing or invalid values
+
+### Access Pattern
+```typescript
+import { config } from './config';
+
+const apiKey = config.get('api.key');
+```
+
+## ⚠️ Stability
+This module is stable and intentionally designed.
+Do NOT refactor, rewrite, or change the architecture without:
+1. Consulting the user first
+2. Having a documented, compelling reason
+3. Understanding WHY the current design exists
+
+If something looks "wrong," it may be intentional. Ask before you chop.

package/src/config/scripts-registry.json

@@ -13,13 +13,6 @@
 		"category": "core",
 		"type": "dev"
 	},
-	{
-		"path": "scripts/setup_mcp.ts",
-		"command": "amalfa setup-mcp",
-		"description": "Generates the Model Context Protocol configuration JSON for Claude Desktop.",
-		"category": "setup",
-		"type": "user"
-	},
 	{
 		"path": "scripts/maintenance/pre-commit.ts",
 		"command": "bun run precommit",

package/src/core/README.md

@@ -1,6 +1,7 @@
+
 # 🧠 Core Logic
 
-The foundational business logic and processing engines for Polyvis.
+The foundational business logic and processing engines for Amalfa.
 
 ## Contents
 - **`BentoNormalizer`**: Ensures document structure (H1/H2 hierarchy).
@@ -9,3 +10,12 @@ The foundational business logic and processing engines for Polyvis.
 - **`VectorEngine`**: Interface for vector operations (search/embed).
 - **`TagEngine`**: Auto-tagging logic (LLM based).
 - **`SemanticWeaver`**: Logic for "rescuing" orphaned nodes using embeddings.
+
+## ⚠️ Stability
+This module is stable and intentionally designed.
+Do NOT refactor, rewrite, or change the architecture without:
+1. Consulting the user first
+2. Having a documented, compelling reason
+3. Understanding WHY the current design exists
+
+If something looks "wrong," it may be intentional. Ask before you chop.

package/src/daemon/README.md

@@ -0,0 +1,25 @@
+# Daemon Directory
+
+## Purpose
+Background services and long-running processes for Amalfa, including the Vector Daemon and Sonar Agent.
+
+## Key Files
+
+- `index.ts` - Daemon entry point
+- `vector-daemon.ts` - Vector storage service
+- `sonar-agent.ts` - Semantic analysis agent
+
+## Patterns
+
+- Services run as background processes
+- Use event-driven architecture
+- Support graceful shutdown
+
+## ⚠️ Stability
+This module is stable and intentionally designed.
+Do NOT refactor, rewrite, or change the architecture without:
+1. Consulting the user first
+2. Having a documented, compelling reason
+3. Understanding WHY the current design exists
+
+If something looks "wrong," it may be intentional. Ask before you chop.

package/src/daemon/sonar-agent.ts

@@ -24,27 +24,14 @@ import { ServiceLifecycle } from "@src/utils/ServiceLifecycle";
 import { inferenceState } from "./sonar-inference";
 import {
 	handleBatchEnhancement,
-	handleChat,
-	handleContextExtraction,
 	handleGardenTask,
-	handleMetadataEnhancement,
 	handleResearchTask,
-	handleResultReranking,
-	handleSearchAnalysis,
 	handleSynthesisTask,
 	handleTimelineTask,
 	type SonarContext,
 } from "./sonar-logic";
 import { getTaskModel } from "./sonar-strategies";
-import type {
-	ChatRequest,
-	ChatSession,
-	MetadataEnhanceRequest,
-	SearchAnalyzeRequest,
-	SearchContextRequest,
-	SearchRerankRequest,
-	SonarTask,
-} from "./sonar-types";
+import type { ChatSession, SonarTask } from "./sonar-types";
 
 const args = process.argv.slice(2);
 const command = args[0] || "serve";
@@ -128,123 +115,18 @@ async function main() {
 	}
 }
 
+import { createSonarApp } from "./sonar-server";
+
 /**
- * Start Bun HTTP Server
+ * Start Bun HTTP Server via Hono
  */
 function startServer(port: number) {
-	const corsHeaders = {
-		"Access-Control-Allow-Origin": "*",
-		"Access-Control-Allow-Methods": "GET, POST, OPTIONS",
-		"Access-Control-Allow-Headers": "Content-Type",
-	};
-
 	const context: SonarContext = { db, graphEngine, gardener, chatSessions };
+	const app = createSonarApp(context);
 
 	Bun.serve({
 		port,
-		async fetch(req) {
-			if (req.method === "OPTIONS")
-				return new Response(null, { headers: corsHeaders });
-			const url = new URL(req.url);
-
-			// Health check
-			if (url.pathname === "/health") {
-				const cfg = await loadConfig();
-				const provider = cfg.sonar.cloud?.enabled ? "cloud" : "local";
-				const model = cfg.sonar.cloud?.enabled
-					? cfg.sonar.cloud.model
-					: inferenceState.ollamaModel || cfg.sonar.model;
-				return Response.json(
-					{
-						status: "ok",
-						ollama: inferenceState.ollamaAvailable,
-						provider,
-						model,
-					},
-					{ headers: corsHeaders },
-				);
-			}
-
-			// Chat endpoint
-			if (url.pathname === "/chat" && req.method === "POST") {
-				try {
-					const body = (await req.json()) as ChatRequest;
-					const { sessionId, message, model } = body;
-					const result = await handleChat(sessionId, message, context, model);
-					return Response.json(result, { headers: corsHeaders });
-				} catch (error) {
-					return Response.json(
-						{ error: String(error) },
-						{ status: 500, headers: corsHeaders },
-					);
-				}
-			}
-
-			// Metadata enhancement endpoint
-			if (url.pathname === "/metadata/enhance" && req.method === "POST") {
-				try {
-					const body = (await req.json()) as MetadataEnhanceRequest;
-					const { docId } = body;
-					await handleMetadataEnhancement(docId, context);
-					return Response.json({ status: "success" }, { headers: corsHeaders });
-				} catch (error) {
-					return Response.json(
-						{ error: String(error) },
-						{ status: 500, headers: corsHeaders },
-					);
-				}
-			}
-
-			// Graph Stats endpoint
-			if (url.pathname === "/graph/stats" && req.method === "GET") {
-				return Response.json(graphEngine.getStats(), { headers: corsHeaders });
-			}
-
-			// Search endpoints (analysis, rerank, context)
-			if (url.pathname === "/search/analyze" && req.method === "POST") {
-				try {
-					const body = (await req.json()) as SearchAnalyzeRequest;
-					const { query } = body;
-					const result = await handleSearchAnalysis(query, context);
-					return Response.json(result, { headers: corsHeaders });
-				} catch (error) {
-					return Response.json(
-						{ error: String(error) },
-						{ status: 500, headers: corsHeaders },
-					);
-				}
-			}
-
-			if (url.pathname === "/search/rerank" && req.method === "POST") {
-				try {
-					const body = (await req.json()) as SearchRerankRequest;
-					const { results, query, intent } = body;
-					const result = await handleResultReranking(results, query, intent);
-					return Response.json(result, { headers: corsHeaders });
-				} catch (error) {
-					return Response.json(
-						{ error: String(error) },
-						{ status: 500, headers: corsHeaders },
-					);
-				}
-			}
-
-			if (url.pathname === "/search/context" && req.method === "POST") {
-				try {
-					const body = (await req.json()) as SearchContextRequest;
-					const { result, query } = body;
-					const contextResult = await handleContextExtraction(result, query);
-					return Response.json(contextResult, { headers: corsHeaders });
-				} catch (error) {
-					return Response.json(
-						{ error: String(error) },
-						{ status: 500, headers: corsHeaders },
-					);
-				}
-			}
-
-			return new Response("Not Found", { status: 404, headers: corsHeaders });
-		},
+		fetch: app.fetch,
 	});
 
 	log.info(`Server started on port ${port}`);

package/src/daemon/sonar-server.ts

@@ -0,0 +1,133 @@
+import { loadConfig } from "@src/config/defaults";
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+import { inferenceState } from "./sonar-inference";
+import {
+	handleChat,
+	handleContextExtraction,
+	handleMetadataEnhancement,
+	handleResultReranking,
+	handleSearchAnalysis,
+	type SonarContext,
+} from "./sonar-logic";
+import type {
+	ChatRequest,
+	MetadataEnhanceRequest,
+	SearchAnalyzeRequest,
+	SearchContextRequest,
+	SearchRerankRequest,
+} from "./sonar-types";
+
+/**
+ * Creates the Hono application for the Sonar Agent
+ */
+export function createSonarApp(context: SonarContext) {
+	const app = new Hono();
+
+	// Global Middleware
+	app.use(
+		"*",
+		cors({
+			origin: "*",
+			allowMethods: ["GET", "POST", "OPTIONS"],
+			allowHeaders: ["Content-Type"],
+		}),
+	);
+
+	/**
+	 * Health Check
+	 */
+	app.get("/health", async (c) => {
+		const cfg = await loadConfig();
+		const provider = cfg.sonar.cloud?.enabled ? "cloud" : "local";
+		const model = cfg.sonar.cloud?.enabled
+			? cfg.sonar.cloud.model
+			: inferenceState.ollamaModel || cfg.sonar.model;
+
+		return c.json({
+			status: "ok",
+			ollama: inferenceState.ollamaAvailable,
+			provider,
+			model,
+		});
+	});
+
+	/**
+	 * Chat Interface
+	 */
+	app.post("/chat", async (c) => {
+		try {
+			const body = await c.req.json<ChatRequest>();
+			const { sessionId, message, model } = body;
+			const result = await handleChat(sessionId, message, context, model);
+			return c.json(result);
+		} catch (error) {
+			return c.json({ error: String(error) }, 500);
+		}
+	});
+
+	/**
+	 * Metadata Enhancement
+	 */
+	app.post("/metadata/enhance", async (c) => {
+		try {
+			const body = await c.req.json<MetadataEnhanceRequest>();
+			const { docId } = body;
+			await handleMetadataEnhancement(docId, context);
+			return c.json({ status: "success" });
+		} catch (error) {
+			return c.json({ error: String(error) }, 500);
+		}
+	});
+
+	/**
+	 * Graph Stats
+	 */
+	app.get("/graph/stats", (c) => {
+		return c.json(context.graphEngine.getStats());
+	});
+
+	/**
+	 * Search: Query Analysis
+	 */
+	app.post("/search/analyze", async (c) => {
+		try {
+			const body = await c.req.json<SearchAnalyzeRequest>();
+			const { query } = body;
+			const result = await handleSearchAnalysis(query, context);
+			return c.json(result);
+		} catch (error) {
+			return c.json({ error: String(error) }, 500);
+		}
+	});
+
+	/**
+	 * Search: Reranking
+	 */
+	app.post("/search/rerank", async (c) => {
+		try {
+			const body = await c.req.json<SearchRerankRequest>();
+			const { results, query, intent } = body;
+			const result = await handleResultReranking(results, query, intent);
+			return c.json(result);
+		} catch (error) {
+			return c.json({ error: String(error) }, 500);
+		}
+	});
+
+	/**
+	 * Search: Context Extraction
+	 */
+	app.post("/search/context", async (c) => {
+		try {
+			const body = await c.req.json<SearchContextRequest>();
+			const { result, query } = body;
+			const contextResult = await handleContextExtraction(result, query);
+			return c.json(contextResult);
+		} catch (error) {
+			return c.json({ error: String(error) }, 500);
+		}
+	});
+
+	return app;
+}

package/src/mcp/README.md

@@ -1,6 +1,15 @@
 # 🔌 MCP Server
 
-The Model Context Protocol (MCP) server implementation for Polyvis.
+The Model Context Protocol (MCP) server implementation for Amalfa.
 
 ## Contents
 - **`index.ts`**: Entry point for the MCP server. Exposes tools (`search_documents`, `read_node_content`, etc.) and resources.
+
+## ⚠️ Stability
+This module is stable and intentionally designed.
+Do NOT refactor, rewrite, or change the architecture without:
+1. Consulting the user first
+2. Having a documented, compelling reason
+3. Understanding WHY the current design exists
+
+If something looks "wrong," it may be intentional. Ask before you chop.

package/src/resonance/DatabaseFactory.ts

@@ -3,8 +3,8 @@ import { Database } from "bun:sqlite";
 /**
  * 🏭 DATABASE FACTORY (The Enforcer)
  *
- * Single Source of Truth for instantiating SQLite connections in PolyVis.
- * strictly enforces the configuration defined in `playbooks/sqlite-standards.md`.
+ * Single Source of Truth for instantiating SQLite connections in Amalfa.
+ * Strictly enforces the configuration defined in `playbooks/sqlite-standards.md`.
  *
  * USAGE:
  * import { DatabaseFactory } from "@src/resonance/DatabaseFactory";
@@ -13,7 +13,7 @@ import { Database } from "bun:sqlite";
 export const DatabaseFactory = {
 	/**
 	 * Connects specifically to the main Resonance Graph database.
-	 * @deprecated Use connect() with explicit path from config instead.
+	 * Kept for convenience and backward compatibility.
 	 */
 	connectToResonance(
 		dbPath: string = ".amalfa/resonance.db",

package/src/resonance/README.md

@@ -1,6 +1,6 @@
 # 🔮 Resonance Engine
 
-The vector database and semantic core of Polyvis.
+The vector database and semantic core of Amalfa.
 
 ## Contents
 - **`daemon.ts`**: The Vector Service (HTTP) and Lifecycle Manager.
@@ -23,7 +23,7 @@ The vector database and semantic core of Polyvis.
 - **Accuracy:** High (51-52% on MTEB retrieval benchmarks)
 - **Training:** Optimized for retrieval tasks on 1B+ text pairs
 
-**Performance on Polyvis corpus:**
+**Performance on Amalfa corpus:**
 - 85.2% average best match (excellent semantic understanding)
 - 21.1% average spread (clear differentiation)
 - 76.3% average corpus score (cohesive knowledge base)
@@ -97,7 +97,7 @@ bun run inspect-db public/resonance.db
 
 ### Current: Two-Tier Search (Post-Migration v5)
 
-Polyvis uses a **hybrid search strategy** optimized for semantic understanding and exact matches:
+Amalfa uses a **hybrid search strategy** optimized for semantic understanding and exact matches:
 
 **1. Vector Search (Primary)**
 - **Purpose:** Semantic similarity, concept discovery
@@ -146,3 +146,12 @@ Query type?
 | ~~FTS~~ | ~~5-20ms~~ | ~~70%~~ | ~~(Removed)~~ |
 
 **Conclusion:** Two-tier search is simpler, faster, and more accurate than FTS middle ground.
+
+## ⚠️ Stability
+This module is stable and intentionally designed.
+Do NOT refactor, rewrite, or change the architecture without:
+1. Consulting the user first
+2. Having a documented, compelling reason
+3. Understanding WHY the current design exists
+
+If something looks "wrong," it may be intentional. Ask before you chop.

package/src/resonance/drizzle/README.md

@@ -0,0 +1,25 @@
+# Drizzle Schema Management
+
+## ⚠️ CRITICAL ARCHITECTURE RULE
+
+**Drizzle ORM is used HERE strictly for:**
+1.  **Schema Definition:** Single source of truth for table structures (`schema.ts`).
+2.  **Migrations:** Generating and running SQL migrations (`drizzle-kit`).
+
+**Drizzle ORM is NOT used for:**
+- **Runtime Queries:** Do NOT use Drizzle `db.select()` query builders in critical paths.
+- **Data Access:** All runtime data access uses `bun:sqlite` with raw parameterized SQL (`db.prepare()`).
+
+## Why?
+Our **FAFCAS** (Fast, Autonomous, Fractionally-Connected Agent System) architecture demands raw IO performance. We treat SQLite as a raw storage engine. The overhead of an ORM query builder—even a light one—is unnecessary.
+
+## ⛔ Agent Guardrail
+If you are an AI Agent reading this:
+- **DO NOT** refactor the existing `ResonanceDB` SQL queries to use Drizzle.
+- **DO NOT** introduce Drizzle usage into `GraphEngine` or `VectorEngine`.
+- **ONLY** modify this folder if the Database Schema (tables/columns) needs to change.
+
+## Workflow for Schema Changes
+1.  Edit `schema.ts`
+2.  Run `bunx drizzle-kit generate`
+3.  Run migrations (automated via scripts)

package/src/resonance/drizzle/migrations/0000_happy_thaddeus_ross.sql

@@ -0,0 +1,30 @@
+CREATE TABLE `edges` (
+	`source` text NOT NULL,
+	`target` text NOT NULL,
+	`type` text NOT NULL,
+	`confidence` real DEFAULT 1,
+	`veracity` real DEFAULT 1,
+	`context_source` text,
+	PRIMARY KEY(`source`, `target`, `type`)
+);
+--> statement-breakpoint
+CREATE INDEX `idx_edges_source` ON `edges` (`source`);--> statement-breakpoint
+CREATE INDEX `idx_edges_target` ON `edges` (`target`);--> statement-breakpoint
+CREATE TABLE `ember_state` (
+	`file_path` text PRIMARY KEY NOT NULL,
+	`last_analyzed` text,
+	`sidecar_created` integer,
+	`confidence` real
+);
+--> statement-breakpoint
+CREATE TABLE `nodes` (
+	`id` text PRIMARY KEY NOT NULL,
+	`type` text,
+	`title` text,
+	`domain` text,
+	`layer` text,
+	`embedding` blob,
+	`hash` text,
+	`meta` text,
+	`date` text
+);

package/src/resonance/drizzle/migrations/meta/0000_snapshot.json

@@ -0,0 +1,199 @@
+{
+	"version": "6",
+	"dialect": "sqlite",
+	"id": "577c9f07-f198-49d2-9fa3-f222a6ecee23",
+	"prevId": "00000000-0000-0000-0000-000000000000",
+	"tables": {
+		"edges": {
+			"name": "edges",
+			"columns": {
+				"source": {
+					"name": "source",
+					"type": "text",
+					"primaryKey": false,
+					"notNull": true,
+					"autoincrement": false
+				},
+				"target": {
+					"name": "target",
+					"type": "text",
+					"primaryKey": false,
+					"notNull": true,
+					"autoincrement": false
+				},
+				"type": {
+					"name": "type",
+					"type": "text",
+					"primaryKey": false,
+					"notNull": true,
+					"autoincrement": false
+				},
+				"confidence": {
+					"name": "confidence",
+					"type": "real",
+					"primaryKey": false,
+					"notNull": false,
+					"autoincrement": false,
+					"default": 1
+				},
+				"veracity": {
+					"name": "veracity",
+					"type": "real",
+					"primaryKey": false,
+					"notNull": false,
+					"autoincrement": false,
+					"default": 1
+				},
+				"context_source": {
+					"name": "context_source",
+					"type": "text",
+					"primaryKey": false,
+					"notNull": false,
+					"autoincrement": false
+				}
+			},
+			"indexes": {
+				"idx_edges_source": {
+					"name": "idx_edges_source",
+					"columns": ["source"],
+					"isUnique": false
+				},
+				"idx_edges_target": {
+					"name": "idx_edges_target",
+					"columns": ["target"],
+					"isUnique": false
+				}
+			},
+			"foreignKeys": {},
+			"compositePrimaryKeys": {
+				"edges_source_target_type_pk": {
+					"columns": ["source", "target", "type"],
+					"name": "edges_source_target_type_pk"
+				}
+			},
+			"uniqueConstraints": {},
+			"checkConstraints": {}
+		},
+		"ember_state": {
+			"name": "ember_state",
+			"columns": {
+				"file_path": {
+					"name": "file_path",
+					"type": "text",
+					"primaryKey": true,
+					"notNull": true,
+					"autoincrement": false
+				},
+				"last_analyzed": {
+					"name": "last_analyzed",
+					"type": "text",
+					"primaryKey": false,
+					"notNull": false,
+					"autoincrement": false
+				},
+				"sidecar_created": {
+					"name": "sidecar_created",
+					"type": "integer",
+					"primaryKey": false,
+					"notNull": false,
+					"autoincrement": false
+				},
+				"confidence": {
+					"name": "confidence",
+					"type": "real",
+					"primaryKey": false,
+					"notNull": false,
+					"autoincrement": false
+				}
+			},
+			"indexes": {},
+			"foreignKeys": {},
+			"compositePrimaryKeys": {},
+			"uniqueConstraints": {},
+			"checkConstraints": {}
+		},
+		"nodes": {
+			"name": "nodes",
+			"columns": {
+				"id": {
+					"name": "id",
+					"type": "text",
+					"primaryKey": true,
+					"notNull": true,
+					"autoincrement": false
+				},
+				"type": {
+					"name": "type",
+					"type": "text",
+					"primaryKey": false,
+					"notNull": false,
+					"autoincrement": false
+				},
+				"title": {
+					"name": "title",
+					"type": "text",
+					"primaryKey": false,
+					"notNull": false,
+					"autoincrement": false
+				},
+				"domain": {
+					"name": "domain",
+					"type": "text",
+					"primaryKey": false,
+					"notNull": false,
+					"autoincrement": false
+				},
+				"layer": {
+					"name": "layer",
+					"type": "text",
+					"primaryKey": false,
+					"notNull": false,
+					"autoincrement": false
+				},
+				"embedding": {
+					"name": "embedding",
+					"type": "blob",
+					"primaryKey": false,
+					"notNull": false,
+					"autoincrement": false
+				},
+				"hash": {
+					"name": "hash",
+					"type": "text",
+					"primaryKey": false,
+					"notNull": false,
+					"autoincrement": false
+				},
+				"meta": {
+					"name": "meta",
+					"type": "text",
+					"primaryKey": false,
+					"notNull": false,
+					"autoincrement": false
+				},
+				"date": {
+					"name": "date",
+					"type": "text",
+					"primaryKey": false,
+					"notNull": false,
+					"autoincrement": false
+				}
+			},
+			"indexes": {},
+			"foreignKeys": {},
+			"compositePrimaryKeys": {},
+			"uniqueConstraints": {},
+			"checkConstraints": {}
+		}
+	},
+	"views": {},
+	"enums": {},
+	"_meta": {
+		"schemas": {},
+		"tables": {},
+		"columns": {}
+	},
+	"internal": {
+		"indexes": {}
+	}
+}

package/src/resonance/drizzle/migrations/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+	"version": "7",
+	"dialect": "sqlite",
+	"entries": [
+		{
+			"idx": 0,
+			"version": "6",
+			"when": 1767981411501,
+			"tag": "0000_happy_thaddeus_ross",
+			"breakpoints": true
+		}
+	]
+}

package/src/resonance/drizzle/schema.ts

@@ -0,0 +1,60 @@
+import {
+	blob,
+	index,
+	integer,
+	primaryKey,
+	real,
+	sqliteTable,
+	text,
+} from "drizzle-orm/sqlite-core";
+
+/**
+ * NODES Table
+ * Core entity storage. Now "Hollow" (no content).
+ */
+export const nodes = sqliteTable("nodes", {
+	id: text("id").primaryKey(),
+	type: text("type"),
+	title: text("title"),
+	domain: text("domain"),
+	layer: text("layer"),
+	// Embeddings are stored as raw BLOBs (Float32Array bytes)
+	embedding: blob("embedding"),
+	hash: text("hash"),
+	meta: text("meta"), // JSON string
+	date: text("date"), // ISO string or YYYY-MM-DD
+});
+
+/**
+ * EDGES Table
+ * Defines relationships between nodes.
+ */
+export const edges = sqliteTable(
+	"edges",
+	{
+		source: text("source").notNull(),
+		target: text("target").notNull(),
+		type: text("type").notNull(),
+		confidence: real("confidence").default(1.0),
+		veracity: real("veracity").default(1.0),
+		contextSource: text("context_source"),
+	},
+	(table) => ({
+		// Composite Primary Key
+		pk: primaryKey({ columns: [table.source, table.target, table.type] }),
+		// Indices for traversal speed
+		sourceIdx: index("idx_edges_source").on(table.source),
+		targetIdx: index("idx_edges_target").on(table.target),
+	}),
+);
+
+/**
+ * EMBER STATE Table (Pilot)
+ * Tracks the state of the Ember Service (automated enrichment).
+ */
+export const emberState = sqliteTable("ember_state", {
+	filePath: text("file_path").primaryKey(),
+	lastAnalyzed: text("last_analyzed"),
+	sidecarCreated: integer("sidecar_created", { mode: "boolean" }),
+	confidence: real("confidence"),
+});

package/src/resonance/services/README.md

@@ -0,0 +1,42 @@
+# Resonance Services Directory
+
+## Purpose
+Service implementations for the Resonance engine - Amalfa's semantic memory and knowledge graph system. These services handle core operations like database interactions, graph traversal, and semantic queries.
+
+## Key Services
+
+| Service | Purpose |
+|---------|---------|
+| `DatabaseFactory` | Factory for creating database connections |
+| `GraphService` | Knowledge graph operations (nodes, edges, queries) |
+| `MemoryService` | Semantic memory storage and retrieval |
+| `EmbeddingService` | Text embedding generation and management |
+
+## Key Files
+
+- `index.ts` - Main exports of all services
+- `database.ts` - Database connection and query services
+- `graph.ts` - Knowledge graph traversal and manipulation
+- `semantic.ts` - Semantic similarity and search services
+
+## Patterns
+
+- Services are stateless where possible
+- Dependency injection for testability
+- Async/await for all I/O operations
+- Error handling with context-rich messages
+
+## Related
+
+- See also: `src/resonance/README.md` for overall resonance documentation
+- See also: `src/resonance/types/` for type definitions
+- See also: `src/resonance/pipeline/` for data processing pipelines
+
+## ⚠️ Stability
+This module is stable and intentionally designed.
+Do NOT refactor, rewrite, or change the architecture without:
+1. Consulting the user first
+2. Having a documented, compelling reason
+3. Understanding WHY the current design exists
+
+If something looks "wrong," it may be intentional. Ask before you chop.

package/src/resonance/types/README.md

@@ -0,0 +1,24 @@
+# Resonance Types Directory
+
+## Purpose
+Type definitions specific to the Resonance engine - Amalfa's semantic memory and knowledge graph system.
+
+## Key Files
+
+- `index.ts` - Main exports of resonance types
+- `graph.ts` - Knowledge graph node and edge types
+- `semantic.ts` - Semantic embedding and similarity types
+
+## Related
+
+- See also: `src/resonance/README.md` for overall resonance documentation
+- See also: `src/types/` for core Amalfa types
+
+## ⚠️ Stability
+This module is stable and intentionally designed.
+Do NOT refactor, rewrite, or change the architecture without:
+1. Consulting the user first
+2. Having a documented, compelling reason
+3. Understanding WHY the current design exists
+
+If something looks "wrong," it may be intentional. Ask before you chop.

package/src/types/README.md

@@ -0,0 +1,33 @@
+amalfa/src/types/README.md
+```
+
+# Type Definitions
+
+## Purpose
+The `types/` directory contains TypeScript type definitions used throughout the Amalfa application. These types ensure type safety and provide a single source of truth for data structures.
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `index.ts` | Main export barrel for all types |
+| `config.ts` | Configuration-related type definitions |
+| `resonance.ts` | Resonance engine type definitions |
+| `daemon.ts` | Daemon service type definitions |
+| `cli.ts` | CLI command type definitions |
+
+## Patterns
+
+- Use interfaces for object shapes
+- Use type aliases for unions and intersections
+- Export all types from `index.ts` for easy importing
+- Keep types focused and composable
+
+## ⚠️ Stability
+This module is stable and intentionally designed.
+Do NOT refactor, rewrite, or change the architecture without:
+1. Consulting the user first
+2. Having a documented, compelling reason
+3. Understanding WHY the current design exists
+
+If something looks "wrong," it may be intentional. Ask before you chop.

package/src/utils/README.md

@@ -0,0 +1,30 @@
+
+# Utils Directory
+
+## Purpose
+The `utils/` directory contains shared utility functions and helper modules used throughout the Amalfa application.
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `index.ts` | Main exports of utility functions |
+| `file.ts` | File system operations |
+| `logger.ts` | Logging utilities |
+| `validation.ts` | Common validation helpers |
+
+## Patterns
+
+- Pure functions where possible
+- Reusable across multiple modules
+- Well-documented with JSDoc comments
+- Side effects are clearly isolated
+
+## ⚠️ Stability
+This module is stable and intentionally designed.
+Do NOT refactor, rewrite, or change the architecture without:
+1. Consulting the user first
+2. Having a documented, compelling reason
+3. Understanding WHY the current design exists
+
+If something looks "wrong," it may be intentional. Ask before you chop.

package/src/pipeline/SemanticHarvester.ts

@@ -1,222 +0,0 @@
-/**
- * SemanticHarvester: TypeScript Bridge to Python Sieve+Net Pipeline
- *
- * Invokes the Python harvester via subprocess and loads the resulting
- * knowledge_graph.json artifact for integration with ResonanceDB.
- *
- * @example
- * const harvester = new SemanticHarvester();
- * const graph = await harvester.harvest("playbooks/");
- * await harvester.loadIntoResonance(graph);
- */
-
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-import { getLogger } from "@src/utils/Logger";
-import { $ } from "bun";
-
-export interface SemanticNode {
-	name: string;
-	type: "concept" | "document";
-	uri?: string;
-}
-
-export interface SemanticEdge {
-	source: string;
-	rel: string;
-	target: string;
-	confidence_score: number;
-	context_source?: string;
-}
-
-export interface KnowledgeGraph {
-	nodes: Record<string, { type: string; uri?: string }>;
-	edges: SemanticEdge[];
-}
-
-export class SemanticHarvester {
-	private readonly ingestDir: string;
-	private readonly venvPython: string;
-	private log = getLogger("Harvester");
-
-	constructor(projectRoot?: string) {
-		const root = projectRoot ?? process.cwd();
-		this.ingestDir = join(root, "ingest");
-		this.venvPython = join(this.ingestDir, ".venv", "bin", "python");
-	}
-
-	/**
-	 * Check if the Python environment is ready.
-	 */
-	async isReady(): Promise<boolean> {
-		// Check venv exists
-		if (!existsSync(this.venvPython)) {
-			this.log.warn(
-				"⚠️ Python venv not found. Run: cd ingest && python3 -m venv .venv && .venv/bin/pip install -r requirements.txt",
-			);
-			return false;
-		}
-
-		// Check classifier model exists
-		const classifierPath = join(this.ingestDir, "polyvis_classifier_v1");
-		if (!existsSync(classifierPath)) {
-			this.log.warn(
-				"⚠️ Classifier not trained. Run: cd ingest && .venv/bin/python train_classifier.py",
-			);
-			return false;
-		}
-
-		return true;
-	}
-
-	/**
-	 * Harvest semantic triples from a file or directory.
-	 *
-	 * @param target - Path to file or directory to process
-	 * @returns The extracted knowledge graph
-	 */
-	async harvest(target?: string): Promise<KnowledgeGraph> {
-		if (!(await this.isReady())) {
-			throw new Error("SemanticHarvester not ready. Check Python environment.");
-		}
-
-		this.log.info("🌾 Running Python Harvester...");
-
-		const harvesterScript = join(this.ingestDir, "harvester.py");
-		const args = target ? [harvesterScript, target] : [harvesterScript];
-
-		try {
-			const result = await $`${this.venvPython} ${args}`.quiet();
-
-			if (result.exitCode !== 0) {
-				this.log.error(
-					{ stderr: result.stderr.toString() },
-					"Harvester Failed",
-				);
-				throw new Error(`Harvester exited with code ${result.exitCode}`);
-			}
-
-			this.log.info(
-				{ output: result.stdout.toString().trim() },
-				"Harvester Success",
-			);
-		} catch (error) {
-			this.log.error({ err: error }, "Harvester Execution Error");
-			throw error;
-		}
-
-		// Load the artifact
-		const artifactPath = join(this.ingestDir, "knowledge_graph.json");
-		const artifact = await Bun.file(artifactPath).json();
-
-		return artifact as KnowledgeGraph;
-	}
-
-	/**
-	 * Get statistics about an extracted knowledge graph.
-	 */
-	getStats(graph: KnowledgeGraph): {
-		nodes: number;
-		edges: number;
-		concepts: number;
-		documents: number;
-	} {
-		const nodes = Object.keys(graph.nodes).length;
-		const edges = graph.edges.length;
-		const concepts = Object.values(graph.nodes).filter(
-			(n) => n.type === "concept",
-		).length;
-		const documents = Object.values(graph.nodes).filter(
-			(n) => n.type === "document",
-		).length;
-
-		return { nodes, edges, concepts, documents };
-	}
-
-	/**
-	 * Load a harvested knowledge graph into ResonanceDB.
-	 *
-	 * @param graph - The extracted knowledge graph from harvest()
-	 * @returns Statistics about the loaded data
-	 */
-	async loadIntoResonance(
-		graph: KnowledgeGraph,
-	): Promise<{ nodesLoaded: number; edgesLoaded: number }> {
-		// Lazy import to avoid circular dependencies
-		const { ResonanceDB } = await import("@src/resonance/db");
-
-		const db = ResonanceDB.init();
-		let nodesLoaded = 0;
-		let edgesLoaded = 0;
-
-		try {
-			db.beginTransaction();
-
-			// Load nodes
-			for (const [name, meta] of Object.entries(graph.nodes)) {
-				const nodeId = `semantic:${name.toLowerCase().replace(/\s+/g, "-")}`;
-				db.insertNode({
-					id: nodeId,
-					type: meta.type,
-					label: name,
-					domain: "semantic",
-					layer: "extracted",
-					meta: { uri: meta.uri, originalName: name },
-				});
-				nodesLoaded++;
-			}
-
-			// Load edges
-			for (const edge of graph.edges) {
-				const sourceId = `semantic:${edge.source.toLowerCase().replace(/\s+/g, "-")}`;
-				const targetId = `semantic:${edge.target.toLowerCase().replace(/\s+/g, "-")}`;
-
-				db.insertSemanticEdge(
-					sourceId,
-					targetId,
-					edge.rel.toLowerCase(),
-					edge.confidence_score,
-					1.0, // Default veracity
-					edge.context_source,
-				);
-				edgesLoaded++;
-			}
-
-			db.commit();
-			this.log.info(
-				{ nodes: nodesLoaded, edges: edgesLoaded },
-				"✅ Loaded Knowledge Graph into ResonanceDB",
-			);
-		} catch (error) {
-			db.rollback();
-			throw error;
-		} finally {
-			db.close();
-		}
-
-		return { nodesLoaded, edgesLoaded };
-	}
-}
-
-// --- CLI Test ---
-if (import.meta.main) {
-	const harvester = new SemanticHarvester();
-	// For CLI output, we can probably rely on the logger since it goes to stderr.
-	// Maybe we want pure console.log for "user facing" CLI output?
-	// But Logger.ts is configured to use pino. pino writes JSON.
-	// If the user runs this manually, they might pipe to pino-pretty.
-	// Let's keep it structured.
-
-	const log = getLogger("CLI");
-
-	log.info("Checking readiness...");
-	const ready = await harvester.isReady();
-	log.info({ ready }, "Readiness Check");
-
-	if (ready) {
-		const target = process.argv[2];
-		const graph = await harvester.harvest(target);
-		const stats = harvester.getStats(graph);
-		log.info({ stats }, "📊 Extraction Stats");
-	}
-}

package/src/resonance/cli/README.md

@@ -1,7 +0,0 @@
-# 🛠️ Resonance CLI
-
-Command-line tools for the Resonance Engine.
-
-## Contents
-- **`ingest.ts`**: The main ingestion pipeline script.
-- **`migrate.ts`**: Database schema migration utility.

package/src/resonance/pipeline/README.md

@@ -1,7 +0,0 @@
-# 🔄 Resonance Pipeline
-
-Data processing and extraction steps for the Resonance Engine.
-
-## Contents
-- **`extract.ts`**: Extracts high-value terms from the knowledge graph for frontend use.
-- **`transform_docs.ts`**: Prepares markdown documents for ingestion.