@jagilber-org/index-server 1.22.1 → 1.26.1

package/dist/services/instructionRecordValidation.d.ts

@@ -0,0 +1,39 @@
+import { InstructionEntry } from '../models/instruction';
+declare const INPUT_SCHEMA_REF = "index_add#input";
+export interface InstructionValidationResult {
+    record: InstructionEntry;
+    validationErrors: string[];
+    hints: string[];
+    schemaRef: string;
+}
+export declare class InstructionValidationError extends Error {
+    readonly validationErrors: string[];
+    readonly hints: string[];
+    readonly schemaRef: string;
+    readonly code = "invalid_instruction";
+    constructor(validationErrors: string[], hints?: string[], schemaRef?: string);
+}
+export declare const INSTRUCTION_ID_MAX_LENGTH = 120;
+export declare function validateInstructionInputSurface(entry: Record<string, unknown>): InstructionValidationResult;
+export declare function validateInstructionRecord(entry: InstructionEntry): InstructionValidationResult;
+export declare function assertValidInstructionRecord(entry: InstructionEntry): InstructionEntry;
+export declare function isInstructionValidationError(error: unknown): error is InstructionValidationError;
+export type LoadErrorCode = 'load_failed' | 'parse_failed' | 'unknown';
+export interface SanitizedLoadError {
+    code: LoadErrorCode;
+    detail: string;
+    raw: string;
+}
+/**
+ * Strip absolute paths, Node fs error codes, quoted path arguments, and
+ * stack traces from a free-form error message. Used to keep client-facing
+ * error responses free of filesystem layout or internal details.
+ */
+export declare function sanitizeErrorDetail(message: string): string;
+/**
+ * Convert an arbitrary error from the existing-entry load path into a
+ * client-safe shape. The `raw` field is preserved for internal audit logging
+ * only; never echo it directly to clients.
+ */
+export declare function sanitizeLoadError(err: unknown, kind?: LoadErrorCode): SanitizedLoadError;
+export { INPUT_SCHEMA_REF as INSTRUCTION_INPUT_SCHEMA_REF };

package/dist/services/instructionRecordValidation.js

@@ -0,0 +1,388 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INSTRUCTION_INPUT_SCHEMA_REF = exports.INSTRUCTION_ID_MAX_LENGTH = exports.InstructionValidationError = void 0;
+exports.validateInstructionInputSurface = validateInstructionInputSurface;
+exports.validateInstructionRecord = validateInstructionRecord;
+exports.assertValidInstructionRecord = assertValidInstructionRecord;
+exports.isInstructionValidationError = isInstructionValidationError;
+exports.sanitizeErrorDetail = sanitizeErrorDetail;
+exports.sanitizeLoadError = sanitizeLoadError;
+const ajv_1 = __importDefault(require("ajv"));
+const ajv_formats_1 = __importDefault(require("ajv-formats"));
+const json_schema_draft_07_json_1 = __importDefault(require("ajv/dist/refs/json-schema-draft-07.json"));
+const schemas_1 = require("../schemas");
+const classificationService_1 = require("./classificationService");
+const INPUT_SCHEMA_REF = 'index_add#input';
+exports.INSTRUCTION_INPUT_SCHEMA_REF = INPUT_SCHEMA_REF;
+const REQUIRED_RECORD_KEYS = new Set([
+    'id',
+    'title',
+    'body',
+    'priority',
+    'audience',
+    'requirement',
+    'categories',
+    'sourceHash',
+    'schemaVersion',
+    'createdAt',
+    'updatedAt',
+    'version',
+    'status',
+    'owner',
+    'priorityTier',
+    'classification',
+    'lastReviewedAt',
+    'nextReviewDue',
+    'changeLog',
+    'semanticSummary',
+]);
+const ALLOWED_INPUT_KEYS = new Set([
+    'id',
+    'title',
+    'body',
+    'rationale',
+    'priority',
+    'audience',
+    'requirement',
+    'categories',
+    'primaryCategory',
+    'deprecatedBy',
+    'riskScore',
+    'reviewIntervalDays',
+    'version',
+    'owner',
+    'status',
+    'priorityTier',
+    'classification',
+    'lastReviewedAt',
+    'nextReviewDue',
+    'changeLog',
+    'semanticSummary',
+    'contentType',
+    'extensions',
+    'supersedes',
+    'createdByAgent',
+    'sourceWorkspace',
+    'mode',
+    'lax',
+]);
+const ajv = new ajv_1.default({ allErrors: true, strict: false });
+(0, ajv_formats_1.default)(ajv);
+try {
+    if (!ajv.getSchema('https://json-schema.org/draft-07/schema')) {
+        ajv.addMetaSchema(json_schema_draft_07_json_1.default, 'https://json-schema.org/draft-07/schema');
+    }
+}
+catch {
+    // Non-fatal; loader uses the same best-effort registration pattern.
+}
+const validateInstructionSchema = ajv.compile(JSON.parse(JSON.stringify(schemas_1.instructionEntry)));
+class InstructionValidationError extends Error {
+    validationErrors;
+    hints;
+    schemaRef;
+    code = 'invalid_instruction';
+    constructor(validationErrors, hints = [], schemaRef = INPUT_SCHEMA_REF) {
+        super(`invalid_instruction: ${validationErrors.join('; ')}`);
+        this.validationErrors = validationErrors;
+        this.hints = hints;
+        this.schemaRef = schemaRef;
+        this.name = 'InstructionValidationError';
+    }
+}
+exports.InstructionValidationError = InstructionValidationError;
+function normalizePath(path) {
+    return path || '/';
+}
+function formatAjvError(error) {
+    const instancePath = normalizePath(error.instancePath);
+    if (error.keyword === 'additionalProperties') {
+        const prop = error.params.additionalProperty;
+        return `${instancePath}: unexpected property "${prop}"`;
+    }
+    if (error.keyword === 'required') {
+        const prop = error.params.missingProperty;
+        return `${instancePath}: missing required property "${prop}"`;
+    }
+    if (error.keyword === 'enum') {
+        const allowed = Array.isArray(error.params.allowedValues)
+            ? (error.params.allowedValues ?? []).join(', ')
+            : 'allowed enum values';
+        return `${instancePath}: must be one of ${allowed}`;
+    }
+    if (error.keyword === 'type') {
+        const expected = error.params.type ?? 'the expected type';
+        return `${instancePath}: must be ${expected}`;
+    }
+    if (error.keyword === 'minLength')
+        return `${instancePath}: must not be empty`;
+    if (error.keyword === 'maxLength')
+        return `${instancePath}: exceeds the allowed maximum length`;
+    if (error.keyword === 'minimum')
+        return `${instancePath}: must be greater than or equal to ${error.params.comparison ?? 'the minimum'}`;
+    if (error.keyword === 'maximum')
+        return `${instancePath}: must be less than or equal to ${error.params.comparison ?? 'the maximum'}`;
+    return `${instancePath}: ${error.message ?? 'failed validation'}`;
+}
+function dedupe(items) {
+    return Array.from(new Set(items));
+}
+function buildHints(validationErrors) {
+    const hints = [
+        'Instruction not added. Fix the listed validation errors and retry.',
+        'Use the returned inputSchema as the authoritative contract for index_add.',
+    ];
+    if (validationErrors.some((msg) => msg.includes('missing required property') || msg.includes('missing required field'))) {
+        hints.push('Provide all required fields for strict add/import calls, especially id, title, and body.');
+    }
+    if (validationErrors.some((msg) => msg.includes('must be one of') || msg.includes('invalid value'))) {
+        hints.push('Use documented enum values for fields like audience, requirement, status, priorityTier, classification, and contentType.');
+    }
+    if (validationErrors.some((msg) => msg.includes('unexpected property'))) {
+        hints.push('Remove unsupported properties instead of sending fields that are not part of the instruction schema.');
+    }
+    if (validationErrors.some((msg) => msg.includes('/extensions') || msg.includes('extensions'))) {
+        hints.push('extensions must be a JSON object whose values are strings, numbers, booleans, arrays, or nested objects; null is not allowed.');
+    }
+    if (validationErrors.some((msg) => msg.includes('null is not allowed'))) {
+        hints.push('Replace null values with a valid value or omit the optional field entirely.');
+    }
+    return dedupe(hints);
+}
+function stripUndefinedAndOptionalNulls(value, key, depth = 0) {
+    if (Array.isArray(value)) {
+        return value.map((item) => stripUndefinedAndOptionalNulls(item, undefined, depth + 1)).filter((item) => item !== undefined);
+    }
+    if (!value || typeof value !== 'object')
+        return value;
+    const out = {};
+    for (const [childKey, childValue] of Object.entries(value)) {
+        if (childValue === undefined)
+            continue;
+        if (childValue === null && depth === 0 && !REQUIRED_RECORD_KEYS.has(childKey))
+            continue;
+        out[childKey] = stripUndefinedAndOptionalNulls(childValue, childKey, depth + 1); // lgtm[js/remote-property-injection] — childKey is own-property of caller-controlled entry; schema rejects unknown top-level keys downstream
+    }
+    if (key && Object.keys(out).length === 0 && !REQUIRED_RECORD_KEYS.has(key))
+        return undefined;
+    return out;
+}
+function applyWriteCompatibility(entry) {
+    const next = stripUndefinedAndOptionalNulls(entry);
+    if (next.status === 'active')
+        next.status = 'approved';
+    if (next.audience === undefined)
+        next.audience = 'all';
+    if (next.requirement === undefined)
+        next.requirement = 'optional';
+    if (typeof next.audience === 'string') {
+        const legacyAudienceMap = {
+            system: 'all',
+            developers: 'group',
+            developer: 'individual',
+            team: 'group',
+            teams: 'group',
+            users: 'group',
+            dev: 'individual',
+            devs: 'group',
+            testers: 'group',
+            administrators: 'group',
+            admins: 'group',
+            agents: 'group',
+            'powershell script authors': 'group',
+        };
+        const lower = next.audience.toLowerCase();
+        if (legacyAudienceMap[next.audience])
+            next.audience = legacyAudienceMap[next.audience];
+        else if (legacyAudienceMap[lower])
+            next.audience = legacyAudienceMap[lower];
+        else if (/author|script\s+author/i.test(lower))
+            next.audience = 'individual';
+    }
+    if (typeof next.requirement === 'string') {
+        const legacyRequirementMap = {
+            MUST: 'mandatory',
+            SHOULD: 'recommended',
+            MAY: 'optional',
+            CRITICAL: 'critical',
+            OPTIONAL: 'optional',
+            MANDATORY: 'mandatory',
+            DEPRECATED: 'deprecated',
+        };
+        const upper = next.requirement.toUpperCase();
+        if (legacyRequirementMap[next.requirement])
+            next.requirement = legacyRequirementMap[next.requirement];
+        else if (legacyRequirementMap[upper])
+            next.requirement = legacyRequirementMap[upper];
+    }
+    if (typeof next.priority !== 'number' || next.priority < 1 || next.priority > 100)
+        next.priority = 50;
+    return next;
+}
+// Matches the upper bound declared in schemas/instruction.schema.json (id maxLength).
+exports.INSTRUCTION_ID_MAX_LENGTH = 120;
+function findIllegalControlChar(id) {
+    for (let i = 0; i < id.length; i++) {
+        const code = id.charCodeAt(i);
+        // Reject ASCII control characters (incl. NUL 0x00) and DEL (0x7F).
+        if (code < 0x20 || code === 0x7f) {
+            const display = `\\x${code.toString(16).padStart(2, '0')}`;
+            return { display, code };
+        }
+    }
+    return undefined;
+}
+function validateIdSurface(id) {
+    if (typeof id !== 'string' || !id.trim())
+        return ['id: missing required field'];
+    const illegal = findIllegalControlChar(id);
+    if (illegal) {
+        return [`id: contains illegal control character (${illegal.display}) — id-illegal-character`];
+    }
+    if (id.length > exports.INSTRUCTION_ID_MAX_LENGTH) {
+        return [`id: exceeds maximum length of ${exports.INSTRUCTION_ID_MAX_LENGTH} characters (id-too-long)`];
+    }
+    if (id.includes('..') || id.includes('/') || id.includes('\\') || /[:*?"<>|]/.test(id)) {
+        return ['id: must be a safe instruction id without path traversal or path separators'];
+    }
+    return [];
+}
+// Typed-field shape checks. These run for both strict and lax callers so that lax mode
+// fills defaults for *missing* fields but never silently coerces wrong-typed inputs.
+function validateTypedInputShape(entry) {
+    const errs = [];
+    if (entry.priority !== undefined && typeof entry.priority !== 'number') {
+        errs.push(`/priority: must be a number, received ${typeof entry.priority}`);
+    }
+    if (entry.categories !== undefined && !Array.isArray(entry.categories)) {
+        errs.push(`/categories: must be an array of strings, received ${typeof entry.categories}`);
+    }
+    if (entry.audience !== undefined && typeof entry.audience !== 'string') {
+        errs.push(`/audience: must be a string, received ${typeof entry.audience}`);
+    }
+    if (entry.requirement !== undefined && typeof entry.requirement !== 'string') {
+        errs.push(`/requirement: must be a string, received ${typeof entry.requirement}`);
+    }
+    if (entry.title !== undefined && typeof entry.title !== 'string') {
+        errs.push(`/title: must be a string, received ${typeof entry.title}`);
+    }
+    if (entry.body !== undefined && typeof entry.body !== 'string') {
+        errs.push(`/body: must be a string, received ${typeof entry.body}`);
+    }
+    if (entry.changeLog !== undefined && !Array.isArray(entry.changeLog)) {
+        errs.push(`/changeLog: must be an array, received ${typeof entry.changeLog}`);
+    }
+    if (entry.extensions !== undefined && (typeof entry.extensions !== 'object' || Array.isArray(entry.extensions))) {
+        errs.push(`/extensions: must be an object, received ${Array.isArray(entry.extensions) ? 'array' : typeof entry.extensions}`);
+    }
+    return errs;
+}
+function validateInstructionInputSurface(entry) {
+    const validationErrors = [];
+    validationErrors.push(...validateIdSurface(entry.id));
+    for (const key of Object.keys(entry)) {
+        if (!ALLOWED_INPUT_KEYS.has(key)) {
+            validationErrors.push(`/: unexpected property "${key}"`);
+            continue;
+        }
+        if (entry[key] === null)
+            validationErrors.push(`/${key}: null is not allowed`);
+    }
+    validationErrors.push(...validateTypedInputShape(entry));
+    return {
+        record: entry,
+        validationErrors: dedupe(validationErrors),
+        hints: buildHints(validationErrors),
+        schemaRef: INPUT_SCHEMA_REF,
+    };
+}
+function validateInstructionRecord(entry) {
+    const record = applyWriteCompatibility(entry);
+    const validationErrors = [];
+    if (record.status !== undefined && !['draft', 'review', 'approved', 'deprecated'].includes(record.status)) {
+        validationErrors.push(`/status: invalid value "${String(record.status)}"`);
+    }
+    if (record.priorityTier !== undefined && !['P1', 'P2', 'P3', 'P4'].includes(record.priorityTier)) {
+        validationErrors.push(`/priorityTier: invalid value "${String(record.priorityTier)}"`);
+    }
+    if (record.classification !== undefined && !['public', 'internal', 'restricted'].includes(record.classification)) {
+        validationErrors.push(`/classification: invalid value "${String(record.classification)}"`);
+    }
+    if (record.contentType !== undefined && !['instruction', 'template', 'chat-session', 'reference', 'example', 'agent'].includes(record.contentType)) {
+        validationErrors.push(`/contentType: invalid value "${String(record.contentType)}"`);
+    }
+    if (!validateInstructionSchema(record)) {
+        validationErrors.push(...(validateInstructionSchema.errors ?? []).map(formatAjvError));
+    }
+    const classifierIssues = new classificationService_1.ClassificationService().validate(record);
+    validationErrors.push(...classifierIssues.map((issue) => `/: ${issue}`));
+    if (typeof record.title === 'string' && !record.title.trim())
+        validationErrors.push('/title: must not be empty');
+    if (typeof record.body === 'string' && !record.body.trim())
+        validationErrors.push('/body: must not be empty');
+    return {
+        record,
+        validationErrors: dedupe(validationErrors),
+        hints: buildHints(validationErrors),
+        schemaRef: INPUT_SCHEMA_REF,
+    };
+}
+function assertValidInstructionRecord(entry) {
+    const validation = validateInstructionRecord(entry);
+    if (validation.validationErrors.length) {
+        throw new InstructionValidationError(validation.validationErrors, validation.hints, validation.schemaRef);
+    }
+    return validation.record;
+}
+function isInstructionValidationError(error) {
+    return error instanceof InstructionValidationError
+        || (typeof error === 'object'
+            && error !== null
+            && 'code' in error
+            && error.code === 'invalid_instruction'
+            && Array.isArray(error.validationErrors));
+}
+const NODE_FS_ERROR_CODES = /\b(ENOENT|EACCES|EEXIST|EISDIR|ENOTDIR|EPERM|EBUSY|EMFILE|ENFILE|EROFS|ENOSPC|EAGAIN|EFAULT|EINVAL|EIO|ELOOP)\b[:,]?\s*/g;
+/**
+ * Strip absolute paths, Node fs error codes, quoted path arguments, and
+ * stack traces from a free-form error message. Used to keep client-facing
+ * error responses free of filesystem layout or internal details.
+ */
+function sanitizeErrorDetail(message) {
+    if (!message)
+        return '';
+    // Truncate to first line — drops stack traces.
+    let s = String(message).split('\n')[0];
+    // Quoted path arguments (single and double quotes), e.g. open 'C:\\x.json'.
+    s = s.replace(/'[^']*[\\/][^']*'/g, "'<redacted-path>'");
+    s = s.replace(/"[^"]*[\\/][^"]*"/g, '"<redacted-path>"');
+    // Windows absolute paths.
+    s = s.replace(/[A-Za-z]:\\[^\s'"`]+/g, '<redacted-path>');
+    // Unix absolute paths with at least two segments.
+    s = s.replace(/\/(?:[^\s/'"`]+\/)+[^\s/'"`]+/g, '<redacted-path>');
+    // Node fs error codes (after path stripping so we don't break boundaries).
+    s = s.replace(NODE_FS_ERROR_CODES, '');
+    // Collapse whitespace and stray punctuation.
+    s = s.replace(/\s+/g, ' ').replace(/^[\s:,;-]+/, '').replace(/[\s:,;-]+$/, '').trim();
+    return s;
+}
+/**
+ * Convert an arbitrary error from the existing-entry load path into a
+ * client-safe shape. The `raw` field is preserved for internal audit logging
+ * only; never echo it directly to clients.
+ */
+function sanitizeLoadError(err, kind = 'load_failed') {
+    const raw = err instanceof Error ? (err.message ?? '') : (typeof err === 'string' ? err : '');
+    let detail = sanitizeErrorDetail(raw);
+    if (!detail) {
+        detail = kind === 'parse_failed'
+            ? 'invalid JSON in existing entry'
+            : kind === 'load_failed'
+                ? 'unable to read existing entry'
+                : 'unknown load error';
+    }
+    return { code: kind, detail, raw };
+}

package/dist/services/instructions.dispatcher.js

@@ -164,11 +164,11 @@ function isMutationEnabled() {
     if (mutationMethods.has(target) && !isMutationEnabled()) {
         // Dispatcher design intent: allow mutation-style actions even when direct mutation tools
         // are disabled. The previous logic incorrectly blocked these calls, causing silent timeouts
-        // in tests expecting dispatcher add to succeed without INDEX_SERVER_MUTATION=1.
+        // in tests expecting dispatcher add to succeed even when direct mutation calls were forced off.
         // We now log (if verbose) and proceed instead of throwing a semantic error.
         try {
             if ((0, runtimeConfig_1.getRuntimeConfig)().logging.verbose)
-                process.stderr.write(`[dispatcher] mutation_allowed_via_dispatcher action=${action} target=${target} (INDEX_SERVER_MUTATION not set)\n`);
+                process.stderr.write(`[dispatcher] mutation_allowed_via_dispatcher action=${action} target=${target} (direct mutation override disabled)\n`);
         }
         catch { /* ignore */ }
     }
@@ -192,7 +192,7 @@ function isMutationEnabled() {
     // because the dispatch schema cannot express nested 'entry' wrappers.
     // When 'entry' is absent but 'id' is present, assemble the entry from flat params.
     if (action === 'add' && !rest.entry && typeof rest.id === 'string') {
-        const entryFields = ['id', 'body', 'title', 'rationale', 'priority', 'audience', 'requirement', 'categories', 'deprecatedBy', 'riskScore', 'version', 'owner', 'status', 'priorityTier', 'classification', 'lastReviewedAt', 'nextReviewDue', 'semanticSummary', 'changeLog', 'extensions'];
+        const entryFields = ['id', 'body', 'title', 'rationale', 'priority', 'audience', 'requirement', 'categories', 'deprecatedBy', 'riskScore', 'version', 'owner', 'status', 'priorityTier', 'classification', 'lastReviewedAt', 'nextReviewDue', 'semanticSummary', 'changeLog', 'contentType', 'extensions'];
         const entry = {};
         for (const k of entryFields) {
             if (rest[k] !== undefined) {
@@ -204,7 +204,7 @@ function isMutationEnabled() {
     }
     void _ignoredAction; // explicitly ignore for lint
     // Mark invocation origin so guard() can allow dispatcher-mediated mutations even if
-    // INDEX_SERVER_MUTATION is not globally enabled.
+    // direct mutation tools were explicitly disabled via runtime override.
     rest._viaDispatcher = true;
     const hStart = timing ? Date.now() : 0;
     // Gating: block mutation targets if bootstrap confirmation required or reference mode active.

package/dist/services/loaderSchemaValidator.d.ts

@@ -0,0 +1,15 @@
+export interface DiskValidationResult {
+    valid: boolean;
+    errors?: string[];
+}
+/**
+ * Validate an instruction record against the loader JSON schema — the same
+ * schema used by IndexLoader when loading entries from disk.
+ *
+ * Call this on the exact object about to be serialized with JSON.stringify()
+ * and written to disk. If it fails, the entry WILL be silently skipped on
+ * the next reload.
+ */
+export declare function validateForDisk(record: unknown): DiskValidationResult;
+/** Returns the set of property names allowed by the loader JSON schema. */
+export declare function getSchemaPropertyNames(): Set<string>;

package/dist/services/loaderSchemaValidator.js

@@ -0,0 +1,69 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateForDisk = validateForDisk;
+exports.getSchemaPropertyNames = getSchemaPropertyNames;
+/**
+ * Shared loader-schema validator — uses the SAME JSON schema the IndexLoader
+ * uses at reload time, compiled once and cached at module scope.
+ *
+ * Every instruction write path MUST validate through this before persisting
+ * to disk. This is the single source of truth that prevents schema drift
+ * between write-time and load-time validation from silently dropping entries.
+ */
+const ajv_1 = __importDefault(require("ajv"));
+const ajv_formats_1 = __importDefault(require("ajv-formats"));
+const json_schema_draft_07_json_1 = __importDefault(require("ajv/dist/refs/json-schema-draft-07.json"));
+const instruction_schema_json_1 = __importDefault(require("../../schemas/instruction.schema.json"));
+const runtimeConfig_1 = require("../config/runtimeConfig");
+const ajv = new ajv_1.default({ strict: false, allErrors: true });
+(0, ajv_formats_1.default)(ajv);
+// Register draft-07 meta schema under https id (mirrors IndexLoader behavior)
+try {
+    const httpsIdNoHash = 'https://json-schema.org/draft-07/schema';
+    const httpsIdHash = 'https://json-schema.org/draft-07/schema#';
+    if (!ajv.getSchema(httpsIdNoHash))
+        ajv.addMetaSchema({ ...json_schema_draft_07_json_1.default, $id: httpsIdNoHash });
+    if (!ajv.getSchema(httpsIdHash))
+        ajv.addMetaSchema({ ...json_schema_draft_07_json_1.default, $id: httpsIdHash });
+}
+catch { /* ignore meta-schema registration issues */ }
+// Patch body maxLength from config (mirrors IndexLoader behavior)
+const schemaCopy = JSON.parse(JSON.stringify(instruction_schema_json_1.default));
+try {
+    const bodyMaxLen = (0, runtimeConfig_1.getRuntimeConfig)().index?.bodyWarnLength || 50000;
+    const props = schemaCopy.properties;
+    if (props?.body)
+        props.body.maxLength = bodyMaxLen;
+}
+catch (err) {
+    // If the bodyMaxLength patch fails the validator falls back to whatever
+    // limit ships in the on-disk schema, which can mismatch the configured
+    // INDEX_SERVER_BODY_WARN_LENGTH and silently accept/reject entries.
+    // Surface the warning so operators can see the divergence.
+    // eslint-disable-next-line no-console
+    console.warn('[loaderSchemaValidator] failed to patch schema bodyMaxLength from runtime config:', err?.message || err);
+}
+const validate = ajv.compile(schemaCopy);
+/**
+ * Validate an instruction record against the loader JSON schema — the same
+ * schema used by IndexLoader when loading entries from disk.
+ *
+ * Call this on the exact object about to be serialized with JSON.stringify()
+ * and written to disk. If it fails, the entry WILL be silently skipped on
+ * the next reload.
+ */
+function validateForDisk(record) {
+    const valid = validate(record);
+    if (valid)
+        return { valid: true };
+    const errors = validate.errors?.map(e => `${e.instancePath || '(root)'} ${e.message}${e.params ? ' ' + JSON.stringify(e.params) : ''}`) ?? ['unknown validation error'];
+    return { valid: false, errors };
+}
+/** Returns the set of property names allowed by the loader JSON schema. */
+function getSchemaPropertyNames() {
+    const props = instruction_schema_json_1.default.properties;
+    return props ? new Set(Object.keys(props)) : new Set();
+}

package/dist/services/logger.js

@@ -10,6 +10,7 @@ const crypto_1 = __importDefault(require("crypto"));
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const runtimeConfig_1 = require("../config/runtimeConfig");
+const mcpLogBridge_1 = require("./mcpLogBridge");
 /** Numeric priority for log level filtering (lower = more verbose). */
 const LEVEL_PRIORITY = {
     TRACE: 0,
@@ -177,8 +178,16 @@ function emit(rec) {
     if (rec.correlationId)
         out.correlationId = rec.correlationId;
     const logLine = JSON.stringify(out);
-    // Always log to stderr for VS Code output panel
-    console.error(logLine);
+    // Route through MCP protocol notifications/message when available.
+    // This gives VS Code correct severity (info/debug/warning/error) instead
+    // of tagging every line as [warning] [server stderr].
+    if ((0, mcpLogBridge_1.isMcpLogBridgeActive)()) {
+        (0, mcpLogBridge_1.sendMcpLog)(rec.level, logLine);
+    }
+    else {
+        // Pre-handshake: fall back to stderr (intercepted and buffered by McpStdioLogger)
+        console.error(logLine);
+    }
     // Also log to file if configured and available
     if (logFileHandle && !logFileHandle.destroyed) {
         try {

package/dist/services/mcpLogBridge.d.ts

@@ -0,0 +1,49 @@
+/**
+ * MCP Log Bridge — thin adapter over the generalized McpStdioLogger.
+ *
+ * Preserves the existing module-level API (`registerMcpServer`, `activateMcpLogBridge`,
+ * `isMcpLogBridgeActive`, `sendMcpLog`, `_restoreStderr`) so that all existing
+ * call sites in index-server.ts, sdkServer.ts, handshakeManager.ts, and logger.ts
+ * continue to work without changes.
+ *
+ * The actual stderr interception, buffering, replay, and MCP protocol routing is
+ * delegated to `McpStdioLogger` from `../lib/mcpStdioLogging`, which is a
+ * self-contained, reusable module for any MCP stdio server.
+ *
+ * See `src/lib/mcpStdioLogging.ts` for the generalized implementation and
+ * `docs/mcp_stdio_logging.md` for integration guidance.
+ */
+import type { LogLevel } from './logger';
+/**
+ * Register the SDK server instance. Called once after server creation.
+ * Does NOT activate the bridge — call `activateMcpLogBridge()` after ready.
+ */
+export declare function registerMcpServer(server: any): void;
+/**
+ * Activate the bridge so subsequent log calls are routed via MCP protocol.
+ * Replays any buffered pre-handshake stderr lines through the protocol.
+ * Called from `emitReadyGlobal()` after the handshake completes.
+ */
+export declare function activateMcpLogBridge(): void;
+/**
+ * Returns true if the bridge is active and logs will be sent via MCP protocol.
+ */
+export declare function isMcpLogBridgeActive(): boolean;
+/**
+ * Send a log message through the MCP `notifications/message` protocol.
+ * No-op if the bridge is not yet active.
+ *
+ * @param level - The index-server log level (TRACE, DEBUG, INFO, WARN, ERROR)
+ * @param data  - The log payload (typically the NDJSON string)
+ */
+export declare function sendMcpLog(level: LogLevel, data: string): void;
+/**
+ * Write directly to the original process.stderr, bypassing the interceptor.
+ * Use from logger.ts to ensure VS Code Output panel always has content.
+ */
+export declare function writeRealStderr(data: string): void;
+/**
+ * Restore original stderr and deactivate the bridge.
+ * Intended for testing cleanup only.
+ */
+export declare function _restoreStderr(): void;