@jagilber-org/index-server 1.22.0

package/dist/services/seedBootstrap.js

@@ -0,0 +1,259 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.autoSeedBootstrap = autoSeedBootstrap;
+exports._getCanonicalSeeds = _getCanonicalSeeds;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = __importDefault(require("crypto"));
+const indexContext_1 = require("./indexContext");
+const logger_1 = require("./logger");
+const runtimeConfig_1 = require("../config/runtimeConfig");
+// Canonical seed instruction objects (kept intentionally minimal – DO NOT add environment specific data)
+const CANONICAL_SEEDS = [
+    {
+        file: '000-bootstrapper.json',
+        id: '000-bootstrapper',
+        json: {
+            id: '000-bootstrapper',
+            title: 'Index Server - AI Agent Quick Start',
+            body: `# Index Server: AI Agent Quick Start
+
+Index Server is a shared knowledge base for AI agents via MCP. Agents search, read, and contribute instructions that persist across sessions and repositories.
+
+## Verify Connection
+
+\`\`\`json
+{"method": "health_check", "params": {}}
+\`\`\`
+
+Success → skip to "How to Use" below. Error → see "Setup" at the end.
+
+---
+
+## How to Use
+
+### Search First (always)
+
+**Before creating, promoting, or rewriting instructions, search for existing ones:**
+
+\`\`\`json
+{"method": "index_search", "params": {"keywords": ["deployment", "docker"]}}
+\`\`\`
+
+Then retrieve the full content of a match:
+
+\`\`\`json
+{"method": "index_dispatch", "params": {"action": "get", "id": "instruction-id-from-search"}}
+\`\`\`
+
+Search when the task involves patterns, standards, prior approaches, governance, shared guidance, or cross-repo learnings.
+
+### Browse & Discover
+
+| Task | Tool | Params |
+|------|------|--------|
+| List all instructions | \`index_dispatch\` | \`{"action": "list"}\` |
+| Browse categories | \`index_dispatch\` | \`{"action": "categories"}\` |
+| Search by keywords | \`index_search\` | \`{"keywords": ["term1", "term2"]}\` |
+| Get by ID | \`index_dispatch\` | \`{"action": "get", "id": "..."}\` |
+| Server health | \`health_check\` | \`{}\` |
+| All available tools | \`meta_tools\` | \`{}\` |
+| Help & overview | \`help_overview\` | \`{}\` |
+
+### When to Use Index Server
+
+**Use for:** Cross-repo patterns, architecture decisions, coding standards, troubleshooting runbooks, security policies, onboarding guides, and validated learnings from past sessions.
+
+**Don't use for:** Reading current file contents (use repo files directly), ephemeral task notes, or repo-private secrets.
+
+---
+
+## Contributing Knowledge
+
+### Search → Validate Locally → Promote
+
+1. **Search first** — check if similar guidance already exists
+2. **Start local** — create new instructions in your repo's \`.instructions/\` directory
+3. **Validate** — use across multiple sessions to prove value
+4. **Promote** — move proven patterns to the shared index:
+
+\`\`\`json
+{"method": "promote_from_repo", "params": {"repoPath": "/path/to/repo"}}
+\`\`\`
+
+Or add directly:
+
+\`\`\`json
+{"method": "index_add", "params": {"entry": {"id": "my-guide", "title": "My Guide", "body": "Content..."}, "lax": true}}
+\`\`\`
+
+### Maintenance
+
+- \`index_groom\` — clean duplicates and stale entries
+- \`index_governanceUpdate\` — deprecate outdated content (don't silently delete)
+- \`feedback_dispatch\` with action="submit" — report issues or request features
+- \`usage_track\` — signal when guidance was helpful or outdated
+
+---
+
+## Copilot Instructions Setup
+
+Add these to your copilot instructions so agents always know about the knowledge base.
+
+### Global (~/.github/copilot-instructions.md)
+
+\`\`\`markdown
+## Index Server
+- If index-server MCP tools are available, use them as a shared knowledge base for validated cross-repo patterns and standards.
+- Search before creating: use index_search with 2-5 keywords, then index_dispatch with action="get" for details.
+- After learning something reusable, add it with index_add or promote from a repo with promote_from_repo.
+- Index entries are promoted snapshots — always prefer current repo files over index content.
+\`\`\`
+
+### Per-Repo (.github/copilot-instructions.md)
+
+\`\`\`markdown
+## Index Server Integration
+- Search order: repo files → .instructions/ → index-server → external docs
+- Search before add/promote: always search for existing guidance before creating new instructions.
+- To retrieve: index_search → index_dispatch with action="get" and the instruction ID
+- To contribute: validate locally in .instructions/ first, then promote with promote_from_repo
+- To maintain: use index_groom to clean duplicates, index_governanceUpdate to deprecate stale content
+- Current repo state always wins over promoted index snapshots
+\`\`\`
+
+---
+
+## Setup (if not yet configured)
+
+### VS Code (.vscode/mcp.json)
+
+\`\`\`json
+{"servers": {"index-server": {"type": "stdio", "command": "npx", "args": ["@jagilber-org/index-server", "--dashboard"]}}}
+\`\`\`
+
+### Copilot CLI (~/.copilot/mcp-config.json)
+
+\`\`\`json
+{"mcpServers": {"index-server": {"type": "stdio", "command": "npx", "args": ["@jagilber-org/index-server", "--dashboard"], "tools": ["*"]}}}
+\`\`\`
+
+### Claude Desktop (claude_desktop_config.json)
+
+\`\`\`json
+{"mcpServers": {"index-server": {"type": "stdio", "command": "npx", "args": ["@jagilber-org/index-server", "--dashboard"], "tools": ["*"]}}}
+\`\`\`
+
+### Docker
+
+\`\`\`bash
+docker compose up  # HTTP on :8787
+\`\`\`
+
+Restart your MCP client after configuration changes. Verify with \`health_check\`.
+
+For full configuration options: see \`docs/mcp_configuration.md\` and \`docs/configuration.md\`.`,
+            audience: 'agents',
+            requirement: 'required',
+            priority: 100,
+            categories: ['bootstrap', 'mcp-activation', 'quick-start', 'documentation'],
+            owner: 'system',
+            version: 3,
+            schemaVersion: '4',
+            semanticSummary: 'Index Server quick start: search-first workflow, knowledge contribution, copilot instructions setup, and MCP client configuration for AI agents'
+        }
+    },
+    {
+        file: '001-lifecycle-bootstrap.json',
+        id: '001-lifecycle-bootstrap',
+        json: {
+            id: '001-lifecycle-bootstrap',
+            title: 'Lifecycle Bootstrap: Local-First Instruction Strategy',
+            body: 'Purpose: Early lifecycle guidance after bootstrap confirmation. Keep index minimal; prefer local-first P0/P1 additions; promote only after stability.',
+            audience: 'agents',
+            requirement: 'recommended',
+            priorityTier: 'p1',
+            categories: ['bootstrap', 'lifecycle'],
+            owner: 'system',
+            version: 1,
+            schemaVersion: '4',
+            semanticSummary: 'Lifecycle and promotion guardrails after bootstrap confirmation',
+            reviewIntervalDays: 120
+        }
+    }
+];
+function computeCanonicalHash() {
+    const canonical = CANONICAL_SEEDS.map(s => ({ id: s.id, file: s.file, json: s.json })).sort((a, b) => a.id.localeCompare(b.id));
+    return crypto_1.default.createHash('sha256').update(JSON.stringify(canonical), 'utf8').digest('hex');
+}
+/**
+ * Run automatic bootstrap seeding if enabled. Creates canonical seed files only when they are
+ * absent — never overwrites existing content. Safe under concurrent multi-process startup.
+ * @returns A {@link SeedSummary} describing what was created, skipped, or already present
+ */
+function autoSeedBootstrap() {
+    const cfg = (0, runtimeConfig_1.getRuntimeConfig)().bootstrapSeed;
+    const disabled = !cfg.autoSeed;
+    const dir = safeInstructionsDir();
+    const summary = { dir, created: [], existing: [], skipped: [], disabled, hash: computeCanonicalHash() };
+    if (disabled) {
+        summary.reason = 'disabled_by_env';
+        return summary;
+    }
+    try {
+        fs_1.default.mkdirSync(dir, { recursive: true });
+    }
+    catch { /* ignore */ }
+    // Probe directory existence (previously stored entries unused; keep check for side effects)
+    try {
+        fs_1.default.readdirSync(dir);
+    }
+    catch { /* ignore */ }
+    for (const seed of CANONICAL_SEEDS) {
+        const target = path_1.default.join(dir, seed.file);
+        const exists = fs_1.default.existsSync(target);
+        if (exists) {
+            summary.existing.push(seed.file);
+            summary.skipped.push(seed.file);
+            continue; // do not overwrite
+        }
+        // Directory empty OR missing seed triggers creation.
+        try {
+            const tmp = path_1.default.join(dir, `.${seed.file}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`);
+            fs_1.default.writeFileSync(tmp, JSON.stringify(seed.json, null, 2), { encoding: 'utf8' });
+            fs_1.default.renameSync(tmp, target);
+            summary.created.push(seed.file);
+        }
+        catch (e) {
+            summary.reason = `partial_failure ${(e instanceof Error) ? e.message : String(e)}`;
+        }
+    }
+    if ((0, runtimeConfig_1.getRuntimeConfig)().bootstrapSeed.verbose) {
+        try {
+            process.stderr.write(`[seed] dir="${dir}" created=${summary.created.length} existing=${summary.existing.length} disabled=${summary.disabled} hash=${summary.hash}\n`);
+        }
+        catch { /* ignore */ }
+    }
+    try {
+        (0, logger_1.logInfo)('[seedBootstrap] Seed summary', summary);
+    }
+    catch { /* ignore */ }
+    return summary;
+}
+function safeInstructionsDir() {
+    try {
+        return (0, indexContext_1.getInstructionsDir)();
+    }
+    catch {
+        return path_1.default.join(process.cwd(), 'instructions');
+    }
+}
+// Test helper re-export for direct validation
+/**
+ * Return the list of canonical seed file/id pairs (without JSON bodies) for test assertions.
+ * @returns Array of `{ file, id }` objects for each canonical seed
+ */
+function _getCanonicalSeeds() { return CANONICAL_SEEDS.map(s => ({ file: s.file, id: s.id })); }

package/dist/services/storage/factory.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Storage backend factory.
+ *
+ * Creates the appropriate IInstructionStore implementation based on config.
+ * Default: JsonFileStore (json). Experimental: SqliteStore (sqlite).
+ */
+import type { IInstructionStore } from './types.js';
+export type StorageBackend = 'json' | 'sqlite';
+/**
+ * Create a storage backend instance.
+ *
+ * @param backend - Override backend type (default: from config).
+ * @param dir - Override instruction directory (default: from config).
+ * @param sqlitePath - Override SQLite DB path (default: from config).
+ * @returns An IInstructionStore implementation.
+ */
+export declare function createStore(backend?: StorageBackend, dir?: string, sqlitePath?: string): IInstructionStore;

package/dist/services/storage/factory.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * Storage backend factory.
+ *
+ * Creates the appropriate IInstructionStore implementation based on config.
+ * Default: JsonFileStore (json). Experimental: SqliteStore (sqlite).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createStore = createStore;
+const runtimeConfig_js_1 = require("../../config/runtimeConfig.js");
+const jsonFileStore_js_1 = require("./jsonFileStore.js");
+const sqliteStore_js_1 = require("./sqliteStore.js");
+/**
+ * Create a storage backend instance.
+ *
+ * @param backend - Override backend type (default: from config).
+ * @param dir - Override instruction directory (default: from config).
+ * @param sqlitePath - Override SQLite DB path (default: from config).
+ * @returns An IInstructionStore implementation.
+ */
+function createStore(backend, dir, sqlitePath) {
+    const config = (0, runtimeConfig_js_1.getRuntimeConfig)();
+    const resolvedBackend = backend ?? config.storage?.backend ?? 'json';
+    const resolvedDir = dir ?? config.index?.baseDir;
+    switch (resolvedBackend) {
+        case 'sqlite': {
+            console.warn('[storage] ⚠️  EXPERIMENTAL: SQLite backend is enabled. This feature has limited testing and may have data-loss or compatibility issues. Not recommended for production use.');
+            const dbPath = sqlitePath ?? config.storage?.sqlitePath ?? 'data/index.db';
+            return new sqliteStore_js_1.SqliteStore(dbPath);
+        }
+        case 'json':
+        default:
+            return new jsonFileStore_js_1.JsonFileStore(resolvedDir);
+    }
+}

package/dist/services/storage/hashUtils.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared governance hashing utilities for storage backends.
+ *
+ * Both JsonFileStore and SqliteStore must produce identical governance hashes
+ * for the same set of entries. This module ensures that.
+ */
+import { InstructionEntry } from '../../models/instruction.js';
+/** @internal Governance projection for deterministic hashing. */
+export declare function projectGovernance(e: InstructionEntry): Record<string, unknown>;
+/** Compute deterministic governance hash from an array of entries. */
+export declare function computeGovernanceHashFromEntries(entries: InstructionEntry[]): string;

package/dist/services/storage/hashUtils.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * Shared governance hashing utilities for storage backends.
+ *
+ * Both JsonFileStore and SqliteStore must produce identical governance hashes
+ * for the same set of entries. This module ensures that.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectGovernance = projectGovernance;
+exports.computeGovernanceHashFromEntries = computeGovernanceHashFromEntries;
+const crypto_1 = __importDefault(require("crypto"));
+/** @internal Governance projection for deterministic hashing. */
+function projectGovernance(e) {
+    return {
+        id: e.id,
+        title: e.title,
+        version: e.version ?? '0.0.0',
+        owner: e.owner ?? 'unowned',
+        priorityTier: e.priorityTier ?? 'P4',
+        nextReviewDue: e.nextReviewDue ?? '',
+        semanticSummarySha256: e.semanticSummary
+            ? crypto_1.default.createHash('sha256').update(e.semanticSummary).digest('hex')
+            : '',
+        changeLogLength: e.changeLog?.length ?? 0,
+    };
+}
+/** Compute deterministic governance hash from an array of entries. */
+function computeGovernanceHashFromEntries(entries) {
+    const sorted = [...entries].sort((a, b) => a.id.localeCompare(b.id));
+    const projection = sorted.map(e => JSON.stringify(projectGovernance(e)));
+    return crypto_1.default.createHash('sha256').update(projection.join('\n')).digest('hex');
+}

package/dist/services/storage/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Storage — Instruction storage abstraction layer.
+ *
+ * Exports the IInstructionStore interface and backend implementations.
+ * Backend selection is controlled by INDEX_SERVER_STORAGE_BACKEND env var.
+ */
+export type { IInstructionStore, ListOptions, QueryOptions, ScopedListOptions, SearchOptions, SearchResult, UsagePersistRecord, UsageTrackOptions, LoadResult, } from './types.js';
+export { JsonFileStore } from './jsonFileStore.js';
+export { SqliteStore } from './sqliteStore.js';
+export { createStore } from './factory.js';
+export { computeGovernanceHashFromEntries, projectGovernance } from './hashUtils.js';
+export type { StorageBackend } from './factory.js';

package/dist/services/storage/index.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * Storage — Instruction storage abstraction layer.
+ *
+ * Exports the IInstructionStore interface and backend implementations.
+ * Backend selection is controlled by INDEX_SERVER_STORAGE_BACKEND env var.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectGovernance = exports.computeGovernanceHashFromEntries = exports.createStore = exports.SqliteStore = exports.JsonFileStore = void 0;
+var jsonFileStore_js_1 = require("./jsonFileStore.js");
+Object.defineProperty(exports, "JsonFileStore", { enumerable: true, get: function () { return jsonFileStore_js_1.JsonFileStore; } });
+var sqliteStore_js_1 = require("./sqliteStore.js");
+Object.defineProperty(exports, "SqliteStore", { enumerable: true, get: function () { return sqliteStore_js_1.SqliteStore; } });
+var factory_js_1 = require("./factory.js");
+Object.defineProperty(exports, "createStore", { enumerable: true, get: function () { return factory_js_1.createStore; } });
+var hashUtils_js_1 = require("./hashUtils.js");
+Object.defineProperty(exports, "computeGovernanceHashFromEntries", { enumerable: true, get: function () { return hashUtils_js_1.computeGovernanceHashFromEntries; } });
+Object.defineProperty(exports, "projectGovernance", { enumerable: true, get: function () { return hashUtils_js_1.projectGovernance; } });

package/dist/services/storage/jsonFileStore.d.ts

@@ -0,0 +1,32 @@
+/**
+ * JsonFileStore — JSON-file-per-instruction storage backend.
+ *
+ * Wraps the existing file-based storage pattern: each instruction is a
+ * separate .json file in a directory. This is the default backend.
+ *
+ * Implements IInstructionStore for the storage abstraction layer.
+ */
+import { InstructionEntry } from '../../models/instruction.js';
+import type { IInstructionStore, ListOptions, QueryOptions, ScopedListOptions, SearchOptions, SearchResult, LoadResult } from './types.js';
+export declare class JsonFileStore implements IInstructionStore {
+    private readonly dir;
+    private cache;
+    private loaded;
+    /**
+     * @param dir - Directory containing instruction .json files.
+     */
+    constructor(dir: string);
+    load(): LoadResult;
+    close(): void;
+    get(id: string): InstructionEntry | null;
+    write(entry: InstructionEntry): void;
+    remove(id: string): void;
+    list(opts?: ListOptions): InstructionEntry[];
+    query(opts: QueryOptions): InstructionEntry[];
+    listScoped(opts: ScopedListOptions): InstructionEntry[];
+    search(opts: SearchOptions): SearchResult[];
+    categories(): Map<string, number>;
+    computeHash(): string;
+    count(): number;
+    private ensureLoaded;
+}

package/dist/services/storage/jsonFileStore.js

@@ -0,0 +1,241 @@
+"use strict";
+/**
+ * JsonFileStore — JSON-file-per-instruction storage backend.
+ *
+ * Wraps the existing file-based storage pattern: each instruction is a
+ * separate .json file in a directory. This is the default backend.
+ *
+ * Implements IInstructionStore for the storage abstraction layer.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JsonFileStore = void 0;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = __importDefault(require("crypto"));
+const hashUtils_js_1 = require("./hashUtils.js");
+class JsonFileStore {
+    dir;
+    cache = new Map();
+    loaded = false;
+    /**
+     * @param dir - Directory containing instruction .json files.
+     */
+    constructor(dir) {
+        this.dir = dir;
+        if (!fs_1.default.existsSync(dir)) {
+            fs_1.default.mkdirSync(dir, { recursive: true });
+        }
+    }
+    // ── Lifecycle ──────────────────────────────────────────────────────
+    load() {
+        const errors = [];
+        const entries = [];
+        let scanned = 0;
+        let skipped = 0;
+        const files = fs_1.default.readdirSync(this.dir).filter(f => f.endsWith('.json') && !f.startsWith('_') && !f.startsWith('.'));
+        scanned = files.length;
+        for (const file of files) {
+            try {
+                const raw = fs_1.default.readFileSync(path_1.default.join(this.dir, file), 'utf-8');
+                const parsed = JSON.parse(raw.replace(/^\uFEFF/, ''));
+                // Handle arrays (some files contain instruction arrays)
+                const items = Array.isArray(parsed) ? parsed : [parsed];
+                for (const item of items) {
+                    const entry = item;
+                    if (!entry.id || !entry.title || !entry.body) {
+                        skipped++;
+                        continue;
+                    }
+                    entries.push(entry);
+                }
+            }
+            catch (err) {
+                skipped++;
+                errors.push({ file, error: err instanceof Error ? err.message : 'Unknown parse error' });
+            }
+        }
+        // Deduplicate by ID (last-write-wins)
+        const byId = new Map();
+        for (const e of entries) {
+            byId.set(e.id, e);
+        }
+        const deduped = Array.from(byId.values());
+        this.cache = byId;
+        this.loaded = true;
+        return {
+            entries: deduped,
+            hash: (0, hashUtils_js_1.computeGovernanceHashFromEntries)(deduped),
+            errors,
+            debug: { scanned, accepted: deduped.length, skipped },
+            summary: {
+                scanned,
+                accepted: deduped.length,
+                skipped,
+                reasons: errors.length > 0 ? { 'parse-error': errors.length } : {},
+            },
+        };
+    }
+    close() {
+        this.cache.clear();
+        this.loaded = false;
+    }
+    // ── CRUD ───────────────────────────────────────────────────────────
+    get(id) {
+        this.ensureLoaded();
+        return this.cache.get(id) ?? null;
+    }
+    write(entry) {
+        // Write to disk
+        const filePath = path_1.default.join(this.dir, `${entry.id}.json`);
+        const tmpPath = `${filePath}.${crypto_1.default.randomBytes(4).toString('hex')}.tmp`;
+        fs_1.default.writeFileSync(tmpPath, JSON.stringify(entry, null, 2), 'utf-8');
+        fs_1.default.renameSync(tmpPath, filePath);
+        // Update in-memory cache
+        this.cache.set(entry.id, entry);
+        this.loaded = true;
+    }
+    remove(id) {
+        const filePath = path_1.default.join(this.dir, `${id}.json`);
+        try {
+            if (fs_1.default.existsSync(filePath)) {
+                fs_1.default.unlinkSync(filePath);
+            }
+        }
+        catch {
+            // No-op on failure (file may already be gone)
+        }
+        this.cache.delete(id);
+    }
+    // ── Queries ────────────────────────────────────────────────────────
+    list(opts) {
+        this.ensureLoaded();
+        let result = Array.from(this.cache.values());
+        if (opts?.category) {
+            result = result.filter(e => e.categories?.includes(opts.category));
+        }
+        if (opts?.contentType) {
+            result = result.filter(e => e.contentType === opts.contentType);
+        }
+        return result;
+    }
+    query(opts) {
+        this.ensureLoaded();
+        let result = Array.from(this.cache.values());
+        if (opts.text) {
+            const lower = opts.text.toLowerCase();
+            result = result.filter(e => e.title.toLowerCase().includes(lower) ||
+                e.body.toLowerCase().includes(lower) ||
+                (e.semanticSummary && e.semanticSummary.toLowerCase().includes(lower)));
+        }
+        if (opts.categoriesAny?.length) {
+            const set = new Set(opts.categoriesAny);
+            result = result.filter(e => e.categories?.some(c => set.has(c)));
+        }
+        if (opts.categoriesAll?.length) {
+            result = result.filter(e => opts.categoriesAll.every(c => e.categories?.includes(c)));
+        }
+        if (opts.excludeCategories?.length) {
+            const excl = new Set(opts.excludeCategories);
+            result = result.filter(e => !e.categories?.some(c => excl.has(c)));
+        }
+        if (opts.contentType) {
+            result = result.filter(e => e.contentType === opts.contentType);
+        }
+        if (opts.priorityMin !== undefined) {
+            result = result.filter(e => e.priority >= opts.priorityMin);
+        }
+        if (opts.priorityMax !== undefined) {
+            result = result.filter(e => e.priority <= opts.priorityMax);
+        }
+        if (opts.priorityTiers?.length) {
+            const tiers = new Set(opts.priorityTiers);
+            result = result.filter(e => e.priorityTier && tiers.has(e.priorityTier));
+        }
+        if (opts.requirements?.length) {
+            const reqs = new Set(opts.requirements);
+            result = result.filter(e => reqs.has(e.requirement));
+        }
+        // Pagination
+        if (opts.offset) {
+            result = result.slice(opts.offset);
+        }
+        if (opts.limit) {
+            result = result.slice(0, opts.limit);
+        }
+        return result;
+    }
+    listScoped(opts) {
+        this.ensureLoaded();
+        let result = Array.from(this.cache.values());
+        if (opts.userId) {
+            result = result.filter(e => e.userId === opts.userId || e.audience === 'all');
+        }
+        if (opts.workspaceId) {
+            result = result.filter(e => e.workspaceId === opts.workspaceId || e.audience === 'all');
+        }
+        if (opts.teamIds?.length) {
+            const teams = new Set(opts.teamIds);
+            result = result.filter(e => e.audience === 'all' ||
+                e.teamIds?.some(t => teams.has(t)));
+        }
+        return result;
+    }
+    search(opts) {
+        this.ensureLoaded();
+        const results = [];
+        for (const entry of this.cache.values()) {
+            let score = 0;
+            const titleLower = entry.title.toLowerCase();
+            const bodyLower = entry.body.toLowerCase();
+            const catStr = (entry.categories ?? []).join(' ').toLowerCase();
+            for (const kw of opts.keywords) {
+                const kwLower = opts.caseSensitive ? kw : kw.toLowerCase();
+                const title = opts.caseSensitive ? entry.title : titleLower;
+                const body = opts.caseSensitive ? entry.body : bodyLower;
+                if (title.includes(kwLower))
+                    score += 3;
+                if (body.includes(kwLower))
+                    score += 1;
+                if (opts.includeCategories && catStr.includes(kwLower))
+                    score += 2;
+            }
+            if (score > 0) {
+                results.push({ id: entry.id, score });
+            }
+        }
+        results.sort((a, b) => b.score - a.score);
+        if (opts.limit) {
+            return results.slice(0, opts.limit);
+        }
+        return results;
+    }
+    categories() {
+        this.ensureLoaded();
+        const counts = new Map();
+        for (const entry of this.cache.values()) {
+            for (const cat of entry.categories ?? []) {
+                counts.set(cat, (counts.get(cat) ?? 0) + 1);
+            }
+        }
+        return counts;
+    }
+    // ── Integrity ──────────────────────────────────────────────────────
+    computeHash() {
+        this.ensureLoaded();
+        return (0, hashUtils_js_1.computeGovernanceHashFromEntries)(Array.from(this.cache.values()));
+    }
+    count() {
+        this.ensureLoaded();
+        return this.cache.size;
+    }
+    // ── Internal ───────────────────────────────────────────────────────
+    ensureLoaded() {
+        if (!this.loaded) {
+            this.load();
+        }
+    }
+}
+exports.JsonFileStore = JsonFileStore;