@jagilber-org/index-server 1.27.0 → 1.28.0

package/dist/dashboard/server/routes/instructions.routes.js

@@ -16,16 +16,125 @@ const registry_js_1 = require("../../../server/registry.js");
 const indexContext_js_1 = require("../../../services/indexContext.js");
 const adminAuth_js_1 = require("./adminAuth.js");
 const handlers_search_js_1 = require("../../../services/handlers.search.js");
+const schemaVersion_js_1 = require("../../../versioning/schemaVersion.js");
+const runtimeConfig_js_1 = require("../../../config/runtimeConfig.js");
 const instructionRecordValidation_js_1 = require("../../../services/instructionRecordValidation.js");
 const logger_js_1 = require("../../../services/logger.js");
 const pathContainment_js_1 = require("../utils/pathContainment.js");
-/** Sanitize an instruction name with defense-in-depth path-traversal guard. */
+/** Validate an instruction name with a defense-in-depth path-containment guard. */
 function safeName(name) {
-    const sanitized = String(name).replace(/[^a-zA-Z0-9-_]/g, '-');
+    const sanitized = String(name);
+    const validationErrors = (0, instructionRecordValidation_js_1.validateInstructionIdSurface)(sanitized);
+    if (validationErrors.length) {
+        throw new instructionRecordValidation_js_1.InstructionValidationError(validationErrors);
+    }
     const base = (0, indexContext_js_1.getInstructionsDir)();
     (0, pathContainment_js_1.validatePathContainment)(node_path_1.default.resolve(base, `${sanitized}.json`), base);
     return sanitized;
 }
+function requireInstructionContentObject(content) {
+    if (!content || typeof content !== 'object' || Array.isArray(content)) {
+        throw new instructionRecordValidation_js_1.InstructionValidationError(['/content: must be an object']);
+    }
+    return content;
+}
+function assertValidDashboardInstructionEnums(content) {
+    const validationErrors = (0, instructionRecordValidation_js_1.validateInstructionInputEnumMembership)(content);
+    if (validationErrors.length) {
+        throw new instructionRecordValidation_js_1.InstructionValidationError(validationErrors);
+    }
+}
+function assertValidDashboardInstructionShape(content) {
+    const validationErrors = [];
+    for (const [key, value] of Object.entries(content)) {
+        if (value === null)
+            validationErrors.push(`/${key}: null is not allowed`);
+    }
+    if (content.title !== undefined && typeof content.title !== 'string') {
+        validationErrors.push(`/title: must be a string, received ${typeof content.title}`);
+    }
+    if (content.body !== undefined && typeof content.body !== 'string') {
+        validationErrors.push(`/body: must be a string, received ${typeof content.body}`);
+    }
+    if (content.audience !== undefined && typeof content.audience !== 'string') {
+        validationErrors.push(`/audience: must be a string, received ${typeof content.audience}`);
+    }
+    if (content.requirement !== undefined && typeof content.requirement !== 'string') {
+        validationErrors.push(`/requirement: must be a string, received ${typeof content.requirement}`);
+    }
+    if (content.contentType !== undefined && typeof content.contentType !== 'string') {
+        validationErrors.push(`/contentType: must be a string, received ${typeof content.contentType}`);
+    }
+    if (content.priority !== undefined && typeof content.priority !== 'number') {
+        validationErrors.push(`/priority: must be a number, received ${typeof content.priority}`);
+    }
+    else if (typeof content.priority === 'number' && (!Number.isInteger(content.priority) || content.priority < 1 || content.priority > 100)) {
+        validationErrors.push('/priority: must be an integer from 1 to 100');
+    }
+    if (content.categories !== undefined && !Array.isArray(content.categories)) {
+        validationErrors.push(`/categories: must be an array of strings, received ${typeof content.categories}`);
+    }
+    else if (Array.isArray(content.categories)) {
+        for (const [index, category] of content.categories.entries()) {
+            if (typeof category !== 'string') {
+                validationErrors.push(`/categories/${index}: must be a string, received ${typeof category}`);
+            }
+            else if (!/^[a-z0-9][a-z0-9-_]{0,48}$/.test(category.toLowerCase())) {
+                validationErrors.push(`/categories/${index}: must match /^[a-z0-9][a-z0-9-_]{0,48}$/`);
+            }
+        }
+    }
+    if (validationErrors.length) {
+        throw new instructionRecordValidation_js_1.InstructionValidationError(validationErrors);
+    }
+}
+function assertDashboardBodyWithinLimit(content) {
+    if (typeof content.body !== 'string')
+        return;
+    const bodyLength = content.body.trim().length;
+    const { bodyWarnLength } = (0, runtimeConfig_js_1.getRuntimeConfig)().index;
+    if (bodyLength > bodyWarnLength) {
+        throw new instructionRecordValidation_js_1.InstructionValidationError([`/body: exceeds the ${bodyWarnLength}-character limit (${bodyLength} chars)`]);
+    }
+}
+function validationErrorResponse(res, error) {
+    return res.status(400).json({ success: false, error: 'invalid_instruction', validationErrors: error.validationErrors });
+}
+function dashboardAudience(value) {
+    switch (value) {
+        case 'individual':
+        case 'group':
+        case 'all':
+            return value;
+        default:
+            return 'all';
+    }
+}
+function dashboardRequirement(value) {
+    switch (value) {
+        case 'mandatory':
+        case 'critical':
+        case 'recommended':
+        case 'optional':
+        case 'deprecated':
+            return value;
+        default:
+            return 'optional';
+    }
+}
+function dashboardContentType(value) {
+    switch (value) {
+        case 'template':
+        case 'workflow':
+        case 'reference':
+        case 'example':
+        case 'agent':
+        case 'instruction':
+            return value;
+        default:
+            return 'instruction';
+    }
+}
 function createInstructionsRoutes() {
     const router = (0, express_1.Router)();
     const buildSnippet = (parts, query) => {
@@ -176,6 +285,9 @@ function createInstructionsRoutes() {
             res.json({ success: true, content: entry, timestamp: Date.now() });
         }
         catch (error) {
+            if ((0, instructionRecordValidation_js_1.isInstructionValidationError)(error)) {
+                return validationErrorResponse(res, error);
+            }
             (0, logger_js_1.logError)('[API] Failed to load instruction:', error);
             res.status(500).json({ success: false, error: 'Failed to load instruction' });
         }
@@ -193,20 +305,28 @@ function createInstructionsRoutes() {
             const st = res.locals.indexState;
             if (st.byId.has(id))
                 return res.status(409).json({ success: false, error: 'Instruction already exists' });
-            const contentObj = typeof content === 'object' && content !== null ? content : {}; // lgtm[js/comparison-between-incompatible-types] — idiomatic typeof-object plus null check (typeof null === 'object' in JS)
+            const contentObj = requireInstructionContentObject(content);
+            assertValidDashboardInstructionEnums(contentObj);
+            assertValidDashboardInstructionShape(contentObj);
+            assertDashboardBodyWithinLimit(contentObj);
             const entry = {
                 ...contentObj,
                 id,
-                title: contentObj.title || id,
-                body: contentObj.body || (typeof content === 'string' ? content : ''),
-                categories: Array.isArray(contentObj.categories) ? contentObj.categories : [],
+                title: typeof contentObj.title === 'string' ? contentObj.title : id,
+                body: typeof contentObj.body === 'string' ? contentObj.body : '',
+                categories: Array.isArray(contentObj.categories)
+                    ? contentObj.categories.filter((category) => typeof category === 'string')
+                    : [],
                 priority: typeof contentObj.priority === 'number' ? contentObj.priority : 50,
-                audience: contentObj.audience || 'all',
-                requirement: contentObj.requirement || 'optional',
+                audience: dashboardAudience(contentObj.audience),
+                requirement: dashboardRequirement(contentObj.requirement),
+                contentType: dashboardContentType(contentObj.contentType),
+                sourceHash: typeof contentObj.sourceHash === 'string' ? contentObj.sourceHash : '',
+                schemaVersion: typeof contentObj.schemaVersion === 'string' ? contentObj.schemaVersion : schemaVersion_js_1.SCHEMA_VERSION,
                 createdAt: new Date().toISOString(),
                 updatedAt: new Date().toISOString(),
             };
-            await (0, indexContext_js_1.writeEntryAsync)(entry); // lgtm[js/http-to-file-access] — writes to config-controlled instructions directory
+            await (0, indexContext_js_1.writeEntryAsync)(entry, { createOnly: true }); // lgtm[js/http-to-file-access] — writes to config-controlled instructions directory
             (0, indexContext_js_1.touchIndexVersion)();
             (0, indexContext_js_1.invalidate)();
             const reloaded = await (0, indexContext_js_1.ensureLoadedAsync)();
@@ -219,7 +339,10 @@ function createInstructionsRoutes() {
         }
         catch (error) {
             if ((0, instructionRecordValidation_js_1.isInstructionValidationError)(error)) {
-                return res.status(400).json({ success: false, error: 'invalid_instruction', validationErrors: error.validationErrors });
+                return validationErrorResponse(res, error);
+            }
+            if ((0, indexContext_js_1.isDuplicateInstructionWriteError)(error)) {
+                return res.status(409).json({ success: false, error: 'Instruction already exists' });
             }
             (0, logger_js_1.logError)('[API] Failed to create instruction:', error);
             res.status(500).json({ success: false, error: 'Failed to create instruction' });
@@ -234,13 +357,17 @@ function createInstructionsRoutes() {
             const id = safeName(req.params.name);
             if (!content)
                 return res.status(400).json({ success: false, error: 'Missing content' });
+            const contentObj = requireInstructionContentObject(content);
+            assertValidDashboardInstructionEnums(contentObj);
+            assertValidDashboardInstructionShape(contentObj);
+            assertDashboardBodyWithinLimit(contentObj);
             const st = res.locals.indexState;
             const existing = st.byId.get(id);
             if (!existing)
                 return res.status(404).json({ success: false, error: 'Not found' });
             const updated = {
                 ...existing,
-                ...(typeof content === 'object' && content !== null ? content : {}), // lgtm[js/comparison-between-incompatible-types] — idiomatic typeof-object plus null check (typeof null === 'object' in JS)
+                ...contentObj,
                 id, // preserve id
                 updatedAt: new Date().toISOString(),
             };
@@ -257,7 +384,7 @@ function createInstructionsRoutes() {
         }
         catch (error) {
             if ((0, instructionRecordValidation_js_1.isInstructionValidationError)(error)) {
-                return res.status(400).json({ success: false, error: 'invalid_instruction', validationErrors: error.validationErrors });
+                return validationErrorResponse(res, error);
             }
             (0, logger_js_1.logError)('[API] Failed to update instruction:', error);
             res.status(500).json({ success: false, error: 'Failed to update instruction' });
@@ -279,6 +406,9 @@ function createInstructionsRoutes() {
             res.json({ success: true, message: 'Instruction deleted', timestamp: Date.now() });
         }
         catch (error) {
+            if ((0, instructionRecordValidation_js_1.isInstructionValidationError)(error)) {
+                return validationErrorResponse(res, error);
+            }
             (0, logger_js_1.logError)('[API] Failed to delete instruction:', error);
             res.status(500).json({ success: false, error: 'Failed to delete instruction' });
         }

package/dist/dashboard/server/routes/scripts.routes.js

@@ -57,7 +57,7 @@ function createScriptsRoutes() {
             return;
         }
         try {
-            const scriptsDir = path_1.default.join(process.cwd(), 'scripts');
+            const scriptsDir = path_1.default.join(process.cwd(), 'scripts', 'dist');
             const filePath = path_1.default.join(scriptsDir, meta.file); // nosemgrep: javascript.express.security.audit.express-path-join-resolve-traversal.express-path-join-resolve-traversal -- path validated below via startsWith check
             let resolved;
             try {

package/dist/dashboard/server/routes/sqlite.routes.js

@@ -566,5 +566,79 @@ function createSqliteRoutes() {
             return res.status(code).json({ success: false, error: err.message });
         }
     });
+    // ── Validation ────────────────────────────────────────────────────────
+    /** GET /sqlite/validate — Comprehensive database validation (read-only) */
+    router.get('/sqlite/validate', adminAuth_js_1.dashboardAdminAuth, (_req, res) => {
+        try {
+            assertSqliteActive();
+            const sqlitePath = getSqlitePath();
+            const db = new node_sqlite_1.DatabaseSync(sqlitePath, { readOnly: true });
+            const checks = [];
+            try {
+                // 1. Integrity check
+                const intRows = db.prepare('PRAGMA integrity_check').all();
+                const intOk = intRows.length === 1 && intRows[0].integrity_check === 'ok';
+                checks.push({ name: 'integrity_check', pass: intOk, detail: intOk ? 'ok' : JSON.stringify(intRows) });
+                // 2. Table counts
+                const instrCount = db.prepare('SELECT COUNT(*) as cnt FROM instructions').get()?.cnt ?? 0;
+                checks.push({ name: 'instructions_exist', pass: instrCount >= 0, detail: `count=${instrCount}` });
+                // 3. FTS5 sync
+                let ftsCount = -1;
+                try {
+                    ftsCount = db.prepare('SELECT COUNT(*) as cnt FROM instructions_fts').get()?.cnt ?? -1;
+                    checks.push({ name: 'fts5_sync', pass: ftsCount === instrCount, detail: `instructions=${instrCount}, fts=${ftsCount}` });
+                }
+                catch {
+                    checks.push({ name: 'fts5_sync', pass: false, detail: 'FTS5 table not accessible' });
+                }
+                // 4. Orphaned usage records
+                try {
+                    const orphanUsage = db.prepare('SELECT COUNT(*) as cnt FROM usage WHERE instruction_id NOT IN (SELECT id FROM instructions)').get()?.cnt ?? 0;
+                    checks.push({ name: 'usage_no_orphans', pass: orphanUsage === 0, detail: `orphans=${orphanUsage}` });
+                }
+                catch {
+                    checks.push({ name: 'usage_no_orphans', pass: true, detail: 'usage table not present (ok)' });
+                }
+                // 5. Embedding consistency
+                try {
+                    const embCount = db.prepare('SELECT COUNT(*) as cnt FROM embeddings').get()?.cnt ?? 0;
+                    const embMetaCount = db.prepare('SELECT COUNT(*) as cnt FROM embedding_meta').get()?.cnt ?? 0;
+                    checks.push({ name: 'embedding_meta_sync', pass: embCount === embMetaCount, detail: `embeddings=${embCount}, meta=${embMetaCount}` });
+                    const orphanEmb = db.prepare('SELECT COUNT(*) as cnt FROM embedding_meta WHERE instruction_id NOT IN (SELECT id FROM instructions)').get()?.cnt ?? 0;
+                    checks.push({ name: 'embedding_no_orphans', pass: orphanEmb === 0, detail: `orphans=${orphanEmb}` });
+                }
+                catch {
+                    checks.push({ name: 'embedding_meta_sync', pass: true, detail: 'embedding tables not present (ok)' });
+                }
+                // 6. NULL required fields
+                const nullIds = db.prepare("SELECT COUNT(*) as cnt FROM instructions WHERE id IS NULL OR id = ''").get()?.cnt ?? 0;
+                checks.push({ name: 'no_null_ids', pass: nullIds === 0, detail: `count=${nullIds}` });
+                const nullTitles = db.prepare("SELECT COUNT(*) as cnt FROM instructions WHERE title IS NULL OR title = ''").get()?.cnt ?? 0;
+                checks.push({ name: 'no_null_titles', pass: nullTitles === 0, detail: `count=${nullTitles}` });
+                const nullBodies = db.prepare("SELECT COUNT(*) as cnt FROM instructions WHERE body IS NULL OR body = ''").get()?.cnt ?? 0;
+                checks.push({ name: 'no_null_bodies', pass: nullBodies === 0, detail: `count=${nullBodies}` });
+                // 7. WAL mode
+                const jm = db.prepare('PRAGMA journal_mode').get();
+                const isWal = jm?.journal_mode === 'wal';
+                checks.push({ name: 'wal_mode', pass: isWal, detail: `journal_mode=${jm?.journal_mode ?? 'unknown'}` });
+                const allPass = checks.every(c => c.pass);
+                return res.json({
+                    success: true,
+                    valid: allPass,
+                    totalChecks: checks.length,
+                    passed: checks.filter(c => c.pass).length,
+                    failed: checks.filter(c => !c.pass).length,
+                    checks,
+                });
+            }
+            finally {
+                db.close();
+            }
+        }
+        catch (err) {
+            const code = err.statusCode ?? 500;
+            return res.status(code).json({ success: false, error: err.message });
+        }
+    });
     return router;
 }

package/dist/models/instruction.d.ts

@@ -1,6 +1,6 @@
 export type AudienceScope = 'individual' | 'group' | 'all';
 export type RequirementLevel = 'mandatory' | 'critical' | 'recommended' | 'optional' | 'deprecated';
-export type ContentType = 'instruction' | 'template' | 'chat-session' | 'reference' | 'example' | 'agent';
+export type ContentType = 'instruction' | 'template' | 'workflow' | 'reference' | 'example' | 'agent';
 export interface InstructionEntry {
     id: string;
     title: string;

package/dist/schemas/index.d.ts

@@ -98,7 +98,7 @@ export declare const instructionEntry: {
             };
         };
         readonly contentType: {
-            readonly enum: readonly ["instruction", "template", "chat-session", "reference", "example", "agent"];
+            readonly enum: readonly ["instruction", "template", "workflow", "reference", "example", "agent"];
         };
         readonly version: {
             readonly type: "string";

package/dist/schemas/index.js

@@ -44,7 +44,7 @@ exports.instructionEntry = {
         workspaceId: { type: 'string' },
         userId: { type: 'string' },
         teamIds: { type: 'array', items: { type: 'string' } },
-        contentType: { enum: ['instruction', 'template', 'chat-session', 'reference', 'example', 'agent'] },
+        contentType: { enum: ['instruction', 'template', 'workflow', 'reference', 'example', 'agent'] },
         version: { type: 'string' },
         status: { enum: ['draft', 'review', 'approved', 'deprecated'] },
         owner: { type: 'string' },

package/dist/server/sdkServer.js

@@ -21,6 +21,7 @@ const registry_1 = require("./registry");
 const zod_1 = require("zod");
 const runtimeConfig_1 = require("../config/runtimeConfig");
 const mcpLogBridge_1 = require("../services/mcpLogBridge");
+const logger_1 = require("../services/logger");
 const handshakeManager_1 = require("./handshakeManager");
 const transportFactory_1 = require("./transportFactory");
 const mcpReadOnlySurfaces_1 = require("./mcpReadOnlySurfaces");
@@ -205,6 +206,8 @@ function createSdkServer(ServerClass) {
         const args = p.arguments || {};
         if (name === 'health_check')
             (0, handshakeManager_1.record)('tools_call_health');
+        const __callStart = Date.now();
+        (0, logger_1.logInfo)('[rpc] tools/call', { tool: name, id: req?.id ?? null });
         try {
             if ((0, runtimeConfig_1.getRuntimeConfig)().logging.verbose)
                 process.stderr.write(`[rpc] call method=tools/call tool=${name} id=${req?.id ?? 'n/a'}\n`);
@@ -216,9 +219,11 @@ function createSdkServer(ServerClass) {
         }
         try {
             const result = await Promise.resolve(handler(args));
+            const bytes = Buffer.byteLength(JSON.stringify(result), 'utf8');
+            (0, logger_1.logInfo)('[rpc] tools/call ok', { tool: name, ms: Date.now() - __callStart, bytes });
             try {
                 if ((0, runtimeConfig_1.getRuntimeConfig)().logging.verbose)
-                    process.stderr.write(`[rpc] tool_result tool=${name} bytes=${Buffer.byteLength(JSON.stringify(result), 'utf8')}\n`);
+                    process.stderr.write(`[rpc] tool_result tool=${name} bytes=${bytes}\n`);
             }
             catch { /* ignore */ }
             return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
@@ -226,7 +231,10 @@ function createSdkServer(ServerClass) {
         catch (e) {
             const code = e?.code;
             const sem = e?.__semantic === true;
+            const msgRaw = e instanceof Error ? e.message : String(e);
+            const stack = e instanceof Error ? e.stack : undefined;
             if (Number.isSafeInteger(code)) {
+                (0, logger_1.logError)('[rpc] tools/call error', { tool: name, ms: Date.now() - __callStart, code, semantic: sem, message: msgRaw, stack });
                 try {
                     if ((0, runtimeConfig_1.getRuntimeConfig)().logging.verbose)
                         process.stderr.write(`[rpc] tool_error_passthru tool=${name} code=${code} semantic=${sem ? '1' : '0'} msg=${e?.message || ''}\n`);
@@ -234,13 +242,13 @@ function createSdkServer(ServerClass) {
                 catch { /* ignore */ }
                 throw e;
             }
-            const msg = e instanceof Error ? e.message : String(e);
+            (0, logger_1.logError)('[rpc] tools/call error', { tool: name, ms: Date.now() - __callStart, code: code ?? null, message: msgRaw, stack });
             try {
                 if ((0, runtimeConfig_1.getRuntimeConfig)().logging.verbose)
-                    process.stderr.write(`[rpc] tool_error_wrap tool=${name} msg=${msg.replace(/\s+/g, ' ')} code=${code ?? 'n/a'}\n`);
+                    process.stderr.write(`[rpc] tool_error_wrap tool=${name} msg=${msgRaw.replace(/\s+/g, ' ')} code=${code ?? 'n/a'}\n`);
             }
             catch { /* ignore */ }
-            throw { code: -32603, message: 'Tool execution failed', data: { message: msg, method: name } };
+            throw { code: -32603, message: 'Tool execution failed', data: { message: msgRaw, method: name } };
         }
     });
     // Lightweight ping handler (simple reachability / latency measurement)

package/dist/services/auditLog.d.ts

@@ -4,7 +4,7 @@ export declare function runWithCorrelation<T>(correlationId: string, fn: () => T
 export declare function getCurrentCorrelationId(): string | undefined;
 /** Reset the cached audit log path, forcing re-resolution on next write. */
 export declare function resetAuditLogCache(): void;
-export type AuditKind = 'mutation' | 'read' | 'http';
+export type AuditKind = 'mutation' | 'read' | 'http' | 'feedback';
 export interface AuditEntry {
     ts: string;
     kind: AuditKind;

package/dist/services/auditLog.js

@@ -19,7 +19,7 @@ const logger_1 = require("./logger");
 const toolRegistry_1 = require("./toolRegistry");
 // Append-only JSONL audit log for all server operations.
 // Each line: { ts, kind, action, ids?, meta? }
-// kind: 'mutation' | 'read' | 'http' — classifies the entry type.
+// kind: 'mutation' | 'read' | 'http' | 'feedback' — classifies the entry type.
 // Path and enablement are driven by runtime configuration (instructions.auditLog).
 // AsyncLocalStorage carries the correlation ID from registry wrapper into handler scope.
 // This lets logAudit() calls inside handlers automatically include correlationId

package/dist/services/embeddingService.d.ts

@@ -58,6 +58,8 @@ export declare function embedText(text: string, modelName: string, cacheDir: str
  */
 export declare function checkModelReadiness(modelName: string, cacheDir: string, localOnly: boolean): {
     ready: boolean;
+    cached: boolean;
+    modelPath: string;
     message?: string;
 };
 /** Signature for the embed function (injectable for testing). */

package/dist/services/embeddingService.js

@@ -187,22 +187,34 @@ async function embedText(text, modelName, cacheDir, device = 'cpu', localOnly =
  * @returns Object with `ready` flag and optional remediation `message`.
  */
 function checkModelReadiness(modelName, cacheDir, localOnly) {
-    if (!localOnly) {
-        return { ready: true }; // Model can be downloaded on demand
-    }
     // HuggingFace transformers caches models as: models--<org>--<name>
     const modelDirName = `models--${modelName.replace(/\//g, '--')}`;
     const modelPath = path_1.default.join(cacheDir, modelDirName);
+    let cached = false;
     try {
         if (fs_1.default.existsSync(modelPath) && fs_1.default.readdirSync(modelPath).length > 0) {
-            return { ready: true };
+            cached = true;
         }
     }
     catch {
         // Directory doesn't exist or can't be read
     }
+    if (cached) {
+        return { ready: true, cached: true, modelPath };
+    }
+    if (!localOnly) {
+        return {
+            ready: true,
+            cached: false,
+            modelPath,
+            message: `Embedding model '${modelName}' is not yet cached. ` +
+                `It will be downloaded to '${cacheDir}' on first compute (~25 MB).`,
+        };
+    }
     return {
         ready: false,
+        cached: false,
+        modelPath,
         message: `Embedding model '${modelName}' not found in cache (${cacheDir}). ` +
             `LOCAL_ONLY is enabled, so the model cannot be downloaded automatically. ` +
             `To fix: set INDEX_SERVER_SEMANTIC_LOCAL_ONLY=0 to allow download, ` +

package/dist/services/embeddingTrigger.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Auto-compute embeddings after operations that mutate the loaded instruction set
+ * (zip import, restore, bulk migrations).
+ *
+ * Behaviour:
+ *  - No-op when semantic is disabled (`INDEX_SERVER_SEMANTIC_ENABLED` falsy).
+ *  - No-op when explicitly opted out via `INDEX_SERVER_AUTO_EMBED_ON_IMPORT=0`.
+ *  - Runs asynchronously (fire-and-forget) so the caller's request returns promptly.
+ *  - Coalesces concurrent triggers via the existing in-flight lock inside
+ *    `getInstructionEmbeddings`.
+ *
+ * Logs success / failure at INFO / WARN so events surface in the events panel
+ * (constitution OB-3, OB-5).
+ */
+/** Whether auto-compute is enabled given current env / runtime config. */
+export declare function autoEmbedEnabled(): boolean;
+/**
+ * Trigger an embedding compute pass after an import / restore.
+ *
+ * @param reason - Free-form context (e.g. `import-zip`, `restore`) used in logs.
+ * @returns Promise resolving when compute finishes (or immediately if skipped).
+ */
+export declare function triggerEmbeddingComputeAfterImport(reason: string): Promise<{
+    triggered: boolean;
+    reason?: string;
+    entries?: number;
+    ms?: number;
+}>;
+/**
+ * Fire-and-forget variant — schedules the compute on the next tick and returns immediately.
+ * Use this from request handlers so HTTP responses are not blocked on model warm-up.
+ */
+export declare function scheduleEmbeddingComputeAfterImport(reason: string): void;

package/dist/services/embeddingTrigger.js

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * Auto-compute embeddings after operations that mutate the loaded instruction set
+ * (zip import, restore, bulk migrations).
+ *
+ * Behaviour:
+ *  - No-op when semantic is disabled (`INDEX_SERVER_SEMANTIC_ENABLED` falsy).
+ *  - No-op when explicitly opted out via `INDEX_SERVER_AUTO_EMBED_ON_IMPORT=0`.
+ *  - Runs asynchronously (fire-and-forget) so the caller's request returns promptly.
+ *  - Coalesces concurrent triggers via the existing in-flight lock inside
+ *    `getInstructionEmbeddings`.
+ *
+ * Logs success / failure at INFO / WARN so events surface in the events panel
+ * (constitution OB-3, OB-5).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.autoEmbedEnabled = autoEmbedEnabled;
+exports.triggerEmbeddingComputeAfterImport = triggerEmbeddingComputeAfterImport;
+exports.scheduleEmbeddingComputeAfterImport = scheduleEmbeddingComputeAfterImport;
+const runtimeConfig_1 = require("../config/runtimeConfig");
+const indexContext_1 = require("./indexContext");
+const embeddingService_1 = require("./embeddingService");
+const logger_1 = require("./logger");
+const envUtils_1 = require("../utils/envUtils");
+let lastTriggerAt = 0;
+/** Whether auto-compute is enabled given current env / runtime config. */
+function autoEmbedEnabled() {
+    const cfg = (0, runtimeConfig_1.getRuntimeConfig)();
+    if (!cfg.semantic.enabled)
+        return false;
+    const raw = process.env.INDEX_SERVER_AUTO_EMBED_ON_IMPORT;
+    // Default ON when semantic is enabled; explicit '0' / 'false' opts out.
+    if (raw === undefined)
+        return true;
+    return (0, envUtils_1.getBooleanEnv)('INDEX_SERVER_AUTO_EMBED_ON_IMPORT', true);
+}
+/**
+ * Trigger an embedding compute pass after an import / restore.
+ *
+ * @param reason - Free-form context (e.g. `import-zip`, `restore`) used in logs.
+ * @returns Promise resolving when compute finishes (or immediately if skipped).
+ */
+async function triggerEmbeddingComputeAfterImport(reason) {
+    if (!autoEmbedEnabled()) {
+        return { triggered: false, reason: 'auto-embed disabled or semantic disabled' };
+    }
+    // Light debounce — coalesce rapid back-to-back imports.
+    const now = Date.now();
+    if (now - lastTriggerAt < 1000) {
+        return { triggered: false, reason: 'debounced' };
+    }
+    lastTriggerAt = now;
+    const cfg = (0, runtimeConfig_1.getRuntimeConfig)();
+    const sem = cfg.semantic;
+    const start = Date.now();
+    try {
+        (0, indexContext_1.ensureLoaded)();
+        const state = (0, indexContext_1.getIndexState)();
+        if (!state.list || state.list.length === 0) {
+            (0, logger_1.logInfo)(`[embedding-trigger] Skipped (no instructions loaded) reason=${reason}`);
+            return { triggered: false, reason: 'no instructions loaded' };
+        }
+        (0, logger_1.logInfo)(`[embedding-trigger] Starting auto-compute reason=${reason} entries=${state.list.length}`);
+        await (0, embeddingService_1.getInstructionEmbeddings)(state.list, state.hash, sem.embeddingPath, sem.model, sem.cacheDir, sem.device, sem.localOnly);
+        const ms = Date.now() - start;
+        (0, logger_1.logInfo)(`[embedding-trigger] Auto-compute complete reason=${reason} entries=${state.list.length} ms=${ms}`);
+        return { triggered: true, entries: state.list.length, ms };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        // Use WARN (not ERROR) so we don't escalate transient model-load issues to ERROR-level paging.
+        (0, logger_1.logWarn)(`[embedding-trigger] Auto-compute failed reason=${reason}: ${msg}`);
+        return { triggered: false, reason: `failed: ${msg}` };
+    }
+}
+/**
+ * Fire-and-forget variant — schedules the compute on the next tick and returns immediately.
+ * Use this from request handlers so HTTP responses are not blocked on model warm-up.
+ */
+function scheduleEmbeddingComputeAfterImport(reason) {
+    if (!autoEmbedEnabled())
+        return;
+    setImmediate(() => {
+        triggerEmbeddingComputeAfterImport(reason).catch(() => { });
+    });
+}

package/dist/services/eventBuffer.d.ts

@@ -0,0 +1,45 @@
+/**
+ * In-process ring buffer of recent log events at WARN/ERROR severity.
+ *
+ * Surfaces operationally-meaningful events to the admin dashboard so operators
+ * do not have to tail server logs. Read-only, bounded; never persists to disk.
+ *
+ * Capacity defaults to 500. The logger emits records via `recordEvent()` only
+ * for WARN or ERROR levels so that volume on healthy systems is negligible.
+ *
+ * Constitution alignment: OB-1, OB-3, OB-4, OB-5 (structured, severity-visible).
+ */
+export type EventLevel = 'WARN' | 'ERROR';
+export interface BufferedEvent {
+    /** Monotonically increasing per-process id (used for unread counts). */
+    id: number;
+    /** ISO 8601 timestamp. */
+    ts: string;
+    /** Severity. */
+    level: EventLevel;
+    /** Message; prefix `[module]` is preserved. */
+    msg: string;
+    /** Optional stack/detail snippet. */
+    detail?: string;
+    /** Process id of emitter. */
+    pid?: number;
+}
+/** Emit a WARN/ERROR event into the buffer. Called by the logger. */
+export declare function recordEvent(level: EventLevel, msg: string, detail?: string, pid?: number): void;
+/** List recent events (most recent last). */
+export declare function listEvents(opts?: {
+    sinceId?: number;
+    level?: EventLevel;
+    limit?: number;
+}): BufferedEvent[];
+/** Compute new-event counts since the supplied id (used for the dashboard counter bubble). */
+export declare function eventCounts(sinceId?: number): {
+    warn: number;
+    error: number;
+    total: number;
+    latestId: number;
+};
+/** Clear the buffer (used by `Mark all read` and tests). */
+export declare function clearEvents(): void;
+/** Test-only helper. */
+export declare function _eventBufferSize(): number;