@jagilber-org/index-server 1.19.1

package/dist/services/messaging/messagingTypes.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReadMessagesOptionsSchema = exports.SendMessageOptionsSchema = exports.AgentMessageSchema = exports.MESSAGE_PRIORITIES = exports.MAX_READ_LIMIT = exports.MAX_BODY_LENGTH = exports.SWEEP_INTERVAL_MS = exports.DEFAULT_TTL_SECONDS = exports.MAX_TTL_SECONDS = void 0;
+/**
+ * Messaging types, Zod schemas, and constants.
+ *
+ * Defines the data model for the inter-agent messaging system.
+ * Messages are short-term, ephemeral (not stored in the instruction index)
+ * but persist across instances/sessions via JSONL files.
+ */
+const zod_1 = require("zod");
+// ── Constants ────────────────────────────────────────────────────────────────
+/** Maximum time-to-live in seconds (24 hours). */
+exports.MAX_TTL_SECONDS = 86_400;
+/** Default time-to-live in seconds (1 hour). */
+exports.DEFAULT_TTL_SECONDS = 3_600;
+/** Sweep interval in milliseconds (60 seconds). */
+exports.SWEEP_INTERVAL_MS = 60_000;
+/** Maximum body size in characters (100KB). */
+exports.MAX_BODY_LENGTH = 100_000;
+/** Maximum messages per read response. */
+exports.MAX_READ_LIMIT = 500;
+// ── Priority enum ────────────────────────────────────────────────────────────
+exports.MESSAGE_PRIORITIES = ['low', 'normal', 'high', 'critical'];
+// ── Zod schemas ──────────────────────────────────────────────────────────────
+exports.AgentMessageSchema = zod_1.z.object({
+    id: zod_1.z.string().min(1),
+    channel: zod_1.z.string().min(1),
+    sender: zod_1.z.string().min(1),
+    recipients: zod_1.z.array(zod_1.z.string().min(1)).min(1),
+    body: zod_1.z.string().min(1).max(exports.MAX_BODY_LENGTH),
+    createdAt: zod_1.z.string().min(1),
+    ttlSeconds: zod_1.z.number().int().min(0).max(exports.MAX_TTL_SECONDS),
+    persistent: zod_1.z.boolean().optional(),
+    readBy: zod_1.z.array(zod_1.z.string()).optional(),
+    payload: zod_1.z.record(zod_1.z.unknown()).optional(),
+    priority: zod_1.z.enum(exports.MESSAGE_PRIORITIES).optional(),
+    parentId: zod_1.z.string().optional(),
+    requiresAck: zod_1.z.boolean().optional(),
+    ackBySeconds: zod_1.z.number().int().positive().optional(),
+    tags: zod_1.z.array(zod_1.z.string()).optional(),
+    origin: zod_1.z.string().optional(),
+}).strict();
+exports.SendMessageOptionsSchema = zod_1.z.object({
+    channel: zod_1.z.string().min(1),
+    sender: zod_1.z.string().min(1),
+    recipients: zod_1.z.array(zod_1.z.string().min(1)).min(1),
+    body: zod_1.z.string().min(1).max(exports.MAX_BODY_LENGTH),
+    ttlSeconds: zod_1.z.number().int().min(1).max(exports.MAX_TTL_SECONDS).optional(),
+    persistent: zod_1.z.boolean().optional(),
+    payload: zod_1.z.record(zod_1.z.unknown()).optional(),
+    priority: zod_1.z.enum(exports.MESSAGE_PRIORITIES).optional(),
+    parentId: zod_1.z.string().optional(),
+    requiresAck: zod_1.z.boolean().optional(),
+    ackBySeconds: zod_1.z.number().int().positive().optional(),
+    tags: zod_1.z.array(zod_1.z.string()).optional(),
+}).strict();
+exports.ReadMessagesOptionsSchema = zod_1.z.object({
+    channel: zod_1.z.string().min(1).optional(),
+    reader: zod_1.z.string().min(1).optional(),
+    unreadOnly: zod_1.z.boolean().optional(),
+    limit: zod_1.z.number().int().min(1).max(exports.MAX_READ_LIMIT).optional(),
+    markRead: zod_1.z.boolean().optional(),
+    tags: zod_1.z.array(zod_1.z.string()).optional(),
+    sender: zod_1.z.string().min(1).optional(),
+}).strict();

package/dist/services/ownershipService.d.ts

@@ -0,0 +1 @@
+export declare function resolveOwner(id: string): string | undefined;

package/dist/services/ownershipService.js

@@ -0,0 +1,38 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveOwner = resolveOwner;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+let cached = null;
+function loadRules() {
+    const file = path_1.default.join(process.cwd(), 'owners.json');
+    try {
+        if (!fs_1.default.existsSync(file))
+            return [];
+        const stat = fs_1.default.statSync(file);
+        if (cached && cached.mtimeMs === stat.mtimeMs)
+            return cached.rules;
+        const raw = JSON.parse(fs_1.default.readFileSync(file, 'utf8'));
+        const rules = Array.isArray(raw.ownership) ? raw.ownership.filter(r => r && typeof r.pattern === 'string' && typeof r.owner === 'string') : [];
+        cached = { mtimeMs: stat.mtimeMs, rules };
+        return rules;
+    }
+    catch {
+        return [];
+    }
+}
+function resolveOwner(id) {
+    const rules = loadRules();
+    for (const r of rules) {
+        try {
+            const re = new RegExp(r.pattern);
+            if (re.test(id))
+                return r.owner;
+        }
+        catch { /* ignore */ }
+    }
+    return undefined;
+}

package/dist/services/performanceBaseline.d.ts

@@ -0,0 +1,19 @@
+interface PerformanceResults {
+    listOperations: {
+        withoutUsage: number[];
+        withUsage: number[];
+        overhead: number;
+    };
+    mutationOperations: {
+        withoutUsage: number[];
+        withUsage: number[];
+        overhead: number;
+    };
+    summary: {
+        listOverheadPercent: number;
+        mutationOverheadPercent: number;
+        meetsTarget: boolean;
+    };
+}
+export declare function runPerformanceBaseline(): Promise<PerformanceResults>;
+export {};

package/dist/services/performanceBaseline.js

@@ -0,0 +1,210 @@
+"use strict";
+// Performance baseline measurement script for Phase 1 usage tracking
+// Measures mutation and list operation timing to establish <5% overhead target
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runPerformanceBaseline = runPerformanceBaseline;
+const child_process_1 = require("child_process");
+const perf_hooks_1 = require("perf_hooks");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+function startServer(enableUsage) {
+    return new Promise((resolve) => {
+        const env = {
+            ...process.env,
+            INDEX_SERVER_MUTATION: '1',
+            INDEX_SERVER_FEATURES: enableUsage ? 'usage' : '',
+            INDEX_SERVER_VERBOSE_LOGGING: ''
+        };
+        const server = (0, child_process_1.spawn)('node', ['dist/server/index-server.js'], {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env
+        });
+        const output = [];
+        server.stdout?.on('data', d => {
+            output.push(...d.toString().trim().split(/\n+/).filter((l) => l));
+        });
+        // Wait for server to be ready
+        setTimeout(() => resolve({ server, output }), 200);
+    });
+}
+function send(server, msg) {
+    server.stdin?.write(JSON.stringify(msg) + '\n');
+}
+function waitFor(output, predicate, timeout = 2000) {
+    return new Promise((resolve, reject) => {
+        const start = Date.now();
+        const check = () => {
+            const line = output.find(predicate);
+            if (line) {
+                resolve(line);
+            }
+            else if (Date.now() - start > timeout) {
+                reject(new Error('Timeout waiting for response'));
+            }
+            else {
+                setTimeout(check, 10);
+            }
+        };
+        check();
+    });
+}
+async function measureListOperations(enableUsage, iterations = 50) {
+    const { server, output } = await startServer(enableUsage);
+    const timings = [];
+    try {
+        // Initialize
+        send(server, {
+            jsonrpc: '2.0',
+            id: 1,
+            method: 'initialize',
+            params: {
+                protocolVersion: '2025-06-18',
+                clientInfo: { name: 'perf-baseline', version: '0' },
+                capabilities: { tools: {} }
+            }
+        });
+        await waitFor(output, line => line.includes('"id":1'));
+        // Measure list operations
+        for (let i = 0; i < iterations; i++) {
+            const start = perf_hooks_1.performance.now();
+            // Use unified dispatcher (legacy instructions/list removed)
+            send(server, { jsonrpc: '2.0', id: 100 + i, method: 'index_dispatch', params: { action: 'list' } });
+            await waitFor(output, line => line.includes(`"id":${100 + i}`));
+            const end = perf_hooks_1.performance.now();
+            timings.push(end - start);
+        }
+        server.kill();
+        return timings;
+    }
+    catch (error) {
+        server.kill();
+        throw error;
+    }
+}
+async function measureMutationOperations(enableUsage, iterations = 20) {
+    const { server, output } = await startServer(enableUsage);
+    const timings = [];
+    try {
+        // Initialize
+        send(server, {
+            jsonrpc: '2.0',
+            id: 1,
+            method: 'initialize',
+            params: {
+                protocolVersion: '2025-06-18',
+                clientInfo: { name: 'perf-baseline', version: '0' },
+                capabilities: { tools: {} }
+            }
+        });
+        await waitFor(output, line => line.includes('"id":1'));
+        // Measure add operations (mutations)
+        for (let i = 0; i < iterations; i++) {
+            const start = perf_hooks_1.performance.now();
+            const entry = {
+                id: `perf-test-${i}`,
+                title: `Performance Test ${i}`,
+                body: 'Performance test entry for baseline measurement',
+                priority: 10,
+                audience: 'all',
+                requirement: 'optional',
+                categories: ['performance']
+            };
+            send(server, {
+                jsonrpc: '2.0',
+                id: 200 + i,
+                method: 'index_add',
+                params: { entry, overwrite: true }
+            });
+            await waitFor(output, line => line.includes(`"id":${200 + i}`));
+            const end = perf_hooks_1.performance.now();
+            timings.push(end - start);
+        }
+        server.kill();
+        return timings;
+    }
+    catch (error) {
+        server.kill();
+        throw error;
+    }
+}
+function calculateStats(timings) {
+    const sorted = [...timings].sort((a, b) => a - b);
+    const mean = timings.reduce((sum, t) => sum + t, 0) / timings.length;
+    const p95 = sorted[Math.floor(sorted.length * 0.95)];
+    const p99 = sorted[Math.floor(sorted.length * 0.99)];
+    return { mean, p95, p99 };
+}
+function calculateOverhead(withoutUsage, withUsage) {
+    const baselineP95 = calculateStats(withoutUsage).p95;
+    const usageP95 = calculateStats(withUsage).p95;
+    return ((usageP95 - baselineP95) / baselineP95) * 100;
+}
+async function runPerformanceBaseline() {
+    console.log('🚀 Starting Phase 1 Performance Baseline Measurement...');
+    console.log('Target: <5% overhead for usage tracking');
+    console.log();
+    // List operations
+    console.log('📊 Measuring list operations...');
+    const listWithoutUsage = await measureListOperations(false);
+    const listWithUsage = await measureListOperations(true);
+    const listOverhead = calculateOverhead(listWithoutUsage, listWithUsage);
+    console.log('✅ List operations measured');
+    console.log(`   Without usage: ${calculateStats(listWithoutUsage).p95.toFixed(2)}ms P95`);
+    console.log(`   With usage: ${calculateStats(listWithUsage).p95.toFixed(2)}ms P95`);
+    console.log(`   Overhead: ${listOverhead.toFixed(2)}%`);
+    console.log();
+    // Mutation operations
+    console.log('📊 Measuring mutation operations...');
+    const mutationWithoutUsage = await measureMutationOperations(false);
+    const mutationWithUsage = await measureMutationOperations(true);
+    const mutationOverhead = calculateOverhead(mutationWithoutUsage, mutationWithUsage);
+    console.log('✅ Mutation operations measured');
+    console.log(`   Without usage: ${calculateStats(mutationWithoutUsage).p95.toFixed(2)}ms P95`);
+    console.log(`   With usage: ${calculateStats(mutationWithUsage).p95.toFixed(2)}ms P95`);
+    console.log(`   Overhead: ${mutationOverhead.toFixed(2)}%`);
+    console.log();
+    // Summary
+    const maxOverhead = Math.max(listOverhead, mutationOverhead);
+    const meetsTarget = maxOverhead <= 5.0;
+    console.log('📈 Performance Baseline Summary:');
+    console.log(`   List operations overhead: ${listOverhead.toFixed(2)}%`);
+    console.log(`   Mutation operations overhead: ${mutationOverhead.toFixed(2)}%`);
+    console.log(`   Maximum overhead: ${maxOverhead.toFixed(2)}%`);
+    console.log(`   Target met (<5%): ${meetsTarget ? '✅ YES' : '❌ NO'}`);
+    const results = {
+        listOperations: {
+            withoutUsage: listWithoutUsage,
+            withUsage: listWithUsage,
+            overhead: listOverhead
+        },
+        mutationOperations: {
+            withoutUsage: mutationWithoutUsage,
+            withUsage: mutationWithUsage,
+            overhead: mutationOverhead
+        },
+        summary: {
+            listOverheadPercent: listOverhead,
+            mutationOverheadPercent: mutationOverhead,
+            meetsTarget
+        }
+    };
+    // Save results
+    const timestamp = new Date().toISOString();
+    const baselineFile = `data/performance-baseline-${timestamp.slice(0, 10)}.json`;
+    const dataDir = path_1.default.dirname(baselineFile);
+    if (!fs_1.default.existsSync(dataDir)) {
+        fs_1.default.mkdirSync(dataDir, { recursive: true });
+    }
+    fs_1.default.writeFileSync(baselineFile, JSON.stringify({
+        timestamp,
+        phase: 'Phase 1 Usage Tracking',
+        target: '<5% overhead',
+        results
+    }, null, 2));
+    console.log();
+    console.log(`💾 Detailed results saved to: ${baselineFile}`);
+    return results;
+}

package/dist/services/preflight.d.ts

@@ -0,0 +1,12 @@
+export interface PreflightCheckResult {
+    name: string;
+    ok: boolean;
+    path?: string;
+    error?: string;
+}
+export interface PreflightSummary {
+    ok: boolean;
+    checks: PreflightCheckResult[];
+}
+export declare function runPreflight(): PreflightSummary;
+export declare function emitPreflightAndMaybeExit(): void;

package/dist/services/preflight.js

@@ -0,0 +1,79 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runPreflight = runPreflight;
+exports.emitPreflightAndMaybeExit = emitPreflightAndMaybeExit;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const runtimeConfig_1 = require("../config/runtimeConfig");
+// List of module specifiers or file probes required at runtime. Adjustable via env overrides.
+const DEFAULT_MODULES = ['mime-db', 'ajv', 'ajv-formats'];
+function resolveModule(mod) {
+    try {
+        const p = require.resolve(mod);
+        return { name: mod, ok: true, path: p };
+    }
+    catch (e) {
+        return { name: mod, ok: false, error: e.message };
+    }
+}
+function checkMimeDbData() {
+    try {
+        // Some deployments strip nested data; ensure the db.json file exists beneath mime-db
+        const base = path_1.default.dirname(require.resolve('mime-db'));
+        const candidate = path_1.default.join(base, 'db.json');
+        if (fs_1.default.existsSync(candidate))
+            return { name: 'mime-db:db.json', ok: true, path: candidate };
+        return { name: 'mime-db:db.json', ok: false, error: 'db.json not found in resolved mime-db package directory' };
+    }
+    catch (e) {
+        return { name: 'mime-db:db.json', ok: false, error: e.message };
+    }
+}
+function runPreflight() {
+    const cfg = (0, runtimeConfig_1.getRuntimeConfig)().preflight;
+    const modules = cfg.modules.length ? cfg.modules : DEFAULT_MODULES;
+    const checks = [];
+    for (const m of modules)
+        checks.push(resolveModule(m));
+    // Specialized data file check for mime-db
+    if (modules.includes('mime-db'))
+        checks.push(checkMimeDbData());
+    const ok = checks.every(c => c.ok);
+    return { ok, checks };
+}
+function emitPreflightAndMaybeExit() {
+    try {
+        const summary = runPreflight();
+        const line = JSON.stringify({ level: summary.ok ? 'info' : 'error', event: 'startup-preflight', ok: summary.ok, checks: summary.checks });
+        // stderr to avoid contaminating stdout protocol
+        try {
+            process.stderr.write(line + '\n');
+        }
+        catch { /* ignore */ }
+        if (!summary.ok) {
+            const cfg = (0, runtimeConfig_1.getRuntimeConfig)().preflight;
+            if (cfg.strict) {
+                try {
+                    process.stderr.write('[startup] Preflight failed (strict mode) – exiting early.\n');
+                }
+                catch { /* ignore */ }
+                process.exit(1);
+            }
+            else {
+                try {
+                    process.stderr.write('[startup] Preflight reported missing optional dependencies (continuing).\n');
+                }
+                catch { /* ignore */ }
+            }
+        }
+    }
+    catch (e) {
+        try {
+            process.stderr.write(`[startup] preflight_unexpected ${e.message}\n`);
+        }
+        catch { /* ignore */ }
+    }
+}

package/dist/services/promptReviewService.d.ts

@@ -0,0 +1,44 @@
+export interface PromptRule {
+    id: string;
+    pattern?: string;
+    mustContain?: string;
+    severity: string;
+    description: string;
+}
+export interface PromptCategory {
+    id: string;
+    rules: PromptRule[];
+}
+export interface PromptCriteria {
+    version: string;
+    categories: PromptCategory[];
+}
+export interface PromptIssue {
+    ruleId: string;
+    severity: string;
+    description: string;
+    match?: string;
+}
+export declare class PromptReviewService {
+    private criteria;
+    /**
+     * @param criteriaPath - Optional explicit path to a `PROMPT-CRITERIA.json` file.
+     *   When omitted the service searches a set of standard candidate locations.
+     */
+    constructor(criteriaPath?: string);
+    /**
+     * Run all loaded criteria rules against a prompt string and return any detected issues.
+     * @param prompt - Prompt text to review
+     * @returns Array of {@link PromptIssue} objects describing detected rule violations; empty when clean
+     */
+    review(prompt: string): PromptIssue[];
+}
+/**
+ * Aggregate a list of prompt issues into per-severity counts and identify the highest severity present.
+ * @param issues - Array of issues returned by {@link PromptReviewService.review}
+ * @returns Object with `counts` map (severity → count) and `highestSeverity` string
+ */
+export declare function summarizeIssues(issues: PromptIssue[]): {
+    counts: Record<string, number>;
+    highestSeverity: string;
+};

package/dist/services/promptReviewService.js

@@ -0,0 +1,101 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PromptReviewService = void 0;
+exports.summarizeIssues = summarizeIssues;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+class PromptReviewService {
+    criteria;
+    /**
+     * @param criteriaPath - Optional explicit path to a `PROMPT-CRITERIA.json` file.
+     *   When omitted the service searches a set of standard candidate locations.
+     */
+    constructor(criteriaPath) {
+        // Resolve criteria path with fallbacks so the server doesn't crash if cwd differs.
+        const candidates = [];
+        if (criteriaPath) {
+            candidates.push(criteriaPath);
+        }
+        else {
+            // Original expected (project root when launched correctly)
+            candidates.push(path_1.default.join(process.cwd(), 'docs', 'PROMPT-CRITERIA.json'));
+            // From compiled file location: dist/services -> ../../docs
+            candidates.push(path_1.default.resolve(__dirname, '..', '..', 'docs', 'PROMPT-CRITERIA.json'));
+            // Additional fallback: dist/server -> ../docs
+            candidates.push(path_1.default.resolve(__dirname, '..', 'docs', 'PROMPT-CRITERIA.json'));
+        }
+        let loaded;
+        let usedPath;
+        for (const p of candidates) {
+            try {
+                const data = fs_1.default.readFileSync(p, 'utf8');
+                loaded = JSON.parse(data);
+                usedPath = p;
+                break;
+            }
+            catch { /* continue */ }
+        }
+        if (!loaded) {
+            // Graceful fallback: empty criteria so server can still start.
+            const msg = `[promptReviewService] WARN: Could not locate PROMPT-CRITERIA.json in any candidate paths. Using empty criteria.`;
+            // Write to stderr explicitly (console.error already does)
+            console.error(msg);
+            loaded = { version: '0.0.0', categories: [] };
+        }
+        else {
+            console.error(`[promptReviewService] Loaded criteria from ${usedPath}`); // stderr so it won't pollute stdout
+        }
+        this.criteria = loaded;
+    }
+    /**
+     * Run all loaded criteria rules against a prompt string and return any detected issues.
+     * @param prompt - Prompt text to review
+     * @returns Array of {@link PromptIssue} objects describing detected rule violations; empty when clean
+     */
+    review(prompt) {
+        const issues = [];
+        for (const cat of this.criteria.categories) {
+            for (const rule of cat.rules) {
+                if (rule.pattern) {
+                    // Apply global + case-insensitive flags for broader detection
+                    const regex = new RegExp(rule.pattern, 'gi');
+                    const m = prompt.match(regex);
+                    if (m) {
+                        issues.push({ ruleId: rule.id, severity: rule.severity, description: rule.description, match: m[0] });
+                    }
+                }
+                if (rule.mustContain) {
+                    const mc = new RegExp(rule.mustContain, 'i');
+                    if (!mc.test(prompt)) {
+                        issues.push({ ruleId: rule.id, severity: rule.severity, description: 'Missing required token(s): ' + rule.description });
+                    }
+                }
+            }
+        }
+        return issues;
+    }
+}
+exports.PromptReviewService = PromptReviewService;
+/**
+ * Aggregate a list of prompt issues into per-severity counts and identify the highest severity present.
+ * @param issues - Array of issues returned by {@link PromptReviewService.review}
+ * @returns Object with `counts` map (severity → count) and `highestSeverity` string
+ */
+function summarizeIssues(issues) {
+    const counts = {};
+    const severityRank = { critical: 4, high: 3, medium: 2, low: 1, info: 0 };
+    let max = -1;
+    let highest = 'info';
+    for (const i of issues) {
+        counts[i.severity] = (counts[i.severity] || 0) + 1;
+        const r = severityRank[i.severity] ?? 0;
+        if (r > max) {
+            max = r;
+            highest = i.severity;
+        }
+    }
+    return { counts, highestSeverity: highest };
+}

package/dist/services/responseEnvelope.d.ts

@@ -0,0 +1,6 @@
+export interface EnvelopeV1<T = unknown> {
+    version: number;
+    serverVersion: string;
+    data: T;
+}
+export declare function wrapResponse<T>(data: T): T | EnvelopeV1<T>;

package/dist/services/responseEnvelope.js

@@ -0,0 +1,25 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrapResponse = wrapResponse;
+const featureFlags_1 = require("./featureFlags");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+// Resolve version once (lazy) for envelope
+let version = '0.0.0';
+try {
+    const pkg = path_1.default.join(process.cwd(), 'package.json');
+    if (fs_1.default.existsSync(pkg)) {
+        const raw = JSON.parse(fs_1.default.readFileSync(pkg, 'utf8'));
+        if (raw.version)
+            version = raw.version;
+    }
+}
+catch { /* ignore */ }
+function wrapResponse(data) {
+    if (!(0, featureFlags_1.flagEnabled)('response_envelope_v1'))
+        return data;
+    return { version: 1, serverVersion: version, data };
+}

package/dist/services/seedBootstrap.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Automatic bootstrap seeding (Option B: create only if missing).
+ *
+ * Creates the two canonical baseline instruction files when BOTH of these are true:
+ *  - INDEX_SERVER_AUTO_SEED !== '0' (default on)
+ *  - Target instructions directory is empty OR any of the seed files are missing
+ *
+ * Never overwrites existing files. Idempotent and safe under concurrent multi-process
+ * startup (best‑effort). Creation uses write-to-temp + rename for atomicity to avoid
+ * partially written JSON on crashes.
+ */
+export interface SeedSummary {
+    dir: string;
+    created: string[];
+    existing: string[];
+    skipped: string[];
+    disabled: boolean;
+    reason?: string;
+    hash: string;
+}
+/**
+ * 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
+ */
+export declare function autoSeedBootstrap(): SeedSummary;
+/**
+ * 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
+ */
+export declare function _getCanonicalSeeds(): {
+    file: string;
+    id: string;
+}[];