amalfa 0.0.0-reserved → 1.0.0

package/schemas/conceptual-lexicon.schema.json

@@ -0,0 +1,75 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"title": "Conceptual Lexicon (CL) Schema",
+	"description": "Defines the structure for a Conceptual Lexicon file, which is an array of term and heuristic entries.",
+	"type": "array",
+	"items": {
+		"$ref": "#/definitions/lexiconEntry"
+	},
+	"definitions": {
+		"lexiconEntry": {
+			"type": "object",
+			"title": "Lexicon Entry",
+			"description": "A single entry (term or heuristic) in the Conceptual Lexicon.",
+			"properties": {
+				"id": {
+					"description": "The unique identifier for the entry (e.g., 'term-001', 'OH-040').",
+					"type": "string",
+					"pattern": "^[a-zA-Z0-9_-]+$"
+				},
+				"title": {
+					"description": "The human-readable title of the term or heuristic.",
+					"type": "string"
+				},
+				"description": {
+					"description": "The full definition of the entry. Can be a simple string or a structured object for complex definitions.",
+					"type": ["string", "object"]
+				},
+				"type": {
+					"description": "The type of the entry, e.g., 'term', 'operational-heuristic'.",
+					"type": "string"
+				},
+				"category": {
+					"description": "The category of the entry, e.g., 'Core Concept', 'Operational Heuristic'.",
+					"type": "string"
+				},
+				"tags": {
+					"description": "An optional array of tags for establishing relationships (e.g., '[Implements: COG-5]').",
+					"type": "array",
+					"items": {
+						"type": "string"
+					}
+				},
+				"source": {
+					"description": "The origin of the entry, typically 'cl'.",
+					"type": "string"
+				},
+				"external_refs": {
+					"description": "A list of external grounding resources (URLs, Citations, Code).",
+					"type": "array",
+					"items": {
+						"type": "object",
+						"properties": {
+							"label": {
+								"description": "Human-readable link text (e.g., 'Wikipedia', 'Source Code').",
+								"type": "string"
+							},
+							"url": {
+								"description": "The fully qualified URI.",
+								"type": "string",
+								"format": "uri"
+							},
+							"type": {
+								"description": "The nature of the reference.",
+								"type": "string",
+								"enum": ["source", "citation", "implementation", "example"]
+							}
+						},
+						"required": ["label", "url", "type"]
+					}
+				}
+			},
+			"required": ["id", "title", "description", "type"]
+		}
+	}
+}

package/scratchpads/dummy-debrief-boxed.md

@@ -0,0 +1,39 @@
+# Debrief: Project Alpha (Dummy)
+
+**Date:** 2025-12-12
+**Status:** Success
+
+
+<!-- bento-id: bento-f4290ac6 -->
+<!-- type: section -->
+## 1. Overview
+We successfully deployed the Alpha version. It was great.
+
+
+<!-- bento-id: bento-4dd57b85 -->
+<!-- type: section -->
+## 2. Technical Details
+We used a lot of code.
+
+### The Algorithm
+Here is the core loop:
+
+```typescript
+function coreLoop() {
+  console.log("Don't split me!");
+  // This is a comment inside code
+}
+```
+
+
+<!-- bento-id: bento-8cc779e9 -->
+<!-- type: section -->
+## 3. Lessons Learned
+- Don't eat yellow snow.
+- **Testing:** Is important.
+
+
+<!-- bento-id: bento-e4cea28f -->
+<!-- type: section -->
+## 4. Future Work
+We need to do more stuff.

package/scratchpads/dummy-debrief.md

@@ -0,0 +1,27 @@
+# Debrief: Project Alpha (Dummy)
+
+**Date:** 2025-12-12
+**Status:** Success
+
+## 1. Overview
+We successfully deployed the Alpha version. It was great.
+
+## 2. Technical Details
+We used a lot of code.
+
+### The Algorithm
+Here is the core loop:
+
+```typescript
+function coreLoop() {
+  console.log("Don't split me!");
+  // This is a comment inside code
+}
+```
+
+## 3. Lessons Learned
+- Don't eat yellow snow.
+- **Testing:** Is important.
+
+## 4. Future Work
+We need to do more stuff.

package/scratchpads/scratchpad-design.md

@@ -0,0 +1,50 @@
+# Design Scratchpad: AntiGravity Emulation
+
+**Goal**: Adopt the visual language of Google's AntiGravity agent.
+
+## 1. Core Philosophy
+- **High Contrast Dark Mode**: Deep backgrounds (`#202124` or darker), crisp white text (`#ffffff`), and subtle borders.
+- **Typography**: Clean, geometric sans-serif (Google Sans / Inter).
+- **Fluidity**: Responsive sizing for typography and spacing.
+- **"The Card"**: Distinct surfaces with subtle borders and rounded corners.
+
+## 2. Color Palette (Dark Mode)
+
+| Semantic Name | Value | Description |
+| :--- | :--- | :--- |
+| `--primary` | `#202124` | Main Background (Deep Gray) |
+| `--secondary` | `#ffffff` | Primary Text (Crisp White) |
+| `--accent` | `#303134` | Secondary Background / Sidebar |
+| `--surface-1` | `#202124` | App Background |
+| `--surface-2` | `#303134` | Card / Panel Background |
+| `--surface-hover` | `#3c4043` | Hover State |
+| `--border-base` | `#5f6368` | Subtle Borders |
+| `--link` | `#8ab4f8` | Google Blue (Links) |
+| `--link-visited` | `#c58af9` | Google Violet (Visited) |
+
+## 3. Typography
+
+- **Font Family**: `Inter, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif`
+- **Scale**:
+    - `xs`: `0.75rem`
+    - `sm`: `0.875rem`
+    - `base`: `1rem`
+    - `lg`: `1.125rem`
+    - `xl`: `1.25rem`
+    - `2xl`: `1.5rem`
+
+## 4. Spacing (Fluid)
+
+Using Open Props `size-fluid-*` where appropriate, but anchoring on a 4px grid.
+
+- `--spacing-1`: `4px`
+- `--spacing-2`: `8px`
+- `--spacing-3`: `12px`
+- `--spacing-4`: `16px` (Standard Gap)
+- `--spacing-5`: `20px`
+- `--spacing-6`: `24px`
+
+## 5. Implementation Strategy
+1.  **Update `theme.css`**: Replace existing color variables with the new palette.
+2.  **Refine Typography**: Ensure `Inter` is loaded or falls back gracefully.
+3.  **Component Audit**: Check Sidebars, Cards, and TOC for contrast issues.

package/scratchpads/scratchpad-scrolling.md

@@ -0,0 +1,20 @@
+# Scratchpad: Sidebar Scrolling Experiments
+
+## Problem Space
+The sidebars in `v3.html` are not scrolling.
+Structure: `aside` (Grid Cell) -> `div` (Container) -> `nav` (List).
+Current State: Both `aside` and `nav` might have overflow properties, or `nav` is not constrained.
+
+## Hypothesis 1: Nested Scroll Conflict
+If `aside` allows scrolling, the inner `div` grows to fit the content.
+If `div` grows, `nav` grows.
+Result: `nav` never overflows its container, so its scrollbar never triggers. The `aside` scrollbar *should* trigger, but might be hidden or behaving oddly due to `app-shell` grid constraints.
+
+## Experiment 1: Lock Parent, Scroll Child
+**Goal**: Make `nav` the *only* scrollable element.
+1.  `aside`: `overflow: hidden` (Don't scroll).
+2.  `div.docs-directory`: `h-full flex flex-col overflow: hidden` (Constrain height, don't scroll).
+3.  `nav`: `flex-1 overflow-y-auto min-h-0` (Fill space, scroll if needed, allow shrinking).
+
+## Log
+-   [ ] Experiment 1

package/scratchpads/scratchpad-toc-disappearance.md

@@ -0,0 +1,23 @@
+# Scratchpad: TOC Disappearance Investigation
+
+## Problem
+The Table of Contents (TOC) for `hi-fi-css.md` (and potentially others) has become invisible or empty after changing the font size from `text-sm` to `text-base`.
+
+## Context
+- **Previous Change**: Increased vertical padding (`py-1` -> `py-1.5`) and font size (`text-sm` -> `text-base`).
+- **User Report**: "now there is nothing visible in the outline".
+- **Previous Issue**: `Alpine Warning: x-for ":key" is undefined` (Fixed by ensuring unique IDs).
+
+## Hypotheses
+1.  **CSS Overflow/Visibility**: The larger text might be pushing content out of a constrained container, or `truncate` is hiding everything if the width is too small.
+2.  **Alpine.js Crash**: The previous fix for IDs might have introduced a syntax error or logic error that crashes the Alpine component, preventing rendering.
+3.  **Data Binding**: The `toc` array might be empty despite the ID fix.
+
+## Experiment Plan (Variable Reduction)
+1.  **Revert Font Size**: Temporarily revert `text-base` to `text-sm` to see if visibility returns. (Isolates CSS vs Logic).
+2.  **Console Logging**: Add aggressive logging in `doc-viewer.js` to confirm `toc` array population and Alpine lifecycle hooks.
+3.  **Inspect DOM**: Use browser tool (if stable) or `view_file` to check if the `<a>` tags exist in the DOM but are hidden.
+
+## Action Log
+- [ ] Create Scratchpad.
+- [ ] Propose Plan.

package/scratchpads/scratchpad-toc.md

@@ -0,0 +1,28 @@
+# Scratchpad: TOC Generation Debugging
+
+## Problem
+The Table of Contents (TOC) for `public/docs/hi-fi-css.md` only shows the document title. Other headings are missing.
+
+## Target File
+`public/docs/hi-fi-css.md`
+
+## Hypotheses
+1.  **Header Levels**: The file might use `h1` or `h4+` which are not captured by `querySelectorAll('h2, h3')`.
+2.  **Parsing Timing**: `generateToC` might run before the DOM is fully updated (though `$nextTick` should prevent this).
+3.  **Marked Config**: The custom renderer might be malformed.
+
+## Investigation Log
+-   [x] Inspect `hi-fi-css.md` content.
+    -   **Finding**: File uses `h1`, `h2`, `h3`, and **many `h4`** headers.
+-   [x] Inspect `doc-viewer.js`.
+    -   **Finding**: `generateToC` only queries `h2, h3`.
+-   [x] Inspect rendered DOM in Browser.
+    -   **Confirmed**: `h4` elements exist but are ignored.
+-   [x] Fix: Add `h4` to `querySelectorAll`.
+    -   **Action**: Updated `doc-viewer.js` to query `h2, h3, h4`.
+-   [ ] **Re-Investigation**: User reports TOC still empty.
+    -   **Hypothesis 1**: `marked` renderer issue with bold tags `**` in headers?
+    -   **Hypothesis 2**: `generateToC` timing (DOM not ready)?
+    -   **Action**: Inspect `#main-content` HTML and Alpine `$data.toc`.
+    -   **Result**: Programmatic test confirmed `h4`s are present (6 count) and `toc` array is populated (39 items).
+    -   **Conclusion**: The fix works. User might be seeing cached state.

package/scratchpads/test_gardener.md

@@ -0,0 +1,7 @@
+# Test Gardener Seed
+
+This is a test file to verify the Auto-Tagger agent.
+It discusses **Artificial Intelligence** and **Knowledge Graphs**.
+It also mentions **Neural Networks** and **Semantic Search**.
+
+Hopefully the gardener finds this and adds tags.

package/src/EnlightenedTriad.ts

@@ -0,0 +1,146 @@
+// --- CONFIGURATION ---
+const PORTS = {
+	SCOUT: 8082, // Phi-3.5 (Fast Entity Extraction)
+	ARCHITECT: 8083, // Llama-3 (Strict Logic/JSON)
+	AUDITOR: 8084, // Olmo-3 (Deep Thinking)
+};
+
+interface AuditResult {
+	passed: boolean;
+	verdict: string;
+	thought_trace: string;
+}
+
+export class EnlightenedTriad {
+	/**
+	 * THE SCOUT (Phi-3.5)
+	 * "The Bouncer"
+	 * Task: Fast, cheap filtering.
+	 */
+	async scout(context: string, extractionTask: string): Promise<string> {
+		return this.callAgent(PORTS.SCOUT, [
+			{
+				role: "system",
+				content:
+					"You are a precise data extractor. Return only the requested data. No filler.",
+			},
+			{
+				role: "user",
+				content: `Context: ${context}\n\nTask: ${extractionTask}`,
+			},
+		]);
+	}
+
+	/**
+	 * THE ARCHITECT (Llama-3 + Accountant Vector)
+	 * "The Builder"
+	 * Task: Structure raw text into strict JSON.
+	 */
+	async architect(unstructuredData: string): Promise<unknown> {
+		const response = await this.callAgent(PORTS.ARCHITECT, [
+			{ role: "system", content: "Output JSON only." },
+			{
+				role: "user",
+				content: `Convert to Causal Graph JSON: ${unstructuredData}`,
+			},
+		]);
+
+		try {
+			// Strip markdown code blocks if present
+			const cleanJson = response
+				.replace(/```json/g, "")
+				.replace(/```/g, "")
+				.trim();
+			return JSON.parse(cleanJson);
+		} catch (_e) {
+			console.error("❌ Architect JSON Error. Raw output:", response);
+			return null;
+		}
+	}
+
+	/**
+	 * THE AUDITOR (Olmo-3-Think)
+	 * "The QA Department"
+	 * Task: Think for 2 minutes, then vote Yes/No.
+	 */
+	async audit(claim: string): Promise<AuditResult> {
+		// High temp for creative debugging/thinking
+		const rawOutput = await this.callAgent(
+			PORTS.AUDITOR,
+			[
+				{
+					role: "user",
+					content: `Analyze the validity of this logical claim. \n\nClaim: "${claim}"\n\nShow your thinking process wrapped in <think> tags like this: <think> ... </think>, then end with 'VERDICT: PASS' or 'VERDICT: FAIL'.`,
+				},
+			],
+			{ temperature: 0.6, max_tokens: 2048 },
+		);
+
+		// --- THE PARSER ---
+		// Olmo uses <think> tags. We split the "Raj" monologue from the Answer.
+		let thoughtTrace = "";
+		let finalAnswer = "";
+
+		const thinkMatch = rawOutput.match(/<think>([\s\S]*?)<\/think>/);
+
+		if (thinkMatch?.[1]) {
+			// case 1: structured output
+			thoughtTrace = thinkMatch[1].trim();
+			finalAnswer = rawOutput.replace(thinkMatch[0], "").trim();
+		} else if (rawOutput.includes("VERDICT:")) {
+			// case 2: implicit separation (fallback)
+			const parts = rawOutput.split("VERDICT:");
+			thoughtTrace = parts[0]?.trim() ?? "";
+			// Reconstruct the verdict part
+			finalAnswer = `VERDICT:${parts.slice(1).join("VERDICT:")}`.trim();
+		} else {
+			// case 3: total failure to structure
+			thoughtTrace = rawOutput;
+			finalAnswer = "VERDICT: FAIL (Parse Error)";
+		}
+
+		const passed = finalAnswer.includes("VERDICT: PASS");
+
+		return {
+			passed,
+			verdict: finalAnswer, // The short answer for UI
+			thought_trace: thoughtTrace, // The monologue for DB/Audit
+		};
+	}
+
+	// --- UTILS (Bun Native Fetch) ---
+	private async callAgent(
+		port: number,
+		messages: { role: string; content: string }[],
+		options: { temperature?: number; max_tokens?: number } = {},
+	): Promise<string> {
+		try {
+			const response = await fetch(
+				`http://127.0.0.1:${port}/v1/chat/completions`,
+				{
+					method: "POST",
+					headers: { "Content-Type": "application/json" },
+					body: JSON.stringify({
+						messages,
+						temperature: options.temperature || 0.1,
+						n_predict: options.max_tokens || 512,
+					}),
+				},
+			);
+
+			if (!response.ok) {
+				throw new Error(
+					`HTTP Error ${response.status}: ${response.statusText}`,
+				);
+			}
+
+			const data = (await response.json()) as {
+				choices: { message: { content: string } }[];
+			};
+			return data.choices?.[0]?.message?.content || "";
+		} catch (_error) {
+			console.error(`❌ Agent at Port ${port} is offline/unreachable.`);
+			return "AGENT_OFFLINE";
+		}
+	}
+}

package/src/JIT_Triad.ts

@@ -0,0 +1,137 @@
+import { type Subprocess, spawn } from "bun";
+import { EnlightenedTriad } from "./EnlightenedTriad"; // Re-using your existing interface
+
+// --- CONFIGURATION ---
+const BASE_DIR = `${import.meta.dir}/../experiments/enlightenment`; // Adjust relative to src/
+const BIN_PATH = `${BASE_DIR}/llama.cpp/build/bin/llama-server`;
+const VECTORS_DIR = `${BASE_DIR}/vectors`;
+
+const AGENTS = {
+	SCOUT: {
+		port: 8082,
+		model: `${VECTORS_DIR}/Phi-3.5-mini-instruct-Q4_K_M.gguf`,
+		ctx: 4096,
+		vector: null,
+	},
+	ARCHITECT: {
+		port: 8083,
+		model: `${VECTORS_DIR}/Meta-Llama-3-8B-Instruct-Q4_K_M.gguf`,
+		ctx: 8192,
+		vector: `${VECTORS_DIR}/enlightenment_vector_v2.gguf`,
+		scale: "-0.3",
+	},
+	AUDITOR: {
+		port: 8084,
+		model: `${VECTORS_DIR}/Olmo-3-7B-Think-Q4_K_M.gguf`,
+		ctx: 8192,
+		vector: null,
+	},
+};
+
+let currentProcess: Subprocess | null = null;
+
+// --- LIFECYCLE MANAGER ---
+async function bootAgent(role: keyof typeof AGENTS) {
+	if (currentProcess) {
+		console.log("♻️  Freeing VRAM (Stopping previous agent)...");
+		currentProcess.kill();
+		await new Promise((r) => setTimeout(r, 1000)); // Cool down
+	}
+
+	const config = AGENTS[role];
+	console.log(`🚀 Booting ${role} on Port ${config.port}...`);
+
+	const args = [
+		BIN_PATH,
+		"-m",
+		config.model,
+		"--port",
+		config.port.toString(),
+		"--ctx-size",
+		config.ctx.toString(),
+		"--n-gpu-layers",
+		"99", // Metal
+		"--log-disable", // Keep console clean
+	];
+
+	if (config.vector) {
+		args.push("--control-vector-scaled", `${config.vector}:${config.scale}`);
+	}
+
+	// Spawn via Bun
+	currentProcess = spawn(args, {
+		stdout: "ignore", // Silence server logs
+		stderr: "ignore",
+	});
+
+	// Wait for Health Check
+	process.stdout.write("   Waiting for neural activity...");
+	for (let i = 0; i < 30; i++) {
+		try {
+			const res = await fetch(`http://127.0.0.1:${config.port}/health`);
+			if (res.ok) {
+				console.log(" Online! 🟢");
+				return;
+			}
+		} catch (_e) {}
+		await new Promise((r) => setTimeout(r, 500));
+		process.stdout.write(".");
+	}
+	throw new Error(`${role} failed to start.`);
+}
+
+async function shutdown() {
+	if (currentProcess) {
+		console.log("\n🛑 Shutting down final agent...");
+		currentProcess.kill();
+	}
+}
+
+// --- THE DEMO FLOW ---
+async function runOptimizedPipeline() {
+	const triad = new EnlightenedTriad();
+
+	try {
+		console.log("⚡️ SYSTEM ONLINE: Engaging OPTIMIZED Intelligence...\n");
+		const rawLog =
+			"2025-12-19 14:02:11 [CRITICAL] Connection refused at 192.168.1.5 (DB_SHARD_04). Latency 4005ms.";
+
+		// --- STEP 1: SCOUT ---
+		await bootAgent("SCOUT");
+		console.log("\n--- 🕵️ SCOUT TASK ---");
+		const scoutResult = await triad.scout(
+			rawLog,
+			"Extract IP and Error Message. No notes.",
+		);
+		console.log(`>> Output: ${scoutResult}`);
+
+		// --- STEP 2: ARCHITECT ---
+		await bootAgent("ARCHITECT");
+		console.log("\n--- 📐 ARCHITECT TASK ---");
+		const architectResult = await triad.architect(scoutResult);
+		console.log(`>> Output:`, JSON.stringify(architectResult, null, 2));
+
+		// --- STEP 3: AUDITOR ---
+		await bootAgent("AUDITOR");
+		console.log("\n--- 🧠 AUDITOR TASK ---");
+		const claim = `The error 'Connection refused' caused the high latency.`;
+		const auditResult = await triad.audit(claim);
+
+		console.log(
+			`\n📝 THOUGHT TRACE:\n${auditResult.thought_trace.substring(0, 300)}...`,
+		);
+		console.log(`\n⚖️ VERDICT: ${auditResult.passed ? "✅ PASS" : "❌ FAIL"}`);
+	} catch (error) {
+		console.error("\n💥 Pipeline Error:", error);
+	} finally {
+		await shutdown();
+	}
+}
+
+// Handle Ctrl+C
+process.on("SIGINT", async () => {
+	await shutdown();
+	process.exit(0);
+});
+
+runOptimizedPipeline();