@prodero/curator 0.0.0-stage → 0.1.0

package/dist/core/index.js

@@ -0,0 +1,93 @@
+import { PRODERO_SCHEMA_VERSION } from "./constants.js";
+import { loadMemoryCatalog } from "./memory-index.js";
+import { loadKnowledgeGraph } from "./knowledge-graph.js";
+import { checkedDataPath, ensureRuntimeDirectories, writeFileAtomic } from "./storage.js";
+import { listProjectSkills, skillContext } from "./skills.js";
+function line(item) { return `- [${item.title}](memory/${item.filename})`; }
+export const MAX_INDEX_REQUIRED_ITEMS = 16;
+export const MAX_INDEX_CONTEXTUAL_ITEMS = 128;
+function diverseContextual(items, limit) {
+    const groups = new Map();
+    for (const item of items) {
+        const key = item.scopeRef ?? item.scope;
+        const group = groups.get(key) ?? [];
+        group.push(item);
+        groups.set(key, group);
+    }
+    const orderedGroups = [...groups.entries()].sort(([a], [b]) => a.localeCompare(b));
+    const selected = [];
+    for (let offset = 0; selected.length < limit; offset += 1) {
+        let added = false;
+        for (const [, group] of orderedGroups) {
+            if (group[offset]) {
+                selected.push(group[offset]);
+                added = true;
+            }
+            if (selected.length >= limit)
+                break;
+        }
+        if (!added)
+            break;
+    }
+    return selected;
+}
+async function skillReferences(root) {
+    return (await listProjectSkills(root)).filter((skill) => skill.status === "active").map(skillContext);
+}
+export async function buildIndex(root) {
+    await ensureRuntimeDirectories(root);
+    const catalog = await loadMemoryCatalog(root);
+    const active = catalog.summaries.filter((item) => item.status === "active" && item.layer === "versioned");
+    const local = catalog.summaries.filter((item) => item.status === "active" && item.layer === "local");
+    const allRequired = active
+        .filter((item) => item.scope === "global" && item.contextPolicy === "required")
+        .sort((a, b) => (a.priority === b.priority ? 0 : a.priority === "critical" ? -1 : 1) || b.updatedAt.localeCompare(a.updatedAt) || a.title.localeCompare(b.title) || a.id.localeCompare(b.id));
+    const required = allRequired.slice(0, MAX_INDEX_REQUIRED_ITEMS);
+    const allRequiredIds = new Set(allRequired.map((item) => item.id));
+    const allContextual = active
+        .filter((item) => !allRequiredIds.has(item.id))
+        .sort((a, b) => (a.scopeRef ?? a.scope).localeCompare(b.scopeRef ?? b.scope) || a.title.localeCompare(b.title) || a.id.localeCompare(b.id));
+    const contextual = diverseContextual(allContextual, MAX_INDEX_CONTEXTUAL_ITEMS);
+    const skills = await skillReferences(root);
+    const text = `---
+prodero_schema: ${PRODERO_SCHEMA_VERSION}
+kind: project-index
+generated: true
+---
+
+# Prodero · Project Intelligence
+
+> Compact router for progressive context loading. Open only references relevant to the current task.
+
+## Required Global Context
+
+${required.length ? required.map(line).join("\n") : "_No required global knowledge._"}${allRequired.length > required.length ? `\n\n_${allRequired.length - required.length} additional required item(s) are available through bounded context resolution._` : ""}
+
+## Contextual Knowledge
+
+${contextual.length ? contextual.map((item) => `${line(item)} — ${item.scope}${item.scopeRef ? `: ${item.scopeRef}` : ""}; ${item.category}; ${item.priority}`).join("\n") : "_No contextual knowledge._"}${allContextual.length > contextual.length ? `\n\n_${allContextual.length - contextual.length} additional contextual item(s) are available through query-ranked resolution._` : ""}
+
+## Local Knowledge
+
+- [Developer-local knowledge](local/index.md) — ignored by Git and retrieved together with Versioned Knowledge.
+
+## Project Skills
+
+${skills.length ? skills.slice(0, 32).map((skill) => `- [${skill.title}](${skill.path})`).join("\n") : "_No project skills._"}
+
+## Loading Rules
+
+1. Use bounded context resolution; required global knowledge is priority-ranked and budgeted.
+2. Follow only bounded graph relationships selected by context resolution; never recursively load the graph or unrelated scopes.
+3. Load relevant project skills; do not recursively load \`.prodero/\`.
+4. Use session memory as the write path. Sync produces Git-ignored Local Knowledge.
+5. Use the promotion review workflow for Versioned Knowledge. Review repository changes before committing or pushing; Prodero does neither.
+`;
+    await writeFileAtomic(await checkedDataPath(root, "index.md"), text);
+    const localText = `# Prodero · Local Knowledge\n\n> Developer-local canonical knowledge. This directory is ignored by Git.\n\n${local.length ? local.sort((a, b) => a.title.localeCompare(b.title) || a.id.localeCompare(b.id)).map((item) => `- [${item.title}](memory/${item.filename}) — ${item.scope}${item.scopeRef ? `: ${item.scopeRef}` : ""}; ${item.category}; ${item.priority}`).join("\n") : "_No active local knowledge._"}\n`;
+    await writeFileAtomic(await checkedDataPath(root, "local", "index.md"), localText);
+    await loadKnowledgeGraph(root, catalog);
+    return text;
+}
+export { skillReferences };
+//# sourceMappingURL=index.js.map

package/dist/core/instruction-review.js

@@ -0,0 +1,86 @@
+import { applicabilityKey } from "./applicability.js";
+import { loadMemoryCatalog } from './memory-index.js';
+import { planAssistedSync } from './knowledge-engine.js';
+import { exactKnowledge } from './semantic-safety.js';
+import { INTELLIGENCE_LIMITS } from './intelligence.js';
+import { withSyncLock, recoverSyncTransaction, commitSyncTransaction, fileHash, safeProjectPath } from './sync-transaction.js';
+import { listCheckpoints } from './storage.js';
+import { sortableId } from './ids.js';
+import { parseKnowledge } from './memory.js';
+import { buildIndex } from './index.js';
+import { estimateTokens, knowledgeText } from './telemetry.js';
+export async function reviewOmittedInstructions(selection, offset = 0, criticalOnly = false) {
+    const catalog = await loadMemoryCatalog(selection.root);
+    const omitted = selection.omitted.filter(i => !criticalOnly || i.priority === 'critical');
+    const page = omitted.slice(offset, offset + 12);
+    const items = await Promise.all(page.map(async (selected) => {
+        const summary = catalog.summaries.find(i => i.id === selected.id);
+        if (!summary)
+            return { selection: selected, item: null, missing: true };
+        const item = await catalog.load(summary.id);
+        return { selection: selected, item: { ...item, layer: summary.layer, revision: catalog.originalHashes.get(item.id) }, missing: false };
+    }));
+    return { root: selection.root, sessionId: selection.sessionId, task: selection.task, items, offset, total: omitted.length, nextOffset: offset + page.length < omitted.length ? offset + page.length : null, criticalOnly,
+        counts: { critical: selection.omitted.filter(i => i.priority === 'critical').length, normal: selection.omitted.filter(i => i.priority !== 'critical').length } };
+}
+// Offline optimization only removes exact duplicates. It uses the same structured
+// action validator as assisted instruction policy consolidation, without inference.
+const duplicateProvider = { name: 'deterministic-duplicates',
+    distill: async () => ({ output: { candidates: [] } }), reconcile: async () => { throw Error('Not used'); },
+    audit: async ({ items }) => {
+        const groups = new Map();
+        for (const m of items) {
+            const key = JSON.stringify([applicabilityKey(m), m.contextPolicy, m.authority, m.priority, exactKnowledge(m.content)]);
+            groups.set(key, [...(groups.get(key) ?? []), m.id]);
+        }
+        const actions = [...groups.values()].flatMap(ids => ids.slice(1).map(id => ({ action: 'NO_CHANGE', sources: [ids[0], id], canonical: null, reason: 'Exact duplicate instruction with identical authority and scope.' })));
+        return { output: { status: actions.length ? 'changes_proposed' : 'clean', issues: [], actions } };
+    } };
+export async function previewInstructionOptimization(selection, provider) {
+    return withSyncLock(selection.root, async () => {
+        await recoverSyncTransaction(selection.root);
+        const catalog = await loadMemoryCatalog(selection.root);
+        const shadowed = new Set(catalog.summaries.filter(i => ['active', 'disputed'].includes(i.status)).flatMap(i => i.supersedes));
+        const ids = [...new Set([...selection.omitted.map(i => i.id), ...selection.selectedIds])];
+        const eligible = ids.map(id => catalog.summaries.find(m => m.id === id)).filter(m => m?.category === 'instruction' && m.status === 'active' && !shadowed.has(m.id) && !m.relations.some(r => r.type === 'contradicts'));
+        // One bounded same-authority area per click, including loaded policies when useful.
+        const groups = new Map();
+        for (const m of eligible)
+            if (m) {
+                const key = JSON.stringify([m.layer, applicabilityKey(m), m.contextPolicy, m.authority, m.priority]);
+                groups.set(key, [...(groups.get(key) ?? []), m]);
+            }
+        const group = [...groups.values()].filter(g => g.length > 1).sort((a, b) => Number(b[0].priority === 'critical') - Number(a[0].priority === 'critical') || b.length - a.length)[0] ?? [];
+        const area = group.slice(0, INTELLIGENCE_LIMITS.auditItems);
+        const checks = await Promise.all(area.map(async (m) => ({ path: m.relativePath, hash: await fileHash(await safeProjectPath(selection.root, m.relativePath)) })));
+        const plan = await planAssistedSync(selection.root, [], provider ?? duplicateProvider, new Date(), new Set(), { instructionIds: area.map(m => m.id) });
+        const after = plan.writes.map(w => ({ ...parseKnowledge(w.after, w.path), path: w.path }));
+        const before = plan.knowledgeBefore;
+        const beforeTokens = before.reduce((n, m) => n + estimateTokens(knowledgeText(m)), 0);
+        const afterTokens = after.filter(m => m.status === 'active').reduce((n, m) => n + estimateTokens(knowledgeText(m)), 0);
+        if (plan.writes.length && (afterTokens > beforeTokens || after.filter(m => m.status === 'active').length >= before.length))
+            throw new Error('Optimization did not reduce instruction pressure. No changes were saved.');
+        return { root: selection.root, plan, checks, view: { before, after, beforeTokens, afterTokens, reducedBy: before.length - after.filter(m => m.status === 'active').length,
+                repository: after.some(m => m.path.startsWith('memory/')), mode: provider ? 'assisted' : 'deterministic',
+                notice: plan.writes.length ? 'Review the preserved clauses and scope before applying.' : provider ? 'No safe consolidation found in this bounded area. Edit obsolete or overly broad instructions individually.' : 'No exact duplicates found. Semantic policy consolidation requires MCP sampling support; individual editing remains available.',
+                inspected: area.length, remaining: Math.max(0, eligible.length - area.length) } };
+    }, { waitMs: 5000 });
+}
+export async function applyInstructionOptimization(preview) {
+    return withSyncLock(preview.root, async () => {
+        await recoverSyncTransaction(preview.root);
+        for (const check of preview.checks)
+            if (await fileHash(await safeProjectPath(preview.root, check.path)) !== check.hash)
+                throw new Error('Instructions changed. Optimize again before applying.');
+        const plan = preview.plan;
+        if (!plan.writes.length)
+            throw new Error('No consolidation changes to apply.');
+        const id = sortableId('chk');
+        const r = plan.result;
+        const checkpoint = { id, createdAt: new Date().toISOString(), previousCheckpoint: (await listCheckpoints(preview.root)).at(-1)?.id ?? null, sessions: [], consolidation: 'assisted-v1', intelligence: plan.intelligence, reasoning: plan.reasoning, knowledgeBefore: plan.knowledgeBefore, createdMemory: [], updatedMemory: r.updated, supersededMemory: r.superseded, duplicateMemory: r.duplicates, conflicts: r.conflicts, summary: { sessions: 0, candidates: 0, created: 0, consolidated: r.consolidated.length, duplicates: r.duplicates.length, superseded: 0, conflicts: 0 }, note: 'Explicit reviewed instruction optimization' };
+        await commitSyncTransaction(preview.root, [...plan.writes, { path: `checkpoints/${id}.json`, before: null, after: JSON.stringify(checkpoint, null, 2) + '\n' }], { policyMode: 'exact' });
+        await buildIndex(preview.root);
+        return { checkpoint: id, reducedBy: preview.view.reducedBy };
+    }, { waitMs: 5000 });
+}
+//# sourceMappingURL=instruction-review.js.map

package/dist/core/integrity-files.js

@@ -0,0 +1,174 @@
+import fs from 'node:fs/promises';
+import { constants } from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { checkedPath, safeRelative, secretPath } from './plugin-files.js';
+export const INTEGRITY_LIMITS = Object.freeze({ files: 20_000, bytes: 100_000_000, depth: 32, entries: 40_000, timeoutMs: 30_000 });
+const skipped = new Set(['.git', 'node_modules', '.cache', '.transactions', 'dist', 'dist-ui']);
+const privateStores = /(^|\/)\.prodero\/(?:local|sessions|checkpoints|\.cache|\.transactions|\.backups|\.migrations)(?:\/|$)/;
+const canonicalStores = ['config.json', 'index.md', 'memory', 'skills', 'local/memory', 'local/skills', 'local/archive', 'archive', 'sessions', 'checkpoints'];
+export async function integritySnapshot(root, relative, options = {}, canonical = false) {
+    const limits = { ...INTEGRITY_LIMITS, ...options.limits };
+    for (const key of Object.keys(INTEGRITY_LIMITS)) {
+        if (!Number.isInteger(limits[key]) || limits[key] < 1 || limits[key] > INTEGRITY_LIMITS[key])
+            throw new Error('Invalid integrity limit; limits may only be lowered');
+    }
+    const exclusions = new Set((options.exclude ?? []).map(safeRelative));
+    const controller = new AbortController();
+    const cancel = () => controller.abort();
+    options.signal?.addEventListener('abort', cancel, { once: true });
+    if (options.signal?.aborted)
+        cancel();
+    const timer = setTimeout(cancel, limits.timeoutMs);
+    const started = performance.now();
+    const check = () => { if (controller.signal.aborted || performance.now() - started >= limits.timeoutMs)
+        throw new Error('INTEGRITY_CANCELLED: digest cancelled or time budget exceeded; no complete digest produced'); };
+    const fail = (kind) => { throw new Error(`INTEGRITY_LIMIT: ${kind} budget exceeded; narrow the import tree or remove out-of-scope artifacts and retry. No complete digest produced.`); };
+    let entries = 0, bytes = 0, directories = 0, files = 0;
+    const digest = crypto.createHash('sha256').update(`curator-integrity-v2:${canonical ? 'canonical' : 'external'}\0`);
+    const hashes = Object.create(null);
+    const changed = () => new Error('Source tree changed while creating digest; retry audit');
+    const stable = (a, b) => a.dev === b.dev && a.ino === b.ino && a.size === b.size && a.mtimeNs === b.mtimeNs && a.ctimeNs === b.ctimeNs;
+    async function git(args, input = '') {
+        check();
+        return new Promise((resolve, reject) => {
+            const child = spawn('git', ['-C', root, ...args], { stdio: ['pipe', 'pipe', 'pipe'], signal: controller.signal });
+            let output = '', errorText = '', error = false;
+            child.stdout.on('data', chunk => { output += chunk; if (Buffer.byteLength(output) > 8_000_000) {
+                error = true;
+                child.kill();
+            } });
+            child.stderr.on('data', chunk => { errorText = (errorText + chunk).slice(0, 4096); });
+            child.stdin.on('error', () => { });
+            child.on('error', () => reject(new Error('INTEGRITY_GIT: Git ignore inspection unavailable or cancelled; no complete digest produced')));
+            child.on('close', code => error ? reject(new Error('INTEGRITY_LIMIT: Git ignore output budget exceeded')) : resolve({ code, output, errorText }));
+            child.stdin.end(input);
+        });
+    }
+    let gitRepository = false;
+    async function ignored(names) {
+        if (!gitRepository || !names.length)
+            return new Set();
+        if (Buffer.byteLength(names.join('\0')) > 4_000_000)
+            fail('Git path-input');
+        const result = await git(['check-ignore', '--no-index', '-z', '--stdin'], names.join('\0') + '\0');
+        if (result.code !== 0 && result.code !== 1)
+            throw new Error('INTEGRITY_GIT: Git ignore inspection failed; no complete digest produced');
+        return new Set(result.output.split('\0').filter(Boolean));
+    }
+    function excluded(rel, within) {
+        if (secretPath(rel))
+            return true;
+        if (canonical) {
+            if (rel.split('/').some(part => part.includes('.tmp-')))
+                return true;
+            if (rel === ".prodero")
+                return false;
+            const name = rel.slice('.prodero/'.length);
+            return !canonicalStores.some(store => name === store || name.startsWith(store + '/') || store.startsWith(name + '/'));
+        }
+        if (privateStores.test(rel) || rel.split('/').some(p => skipped.has(p)))
+            return true;
+        if (relative === '.' && rel.split('/')[0] === '.prodero')
+            return true;
+        return [...exclusions].some(p => within === p || within.startsWith(p + '/'));
+    }
+    async function hashFile(target, rel, stat) {
+        if (++files > limits.files)
+            fail('file-count');
+        if (stat.size > BigInt(limits.bytes - bytes))
+            fail('total-byte');
+        check();
+        const handle = await fs.open(target, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        try {
+            const before = await handle.stat({ bigint: true });
+            if (!before.isFile() || !stable(stat, before))
+                throw changed();
+            const value = crypto.createHash('sha256');
+            let read = 0;
+            for await (const chunk of handle.createReadStream({ autoClose: false, highWaterMark: 64 * 1024, signal: controller.signal })) {
+                check();
+                read += chunk.length;
+                if (read > limits.bytes - bytes)
+                    fail('total-byte');
+                value.update(chunk);
+            }
+            const after = await handle.stat({ bigint: true });
+            const current = await fs.lstat(target, { bigint: true });
+            if (!stable(before, after) || !stable(after, current) || BigInt(read) !== before.size)
+                throw changed();
+            bytes += read;
+            hashes[rel] = value.digest('hex');
+            return { hash: hashes[rel], bytes: read };
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    async function visit(target, rel, within, depth) {
+        check();
+        if (excluded(rel, within))
+            return;
+        const before = await fs.lstat(target, { bigint: true });
+        if (before.isSymbolicLink())
+            throw new Error('Symlink in source tree rejected');
+        if (depth > limits.depth)
+            fail('traversal-depth');
+        if (before.isDirectory()) {
+            if (within) {
+                directories++;
+                digest.update(`D\0${within}\0`);
+            }
+            const names = [];
+            for await (const entry of await fs.opendir(target)) {
+                check();
+                if (++entries > limits.entries)
+                    fail('entry-count');
+                const nextRel = rel === '.' ? entry.name : `${rel}/${entry.name}`;
+                const nextWithin = within ? `${within}/${entry.name}` : entry.name;
+                if (!excluded(nextRel, nextWithin))
+                    names.push(entry.name);
+            }
+            // Batch Git checks and prune ignored directories before traversing them.
+            const paths = names.map(n => rel === '.' ? n : `${rel}/${n}`);
+            const ignores = await ignored(paths);
+            for (const name of names.sort()) {
+                const nextRel = rel === '.' ? name : `${rel}/${name}`;
+                if (!ignores.has(nextRel))
+                    await visit(path.join(target, name), nextRel, within ? `${within}/${name}` : name, depth + 1);
+            }
+            if (!stable(before, await fs.lstat(target, { bigint: true })))
+                throw changed();
+        }
+        else if (before.isFile()) {
+            const value = await hashFile(target, rel, before);
+            digest.update(`F\0${within}\0${value.bytes}\0${value.hash}\0`);
+        }
+        else
+            throw new Error('Special source file rejected');
+    }
+    try {
+        check();
+        const base = await checkedPath(root, relative);
+        if (!canonical) {
+            const result = await git(['rev-parse', '--is-inside-work-tree']);
+            if (result.code !== 0 && !(result.code === 128 && /not a git repository/i.test(result.errorText)))
+                throw new Error('INTEGRITY_GIT: Unable to determine Git ignore scope');
+            gitRepository = result.code === 0 && result.output.trim() === 'true';
+        }
+        const stat = await fs.lstat(base).catch(error => { if (error.code === 'ENOENT')
+            return null; throw error; });
+        if (stat && !stat.isDirectory())
+            throw new Error('Source is not a directory');
+        if (stat && !(await ignored([relative])).has(relative))
+            await visit(base, relative, '', 0);
+        check();
+        return { hashes: Object.fromEntries(Object.entries(hashes)), digest: { version: 2, algorithm: 'sha256-tree-v2', sha256: digest.digest('hex'), files, directories, bytes } };
+    }
+    finally {
+        clearTimeout(timer);
+        options.signal?.removeEventListener('abort', cancel);
+    }
+}
+//# sourceMappingURL=integrity-files.js.map

package/dist/core/intelligence.js

@@ -0,0 +1,95 @@
+import { applicabilitySchema } from "./applicability.js";
+import { assertNoSecrets } from "./secrets.js";
+import { z } from 'zod';
+import { estimateTokens } from './telemetry.js';
+/** Central limits are local estimates, never provider billing units. */
+export const INTELLIGENCE_LIMITS = Object.freeze({
+    distillInputTokens: 4_000, candidatesPerBatch: 12, observationsPerBatch: 12,
+    relatedMemories: 12, reconcileInputTokens: 8_000,
+    auditItems: 16, auditInputTokens: 12_000, auditTriggerItems: 3,
+    outputTokens: 4_000, outputBytes: 32_000, timeoutMs: 45_000,
+});
+const text = z.string().trim().min(1);
+const id = text.max(240);
+export const canonicalProposalSchema = z.object({
+    applicability: applicabilitySchema.optional(),
+    title: text.max(200), content: text.max(8_000),
+    category: z.enum(['principle', 'invariant', 'decision', 'constraint', 'lesson', 'state', 'instruction']),
+    scope: z.enum(['global', 'module', 'task']), scopeRef: z.string().max(300).nullable(), scopeKind: z.enum(['path', 'topic']).optional(),
+    priority: z.enum(['critical', 'important', 'normal', 'contextual']),
+}).strict();
+export const candidateSchema = canonicalProposalSchema.extend({
+    id, kind: z.enum(['knowledge', 'skill_candidate', 'instruction_candidate']),
+    sources: z.array(id).min(1).max(24),
+    evidence: z.array(z.object({ source: id, quote: text.max(8_000) }).strict()).min(1).max(24),
+    supersedes: z.array(id).max(12),
+}).strict();
+export const distillSchema = z.object({ candidates: z.array(candidateSchema).max(INTELLIGENCE_LIMITS.candidatesPerBatch) }).strict();
+export const reconciliationCategorySchema = z.enum(['state_transition', 'refinement', 'duplicate', 'supporting', 'potential_conflict', 'unresolved', 'independent']);
+export const actionSchema = z.object({
+    action: z.enum(['CREATE', 'MERGE', 'SUPERSEDE', 'CONFLICT', 'NO_CHANGE', 'LINK', 'UNCERTAIN']),
+    sources: z.array(id).min(1).max(16),
+    canonical: canonicalProposalSchema.nullable(),
+    reason: text.max(500),
+    classification: reconciliationCategorySchema.optional(),
+    // Optional for backward-compatible providers; required for inferred replacement.
+    replacements: z.array(z.object({
+        target: id, previousQuote: text.max(8_000), replacementQuote: text.max(8_000),
+        transitionQuote: text.max(8_000), sameFact: z.literal(true), completeReplacement: z.literal(true),
+        basis: z.literal('explicit_transition'),
+    }).strict()).min(1).max(12).optional(),
+}).strict();
+export const reconcileSchema = z.object({ actions: z.array(actionSchema).min(1).max(1) }).strict();
+export const auditSchema = z.object({
+    status: z.enum(['clean', 'changes_proposed', 'uncertain']),
+    issues: z.array(z.object({ kind: z.enum(['contradiction', 'duplicate', 'obsolete', 'unsafe_merge', 'fragmentation', 'constraint_loss', 'uncertain']), sources: z.array(id).min(1).max(16), reason: text.max(500) }).strict()).max(16),
+    actions: z.array(actionSchema).max(16),
+}).strict();
+export function intelligenceTelemetry(provider, fallbackReason) {
+    return { mode: provider ? 'assisted' : 'deterministic', provider: provider?.name ?? null, ...(fallbackReason ? { fallbackReason } : {}),
+        distillation: { calls: 0, sessions: 0, observations: 0, candidates: 0, inputTokens: 0, outputTokens: 0 },
+        reconciliation: { calls: 0, comparisons: 0, inputTokens: 0, outputTokens: 0, actions: { CREATE: 0, MERGE: 0, SUPERSEDE: 0, CONFLICT: 0, NO_CHANGE: 0, LINK: 0, UNCERTAIN: 0 } },
+        audit: { triggered: false, items: 0, truncated: false, issues: 0, proposed: 0, applied: 0, inputTokens: 0, outputTokens: 0, status: 'skipped' }, providerUsage: [] };
+}
+export class IntelligenceError extends Error {
+    phase;
+    constructor(phase, detail) {
+        super(`Knowledge engine ${phase} failed: ${detail}. No semantic plan was committed; sessions remain pending.`);
+        this.phase = phase;
+    }
+}
+export async function requestIntelligence(provider, phase, input, telemetry) {
+    assertNoSecrets(input);
+    const limit = phase === 'distill' ? INTELLIGENCE_LIMITS.distillInputTokens : phase === 'reconcile' ? INTELLIGENCE_LIMITS.reconcileInputTokens : INTELLIGENCE_LIMITS.auditInputTokens;
+    const inputTokens = estimateTokens(JSON.stringify(input));
+    if (inputTokens > limit)
+        throw new IntelligenceError(phase, 'input budget exceeded');
+    const controller = new AbortController();
+    let timer;
+    try {
+        const response = await Promise.race([
+            provider[phase].call(provider, structuredClone(input), controller.signal),
+            new Promise((_, reject) => { timer = setTimeout(() => { controller.abort(); reject(new Error('provider timed out')); }, INTELLIGENCE_LIMITS.timeoutMs); }),
+        ]);
+        assertNoSecrets(response.output);
+        const encoded = JSON.stringify(response.output);
+        if (!encoded || Buffer.byteLength(encoded) > INTELLIGENCE_LIMITS.outputBytes)
+            throw new Error('output budget exceeded');
+        const output = (phase === 'distill' ? distillSchema : phase === 'reconcile' ? reconcileSchema : auditSchema).parse(response.output);
+        const target = phase === 'distill' ? telemetry.distillation : phase === 'reconcile' ? telemetry.reconciliation : telemetry.audit;
+        target.inputTokens += inputTokens;
+        target.outputTokens += estimateTokens(encoded);
+        if ('calls' in target)
+            target.calls++;
+        if (response.usage)
+            telemetry.providerUsage.push(response.usage);
+        return output;
+    }
+    catch (error) {
+        throw new IntelligenceError(phase, error instanceof z.ZodError ? 'invalid structured output' : 'provider failed or returned unsafe content');
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=intelligence.js.map

package/dist/core/knowledge-analysis.js

@@ -0,0 +1,46 @@
+/** Evidence-first proposals only. Classification never establishes authority. */
+import { inferApplicability, buildTaskContext } from './applicability.js';
+export const KNOWLEDGE_ANALYSIS_VERSION = 'evidence-3';
+const transient = /\b(?:currently (?:fails?|blocked|broken)|temporary workaround|remains? blocked|planned work owns|discovery.*fails?)\b/i;
+/** Keep exact text slices: no paraphrasing, dropped clauses or lexical authority. */
+export function analyzeKnowledgeText(title, content) {
+    const boundaries = [...content.matchAll(/^(?:Decision|Impact|Constraint|Correction|Guard Pattern|Workflow Note|Test-Quality Note|State|Lesson|Principle|Invariant):\s*$/gmi)];
+    const chunks = boundaries.length > 1 ? boundaries.map((m, i) => ({ start: i === 0 ? 0 : m.index, end: boundaries[i + 1]?.index ?? content.length, label: m[0].trim().slice(0, -1).toLowerCase() })) : [{ start: 0, end: content.length, label: boundaries[0]?.[0].trim().slice(0, -1).toLowerCase() ?? '' }];
+    // Impact stays with its decision; split only lifecycle/category boundaries.
+    const groups = [];
+    for (const c of chunks) {
+        if ((c.label === 'impact' || c.label === 'constraint' && /\b(?:must|should|never|always|required|only|cannot|do not)\b/i.test(content.slice(groups.at(-1)?.start ?? 0, c.start))) && groups.length && !transient.test(content.slice(c.start, c.end)))
+            groups.at(-1).end = c.end;
+        else
+            groups.push({ ...c });
+    }
+    const wholeContext = buildTaskContext(`${title}\n${content}`);
+    const titleContext = buildTaskContext(title);
+    const domain = titleContext.subsystems.length ? titleContext.subsystems : wholeContext.subsystems;
+    return groups.filter(c => content.slice(c.start, c.end).trim()).map((c, i) => {
+        const body = content.slice(c.start, c.end).trim();
+        const historical = transient.test(body);
+        const normative = /\b(?:must|should|never|always|required|only|cannot|do not|prohibit)\b/i.test(body);
+        const category = historical ? 'state' : c.label === 'principle' ? 'principle' : c.label === 'invariant' ? 'invariant' : c.label === 'constraint' || c.label === 'guard pattern' ? 'constraint' : c.label === 'lesson' || c.label === 'correction' ? 'lesson' : c.label === 'decision' ? (normative ? 'instruction' : 'decision') : c.label === 'workflow note' || /^(?:Run |Use |Always |Never |Do not )/.test(body) ? 'instruction' : /\b(?:invariant|transactional invariant)\b/i.test(body) ? 'invariant' : /\b(?:must not|cannot|never persist|prohibit)\b/i.test(body) ? 'constraint' : /\b(?:uses?|chosen|canonical|decided|adopted)\b/i.test(body) ? 'decision' : 'state';
+        let applicability = inferApplicability(body);
+        // Named domain is stronger than incidental code identifiers. Preserve concrete paths
+        // when no domain is established; avoid AND-ing incidental paths with a subsystem.
+        // Titles are authored source metadata, not a built-in domain dictionary.
+        // A single explicit identifier may name the work boundary; ambiguous titles
+        // remain unresolved rather than inventing a preferred subsystem.
+        const named = [...new Set(domain.filter(n => !['AI', 'PHP', 'CLI', 'HTTP', 'HTML', 'JSON', 'DB', 'SQL'].includes(n)))];
+        if (named.length === 1)
+            applicability = { kind: 'scoped', subsystems: named, ...(/\b(?:tests?|testing|harness)\b/i.test(title) ? { taskKinds: ['testing'] } : {}) };
+        if (named.length > 1)
+            applicability = { kind: 'unresolved' };
+        const evidence = [`Source characters ${c.start}–${c.end}`, ...(c.label ? [`Explicit source field: ${c.label}`] : []), ...(historical ? ['Time-sensitive wording; retained as historical state'] : [])];
+        if (applicability.kind === 'scoped')
+            evidence.push(`Explicit work signals: ${JSON.stringify(applicability)}`);
+        return { title: groups.length === 1 ? title : `${title.slice(0, 155)} · ${c.label || `part ${i + 1}`}`, content: body, category, applicability, evidence, start: c.start, end: c.end, transient: historical };
+    });
+}
+export function importPreviewSummary(items) {
+    const selected = items.filter(i => i.include !== false);
+    return { records: selected.length, categories: Object.fromEntries([...new Set(selected.map(i => i.category))].sort().map(c => [c, selected.filter(i => i.category === c).length])), required: 0, relevant: selected.length, projectWide: selected.filter(i => i.applicability?.kind === 'project').length, scoped: selected.filter(i => i.applicability?.kind === 'scoped').length, unresolved: selected.filter(i => !i.applicability || i.applicability.kind === 'unresolved').length };
+}
+//# sourceMappingURL=knowledge-analysis.js.map

package/dist/core/knowledge-authority.js

@@ -0,0 +1,143 @@
+import { sameApplicability, applicabilityKey, narrowsApplicability, applicabilityOf, withApplicability } from "./applicability.js";
+import { AsyncLocalStorage } from 'node:async_hooks';
+import path from 'node:path';
+import { knowledgePolicy } from './knowledge-policy.js';
+import { evidenceSentences } from './semantic-safety.js';
+const authorityContext = new AsyncLocalStorage();
+const shape = (i) => JSON.stringify([i.category, i.scope, i.scopeRef, i.scopeKind, i.priority, i.content, applicabilityKey(i)]);
+/** Internal application capability, not an MCP input or persisted permission.
+ * Entry points bind either host-attested intent or the explicit chat-rule command;
+ * the latter is model-mediated and retains distinct provenance.
+ * Scope is invocation-local; neither serialized evidence nor authority is a capability. */
+export async function withTrustedKnowledgeIntent(root, proposed, proof, operation) {
+    if (!proof.evidence.trim())
+        throw new Error('Trusted policy intent requires an auditable source reference');
+    const grant = { active: true, root: path.resolve(root), proposed: structuredClone(proposed), evidence: proof.evidence, authority: proof.authority, before: proof.before ? JSON.stringify(proof.before) : undefined };
+    try {
+        return await authorityContext.run(grant, operation);
+    }
+    finally {
+        grant.active = false;
+    }
+}
+export const protectedKnowledge = (i) => i.contextPolicy === 'required' || i.priority === 'critical' || ['explicit_user', 'reviewed'].includes(i.authority ?? '');
+const sameScope = (a, b) => sameApplicability(a, b);
+/** Conservative proof: whole clauses, including order, must survive exactly. No
+ * semantic equivalence is inferred from an LLM assertion or bag of words. */
+export const sameProtection = (a, b) => a.category === b.category && sameScope(a, b) && a.priority === b.priority && a.contextPolicy === b.contextPolicy && a.authority === b.authority && JSON.stringify(evidenceSentences(a.content)) === JSON.stringify(evidenceSentences(b.content));
+const samePolicyBoundary = (a, b) => a.category === b.category && sameScope(a, b) && a.priority === b.priority && a.contextPolicy === b.contextPolicy && a.authority === b.authority;
+function clausesCovered(before, after) {
+    const output = evidenceSentences(after);
+    let cursor = 0;
+    return evidenceSentences(before).every(clause => { const index = output.indexOf(clause, cursor); cursor = index + 1; return index >= 0; });
+}
+export const coversProtection = (before, after) => samePolicyBoundary(before, after) && clausesCovered(before.content, after.content);
+function equivalentSources(proposed, sources) {
+    if (!sources.length || !sources.every(s => samePolicyBoundary(s, proposed)))
+        return false;
+    const clauses = new Set(sources.flatMap(s => evidenceSentences(s.content))), out = new Set(evidenceSentences(proposed.content));
+    return clauses.size === out.size && [...clauses].every(c => out.has(c)) && sources.every(s => clausesCovered(s.content, proposed.content));
+}
+export function inferredKnowledge(item, origin = 'inferred') {
+    return { ...item, ...knowledgePolicy({ ...item, version: item.version === 3 ? 3 : 2, contextPolicy: 'relevant', authority: origin }) };
+}
+/** The single semantic authorization boundary, shared by every canonical transaction. */
+export function evaluateKnowledgeTransition(root, proposed, before, options = {}) {
+    try {
+        knowledgePolicy(proposed);
+    }
+    catch {
+        return { decision: 'forbidden', item: before ?? proposed, reasons: ['invalid-policy-combination'], blocking: true };
+    }
+    if (reviewedBatchAllows(root, proposed, before))
+        return { decision: "allowed", item: proposed, reasons: ["trusted-current-operation"], blocking: false };
+    const grant = authorityContext.getStore();
+    if (grant?.active && grant.proposed.status === proposed.status && grant.root === path.resolve(root) && shape(grant.proposed) === shape(proposed) && (!grant.before || grant.before === JSON.stringify(before) || (!before && options.sources?.some(s => JSON.stringify(s) === grant.before)))) {
+        const item = { ...proposed, ...knowledgePolicy({ ...proposed, version: proposed.version === 3 ? 3 : 2, contextPolicy: grant.proposed.contextPolicy, authority: grant.authority }), evidence: [...(proposed.evidence ?? []), { kind: 'user_instruction', ref: grant.evidence }] };
+        return { decision: 'allowed', item, reasons: ['trusted-current-operation'], blocking: false };
+    }
+    if (!before) {
+        // Publication and equivalent replacement retain existing policy, never gain it.
+        const source = options.sources?.find(s => sameProtection(s, proposed));
+        if ((source && source.status === proposed.status) || (proposed.status === 'active' && equivalentSources(proposed, (options.sources ?? []).filter(s => s.status === 'active'))))
+            return { decision: 'allowed', item: proposed, reasons: ['existing-policy-preserved'], blocking: false };
+        const item = inferredKnowledge(proposed, proposed.authority === 'imported' ? 'imported' : 'inferred');
+        if (item.priority === 'critical')
+            item.priority = 'important';
+        const sources = options.sources ?? [];
+        // Never union incomparable source boundaries. A useful inferred fork can
+        // keep the first source boundary; uncovered originals remain active.
+        if (sources.length && !sources.some(s => sameScope(item, s))) {
+            item.scope = sources[0].scope;
+            item.scopeRef = sources[0].scopeRef;
+            item.scopeKind = sources[0].scopeKind;
+            Object.assign(item, withApplicability(item, applicabilityOf(sources[0])));
+        }
+        const changed = item.contextPolicy !== proposed.contextPolicy || item.authority !== proposed.authority || item.priority !== proposed.priority || !sameScope(item, proposed);
+        return { decision: changed ? (options.exact ? 'review_required' : 'allowed_with_safe_fallback') : 'allowed', item, reasons: changed ? ['unverified-promotion-saved-as-relevant'] : [], blocking: changed && !!options.exact };
+    }
+    const reasons = [];
+    if (options.replacementRequested && before.status !== proposed.status && !options.retirementCovered)
+        reasons.push("replacement-does-not-cover-source");
+    if (before.contextPolicy !== proposed.contextPolicy)
+        reasons.push('delivery-policy-change');
+    if (before.authority !== proposed.authority)
+        reasons.push('authority-change');
+    if (proposed.priority === 'critical' && before.priority !== 'critical')
+        reasons.push('criticality-increase');
+    if (protectedKnowledge(before)) {
+        if (!sameScope(before, proposed))
+            reasons.push('protected-applicability-change');
+        if (before.priority !== proposed.priority)
+            reasons.push('protected-priority-change');
+        if ((before.category !== proposed.category || JSON.stringify(evidenceSentences(before.content)) !== JSON.stringify(evidenceSentences(proposed.content))) && !equivalentSources(proposed, options.sources ?? [before]))
+            reasons.push('protected-meaning-change');
+        if ((proposed.relations ?? []).some(r => ['superseded_by', 'consolidated_into', 'contradicts'].includes(r.type) && !(before.relations ?? []).some(old => old.type === r.type && old.target === r.target)))
+            reasons.push('protected-topology-change');
+        if (before.status !== proposed.status && !options.retirementCovered)
+            reasons.push('protected-retirement');
+    }
+    // Ordinary inference may refine relevant knowledge but cannot broaden its scope.
+    if (!sameScope(before, proposed) && !(before.contextPolicy === 'relevant' && before.authority === 'inferred' && proposed.derivedFrom.length > 0 && narrowsApplicability(before, proposed)))
+        reasons.push('applicability-change');
+    if (!reasons.length)
+        return { decision: 'allowed', item: proposed, reasons: [], blocking: false };
+    return { decision: options.exact ? 'review_required' : 'review_recommended', item: structuredClone(before), reasons: [...new Set(reasons)], blocking: !!options.exact };
+}
+export class KnowledgePolicyReviewRequired extends Error {
+    transition;
+    code = 'POLICY_REVIEW_REQUIRED';
+    constructor(transition) {
+        super('POLICY_REVIEW_REQUIRED: The requested rule change needs trusted user intent or an exact policy review. Existing knowledge was preserved.');
+        this.transition = transition;
+    }
+}
+/** Optional diagnostics, not an approval queue and never a Prepare blocker. */
+export function summarizePolicyDecisions(decisions) {
+    return { blocking: decisions.some(d => d.blocking), recommendations: decisions.filter(d => d.decision === 'review_recommended').length,
+        safeFallbacks: decisions.filter(d => d.decision === 'allowed_with_safe_fallback').length, reasons: [...new Set(decisions.flatMap(d => d.reasons))], interactivePrompts: 0 };
+}
+const batchReviewContext = new AsyncLocalStorage();
+export async function withTrustedKnowledgeBatch(root, entries, evidence, operation) {
+    if (!evidence.trim() || !entries.length)
+        throw new Error('Exact trusted batch review required');
+    const grant = { active: true, root: path.resolve(root), entries: structuredClone(entries), evidence };
+    try {
+        return await batchReviewContext.run(grant, operation);
+    }
+    finally {
+        grant.active = false;
+    }
+}
+function reviewedBatchAllows(root, proposed, before) {
+    const g = batchReviewContext.getStore();
+    // Canonical normalization eliminates presentation aliases, not semantic metadata.
+    const canonical = (i) => JSON.stringify(Object.fromEntries(Object.entries(i).filter(([k, v]) => v !== undefined && !['kind', 'enforcement'].includes(k)).sort(([a], [b]) => a.localeCompare(b))));
+    return !!g?.active && g.root === path.resolve(root) && g.entries.some(e => canonical(e.after) === canonical(proposed) && (!e.before ? !before : !!before && canonical(e.before) === canonical(before)));
+}
+/** Diagnostic reference only; never grants permission when replayed from history. */
+export function trustedKnowledgeBatchEvidence(root) {
+    const grant = batchReviewContext.getStore();
+    return grant?.active && grant.root === path.resolve(root) ? grant.evidence : null;
+}
+//# sourceMappingURL=knowledge-authority.js.map