@jagilber-org/index-server 1.22.0

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

@@ -0,0 +1,469 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.instructionActions = void 0;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const registry_1 = require("../../server/registry");
+const indexContext_1 = require("../indexContext");
+const bootstrapGating_1 = require("../bootstrapGating");
+const classificationService_1 = require("../classificationService");
+const features_1 = require("../features");
+const runtimeConfig_1 = require("../../config/runtimeConfig");
+const tracing_1 = require("../tracing");
+const handlers_search_1 = require("../handlers.search");
+const instructions_shared_1 = require("./instructions.shared");
+// Legacy individual instruction handlers removed in favor of unified dispatcher (index_dispatch).
+// Internal implementation functions retained below for dispatcher direct invocation.
+exports.instructionActions = {
+    list: (p) => {
+        let st = (0, indexContext_1.ensureLoaded)();
+        const originalHash = st.hash;
+        let items = st.list;
+        if (p?.category) {
+            const c = p.category.toLowerCase();
+            items = items.filter(i => i.categories.includes(c));
+        }
+        if (p?.contentType) {
+            const ct = p.contentType;
+            items = items.filter(i => (i.contentType || 'instruction') === ct);
+        }
+        let attemptedReload = false;
+        const attemptedLate = false;
+        if (p?.expectId) {
+            const idx = items.findIndex(i => i.id === p.expectId);
+            if (idx > 0) {
+                const target = items[idx];
+                items = [target, ...items.slice(0, idx), ...items.slice(idx + 1)];
+            }
+        }
+        if (p?.expectId) {
+            try {
+                const inIndex = st.byId.has(p.expectId);
+                if (!inIndex) {
+                    attemptedReload = true;
+                    (0, indexContext_1.invalidate)();
+                    st = (0, indexContext_1.ensureLoaded)();
+                    items = st.list;
+                    if (p.category) {
+                        const c2 = p.category.toLowerCase();
+                        items = items.filter(i => i.categories.includes(c2));
+                    }
+                    if (st.byId.has(p.expectId)) {
+                        const idx2 = items.findIndex(i => i.id === p.expectId);
+                        if (idx2 > 0) {
+                            const target2 = items[idx2];
+                            items = [target2, ...items.slice(0, idx2), ...items.slice(idx2 + 1)];
+                        }
+                    }
+                }
+            }
+            catch { /* ignore repair errors */ }
+        }
+        if ((0, instructions_shared_1.traceVisibility)()) {
+            try {
+                const idsSample = items.slice(0, 5).map(i => i.id);
+                const expectId = p?.expectId;
+                const expectinIndex = expectId ? st.byId.has(expectId) : undefined;
+                (0, tracing_1.emitTrace)('[trace:list]', { total: st.list.length, filtered: items.length, sample: idsSample, expectId, expectinIndex, attemptedReload, attemptedLate, originalHash, finalHash: st.hash });
+            }
+            catch { /* ignore */ }
+        }
+        const totalCount = items.length;
+        // Apply offset/limit pagination when provided via REST bridge callers
+        const offset = typeof p?.offset === 'number' && p.offset > 0 ? p.offset : 0;
+        if (offset > 0) {
+            items = items.slice(offset);
+        }
+        if (typeof p?.limit === 'number' && p.limit > 0) {
+            items = items.slice(0, p.limit);
+        }
+        const resp = (0, instructions_shared_1.limitResponseSize)({ hash: st.hash, count: totalCount, items });
+        return resp;
+    },
+    listScoped: (p) => {
+        const st = (0, indexContext_1.ensureLoaded)();
+        const userId = p.userId?.toLowerCase();
+        const workspaceId = p.workspaceId?.toLowerCase();
+        const teamIds = (p.teamIds || []).map(t => t.toLowerCase());
+        const all = st.list;
+        const matchUser = userId ? all.filter(e => (e.userId || '').toLowerCase() === userId) : [];
+        if (matchUser.length)
+            return { hash: st.hash, count: matchUser.length, scope: 'user', items: matchUser };
+        const matchWorkspace = workspaceId ? all.filter(e => (e.workspaceId || '').toLowerCase() === workspaceId) : [];
+        if (matchWorkspace.length)
+            return { hash: st.hash, count: matchWorkspace.length, scope: 'workspace', items: matchWorkspace };
+        const teamSet = new Set(teamIds);
+        const matchTeams = teamIds.length ? all.filter(e => Array.isArray(e.teamIds) && e.teamIds.some(t => teamSet.has(t.toLowerCase()))) : [];
+        if (matchTeams.length)
+            return { hash: st.hash, count: matchTeams.length, scope: 'team', items: matchTeams };
+        const audienceAll = all.filter(e => e.audience === 'all');
+        return { hash: st.hash, count: audienceAll.length, scope: 'all', items: audienceAll };
+    },
+    get: (p) => {
+        const st = (0, indexContext_1.ensureLoaded)();
+        const item = st.byId.get(p.id);
+        if (!item && (0, runtimeConfig_1.getRuntimeConfig)().instructions.strictVisibility) {
+            const enhanced = exports.instructionActions.getEnhanced({ id: p.id });
+            if (enhanced.item)
+                return { hash: enhanced.hash || st.hash, item: enhanced.item };
+        }
+        if ((0, instructions_shared_1.traceVisibility)()) {
+            const dir = (0, indexContext_1.getInstructionsDir)();
+            (0, tracing_1.emitTrace)('[trace:get]', { dir, id: p.id, found: !!item, total: st.list.length, strict: (0, runtimeConfig_1.getRuntimeConfig)().instructions.strictVisibility });
+            (0, instructions_shared_1.traceInstructionVisibility)(p.id, item ? 'get-found' : 'get-not-found');
+            if (!item)
+                (0, instructions_shared_1.traceEnvSnapshot)('get-not-found');
+        }
+        return item ? { hash: st.hash, item } : { notFound: true, id: p.id, hint: `No instruction found with id "${p.id}". Use action="search" with q="<keyword>" to find valid ids, or action="list" to see all.`, example: { action: 'get', id: 'valid-instruction-id' } };
+    },
+    getEnhanced: (p) => {
+        let st = (0, indexContext_1.ensureLoaded)();
+        let item = st.byId.get(p.id);
+        if (item)
+            return { hash: st.hash, item };
+        // Not in current in-memory index — force reload from store (covers SQLite and JSON)
+        let repaired = false;
+        try {
+            (0, instructions_shared_1.traceInstructionVisibility)(p.id, 'getEnhanced-start');
+            (0, indexContext_1.invalidate)();
+            st = (0, indexContext_1.ensureLoaded)();
+            item = st.byId.get(p.id);
+            if (item) {
+                repaired = true;
+            }
+            if (!repaired) {
+                (0, features_1.incrementCounter)('instructions:getLateMaterializeNotFound');
+            }
+        }
+        catch { /* swallow */ }
+        if ((0, instructions_shared_1.traceVisibility)()) {
+            (0, tracing_1.emitTrace)('[trace:get:late-materialize]', { id: p.id, repaired });
+        }
+        (0, instructions_shared_1.traceInstructionVisibility)(p.id, 'getEnhanced-end', { repaired, finalFound: !!item });
+        return item ? { hash: st.hash, item } : { notFound: true };
+    },
+    search: async (p) => {
+        const providedKeywords = Array.isArray(p.keywords)
+            ? p.keywords.filter((keyword) => typeof keyword === 'string' && keyword.trim().length > 0)
+            : [];
+        const keywords = providedKeywords.length > 0
+            ? providedKeywords
+            : (typeof p.q === 'string' && p.q.trim().length > 0 ? [p.q] : []);
+        const searchResult = await (0, handlers_search_1.handleInstructionsSearch)({
+            keywords,
+            mode: p.mode,
+            limit: p.limit,
+            includeCategories: p.includeCategories ?? true,
+            caseSensitive: p.caseSensitive,
+            contentType: p.contentType,
+        });
+        const st = (0, indexContext_1.ensureLoaded)();
+        const items = searchResult.results
+            .map(result => st.byId.get(result.instructionId))
+            .filter((item) => !!item);
+        if ((0, instructions_shared_1.traceVisibility)()) {
+            const dir = (0, indexContext_1.getInstructionsDir)();
+            const sample = items.slice(0, 5).map(i => i.id);
+            (0, tracing_1.emitTrace)('[trace:search]', { dir, q: keywords.join(' '), matches: items.length, sample });
+        }
+        return {
+            hash: st.hash,
+            count: items.length,
+            totalMatches: searchResult.totalMatches,
+            items,
+            results: searchResult.results,
+            query: searchResult.query,
+            autoTokenized: searchResult.autoTokenized,
+            hints: searchResult.hints,
+        };
+    },
+    diff: (p) => {
+        const st = (0, indexContext_1.ensureLoaded)();
+        const clientHash = p.clientHash;
+        const known = p.known;
+        if (!known && clientHash && clientHash === st.hash)
+            return { upToDate: true, hash: st.hash };
+        if (known) {
+            const map = new Map();
+            for (const k of known) {
+                if (k && k.id && !map.has(k.id))
+                    map.set(k.id, k.sourceHash);
+            }
+            const added = [];
+            const updated = [];
+            const removed = [];
+            for (const e of st.list) {
+                const prev = map.get(e.id);
+                if (prev === undefined)
+                    added.push(e);
+                else if (prev !== e.sourceHash)
+                    updated.push(e);
+            }
+            for (const id of map.keys()) {
+                if (!st.byId.has(id))
+                    removed.push(id);
+            }
+            if (!added.length && !updated.length && !removed.length && clientHash === st.hash)
+                return { upToDate: true, hash: st.hash };
+            return { hash: st.hash, added, updated, removed };
+        }
+        if (!clientHash || clientHash !== st.hash)
+            return { hash: st.hash, changed: st.list };
+        return { upToDate: true, hash: st.hash };
+    },
+    export: (p) => {
+        const st = (0, indexContext_1.ensureLoaded)();
+        let items = st.list;
+        if (p?.ids?.length) {
+            const want = new Set(p.ids);
+            items = items.filter(i => want.has(i.id));
+        }
+        if (p?.metaOnly) {
+            items = items.map(i => ({ ...i, body: '' }));
+        }
+        return (0, instructions_shared_1.limitResponseSize)({ hash: st.hash, count: items.length, items });
+    },
+    query: (p) => {
+        const st = (0, indexContext_1.ensureLoaded)();
+        if ((0, instructions_shared_1.traceVisibility)()) {
+            try {
+                (0, tracing_1.emitTrace)('[trace:query:start]', { pid: process.pid, dir: (0, indexContext_1.getInstructionsDir)(), keys: Object.keys(p || {}), categoriesAny: p.categoriesAny, categoriesAll: p.categoriesAll, excludeCategories: p.excludeCategories });
+            }
+            catch { /* ignore */ }
+        }
+        const norm = (arr) => Array.from(new Set((arr || []).filter(x => typeof x === 'string' && x.trim()).map(x => x.toLowerCase())));
+        const catsAll = norm(p.categoriesAll);
+        const catsAny = norm(p.categoriesAny);
+        const catsEx = norm(p.excludeCategories);
+        const tierSet = new Set((p.priorityTiers || []).filter(t => ['P1', 'P2', 'P3', 'P4'].includes(String(t))));
+        const reqSet = new Set((p.requirements || []).filter(r => ['mandatory', 'critical', 'recommended', 'optional', 'deprecated'].includes(String(r))));
+        const prMin = typeof p.priorityMin === 'number' ? p.priorityMin : undefined;
+        const prMax = typeof p.priorityMax === 'number' ? p.priorityMax : undefined;
+        const text = (p.text || '').toLowerCase().trim();
+        let items = st.list;
+        const instructionsCfg = (0, runtimeConfig_1.getRuntimeConfig)().instructions;
+        const diagActive = instructionsCfg.traceQueryDiag && (catsAll.length || catsAny.length || catsEx.length || text.length);
+        const stages = [];
+        const pushStage = (stage, note) => { if (diagActive)
+            stages.push({ stage, count: items.length, note }); };
+        if (diagActive)
+            pushStage('loaded');
+        let preFilterSample;
+        if (diagActive) {
+            preFilterSample = items.slice(0, 25).map(i => i.id);
+        }
+        const preCount = items.length;
+        if (catsAll.length) {
+            items = items.filter(e => catsAll.every(c => e.categories.includes(c)));
+            pushStage('catsAll');
+        }
+        if (catsAny.length) {
+            const before = items.length;
+            items = items.filter(e => e.categories.some(c => catsAny.includes(c)));
+            pushStage('catsAny', before !== items.length ? undefined : 'no-change');
+        }
+        if (catsEx.length) {
+            items = items.filter(e => !e.categories.some(c => catsEx.includes(c)));
+            pushStage('catsEx');
+        }
+        if (p?.contentType) {
+            const ct = p.contentType;
+            items = items.filter(i => (i.contentType || 'instruction') === ct);
+            pushStage('contentType');
+        }
+        if (prMin !== undefined) {
+            items = items.filter(e => e.priority >= prMin);
+            pushStage('prMin');
+        }
+        if (prMax !== undefined) {
+            items = items.filter(e => e.priority <= prMax);
+            pushStage('prMax');
+        }
+        if (tierSet.size) {
+            items = items.filter(e => e.priorityTier && tierSet.has(e.priorityTier));
+            pushStage('tiers');
+        }
+        if (reqSet.size) {
+            items = items.filter(e => reqSet.has(e.requirement));
+            pushStage('requirements');
+        }
+        if (text) {
+            items = items.filter(e => e.title.toLowerCase().includes(text) || e.body.toLowerCase().includes(text) || (e.semanticSummary || '').toLowerCase().includes(text));
+            pushStage('text');
+        }
+        try {
+            const recent = st._recentAdds;
+            if (recent) {
+                const now = Date.now();
+                const GRACE = 300;
+                for (const [id, meta] of Object.entries(recent)) {
+                    if (now - meta.ts > GRACE)
+                        continue;
+                    if (items.some(e => e.id === id))
+                        continue;
+                    const catMatchAll = !catsAll.length || catsAll.every(c => meta.categories.includes(c));
+                    const catMatchAny = !catsAny.length || meta.categories.some(c => catsAny.includes(c));
+                    const catExcluded = catsEx.length && meta.categories.some(c => catsEx.includes(c));
+                    if (catMatchAll && catMatchAny && !catExcluded) {
+                        const injected = st.byId.get(id);
+                        if (injected) {
+                            items = items.concat([injected]);
+                            if ((0, instructions_shared_1.traceVisibility)())
+                                (0, tracing_1.emitTrace)('[trace:query:recent-add-injected]', { id, graceMs: now - meta.ts });
+                        }
+                    }
+                }
+            }
+        }
+        catch { /* ignore fallback */ }
+        const total = items.length;
+        const limit = Math.min(Math.max((p.limit ?? 100), 1), 1000);
+        const offset = Math.max((p.offset ?? 0), 0);
+        const paged = items.slice(offset, offset + limit);
+        if ((0, instructions_shared_1.traceVisibility)()) {
+            const sample = paged.slice(0, 5).map(i => i.id);
+            (0, tracing_1.emitTrace)('[trace:query]', { applied: { catsAll, catsAny, catsEx, prMin, prMax, tiers: [...tierSet], requirements: [...reqSet], text: text || undefined }, preCount, total, returned: paged.length, sample });
+            if (diagActive) {
+                const suspicious = paged.length === 0 || paged.length < Math.min(3, preCount);
+                if (suspicious) {
+                    const categoryDiagnostics = {};
+                    for (const c of catsAny) {
+                        let present = 0;
+                        let passed = 0;
+                        const sampleIds = [];
+                        for (const e of st.list) {
+                            if (e.categories.includes(c)) {
+                                present++;
+                                if (items.includes(e)) {
+                                    passed++;
+                                    if (sampleIds.length < 5)
+                                        sampleIds.push(e.id);
+                                }
+                            }
+                        }
+                        categoryDiagnostics[c] = { present, passedAllFilters: passed, sampleIds };
+                    }
+                    (0, tracing_1.emitTrace)('[trace:query:diag]', { preFilterSample, stages, categoryDiagnostics, finalReturned: paged.length, totalAfterFilters: total, preCount });
+                }
+            }
+        }
+        return { hash: st.hash, total, count: paged.length, offset, limit, items: paged, applied: { catsAll, catsAny, catsEx, prMin, prMax, tiers: [...tierSet], requirements: [...reqSet], text: text || undefined } };
+    },
+    categories: (_p) => {
+        const st = (0, indexContext_1.ensureLoaded)();
+        const counts = new Map();
+        for (const e of st.list) {
+            for (const c of e.categories) {
+                counts.set(c, (counts.get(c) || 0) + 1);
+            }
+        }
+        const categories = [...counts.entries()].sort((a, b) => a[0].localeCompare(b[0])).map(([name, count]) => ({ name, count }));
+        return { count: categories.length, categories };
+    },
+    dir: () => {
+        const dir = (0, indexContext_1.getInstructionsDir)();
+        const st = (0, indexContext_1.ensureLoaded)();
+        const files = st.list.map(e => `${e.id}.json`).sort();
+        return { dir, filesCount: files.length, files };
+    }
+};
+// Deep inspection (diagnostics) — reads from store, not disk
+(0, registry_1.registerHandler)('index_inspect', (p) => {
+    const id = p.id;
+    if (!id)
+        return { error: 'missing id' };
+    const st = (0, indexContext_1.ensureLoaded)();
+    const entry = st.byId.get(id);
+    if (!entry)
+        return { id, exists: false, fileMissing: true };
+    let schemaErrors;
+    let classificationIssues;
+    let normalized;
+    try {
+        const rec = entry;
+        const missing = [];
+        if (!rec.id)
+            missing.push('missing id');
+        if (!rec.title)
+            missing.push('missing title');
+        if (!rec.body)
+            missing.push('missing body');
+        if (missing.length)
+            schemaErrors = missing.join(', ');
+        const classifier = new classificationService_1.ClassificationService();
+        if (!schemaErrors) {
+            classificationIssues = classifier.validate(rec);
+            if (!classificationIssues.length) {
+                normalized = classifier.normalize(rec);
+            }
+        }
+    }
+    catch (err) {
+        schemaErrors = err.message;
+    }
+    return { id, exists: true, schemaErrors, classificationIssues, normalized, raw: entry };
+});
+(0, registry_1.registerHandler)('index_health', () => {
+    const st = (0, indexContext_1.ensureLoaded)();
+    const governanceHash = (0, indexContext_1.computeGovernanceHash)(st.list);
+    const summary = st.loadSummary || { scanned: st.loadDebug?.scanned ?? st.list.length, accepted: st.list.length, skipped: (st.loadDebug ? (st.loadDebug.scanned - st.loadDebug.accepted) : 0), reasons: {} };
+    const total = st.list.length || 1;
+    const governanceKeywords = ['constitution', 'quality gate', 'p1 ', 'p0 ', 'lifecycle', 'governance', 'bootstrapper'];
+    let governanceLike = 0;
+    let keywordHit = 0;
+    for (const e of st.list) {
+        const body = (e.body || '').toLowerCase();
+        const title = (e.title || '').toLowerCase();
+        const composite = title + '\n' + body.slice(0, 2000);
+        if (/__governance_seed__/.test(composite) || /^000-bootstrapper/.test(e.id) || /^001-knowledge-index-lifecycle/.test(e.id)) {
+            governanceLike++;
+            continue;
+        }
+        if (governanceKeywords.some(k => composite.includes(k))) {
+            keywordHit++;
+        }
+    }
+    const leakageRatio = governanceLike / total;
+    const effectiveGovernanceLike = ((0, indexContext_1.ensureLoaded)().list.filter(e => e && e.id && !bootstrapGating_1.BOOTSTRAP_ALLOWLIST.has(e.id)).length === 0) ? 0 : governanceLike;
+    let recursionRisk;
+    try {
+        const st3 = (0, indexContext_1.ensureLoaded)();
+        const allowlistedCount = st3.list.filter(e => bootstrapGating_1.BOOTSTRAP_ALLOWLIST.has(e.id)).length;
+        const adjusted = Math.max(0, governanceLike - allowlistedCount);
+        recursionRisk = adjusted === 0 ? 'none' : (leakageRatio < 0.01 ? 'warning' : 'critical');
+    }
+    catch {
+        recursionRisk = effectiveGovernanceLike === 0 ? 'none' : (leakageRatio < 0.01 ? 'warning' : 'critical');
+    }
+    const snapshot = path_1.default.join(process.cwd(), 'snapshots', 'canonical-instructions.json');
+    if (!fs_1.default.existsSync(snapshot))
+        return { snapshot: 'missing', hash: st.hash, count: st.list.length, governanceHash, recursionRisk, leakage: { governanceLike, keywordHit, leakageRatio }, summary };
+    try {
+        const raw = JSON.parse(fs_1.default.readFileSync(snapshot, 'utf8'));
+        const snapItems = raw.items || [];
+        const snapMap = new Map(snapItems.map(i => [i.id, i.sourceHash]));
+        const missing = [];
+        const changed = [];
+        for (const e of st.list) {
+            const h = snapMap.get(e.id);
+            if (h === undefined)
+                missing.push(e.id);
+            else if (h !== e.sourceHash)
+                changed.push(e.id);
+        }
+        const extra = snapItems.filter(i => !st.byId.has(i.id)).map(i => i.id);
+        return { snapshot: 'present', hash: st.hash, count: st.list.length, missing, changed, extra, drift: missing.length + changed.length + extra.length, governanceHash, recursionRisk, leakage: { governanceLike, keywordHit, leakageRatio }, summary };
+    }
+    catch (e) {
+        return { snapshot: 'error', error: e instanceof Error ? e.message : String(e), hash: st.hash, governanceHash, recursionRisk, leakage: { governanceLike, keywordHit, leakageRatio }, summary };
+    }
+});
+(0, registry_1.registerHandler)('index_debug', () => {
+    const before = (0, indexContext_1.getDebugIndexSnapshot)();
+    const st = (0, indexContext_1.ensureLoaded)();
+    const after = { hash: st.hash, count: st.list.length };
+    return { before, after };
+});

package/dist/services/handlers/instructions.reload.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const registry_1 = require("../../server/registry");
+const indexContext_1 = require("../indexContext");
+const auditLog_1 = require("../auditLog");
+const instructions_shared_1 = require("./instructions.shared");
+(0, registry_1.registerHandler)('index_reload', (0, instructions_shared_1.guard)('index_reload', () => {
+    (0, indexContext_1.invalidate)();
+    const st = (0, indexContext_1.ensureLoaded)();
+    const resp = { reloaded: true, hash: st.hash, count: st.list.length };
+    (0, auditLog_1.logAudit)('reload', undefined, { count: st.list.length });
+    return resp;
+}));

package/dist/services/handlers/instructions.remove.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,122 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const registry_1 = require("../../server/registry");
+const indexContext_1 = require("../indexContext");
+const auditLog_1 = require("../auditLog");
+const runtimeConfig_1 = require("../../config/runtimeConfig");
+const manifestManager_1 = require("../manifestManager");
+const tracing_1 = require("../tracing");
+const instructions_shared_1 = require("./instructions.shared");
+const backupZip_1 = require("../backupZip");
+function backupInstructionsDir() {
+    const cfg = (0, runtimeConfig_1.getRuntimeConfig)();
+    const base = (0, indexContext_1.getInstructionsDir)();
+    const backupsRoot = cfg.dashboard.admin.backupsDir;
+    fs_1.default.mkdirSync(backupsRoot, { recursive: true });
+    const stamp = new Date().toISOString().replace(/[:.]/g, '').replace('T', '-').slice(0, 15);
+    let zipPath = path_1.default.join(backupsRoot, `instructions-${stamp}.zip`);
+    let i = 1;
+    while (fs_1.default.existsSync(zipPath)) {
+        zipPath = path_1.default.join(backupsRoot, `instructions-${stamp}-${i++}.zip`);
+    }
+    (0, backupZip_1.createZipBackup)(base, zipPath);
+    return zipPath;
+}
+(0, registry_1.registerHandler)('index_remove', (0, instructions_shared_1.guard)('index_remove', (p) => {
+    const ids = Array.isArray(p.ids) ? Array.from(new Set(p.ids.filter(x => typeof x === 'string' && x.trim()))) : [];
+    if (!ids.length)
+        return { removed: 0, removedIds: [], missing: [], errorCount: 0, errors: ['no ids supplied'] };
+    const base = (0, indexContext_1.getInstructionsDir)();
+    const cfg = (0, runtimeConfig_1.getRuntimeConfig)();
+    const instructionsCfg = cfg.instructions;
+    const mutationCfg = cfg.mutation;
+    const maxBulk = mutationCfg.maxBulkDelete;
+    if (p.dryRun) {
+        const wouldRemove = [];
+        const wouldMiss = [];
+        const stDry = (0, indexContext_1.ensureLoaded)();
+        for (const id of ids) {
+            const file = path_1.default.join(base, `${id}.json`);
+            if (fs_1.default.existsSync(file) || stDry.byId.has(id)) {
+                wouldRemove.push(id);
+            }
+            else {
+                wouldMiss.push(id);
+            }
+        }
+        return { dryRun: true, wouldRemove: wouldRemove.length, wouldRemoveIds: wouldRemove, wouldMiss, removed: 0 };
+    }
+    if (ids.length > maxBulk && !p.force) {
+        (0, auditLog_1.logAudit)('remove_blocked', ids, { count: ids.length, maxBulkDelete: maxBulk, reason: 'bulk_limit_exceeded' });
+        return { removed: 0, removedIds: [], missing: [], errorCount: 1, errors: [`Bulk delete blocked: ${ids.length} IDs exceeds INDEX_SERVER_MAX_BULK_DELETE=${maxBulk}. Pass force=true to proceed (a backup will be created first).`], bulkBlocked: true, maxBulkDelete: maxBulk, requestedCount: ids.length };
+    }
+    let backupDir;
+    if (ids.length > maxBulk && mutationCfg.backupBeforeBulkDelete) {
+        try {
+            backupDir = backupInstructionsDir();
+            (0, auditLog_1.logAudit)('remove_backup', ids, { backupDir, count: ids.length });
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : 'backup-failed';
+            (0, auditLog_1.logAudit)('remove_backup_failed', ids, { error: msg, count: ids.length });
+            return { removed: 0, removedIds: [], missing: [], errorCount: 1, errors: [`Bulk delete aborted: pre-mutation backup failed: ${msg}`], backupFailed: true };
+        }
+    }
+    const missing = [];
+    const removed = [];
+    const errors = [];
+    const stPre = (0, indexContext_1.ensureLoaded)();
+    for (const id of ids) {
+        const file = path_1.default.join(base, `${id}.json`);
+        try {
+            if (!fs_1.default.existsSync(file) && !stPre.byId.has(id)) {
+                missing.push(id);
+                continue;
+            }
+            (0, indexContext_1.removeEntry)(id);
+            removed.push(id);
+        }
+        catch (e) {
+            errors.push({ id, error: e instanceof Error ? e.message : 'delete-failed' });
+        }
+    }
+    if (removed.length) {
+        (0, indexContext_1.touchIndexVersion)();
+        (0, indexContext_1.invalidate)();
+    }
+    let st = (0, indexContext_1.ensureLoaded)();
+    const strictRemove = instructionsCfg.strictRemove;
+    let strictFailed = [];
+    if (strictRemove) {
+        const stillVisible = removed.filter(id => st.byId.has(id));
+        if (stillVisible.length) {
+            try {
+                (0, indexContext_1.invalidate)();
+                st = (0, indexContext_1.ensureLoaded)();
+            }
+            catch { /* ignore */ }
+        }
+        strictFailed = removed.filter(id => st.byId.has(id));
+        if (strictFailed.length && (0, instructions_shared_1.traceVisibility)())
+            (0, tracing_1.emitTrace)('[trace:remove:strict-failed]', { ids: strictFailed });
+    }
+    const resp = { removed: removed.length, removedIds: removed, missing, errorCount: errors.length + (strictFailed.length ? 1 : 0), errors, strictVerified: strictRemove ? (strictFailed.length === 0) : undefined, strictFailed, backupDir };
+    if (strictRemove && strictFailed.length) {
+        (0, auditLog_1.logAudit)('remove', ids, { removed: removed.length, missing: missing.length, errors: errors.length, strict_failed: strictFailed.length, backupDir });
+        return resp;
+    }
+    (0, auditLog_1.logAudit)('remove', ids, { removed: removed.length, missing: missing.length, errors: errors.length, backupDir });
+    try {
+        setImmediate(() => { try {
+            (0, manifestManager_1.attemptManifestUpdate)();
+        }
+        catch { /* ignore */ } });
+    }
+    catch { /* ignore */ }
+    return resp;
+}));

package/dist/services/handlers/instructions.shared.d.ts

@@ -0,0 +1,32 @@
+import { InstructionEntry } from '../../models/instruction';
+export declare function isMutationEnabled(): boolean;
+export declare function isCI(): boolean;
+export declare function limitResponseSize<T extends Record<string, unknown>>(response: T): T;
+export interface ImportEntry {
+    id: string;
+    title: string;
+    body: string;
+    rationale?: string;
+    priority: number;
+    audience: InstructionEntry['audience'];
+    requirement: InstructionEntry['requirement'];
+    categories?: unknown[];
+    deprecatedBy?: string;
+    riskScore?: number;
+    version?: string;
+    owner?: string;
+    status?: InstructionEntry['status'];
+    priorityTier?: InstructionEntry['priorityTier'];
+    classification?: InstructionEntry['classification'];
+    lastReviewedAt?: string;
+    nextReviewDue?: string;
+    changeLog?: InstructionEntry['changeLog'];
+    semanticSummary?: string;
+    contentType?: InstructionEntry['contentType'];
+    extensions?: InstructionEntry['extensions'];
+}
+export declare function guard<TParams, TResult>(name: string, fn: (p: TParams) => TResult): (p: TParams) => TResult;
+export declare function traceVisibility(): boolean;
+export declare function traceInstructionVisibility(id: string, phase: string, extra?: Record<string, unknown>): void;
+export declare function traceEnvSnapshot(phase: string, extra?: Record<string, unknown>): void;
+export {};