@jagilber-org/index-server 1.22.0 → 1.26.1

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

@@ -15,11 +15,14 @@ const schemaVersion_1 = require("../../versioning/schemaVersion");
 const categoryRules_1 = require("../categoryRules");
 const canonical_1 = require("../canonical");
 const instructions_shared_1 = require("./instructions.shared");
+const loaderSchemaValidator_1 = require("../loaderSchemaValidator");
+const instructionRecordValidation_1 = require("../instructionRecordValidation");
 (0, registry_1.registerHandler)('index_enrich', (0, instructions_shared_1.guard)('index_enrich', () => {
     const st = (0, indexContext_1.ensureLoaded)();
     let rewritten = 0;
     const updated = [];
     const skipped = [];
+    const errors = [];
     for (const e of st.list) {
         // Use in-memory state as the raw record (works for both SQLite and JSON backends)
         const raw = { ...e };
@@ -27,7 +30,7 @@ const instructions_shared_1 = require("./instructions.shared");
             let needs = false;
             const nowIso = new Date().toISOString();
             if (!(typeof raw.sourceHash === 'string' && raw.sourceHash.length > 0)) {
-                raw.sourceHash = e.sourceHash || crypto_1.default.createHash('sha256').update(String(e.body || ''), 'utf8').digest('hex');
+                raw.sourceHash = e.sourceHash || (0, instructions_shared_1.computeSourceHash)(String(e.body || ''));
                 needs = true;
             }
             if (typeof raw.createdAt === 'string' && raw.createdAt.length === 0) {
@@ -109,7 +112,11 @@ const instructions_shared_1 = require("./instructions.shared");
                 skipped.push(e.id);
             }
         }
-        catch { /* ignore */ }
+        catch (err) {
+            const detail = err.message || 'unknown';
+            errors.push({ id: e.id, error: detail });
+            (0, auditLog_1.logAudit)('enrich_entry_error', e.id, { error: detail });
+        }
     }
     if (rewritten) {
         (0, indexContext_1.touchIndexVersion)();
@@ -117,8 +124,10 @@ const instructions_shared_1 = require("./instructions.shared");
         (0, indexContext_1.ensureLoaded)();
     }
     const resp = { rewritten, updated, skipped };
+    if (errors.length)
+        resp.errors = errors;
     if (rewritten) {
-        (0, auditLog_1.logAudit)('enrich', updated, { rewritten, skipped: skipped.length });
+        (0, auditLog_1.logAudit)('enrich', updated, { rewritten, skipped: skipped.length, errors: errors.length });
         (0, manifestManager_1.attemptManifestUpdate)();
     }
     return resp;
@@ -127,29 +136,98 @@ const instructions_shared_1 = require("./instructions.shared");
     const st = (0, indexContext_1.ensureLoaded)();
     const toFix = [];
     for (const e of st.list) {
-        const actual = crypto_1.default.createHash('sha256').update(e.body, 'utf8').digest('hex');
+        const actual = (0, instructions_shared_1.computeSourceHash)(e.body);
         if (actual !== e.sourceHash)
             toFix.push({ entry: e, actual });
     }
-    if (!toFix.length)
-        return { repaired: 0, updated: [] };
     const repaired = [];
+    const errors = [];
     for (const { entry, actual } of toFix) {
         try {
             const updated = { ...entry, sourceHash: actual, updatedAt: new Date().toISOString() };
             (0, indexContext_1.writeEntry)(updated);
             repaired.push(entry.id);
         }
-        catch { /* ignore */ }
+        catch (err) {
+            const detail = err.message || 'unknown';
+            errors.push({ id: entry.id, error: detail });
+            (0, auditLog_1.logAudit)('repair_entry_error', entry.id, { error: detail });
+        }
     }
-    if (repaired.length) {
+    // Repair skipped files: scan disk for .json files not in the loaded index (#207)
+    const skippedRepaired = [];
+    const skippedErrors = [];
+    try {
+        const dir = (0, indexContext_1.getInstructionsDir)();
+        const diskFiles = fs_1.default.readdirSync(dir).filter(f => f.endsWith('.json') && !f.startsWith('_'));
+        // Use the compiled-in schema property set so disk-resident vs static-import
+        // schemas can never diverge (review #211 finding 9).
+        const schemaProps = (0, loaderSchemaValidator_1.getSchemaPropertyNames)();
+        for (const file of diskFiles) {
+            const id = file.replace(/\.json$/, '');
+            if (st.byId.has(id))
+                continue; // already loaded, not skipped
+            const filePath = path_1.default.join(dir, file);
+            try {
+                const raw = JSON.parse(fs_1.default.readFileSync(filePath, 'utf8'));
+                if (!raw.id || !raw.body) {
+                    skippedErrors.push({ id, error: 'missing required fields (id or body)' });
+                    continue;
+                }
+                // Strip properties not in the JSON schema
+                if (schemaProps.size) {
+                    const keys = Object.keys(raw);
+                    let stripped = false;
+                    for (const key of keys) {
+                        if (!schemaProps.has(key)) {
+                            delete raw[key];
+                            stripped = true;
+                        }
+                    }
+                    if (stripped) {
+                        raw.sourceHash = (0, instructions_shared_1.computeSourceHash)(String(raw.body));
+                        raw.updatedAt = new Date().toISOString();
+                        // DI-4: mirror the loader's migration step before validating
+                        // against the loader schema, matching writeEntry/writeEntryAsync.
+                        // Without this, a stripped record carrying a legacy schemaVersion
+                        // would fail validateForDisk even though the loader would have
+                        // migrated it transparently on read.
+                        (0, schemaVersion_1.migrateInstructionRecord)(raw);
+                        // Gate the write through the same loader-schema validator the
+                        // primary writeEntry path uses (review #211 finding 3). If the
+                        // stripped record still fails validation, skip the write rather
+                        // than persisting a record that the next reload will silently
+                        // discard.
+                        const diskCheck = (0, loaderSchemaValidator_1.validateForDisk)(raw);
+                        if (!diskCheck.valid) {
+                            skippedErrors.push({ id, error: (0, instructionRecordValidation_1.sanitizeErrorDetail)(`schema validation failed: ${(diskCheck.errors || []).join('; ')}`) || 'schema validation failed' });
+                            continue;
+                        }
+                        fs_1.default.writeFileSync(filePath, JSON.stringify(raw, null, 2) + '\n', 'utf8');
+                        skippedRepaired.push(id);
+                    }
+                }
+            }
+            catch (err) {
+                // Sanitize the raw error before returning to the client (review #211 finding 6).
+                skippedErrors.push({ id, error: (0, instructionRecordValidation_1.sanitizeErrorDetail)(err.message) || 'unknown' });
+            }
+        }
+    }
+    catch (err) {
+        errors.push({ id: '__disk_scan__', error: (0, instructionRecordValidation_1.sanitizeErrorDetail)(`skipped-file scan failed: ${err.message || 'unknown'}`) || 'skipped-file scan failed' });
+    }
+    const allRepaired = [...repaired, ...skippedRepaired];
+    if (allRepaired.length) {
         (0, indexContext_1.touchIndexVersion)();
         (0, indexContext_1.invalidate)();
         (0, indexContext_1.ensureLoaded)();
     }
-    const resp = { repaired: repaired.length, updated: repaired };
-    if (repaired.length) {
-        (0, auditLog_1.logAudit)('repair', repaired, { repaired: repaired.length });
+    const resp = {
+        repaired: allRepaired.length, updated: repaired, skippedRepaired, errors: [...errors, ...skippedErrors]
+    };
+    if (allRepaired.length) {
+        (0, auditLog_1.logAudit)('repair', allRepaired, { repaired: allRepaired.length, skippedRepaired: skippedRepaired.length, errors: errors.length + skippedErrors.length });
         (0, manifestManager_1.attemptManifestUpdate)();
     }
     return resp;
@@ -222,12 +300,8 @@ const instructions_shared_1 = require("./instructions.shared");
             }
         }
     }
-    const isJunkCategory = (cat) => /^\d/.test(cat) || cat.length <= 1 || /^case-\d{6,}$/.test(cat);
     for (const e of byId.values()) {
-        let normCats = Array.from(new Set((e.categories || []).filter(c => typeof c === 'string').map(c => c.toLowerCase())));
-        normCats = normCats.filter(c => !isJunkCategory(c));
-        normCats = normCats.filter(cat => !(cat.endsWith('s') && normCats.includes(cat.slice(0, -1))));
-        normCats = normCats.sort();
+        const normCats = (0, instructions_shared_1.normalizeCategories)(e.categories || []);
         if (JSON.stringify(normCats) !== JSON.stringify(e.categories)) {
             e.categories = normCats;
             normalizedCategories++;
@@ -239,7 +313,7 @@ const instructions_shared_1 = require("./instructions.shared");
     if (mergeDuplicates) {
         const groups = new Map();
         for (const e of byId.values()) {
-            const key = e.sourceHash || crypto_1.default.createHash('sha256').update(e.body, 'utf8').digest('hex');
+            const key = e.sourceHash || (0, instructions_shared_1.computeSourceHash)(e.body);
             const arr = groups.get(key) || [];
             arr.push(e);
             groups.set(key, arr);
@@ -316,7 +390,9 @@ const instructions_shared_1 = require("./instructions.shared");
                     }
                 }
             }
-            catch { /* ignore */ }
+            catch (err) {
+                notes.push(`purgeLegacyScopes-failed:${e.id}:${err.message || String(err)}`);
+            }
         }
         if (dryRun && purgedScopes)
             notes.push(`would-purge:${purgedScopes}`);
@@ -328,10 +404,12 @@ const instructions_shared_1 = require("./instructions.shared");
             const derived = (0, categoryRules_1.deriveCategory)(e.id);
             if (derived === 'Other')
                 continue;
-            e.primaryCategory = derived.toLowerCase();
-            const lc = derived.toLowerCase();
-            if (!e.categories.includes(lc)) {
-                e.categories = [...e.categories, lc].sort();
+            const slug = (0, categoryRules_1.slugifyCategory)(derived);
+            if (!slug)
+                continue;
+            e.primaryCategory = slug;
+            if (!e.categories.includes(slug)) {
+                e.categories = [...e.categories, slug].sort();
             }
             e.updatedAt = new Date().toISOString();
             remappedCategories++;
@@ -341,7 +419,7 @@ const instructions_shared_1 = require("./instructions.shared");
     {
         for (const e of byId.values()) {
             const storedHash = e.sourceHash || '';
-            const actualHash = crypto_1.default.createHash('sha256').update(e.body, 'utf8').digest('hex');
+            const actualHash = (0, instructions_shared_1.computeSourceHash)(e.body);
             if (storedHash !== actualHash) {
                 e.sourceHash = actualHash;
                 repairedHashes++;
@@ -351,6 +429,7 @@ const instructions_shared_1 = require("./instructions.shared");
         }
     }
     deprecatedRemoved = toRemove.length;
+    const errors = [];
     if (!dryRun) {
         for (const id of toRemove) {
             byId.delete(id);
@@ -364,7 +443,10 @@ const instructions_shared_1 = require("./instructions.shared");
                 filesRewritten++;
             }
             catch (err) {
-                notes.push(`write-failed:${id}:${err.message}`);
+                const detail = err.message || String(err);
+                errors.push({ id, error: `write-failed: ${detail}` });
+                notes.push(`write-failed:${id}:${detail}`);
+                (0, auditLog_1.logAudit)('groom_entry_error', id, { error: detail, operation: 'write' });
             }
         }
         for (const id of toRemove) {
@@ -372,7 +454,10 @@ const instructions_shared_1 = require("./instructions.shared");
                 (0, indexContext_1.removeEntry)(id);
             }
             catch (err) {
-                notes.push(`delete-failed:${id}:${err.message}`);
+                const detail = err.message || String(err);
+                errors.push({ id, error: `delete-failed: ${detail}` });
+                notes.push(`delete-failed:${id}:${detail}`);
+                (0, auditLog_1.logAudit)('groom_entry_error', id, { error: detail, operation: 'delete' });
             }
         }
         if (updated.size || toRemove.length) {
@@ -389,8 +474,10 @@ const instructions_shared_1 = require("./instructions.shared");
     }
     const stAfter = (0, indexContext_1.ensureLoaded)();
     const resp = { previousHash, hash: stAfter.hash, scanned, repairedHashes, normalizedCategories, deprecatedRemoved, duplicatesMerged, signalApplied, filesRewritten, purgedScopes, migrated, remappedCategories, dryRun, notes };
+    if (errors.length)
+        resp.errors = errors;
     if (!dryRun && (repairedHashes || normalizedCategories || deprecatedRemoved || duplicatesMerged || signalApplied || filesRewritten || purgedScopes || migrated || remappedCategories)) {
-        (0, auditLog_1.logAudit)('groom', undefined, { repairedHashes, normalizedCategories, deprecatedRemoved, duplicatesMerged, signalApplied, filesRewritten, purgedScopes, migrated, remappedCategories });
+        (0, auditLog_1.logAudit)('groom', undefined, { repairedHashes, normalizedCategories, deprecatedRemoved, duplicatesMerged, signalApplied, filesRewritten, purgedScopes, migrated, remappedCategories, errors: errors.length });
         (0, manifestManager_1.attemptManifestUpdate)();
     }
     return resp;
@@ -409,6 +496,7 @@ const instructions_shared_1 = require("./instructions.shared");
     } });
     let scanned = 0, changed = 0, fixedHash = 0, fixedVersion = 0, fixedTier = 0, addedTimestamps = 0, addedContentType = 0;
     const updatedIds = [];
+    const errors = [];
     const scannedIds = new Set();
     const SEMVER = /^\d+\.\d+\.\d+(?:[-+].*)?$/;
     for (const dir of dirs) {
@@ -486,7 +574,8 @@ const instructions_shared_1 = require("./instructions.shared");
                     try {
                         (0, indexContext_1.writeEntry)(rec);
                     }
-                    catch {
+                    catch (err) {
+                        errors.push({ id: path_1.default.basename(full, '.json'), error: `write-failed: ${err.message || String(err)}` });
                         continue;
                     }
                 }
@@ -548,7 +637,8 @@ const instructions_shared_1 = require("./instructions.shared");
                     try {
                         (0, indexContext_1.writeEntry)(rec);
                     }
-                    catch {
+                    catch (err) {
+                        errors.push({ id: entry.id, error: `write-failed: ${err.message || String(err)}` });
                         continue;
                     }
                 }
@@ -563,13 +653,20 @@ const instructions_shared_1 = require("./instructions.shared");
             (0, indexContext_1.invalidate)();
             (0, indexContext_1.ensureLoaded)();
         }
-        catch { /* ignore */ }
+        catch (err) {
+            (0, auditLog_1.logAudit)('normalize_reload_error', undefined, { error: err.message });
+        }
         try {
             (0, manifestManager_1.attemptManifestUpdate)();
         }
-        catch { /* ignore */ }
+        catch (err) {
+            (0, auditLog_1.logAudit)('normalize_manifest_error', undefined, { error: err.message });
+        }
     }
-    return { scanned, changed, fixedHash, fixedVersion, fixedTier, addedTimestamps, addedContentType, dryRun, updated: updatedIds };
+    const normalizeResp = { scanned, changed, fixedHash, fixedVersion, fixedTier, addedTimestamps, addedContentType, dryRun, updated: updatedIds };
+    if (errors.length)
+        normalizeResp.errors = errors;
+    return normalizeResp;
 }));
 // usage_flush (mutation)
 (0, registry_1.registerHandler)('usage_flush', (0, instructions_shared_1.guard)('usage_flush', () => ({ flushed: true })));

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

@@ -12,6 +12,8 @@ const features_1 = require("../features");
 const schemaVersion_1 = require("../../versioning/schemaVersion");
 const classificationService_1 = require("../classificationService");
 const ownershipService_1 = require("../ownershipService");
+const instructionRecordValidation_1 = require("../instructionRecordValidation");
+const instructionRecordValidation_2 = require("../instructionRecordValidation");
 const auditLog_1 = require("../auditLog");
 const runtimeConfig_1 = require("../../config/runtimeConfig");
 const manifestManager_1 = require("../manifestManager");
@@ -39,7 +41,7 @@ function parseInlineEntries(rawEntries) {
         return { error: { error: 'entries JSON parse error', detail: e.message } };
     }
 }
-(0, registry_1.registerHandler)('index_import', (0, instructions_shared_1.guard)('index_import', (p) => {
+(0, registry_1.registerHandler)('index_import', (0, instructions_shared_1.guard)('index_import', async (p) => {
     let entries;
     const mode = p.mode || 'skip';
     if (Array.isArray(p.entries)) {
@@ -108,10 +110,21 @@ function parseInlineEntries(rawEntries) {
     let imported = 0, skipped = 0, overwritten = 0;
     const errors = [];
     const classifier = new classificationService_1.ClassificationService();
+    const skippedIds = new Set();
+    const formatImportValidationError = (validationErrors) => `invalid_instruction: ${validationErrors.join('; ')}`;
     for (const e of entries) {
-        if (!e || !e.id || !e.title || !e.body) {
-            const id = e?.id || 'unknown';
-            errors.push({ id, error: 'missing required fields' });
+        const id = e?.id || 'unknown';
+        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,
+            e?.priority === undefined ? 'priority: missing required field' : undefined,
+            e?.audience === undefined ? 'audience: missing required field' : undefined,
+            e?.requirement === undefined ? 'requirement: missing required field' : undefined,
+        ].filter((issue) => !!issue);
+        const surfaceValidation = e ? (0, instructionRecordValidation_1.validateInstructionInputSurface)(e) : { validationErrors: [], hints: [], schemaRef: 'index_add#input' };
+        if (!e || requiredFieldErrors.length || surfaceValidation.validationErrors.length) {
+            errors.push({ id, error: formatImportValidationError([...requiredFieldErrors, ...surfaceValidation.validationErrors]) });
             continue;
         }
         const bodyTrimmed = typeof e.body === 'string' ? e.body.trim() : String(e.body);
@@ -121,11 +134,11 @@ function parseInlineEntries(rawEntries) {
             continue;
         }
         const file = path_1.default.join(dir, `${e.id}.json`);
-        const stImport = (0, indexContext_1.ensureLoaded)();
+        const stImport = await (0, indexContext_1.ensureLoadedAsync)();
         const storeHas = stImport.byId.has(e.id);
         const fileExists = storeHas || fs_1.default.existsSync(file);
         const now = new Date().toISOString();
-        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);
         const primaryCategoryRaw = e.primaryCategory;
         if (!categories.length) {
             if (instructionsCfg.requireCategory) {
@@ -163,20 +176,11 @@ function parseInlineEntries(rawEntries) {
         }
         if (fileExists && mode === 'skip') {
             skipped++;
+            skippedIds.add(e.id);
             continue;
         }
-        if (fileExists && mode === 'overwrite')
-            overwritten++;
-        else if (!fileExists)
-            imported++;
         const base = existing ? { ...existing, title: e.title, body: bodyTrimmed, rationale: e.rationale, priority: e.priority, audience: e.audience, requirement: e.requirement, categories, primaryCategory: effectivePrimary, updatedAt: now } : { id: e.id, title: e.title, body: bodyTrimmed, rationale: e.rationale, priority: e.priority, audience: e.audience, requirement: e.requirement, categories, primaryCategory: effectivePrimary, sourceHash: newBodyHash, schemaVersion: schemaVersion_1.SCHEMA_VERSION, deprecatedBy: e.deprecatedBy, createdAt: now, updatedAt: now, riskScore: e.riskScore, createdByAgent: instructionsCfg.agentId, sourceWorkspace: instructionsCfg.workspaceId, extensions: e.extensions };
-        const govKeys = ['version', 'owner', 'status', 'priorityTier', 'classification', 'lastReviewedAt', 'nextReviewDue', 'changeLog', 'semanticSummary', 'contentType', 'extensions'];
-        for (const k of govKeys) {
-            const v = e[k];
-            if (v !== undefined) {
-                base[k] = v;
-            }
-        }
+        (0, instructions_shared_1.applyGovernanceKeys)(base, e, instructions_shared_1.IMPORT_GOVERNANCE_KEYS);
         if (!base.sourceWorkspace)
             base.sourceWorkspace = instructionsCfg.workspaceId;
         base.sourceHash = newBodyHash;
@@ -188,18 +192,47 @@ function parseInlineEntries(rawEntries) {
                 record.updatedAt = new Date().toISOString();
             }
         }
+        const recordValidation = (0, instructionRecordValidation_1.validateInstructionRecord)(record);
+        if (recordValidation.validationErrors.length) {
+            errors.push({ id: e.id, error: formatImportValidationError(recordValidation.validationErrors) });
+            continue;
+        }
         try {
-            (0, indexContext_1.writeEntry)(record);
+            await (0, indexContext_1.writeEntryAsync)(record);
         }
-        catch {
-            errors.push({ id: e.id, error: 'write-failed' });
+        catch (err) {
+            if ((0, instructionRecordValidation_2.isInstructionValidationError)(err)) {
+                errors.push({ id: e.id, error: formatImportValidationError(err.validationErrors) });
+                continue;
+            }
+            errors.push({ id: e.id, error: `write-failed: ${err.message || 'unknown'}` });
+            continue;
         }
+        if (fileExists && mode === 'overwrite')
+            overwritten++;
+        else if (!fileExists)
+            imported++;
     }
     (0, indexContext_1.touchIndexVersion)();
     (0, indexContext_1.invalidate)();
-    const st = (0, indexContext_1.ensureLoaded)();
-    const summary = { hash: st.hash, imported, skipped, overwritten, total: entries.length, errors };
-    (0, auditLog_1.logAudit)('import', entries.map(e => e.id), { imported, skipped, overwritten, errors: errors.length });
+    const st = await (0, indexContext_1.ensureLoadedAsync)();
+    // Read-back verification: confirm each written entry is visible in the reloaded index
+    const verificationErrors = [];
+    const writtenIds = entries
+        .filter(e => e.id && !errors.some(err => err.id === e.id) && !skippedIds.has(e.id))
+        .map(e => e.id);
+    for (const id of writtenIds) {
+        if (!st.byId.has(id)) {
+            verificationErrors.push({ id, error: 'not-in-index-after-reload' });
+        }
+    }
+    if (verificationErrors.length) {
+        errors.push(...verificationErrors);
+        (0, auditLog_1.logAudit)('import_verification', verificationErrors.map(v => v.id), { missingAfterReload: verificationErrors.length });
+    }
+    const verifiedCount = writtenIds.length - verificationErrors.length;
+    const summary = { hash: st.hash, imported, skipped, overwritten, total: entries.length, errors, verified: verificationErrors.length === 0, verifiedCount, verificationErrorCount: verificationErrors.length };
+    (0, auditLog_1.logAudit)('import', entries.map(e => e.id), { imported, skipped, overwritten, errors: errors.length, verified: verificationErrors.length === 0 });
     (0, manifestManager_1.attemptManifestUpdate)();
     return summary;
 }));

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

@@ -7,40 +7,58 @@ const manifestManager_1 = require("../manifestManager");
 const features_1 = require("../features");
 const instructions_shared_1 = require("./instructions.shared");
 (0, registry_1.registerHandler)('index_governanceHash', () => {
+    const reloadFailures = [];
+    let reloadSucceeded = false;
+    const captureReloadFailure = (stage, error) => {
+        const reason = error instanceof Error ? error.message : String(error);
+        reloadFailures.push(`${stage}: ${reason}`);
+    };
+    const reloadState = (stage) => {
+        (0, indexContext_1.invalidate)();
+        try {
+            const loaded = (0, indexContext_1.ensureLoaded)();
+            reloadSucceeded = true;
+            return loaded;
+        }
+        catch (error) {
+            captureReloadFailure(stage, error);
+            throw error;
+        }
+    };
     let st = (0, indexContext_1.ensureLoaded)();
     const now = Date.now();
     const loadedAgo = now - new Date(st.loadedAt).getTime();
     if (loadedAgo > 50) {
         try {
             // Force reload if stale — trust the store for freshness
-            (0, indexContext_1.invalidate)();
-            st = (0, indexContext_1.ensureLoaded)();
+            st = reloadState('stale-check');
         }
-        catch { /* ignore verification errors */ }
+        catch { /* handled below */ }
     }
     let projections = st.list.slice().sort((a, b) => a.id.localeCompare(b.id)).map(indexContext_1.projectGovernance);
     try {
         const storeCount = st.list.length;
         if (storeCount && (projections.length === 0 || projections.length < Math.floor(storeCount * 0.9))) {
             // Late materialization: reload from store to pick up any missing entries
-            (0, indexContext_1.invalidate)();
-            st = (0, indexContext_1.ensureLoaded)();
+            st = reloadState('late-materialization');
             projections = st.list.slice().sort((a, b) => a.id.localeCompare(b.id)).map(indexContext_1.projectGovernance);
         }
     }
-    catch { /* ignore defensive reload errors */ }
+    catch { /* handled below */ }
     const governanceHash = (0, indexContext_1.computeGovernanceHash)(st.list);
     if (projections.length && projections.length < Math.floor(st.list.length * 0.9) || projections.some(p => !p.owner)) {
         try {
-            (0, indexContext_1.invalidate)();
-            const st2 = (0, indexContext_1.ensureLoaded)();
+            const st2 = reloadState('projection-repair');
             projections = st2.list.slice().sort((a, b) => a.id.localeCompare(b.id)).map(indexContext_1.projectGovernance);
             try {
                 (0, features_1.incrementCounter)('governance:projectionRepair');
             }
-            catch { /* ignore */ }
+            catch { /* counter-only — non-critical */ }
         }
-        catch { /* ignore reload failure */ }
+        catch { /* handled below */ }
+    }
+    if (reloadFailures.length && !reloadSucceeded) {
+        throw new Error(`index_governanceHash could not refresh index state: ${reloadFailures.join('; ')}`);
     }
     return { count: projections.length, governanceHash, items: projections };
 });
@@ -48,8 +66,10 @@ const instructions_shared_1 = require("./instructions.shared");
     const id = p.id;
     const st = (0, indexContext_1.ensureLoaded)();
     const existing = st.byId.get(id);
-    if (!existing)
+    if (!existing) {
+        (0, auditLog_1.logAudit)('governanceUpdate', id, { changed: false, notFound: true });
         return { id, notFound: true };
+    }
     // Read from store (in-memory), fall back to disk for JSON backend
     const record = { ...existing };
     let changed = false;
@@ -63,6 +83,7 @@ const instructions_shared_1 = require("./instructions.shared");
         const allowed = ['draft', 'review', 'approved', 'deprecated'];
         const desired = p.status === 'active' ? 'approved' : p.status;
         if (!allowed.includes(desired)) {
+            (0, auditLog_1.logAudit)('governanceUpdate', id, { changed: false, error: 'invalid status', provided: p.status });
             return { id, error: 'invalid status', provided: p.status };
         }
         if (desired !== record.status) {
@@ -79,26 +100,10 @@ const instructions_shared_1 = require("./instructions.shared");
         changed = true;
     }
     if (bump && bump !== 'none') {
-        const parts = (record.version || '1.0.0').split('.').map(n => parseInt(n || '0', 10));
-        while (parts.length < 3)
-            parts.push(0);
-        if (bump === 'major')
-            parts[0]++;
-        else if (bump === 'minor')
-            parts[1]++;
-        else if (bump === 'patch')
-            parts[2]++;
-        if (bump === 'major') {
-            parts[1] = 0;
-            parts[2] = 0;
-        }
-        if (bump === 'minor') {
-            parts[2] = 0;
-        }
-        const newVersion = parts.join('.');
+        const newVersion = (0, instructions_shared_1.bumpVersion)(record.version, bump);
         if (newVersion !== record.version) {
             record.version = newVersion;
-            record.changeLog = [...(record.changeLog || []), { version: newVersion, changedAt: now, summary: `manual ${bump} bump via governanceUpdate` }];
+            record.changeLog = [...(record.changeLog || []), (0, instructions_shared_1.createChangeLogEntry)(newVersion, `manual ${bump} bump via governanceUpdate`)];
             changed = true;
         }
     }
@@ -108,14 +113,20 @@ const instructions_shared_1 = require("./instructions.shared");
     try {
         (0, indexContext_1.writeEntry)(record);
     }
-    catch {
-        return { id, error: 'write-failed' };
+    catch (err) {
+        const detail = err.message || 'unknown';
+        const errorType = err instanceof Error ? err.constructor.name : typeof err;
+        const stack = err instanceof Error ? err.stack?.slice(0, 500) : undefined;
+        // #132: full detail (including paths) only goes to the audit log; client gets a path-redacted version
+        const safeDetail = detail.replace(/[A-Za-z]:\\[^\s'"`]+/g, '<redacted-path>').replace(/\/(?:[^\s/'"`]+\/)+[^\s/'"`]+/g, '<redacted-path>');
+        (0, auditLog_1.logAudit)('governanceUpdate', id, { changed: false, error: detail, errorType, stack, writeFailure: true });
+        return { id, error: 'write-failed', detail: safeDetail, errorType };
     }
     (0, indexContext_1.touchIndexVersion)();
     (0, indexContext_1.invalidate)();
     (0, indexContext_1.ensureLoaded)();
     const resp = { id, changed: true, version: record.version, owner: record.owner, status: record.status, lastReviewedAt: record.lastReviewedAt, nextReviewDue: record.nextReviewDue };
-    (0, auditLog_1.logAudit)('governanceUpdate', id, { changed: true, version: record.version });
+    (0, auditLog_1.logAudit)('governanceUpdate', id, { changed: true, version: record.version, owner: record.owner, status: record.status, lastReviewedAt: record.lastReviewedAt, nextReviewDue: record.nextReviewDue });
     (0, manifestManager_1.attemptManifestUpdate)();
     return resp;
 }));