claude-faf-mcp 5.7.1 → 5.7.2

package/CHANGELOG.md

@@ -1,5 +1,5 @@
 <!-- faf: claude-faf-mcp | TypeScript | mcp-server | FAF MCP server for Claude Desktop — persistent project context, 32 tools -->
-<!-- faf: doc=changelog | latest=v5.7.1 | canonical=project.faf | family=FAF -->
+<!-- faf: doc=changelog | latest=v5.7.2 | canonical=project.faf | family=FAF -->
 
 # Changelog
 
@@ -9,6 +9,19 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [Unreleased]
+
+**Interop now enhances your files.** The same solid, structured `.faf` data is prefixed to the top of your context files for rapid AI consumption upfront — and your Markdown stays in the instruction lane.
+
+### Changed
+
+- **Non-destructive interop.** `faf_agents`, `faf_gemini`, `faf_cursor`, and `faf_sync` now inject a structured `.faf` block at the top of AGENTS.md, GEMINI.md, .cursorrules, and CLAUDE.md and preserve everything you've written below. Re-runs update the block in place (idempotent); existing faf-generated files upgrade cleanly in one pass.
+
+## [5.7.2] - 2026-06-11 — The Canonical Edition
+
+### Security
+- **Path confinement on every caller-supplied `path` argument (CWE-22 / CWE-73 / CWE-200).** The shared `getProjectPath()` chokepoint (feeding the `.faf` tools) and the `faf_read` / `faf_write` file tools resolved a caller path straight into a filesystem read/write with no confinement — so an absolute path or `../` traversal could read any file the server process could read (e.g. `/etc/passwd`, `~/.ssh/id_rsa`) or write outside the project. New `safe-path.ts` confines reads to `.faf` / `.fafm` context files and general file ops to the project root (cwd + system temp; override with `FAF_ALLOWED_ROOTS`), canonicalizes through symlinks (closing the symlink bypass), and rejects traversal/absolute escapes; `callTool()` gains a central PATH-DENIED guard. Identified by the maintainers during a sibling-server audit prompted by the coordinated disclosure of the same class of issue in `grok-faf-mcp` by Zhihao Zhang (Worcester Polytechnic Institute). Adds a security regression suite (incl. symlink bypass).
+
 ## [5.7.1] - 2026-06-10 — The Canonical Edition
 
 Typed structured output and one-click registry install — the reliability layer made machine-readable.

package/README.md

@@ -26,7 +26,7 @@
 
 > ⚡ **New: `/faf` prompt** — type `/faf` in Claude Desktop. It checks your project, scores it, drives it to 100%, and syncs. Relentlessly. One command.
 
-> 🏆 **v5.7.1 — The Canonical Edition.** Typed structured output — `faf_score` and `faf_status` now return MCP `structuredContent` with output schemas alongside the text — plus one-click install straight from the MCP registry. Built on 5.7.0's canonical foundation: edge-direct remote, 32 must-have tools.
+> 🏆 **v5.7.2 — The Canonical Edition.** Security patch — caller-supplied `path` arguments are now confined: reads are restricted to `.faf` / `.fafm` context files and file ops to the project root (override with `FAF_ALLOWED_ROOTS`), closing an arbitrary local file read. Built on the Canonical foundation: typed structured output (`structuredContent` + output schemas), edge-direct remote, 32 must-have tools.
 
 32 MCP tools. IANA-registered formats (`application/vnd.faf+yaml` · `application/vnd.fafm+yaml`). 2,538 test executions per push.
 
@@ -82,7 +82,7 @@ Same `.faf`, every surface — Claude, Gemini, Grok, Cursor. **[faf-cli on npm
 
 **Click** — one-click `.mcpb`
 
-[**⬇ Download `claude-faf-mcp-5.7.1.mcpb`**](https://github.com/Wolfe-Jam/claude-faf-mcp/releases/latest/download/claude-faf-mcp-5.7.1.mcpb)
+[**⬇ Download `claude-faf-mcp-5.7.2.mcpb`**](https://github.com/Wolfe-Jam/claude-faf-mcp/releases/latest/download/claude-faf-mcp-5.7.2.mcpb)
 
 Double-click. **No terminal. No JSON config. 32 tools live in 10 seconds.**
 

package/dist/src/faf-core/commands/bi-sync.js

@@ -45,6 +45,7 @@ const path = __importStar(require("path"));
 const fs_1 = require("fs");
 const file_utils_1 = require("../utils/file-utils");
 const agents_js_1 = require("./agents.js");
+const inject_1 = require("../inject");
 const cursor_js_1 = require("./cursor.js");
 const gemini_js_1 = require("./gemini.js");
 /**
@@ -134,7 +135,7 @@ async function syncBiDirectional(projectPath, _options = {}) {
         if (!claudeMdExists) {
             // Create CLAUDE.md from project.faf
             const claudeMdContent = fafToClaudeMd(fafContent);
-            await fs_1.promises.writeFile(claudeMdPath, claudeMdContent, 'utf-8');
+            await (0, inject_1.injectFafBlock)(claudeMdPath, claudeMdContent);
             result.success = true;
             result.direction = 'faf-to-claude';
             result.filesChanged.push('CLAUDE.md');
@@ -143,7 +144,7 @@ async function syncBiDirectional(projectPath, _options = {}) {
         else {
             // Both files exist - update CLAUDE.md from project.faf
             const claudeMdContent = fafToClaudeMd(fafContent);
-            await fs_1.promises.writeFile(claudeMdPath, claudeMdContent, 'utf-8');
+            await (0, inject_1.injectFafBlock)(claudeMdPath, claudeMdContent);
             result.success = true;
             result.direction = 'faf-to-claude';
             result.filesChanged.push('CLAUDE.md');

package/dist/src/faf-core/inject.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Block markers for the faf-managed front section. Markdown files use HTML
+ * comments; non-markdown files (.cursorrules) pass hash-comment markers.
+ */
+export declare const FAF_START = "<!-- faf:start -->";
+export declare const FAF_END = "<!-- faf:end -->";
+/**
+ * Non-destructively write a faf-managed block into a file.
+ *
+ *   - no file                                 -> create it with just the block
+ *   - markers present                         -> replace ONLY between them (update in place)
+ *   - legacy faf file (metastamp, no markers) -> reclaim in place (no duplication)
+ *   - genuine user file                       -> prefix the block; preserve everything below
+ *
+ * Idempotent: re-runs update the block, never duplicate or destroy user content.
+ * faf owns what's between the markers; the user owns everything else.
+ * Enhance, never replace.
+ */
+export declare function injectFafBlock(path: string, block: string, start?: string, end?: string): Promise<void>;

package/dist/src/faf-core/inject.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAF_END = exports.FAF_START = void 0;
+exports.injectFafBlock = injectFafBlock;
+const fs_1 = require("fs");
+/**
+ * Block markers for the faf-managed front section. Markdown files use HTML
+ * comments; non-markdown files (.cursorrules) pass hash-comment markers.
+ */
+exports.FAF_START = '<!-- faf:start -->';
+exports.FAF_END = '<!-- faf:end -->';
+/**
+ * faf's own metastamp fingerprint. Every faf-generated file begins with it and a
+ * user never hand-writes it — so a markerless file led by it is legacy faf output
+ * we can safely reclaim, never genuine user content.
+ */
+const FAF_METASTAMP = '<!-- faf:';
+/**
+ * Non-destructively write a faf-managed block into a file.
+ *
+ *   - no file                                 -> create it with just the block
+ *   - markers present                         -> replace ONLY between them (update in place)
+ *   - legacy faf file (metastamp, no markers) -> reclaim in place (no duplication)
+ *   - genuine user file                       -> prefix the block; preserve everything below
+ *
+ * Idempotent: re-runs update the block, never duplicate or destroy user content.
+ * faf owns what's between the markers; the user owns everything else.
+ * Enhance, never replace.
+ */
+async function injectFafBlock(path, block, start = exports.FAF_START, end = exports.FAF_END) {
+    const wrapped = `${start}\n${block.trim()}\n${end}`;
+    let existing = null;
+    try {
+        existing = await fs_1.promises.readFile(path, 'utf-8');
+    }
+    catch {
+        existing = null; // file does not exist yet
+    }
+    if (existing === null) {
+        await fs_1.promises.writeFile(path, `${wrapped}\n`, 'utf-8');
+        return;
+    }
+    const s = existing.indexOf(start);
+    const e = existing.indexOf(end);
+    if (s !== -1 && e !== -1 && e > s) {
+        await fs_1.promises.writeFile(path, existing.slice(0, s) + wrapped + existing.slice(e + end.length), 'utf-8');
+        return;
+    }
+    if (existing.trimStart().startsWith(FAF_METASTAMP)) {
+        // Legacy faf output — reclaim in place, no duplication.
+        await fs_1.promises.writeFile(path, `${wrapped}\n`, 'utf-8');
+        return;
+    }
+    // Genuine user file — prefix the block, preserve everything.
+    await fs_1.promises.writeFile(path, `${wrapped}\n\n${existing}`, 'utf-8');
+}
+//# sourceMappingURL=inject.js.map

package/dist/src/faf-core/parsers/agents-parser.js

@@ -23,6 +23,7 @@ exports.detectAgentsMd = detectAgentsMd;
 exports.detectGlobalAgentsMd = detectGlobalAgentsMd;
 const fs_1 = require("fs");
 const path_1 = __importDefault(require("path"));
+const inject_1 = require("../inject");
 // ============================================================================
 // Parsing
 // ============================================================================
@@ -278,9 +279,9 @@ async function agentsExport(fafContent, outputPath) {
     lines.push('---');
     lines.push(`*Generated from project.faf by claude-faf-mcp — ${new Date().toISOString().split('T')[0]}*`);
     lines.push('');
-    // Write file
+    // Write file — non-destructive: inject/update the faf block, preserve the rest.
     const content = lines.join('\n');
-    await fs_1.promises.writeFile(outputPath, content);
+    await (0, inject_1.injectFafBlock)(outputPath, content);
     return {
         success: true,
         filePath: outputPath,

package/dist/src/faf-core/parsers/cursorrules-parser.js

@@ -25,6 +25,7 @@ exports.cursorExport = cursorExport;
 exports.detectCursorRules = detectCursorRules;
 const fs_1 = require("fs");
 const path_1 = __importDefault(require("path"));
+const inject_1 = require("../inject");
 // ============================================================================
 // Parsing
 // ============================================================================
@@ -41,6 +42,9 @@ function parseCursorRules(content) {
     const rawLines = [];
     for (const line of lines) {
         rawLines.push(line);
+        // Skip faf's own block markers — they are not headings or content.
+        if (line.trim() === '# faf:start' || line.trim() === '# faf:end')
+            continue;
         // H1 = Project name
         const h1Match = line.match(/^#\s+(?:Project:\s*)?(.+)$/);
         if (h1Match) {
@@ -286,9 +290,9 @@ async function cursorExport(fafContent, outputPath) {
     lines.push('---');
     lines.push(`Generated from project.faf by claude-faf-mcp — ${new Date().toISOString().split('T')[0]}`);
     lines.push('');
-    // Write file
+    // Write file — non-destructive: inject/update the faf block (hash-comment markers), preserve the rest.
     const content = lines.join('\n');
-    await fs_1.promises.writeFile(outputPath, content);
+    await (0, inject_1.injectFafBlock)(outputPath, content, '# faf:start', '# faf:end');
     return {
         success: true,
         filePath: outputPath,

package/dist/src/faf-core/parsers/gemini-parser.js

@@ -23,6 +23,7 @@ exports.detectGeminiMd = detectGeminiMd;
 exports.detectGlobalGeminiMd = detectGlobalGeminiMd;
 const fs_1 = require("fs");
 const path_1 = __importDefault(require("path"));
+const inject_1 = require("../inject");
 // ============================================================================
 // Parsing
 // ============================================================================
@@ -218,9 +219,9 @@ async function geminiExport(fafContent, outputPath) {
         }
         lines.push('');
     }
-    // Write file
+    // Write file — non-destructive: inject/update the faf block, preserve the rest.
     const content = lines.join('\n');
-    await fs_1.promises.writeFile(outputPath, content);
+    await (0, inject_1.injectFafBlock)(outputPath, content);
     return {
         success: true,
         filePath: outputPath,

package/dist/src/fafa/a2a-card.d.ts

@@ -0,0 +1,54 @@
+/**
+ * `.fafa` → A2A AgentCard mapper.
+ *
+ * Maps CFM's FAF Agent Card (`.fafa`) to a conformant **A2A AgentCard**
+ * (A2A protocol v1.0, served at `/.well-known/a2a-agent-card`).
+ *
+ * Posture: `.fafa` is a PEER to the A2A AgentCard — **compatible + enhancing**.
+ * Every A2A field maps from `.fafa`; the enhancement is the **FAF context block**,
+ * which rides as an A2A extension (`one.faf/context`) — byte-equivalent to the MCP
+ * server-card `_meta["one.faf/context"]`. One context, every door.
+ *
+ * Pure mapper (testable). The live A2A *invocation* endpoint (JSON-RPC `message/send`)
+ * is served at the edge — this module produces the discovery card that points at it.
+ */
+export declare const A2A_PROTOCOL_VERSION = "1.0";
+export declare const A2A_WELL_KNOWN_PATH = "/.well-known/a2a-agent-card";
+export interface A2AAgentSkill {
+    id: string;
+    name: string;
+    description?: string;
+    tags: string[];
+    examples?: string[];
+    inputModes?: string[];
+    outputModes?: string[];
+}
+export interface A2AAgentCard {
+    protocolVersion: string;
+    name: string;
+    description?: string;
+    url: string;
+    version?: string;
+    provider?: {
+        organization?: string;
+        url?: string;
+    };
+    capabilities: {
+        streaming: boolean;
+        pushNotifications: boolean;
+        extendedAgentCard: boolean;
+    };
+    defaultInputModes: string[];
+    defaultOutputModes: string[];
+    skills: A2AAgentSkill[];
+    extensions?: {
+        uri: string;
+        description?: string;
+        required: boolean;
+        params?: Record<string, unknown>;
+    }[];
+}
+/** Map a parsed `.fafa` document to a conformant A2A AgentCard. */
+export declare function fafaToA2ACard(fafa: any, opts: {
+    url: string;
+}): A2AAgentCard;

package/dist/src/fafa/a2a-card.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * `.fafa` → A2A AgentCard mapper.
+ *
+ * Maps CFM's FAF Agent Card (`.fafa`) to a conformant **A2A AgentCard**
+ * (A2A protocol v1.0, served at `/.well-known/a2a-agent-card`).
+ *
+ * Posture: `.fafa` is a PEER to the A2A AgentCard — **compatible + enhancing**.
+ * Every A2A field maps from `.fafa`; the enhancement is the **FAF context block**,
+ * which rides as an A2A extension (`one.faf/context`) — byte-equivalent to the MCP
+ * server-card `_meta["one.faf/context"]`. One context, every door.
+ *
+ * Pure mapper (testable). The live A2A *invocation* endpoint (JSON-RPC `message/send`)
+ * is served at the edge — this module produces the discovery card that points at it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.A2A_WELL_KNOWN_PATH = exports.A2A_PROTOCOL_VERSION = void 0;
+exports.fafaToA2ACard = fafaToA2ACard;
+exports.A2A_PROTOCOL_VERSION = '1.0';
+exports.A2A_WELL_KNOWN_PATH = '/.well-known/a2a-agent-card';
+/** Map a parsed `.fafa` document to a conformant A2A AgentCard. */
+function fafaToA2ACard(fafa, opts) {
+    const agent = fafa?.agent ?? {};
+    const card = {
+        protocolVersion: exports.A2A_PROTOCOL_VERSION,
+        name: agent.name,
+        description: agent.description,
+        url: opts.url, // A2A service endpoint (JSON-RPC) — served at the edge
+        version: agent.version,
+        provider: { organization: agent.vendor, url: agent.homepage },
+        // CFM's tools are synchronous request/response; no streaming/push yet.
+        capabilities: { streaming: false, pushNotifications: false, extendedAgentCard: false },
+        defaultInputModes: ['text/plain', 'application/json'],
+        defaultOutputModes: ['text/plain', 'application/json'],
+        // A2A skill ≡ FAF capability ≡ MCP tool (per AGENT-FORMAT §3).
+        skills: (fafa?.capabilities ?? []).map((c) => ({
+            id: c.name,
+            name: c.name,
+            description: c.description,
+            tags: Array.isArray(c.tags) ? c.tags : [],
+        })),
+    };
+    // The enhancement: the FAF context block as an A2A extension (the durable middle).
+    if (fafa?.provenance) {
+        card.extensions = [{
+                uri: 'https://one.faf/context',
+                description: 'FAF context provenance — the durable context block (one context, every door).',
+                required: false,
+                params: fafa.provenance,
+            }];
+    }
+    return card;
+}
+//# sourceMappingURL=a2a-card.js.map

package/dist/src/fafm/faf-memory.d.ts

@@ -0,0 +1,72 @@
+export type Priority = 'ephemeral' | 'standard' | 'high' | 'critical';
+/** Normalise a priority string: map legacy aliases, default unknowns to `standard`. */
+export declare function canonicalPriority(p?: string | null): Priority;
+export interface Fact {
+    text: string;
+    id?: string;
+    type?: string;
+    priority: Priority;
+    tags: string[];
+    links: string[];
+    timestamp?: string;
+    source?: string;
+}
+export interface EtchInput {
+    text: string;
+    id?: string;
+    type?: string;
+    priority?: string;
+    tags?: string[];
+    links?: string[];
+    source?: string;
+}
+export interface RecallOpts {
+    query?: string;
+    tags?: string[];
+    type?: string;
+    minPriority?: string;
+    limit?: number;
+}
+/** A loaded `.fafm` knowledge soul + its basic offline memory ops. */
+export declare class Soul {
+    namepoint: string;
+    profile: string;
+    retention: string;
+    created: string;
+    last_etched: string;
+    private _facts;
+    private _byId;
+    constructor(namepoint: string, opts?: {
+        profile?: string;
+        facts?: Fact[];
+        retention?: string;
+        created?: string;
+    });
+    get facts(): Fact[];
+    static fromObj(o: any): Fact;
+    /** Load a `.fafm` soul from disk; namepoint defaults to the filename stem. */
+    static load(soulPath: string): Soul;
+    /** Load if the soul exists, else a fresh empty soul (offline-first, no account). */
+    static open(soulPath: string, namepoint?: string): Soul;
+    private factToObj;
+    toDoc(): Record<string, any>;
+    toYaml(): string;
+    save(soulPath: string): string;
+    /** Insert or update a Fact by id (O(1) dedup); else append. The merge primitive. */
+    add(fact: Fact): Fact;
+    /** Write a fact. If `id` matches an existing fact it's updated in place; else appended. */
+    etch(input: EtchInput): Fact;
+    /**
+     * Deterministic recall: case-insensitive substring on `text`, tag intersection,
+     * type equality, priority floor — ranked by priority, then recency, then
+     * insertion index (so the most-recently-etched fact always wins ties).
+     */
+    recall(opts?: RecallOpts): Fact[];
+    getFact(id: string): Fact | undefined;
+    /** The lean index — one-liners for always-loaded recall (`id — text`). */
+    index(): {
+        id: string;
+        text: string;
+        priority: Priority;
+    }[];
+}

package/dist/src/fafm/faf-memory.js

@@ -0,0 +1,229 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Soul = void 0;
+exports.canonicalPriority = canonicalPriority;
+/**
+ * FAFMemory — a conformant TypeScript implementation of the `.fafm` v1.1 memory
+ * soul (`application/vnd.fafm+yaml`). Local, offline-first.
+ *
+ * Parity-true with the Python `claude-fafm-sdk` (`Soul.etch` / `Soul.recall`) —
+ * same priority vocab, same dedup-by-id, same recall ranking (priority → recency
+ * → insertion-index). This is the seed of `claude-fafm-sdk-ts`.
+ *
+ * Boundary (doctrine): this is FAFMemory — it owns `etch`/`recall`/soul state.
+ * Context (`.faf`) is a separate object; the caller composes them. Recall NEVER
+ * lives on the context side.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const YAML = __importStar(require("yaml"));
+const PRIORITY_ORDER = ['ephemeral', 'standard', 'high', 'critical'];
+const PRIORITY_RANK = Object.fromEntries(PRIORITY_ORDER.map((p, i) => [p, i]));
+const LEGACY_PRIORITY = { low: 'ephemeral', medium: 'standard' };
+/** Normalise a priority string: map legacy aliases, default unknowns to `standard`. */
+function canonicalPriority(p) {
+    if (!p)
+        return 'standard';
+    if (p in LEGACY_PRIORITY)
+        return LEGACY_PRIORITY[p];
+    return (p in PRIORITY_RANK ? p : 'standard');
+}
+/** Second-granularity UTC ISO stamp (matches existing souls; ties broken by insertion index). */
+function utcnow() {
+    return new Date().toISOString().replace(/\.\d+Z$/, 'Z');
+}
+/** A loaded `.fafm` knowledge soul + its basic offline memory ops. */
+class Soul {
+    namepoint;
+    profile;
+    retention;
+    created;
+    last_etched;
+    _facts;
+    _byId;
+    constructor(namepoint, opts = {}) {
+        this.namepoint = namepoint;
+        this.profile = opts.profile ?? 'knowledge';
+        this.retention = opts.retention ?? 'forever';
+        this.created = opts.created ?? utcnow();
+        this.last_etched = this.created;
+        this._facts = opts.facts ?? [];
+        this._byId = new Map();
+        this._facts.forEach((f, i) => { if (f.id != null)
+            this._byId.set(f.id, i); });
+    }
+    get facts() { return this._facts; }
+    static fromObj(o) {
+        return {
+            text: o.text,
+            id: o.id ?? undefined,
+            type: o.type ?? undefined,
+            priority: canonicalPriority(o.priority),
+            tags: Array.isArray(o.tags) ? o.tags : [],
+            links: Array.isArray(o.links) ? o.links : [],
+            timestamp: o.timestamp ?? undefined,
+            source: o.source ?? undefined,
+        };
+    }
+    /** Load a `.fafm` soul from disk; namepoint defaults to the filename stem. */
+    static load(soulPath) {
+        const doc = YAML.parse(fs.readFileSync(soulPath, 'utf-8')) || {};
+        if (typeof doc !== 'object' || Array.isArray(doc))
+            throw new Error('soul is not a YAML mapping');
+        const memory = doc.memory || {};
+        const soul = new Soul(doc.namepoint ?? path.basename(soulPath, path.extname(soulPath)), {
+            profile: doc.profile ?? 'knowledge',
+            facts: (memory.facts || []).map((f) => Soul.fromObj(f)),
+            retention: doc.retention ?? 'forever',
+            created: doc.created,
+        });
+        soul.last_etched = doc.last_etched ?? soul.created;
+        return soul;
+    }
+    /** Load if the soul exists, else a fresh empty soul (offline-first, no account). */
+    static open(soulPath, namepoint) {
+        if (fs.existsSync(soulPath))
+            return Soul.load(soulPath);
+        return new Soul(namepoint ?? path.basename(soulPath, path.extname(soulPath)));
+    }
+    factToObj(f) {
+        const out = { text: f.text };
+        if (f.id != null)
+            out.id = f.id;
+        if (f.type != null)
+            out.type = f.type;
+        out.priority = f.priority;
+        if (f.tags.length)
+            out.tags = f.tags;
+        if (f.links.length)
+            out.links = f.links;
+        if (f.timestamp != null)
+            out.timestamp = f.timestamp;
+        if (f.source != null)
+            out.source = f.source;
+        return out;
+    }
+    toDoc() {
+        return {
+            version: '1.1',
+            profile: this.profile,
+            namepoint: this.namepoint,
+            created: this.created,
+            last_etched: this.last_etched,
+            retention: this.retention,
+            memory: {
+                facts: this._facts.map((f) => this.factToObj(f)),
+                sessions: [],
+                preferences: {},
+                custom: {},
+            },
+        };
+    }
+    toYaml() {
+        return YAML.stringify(this.toDoc(), { lineWidth: 100 });
+    }
+    save(soulPath) {
+        fs.mkdirSync(path.dirname(path.resolve(soulPath)), { recursive: true });
+        fs.writeFileSync(soulPath, this.toYaml(), 'utf-8');
+        return soulPath;
+    }
+    /** Insert or update a Fact by id (O(1) dedup); else append. The merge primitive. */
+    add(fact) {
+        if (fact.id != null && this._byId.has(fact.id)) {
+            this._facts[this._byId.get(fact.id)] = fact;
+        }
+        else {
+            this._facts.push(fact);
+            if (fact.id != null)
+                this._byId.set(fact.id, this._facts.length - 1);
+        }
+        if (fact.timestamp && fact.timestamp > (this.last_etched || ''))
+            this.last_etched = fact.timestamp;
+        return fact;
+    }
+    /** Write a fact. If `id` matches an existing fact it's updated in place; else appended. */
+    etch(input) {
+        return this.add({
+            text: input.text,
+            id: input.id,
+            type: input.type,
+            priority: canonicalPriority(input.priority),
+            tags: [...(input.tags ?? [])],
+            links: [...(input.links ?? [])],
+            timestamp: utcnow(),
+            source: input.source,
+        });
+    }
+    /**
+     * Deterministic recall: case-insensitive substring on `text`, tag intersection,
+     * type equality, priority floor — ranked by priority, then recency, then
+     * insertion index (so the most-recently-etched fact always wins ties).
+     */
+    recall(opts = {}) {
+        const floor = PRIORITY_RANK[canonicalPriority(opts.minPriority ?? 'ephemeral')] ?? 0;
+        const q = (opts.query ?? '').toLowerCase();
+        const wantTags = new Set(opts.tags ?? []);
+        const indexed = this._facts
+            .map((f, i) => ({ f, i }))
+            .filter(({ f }) => (!q || f.text.toLowerCase().includes(q)) &&
+            (wantTags.size === 0 || f.tags.some((t) => wantTags.has(t))) &&
+            (opts.type == null || f.type === opts.type) &&
+            ((PRIORITY_RANK[f.priority] ?? 1) >= floor));
+        indexed.sort((a, b) => {
+            const ra = PRIORITY_RANK[a.f.priority] ?? 1, rb = PRIORITY_RANK[b.f.priority] ?? 1;
+            if (ra !== rb)
+                return rb - ra; // priority desc
+            const ta = a.f.timestamp ?? '', tb = b.f.timestamp ?? '';
+            if (ta !== tb)
+                return ta < tb ? 1 : -1; // recency desc
+            return b.i - a.i; // insertion index desc
+        });
+        const results = indexed.map(({ f }) => f);
+        return opts.limit != null ? results.slice(0, opts.limit) : results;
+    }
+    getFact(id) {
+        const i = this._byId.get(id);
+        return i != null ? this._facts[i] : undefined;
+    }
+    /** The lean index — one-liners for always-loaded recall (`id — text`). */
+    index() {
+        return this._facts
+            .filter((f) => f.id != null)
+            .map((f) => ({ id: f.id, text: f.text, priority: f.priority }));
+    }
+}
+exports.Soul = Soul;
+//# sourceMappingURL=faf-memory.js.map