bilmem 0.1.0

package/dist/storage/index.js

@@ -0,0 +1,1748 @@
+// src/storage/canonical.ts
+import * as fs3 from "fs/promises";
+import * as path3 from "path";
+
+// src/rules/loader.ts
+import YAML from "yaml";
+import * as fs from "fs/promises";
+import * as path from "path";
+function validateRuleDefinition(rule, index = 0) {
+  const errors = [];
+  if (!rule || typeof rule !== "object") {
+    errors.push(`Rule at index ${index} must be an object.`);
+    return errors;
+  }
+  const r = rule;
+  if (!r.id || typeof r.id !== "string" || !r.id.trim()) {
+    errors.push(`Rule at index ${index} requires a non-empty string 'id'.`);
+  }
+  if (!r.statement || typeof r.statement !== "string" || !r.statement.trim()) {
+    errors.push(`Rule '${r.id || index}' requires a non-empty string 'statement'.`);
+  }
+  if (r.type) {
+    const validTypes = [
+      "rule",
+      "convention",
+      "decision",
+      "lesson",
+      "architecture",
+      "fact"
+    ];
+    if (!validTypes.includes(r.type)) {
+      errors.push(`Rule '${r.id || index}' has invalid type '${r.type}'. Allowed: ${validTypes.join(", ")}.`);
+    }
+  }
+  if (r.confidence !== void 0) {
+    if (typeof r.confidence !== "number" || r.confidence < 0 || r.confidence > 1) {
+      errors.push(`Rule '${r.id || index}' confidence must be a number between 0.0 and 1.0.`);
+    }
+  }
+  if (r.positive !== void 0 && !Array.isArray(r.positive)) {
+    errors.push(`Rule '${r.id || index}' positive cues must be an array of strings.`);
+  }
+  if (r.negative !== void 0 && !Array.isArray(r.negative)) {
+    errors.push(`Rule '${r.id || index}' negative cues must be an array of strings.`);
+  }
+  return errors;
+}
+function validateRuleSet(data) {
+  const errors = [];
+  if (!data || typeof data !== "object") {
+    return { valid: false, errors: ["RuleSet content must be an object or an array of rules."] };
+  }
+  let rules = [];
+  if (Array.isArray(data)) {
+    rules = data;
+  } else if ("rules" in data && Array.isArray(data.rules)) {
+    rules = data.rules;
+  } else if ("id" in data && "statement" in data) {
+    rules = [data];
+  } else {
+    return { valid: false, errors: ['RuleSet must contain a "rules" array or be a list of rule definitions.'] };
+  }
+  if (rules.length === 0) {
+    errors.push("RuleSet contains no rules.");
+  }
+  rules.forEach((rule, idx) => {
+    errors.push(...validateRuleDefinition(rule, idx));
+  });
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+function parseRuleSetYaml(content, sourcePath = "inline.yml") {
+  let parsed;
+  try {
+    parsed = YAML.parse(content);
+  } catch (err) {
+    throw new Error(`YAML syntax error in ${sourcePath}: ${err.message}`);
+  }
+  const validation = validateRuleSet(parsed);
+  if (!validation.valid) {
+    throw new Error(`Invalid RuleSet in ${sourcePath}:
+- ${validation.errors.join("\n- ")}`);
+  }
+  if (Array.isArray(parsed)) {
+    return {
+      name: path.basename(sourcePath, path.extname(sourcePath)),
+      rules: parsed
+    };
+  }
+  if ("id" in parsed && "statement" in parsed && !("rules" in parsed)) {
+    return {
+      name: parsed.id,
+      rules: [parsed]
+    };
+  }
+  const set = parsed;
+  return {
+    name: set.name ?? path.basename(sourcePath, path.extname(sourcePath)),
+    version: set.version ?? 1,
+    scope: set.scope ?? "project",
+    description: set.description,
+    rules: set.rules
+  };
+}
+function stringifyRuleSetYaml(ruleSet) {
+  const payload = {};
+  if (ruleSet.name) payload.name = ruleSet.name;
+  if (ruleSet.version !== void 0) payload.version = ruleSet.version;
+  if (ruleSet.scope) payload.scope = ruleSet.scope;
+  if (ruleSet.description) payload.description = ruleSet.description;
+  payload.rules = ruleSet.rules.map((r) => {
+    const ruleObj = {
+      id: r.id
+    };
+    if (r.name) ruleObj.name = r.name;
+    ruleObj.statement = r.statement;
+    if (r.type && r.type !== "rule") ruleObj.type = r.type;
+    if (r.confidence !== void 0 && r.confidence !== 0.95) ruleObj.confidence = r.confidence;
+    if (r.scope && r.scope !== "project") ruleObj.scope = r.scope;
+    if (r.positive && r.positive.length > 0) ruleObj.positive = r.positive;
+    if (r.negative && r.negative.length > 0) ruleObj.negative = r.negative;
+    if (r.tags && r.tags.length > 0) ruleObj.tags = r.tags;
+    if (r.when && Object.keys(r.when).length > 0) ruleObj.when = r.when;
+    if (r.details && Object.keys(r.details).length > 0) ruleObj.details = r.details;
+    return ruleObj;
+  });
+  return YAML.stringify(payload, { indent: 2, lineWidth: 100 });
+}
+async function loadRuleSetFile(filePath) {
+  const content = await fs.readFile(filePath, "utf-8");
+  return parseRuleSetYaml(content, filePath);
+}
+async function findRuleFiles(rootDir, storageRulesDir) {
+  const candidates = [];
+  const rulesDir = storageRulesDir || path.resolve(rootDir, ".bilmem", "rules");
+  try {
+    const entries = await fs.readdir(rulesDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isFile() && (entry.name.endsWith(".yml") || entry.name.endsWith(".yaml"))) {
+        candidates.push(path.join(rulesDir, entry.name));
+      }
+    }
+  } catch {
+  }
+  for (const name of ["rules.yml", "rules.yaml"]) {
+    const p = path.resolve(rootDir, ".bilmem", name);
+    try {
+      const st = await fs.stat(p);
+      if (st.isFile()) candidates.push(p);
+    } catch {
+    }
+  }
+  for (const name of ["bilmem.rules.yml", "bilmem.rules.yaml", "rules.yml", "rules.yaml"]) {
+    const p = path.resolve(rootDir, name);
+    try {
+      const st = await fs.stat(p);
+      if (st.isFile()) candidates.push(p);
+    } catch {
+    }
+  }
+  return Array.from(new Set(candidates));
+}
+
+// src/stats/events.ts
+import * as fs2 from "fs/promises";
+import * as path2 from "path";
+function getEventsFilePath(rootDir) {
+  return path2.join(rootDir, ".bilmem", "events.jsonl");
+}
+async function readMetricEvents(rootDir, filter) {
+  const filePath = getEventsFilePath(rootDir);
+  let raw;
+  try {
+    raw = await fs2.readFile(filePath, "utf-8");
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      return [];
+    }
+    return [];
+  }
+  const lines = raw.split("\n");
+  const events = [];
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (!parsed || typeof parsed !== "object" || typeof parsed.type !== "string") {
+        continue;
+      }
+      if (typeof parsed.timestamp !== "number") {
+        continue;
+      }
+      if (filter?.sinceTimestamp !== void 0 && parsed.timestamp < filter.sinceTimestamp) {
+        continue;
+      }
+      if (filter?.knowledgeId !== void 0) {
+        const kid = parsed.knowledgeId;
+        if (kid !== filter.knowledgeId) {
+          continue;
+        }
+      }
+      events.push(parsed);
+    } catch {
+      continue;
+    }
+  }
+  return events;
+}
+async function resetMetricEvents(rootDir) {
+  const filePath = getEventsFilePath(rootDir);
+  try {
+    await fs2.mkdir(path2.dirname(filePath), { recursive: true });
+    await fs2.writeFile(filePath, "", "utf-8");
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+  }
+}
+
+// src/storage/canonical.ts
+function sanitizeFileName(id) {
+  return encodeURIComponent(id).replace(/%/g, "_");
+}
+function desanitizeFileName(name) {
+  try {
+    return decodeURIComponent(name.replace(/_/g, "%"));
+  } catch {
+    return name;
+  }
+}
+var Storage = class {
+  baseDir;
+  knowledgeDir;
+  evidenceDir;
+  observationDir;
+  unknownDir;
+  rulesDir;
+  configFile;
+  relationsFile;
+  outcomesFile;
+  metricsFile;
+  revisionsFile;
+  knowledgeJsonlFile;
+  evidenceJsonlFile;
+  observationJsonlFile;
+  unknownsJsonlFile;
+  receiptsDir;
+  receiptsJsonlFile;
+  eventsFile;
+  constructor(rootDir = process.cwd()) {
+    this.baseDir = path3.resolve(rootDir, ".bilmem");
+    this.knowledgeDir = path3.join(this.baseDir, "knowledge");
+    this.evidenceDir = path3.join(this.baseDir, "evidence");
+    this.observationDir = path3.join(this.baseDir, "observations");
+    this.unknownDir = path3.join(this.baseDir, "unknowns");
+    this.rulesDir = path3.join(this.baseDir, "rules");
+    this.receiptsDir = path3.join(this.baseDir, "receipts");
+    this.configFile = path3.join(this.baseDir, "config.json");
+    this.relationsFile = path3.join(this.baseDir, "relations.json");
+    this.outcomesFile = path3.join(this.baseDir, "outcomes.jsonl");
+    this.metricsFile = path3.join(this.baseDir, "metrics.json");
+    this.revisionsFile = path3.join(this.baseDir, "revisions.jsonl");
+    this.knowledgeJsonlFile = path3.join(this.baseDir, "knowledge.jsonl");
+    this.evidenceJsonlFile = path3.join(this.baseDir, "evidence.jsonl");
+    this.observationJsonlFile = path3.join(this.baseDir, "observations.jsonl");
+    this.unknownsJsonlFile = path3.join(this.baseDir, "unknowns.jsonl");
+    this.receiptsJsonlFile = path3.join(this.baseDir, "receipts.jsonl");
+    this.eventsFile = path3.join(this.baseDir, "events.jsonl");
+  }
+  getBaseDir() {
+    return this.baseDir;
+  }
+  async isInitialized() {
+    try {
+      await fs3.access(this.configFile);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async init(options = {}) {
+    await fs3.mkdir(this.knowledgeDir, { recursive: true });
+    await fs3.mkdir(this.evidenceDir, { recursive: true });
+    await fs3.mkdir(this.observationDir, { recursive: true });
+    await fs3.mkdir(this.unknownDir, { recursive: true });
+    await fs3.mkdir(this.rulesDir, { recursive: true });
+    await fs3.mkdir(this.receiptsDir, { recursive: true });
+    let config;
+    if (await this.isInitialized()) {
+      config = await this.getConfig();
+    } else {
+      config = {
+        schemaVersion: 1,
+        projectName: options.projectName ?? path3.basename(path3.dirname(this.baseDir)) ?? "project",
+        defaultScope: options.defaultScope ?? "project",
+        dataDir: this.baseDir
+      };
+      await this.saveConfig(config);
+    }
+    try {
+      await fs3.access(this.relationsFile);
+    } catch {
+      await fs3.writeFile(this.relationsFile, JSON.stringify([], null, 2), "utf-8");
+    }
+    try {
+      await fs3.access(this.metricsFile);
+    } catch {
+      const defaultMetrics = {
+        knowledgeHits: 0,
+        knowledgeMisses: 0,
+        knowledgeReused: 0,
+        unknownsResolved: 0,
+        repeatedInvestigationsPrevented: 0,
+        candidateKnowledgeMerged: 0,
+        staleKnowledgeDetected: 0,
+        contradictionsDetected: 0,
+        knowledgePromoted: 0,
+        knowledgeSuperseded: 0
+      };
+      await fs3.writeFile(this.metricsFile, JSON.stringify(defaultMetrics, null, 2), "utf-8");
+    }
+    return config;
+  }
+  // --- Config ---
+  async getConfig() {
+    const raw = await fs3.readFile(this.configFile, "utf-8");
+    return JSON.parse(raw);
+  }
+  async saveConfig(config) {
+    await fs3.writeFile(this.configFile, JSON.stringify(config, null, 2), "utf-8");
+  }
+  async updateConfig(updates) {
+    const current = await this.getConfig();
+    const updated = { ...current, ...updates };
+    await this.saveConfig(updated);
+    return updated;
+  }
+  // --- Knowledge ---
+  async saveKnowledge(knowledge) {
+    await fs3.mkdir(this.knowledgeDir, { recursive: true });
+    const filename = `${sanitizeFileName(knowledge.id)}.json`;
+    const filePath = path3.join(this.knowledgeDir, filename);
+    await fs3.writeFile(filePath, JSON.stringify(knowledge, null, 2), "utf-8");
+    await fs3.appendFile(this.knowledgeJsonlFile, JSON.stringify(knowledge) + "\n", "utf-8");
+  }
+  async getKnowledge(id) {
+    const filename = `${sanitizeFileName(id)}.json`;
+    const filePath = path3.join(this.knowledgeDir, filename);
+    try {
+      const raw = await fs3.readFile(filePath, "utf-8");
+      return JSON.parse(raw);
+    } catch {
+      return void 0;
+    }
+  }
+  async getAllKnowledge() {
+    try {
+      const files = await fs3.readdir(this.knowledgeDir);
+      const items = [];
+      for (const file of files) {
+        if (!file.endsWith(".json")) continue;
+        const raw = await fs3.readFile(path3.join(this.knowledgeDir, file), "utf-8");
+        try {
+          items.push(JSON.parse(raw));
+        } catch {
+        }
+      }
+      return items;
+    } catch {
+      return [];
+    }
+  }
+  async deleteKnowledge(id) {
+    const filename = `${sanitizeFileName(id)}.json`;
+    const filePath = path3.join(this.knowledgeDir, filename);
+    try {
+      await fs3.unlink(filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  // --- Evidence ---
+  async saveEvidence(evidence) {
+    await fs3.mkdir(this.evidenceDir, { recursive: true });
+    const filename = `${sanitizeFileName(evidence.id)}.json`;
+    const filePath = path3.join(this.evidenceDir, filename);
+    await fs3.writeFile(filePath, JSON.stringify(evidence, null, 2), "utf-8");
+    await fs3.appendFile(this.evidenceJsonlFile, JSON.stringify(evidence) + "\n", "utf-8");
+  }
+  async getEvidence(id) {
+    const filename = `${sanitizeFileName(id)}.json`;
+    const filePath = path3.join(this.evidenceDir, filename);
+    try {
+      const raw = await fs3.readFile(filePath, "utf-8");
+      return JSON.parse(raw);
+    } catch {
+      return void 0;
+    }
+  }
+  async getAllEvidence() {
+    try {
+      const files = await fs3.readdir(this.evidenceDir);
+      const items = [];
+      for (const file of files) {
+        if (!file.endsWith(".json")) continue;
+        const raw = await fs3.readFile(path3.join(this.evidenceDir, file), "utf-8");
+        try {
+          items.push(JSON.parse(raw));
+        } catch {
+        }
+      }
+      return items;
+    } catch {
+      return [];
+    }
+  }
+  // --- Observations ---
+  async saveObservation(obs) {
+    await fs3.mkdir(this.observationDir, { recursive: true });
+    const filename = `${sanitizeFileName(obs.id)}.json`;
+    const filePath = path3.join(this.observationDir, filename);
+    await fs3.writeFile(filePath, JSON.stringify(obs, null, 2), "utf-8");
+    await fs3.appendFile(this.observationJsonlFile, JSON.stringify(obs) + "\n", "utf-8");
+  }
+  async getObservation(id) {
+    const filename = `${sanitizeFileName(id)}.json`;
+    const filePath = path3.join(this.observationDir, filename);
+    try {
+      const raw = await fs3.readFile(filePath, "utf-8");
+      return JSON.parse(raw);
+    } catch {
+      return void 0;
+    }
+  }
+  async getAllObservations() {
+    try {
+      const files = await fs3.readdir(this.observationDir);
+      const items = [];
+      for (const file of files) {
+        if (!file.endsWith(".json")) continue;
+        const raw = await fs3.readFile(path3.join(this.observationDir, file), "utf-8");
+        try {
+          items.push(JSON.parse(raw));
+        } catch {
+        }
+      }
+      return items;
+    } catch {
+      return [];
+    }
+  }
+  async deleteObservation(id) {
+    const filename = `${sanitizeFileName(id)}.json`;
+    const filePath = path3.join(this.observationDir, filename);
+    try {
+      await fs3.unlink(filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  // --- Unknowns ---
+  async saveUnknown(record) {
+    await fs3.mkdir(this.unknownDir, { recursive: true });
+    const filename = `${sanitizeFileName(record.id)}.json`;
+    const filePath = path3.join(this.unknownDir, filename);
+    await fs3.writeFile(filePath, JSON.stringify(record, null, 2), "utf-8");
+    await fs3.appendFile(this.unknownsJsonlFile, JSON.stringify(record) + "\n", "utf-8");
+  }
+  async getUnknown(id) {
+    const filename = `${sanitizeFileName(id)}.json`;
+    const filePath = path3.join(this.unknownDir, filename);
+    try {
+      const raw = await fs3.readFile(filePath, "utf-8");
+      return JSON.parse(raw);
+    } catch {
+      return void 0;
+    }
+  }
+  async getAllUnknowns() {
+    try {
+      const files = await fs3.readdir(this.unknownDir);
+      const items = [];
+      for (const file of files) {
+        if (!file.endsWith(".json")) continue;
+        const raw = await fs3.readFile(path3.join(this.unknownDir, file), "utf-8");
+        try {
+          items.push(JSON.parse(raw));
+        } catch {
+        }
+      }
+      return items;
+    } catch {
+      return [];
+    }
+  }
+  async deleteUnknown(id) {
+    const filename = `${sanitizeFileName(id)}.json`;
+    const filePath = path3.join(this.unknownDir, filename);
+    try {
+      await fs3.unlink(filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  // --- Outcomes (Append-oriented log) ---
+  async appendOutcome(outcome) {
+    const line = JSON.stringify(outcome) + "\n";
+    await fs3.appendFile(this.outcomesFile, line, "utf-8");
+    if (outcome.knowledgeId) {
+      await this.appendMetricEvent({
+        type: "outcome",
+        knowledgeId: outcome.knowledgeId,
+        result: outcome.result,
+        timestamp: Date.now()
+      });
+      if (outcome.result === "success") {
+        await this.appendMetricEvent({
+          type: "question_resolved",
+          questionId: outcome.knowledgeId,
+          timestamp: Date.now()
+        });
+      }
+    }
+  }
+  async getAllOutcomes() {
+    try {
+      const raw = await fs3.readFile(this.outcomesFile, "utf-8");
+      const lines = raw.split("\n").filter((l) => l.trim().length > 0);
+      return lines.map((l) => JSON.parse(l));
+    } catch {
+      return [];
+    }
+  }
+  // --- Metric Events (Append-only local log) ---
+  async appendMetricEvent(event) {
+    try {
+      await fs3.mkdir(this.baseDir, { recursive: true });
+      await fs3.appendFile(this.eventsFile, JSON.stringify(event) + "\n", "utf-8");
+    } catch {
+    }
+  }
+  async getMetricEvents(filter) {
+    return readMetricEvents(path3.dirname(this.baseDir), filter);
+  }
+  async resetMetricEvents() {
+    return resetMetricEvents(path3.dirname(this.baseDir));
+  }
+  // --- Investigation Receipts ---
+  async saveReceipt(receipt) {
+    await fs3.mkdir(this.receiptsDir, { recursive: true });
+    const filename = `${sanitizeFileName(receipt.id)}.json`;
+    const filePath = path3.join(this.receiptsDir, filename);
+    await fs3.writeFile(filePath, JSON.stringify(receipt, null, 2), "utf-8");
+    await fs3.appendFile(this.receiptsJsonlFile, JSON.stringify(receipt) + "\n", "utf-8");
+  }
+  async getReceipt(id) {
+    const filename = `${sanitizeFileName(id)}.json`;
+    const filePath = path3.join(this.receiptsDir, filename);
+    try {
+      const raw = await fs3.readFile(filePath, "utf-8");
+      return JSON.parse(raw);
+    } catch {
+      return void 0;
+    }
+  }
+  async getAllReceipts() {
+    try {
+      const files = await fs3.readdir(this.receiptsDir);
+      const items = [];
+      for (const file of files) {
+        if (!file.endsWith(".json")) continue;
+        const raw = await fs3.readFile(path3.join(this.receiptsDir, file), "utf-8");
+        try {
+          items.push(JSON.parse(raw));
+        } catch {
+        }
+      }
+      return items;
+    } catch {
+      return [];
+    }
+  }
+  // --- Relations ---
+  async getRelations() {
+    try {
+      const raw = await fs3.readFile(this.relationsFile, "utf-8");
+      return JSON.parse(raw);
+    } catch {
+      return [];
+    }
+  }
+  async saveRelations(relations) {
+    await fs3.writeFile(this.relationsFile, JSON.stringify(relations, null, 2), "utf-8");
+  }
+  // --- Metrics ---
+  async getMetrics() {
+    try {
+      const raw = await fs3.readFile(this.metricsFile, "utf-8");
+      return JSON.parse(raw);
+    } catch {
+      return {
+        knowledgeHits: 0,
+        knowledgeMisses: 0,
+        knowledgeReused: 0,
+        unknownsResolved: 0,
+        repeatedInvestigationsPrevented: 0,
+        candidateKnowledgeMerged: 0,
+        staleKnowledgeDetected: 0,
+        contradictionsDetected: 0,
+        knowledgePromoted: 0,
+        knowledgeSuperseded: 0
+      };
+    }
+  }
+  async saveMetrics(metrics) {
+    await fs3.writeFile(this.metricsFile, JSON.stringify(metrics, null, 2), "utf-8");
+  }
+  // --- Rules ---
+  getRulesDir() {
+    return this.rulesDir;
+  }
+  async loadRuleSets() {
+    const files = await findRuleFiles(path3.dirname(this.baseDir), this.rulesDir);
+    const sets = [];
+    for (const f of files) {
+      try {
+        sets.push(await loadRuleSetFile(f));
+      } catch {
+      }
+    }
+    return sets;
+  }
+  async saveRuleSet(ruleSet, fileName = "default.yml") {
+    await fs3.mkdir(this.rulesDir, { recursive: true });
+    const cleanName = fileName.endsWith(".yml") || fileName.endsWith(".yaml") ? fileName : `${fileName}.yml`;
+    const targetPath = path3.join(this.rulesDir, cleanName);
+    const yaml = stringifyRuleSetYaml(ruleSet);
+    await fs3.writeFile(targetPath, yaml, "utf-8");
+    return targetPath;
+  }
+  async addRule(rule, fileName = "default.yml") {
+    await fs3.mkdir(this.rulesDir, { recursive: true });
+    const cleanName = fileName.endsWith(".yml") || fileName.endsWith(".yaml") ? fileName : `${fileName}.yml`;
+    const targetPath = path3.join(this.rulesDir, cleanName);
+    let existingSet;
+    try {
+      existingSet = await loadRuleSetFile(targetPath);
+    } catch {
+      existingSet = {
+        name: path3.basename(cleanName, path3.extname(cleanName)),
+        rules: []
+      };
+    }
+    const existingIdx = existingSet.rules.findIndex((r) => r.id === rule.id);
+    if (existingIdx >= 0) {
+      existingSet.rules[existingIdx] = rule;
+    } else {
+      existingSet.rules.push(rule);
+    }
+    const yaml = stringifyRuleSetYaml(existingSet);
+    await fs3.writeFile(targetPath, yaml, "utf-8");
+    return targetPath;
+  }
+  // --- Revisions & Incremental Learning Diff ---
+  async appendRevision(snapshot) {
+    const line = JSON.stringify(snapshot) + "\n";
+    await fs3.appendFile(this.revisionsFile, line, "utf-8");
+  }
+  async getRevisions() {
+    try {
+      const raw = await fs3.readFile(this.revisionsFile, "utf-8");
+      const lines = raw.split("\n").filter((l) => l.trim().length > 0);
+      return lines.map((l) => JSON.parse(l));
+    } catch {
+      return [];
+    }
+  }
+  async getLatestRevision() {
+    const revs = await this.getRevisions();
+    return revs.length > 0 ? revs[revs.length - 1] : void 0;
+  }
+  async getDiff(sinceRef) {
+    const revisions = await this.getRevisions();
+    let baselineSnapshot;
+    let targetSnapshot;
+    if (sinceRef && sinceRef.includes("..")) {
+      const [startRef, endRef] = sinceRef.split("..").map((s) => s.trim().toLowerCase());
+      baselineSnapshot = revisions.find(
+        (r) => r.id.toLowerCase() === startRef || r.commit?.toLowerCase() === startRef || r.commit?.toLowerCase().startsWith(startRef) || r.id.toLowerCase().startsWith(startRef)
+      );
+      targetSnapshot = revisions.find(
+        (r) => r.id.toLowerCase() === endRef || r.commit?.toLowerCase() === endRef || r.commit?.toLowerCase().startsWith(endRef) || r.id.toLowerCase().startsWith(endRef)
+      );
+    } else if (sinceRef) {
+      const cleanRef = sinceRef.trim().toLowerCase();
+      baselineSnapshot = revisions.find(
+        (r) => r.id.toLowerCase() === cleanRef || r.commit?.toLowerCase() === cleanRef || r.commit?.toLowerCase().startsWith(cleanRef) || r.id.toLowerCase().startsWith(cleanRef)
+      );
+    } else {
+      if (revisions.length >= 2) {
+        baselineSnapshot = revisions[revisions.length - 2];
+      } else if (revisions.length === 1) {
+        baselineSnapshot = revisions[0];
+      }
+    }
+    const baselineTimestamp = baselineSnapshot?.timestamp ?? "1970-01-01T00:00:00.000Z";
+    const baselineTime = new Date(baselineTimestamp).getTime();
+    const targetTime = targetSnapshot ? new Date(targetSnapshot.timestamp).getTime() : Date.now();
+    const inWindow = (time) => time >= baselineTime && time <= targetTime;
+    const allObservations = await this.getAllObservations();
+    const allKnowledge = await this.getAllKnowledge();
+    const allUnknowns = await this.getAllUnknowns();
+    let observationsAdded = 0;
+    for (const obs of allObservations) {
+      const obsTime = new Date(obs.recordedAt || obs.provenance?.timestamp || 0).getTime();
+      if (inWindow(obsTime)) {
+        observationsAdded++;
+      }
+    }
+    let candidatesAdded = 0;
+    let strengthenedCount = 0;
+    let revisedCount = 0;
+    let contradictionCount = 0;
+    let invalidatedCount = 0;
+    let needsRevalidationCount = 0;
+    const strengthened = [];
+    const revised = [];
+    const contradictions = [];
+    const invalidated = [];
+    const needsRevalidation = [];
+    for (const k of allKnowledge) {
+      const createdTime = new Date(k.createdAt).getTime();
+      const updatedTime = new Date(k.updatedAt).getTime();
+      if ((k.status === "invalid" || k.status === "invalidated") && inWindow(updatedTime)) {
+        invalidatedCount++;
+        invalidated.push(k.id);
+        continue;
+      }
+      if (k.status === "contradicted" && inWindow(updatedTime)) {
+        contradictionCount++;
+        contradictions.push(k.id);
+        continue;
+      }
+      if ((k.status === "needs_revalidation" || k.status === "stale") && inWindow(updatedTime)) {
+        needsRevalidationCount++;
+        needsRevalidation.push(k.id);
+        continue;
+      }
+      if (inWindow(createdTime)) {
+        candidatesAdded++;
+      } else if (inWindow(updatedTime)) {
+        if (k.metrics.support_count > 1 || k.confidence >= 0.85 || k.metrics.successful_outcomes > 0) {
+          strengthenedCount++;
+          strengthened.push(k.id);
+        } else {
+          revisedCount++;
+          revised.push(k.id);
+        }
+      }
+    }
+    let unknownsCount = 0;
+    const unknownsList = [];
+    for (const u of allUnknowns) {
+      const uTime = new Date(u.createdAt || u.updatedAt || 0).getTime();
+      if (inWindow(uTime)) {
+        unknownsCount++;
+        unknownsList.push(u.id);
+      }
+    }
+    const refLabel = sinceRef ?? (baselineSnapshot ? baselineSnapshot.commit?.slice(0, 7) || baselineSnapshot.id.slice(0, 7) : void 0);
+    return {
+      sinceRef: refLabel,
+      observationsAdded,
+      candidatesAdded,
+      strengthenedCount,
+      revisedCount,
+      contradictionCount,
+      unknownsCount,
+      needsRevalidationCount,
+      invalidatedCount,
+      details: {
+        strengthened,
+        revised,
+        contradictions,
+        unknowns: unknownsList,
+        needsRevalidation,
+        invalidated
+      }
+    };
+  }
+};
+function formatKnowledgeDiff(diff) {
+  const header = diff.sinceRef ? `Since ${diff.sinceRef}:` : "Recent knowledge changes:";
+  const lines = [
+    header,
+    "",
+    `+ ${diff.observationsAdded} observations`,
+    `+ ${diff.candidatesAdded} candidates`,
+    `\u2191 ${diff.strengthenedCount} knowledge strengthened`,
+    `~ ${diff.revisedCount} knowledge revised`,
+    `! ${diff.contradictionCount} contradiction${diff.contradictionCount === 1 ? "" : "s"}`,
+    `? ${diff.unknownsCount ?? 0} unknowns`,
+    `\xD7 ${diff.needsRevalidationCount ?? 0} knowledge needs revalidation`,
+    `- ${diff.invalidatedCount} invalidated`
+  ];
+  return lines.join("\n");
+}
+
+// src/storage/portable.ts
+import YAML2 from "yaml";
+
+// src/core/knowledge.ts
+import { createHash } from "crypto";
+
+// src/core/quarantine.ts
+function determineInitialStage(knowledge) {
+  if (knowledge.type === "fact" || knowledge.type === "architecture" || knowledge.confidenceTier === "high" || knowledge.confidence !== void 0 && knowledge.confidence >= 0.85) {
+    return "active";
+  }
+  if (knowledge.type === "rule" && ((knowledge.evidence?.length ?? 0) >= 2 || knowledge.confidence !== void 0 && knowledge.confidence >= 0.75)) {
+    return "probation";
+  }
+  if (knowledge.confidence !== void 0 && knowledge.confidence >= 0.7) {
+    return "probation";
+  }
+  return "candidate";
+}
+function evaluatePromotion(knowledge) {
+  const stage = knowledge.stage ?? "candidate";
+  const supportCount = knowledge.metrics.support_count;
+  const reuseCount = knowledge.metrics.reuse_count;
+  const successCount = Math.max(knowledge.outcomesSummary?.successful ?? 0, knowledge.metrics.successful_outcomes ?? 0);
+  const misleadingCount = Math.max(knowledge.outcomesSummary?.misleading ?? 0, knowledge.metrics.failed_outcomes ?? 0);
+  if (stage === "candidate") {
+    if (supportCount >= 2 || knowledge.evidence && knowledge.evidence.length >= 2 || knowledge.confidence >= 0.85) {
+      return {
+        promoted: true,
+        newStage: "probation",
+        reason: `Supported by ${supportCount} sources / ${knowledge.evidence.length} evidence nodes`
+      };
+    }
+  } else if (stage === "probation") {
+    if (successCount > 0 && misleadingCount === 0 || reuseCount >= 2 && misleadingCount === 0) {
+      return {
+        promoted: true,
+        newStage: "active",
+        reason: `Verified by ${successCount} successful task outcomes and ${reuseCount} reuses`
+      };
+    }
+  }
+  return { promoted: false, newStage: stage };
+}
+function calculateKnowledgeValue(knowledge) {
+  const reuse = knowledge.metrics.reuse_count;
+  const success = knowledge.outcomesSummary?.successful ?? knowledge.metrics.successful_outcomes;
+  const misleading = knowledge.outcomesSummary?.misleading ?? knowledge.metrics.failed_outcomes;
+  const evidenceCount = Math.min(knowledge.evidence.length, 6);
+  const confidence = knowledge.confidence;
+  let value = reuse * 2.5 + success * 4 + evidenceCount * 1.5 + confidence * 2 - misleading * 5;
+  if (knowledge.status === "active") value += 5;
+  if (knowledge.status === "needs_revalidation") value -= 3;
+  if (knowledge.status === "contradicted") value -= 8;
+  if (knowledge.status === "stale") value -= 4;
+  if (knowledge.stage === "active") value += 3;
+  if (knowledge.stage === "candidate") value -= 1;
+  return Math.round(value * 10) / 10;
+}
+
+// src/core/knowledge.ts
+function tierToConfidence(tier) {
+  switch (tier) {
+    case "low":
+      return 0.5;
+    case "medium":
+      return 0.75;
+    case "high":
+      return 0.95;
+  }
+}
+function confidenceToTier(score) {
+  if (score >= 0.85) return "high";
+  if (score >= 0.65) return "medium";
+  return "low";
+}
+function hashString(input) {
+  return createHash("sha256").update(input.trim().toLowerCase()).digest("hex").slice(0, 16);
+}
+function createKnowledge(params) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const confidenceTier = params.confidenceTier ?? (params.confidence !== void 0 ? confidenceToTier(params.confidence) : void 0);
+  const confidence = params.confidence !== void 0 ? params.confidence : confidenceTier ? tierToConfidence(confidenceTier) : 0.85;
+  const dependsOn = new Set(params.depends_on ?? []);
+  if (params.evidence) {
+    for (const ev of params.evidence) {
+      if (ev.startsWith("file:") || ev.startsWith("test:") || ev.startsWith("code:")) {
+        dependsOn.add(ev);
+      } else if (ev.includes("/") || ev.endsWith(".json") || ev.endsWith(".yaml") || ev.endsWith(".yml")) {
+        dependsOn.add(`file:${ev}`);
+      }
+    }
+  }
+  const initialStage = params.stage ?? determineInitialStage({
+    type: params.type ?? "lesson",
+    evidence: params.evidence ?? [],
+    confidence
+  });
+  const status = params.status ?? (initialStage === "candidate" ? "candidate" : "active");
+  const history = params.history ?? [
+    {
+      timestamp: now,
+      stage: initialStage,
+      status,
+      reason: `Initial knowledge recorded (${params.type ?? "lesson"})`,
+      source: params.evidence?.[0]
+    }
+  ];
+  const knowledgeItem = {
+    id: params.id.trim(),
+    type: params.type ?? "lesson",
+    status,
+    stage: initialStage,
+    statement: params.statement.trim(),
+    positive: Array.from(new Set(params.positive?.map((p) => p.trim().toLowerCase()) ?? [])),
+    negative: Array.from(new Set(params.negative?.map((n) => n.trim().toLowerCase()) ?? [])),
+    relations: Array.from(new Set(params.relations?.map((r) => r.trim()) ?? [])),
+    depends_on: Array.from(dependsOn),
+    resolves: params.resolves ? Array.from(new Set(params.resolves.map((r) => r.trim()))) : void 0,
+    question: params.question?.trim(),
+    confidence: Math.min(1, Math.max(0, confidence)),
+    confidenceTier,
+    evidence: Array.from(new Set(params.evidence ?? [])),
+    scope: params.scope ?? "project",
+    tags: Array.from(new Set(params.tags?.map((t) => t.trim().toLowerCase()) ?? [])),
+    temporal: {
+      revision: 1
+    },
+    metrics: {
+      reuse_count: 0,
+      support_count: 1,
+      contradiction_count: 0,
+      successful_outcomes: 0,
+      failed_outcomes: 0
+    },
+    outcomesSummary: params.outcomesSummary ?? {
+      applied: 0,
+      successful: 0,
+      misleading: 0,
+      neutral: 0
+    },
+    history,
+    value: 0,
+    createdAt: now,
+    updatedAt: now
+  };
+  knowledgeItem.value = calculateKnowledgeValue(knowledgeItem);
+  return knowledgeItem;
+}
+function calculateEffectiveConfidence(knowledge) {
+  const m = knowledge.metrics;
+  const base = knowledge.confidence;
+  const evRatio = (m.support_count + 1) / (m.support_count + 3 * m.contradiction_count + 1);
+  const totalOutcomes = m.successful_outcomes + m.failed_outcomes;
+  let outRatio = 1;
+  let evWeight = 0.6;
+  let outWeight = 0.4;
+  if (totalOutcomes === 0) {
+    evWeight = 0.85;
+    outWeight = 0.15;
+  } else {
+    outRatio = (m.successful_outcomes + 1) / (totalOutcomes + 1);
+  }
+  const effective = base * (evWeight * evRatio + outWeight * outRatio);
+  return Math.round(Math.min(1, Math.max(0.05, effective)) * 100) / 100;
+}
+var knowledgeTokenCache = /* @__PURE__ */ new WeakMap();
+function tokenize(text) {
+  return new Set(
+    text.toLowerCase().replace(/[^a-z0-9_-]/g, " ").split(/\s+/).filter((t) => t.length > 2)
+  );
+}
+function getCachedTokens(k) {
+  let tokens = knowledgeTokenCache.get(k);
+  if (!tokens) {
+    tokens = tokenize(k.statement);
+    knowledgeTokenCache.set(k, tokens);
+  }
+  return tokens;
+}
+function jaccardSimilarity(setA, setB) {
+  if (setA.size === 0 && setB.size === 0) return 1;
+  let intersection = 0;
+  for (const item of setA) {
+    if (setB.has(item)) intersection++;
+  }
+  const union = setA.size + setB.size - intersection;
+  return union === 0 ? 0 : intersection / union;
+}
+var POLAR_ANTONYMS = [
+  ["enabled", "disabled"],
+  ["enable", "disable"],
+  ["active", "inactive"],
+  ["true", "false"],
+  ["on", "off"],
+  ["yes", "no"],
+  ["allowed", "disallowed"],
+  ["allowed", "prohibited"],
+  ["allowed", "forbidden"],
+  ["permit", "deny"],
+  ["allow", "forbid"],
+  ["allow", "prohibit"],
+  ["always", "never"],
+  ["should", "should not"],
+  ["must", "must not"],
+  ["required", "optional"],
+  ["required", "forbidden"],
+  ["valid", "invalid"],
+  ["safe", "unsafe"],
+  ["sync", "async"],
+  ["synchronous", "asynchronous"],
+  ["public", "private"]
+];
+var NEGATION_PATTERNS = [
+  /\bnot\b/i,
+  /\bnever\b/i,
+  /\bno\b/i,
+  /\bcannot\b/i,
+  /\bwithout\b/i,
+  /\bdisallow\b/i,
+  /\bforbid\b/i,
+  /\bprohibit\b/i,
+  /\bavoid\b/i
+];
+function detectPolarContradiction(stmtA, stmtB) {
+  const lowerA = stmtA.toLowerCase();
+  const lowerB = stmtB.toLowerCase();
+  for (const [pos, neg] of POLAR_ANTONYMS) {
+    const aHasPos = new RegExp(`\\b${pos}\\b`, "i").test(lowerA);
+    const aHasNeg = new RegExp(`\\b${neg}\\b`, "i").test(lowerA);
+    const bHasPos = new RegExp(`\\b${pos}\\b`, "i").test(lowerB);
+    const bHasNeg = new RegExp(`\\b${neg}\\b`, "i").test(lowerB);
+    if (aHasPos && bHasNeg || aHasNeg && bHasPos) {
+      return {
+        contradicted: true,
+        reason: `Polar opposite terms detected: '${pos}' vs '${neg}'`
+      };
+    }
+  }
+  const aHasNegation = NEGATION_PATTERNS.some((p) => p.test(lowerA));
+  const bHasNegation = NEGATION_PATTERNS.some((p) => p.test(lowerB));
+  if (aHasNegation !== bHasNegation) {
+    return {
+      contradicted: true,
+      reason: "Asymmetric negation detected (one statement asserts, the other negates)"
+    };
+  }
+  return { contradicted: false };
+}
+function reconcileKnowledge(candidate, existingList) {
+  const candidateId = candidate.id?.trim();
+  const candidateStmt = candidate.statement.trim();
+  const candidateTokens = tokenize(candidateStmt);
+  const candidatePos = new Set((candidate.positive ?? []).map((p) => p.trim().toLowerCase()));
+  if (candidateId) {
+    const directMatch = existingList.find((k) => k.id === candidateId);
+    if (directMatch) {
+      if (directMatch.statement.trim().toLowerCase() === candidateStmt.toLowerCase()) {
+        const hasNewEvidence = (candidate.evidence ?? []).some((e) => !directMatch.evidence.includes(e));
+        if (!hasNewEvidence) {
+          return {
+            action: "IGNORE",
+            targetId: directMatch.id,
+            knowledge: directMatch,
+            reason: "Identical statement and evidence already recorded"
+          };
+        }
+        return {
+          action: "SUPPORT",
+          targetId: directMatch.id,
+          knowledge: directMatch,
+          reason: "Confirms existing knowledge with new evidence source"
+        };
+      }
+      const opposingPositive = (candidate.negative ?? []).some((n) => directMatch.positive.includes(n));
+      const opposingNegative = (candidate.positive ?? []).some((p) => directMatch.negative.includes(p));
+      const polarCheck = detectPolarContradiction(candidateStmt, directMatch.statement);
+      if (opposingPositive || opposingNegative || polarCheck.contradicted) {
+        const distinctCues = Array.from(candidatePos).filter((c) => !directMatch.positive.includes(c));
+        const mentionsEnvA = /(development|dev|local|staging|test)/i.test(candidateStmt);
+        const mentionsEnvB = /(production|prod)/i.test(directMatch.statement);
+        const mentionsEnvBDev = /(development|dev|local|staging|test)/i.test(directMatch.statement);
+        const mentionsEnvAProd = /(production|prod)/i.test(candidateStmt);
+        if (distinctCues.length > 0 || mentionsEnvA && mentionsEnvB || mentionsEnvBDev && mentionsEnvAProd) {
+          return {
+            action: "SPECIALIZE",
+            targetId: directMatch.id,
+            knowledge: directMatch,
+            reason: `Conflicting claim applies under specialized context cues: [${distinctCues.join(", ")}] (${polarCheck.reason || "opposing polarity"})`
+          };
+        }
+        return {
+          action: "CONTRADICT",
+          targetId: directMatch.id,
+          knowledge: directMatch,
+          reason: `Contradicts existing statement (${polarCheck.reason || "opposing polarity"}) for ID "${directMatch.id}"`
+        };
+      }
+      return {
+        action: "UPDATE",
+        targetId: directMatch.id,
+        knowledge: directMatch,
+        reason: "Refines or updates existing knowledge statement"
+      };
+    }
+  }
+  let bestMatch = null;
+  let bestSim = 0;
+  let bestPolarCheck = { contradicted: false };
+  for (const existing of existingList) {
+    const existingTokens = getCachedTokens(existing);
+    const sim = jaccardSimilarity(candidateTokens, existingTokens);
+    const polarCheck = detectPolarContradiction(candidateStmt, existing.statement);
+    if (polarCheck.contradicted) {
+      let sharedCount = 0;
+      for (const t of candidateTokens) {
+        if (existingTokens.has(t)) sharedCount++;
+      }
+      const sharedCues = (candidate.positive ?? []).filter((p) => existing.positive.includes(p));
+      if (sharedCount >= 2 || sharedCues.length >= 1 && sim >= 0.35 || sim >= 0.4) {
+        bestMatch = existing;
+        bestSim = Math.max(sim, 0.85);
+        bestPolarCheck = polarCheck;
+        break;
+      }
+    }
+    if (sim > bestSim) {
+      bestSim = sim;
+      bestMatch = existing;
+      bestPolarCheck = polarCheck;
+    }
+  }
+  if (bestMatch && bestSim >= 0.7) {
+    const polarCheck = bestPolarCheck.contradicted ? bestPolarCheck : detectPolarContradiction(candidateStmt, bestMatch.statement);
+    const hasOpposingCues = (candidate.negative ?? []).some((n) => bestMatch.positive.includes(n)) || (candidate.positive ?? []).some((p) => bestMatch.negative.includes(p));
+    if (polarCheck.contradicted || hasOpposingCues) {
+      const distinctCues = Array.from(candidatePos).filter((c) => !bestMatch.positive.includes(c));
+      const mentionsEnvA = /(development|dev|local|staging|test)/i.test(candidateStmt);
+      const mentionsEnvB = /(production|prod)/i.test(bestMatch.statement);
+      const mentionsEnvBDev = /(development|dev|local|staging|test)/i.test(bestMatch.statement);
+      const mentionsEnvAProd = /(production|prod)/i.test(candidateStmt);
+      if (distinctCues.length > 0 || mentionsEnvA && mentionsEnvB || mentionsEnvBDev && mentionsEnvAProd) {
+        return {
+          action: "SPECIALIZE",
+          targetId: bestMatch.id,
+          knowledge: bestMatch,
+          reason: `High textual similarity (${Math.round(bestSim * 100)}%) with polar distinction across contexts (${polarCheck.reason || "opposing cues"})`,
+          score: bestSim
+        };
+      }
+      return {
+        action: "CONTRADICT",
+        targetId: bestMatch.id,
+        knowledge: bestMatch,
+        reason: `Contradicting statement (${polarCheck.reason || "opposing cues"}) despite high textual similarity (${Math.round(bestSim * 100)}%)`,
+        score: bestSim
+      };
+    }
+    if (bestSim >= 0.9) {
+      return {
+        action: "MERGE",
+        targetId: bestMatch.id,
+        knowledge: bestMatch,
+        reason: `Nearly identical statement (${Math.round(bestSim * 100)}% match) with compatible polarity; merging cues and evidence`,
+        score: bestSim
+      };
+    }
+    return {
+      action: "SUPPORT",
+      targetId: bestMatch.id,
+      knowledge: bestMatch,
+      reason: `Supports existing knowledge (${Math.round(bestSim * 100)}% similarity) with compatible polarity`,
+      score: bestSim
+    };
+  }
+  return {
+    action: "NEW",
+    reason: "No conflicting or matching knowledge found; creating new knowledge entry"
+  };
+}
+function applyReconciliation(reconciliation, candidate, existingList, storage) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  switch (reconciliation.action) {
+    case "SUPPORT": {
+      const target = existingList.find((k) => k.id === reconciliation.targetId);
+      target.metrics.support_count++;
+      target.metrics.last_used = now;
+      storage?.appendMetricEvent({
+        type: "knowledge_strengthened",
+        knowledgeId: target.id,
+        timestamp: Date.now()
+      });
+      if (candidate.evidence) {
+        for (const e of candidate.evidence) {
+          if (!target.evidence.includes(e)) {
+            target.evidence.push(e);
+          }
+        }
+      }
+      if (candidate.positive) {
+        for (const p of candidate.positive) {
+          const lp = p.trim().toLowerCase();
+          if (!target.positive.includes(lp)) target.positive.push(lp);
+        }
+      }
+      if (!target.history) {
+        target.history = [
+          {
+            timestamp: target.createdAt || now,
+            stage: target.stage,
+            status: target.status,
+            reason: "Initial knowledge recorded",
+            source: target.evidence?.[0]
+          }
+        ];
+      }
+      const promotion = evaluatePromotion(target);
+      if (promotion.promoted && promotion.newStage) {
+        target.stage = promotion.newStage;
+        if (target.stage === "active" && target.status === "candidate") {
+          target.status = "active";
+        }
+        target.history.push({
+          timestamp: now,
+          stage: target.stage,
+          status: target.status,
+          reason: promotion.reason || `Promoted to ${target.stage}`,
+          source: candidate.evidence?.[0]
+        });
+      } else {
+        target.history.push({
+          timestamp: now,
+          stage: target.stage,
+          status: target.status,
+          reason: reconciliation.reason || "Confirmed with supporting evidence",
+          source: candidate.evidence?.[0]
+        });
+      }
+      target.confidence = calculateEffectiveConfidence(target);
+      target.value = calculateKnowledgeValue(target);
+      target.updatedAt = now;
+      return { updatedKnowledge: target, action: "SUPPORT", createdId: target.id };
+    }
+    case "MERGE": {
+      const target = existingList.find((k) => k.id === reconciliation.targetId);
+      target.metrics.support_count++;
+      target.metrics.last_used = now;
+      storage?.appendMetricEvent({
+        type: "knowledge_merged",
+        knowledgeId: target.id,
+        targetId: reconciliation.targetId,
+        timestamp: Date.now()
+      });
+      if (candidate.evidence) {
+        for (const e of candidate.evidence) {
+          if (!target.evidence.includes(e)) target.evidence.push(e);
+        }
+      }
+      if (candidate.positive) {
+        for (const p of candidate.positive) {
+          const lp = p.trim().toLowerCase();
+          if (!target.positive.includes(lp)) target.positive.push(lp);
+        }
+      }
+      if (candidate.negative) {
+        for (const n of candidate.negative) {
+          const ln = n.trim().toLowerCase();
+          if (!target.negative.includes(ln)) target.negative.push(ln);
+        }
+      }
+      if (!target.history) {
+        target.history = [
+          {
+            timestamp: target.createdAt || now,
+            stage: target.stage,
+            status: target.status,
+            reason: "Initial knowledge recorded",
+            source: target.evidence?.[0]
+          }
+        ];
+      }
+      const promotion = evaluatePromotion(target);
+      if (promotion.promoted && promotion.newStage) {
+        target.stage = promotion.newStage;
+        if (target.stage === "active" && target.status === "candidate") {
+          target.status = "active";
+        }
+        target.history.push({
+          timestamp: now,
+          stage: target.stage,
+          status: target.status,
+          reason: promotion.reason || `Promoted to ${target.stage}`,
+          source: candidate.evidence?.[0]
+        });
+      } else {
+        target.history.push({
+          timestamp: now,
+          stage: target.stage,
+          status: target.status,
+          reason: reconciliation.reason || "Merged with compatible knowledge candidate",
+          source: candidate.evidence?.[0]
+        });
+      }
+      target.confidence = calculateEffectiveConfidence(target);
+      target.value = calculateKnowledgeValue(target);
+      target.updatedAt = now;
+      return { updatedKnowledge: target, action: "MERGE", createdId: target.id };
+    }
+    case "UPDATE": {
+      const target = existingList.find((k) => k.id === reconciliation.targetId);
+      target.statement = candidate.statement;
+      if (candidate.type) target.type = candidate.type;
+      if (candidate.positive) {
+        target.positive = Array.from(/* @__PURE__ */ new Set([...target.positive, ...candidate.positive.map((p) => p.toLowerCase())]));
+      }
+      if (candidate.negative) {
+        target.negative = Array.from(/* @__PURE__ */ new Set([...target.negative, ...candidate.negative.map((n) => n.toLowerCase())]));
+      }
+      if (candidate.evidence) {
+        target.evidence = Array.from(/* @__PURE__ */ new Set([...target.evidence, ...candidate.evidence]));
+      }
+      target.temporal = {
+        revision: (target.temporal?.revision ?? 1) + 1,
+        valid_from: { timestamp: now }
+      };
+      if (!target.history) {
+        target.history = [
+          {
+            timestamp: target.createdAt || now,
+            stage: target.stage,
+            status: target.status,
+            reason: "Initial knowledge recorded",
+            source: target.evidence?.[0]
+          }
+        ];
+      }
+      target.history.push({
+        timestamp: now,
+        stage: target.stage,
+        status: target.status,
+        reason: reconciliation.reason || "Updated statement and context",
+        source: candidate.evidence?.[0]
+      });
+      target.updatedAt = now;
+      target.confidence = calculateEffectiveConfidence(target);
+      target.value = calculateKnowledgeValue(target);
+      storage?.appendMetricEvent({
+        type: "knowledge_strengthened",
+        knowledgeId: target.id,
+        timestamp: Date.now()
+      });
+      return { updatedKnowledge: target, action: "UPDATE", createdId: target.id };
+    }
+    case "CONTRADICT": {
+      const target = existingList.find((k) => k.id === reconciliation.targetId);
+      target.metrics.contradiction_count++;
+      if (candidate.evidence) {
+        for (const e of candidate.evidence) {
+          if (!target.evidence.includes(e)) target.evidence.push(e);
+        }
+      }
+      if (target.metrics.contradiction_count > target.metrics.support_count) {
+        target.status = "contradicted";
+      }
+      if (!target.history) {
+        target.history = [
+          {
+            timestamp: target.createdAt || now,
+            stage: target.stage,
+            status: target.status,
+            reason: "Initial knowledge recorded",
+            source: target.evidence?.[0]
+          }
+        ];
+      }
+      target.history.push({
+        timestamp: now,
+        stage: target.stage,
+        status: target.status,
+        reason: reconciliation.reason || "Contradicted by opposing claim",
+        source: candidate.evidence?.[0]
+      });
+      target.confidence = calculateEffectiveConfidence(target);
+      target.value = calculateKnowledgeValue(target);
+      target.updatedAt = now;
+      storage?.appendMetricEvent({
+        type: "contradiction_detected",
+        knowledgeId: target.id,
+        timestamp: Date.now()
+      });
+      return { updatedKnowledge: target, action: "CONTRADICT", createdId: target.id };
+    }
+    case "SPECIALIZE": {
+      const parent = existingList.find((k) => k.id === reconciliation.targetId);
+      const subContext = candidate.positive?.[0] || "specialized";
+      const newId = candidate.id && candidate.id !== parent?.id ? candidate.id : `${parent ? parent.id : "knowledge"}.${subContext}`;
+      const created = createKnowledge({
+        id: newId,
+        type: candidate.type ?? parent?.type ?? "lesson",
+        statement: candidate.statement,
+        positive: candidate.positive ?? [],
+        negative: candidate.negative ?? [],
+        relations: parent ? [parent.id, ...candidate.relations ?? []] : candidate.relations ?? [],
+        confidence: candidate.confidence ?? 0.85,
+        evidence: candidate.evidence ?? [],
+        scope: candidate.scope ?? parent?.scope ?? "project",
+        tags: candidate.tags ?? parent?.tags ?? []
+      });
+      if (parent) {
+        if (!parent.relations.includes(newId)) {
+          parent.relations.push(newId);
+        }
+        if (!parent.history) {
+          parent.history = [
+            {
+              timestamp: parent.createdAt || now,
+              stage: parent.stage,
+              status: parent.status,
+              reason: "Initial knowledge recorded"
+            }
+          ];
+        }
+        parent.history.push({
+          timestamp: now,
+          stage: parent.stage,
+          status: parent.status,
+          reason: `Specialized into contextual branch ${newId}`
+        });
+      }
+      storage?.appendMetricEvent({
+        type: "knowledge_specialized",
+        knowledgeId: created.id,
+        timestamp: Date.now()
+      });
+      return { updatedKnowledge: created, action: "SPECIALIZE", createdId: created.id };
+    }
+    case "IGNORE": {
+      const target = existingList.find((k) => k.id === reconciliation.targetId);
+      storage?.appendMetricEvent({
+        type: "duplicate_ignored",
+        timestamp: Date.now()
+      });
+      return { updatedKnowledge: target, action: "IGNORE", createdId: target.id };
+    }
+    case "NEW":
+    default: {
+      const newId = candidate.id || `kn_${hashString(candidate.statement)}`;
+      const created = createKnowledge({
+        id: newId,
+        type: candidate.type,
+        statement: candidate.statement,
+        positive: candidate.positive,
+        negative: candidate.negative,
+        relations: candidate.relations,
+        confidence: candidate.confidence,
+        evidence: candidate.evidence,
+        scope: candidate.scope,
+        tags: candidate.tags
+      });
+      storage?.appendMetricEvent({
+        type: "knowledge_created",
+        knowledgeId: created.id,
+        timestamp: Date.now()
+      });
+      return { updatedKnowledge: created, action: "NEW", createdId: created.id };
+    }
+  }
+}
+
+// src/storage/portable.ts
+function exportKnowledgeToYaml(items, options = {}) {
+  let filtered = items;
+  if (options.scope) {
+    const s = options.scope.toLowerCase();
+    filtered = items.filter((k) => k.scope.toLowerCase() === s);
+  }
+  const payload = {
+    schemaVersion: 1,
+    exportedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    count: filtered.length,
+    knowledge: filtered.map((k) => ({
+      id: k.id,
+      type: k.type,
+      status: k.status,
+      statement: k.statement,
+      positive: k.positive,
+      negative: k.negative,
+      relations: k.relations.length > 0 ? k.relations : void 0,
+      confidence: k.confidence,
+      evidence: k.evidence.length > 0 ? k.evidence : void 0,
+      scope: k.scope,
+      tags: k.tags && k.tags.length > 0 ? k.tags : void 0,
+      temporal: k.temporal,
+      metrics: {
+        reuse_count: k.metrics.reuse_count,
+        support_count: k.metrics.support_count,
+        contradiction_count: k.metrics.contradiction_count
+      }
+    }))
+  };
+  return YAML2.stringify(payload, { indent: 2, lineWidth: 100 });
+}
+async function importKnowledgeFromYaml(yamlContent, storage) {
+  const parsed = YAML2.parse(yamlContent);
+  if (!parsed || typeof parsed !== "object") {
+    throw new Error("Invalid YAML: root must be an object");
+  }
+  let candidates = [];
+  if (Array.isArray(parsed)) {
+    candidates = parsed;
+  } else if (Array.isArray(parsed.knowledge)) {
+    candidates = parsed.knowledge;
+  } else if (parsed.id && parsed.statement) {
+    candidates = [parsed];
+  } else {
+    throw new Error("Invalid knowledge YAML format: no knowledge entries found");
+  }
+  const existing = await storage.getAllKnowledge();
+  const results = [];
+  const created = [];
+  const updated = [];
+  for (const raw of candidates) {
+    if (!raw.statement || typeof raw.statement !== "string") {
+      continue;
+    }
+    const rec = reconcileKnowledge(raw, existing);
+    results.push(rec);
+    const { updatedKnowledge, action } = applyReconciliation(rec, raw, existing, storage);
+    await storage.saveKnowledge(updatedKnowledge);
+    if (action === "NEW" || action === "SPECIALIZE") {
+      created.push(updatedKnowledge);
+      existing.push(updatedKnowledge);
+    } else if (action !== "IGNORE") {
+      updated.push(updatedKnowledge);
+    }
+  }
+  return {
+    totalParsed: candidates.length,
+    results,
+    created,
+    updated
+  };
+}
+async function dumpToYaml(storage) {
+  const config = await storage.getConfig();
+  const knowledge = await storage.getAllKnowledge();
+  const unknowns = await storage.getAllUnknowns();
+  const evidence = await storage.getAllEvidence();
+  const observations = await storage.getAllObservations();
+  const relations = await storage.getRelations();
+  const metrics = await storage.getMetrics();
+  const dump = {
+    schemaVersion: 1,
+    exportedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    config,
+    knowledge,
+    unknowns,
+    evidence,
+    observations,
+    relations,
+    metrics
+  };
+  return YAML2.stringify(dump, { indent: 2, lineWidth: 120 });
+}
+async function restoreFromYaml(yamlContent, storage) {
+  const parsed = YAML2.parse(yamlContent);
+  if (!parsed || parsed.schemaVersion !== 1) {
+    throw new Error(`Unsupported snapshot schema version: ${parsed?.schemaVersion}`);
+  }
+  if (parsed.config) {
+    await storage.saveConfig(parsed.config);
+  }
+  let kCount = 0;
+  if (Array.isArray(parsed.knowledge)) {
+    for (const k of parsed.knowledge) {
+      await storage.saveKnowledge(k);
+      kCount++;
+    }
+  }
+  let uCount = 0;
+  if (Array.isArray(parsed.unknowns)) {
+    for (const u of parsed.unknowns) {
+      await storage.saveUnknown(u);
+      uCount++;
+    }
+  }
+  if (Array.isArray(parsed.evidence)) {
+    for (const e of parsed.evidence) {
+      await storage.saveEvidence(e);
+    }
+  }
+  if (Array.isArray(parsed.observations)) {
+    for (const o of parsed.observations) {
+      await storage.saveObservation(o);
+    }
+  }
+  if (Array.isArray(parsed.relations)) {
+    await storage.saveRelations(parsed.relations);
+  }
+  if (parsed.metrics) {
+    await storage.saveMetrics(parsed.metrics);
+  }
+  return {
+    restoredKnowledgeCount: kCount,
+    restoredUnknownsCount: uCount
+  };
+}
+
+// src/storage/compaction.ts
+function tokenize2(text) {
+  return new Set(
+    text.toLowerCase().replace(/[^a-z0-9_-]/g, " ").split(/\s+/).filter((t) => t.length > 2)
+  );
+}
+function jaccard(a, b) {
+  if (a.size === 0 && b.size === 0) return 1;
+  let inter = 0;
+  for (const item of a) {
+    if (b.has(item)) inter++;
+  }
+  const union = a.size + b.size - inter;
+  return union === 0 ? 0 : inter / union;
+}
+async function compact(storage, options = {}) {
+  const dryRun = options.dryRun ?? false;
+  const report = {
+    dryRun,
+    mergedDuplicatesCount: 0,
+    markedStaleCount: 0,
+    markedContradictedCount: 0,
+    prunedObservationsCount: 0,
+    details: []
+  };
+  const allKnowledge = await storage.getAllKnowledge();
+  const allEvidence = await storage.getAllEvidence();
+  const allObservations = await storage.getAllObservations();
+  const activeReferencedEvidence = /* @__PURE__ */ new Set();
+  for (const k of allKnowledge) {
+    for (const e of k.evidence) {
+      activeReferencedEvidence.add(e);
+    }
+  }
+  const activeReferencedObservations = /* @__PURE__ */ new Set();
+  for (const ev of allEvidence) {
+    for (const oId of ev.observationIds) {
+      activeReferencedObservations.add(oId);
+    }
+  }
+  const processed = /* @__PURE__ */ new Set();
+  const toDelete = /* @__PURE__ */ new Set();
+  for (let i = 0; i < allKnowledge.length; i++) {
+    const primary = allKnowledge[i];
+    if (processed.has(primary.id) || toDelete.has(primary.id)) continue;
+    processed.add(primary.id);
+    const primaryTokens = tokenize2(primary.statement);
+    for (let j = i + 1; j < allKnowledge.length; j++) {
+      const secondary = allKnowledge[j];
+      if (processed.has(secondary.id) || toDelete.has(secondary.id)) continue;
+      if (primary.scope !== secondary.scope) continue;
+      const polarCheck = detectPolarContradiction(primary.statement, secondary.statement);
+      if (polarCheck.contradicted) {
+        primary.metrics.contradiction_count++;
+        secondary.metrics.contradiction_count++;
+        report.markedContradictedCount++;
+        report.details.push(
+          `Detected contradiction: "${secondary.id}" vs "${primary.id}" (${polarCheck.reason}). Skipping merge.`
+        );
+        continue;
+      }
+      const secondaryTokens = tokenize2(secondary.statement);
+      const sim = jaccard(primaryTokens, secondaryTokens);
+      if (sim >= 0.85) {
+        report.mergedDuplicatesCount++;
+        report.details.push(`Merged duplicate: "${secondary.id}" into "${primary.id}" (${Math.round(sim * 100)}% match)`);
+        primary.metrics.support_count += secondary.metrics.support_count;
+        primary.metrics.reuse_count += secondary.metrics.reuse_count;
+        primary.metrics.successful_outcomes += secondary.metrics.successful_outcomes;
+        primary.metrics.failed_outcomes += secondary.metrics.failed_outcomes;
+        for (const e of secondary.evidence) {
+          if (!primary.evidence.includes(e)) primary.evidence.push(e);
+        }
+        for (const p of secondary.positive) {
+          if (!primary.positive.includes(p)) primary.positive.push(p);
+        }
+        for (const n of secondary.negative) {
+          if (!primary.negative.includes(n)) primary.negative.push(n);
+        }
+        primary.confidence = calculateEffectiveConfidence(primary);
+        toDelete.add(secondary.id);
+      }
+    }
+    if (primary.metrics.contradiction_count > 2 * primary.metrics.support_count && primary.status === "active") {
+      primary.status = "contradicted";
+      report.markedContradictedCount++;
+      report.details.push(`Marked "${primary.id}" as contradicted (${primary.metrics.contradiction_count} vs ${primary.metrics.support_count})`);
+    }
+    if (!dryRun) {
+      await storage.saveKnowledge(primary);
+    }
+  }
+  if (!dryRun) {
+    for (const delId of toDelete) {
+      await storage.deleteKnowledge(delId);
+    }
+  }
+  const now = Date.now();
+  const FOURTEEN_DAYS_MS = 14 * 24 * 60 * 60 * 1e3;
+  for (const obs of allObservations) {
+    const isReferenced = activeReferencedObservations.has(obs.id) || activeReferencedEvidence.has(obs.id) || activeReferencedEvidence.has(obs.source);
+    if (!isReferenced) {
+      const age = now - new Date(obs.recordedAt).getTime();
+      if (age > FOURTEEN_DAYS_MS) {
+        report.prunedObservationsCount++;
+        report.details.push(`Pruned unreferenced stale observation: "${obs.id}"`);
+        if (!dryRun) {
+          await storage.deleteObservation(obs.id);
+        }
+      }
+    }
+  }
+  return report;
+}
+export {
+  Storage as CanonicalStorage,
+  Storage,
+  compact,
+  desanitizeFileName,
+  dumpToYaml,
+  exportKnowledgeToYaml,
+  formatKnowledgeDiff,
+  importKnowledgeFromYaml,
+  restoreFromYaml,
+  sanitizeFileName
+};
+//# sourceMappingURL=index.js.map