amalfa 0.0.0-reserved → 1.0.0

package/src/services/olmo3.ts

@@ -0,0 +1,58 @@
+import { join } from "node:path";
+import { ServiceLifecycle } from "../utils/ServiceLifecycle";
+
+// --- Configuration ---
+const BASE_DIR = join(import.meta.dir, "../../experiments/enlightenment");
+const BIN_PATH = join(BASE_DIR, "llama.cpp/build/bin/llama-server");
+const MODEL_PATH = join(BASE_DIR, "vectors/Olmo-3-7B-Think-Q4_K_M.gguf");
+
+const PORT = 8084;
+
+const args = process.argv.slice(2);
+const command = args[0] || "serve";
+
+// --- Service Lifecycle ---
+
+const lifecycle = new ServiceLifecycle({
+	name: "Olmo-3",
+	pidFile: ".olmo3.pid",
+	logFile: ".olmo3.log",
+	entryPoint: "src/services/olmo3.ts",
+});
+
+// --- Server Logic ---
+
+async function runServer() {
+	console.log(`🚀 Starting Olmo-3 Server on port ${PORT}...`);
+
+	const cmd = [
+		BIN_PATH,
+		"-m",
+		MODEL_PATH,
+		"--port",
+		PORT.toString(),
+		"--ctx-size",
+		"8192", // Reduced context for stability on Metal
+		"--n-gpu-layers",
+		"99", // Offload to GPU/Metal
+		"--jinja", // Jinja2 template support
+		"--reasoning-format",
+		"deepseek", // Separate partial thinking
+		"-fa",
+		"on", // Flash Attention
+		"--temp",
+		"0.6",
+	];
+
+	const serverProcess = Bun.spawn(cmd, {
+		stdout: "inherit",
+		stderr: "inherit",
+	});
+
+	// Wait for process to exit
+	await serverProcess.exited;
+}
+
+// --- Dispatch ---
+
+await lifecycle.run(command, runServer);

package/src/services/phi.ts

@@ -0,0 +1,52 @@
+import { join } from "node:path";
+import { ServiceLifecycle } from "../utils/ServiceLifecycle";
+
+// --- Configuration ---
+const BASE_DIR = join(import.meta.dir, "../../experiments/enlightenment");
+const BIN_PATH = join(BASE_DIR, "llama.cpp/build/bin/llama-server");
+const MODEL_PATH = join(BASE_DIR, "vectors/Phi-3.5-mini-instruct-Q4_K_M.gguf");
+
+const PORT = 8082;
+
+const args = process.argv.slice(2);
+const command = args[0] || "serve";
+
+// --- Service Lifecycle ---
+
+const lifecycle = new ServiceLifecycle({
+	name: "Phi-3.5",
+	pidFile: ".phi.pid",
+	logFile: ".phi.log",
+	entryPoint: "src/services/phi.ts",
+});
+
+// --- Server Logic ---
+
+async function runServer() {
+	console.log(`🚀 Starting Phi-3.5 Server on port ${PORT}...`);
+
+	const cmd = [
+		BIN_PATH,
+		"-m",
+		MODEL_PATH,
+		"--port",
+		PORT.toString(),
+		"--ctx-size",
+		"4096",
+		"--n-gpu-layers",
+		"99", // Offload to GPU/Metal
+		"--log-disable", // Keep clean for Phi
+	];
+
+	const serverProcess = Bun.spawn(cmd, {
+		stdout: "inherit",
+		stderr: "inherit",
+	});
+
+	// Wait for process to exit
+	await serverProcess.exited;
+}
+
+// --- Dispatch ---
+
+await lifecycle.run(command, runServer);

package/src/types/artifact.ts

@@ -0,0 +1,12 @@
+export interface IngestionArtifact {
+	id: string;
+	type: "playbook" | "debrief";
+	order_index: number;
+	payload: {
+		title: string;
+		content: string;
+		domain: string;
+		layer: string;
+		metadata?: Record<string, unknown>;
+	};
+}

package/src/utils/EnvironmentVerifier.ts

@@ -0,0 +1,67 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import settings from "../../polyvis.settings.json";
+
+/**
+ * EnvironmentVerifier
+ *
+ * Responsible for verifying that the runtime environment matches the
+ * expectations set in polyvis.settings.json.
+ *
+ * Usage:
+ * await EnvironmentVerifier.verifyOrExit();
+ */
+export const EnvironmentVerifier = {
+	async verifyOrExit(): Promise<void> {
+		const errors: string[] = [];
+		const cwd = process.cwd();
+
+		console.error(`🛡️  [Env] Verifying filesystem context in: ${cwd}`);
+
+		// 1. Verify Database Directory
+		const dbPath = settings.paths.database.resonance;
+		const dbDir = resolve(cwd, dbPath, "..");
+		if (!existsSync(dbDir)) {
+			errors.push(`Database directory missing: ${dbDir}`);
+		}
+
+		// 2. Verify Source Directories
+		// We iterate over the 'sources' config to ensure target folders exist
+		const experienceSources = settings.paths.sources.experience;
+		for (const source of experienceSources) {
+			const absPath = resolve(cwd, source.path);
+			if (!existsSync(absPath)) {
+				console.warn(
+					`   ⚠️  Optional source directory missing: ${source.path} (created automatically by some tools, but worth noting)`,
+				);
+				// We don't hard fail on standard folders, as they might be empty/missing in a fresh repo.
+				// But specifically for 'docs' or critical ones we might want to be stricter.
+				// For now, we WARN.
+			}
+		}
+
+		// 3. Verify Static Assets (Lexicon/CDA)
+		const lexiconPath = resolve(cwd, settings.paths.sources.persona.lexicon);
+		if (!existsSync(lexiconPath)) {
+			errors.push(`Critical Artifact missing: Lexicon (${lexiconPath})`);
+		}
+
+		const cdaPath = resolve(cwd, settings.paths.sources.persona.cda);
+		if (!existsSync(cdaPath)) {
+			errors.push(`Critical Artifact missing: CDA (${cdaPath})`);
+		}
+
+		if (errors.length > 0) {
+			console.error("\n❌ Environment Verification Failed:");
+			errors.forEach((e) => {
+				console.error(`   - ${e}`);
+			});
+			console.error(
+				"\nPlease ensure you are running from the project root and all assets are present.",
+			);
+			process.exit(1);
+		}
+
+		console.error("   ✅ Environment Verified.");
+	},
+};

package/src/utils/Logger.ts

@@ -0,0 +1,21 @@
+import pino, { type Logger } from "pino";
+export type { Logger };
+
+// Configure the base logger
+const loggerConfig: pino.LoggerOptions = {
+	level: process.env.LOG_LEVEL || "info",
+	base: undefined, // Remove pid/hostname from logs for cleanliness
+	timestamp: pino.stdTimeFunctions.isoTime,
+};
+
+// Default to stderr (fd 2) to prevent polluting stdout (critical for MCP/CLI piping)
+export const rootLogger = pino(loggerConfig, pino.destination(2));
+
+/**
+ * Creates a child logger with a bound component name.
+ * @param component The name of the component (e.g., 'Ingestor', 'MCP')
+ * @returns A pino logger instance suitable for that component
+ */
+export const getLogger = (component: string) => {
+	return rootLogger.child({ component });
+};

package/src/utils/ServiceLifecycle.ts

@@ -0,0 +1,207 @@
+import { existsSync } from "node:fs";
+import { unlink } from "node:fs/promises";
+import { ZombieDefense } from "./ZombieDefense";
+
+export interface ServiceConfig {
+	name: string; // e.g. "Daemon"
+	pidFile: string; // e.g. ".daemon.pid"
+	logFile: string; // e.g. ".daemon.log"
+	entryPoint: string; // e.g. "src/resonance/daemon.ts"
+}
+
+export class ServiceLifecycle {
+	constructor(private config: ServiceConfig) {}
+
+	private async isRunning(pid: number): Promise<boolean> {
+		try {
+			process.kill(pid, 0);
+			return true;
+		} catch (_e) {
+			return false;
+		}
+	}
+
+	/**
+	 * Start the service in the background (detached).
+	 */
+	async start() {
+		// Enforce clean state first (kill duplicates)
+		await ZombieDefense.assertClean(this.config.name, true);
+
+		// Check if already running based on PID file
+		if (await Bun.file(this.config.pidFile).exists()) {
+			const pid = parseInt(await Bun.file(this.config.pidFile).text(), 10);
+			if (await this.isRunning(pid)) {
+				console.log(`⚠️  ${this.config.name} is already running (PID: ${pid})`);
+				return;
+			}
+			console.log(
+				`⚠️  Found stale PID file for ${this.config.name}. Clearing...`,
+			);
+			await unlink(this.config.pidFile);
+		}
+
+		const logFile = Bun.file(this.config.logFile);
+		await Bun.write(logFile, ""); // Truncate logs
+
+		// Spawn subprocess
+		const subprocess = Bun.spawn(
+			["bun", "run", this.config.entryPoint, "serve"],
+			{
+				cwd: process.cwd(),
+				detached: true,
+				stdout: logFile,
+				stderr: logFile,
+			},
+		);
+
+		await Bun.write(this.config.pidFile, subprocess.pid.toString());
+		subprocess.unref();
+
+		console.log(
+			`✅ ${this.config.name} started in background (PID: ${subprocess.pid})`,
+		);
+		console.log(`📝 Logs: ${this.config.logFile}`);
+	}
+
+	/**
+	 * Stop the service using the PID file.
+	 */
+	async stop() {
+		if (!(await Bun.file(this.config.pidFile).exists())) {
+			console.log(`ℹ️  ${this.config.name} is not running.`);
+			return;
+		}
+
+		const pid = parseInt(await Bun.file(this.config.pidFile).text(), 10);
+
+		if (await this.isRunning(pid)) {
+			console.log(`🛑 Stopping ${this.config.name} (PID: ${pid})...`);
+			process.kill(pid, "SIGTERM");
+
+			let attempts = 0;
+			// Wait up to 1 second
+			while ((await this.isRunning(pid)) && attempts < 10) {
+				await new Promise((r) => setTimeout(r, 100));
+				attempts++;
+			}
+
+			if (await this.isRunning(pid)) {
+				console.log("⚠️  Process did not exit gracefully. Force killing...");
+				process.kill(pid, "SIGKILL");
+			}
+			console.log(`✅ ${this.config.name} stopped.`);
+		} else {
+			console.log("⚠️  Stale PID file found. Cleaning up.");
+		}
+
+		try {
+			await unlink(this.config.pidFile);
+		} catch (e: unknown) {
+			const err = e as { code?: string; message: string };
+			if (err.code !== "ENOENT") {
+				console.warn(`⚠️ Failed to remove PID file: ${err.message}`);
+			}
+		}
+	}
+
+	/**
+	 * Check status of the service.
+	 */
+	async status() {
+		if (await Bun.file(this.config.pidFile).exists()) {
+			const pid = parseInt(await Bun.file(this.config.pidFile).text(), 10);
+			if (await this.isRunning(pid)) {
+				console.log(`🟢 ${this.config.name} is RUNNING (PID: ${pid})`);
+				return;
+			}
+			console.log(`🔴 ${this.config.name} is NOT RUNNING (Stale PID: ${pid})`);
+		} else {
+			console.log(`⚪️ ${this.config.name} is STOPPED`);
+		}
+	}
+
+	/**
+	 * Wrapper for the foreground 'serve' command logic.
+	 * Use this to wrap your actual server startup code.
+	 */
+	async serve(serverLogic: () => Promise<void>, checkZombies = true) {
+		// Enforce clean state (ensure we aren't running as a zombie of ourselves)
+		if (checkZombies) {
+			await ZombieDefense.assertClean(`${this.config.name} (Serve)`);
+		}
+
+		// Register cleanup handlers to remove PID file on exit/crash/kill
+		let cleanupCalled = false;
+		const cleanup = async (signal?: string) => {
+			if (cleanupCalled) return; // Prevent double cleanup
+			cleanupCalled = true;
+
+			try {
+				if (await Bun.file(this.config.pidFile).exists()) {
+					await unlink(this.config.pidFile);
+					if (signal) {
+						console.error(
+							`\n🧹 ${this.config.name}: PID file cleaned up on ${signal}`,
+						);
+					}
+				}
+			} catch (_e) {
+				// Ignore cleanup errors (file might already be deleted)
+			}
+		};
+
+		// Register signal handlers
+		process.on("SIGINT", () => cleanup("SIGINT").then(() => process.exit(0)));
+		process.on("SIGTERM", () => cleanup("SIGTERM").then(() => process.exit(0)));
+		process.on("exit", () => {
+			// Note: exit event is synchronous, so we do sync cleanup
+			if (!cleanupCalled && existsSync(this.config.pidFile)) {
+				cleanupCalled = true;
+				try {
+					Bun.write(this.config.pidFile, ""); // Truncate to mark as stale
+				} catch {}
+			}
+		});
+
+		await serverLogic();
+	}
+
+	/**
+	 * Main CLI dispatch logic.
+	 */
+	async run(
+		command: string,
+		serverLogic: () => Promise<void>,
+		checkZombies = true,
+	) {
+		switch (command) {
+			case "start":
+				await this.start();
+				process.exit(0);
+				break;
+			case "stop":
+				await this.stop();
+				process.exit(0);
+				break;
+			case "status":
+				await this.status();
+				process.exit(0);
+				break;
+			case "restart":
+				await this.stop();
+				await new Promise((r) => setTimeout(r, 500));
+				await this.start();
+				process.exit(0);
+				break;
+			case "serve":
+				await this.serve(serverLogic, checkZombies);
+				break;
+			default:
+				console.log(
+					`Unknown command '${command}'. Use: start, stop, status, restart, or serve`,
+				);
+				process.exit(1);
+		}
+	}
+}

package/src/utils/ZombieDefense.ts

@@ -0,0 +1,244 @@
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+
+const execAsync = promisify(exec);
+
+export interface ZombieReport {
+	ghosts: string[];
+	duplicates: string[];
+	unknowns: string[];
+	clean: boolean;
+}
+
+// Services intended to run as singletons
+const WHITELIST = [
+	"src/resonance/daemon.ts",
+	"src/mcp/index.ts",
+	"scripts/cli/dev.ts",
+	"src/resonance/cli/ingest.ts",
+	"bun run build:data",
+	"bun run mcp",
+	"bun run daemon",
+	"bun run dev",
+	"bun run watch:css",
+	"bun run watch:js",
+	"scripts/verify/test_mcp_query.ts",
+	"src/services/olmo3.ts",
+	"src/services/phi.ts",
+	"src/services/llama.ts",
+	"src/services/llamauv.ts",
+	"scripts/cli/servers.ts",
+	"bun run olmo3",
+	"bun run phi",
+	"bun run llama",
+	"bun run llamauv",
+	"bun run servers",
+];
+
+export const ZombieDefense = {
+	/**
+	 * Scan the environment for unauthorized or stale processes.
+	 */
+	async scan(excludePids: string[] = []): Promise<ZombieReport> {
+		const report: ZombieReport = {
+			ghosts: [],
+			duplicates: [],
+			unknowns: [],
+			clean: true,
+		};
+
+		const protectedPids = new Set([
+			process.pid.toString(),
+			process.ppid.toString(),
+			...excludePids,
+		]);
+
+		// 1. Ghost Check (Deleted File Handles)
+		try {
+			const { stdout } = await execAsync("lsof +L1");
+			const lines = stdout.split("\n");
+			// Strict Filter: Only worry about resonance.db or files in our project scope
+			report.ghosts = lines.filter((l) => {
+				if (!l.includes("bun")) return false;
+				// Must be relevant file
+				return l.includes("resonance.db") || l.includes(process.cwd());
+			});
+		} catch (_e) {
+			// lsof exits 1 if nothing found
+		}
+
+		// 2. Process Table Check
+		try {
+			const { stdout } = await execAsync("ps aux | grep bun | grep -v grep");
+			const processes = stdout.split("\n").filter((l) => l.trim().length > 0);
+			const activeMap = new Map<string, number>();
+
+			processes.forEach((p) => {
+				// Ignore self and parent immediately
+				const match = p.match(/\s+(\d+)\s+/);
+				if (match?.[1] && protectedPids.has(match[1])) return;
+
+				// Strict Filter: Must be in our CWD or explicit bun run
+				if (!p.includes(process.cwd()) && !p.includes("bun run")) return;
+
+				const isWhitelisted = WHITELIST.some((w) => p.includes(w));
+
+				if (isWhitelisted) {
+					WHITELIST.forEach((w) => {
+						if (p.includes(w)) {
+							// HEURISTIC: Don't count "bun run scripts/foo.ts" and "bun scripts/foo.ts" as duplicates of each other if they are the same PID (obviously),
+							// but here we already filtered by PID.
+							// We need to be careful about the wrapper vs the actual process.
+
+							const count = (activeMap.get(w) || 0) + 1;
+							activeMap.set(w, count);
+							if (count > 1) {
+								report.duplicates.push(p);
+							}
+						}
+					});
+				} else {
+					// Ignore self (if running from a script calling this)
+					if (
+						!p.includes("detect_zombies.ts") &&
+						!p.includes("ZombieDefense")
+					) {
+						report.unknowns.push(p);
+					}
+				}
+			});
+		} catch (_e) {
+			// No bun processes
+		}
+
+		if (
+			report.ghosts.length > 0 ||
+			report.duplicates.length > 0 ||
+			report.unknowns.length > 0
+		) {
+			report.clean = false;
+		}
+
+		return report;
+	},
+
+	/**
+	 * Helper: Extract PIDs from report lines
+	 */
+	extractPids(lines: string[]): string[] {
+		const pids = new Set<string>();
+		lines.forEach((line) => {
+			const match = line.match(/\s+(\d+)\s+/);
+			if (match?.[1]) {
+				pids.add(match[1]);
+			}
+		});
+		return Array.from(pids);
+	},
+
+	/**
+	 * Terminate identified zombie PIDs
+	 */
+	async killZombies(report: ZombieReport) {
+		let targets = [
+			...new Set([
+				...this.extractPids(report.ghosts),
+				...this.extractPids(report.duplicates),
+			]),
+		];
+
+		// SAFETY: Exclude self
+		const selfPid = process.pid.toString();
+		targets = targets.filter((pid) => pid !== selfPid);
+
+		if (targets.length === 0) return;
+
+		console.error(
+			`🔪 Killing ${targets.length} zombie processes: ${targets.join(", ")}`,
+		);
+		try {
+			await execAsync(`kill -9 ${targets.join(" ")}`);
+			console.error("   ✅ Zombies terminated.");
+		} catch (err) {
+			const e = err as Error;
+			console.error(`   ❌ Failed to kill zombies: ${e.message}`);
+		}
+	},
+
+	/**
+	 * Enforce a clean state. Exits process if zombies found.
+	 * @param serviceName Name of the service calling this guard
+	 * @param interactive If true, prompts user to kill zombies.
+	 */
+	async assertClean(serviceName: string, interactive = false) {
+		if (process.env.SKIP_ZOMBIE_CHECK === "true") {
+			return;
+		}
+		console.error(`🛡️  [${serviceName}] Running Zombie Defense Protocol...`);
+		let report = await this.scan();
+
+		if (report.clean) {
+			console.error("   ✅ Environment Clean.");
+			return;
+		}
+
+		console.error("\n🛑 STARTUP ABORTED: ZOMBIE PROCESSES DETECTED");
+
+		if (report.ghosts.length > 0) {
+			console.error("\n👻 GHOSTS (Holding deleted files):");
+			report.ghosts.forEach((g) => {
+				console.error(`   ${g}`);
+			});
+		}
+
+		if (report.duplicates.length > 0) {
+			console.error("\n👯 DUPLICATES (Service already running?):");
+			report.duplicates.forEach((d) => {
+				console.error(`   ${d}`);
+			});
+		}
+
+		if (report.unknowns.length > 0) {
+			console.error(
+				"\n👽 UNKNOWNS (Rogue processes - Manual Check Recommended):",
+			);
+			report.unknowns.forEach((u) => {
+				console.error(`   ${u}`);
+			});
+		}
+
+		if (interactive) {
+			const targets = this.extractPids([
+				...report.ghosts,
+				...report.duplicates,
+			]);
+			if (targets.length > 0) {
+				process.stderr.write(
+					`\n👇 Found ${targets.length} confirmable zombies. Kill and Proceed? [y/N] `,
+				);
+				const answer = await new Promise<string>((resolve) => {
+					// Simple one-off prompt since Bun used here might not have 'prompt' in all envs
+					// Using Bun.stdin reader
+					process.stdin.once("data", (d) => resolve(d.toString().trim()));
+				});
+
+				if (answer.toLowerCase() === "y" || answer.toLowerCase() === "yes") {
+					await this.killZombies(report);
+					// Re-scan to verify
+					report = await this.scan();
+					if (report.clean) {
+						console.error("   ✅ Environment Cleared. Proceeding...");
+						return;
+					}
+					console.error("   ❌ Environment still dirty after kill attempt.");
+				}
+			}
+		} else {
+			console.error(
+				"\n👉 ACTION REQUIRED: Run 'pkill -f bun' to clear the environment.",
+			);
+		}
+
+		process.exit(1);
+	},
+};