@prodero/curator 0.0.0-stage → 0.2.0

package/dist/core/imports.js

@@ -0,0 +1,169 @@
+import { applicabilitySchema, withApplicability, sameApplicability, applicabilityKey, inferApplicability } from "./applicability.js";
+import { assertCompatibleProject } from "./storage.js";
+import fs from "node:fs/promises";
+import { sortableId } from "./ids.js";
+import { z } from "zod";
+import { listKnowledge, renderKnowledge } from "./memory.js";
+import { listProjectSkills, renderSkill, skillInputSchema } from "./skills.js";
+import { readConfig, sha256, listCheckpoints } from "./storage.js";
+import { checkedPath, hasSecret, readSource, safeRelative, snapshotImportState } from "./plugin-files.js";
+import { commitSyncTransaction, recoverSyncTransaction, withSyncLock } from "./sync-transaction.js";
+import { buildIndex } from "./index.js";
+import { estimateTokens, knowledgeText, MAX_CANONICAL_ITEM_TOKENS } from "./telemetry.js";
+import { assertEnglishProse } from "./language.js";
+const hash = z.string().regex(/^[a-f0-9]{64}$/);
+const text = z.string().trim().min(1);
+export const importEvidenceSchema = z.object({ path: text.max(400), sha256: hash, startLine: z.number().int().positive(), endLine: z.number().int().positive() }).strict();
+export const importItemSchema = z.object({
+    applicability: applicabilitySchema.optional(), scopeKind: z.enum(["path", "topic"]).optional(),
+    key: text.max(100), destination: z.enum(["project_instruction", "knowledge", "skill"]),
+    title: text.max(200).regex(/^[^\r\n]+$/), content: text.max(8000),
+    scope: z.enum(["global", "module", "task"]), scopeRef: text.max(300).nullable(),
+    category: z.enum(["principle", "invariant", "decision", "constraint", "lesson", "state", "instruction"]),
+    evidence: z.array(importEvidenceSchema).min(1).max(12), reason: text.max(1000),
+    persistEvidence: z.boolean().optional(),
+    skill: skillInputSchema.strict().nullable(), activateSkill: z.boolean(),
+}).strict();
+export const importBatchSchema = z.object({
+    version: z.literal(1), planId: hash, approvedPlanId: hash,
+    stateFingerprint: hash, items: z.array(importItemSchema).max(100),
+}).strict();
+export async function readImportState(root) {
+    if (!(await readConfig(root)))
+        throw new Error("Initialize Prodero before importing knowledge");
+    const files = await snapshotImportState(root);
+    return { knowledge: await listKnowledge(root), skills: await listProjectSkills(root), fingerprint: sha256(JSON.stringify(files)), files, importedSources: (await listCheckpoints(root)).flatMap(c => c.importReceipt ? [...c.importReceipt.created, ...c.importReceipt.duplicates].flatMap(i => i.source ?? []) : []), importedKeys: (await listCheckpoints(root)).flatMap(c => c.importReceipt ? [...c.importReceipt.created, ...c.importReceipt.duplicates].map(i => i.key) : []) };
+}
+const normalized = (content) => content.trim().replace(/\s+/g, " ").toLowerCase();
+/** Read-only preflight is shared by proposal review and the durable apply boundary. */
+export async function validateImportItems(root, raw) {
+    await assertCompatibleProject(root);
+    const items = z.array(importItemSchema).max(100).parse(raw);
+    if (new Set(items.map(i => i.key)).size !== items.length)
+        throw new Error("Duplicate import item key");
+    if (hasSecret(JSON.stringify(items)))
+        throw new Error("Potential secret in import proposal");
+    // Validate every proposal and evidence before taking the writer lock or touching durable state.
+    for (const item of items) {
+        assertEnglishProse([item.title, item.content, item.reason, item.skill?.title, item.skill?.description, item.skill?.scope, ...(item.skill?.triggers ?? []), item.skill?.content], "Imported Prodero knowledge");
+        if (item.destination !== "skill" && estimateTokens(knowledgeText(item)) > MAX_CANONICAL_ITEM_TOKENS)
+            throw new Error("Knowledge exceeds canonical token budget");
+        if ((item.scope === "global") !== (item.scopeRef === null))
+            throw new Error("Invalid scope boundary");
+        if (item.destination === "project_instruction" && item.category !== "instruction")
+            throw new Error("Project rules require instruction category");
+        if (item.destination === "skill" ? !item.skill : item.skill !== null || item.activateSkill)
+            throw new Error("Invalid skill destination");
+        if (item.skill && (item.title !== item.skill.title || item.content !== item.skill.content || item.skill.relatedKnowledge.length))
+            throw new Error("Skill proposal must match its reviewed content and use evidence references");
+        if (item.skill && estimateTokens(renderSkill({ ...item.skill, id: "validation", status: "candidate", origin: "legacy", createdAt: "", updatedAt: "", sourceSessions: [], derivedFrom: [], proposedReason: item.reason, reviewedAt: null, reviewReason: null, path: "skills/validation.md" })) > 1500)
+            throw new Error("Skill exceeds context budget; distill the procedure");
+        for (const reference of item.skill?.references ?? [])
+            safeRelative(reference);
+        for (const evidence of item.evidence) {
+            safeRelative(evidence.path);
+            const source = await readSource(root, evidence.path);
+            if (source.sha256 !== evidence.sha256 || evidence.endLine < evidence.startLine || evidence.endLine > source.content.split("\n").length)
+                throw new Error("Source evidence changed or line range invalid");
+        }
+    }
+}
+/** No plugin-supplied write paths, overwrites or model execution. Exact approved input only. */
+export async function applyImport(root, plugin, raw) {
+    const batch = importBatchSchema.parse(raw);
+    if (batch.approvedPlanId !== batch.planId)
+        throw new Error("Exact plan approval required");
+    await validateImportItems(root, batch.items);
+    const batchHash = sha256(JSON.stringify(batch));
+    return withSyncLock(root, async () => {
+        await recoverSyncTransaction(root);
+        const checkpoints = await listCheckpoints(root);
+        const previousImport = checkpoints.find(c => c.importReceipt?.plugin === plugin.id && c.importReceipt?.planId === batch.planId);
+        if (previousImport?.importReceipt) {
+            const receipt = previousImport.importReceipt;
+            if (receipt.batchHash !== batchHash)
+                throw new Error("Applied plan differs from requested batch");
+            await checkedPath(root, ".prodero/index.md");
+            await buildIndex(root);
+            return receipt;
+        }
+        // Reuse Core's chronological ID contract; the receipt is the stable replay key.
+        const checkpoint = sortableId("chk");
+        const state = await readImportState(root);
+        if (state.fingerprint !== batch.stateFingerprint)
+            throw new Error("Prodero state changed since audit; create a fresh reviewed plan");
+        const writes = [];
+        const now = new Date().toISOString();
+        const receipt = { version: 1, plugin: plugin.id, pluginVersion: plugin.version, planId: batch.planId, batchHash, checkpoint, created: [], duplicates: [], before: state.files };
+        const knowledge = [...state.knowledge], skills = [...state.skills];
+        for (const item of batch.items) {
+            const applicability = item.applicability ?? (item.scopeRef ? { kind: "scoped", ...(item.scopeKind === "path" || /[/.]/.test(item.scopeRef) ? { paths: [item.scopeRef] } : { subsystems: [item.scopeRef] }) } : inferApplicability(item.content));
+            const signature = item.destination === "skill" ? `skill:${item.skill.scope}:${normalized(item.content)}` : `${item.destination}:${applicabilityKey({ ...item, applicability })}:${item.category}:${normalized(item.content)}`;
+            const id = `${item.destination === "skill" ? "skill" : "mem"}_import_${sha256(signature).slice(0, 32)}`;
+            const provenance = item.persistEvidence !== false ? item.evidence.map(e => `${e.path}#L${e.startLine}-L${e.endLine}@${e.sha256}`) : [];
+            const derivedFrom = [...provenance, `plugin:${plugin.id}@${plugin.version}/plan:${batch.planId}`];
+            let target, after;
+            if (item.destination === "skill") {
+                const prior = skills.find(s => s.status !== "superseded" && normalized(s.content) === normalized(item.content) && s.scope === item.skill.scope);
+                if (prior) {
+                    const p = `.prodero/${prior.path}`;
+                    receipt.duplicates.push({ key: item.key, path: p, sha256: sha256(await fs.readFile(await checkedPath(root, p), "utf8").catch(() => writes.find(w => `.prodero/${w.path}` === p).after)), destination: item.destination, source: item.evidence });
+                    continue;
+                }
+                const skill = { ...item.skill, id, status: item.activateSkill ? "active" : "candidate", origin: "legacy", createdAt: now, updatedAt: now, sourceSessions: [], derivedFrom, proposedReason: item.reason, reviewedAt: item.activateSkill ? now : null, reviewReason: item.activateSkill ? `Approved plan ${batch.planId}` : null, path: `skills/${id}.md` };
+                after = renderSkill(skill);
+                if (estimateTokens(after) > 1500)
+                    throw new Error("Skill with provenance exceeds context budget");
+                target = skill.path;
+                skills.push(skill);
+            }
+            else {
+                const prior = knowledge.find(k => k.status === "active" && sameApplicability(k, { ...item, applicability }) && k.category === item.category && normalized(k.content) === normalized(item.content));
+                if (prior) {
+                    const p = `.prodero/memory/${prior.id}.md`;
+                    receipt.duplicates.push({ key: item.key, path: p, sha256: state.files[p] ?? sha256(writes.find(w => `.prodero/${w.path}` === p).after), destination: item.destination, source: item.evidence });
+                    continue;
+                }
+                const knowledgeItem = withApplicability({ version: 3, contextPolicy: "relevant", authority: "imported", id, scope: item.scope, scopeRef: item.scopeRef, category: item.category, priority: "normal", status: "active", title: item.title, content: item.content, createdAt: now, updatedAt: now, sourceSessions: [], derivedFrom, supersedes: [], related: [], evidence: provenance.map(ref => ({ kind: "source_file", ref })) }, applicability);
+                if (estimateTokens(knowledgeText(knowledgeItem)) > MAX_CANONICAL_ITEM_TOKENS)
+                    throw new Error("Knowledge exceeds canonical token budget");
+                after = renderKnowledge(knowledgeItem);
+                target = `memory/${id}.md`;
+                knowledge.push(knowledgeItem);
+            }
+            writes.push({ path: target, before: null, after });
+            receipt.created.push({ key: item.key, path: `.prodero/${target}`, sha256: sha256(after), destination: item.destination, source: item.evidence });
+        }
+        await checkedPath(root, ".prodero/index.md");
+        const record = { id: checkpoint, createdAt: now, previousCheckpoint: checkpoints.at(-1)?.id ?? null, sessions: [], consolidation: "not-performed", createdMemory: receipt.created.filter(i => i.destination !== "skill").map(i => i.path.split("/").at(-1).slice(0, -3)), createdSkills: receipt.created.filter(i => i.destination === "skill").map(i => i.path.split("/").at(-1).slice(0, -3)), updatedMemory: [], supersededMemory: [], duplicateMemory: [], conflicts: [], summary: { sessions: 0, candidates: batch.items.length, created: receipt.created.length, consolidated: 0, duplicates: receipt.duplicates.length, superseded: 0, conflicts: 0 }, importReceipt: receipt };
+        try {
+            await commitSyncTransaction(root, [...writes, { path: `checkpoints/${checkpoint}.json`, before: null, after: JSON.stringify(record, null, 2) + "\n" }]);
+            await buildIndex(root);
+        }
+        catch {
+            throw new Error("Import interrupted and may be partially applied. Core retains its recovery journal/checkpoint; retry this exact approved plan after resolving the filesystem or concurrent-write error.");
+        }
+        return receipt;
+    });
+}
+export async function verifyImport(root, receipt) {
+    await assertCompatibleProject(root);
+    const issues = [];
+    if (!/^chk_[0-9]{17}_[a-f0-9]{12}$/.test(receipt.checkpoint))
+        throw new Error("Invalid receipt checkpoint");
+    const record = JSON.parse(await fs.readFile(await checkedPath(root, `.prodero/checkpoints/${receipt.checkpoint}.json`), "utf8"));
+    if (JSON.stringify(record.importReceipt) !== JSON.stringify(receipt))
+        throw new Error("Receipt does not match durable checkpoint");
+    const state = await readImportState(root);
+    for (const item of [...receipt.created, ...receipt.duplicates])
+        if (state.files[item.path] !== item.sha256)
+            issues.push(`Imported item missing or changed: ${item.key}`);
+    const allowed = new Set([...receipt.created.map(i => i.path), `.prodero/checkpoints/${receipt.checkpoint}.json`, ".prodero/index.md"]);
+    for (const p of new Set([...Object.keys(receipt.before), ...Object.keys(state.files)]))
+        if (!allowed.has(p) && receipt.before[p] !== state.files[p])
+            issues.push(`Other canonical state changed: ${p}`);
+    if (new Set(receipt.created.map(i => i.path)).size !== receipt.created.length)
+        issues.push("Duplicate created destination");
+    return { valid: issues.length === 0, issues };
+}
+//# sourceMappingURL=imports.js.map

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