@jagilber-org/index-server 1.19.1

package/dist/services/classificationService.js

@@ -0,0 +1,168 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClassificationService = void 0;
+const schemaVersion_1 = require("../versioning/schemaVersion");
+const crypto_1 = __importDefault(require("crypto"));
+class ClassificationService {
+    /**
+     * Normalize an instruction entry by filling governance defaults, deriving scope fields,
+     * computing hashes, and canonicalizing text fields.
+     * @param entry - Raw instruction entry to normalize
+     * @returns A fully normalized {@link NormalizedInstruction} with all governance defaults applied
+     */
+    normalize(entry) {
+        const now = new Date().toISOString();
+        const trimmedTitle = entry.title.trim();
+        const trimmedBody = entry.body.trim();
+        // Derive structured scope fields from legacy category prefixes if not already present
+        let workspaceId = entry.workspaceId;
+        let userId = entry.userId;
+        const teamIds = entry.teamIds ? [...entry.teamIds] : [];
+        const otherCats = [];
+        for (const cRaw of entry.categories) {
+            const c = cRaw.toLowerCase();
+            if (c.startsWith('scope:workspace:')) {
+                if (!workspaceId)
+                    workspaceId = c.substring('scope:workspace:'.length);
+                continue;
+            }
+            if (c.startsWith('scope:user:')) {
+                if (!userId)
+                    userId = c.substring('scope:user:'.length);
+                continue;
+            }
+            if (c.startsWith('scope:team:')) {
+                const tid = c.substring('scope:team:'.length);
+                if (tid && !teamIds.includes(tid))
+                    teamIds.push(tid);
+                continue;
+            }
+            otherCats.push(cRaw);
+        }
+        // Governance defaults
+        const version = entry.version || '1.0.0';
+        const status = entry.status || (entry.requirement === 'deprecated' ? 'deprecated' : 'approved');
+        const owner = entry.owner || 'unowned';
+        const priorityTier = entry.priorityTier || this.computePriorityTier(entry.priority, entry.requirement);
+        const classification = entry.classification || 'internal';
+        const lastReviewedAt = entry.lastReviewedAt || now;
+        const reviewIntervalDays = entry.reviewIntervalDays ?? this.reviewIntervalDays(priorityTier, entry.requirement);
+        const nextReviewDue = entry.nextReviewDue || new Date(Date.now() + reviewIntervalDays * 86400_000).toISOString();
+        const changeLog = entry.changeLog && entry.changeLog.length ? entry.changeLog : [{ version, changedAt: entry.createdAt || now, summary: 'initial import' }];
+        const semanticSummary = entry.semanticSummary || this.deriveSummary(entry.body);
+        const contentType = entry.contentType || 'instruction'; // Default to 'instruction' for backward compatibility
+        const norm = {
+            ...entry,
+            title: trimmedTitle,
+            body: trimmedBody,
+            categories: Array.from(new Set(otherCats.map(c => c.toLowerCase()))).sort(),
+            updatedAt: entry.updatedAt || now,
+            createdAt: entry.createdAt || now,
+            // Guarantee schemaVersion presence (tests/assertions now rely on dispatcher list action output)
+            schemaVersion: entry.schemaVersion || schemaVersion_1.SCHEMA_VERSION,
+            // Compute hash from canonical (trimmed) body to ensure stability across innocuous whitespace differences
+            sourceHash: entry.sourceHash && entry.sourceHash.length === 64 ? entry.sourceHash : this.computeHash(trimmedBody),
+            riskScore: this.computeRisk(entry),
+            workspaceId,
+            userId,
+            teamIds: teamIds.length ? teamIds : undefined,
+            version,
+            status,
+            owner,
+            priorityTier,
+            classification,
+            lastReviewedAt,
+            nextReviewDue,
+            reviewIntervalDays,
+            changeLog: changeLog,
+            supersedes: entry.supersedes,
+            semanticSummary,
+            contentType
+        };
+        return norm;
+    }
+    /**
+     * Validate an instruction entry for required fields and logical consistency.
+     * @param entry - Instruction entry to validate
+     * @returns Array of human-readable issue strings; empty when the entry is valid
+     */
+    validate(entry) {
+        const issues = [];
+        if (!entry.id)
+            issues.push('missing id');
+        if (!entry.title)
+            issues.push('missing title');
+        if (!entry.body)
+            issues.push('missing body');
+        if (entry.requirement === 'deprecated' && !entry.deprecatedBy)
+            issues.push('deprecated requires deprecatedBy');
+        return issues;
+    }
+    /**
+     * Compute a numeric risk score for an instruction entry (higher = riskier).
+     * Score is derived from priority and requirement level.
+     * @param entry - Instruction entry to score
+     * @returns Numeric risk score
+     */
+    computeRisk(entry) {
+        const base = 100 - Math.min(Math.max(entry.priority, 1), 100);
+        const reqWeight = this.requirementWeight(entry.requirement);
+        return base + reqWeight;
+    }
+    requirementWeight(r) {
+        switch (r) {
+            case 'mandatory': return 50;
+            case 'critical': return 60;
+            case 'recommended': return 20;
+            case 'optional': return 5;
+            case 'deprecated': return -30;
+            default: return 0;
+        }
+    }
+    /**
+     * Compute a SHA-256 hex digest of the given content string.
+     * @param content - UTF-8 string to hash
+     * @returns 64-character hex-encoded SHA-256 digest
+     */
+    computeHash(content) { return crypto_1.default.createHash('sha256').update(content, 'utf8').digest('hex'); }
+    computePriorityTier(priority, requirement) {
+        // Lower numeric is higher importance
+        if (priority <= 20 || requirement === 'mandatory' || requirement === 'critical')
+            return 'P1';
+        if (priority <= 40)
+            return 'P2';
+        if (priority <= 70)
+            return 'P3';
+        return 'P4';
+    }
+    reviewIntervalDays(tier, requirement) {
+        // Shorter intervals for higher criticality
+        if (tier === 'P1' || requirement === 'mandatory' || requirement === 'critical')
+            return 30;
+        if (tier === 'P2')
+            return 60;
+        if (tier === 'P3')
+            return 90;
+        return 120;
+    }
+    // Public helper for schema migration - computes review interval
+    /**
+     * Compute the recommended review interval in days for a given priority tier and requirement level.
+     * @param tier - Priority tier (`'P1'`–`'P4'`; P1 is highest priority)
+     * @param requirement - Requirement level for the instruction
+     * @returns Number of days until the next review should occur
+     */
+    computeReviewIntervalDays(tier, requirement) {
+        return this.reviewIntervalDays(tier, requirement);
+    }
+    deriveSummary(body) {
+        const trimmed = body.trim();
+        const firstLine = trimmed.split(/\r?\n/)[0];
+        // Keep it short (~160 chars)
+        return firstLine.length > 160 ? firstLine.slice(0, 157) + '...' : firstLine;
+    }
+}
+exports.ClassificationService = ClassificationService;

package/dist/services/embeddingService.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Embedding Service for Semantic Search
+ *
+ * Lazy-loaded embedding model — zero startup cost.
+ * Model is loaded only on first embedText() call via dynamic import.
+ * Vectors cached to disk for cross-instance sharing.
+ *
+ * Key design:
+ * - cosineSimilarity, isStale, load/saveCachedEmbeddings are pure functions (no model needed)
+ * - embedText and getInstructionEmbeddings trigger lazy model load
+ * - Uses @huggingface/transformers (optional dep) via dynamic ESM import
+ */
+import { InstructionEntry } from '../models/instruction';
+/**
+ * Cosine similarity between two vectors.
+ * Pure math — no dependencies, no model needed.
+ */
+export declare function cosineSimilarity(a: Float32Array, b: Float32Array): number;
+/**
+ * Check if cached embeddings are stale (index has changed since last embed).
+ */
+export declare function isStale(indexHash: string, embeddingHash: string): boolean;
+/**
+ * Persisted embedding cache format (backwards-compatible: entryHashes is optional).
+ */
+export interface EmbeddingCacheData {
+    indexHash: string;
+    modelName?: string;
+    /** Per-entry content hashes for incremental invalidation (required for v2+). */
+    entryHashes?: Record<string, string>;
+    embeddings: Record<string, number[]>;
+}
+/**
+ * Load cached embeddings from disk.
+ * Returns null if file doesn't exist or is invalid.
+ */
+export declare function loadCachedEmbeddings(filePath: string): EmbeddingCacheData | null;
+/**
+ * Save embeddings to disk for cross-instance sharing.
+ */
+export declare function saveCachedEmbeddings(filePath: string, data: EmbeddingCacheData): void;
+/**
+ * Embed a single text string into a vector.
+ * Triggers lazy model loading on first call.
+ */
+export declare function embedText(text: string, modelName: string, cacheDir: string, device?: string, localOnly?: boolean): Promise<Float32Array>;
+/** Signature for the embed function (injectable for testing). */
+export type EmbedFn = (text: string, modelName: string, cacheDir: string, device: string, localOnly: boolean) => Promise<Float32Array>;
+/**
+ * Get or compute embeddings for all index instructions.
+ * Uses disk cache when available and fresh.
+ *
+ * Incremental update: when the index hash changes (instructions added/modified),
+ * only entries whose sourceHash differs from the cached value are recomputed.
+ * This reduces cold-recompute from O(all entries) to O(delta entries).
+ *
+ * Concurrency lock: concurrent cache-miss requests share a single in-flight computation
+ * rather than each independently recomputing the full index.
+ *
+ * @param embedFn - Injectable embed function (defaults to module embedText; override in tests).
+ */
+export declare function getInstructionEmbeddings(instructions: InstructionEntry[], indexHash: string, embeddingPath: string, modelName: string, cacheDir: string, device?: string, localOnly?: boolean, embedFn?: EmbedFn): Promise<Record<string, Float32Array>>;

package/dist/services/embeddingService.js

@@ -0,0 +1,259 @@
+"use strict";
+/**
+ * Embedding Service for Semantic Search
+ *
+ * Lazy-loaded embedding model — zero startup cost.
+ * Model is loaded only on first embedText() call via dynamic import.
+ * Vectors cached to disk for cross-instance sharing.
+ *
+ * Key design:
+ * - cosineSimilarity, isStale, load/saveCachedEmbeddings are pure functions (no model needed)
+ * - embedText and getInstructionEmbeddings trigger lazy model load
+ * - Uses @huggingface/transformers (optional dep) via dynamic ESM import
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cosineSimilarity = cosineSimilarity;
+exports.isStale = isStale;
+exports.loadCachedEmbeddings = loadCachedEmbeddings;
+exports.saveCachedEmbeddings = saveCachedEmbeddings;
+exports.embedText = embedText;
+exports.getInstructionEmbeddings = getInstructionEmbeddings;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const logger_1 = require("./logger");
+// Lazy model state — never loaded at import time
+let pipeline = null;
+let extractor = null;
+let modelLoading = null;
+// Concurrency lock for index embedding computation — prevents N concurrent cache-miss
+// requests from each independently computing embeddings for all index entries.
+let indexEmbeddingComputing = null;
+/**
+ * Cosine similarity between two vectors.
+ * Pure math — no dependencies, no model needed.
+ */
+function cosineSimilarity(a, b) {
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(normA) * Math.sqrt(normB);
+    if (denom === 0)
+        return 0;
+    return dot / denom;
+}
+/**
+ * Check if cached embeddings are stale (index has changed since last embed).
+ */
+function isStale(indexHash, embeddingHash) {
+    return indexHash !== embeddingHash;
+}
+/**
+ * Load cached embeddings from disk.
+ * Returns null if file doesn't exist or is invalid.
+ */
+function loadCachedEmbeddings(filePath) {
+    try {
+        if (!fs_1.default.existsSync(filePath))
+            return null;
+        const raw = fs_1.default.readFileSync(filePath, 'utf-8');
+        const data = JSON.parse(raw);
+        if (!data || typeof data.indexHash !== 'string' || typeof data.embeddings !== 'object')
+            return null;
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Save embeddings to disk for cross-instance sharing.
+ */
+function saveCachedEmbeddings(filePath, data) {
+    const dir = path_1.default.dirname(filePath);
+    if (!fs_1.default.existsSync(dir)) {
+        fs_1.default.mkdirSync(dir, { recursive: true });
+    }
+    fs_1.default.writeFileSync(filePath, JSON.stringify(data), 'utf-8');
+}
+// Helper: dynamic ESM import (same pattern as sdkServer.ts)
+const dynamicImport = (specifier) => (Function('m', 'return import(m);'))(specifier);
+/**
+ * Lazily initialize the embedding model.
+ * Only called on first semantic search request — never at import/startup time.
+ *
+ * @param device - 'cpu' (default WASM), 'cuda' (NVIDIA GPU), 'dml' (DirectML/Windows GPU)
+ * @param localOnly - When true, disables remote model downloads (model must already be cached)
+ */
+async function ensureModel(modelName, cacheDir, device = 'cpu', localOnly = false) {
+    if (extractor) {
+        (0, logger_1.logInfo)('[embeddingService] Embedding model already loaded, skipping init');
+        return;
+    }
+    if (modelLoading) {
+        (0, logger_1.logInfo)('[embeddingService] Embedding model load in progress, waiting...');
+        await modelLoading;
+        return;
+    }
+    modelLoading = (async () => {
+        try {
+            // Validate requested device against available ONNX Runtime providers
+            const resolvedDevice = await resolveDevice(device);
+            (0, logger_1.logInfo)(`[embeddingService] Loading embedding model: ${modelName} (device=${resolvedDevice}, localOnly=${localOnly})`);
+            const transformers = await dynamicImport('@huggingface/transformers');
+            // Apply localOnly setting — block remote downloads when set
+            if (localOnly && transformers.env) {
+                transformers.env.allowRemoteModels = false;
+            }
+            pipeline = transformers.pipeline;
+            const pipelineOpts = {
+                cache_dir: cacheDir,
+                quantized: true,
+            };
+            // Set device: 'cpu' uses default WASM; 'cuda'/'dml' use GPU execution providers
+            if (resolvedDevice !== 'cpu') {
+                pipelineOpts.device = resolvedDevice;
+            }
+            extractor = await pipeline('feature-extraction', modelName, pipelineOpts);
+            (0, logger_1.logInfo)(`[embeddingService] Embedding model loaded successfully (device=${resolvedDevice})`);
+        }
+        catch (err) {
+            modelLoading = null;
+            throw err;
+        }
+    })();
+    await modelLoading;
+}
+/**
+ * Check available ONNX Runtime execution providers and resolve the best device.
+ * Falls back to dml → cpu if the requested provider is not available.
+ */
+async function resolveDevice(requested) {
+    if (requested === 'cpu')
+        return 'cpu';
+    try {
+        const ort = await dynamicImport('onnxruntime-node');
+        if (typeof ort.listSupportedBackends === 'function') {
+            const backends = ort.listSupportedBackends();
+            const available = backends.map((b) => b.name);
+            (0, logger_1.logInfo)(`[embeddingService] ONNX Runtime backends available: [${available.join(', ')}]`);
+            if (available.includes(requested))
+                return requested;
+            // Requested provider not available — try fallback chain
+            if (requested === 'cuda' && available.includes('dml')) {
+                (0, logger_1.logWarn)(`[embeddingService] CUDA provider not available (onnxruntime-node does not bundle CUDA). Falling back to DML.`);
+                (0, logger_1.logWarn)(`[embeddingService] To enable CUDA: install CUDA Toolkit + cuDNN, then copy onnxruntime_providers_cuda.dll into node_modules/onnxruntime-node/bin/`);
+                return 'dml';
+            }
+            (0, logger_1.logWarn)(`[embeddingService] ${requested} provider not available. Available: [${available.join(', ')}]. Falling back to cpu.`);
+            return 'cpu';
+        }
+    }
+    catch {
+        (0, logger_1.logWarn)(`[embeddingService] Could not probe ONNX Runtime backends; using requested device '${requested}' as-is.`);
+    }
+    return requested;
+}
+/**
+ * Embed a single text string into a vector.
+ * Triggers lazy model loading on first call.
+ */
+async function embedText(text, modelName, cacheDir, device = 'cpu', localOnly = false) {
+    const start = performance.now();
+    await ensureModel(modelName, cacheDir, device, localOnly);
+    const output = await extractor(text, { pooling: 'mean', normalize: true });
+    const vec = new Float32Array(output.data);
+    (0, logger_1.logInfo)(`[embeddingService] embedText completed in ${(performance.now() - start).toFixed(1)}ms (${text.substring(0, 60)}${text.length > 60 ? '...' : ''})`);
+    return vec;
+}
+/**
+ * Get or compute embeddings for all index instructions.
+ * Uses disk cache when available and fresh.
+ *
+ * Incremental update: when the index hash changes (instructions added/modified),
+ * only entries whose sourceHash differs from the cached value are recomputed.
+ * This reduces cold-recompute from O(all entries) to O(delta entries).
+ *
+ * Concurrency lock: concurrent cache-miss requests share a single in-flight computation
+ * rather than each independently recomputing the full index.
+ *
+ * @param embedFn - Injectable embed function (defaults to module embedText; override in tests).
+ */
+async function getInstructionEmbeddings(instructions, indexHash, embeddingPath, modelName, cacheDir, device = 'cpu', localOnly = false, embedFn = embedText) {
+    // Full cache hit: same index hash and model — return immediately without locking.
+    const cached = loadCachedEmbeddings(embeddingPath);
+    if (cached && !isStale(indexHash, cached.indexHash) && cached.modelName === modelName) {
+        const entryCount = Object.keys(cached.embeddings).length;
+        (0, logger_1.logInfo)(`[embeddingService] Embedding cache HIT: ${entryCount} entries from ${embeddingPath} (model=${modelName})`);
+        const result = {};
+        for (const [id, vec] of Object.entries(cached.embeddings)) {
+            result[id] = new Float32Array(vec);
+        }
+        return result;
+    }
+    // Concurrency lock: if another call is already computing, wait for it.
+    if (indexEmbeddingComputing) {
+        (0, logger_1.logInfo)('[embeddingService] Embedding computation already in progress, waiting...');
+        return await indexEmbeddingComputing;
+    }
+    // Model changed -> cannot reuse any cached entries.
+    const modelChanged = !!cached && cached.modelName !== modelName;
+    const existingEmbeddings = (!modelChanged && cached?.embeddings) ? cached.embeddings : {};
+    const existingHashes = (!modelChanged && cached?.entryHashes) ? cached.entryHashes : {};
+    // Determine which entries need (re)computation.
+    const currentIds = new Set(instructions.map(i => i.id));
+    const toCompute = instructions.filter(inst => {
+        const cachedHash = existingHashes[inst.id];
+        return !cachedHash || cachedHash !== inst.sourceHash || !existingEmbeddings[inst.id];
+    });
+    const reuseCount = instructions.length - toCompute.length;
+    const missReason = !cached ? 'no cache'
+        : modelChanged ? `model changed (${cached.modelName} -> ${modelName})`
+            : toCompute.length === instructions.length ? 'index stale (no hashes to reuse)'
+                : `incremental (${toCompute.length} new/changed, ${reuseCount} reused)`;
+    (0, logger_1.logInfo)(`[embeddingService] Embedding cache MISS (${missReason}). Computing embeddings for ${toCompute.length}/${instructions.length} instructions`);
+    indexEmbeddingComputing = (async () => {
+        try {
+            const embeddings = { ...existingEmbeddings };
+            const entryHashes = { ...existingHashes };
+            for (const inst of toCompute) {
+                const text = `${inst.title} ${inst.semanticSummary || inst.body}`;
+                embeddings[inst.id] = Array.from(await embedFn(text, modelName, cacheDir, device, localOnly));
+                if (inst.sourceHash)
+                    entryHashes[inst.id] = inst.sourceHash;
+            }
+            // Prune deleted instructions from cache.
+            for (const id of Object.keys(embeddings)) {
+                if (!currentIds.has(id)) {
+                    delete embeddings[id];
+                    delete entryHashes[id];
+                }
+            }
+            // Persist updated cache.
+            try {
+                saveCachedEmbeddings(embeddingPath, { indexHash, modelName, entryHashes, embeddings });
+                (0, logger_1.logInfo)('[embeddingService] Embeddings cached to disk');
+            }
+            catch (err) {
+                (0, logger_1.logWarn)(`[embeddingService] Failed to cache embeddings: ${err instanceof Error ? err.message : 'unknown'}`);
+            }
+            // Return as Float32Arrays.
+            const result = {};
+            for (const [id, vec] of Object.entries(embeddings)) {
+                result[id] = new Float32Array(vec);
+            }
+            return result;
+        }
+        finally {
+            indexEmbeddingComputing = null;
+        }
+    })();
+    return await indexEmbeddingComputing;
+}

package/dist/services/errors.d.ts

@@ -0,0 +1,22 @@
+export interface SemanticRpcErrorShape<TData extends Record<string, unknown> | undefined = Record<string, unknown>> {
+    code: number;
+    message: string;
+    data: TData;
+    __semantic: true;
+}
+/**
+ * Throw a structured JSON-RPC-compatible semantic error object.
+ * The thrown value is a plain object (not an Error instance) so that downstream
+ * serialization layers can pass it through without losing custom properties.
+ * @param code - JSON-RPC error code (e.g. -32602 for invalid params)
+ * @param message - Human-readable error message
+ * @param data - Optional additional data attached to the error
+ * @throws Always throws the constructed {@link SemanticRpcErrorShape}
+ */
+export declare function semanticError<TData extends Record<string, unknown> | undefined = Record<string, unknown>>(code: number, message: string, data?: TData): never;
+/**
+ * Type-guard that tests whether an unknown value is a semantic RPC error object.
+ * @param e - Value to inspect
+ * @returns `true` if `e` is a {@link SemanticRpcErrorShape}, `false` otherwise
+ */
+export declare function isSemanticError(e: unknown): e is SemanticRpcErrorShape<Record<string, unknown>>;

package/dist/services/errors.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.semanticError = semanticError;
+exports.isSemanticError = isSemanticError;
+/**
+ * Throw a structured JSON-RPC-compatible semantic error object.
+ * The thrown value is a plain object (not an Error instance) so that downstream
+ * serialization layers can pass it through without losing custom properties.
+ * @param code - JSON-RPC error code (e.g. -32602 for invalid params)
+ * @param message - Human-readable error message
+ * @param data - Optional additional data attached to the error
+ * @throws Always throws the constructed {@link SemanticRpcErrorShape}
+ */
+function semanticError(code, message, data) {
+    const err = { code, message, data: (data === undefined ? {} : data), __semantic: true };
+    // Throw plain object so downstream passes through as-is.
+    // (Stack trace not required for semantic validation errors.)
+    // eslint-disable-next-line no-throw-literal
+    throw err;
+}
+/**
+ * Type-guard that tests whether an unknown value is a semantic RPC error object.
+ * @param e - Value to inspect
+ * @returns `true` if `e` is a {@link SemanticRpcErrorShape}, `false` otherwise
+ */
+function isSemanticError(e) {
+    if (!e || typeof e !== 'object')
+        return false;
+    const maybe = e;
+    return maybe.__semantic === true && Number.isSafeInteger(maybe.code) && typeof maybe.message === 'string';
+}

package/dist/services/featureFlags.d.ts

@@ -0,0 +1,25 @@
+export type FeatureFlag = 'response_envelope_v1' | 'tools_extended' | 'tools_admin';
+interface FlagConfig {
+    [k: string]: boolean;
+}
+/**
+ * Check whether a feature flag is currently enabled.
+ * @param flag - Feature flag name to evaluate
+ * @returns `true` if the flag is enabled, `false` otherwise
+ */
+export declare function flagEnabled(flag: FeatureFlag): boolean;
+/** Return a shallow copy of the current flag configuration map.
+ * @returns Object mapping flag names to their boolean values
+ */
+export declare function dumpFlags(): {
+    [k: string]: boolean;
+};
+/**
+ * Replace the in-memory flag cache and persist the new values to the flags file.
+ * @param newFlags - Complete flag configuration to apply
+ * @returns Shallow copy of the resulting flag configuration after the update
+ */
+export declare function updateFlags(newFlags: FlagConfig): {
+    [k: string]: boolean;
+};
+export {};

package/dist/services/featureFlags.js

@@ -0,0 +1,89 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flagEnabled = flagEnabled;
+exports.dumpFlags = dumpFlags;
+exports.updateFlags = updateFlags;
+// Simple feature flag loader: environment variables + optional JSON file.
+// Precedence: explicit env var (INDEX_SERVER_FLAG_<UPPER>) > JSON file > default (false)
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const runtimeConfig_1 = require("../config/runtimeConfig");
+let cache = null;
+let lastFilePath = null;
+let lastConfigIdentity = null;
+function ensureConfigSync() {
+    const cfg = (0, runtimeConfig_1.getRuntimeConfig)();
+    if (lastConfigIdentity !== cfg) {
+        cache = null;
+        lastFilePath = null;
+        lastConfigIdentity = cfg;
+    }
+    return cfg;
+}
+function loadFile() {
+    const cfg = ensureConfigSync();
+    const file = cfg.featureFlags.file || path_1.default.join(process.cwd(), 'flags.json');
+    lastFilePath = file;
+    if (!fs_1.default.existsSync(file))
+        return {};
+    try {
+        const raw = JSON.parse(fs_1.default.readFileSync(file, 'utf8'));
+        if (raw && typeof raw === 'object') {
+            const out = {};
+            for (const [k, v] of Object.entries(raw)) {
+                if (typeof v === 'boolean')
+                    out[k] = v;
+            }
+            return out;
+        }
+    }
+    catch { /* ignore */ }
+    return {};
+}
+function load() {
+    const cfg = ensureConfigSync();
+    if (cache)
+        return cache;
+    const base = loadFile();
+    // Overlay env-derived namespace captured in runtime config
+    for (const [flagName, rawValue] of Object.entries(cfg.featureFlags.envNamespace)) {
+        const v = String(rawValue).toLowerCase();
+        if (['1', 'true', 'yes', 'on', 'enabled'].includes(v))
+            base[flagName] = true;
+        else if (['0', 'false', 'no', 'off', 'disabled'].includes(v))
+            base[flagName] = false;
+    }
+    cache = base;
+    return cache;
+}
+/**
+ * Check whether a feature flag is currently enabled.
+ * @param flag - Feature flag name to evaluate
+ * @returns `true` if the flag is enabled, `false` otherwise
+ */
+function flagEnabled(flag) {
+    const cfg = load();
+    return !!cfg[flag];
+}
+/** Return a shallow copy of the current flag configuration map.
+ * @returns Object mapping flag names to their boolean values
+ */
+function dumpFlags() { return { ...load() }; }
+/**
+ * Replace the in-memory flag cache and persist the new values to the flags file.
+ * @param newFlags - Complete flag configuration to apply
+ * @returns Shallow copy of the resulting flag configuration after the update
+ */
+function updateFlags(newFlags) {
+    cache = { ...newFlags };
+    try {
+        const cfg = ensureConfigSync();
+        const file = lastFilePath || cfg.featureFlags.file || path_1.default.join(process.cwd(), 'flags.json');
+        fs_1.default.writeFileSync(file, JSON.stringify(cache, null, 2));
+    }
+    catch { /* ignore write errors */ }
+    return dumpFlags();
+}

package/dist/services/features.d.ts

@@ -0,0 +1,13 @@
+export declare function hasFeature(name: string): boolean;
+export declare function incrementCounter(name: string, by?: number): void;
+export declare function getCounters(): {
+    [x: string]: number;
+};
+export declare function featureStatus(): {
+    features: string[];
+    counters: {
+        [x: string]: number;
+    };
+    env: string[];
+};
+export declare function enableFeature(name: string): void;