@jagilber-org/index-server 1.22.1 → 1.26.1

package/dist/services/handlers/instructions.add.js

@@ -18,8 +18,10 @@ const runtimeConfig_1 = require("../../config/runtimeConfig");
 const canonical_1 = require("../canonical");
 const manifestManager_1 = require("../manifestManager");
 const tracing_1 = require("../tracing");
+const instructionRecordValidation_1 = require("../instructionRecordValidation");
+const instructionRecordValidation_2 = require("../instructionRecordValidation");
 const instructions_shared_1 = require("./instructions.shared");
-(0, registry_1.registerHandler)('index_add', (0, instructions_shared_1.guard)('index_add', (p) => {
+(0, registry_1.registerHandler)('index_add', (0, instructions_shared_1.guard)('index_add', async (p) => {
     const e = p.entry;
     const instructionsCfg = (0, runtimeConfig_1.getRuntimeConfig)().instructions;
     const SEMVER_REGEX = /^([0-9]+)\.([0-9]+)\.([0-9]+)(?:[-+].*)?$/;
@@ -38,24 +40,153 @@ const instructions_shared_1 = require("./instructions.shared");
         } : { id };
         const base = {
             id,
+            success: false,
             created: false,
             overwritten: false,
             skipped: false,
             error,
             hash: opts?.hash,
-            feedbackHint: 'Creation failed. If unexpected, call feedback_submit with reproEntry.',
+            message: opts?.message || 'Instruction not added.',
+            feedbackHint: 'Instruction not added. Fix validationErrors or call feedback_submit with reproEntry.',
             reproEntry
         };
-        if (/^missing (entry|id|required fields)/.test(error) || error === 'missing required fields') {
-            if (ADD_INPUT_SCHEMA) {
-                base.schemaRef = "meta_tools[name='index_add'].inputSchema";
+        if (opts?.validationErrors?.length)
+            base.validationErrors = opts.validationErrors;
+        if (opts?.hints?.length)
+            base.hints = opts.hints;
+        if (opts?.errorCode)
+            base.errorCode = opts.errorCode;
+        if (opts?.detail)
+            base.detail = opts.detail;
+        if (/^missing (entry|id|required fields)/.test(error) || error === 'missing required fields' || error === 'invalid_instruction') {
+            base.schemaRef = instructionRecordValidation_1.INSTRUCTION_INPUT_SCHEMA_REF;
+            if (ADD_INPUT_SCHEMA)
                 base.inputSchema = ADD_INPUT_SCHEMA;
+        }
+        return base;
+    };
+    const failValidation = (error, validationErrors, hints, opts) => fail(error, { ...opts, validationErrors, hints, message: 'Instruction not added.' });
+    const loadExistingEntry = async (id, filePath) => {
+        let priorLoad;
+        try {
+            const stExisting = await (0, indexContext_1.ensureLoadedAsync)();
+            const memEntry = stExisting.byId.get(id);
+            if (memEntry)
+                return { entry: { ...memEntry } };
+        }
+        catch (err) {
+            priorLoad = (0, instructionRecordValidation_1.sanitizeLoadError)(err, 'load_failed');
+        }
+        if (fs_1.default.existsSync(filePath)) {
+            let diskRaw;
+            try {
+                diskRaw = fs_1.default.readFileSync(filePath, 'utf8');
             }
-            else {
-                base.schemaRef = 'meta_tools (lookup index_add)';
+            catch (err) {
+                return { error: (0, instructionRecordValidation_1.sanitizeLoadError)(err, 'load_failed') };
+            }
+            try {
+                return { entry: JSON.parse(diskRaw) };
+            }
+            catch (err) {
+                return { error: (0, instructionRecordValidation_1.sanitizeLoadError)(err, 'parse_failed') };
             }
         }
-        return base;
+        if (priorLoad)
+            return { error: priorLoad };
+        return { error: { code: 'unknown', detail: 'missing-existing-entry', raw: 'missing-existing-entry' } };
+    };
+    const verifyReadBack = async (id, filePath, requestedCategories) => {
+        try {
+            (0, indexContext_1.invalidate)();
+        }
+        catch { /* ignore */ }
+        const stReloaded = await (0, indexContext_1.ensureLoadedAsync)();
+        let strictVerified = false;
+        const verifyIssues = [];
+        try {
+            let parsed;
+            parsed = stReloaded.byId.get(id) ?? undefined;
+            if (!parsed && fs_1.default.existsSync(filePath)) {
+                let diskRaw;
+                try {
+                    diskRaw = fs_1.default.readFileSync(filePath, 'utf8');
+                }
+                catch (ex) {
+                    verifyIssues.push('read-failed:' + ex.message);
+                }
+                if (diskRaw) {
+                    try {
+                        parsed = JSON.parse(diskRaw);
+                    }
+                    catch (ex) {
+                        verifyIssues.push('parse-failed:' + ex.message);
+                    }
+                }
+            }
+            if (parsed) {
+                if (parsed.id !== id)
+                    verifyIssues.push('id-mismatch');
+                if (!parsed.title)
+                    verifyIssues.push('missing-title');
+                if (!parsed.body)
+                    verifyIssues.push('missing-body');
+                const wantCats = Array.isArray(requestedCategories)
+                    ? requestedCategories.filter((c) => typeof c === 'string').map(c => c.toLowerCase())
+                    : [];
+                if (wantCats.length) {
+                    for (const c of wantCats) {
+                        if (!parsed.categories?.includes(c))
+                            verifyIssues.push('missing-category:' + c);
+                    }
+                }
+            }
+            const mem = stReloaded.byId.get(id);
+            if (!mem)
+                verifyIssues.push('not-in-index');
+            const wantCats2 = Array.isArray(requestedCategories)
+                ? requestedCategories.filter((c) => typeof c === 'string').map(c => c.toLowerCase())
+                : [];
+            if (wantCats2.length) {
+                const catHit = stReloaded.list.some(rec => rec.id === id && wantCats2.every(c => rec.categories.includes(c)));
+                if (!catHit)
+                    verifyIssues.push('category-query-miss');
+            }
+            try {
+                if (parsed) {
+                    const classifier2 = new classificationService_1.ClassificationService();
+                    const issues = classifier2.validate(parsed);
+                    if (issues.length)
+                        verifyIssues.push('classification-issues:' + issues.join(','));
+                }
+            }
+            catch (err) {
+                verifyIssues.push('classification-exception:' + err.message);
+            }
+            if (verifyIssues.includes('not-in-index')) {
+                try {
+                    (0, indexContext_1.invalidate)();
+                    const st2 = await (0, indexContext_1.ensureLoadedAsync)();
+                    if (st2.byId.has(id)) {
+                        const idx = verifyIssues.indexOf('not-in-index');
+                        if (idx >= 0)
+                            verifyIssues.splice(idx, 1);
+                    }
+                }
+                catch { /* ignore */ }
+            }
+            if (!verifyIssues.length)
+                strictVerified = true;
+        }
+        catch (err) {
+            verifyIssues.push('verify-exception:' + err.message);
+        }
+        return {
+            stReloaded,
+            strictVerified,
+            verifyIssues,
+            verified: strictVerified && verifyIssues.length === 0,
+        };
     };
     const metadataEquals = (left, right) => {
         if (left === right)
@@ -79,87 +210,60 @@ const instructions_shared_1 = require("./instructions.shared");
         if (!e.id)
             return fail('missing id');
         const mutable = e;
-        if (!mutable.title)
+        // Only fill defaults for *missing* fields. Never silently coerce a wrong-typed value:
+        // shape violations are surfaced as invalid_instruction by validateInstructionInputSurface.
+        if (mutable.title === undefined)
             mutable.title = mutable.id;
-        if (typeof mutable.priority !== 'number')
+        if (mutable.priority === undefined)
             mutable.priority = 50;
-        if (!mutable.audience)
+        if (mutable.audience === undefined)
             mutable.audience = 'all';
-        if (!mutable.requirement)
+        if (mutable.requirement === undefined)
             mutable.requirement = 'optional';
-        if (!Array.isArray(mutable.categories))
+        if (mutable.categories === undefined)
             mutable.categories = [];
     }
-    if (p.overwrite && (!e.body || !e.title)) {
-        try {
-            // Try in-memory state first (covers SQLite and JSON backends), fall back to disk
-            let raw;
-            const stHydrate = (0, indexContext_1.ensureLoaded)();
-            const memEntry = stHydrate.byId.get(e.id);
-            if (memEntry) {
-                raw = { ...memEntry };
-            }
-            if (!raw) {
-                const dirCandidate = (0, indexContext_1.getInstructionsDir)();
-                const fileCandidate = path_1.default.join(dirCandidate, `${e.id}.json`);
-                if (fs_1.default.existsSync(fileCandidate)) {
-                    try {
-                        raw = JSON.parse(fs_1.default.readFileSync(fileCandidate, 'utf8'));
-                    }
-                    catch { /* ignore parse */ }
-                }
-            }
-            if (raw) {
-                const mutableExisting = e;
-                if (!mutableExisting.body && typeof raw.body === 'string' && raw.body.trim()) {
-                    mutableExisting.body = raw.body;
-                }
-                if (!mutableExisting.title && typeof raw.title === 'string' && raw.title.trim()) {
-                    mutableExisting.title = raw.title;
-                }
-            }
-        }
-        catch { /* ignore hydration errors */ }
-    }
-    if (!e.id || !e.title || !e.body)
-        return fail('missing required fields');
     const dir = (0, indexContext_1.getInstructionsDir)();
     if (!fs_1.default.existsSync(dir))
         fs_1.default.mkdirSync(dir, { recursive: true });
     const file = path_1.default.join(dir, `${e.id}.json`);
-    const existsInStore = (0, indexContext_1.ensureLoaded)().byId.has(e.id);
-    const existsOnDisk = !existsInStore && fs_1.default.existsSync(file);
-    const exists = existsInStore || existsOnDisk;
-    const existedBeforeOriginal = exists;
-    const overwrite = !!p.overwrite;
-    if (exists && !overwrite) {
-        let st0 = (0, indexContext_1.ensureLoaded)();
-        let visible = st0.byId.has(e.id);
-        let repaired = false;
-        if (!visible) {
-            try {
-                (0, indexContext_1.invalidate)();
-                st0 = (0, indexContext_1.ensureLoaded)();
-                visible = st0.byId.has(e.id);
-                if (visible)
-                    repaired = true;
+    if (p.overwrite && (!e.body || !e.title)) {
+        const hydrated = await loadExistingEntry(e.id, file);
+        if (hydrated.entry) {
+            const mutableExisting = e;
+            if (!mutableExisting.body && typeof hydrated.entry.body === 'string' && hydrated.entry.body.trim()) {
+                mutableExisting.body = hydrated.entry.body;
+            }
+            if (!mutableExisting.title && typeof hydrated.entry.title === 'string' && hydrated.entry.title.trim()) {
+                mutableExisting.title = hydrated.entry.title;
             }
-            catch { /* ignore reload */ }
-        }
-        (0, auditLog_1.logAudit)('add', e.id, { skipped: true, late_visible: visible, repaired });
-        if ((0, instructions_shared_1.traceVisibility)()) {
-            (0, tracing_1.emitTrace)('[trace:add:skip]', { id: e.id, visible, repaired });
-        }
-        if ((0, instructions_shared_1.traceVisibility)()) {
-            (0, instructions_shared_1.traceInstructionVisibility)(e.id, 'add-skip-pre-return', { visible, repaired });
-            if (!visible)
-                (0, instructions_shared_1.traceEnvSnapshot)('add-skip-anomalous', { repaired });
         }
-        if (!visible) {
-            return { id: e.id, skipped: true, created: false, overwritten: false, hash: st0.hash, visibilityWarning: 'skipped_file_not_in_index' };
+        else if (hydrated.error) {
+            // Surface all read failures, including those combined with 'missing-existing-entry'
+            const hasRealError = hydrated.error.detail !== 'missing-existing-entry';
+            if (hasRealError) {
+                (0, auditLog_1.logAudit)('add_hydration_error', e.id, { error: hydrated.error.raw, errorCode: hydrated.error.code, overwrite: true });
+                return fail('existing_instruction_unreadable', {
+                    id: e.id,
+                    message: `Existing instruction could not be hydrated for overwrite (${hydrated.error.code}): ${hydrated.error.detail}`,
+                    errorCode: hydrated.error.code,
+                    detail: hydrated.error.detail,
+                });
+            }
         }
-        return { id: e.id, skipped: true, created: false, overwritten: false, hash: st0.hash, repaired: repaired ? true : undefined };
     }
+    const requiredFieldErrors = [
+        !e.id ? 'id: missing required field' : undefined,
+        e.title === undefined ? 'title: missing required field' : undefined,
+        e.body === undefined ? 'body: missing required field' : undefined,
+    ].filter((issue) => !!issue);
+    const surfaceValidation = (0, instructionRecordValidation_1.validateInstructionInputSurface)(e);
+    if (requiredFieldErrors.length || surfaceValidation.validationErrors.length) {
+        return failValidation(requiredFieldErrors.length ? 'missing required fields' : 'invalid_instruction', [...requiredFieldErrors, ...surfaceValidation.validationErrors], surfaceValidation.hints, { id: e.id });
+    }
+    const overwrite = !!p.overwrite;
+    const exists = overwrite ? ((await (0, indexContext_1.ensureLoadedAsync)()).byId.has(e.id) || fs_1.default.existsSync(file)) : false;
+    const existedBeforeOriginal = exists;
     const now = new Date().toISOString();
     const rawBody = typeof e.body === 'string' ? e.body : String(e.body || '');
     const bodyTrimmed = rawBody.trim();
@@ -172,7 +276,7 @@ const instructions_shared_1 = require("./instructions.shared");
             guidance: `Body exceeds the ${bodyWarnLength}-character limit (${bodyTrimmed.length} chars). Please split into multiple cross-linked instructions, refine/compress content, or categorize sections as separate entries. Use categories and cross-references (e.g., "See also: <sibling-id>") to maintain discoverability.`
         };
     }
-    let categories = Array.from(new Set((Array.isArray(e.categories) ? e.categories : []).filter((c) => typeof c === 'string' && c.trim().length > 0).map(c => c.toLowerCase()))).sort();
+    let categories = (0, instructions_shared_1.normalizeInputCategories)(e.categories);
     if (!categories.length) {
         const allowAuto = lax || !instructionsCfg.requireCategory;
         if (allowAuto) {
@@ -197,130 +301,154 @@ const instructions_shared_1 = require("./instructions.shared");
     const classifier = new classificationService_1.ClassificationService();
     let base;
     if (exists) {
-        try {
-            let existing;
-            // Try store first (covers SQLite), fall back to disk (JSON backend)
-            const stMerge = (0, indexContext_1.ensureLoaded)();
-            const memEntry = stMerge.byId.get(e.id);
-            if (memEntry) {
-                existing = { ...memEntry };
-            }
-            else if (existsOnDisk) {
-                existing = JSON.parse(fs_1.default.readFileSync(file, 'utf8'));
-            }
-            else {
-                throw new Error('entry not found in store or on disk');
-            }
-            base = { ...existing };
-            const prevBody = existing.body;
-            const prevVersion = existing.version || '1.0.0';
-            if (e.title)
-                base.title = e.title;
-            if (e.body)
-                base.body = bodyTrimmed;
-            if (e.rationale !== undefined)
-                base.rationale = e.rationale;
-            if (typeof e.priority === 'number')
-                base.priority = e.priority;
-            if (e.audience)
-                base.audience = e.audience;
-            if (e.requirement)
-                base.requirement = e.requirement;
-            if (categories.length) {
-                base.categories = categories;
-                base.primaryCategory = primaryCategory;
-            }
-            base.updatedAt = now;
-            if (e.version !== undefined)
-                base.version = e.version;
-            if (e.changeLog !== undefined)
-                base.changeLog = e.changeLog;
-            const semverRegex = SEMVER_REGEX;
-            const parse = (v) => { const m = semverRegex.exec(v); if (!m)
-                return null; return { major: +m[1], minor: +m[2], patch: +m[3] }; };
-            const gt = (a, b) => { const pa = parse(a), pb = parse(b); if (!pa || !pb)
-                return false; if (pa.major !== pb.major)
-                return pa.major > pb.major; if (pa.minor !== pb.minor)
-                return pa.minor > pb.minor; return pa.patch > pb.patch; };
-            const bodyChanged = e.body ? (bodyTrimmed !== prevBody) : false;
-            const titleChanged = e.title !== undefined && e.title !== existing.title;
-            const eRec = e;
-            const mutableMetadataKeys = ['owner', 'status', 'priorityTier', 'classification', 'lastReviewedAt', 'nextReviewDue', 'semanticSummary', 'contentType', 'extensions'];
-            const metadataChanged = mutableMetadataKeys.some((key) => eRec[key] !== undefined && !metadataEquals(eRec[key], existing[key]));
-            const versionChanged = e.version !== undefined && e.version !== existing.version;
-            const categoriesChanged = categories.length > 0 && JSON.stringify(categories.sort()) !== JSON.stringify((existing.categories || []).sort());
-            const governanceMetaChanged = titleChanged || metadataChanged || versionChanged || categoriesChanged;
-            if (overwrite && !bodyChanged && !governanceMetaChanged) {
-                const stNoop = (0, indexContext_1.ensureLoaded)();
-                const respNoop = { id: e.id, created: false, overwritten: false, skipped: true, hash: stNoop.hash, verified: true };
-                if (instructionsCfg.strictCreate)
-                    respNoop.strictVerified = true;
-                (0, auditLog_1.logAudit)('add', e.id, { created: false, overwritten: false, skipped: true, verified: true, noop: true });
-                if ((0, instructions_shared_1.traceVisibility)())
-                    (0, tracing_1.emitTrace)('[trace:add:noop-overwrite]', { id: e.id, hash: stNoop.hash, reason: 'no body/governance delta' });
-                return respNoop;
+        const existingLoad = await loadExistingEntry(e.id, file);
+        if (!existingLoad.entry) {
+            const errCode = existingLoad.error?.code ?? 'unknown';
+            const errDetail = existingLoad.error?.detail ?? 'missing-existing-entry';
+            return fail('existing_instruction_unreadable', {
+                id: e.id,
+                message: `Existing instruction could not be read for overwrite (${errCode}): ${errDetail}`,
+                errorCode: errCode,
+                detail: errDetail,
+            });
+        }
+        const existing = existingLoad.entry;
+        base = { ...existing };
+        const prevBody = existing.body;
+        const prevVersion = existing.version || '1.0.0';
+        if (e.title)
+            base.title = e.title;
+        if (e.body)
+            base.body = bodyTrimmed;
+        if (e.rationale !== undefined)
+            base.rationale = e.rationale;
+        if (typeof e.priority === 'number')
+            base.priority = e.priority;
+        if (e.audience)
+            base.audience = e.audience;
+        if (e.requirement)
+            base.requirement = e.requirement;
+        if (categories.length) {
+            base.categories = categories;
+            base.primaryCategory = primaryCategory;
+        }
+        base.updatedAt = now;
+        if (e.version !== undefined)
+            base.version = e.version;
+        if (e.changeLog !== undefined)
+            base.changeLog = e.changeLog;
+        const semverRegex = SEMVER_REGEX;
+        const parse = (v) => { const m = semverRegex.exec(v); if (!m)
+            return null; return { major: +m[1], minor: +m[2], patch: +m[3] }; };
+        const gt = (a, b) => { const pa = parse(a), pb = parse(b); if (!pa || !pb)
+            return false; if (pa.major !== pb.major)
+            return pa.major > pb.major; if (pa.minor !== pb.minor)
+            return pa.minor > pb.minor; return pa.patch > pb.patch; };
+        const bodyChanged = e.body ? (bodyTrimmed !== prevBody) : false;
+        const titleChanged = e.title !== undefined && e.title !== existing.title;
+        const eRec = e;
+        const mutableMetadataKeys = ['owner', 'status', 'priorityTier', 'classification', 'lastReviewedAt', 'nextReviewDue', 'semanticSummary', 'contentType', 'extensions'];
+        const metadataChanged = mutableMetadataKeys.some((key) => eRec[key] !== undefined && !metadataEquals(eRec[key], existing[key]));
+        const versionChanged = e.version !== undefined && e.version !== existing.version;
+        const categoriesChanged = categories.length > 0 && JSON.stringify(categories.sort()) !== JSON.stringify((existing.categories || []).sort());
+        const governanceMetaChanged = titleChanged || metadataChanged || versionChanged || categoriesChanged;
+        if (overwrite && !bodyChanged && !governanceMetaChanged) {
+            // Noop overwrite: no mutation needed because the incoming entry matches
+            // the existing record. Even so, verify the persisted state still matches
+            // the in-memory index — the file (or store row) may have disappeared
+            // since the index was last loaded. Skipping verification here would mean
+            // silently reporting success when the entry is no longer durable.
+            const verification = await verifyReadBack(e.id, file, e.categories);
+            const noopVerified = verification.verified;
+            (0, auditLog_1.logAudit)('add', e.id, {
+                created: false,
+                overwritten: false,
+                skipped: true,
+                verified: noopVerified,
+                strictVerified: verification.strictVerified,
+                verifyIssues: verification.verifyIssues.length ? verification.verifyIssues : undefined,
+                noop: true,
+                note: noopVerified ? 'noop_verified' : 'noop_read_back_failed',
+            });
+            if ((0, instructions_shared_1.traceVisibility)())
+                (0, tracing_1.emitTrace)('[trace:add:noop-overwrite]', {
+                    id: e.id,
+                    hash: verification.stReloaded.hash,
+                    verified: noopVerified,
+                    strictVerified: verification.strictVerified,
+                    issues: verification.verifyIssues.slice(0, 5),
+                    reason: noopVerified
+                        ? 'no body/governance delta — persisted state verified'
+                        : 'no body/governance delta — persisted state verification failed',
+                });
+            if (!noopVerified) {
+                return {
+                    ...fail('read-back verification failed', {
+                        id: e.id,
+                        hash: verification.stReloaded.hash,
+                        message: 'Noop overwrite rejected: persisted instruction state does not match the in-memory index.',
+                        validationErrors: verification.verifyIssues,
+                    }),
+                    created: false,
+                    overwritten: false,
+                    verified: false,
+                    strictVerified: verification.strictVerified,
+                    verifyIssues: verification.verifyIssues,
+                };
             }
-            let incomingVersion = e.version;
-            if (incomingVersion && !semverRegex.test(incomingVersion))
-                return fail('invalid_semver', { id: e.id });
-            if (bodyChanged) {
-                if (incomingVersion) {
-                    if (!gt(incomingVersion, prevVersion))
-                        return fail('version_not_bumped', { id: e.id });
-                }
-                else {
-                    const pv = parse(prevVersion) || { major: 1, minor: 0, patch: 0 };
-                    const autoVersion = `${pv.major}.${pv.minor}.${pv.patch + 1}`;
-                    base.version = autoVersion;
-                    incomingVersion = autoVersion;
-                }
+            const respNoop = {
+                id: e.id,
+                success: true,
+                created: false,
+                overwritten: false,
+                skipped: true,
+                hash: verification.stReloaded.hash,
+                verified: true,
+                note: 'noop_verified',
+            };
+            if (instructionsCfg.strictCreate) {
+                respNoop.strictVerified = verification.strictVerified;
             }
-            else if (incomingVersion) {
+            return respNoop;
+        }
+        let incomingVersion = e.version;
+        if (incomingVersion && !semverRegex.test(incomingVersion))
+            return fail('invalid_semver', { id: e.id });
+        if (bodyChanged) {
+            if (incomingVersion) {
                 if (!gt(incomingVersion, prevVersion))
                     return fail('version_not_bumped', { id: e.id });
             }
             else {
-                base.version = prevVersion;
-                incomingVersion = prevVersion;
-            }
-            if (!Array.isArray(base.changeLog) || !base.changeLog.length) {
-                base.changeLog = [{ version: prevVersion, changedAt: existing.createdAt || now, summary: 'initial import' }];
-            }
-            const finalVersion = base.version || incomingVersion || prevVersion;
-            const last = base.changeLog[base.changeLog.length - 1];
-            if (last.version !== finalVersion) {
-                const summary = bodyChanged ? (e.version ? 'body update' : 'auto bump (body change)') : 'metadata update';
-                base.changeLog.push({ version: finalVersion, changedAt: now, summary });
+                const pv = parse(prevVersion) || { major: 1, minor: 0, patch: 0 };
+                const autoVersion = `${pv.major}.${pv.minor}.${pv.patch + 1}`;
+                base.version = autoVersion;
+                incomingVersion = autoVersion;
             }
-            const repairChangeLog = (cl) => {
-                const out = [];
-                if (Array.isArray(cl)) {
-                    for (const entry of cl) {
-                        if (!entry || typeof entry !== 'object')
-                            continue;
-                        const { version: v, changedAt: ca, summary: sum } = entry;
-                        if (typeof v === 'string' && v.trim() && typeof sum === 'string' && sum.trim()) {
-                            const caIso = typeof ca === 'string' && /T/.test(ca) ? ca : now;
-                            out.push({ version: v.trim(), changedAt: caIso, summary: sum.trim() });
-                        }
-                    }
-                }
-                if (!out.length) {
-                    out.push({ version: prevVersion, changedAt: existing.createdAt || now, summary: 'initial import (repaired)' });
-                }
-                const lastVer = out[out.length - 1].version;
-                if (lastVer !== finalVersion) {
-                    out.push({ version: finalVersion, changedAt: now, summary: bodyChanged ? 'body update (repaired)' : 'metadata update (repaired)' });
-                }
-                return out;
-            };
-            base.changeLog = repairChangeLog(base.changeLog);
         }
-        catch {
-            base = { id: e.id, title: e.title, body: bodyTrimmed, rationale: e.rationale, priority: e.priority, audience: e.audience, requirement: e.requirement, categories, primaryCategory, sourceHash, schemaVersion: schemaVersion_1.SCHEMA_VERSION, deprecatedBy: e.deprecatedBy, createdAt: now, updatedAt: now, riskScore: e.riskScore, createdByAgent: instructionsCfg.agentId, sourceWorkspace: instructionsCfg.workspaceId, extensions: e.extensions };
-            base.version = '1.0.0';
-            base.changeLog = [{ version: '1.0.0', changedAt: now, summary: 'initial import' }];
+        else if (incomingVersion) {
+            if (!gt(incomingVersion, prevVersion))
+                return fail('version_not_bumped', { id: e.id });
+        }
+        else {
+            base.version = prevVersion;
+            incomingVersion = prevVersion;
+        }
+        if (!Array.isArray(base.changeLog) || !base.changeLog.length) {
+            base.changeLog = [{ version: prevVersion, changedAt: existing.createdAt || now, summary: 'initial import' }];
         }
+        const finalVersion = base.version || incomingVersion || prevVersion;
+        const last = base.changeLog[base.changeLog.length - 1];
+        if (last.version !== finalVersion) {
+            const summary = bodyChanged ? (e.version ? 'body update' : 'auto bump (body change)') : 'metadata update';
+            base.changeLog.push({ version: finalVersion, changedAt: now, summary });
+        }
+        base.changeLog = (0, instructions_shared_1.repairChangeLog)(base.changeLog, {
+            finalVersion,
+            now,
+            fallback: { version: prevVersion, changedAt: existing.createdAt || now, summary: 'initial import (repaired)' },
+            trailingSummary: bodyChanged ? 'body update (repaired)' : 'metadata update (repaired)'
+        });
     }
     else {
         base = { id: e.id, title: e.title, body: bodyTrimmed, rationale: e.rationale, priority: e.priority, audience: e.audience, requirement: e.requirement, categories, primaryCategory, sourceHash, schemaVersion: schemaVersion_1.SCHEMA_VERSION, deprecatedBy: e.deprecatedBy, createdAt: now, updatedAt: now, riskScore: e.riskScore, createdByAgent: instructionsCfg.agentId, sourceWorkspace: instructionsCfg.workspaceId, extensions: e.extensions };
@@ -336,32 +464,15 @@ const instructions_shared_1 = require("./instructions.shared");
             base.changeLog = [{ version: base.version, changedAt: now, summary: 'initial import' }];
         }
         if (Array.isArray(base.changeLog)) {
-            const repaired = [];
-            for (const entry of base.changeLog) {
-                if (!entry || typeof entry !== 'object')
-                    continue;
-                const { version: v, changedAt: ca, summary: sum } = entry;
-                if (typeof v === 'string' && v.trim() && typeof sum === 'string' && sum.trim()) {
-                    const caIso = typeof ca === 'string' && /T/.test(ca) ? ca : now;
-                    repaired.push({ version: v.trim(), changedAt: caIso, summary: sum.trim() });
-                }
-            }
-            if (!repaired.length) {
-                repaired.push({ version: base.version, changedAt: now, summary: 'initial import (repaired)' });
-            }
-            if (repaired[repaired.length - 1].version !== base.version) {
-                repaired.push({ version: base.version, changedAt: now, summary: 'initial import (normalized)' });
-            }
-            base.changeLog = repaired;
-        }
-    }
-    const govKeys = ['version', 'owner', 'status', 'priorityTier', 'classification', 'lastReviewedAt', 'nextReviewDue', 'semanticSummary', 'contentType', 'extensions'];
-    for (const k of govKeys) {
-        const v = e[k];
-        if (v !== undefined) {
-            base[k] = v;
+            base.changeLog = (0, instructions_shared_1.repairChangeLog)(base.changeLog, {
+                finalVersion: base.version,
+                now,
+                fallback: { version: base.version, changedAt: now, summary: 'initial import (repaired)' },
+                trailingSummary: 'initial import (normalized)'
+            });
         }
     }
+    (0, instructions_shared_1.applyGovernanceKeys)(base, e, instructions_shared_1.ADD_GOVERNANCE_KEYS);
     if (!base.sourceWorkspace)
         base.sourceWorkspace = instructionsCfg.workspaceId;
     if (!exists || base.body === bodyTrimmed) {
@@ -380,119 +491,75 @@ const instructions_shared_1 = require("./instructions.shared");
             record.updatedAt = new Date().toISOString();
         }
     }
-    try {
-        (0, indexContext_1.writeEntry)(record);
-    }
-    catch (err) {
-        return fail(err.message || 'write-failed', { id: e.id });
+    const recordValidation = (0, instructionRecordValidation_1.validateInstructionRecord)(record);
+    if (recordValidation.validationErrors.length) {
+        return failValidation('invalid_instruction', recordValidation.validationErrors, recordValidation.hints, { id: e.id });
     }
     try {
-        (0, indexContext_1.touchIndexVersion)();
-    }
-    catch { /* ignore */ }
-    let stReloaded;
-    const strictMode = instructionsCfg.strictVisibility;
-    if (strictMode) {
-        try {
-            const current = (0, indexContext_1.ensureLoaded)();
-            stReloaded = current;
-            if (!current.byId.has(record.id)) {
-                current.byId.set(record.id, record);
-                current.list.push(record);
-            }
-        }
-        catch { /* fallback to reload path below if anything fails */ }
+        await (0, indexContext_1.writeEntryAsync)(record, overwrite ? undefined : { createOnly: true });
     }
-    if (!stReloaded) {
-        try {
-            (0, indexContext_1.invalidate)();
+    catch (err) {
+        if ((0, instructionRecordValidation_2.isInstructionValidationError)(err)) {
+            return failValidation('invalid_instruction', err.validationErrors, err.hints, { id: e.id });
         }
-        catch { /* ignore */ }
-        stReloaded = (0, indexContext_1.ensureLoaded)();
-    }
-    const createdNow = !existedBeforeOriginal;
-    const overwrittenNow = overwrite && existedBeforeOriginal;
-    let strictVerified = false;
-    const verifyIssues = [];
-    try {
-        let parsed;
-        // Verify from in-memory store first (covers SQLite), fall back to disk (JSON backend)
-        parsed = stReloaded.byId.get(e.id) ?? undefined;
-        if (!parsed) {
-            if (fs_1.default.existsSync(file)) {
-                let diskRaw;
+        if (!overwrite && (0, indexContext_1.isDuplicateInstructionWriteError)(err)) {
+            let st0 = await (0, indexContext_1.ensureLoadedAsync)();
+            let visible = st0.byId.has(e.id);
+            let repaired = false;
+            if (!visible) {
                 try {
-                    diskRaw = fs_1.default.readFileSync(file, 'utf8');
-                }
-                catch (ex) {
-                    verifyIssues.push('read-failed:' + ex.message);
-                }
-                if (diskRaw) {
-                    try {
-                        parsed = JSON.parse(diskRaw);
-                    }
-                    catch (ex) {
-                        verifyIssues.push('parse-failed:' + ex.message);
-                    }
+                    (0, indexContext_1.invalidate)();
+                    st0 = await (0, indexContext_1.ensureLoadedAsync)();
+                    visible = st0.byId.has(e.id);
+                    if (visible)
+                        repaired = true;
                 }
+                catch { /* ignore reload */ }
             }
-        }
-        if (parsed) {
-            if (parsed.id !== e.id)
-                verifyIssues.push('id-mismatch');
-            if (!parsed.title)
-                verifyIssues.push('missing-title');
-            if (!parsed.body)
-                verifyIssues.push('missing-body');
-            const wantCats = Array.isArray(e.categories) ? e.categories.filter((c) => typeof c === 'string').map(c => c.toLowerCase()) : [];
-            if (wantCats.length) {
-                for (const c of wantCats) {
-                    if (!parsed.categories?.includes(c)) {
-                        verifyIssues.push('missing-category:' + c);
-                    }
-                }
+            (0, auditLog_1.logAudit)('add', e.id, { skipped: true, late_visible: visible, repaired, duplicateAtWrite: true });
+            if ((0, instructions_shared_1.traceVisibility)()) {
+                (0, tracing_1.emitTrace)('[trace:add:skip]', { id: e.id, visible, repaired, duplicateAtWrite: true });
             }
-        }
-        const mem = stReloaded.byId.get(e.id);
-        if (!mem) {
-            verifyIssues.push('not-in-index');
-        }
-        const wantCats2 = Array.isArray(e.categories) ? e.categories.filter((c) => typeof c === 'string').map(c => c.toLowerCase()) : [];
-        if (wantCats2.length) {
-            const catHit = stReloaded.list.some(rec => rec.id === e.id && wantCats2.every(c => rec.categories.includes(c)));
-            if (!catHit)
-                verifyIssues.push('category-query-miss');
-        }
-        try {
-            if (parsed) {
-                const classifier2 = new classificationService_1.ClassificationService();
-                const issues = classifier2.validate(parsed);
-                if (issues.length) {
-                    verifyIssues.push('classification-issues:' + issues.join(','));
-                }
+            if ((0, instructions_shared_1.traceVisibility)()) {
+                (0, instructions_shared_1.traceInstructionVisibility)(e.id, 'add-skip-post-write-conflict', { visible, repaired });
+                if (!visible)
+                    (0, instructions_shared_1.traceEnvSnapshot)('add-skip-anomalous', { repaired });
             }
-        }
-        catch (err) {
-            verifyIssues.push('classification-exception:' + err.message);
-        }
-        if (verifyIssues.includes('not-in-index')) {
-            try {
-                (0, indexContext_1.invalidate)();
-                const st2 = (0, indexContext_1.ensureLoaded)();
-                if (st2.byId.has(e.id)) {
-                    const idx = verifyIssues.indexOf('not-in-index');
-                    if (idx >= 0)
-                        verifyIssues.splice(idx, 1);
+            if (!visible) {
+                const existingLoadError = st0.loadErrors?.find((issue) => {
+                    const fileName = path_1.default.basename(issue.file);
+                    return issue.file === `${e.id}.json` || fileName === `${e.id}.json` || issue.file.endsWith(`\\${e.id}.json`);
+                });
+                if (existingLoadError) {
+                    return {
+                        id: e.id,
+                        success: false,
+                        skipped: false,
+                        created: false,
+                        overwritten: false,
+                        hash: st0.hash,
+                        error: 'existing_instruction_invalid',
+                        validationErrors: [(0, instructionRecordValidation_1.sanitizeErrorDetail)(existingLoadError.error) || 'existing entry could not be parsed'],
+                    };
                 }
+                return { id: e.id, success: true, skipped: true, created: false, overwritten: false, hash: st0.hash, visibilityWarning: 'skipped_file_not_in_index' };
             }
-            catch { /* ignore */ }
+            return { id: e.id, success: true, skipped: true, created: false, overwritten: false, hash: st0.hash, repaired: repaired ? true : undefined };
         }
-        if (!verifyIssues.length)
-            strictVerified = true;
+        // Catch-all: never expose raw Node error text (ENOENT, null-byte path errors, stack frames) to MCP clients.
+        return fail('write_failed', {
+            id: e.id,
+            message: 'Instruction write failed due to an internal error. The error details are not exposed to clients.',
+        });
     }
-    catch (err) {
-        verifyIssues.push('verify-exception:' + err.message);
+    try {
+        (0, indexContext_1.touchIndexVersion)();
     }
+    catch { /* ignore */ }
+    const strictMode = instructionsCfg.strictVisibility || instructionsCfg.strictCreate;
+    const createdNow = !existedBeforeOriginal;
+    const overwrittenNow = overwrite && existedBeforeOriginal;
+    const verification = await verifyReadBack(e.id, file, e.categories);
     try {
         if (instructionsCfg.manifest.writeEnabled)
             (0, manifestManager_1.writeManifestFromIndex)();
@@ -503,8 +570,53 @@ const instructions_shared_1 = require("./instructions.shared");
             catch { /* ignore */ } });
     }
     catch { /* ignore manifest */ }
-    (0, auditLog_1.logAudit)('add', e.id, { created: createdNow, overwritten: overwrittenNow, verified: true, forcedReload: true });
+    (0, auditLog_1.logAudit)('add', e.id, {
+        created: createdNow,
+        overwritten: overwrittenNow,
+        verified: verification.verified,
+        strictVerified: verification.strictVerified,
+        verifyIssues: verification.verifyIssues.length ? verification.verifyIssues : undefined,
+        forcedReload: true,
+    });
     if ((0, instructions_shared_1.traceVisibility)())
-        (0, tracing_1.emitTrace)('[trace:add:forced-reload]', { id: e.id, created: createdNow, overwritten: overwrittenNow, hash: stReloaded.hash, strictVerified, issues: verifyIssues.slice(0, 5), strictMode });
-    return { id: e.id, created: createdNow, overwritten: overwrittenNow, skipped: false, hash: stReloaded.hash, verified: true, strictVerified, verifyIssues: verifyIssues.length ? verifyIssues : undefined, strictMode, bodyLength: bodyTrimmed.length };
+        (0, tracing_1.emitTrace)('[trace:add:forced-reload]', {
+            id: e.id,
+            created: createdNow,
+            overwritten: overwrittenNow,
+            hash: verification.stReloaded.hash,
+            verified: verification.verified,
+            strictVerified: verification.strictVerified,
+            issues: verification.verifyIssues.slice(0, 5),
+            strictMode,
+        });
+    if (!verification.verified) {
+        return {
+            ...fail('read-back verification failed', {
+                id: e.id,
+                hash: verification.stReloaded.hash,
+                message: 'Instruction write completed but read-back verification failed.',
+                validationErrors: verification.verifyIssues,
+            }),
+            created: createdNow,
+            overwritten: overwrittenNow,
+            verified: false,
+            strictVerified: verification.strictVerified,
+            verifyIssues: verification.verifyIssues,
+            strictMode,
+            bodyLength: bodyTrimmed.length,
+        };
+    }
+    return {
+        id: e.id,
+        success: true,
+        created: createdNow,
+        overwritten: overwrittenNow,
+        skipped: false,
+        hash: verification.stReloaded.hash,
+        verified: verification.verified,
+        strictVerified: verification.strictVerified,
+        verifyIssues: undefined,
+        strictMode,
+        bodyLength: bodyTrimmed.length,
+    };
 }));