@prodero/curator 0.0.0-stage → 0.2.0

package/dist/core/knowledge-provenance.js

@@ -0,0 +1,90 @@
+import { readConfig } from './storage.js';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { parseKnowledge } from './memory.js';
+import { assertCompatibleProject, assertLifecycleReadable, knowledgeReadFence, canonicalId, checkedDataPath, exists, sha256 } from './storage.js';
+export const archiveBucket = (at) => {
+    if (!Number.isFinite(Date.parse(at)))
+        throw new Error('Invalid archive timestamp');
+    return new Date(at).toISOString().slice(0, 7).replace('-', '_');
+};
+export const knowledgeArchivePath = (layer, at, id) => {
+    canonicalId(id, 'archive');
+    return `${layer === 'local' ? 'local/' : ''}archive/${archiveBucket(at)}/${id}.md`;
+};
+/** Enumerate paths only. Ordinary retrieval never loads archive bodies. */
+export async function listArchivePaths(root) {
+    await assertLifecycleReadable(root);
+    const entries = [];
+    for (const layer of ['versioned', 'local']) {
+        const base = layer === 'local' ? 'local/archive' : 'archive';
+        const directory = await checkedDataPath(root, base);
+        if (!await exists(directory))
+            continue;
+        for (const bucket of (await fs.readdir(directory)).filter(n => /^\d{4}_(0[1-9]|1[0-2])$/.test(n)).sort()) {
+            const dir = await checkedDataPath(root, base, bucket);
+            for (const name of (await fs.readdir(dir)).filter(n => n.endsWith('.md') && !n.startsWith('.')).sort()) {
+                const id = path.basename(name, '.md');
+                canonicalId(id, name);
+                const relative = `${base}/${bucket}/${name}`;
+                await checkedDataPath(root, relative);
+                entries.push({ id, path: relative, layer });
+            }
+        }
+    }
+    return entries;
+}
+/** Explicit ID/provenance operations, not archive-aware search or ranking. */
+export async function readKnowledgeInventory(root, options = {}) {
+    await assertCompatibleProject(root);
+    const finishRead = await knowledgeReadFence(root);
+    const paths = (await listArchivePaths(root)).map(e => ({ ...e, storage: 'archive' }));
+    for (const layer of options.storage === 'archive' ? [] : ['versioned', 'local']) {
+        const base = layer === 'local' ? 'local/memory' : 'memory', dir = await checkedDataPath(root, base);
+        if (!await exists(dir))
+            continue;
+        for (const name of (await fs.readdir(dir)).filter(n => n.endsWith('.md') && !n.startsWith('.')).sort())
+            paths.push({ path: `${base}/${name}`, layer, id: path.basename(name, '.md'), storage: 'current' });
+    }
+    const records = [], ids = new Set();
+    for (const entry of paths.sort((a, b) => a.path.localeCompare(b.path))) {
+        const text = await fs.readFile(await checkedDataPath(root, entry.path), 'utf8'), item = parseKnowledge(text, path.basename(entry.path), (await readConfig(root))?.knowledgeSchemaVersion);
+        if (ids.has(item.id))
+            throw new Error(`Duplicate knowledge ID across storage locations: ${item.id}`);
+        ids.add(item.id);
+        if (entry.storage === 'archive' && (!item.archivedAt || knowledgeArchivePath(entry.layer, item.archivedAt, item.id) !== entry.path))
+            throw new Error(`Archive metadata/path mismatch: ${item.id}`);
+        records.push({ ...entry, item, revision: sha256(text) });
+    }
+    await finishRead();
+    return records;
+}
+export function provenanceEdges(items) {
+    const edges = new Map();
+    const add = (from, to, type) => edges.set(`${from}\0${type}\0${to}`, { from, to, type });
+    for (const item of items) {
+        for (const old of item.supersedes)
+            add(item.id, old, 'supersedes');
+        for (const r of item.relations ?? []) {
+            if (r.type === 'supersedes' || r.type === 'consolidates')
+                add(item.id, r.target, r.type);
+            if (r.type === 'superseded_by')
+                add(r.target, item.id, 'supersedes');
+            if (r.type === 'consolidated_into')
+                add(r.target, item.id, 'consolidates');
+        }
+    }
+    return [...edges.values()].sort((a, b) => a.from.localeCompare(b.from) || a.type.localeCompare(b.type) || a.to.localeCompare(b.to));
+}
+export async function getKnowledgeProvenance(root, id) {
+    canonicalId(id, 'knowledge lookup');
+    const records = await readKnowledgeInventory(root), record = records.find(r => r.item.id === id);
+    if (!record)
+        throw new Error(`Knowledge ${id} was not found`);
+    const edges = provenanceEdges(records.map(r => r.item)), incoming = edges.filter(e => e.to === id), outgoing = edges.filter(e => e.from === id);
+    const supersededBy = incoming.filter(e => e.type === 'supersedes').map(e => e.from), consolidatedInto = incoming.filter(e => e.type === 'consolidates').map(e => e.from);
+    return { ...record, current: record.storage === 'current' && record.item.status === 'active' && !incoming.length,
+        supersedes: outgoing.filter(e => e.type === 'supersedes').map(e => e.to), superseded_by: supersededBy,
+        consolidates: outgoing.filter(e => e.type === 'consolidates').map(e => e.to), consolidated_into: consolidatedInto };
+}
+//# sourceMappingURL=knowledge-provenance.js.map

package/dist/core/knowledge-write-policy.js

@@ -0,0 +1,85 @@
+import { sameApplicability } from "./applicability.js";
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { parseKnowledge, renderKnowledge } from './memory.js';
+import { checkedDataPath } from './storage.js';
+import { sha256 } from './storage.js';
+import { evaluateKnowledgeTransition, inferredKnowledge, protectedKnowledge, sameProtection, coversProtection, KnowledgePolicyReviewRequired, summarizePolicyDecisions } from './knowledge-authority.js';
+import { loadMemoryCatalog } from './memory-index.js';
+const canonical = (p) => /^(memory|local\/memory|(local\/)?archive\/\d{4}_\d{2})\//.test(p);
+/** Policy validation precedes the durable journal. Recovery replays the already
+ * decided journal; it must not re-authorize a past decision from persisted prose. */
+export async function protectKnowledgeWrites(root, writes, exact = false, moves = []) {
+    writes = writes.map(w => { if (!canonical(w.path))
+        return w; const item = parseKnowledge(w.after, path.basename(w.path)); return { ...w, after: renderKnowledge({ ...item, version: 3, applicability: item.applicability ?? { kind: 'legacy' } }) }; });
+    const proposed = writes.filter(w => canonical(w.path));
+    if (!proposed.length)
+        return { writes, policy: { ...summarizePolicyDecisions([]), createdIds: undefined, supersededIds: undefined, preservedIds: [] } };
+    const parsed = new Map(proposed.map(w => [w.path, parseKnowledge(w.after, path.basename(w.path), 3)]));
+    const catalog = await loadMemoryCatalog(root);
+    const ids = new Set([...parsed.values()].flatMap(i => [i.id, ...i.supersedes, ...i.related, ...(i.relations ?? []).map(r => r.target)]));
+    const current = [];
+    for (const id of ids)
+        if (catalog.summaries.some(s => s.id === id))
+            current.push(await catalog.load(id));
+    const byId = new Map(current.map(i => [i.id, i]));
+    const decisions = [], safe = new Map(), forks = [];
+    const sourcesFor = (i) => current.filter(s => i.supersedes.includes(s.id) || i.related.includes(s.id) || i.id === s.id || (i.relations ?? []).some(r => ['supersedes', 'consolidates'].includes(r.type) && r.target === s.id) || sameProtection(s, i));
+    // Decide new records first, so a retirement cannot rely on a rejected replacement.
+    for (const w of proposed)
+        if (w.before === null) {
+            const i = parsed.get(w.path);
+            const move = moves.find(m => m.to === w.path);
+            const original = move ? parseKnowledge(await fs.readFile(await checkedDataPath(root, move.from), 'utf8'), path.basename(move.from), 3) : undefined;
+            const retirementCovered = !!original && [...parsed.values()].some(other => other.id !== i.id && other.status === 'active' && coversProtection(original, other) && evaluateKnowledgeTransition(root, other, byId.get(other.id), { sources: sourcesFor(other) }).decision === 'allowed');
+            const d = evaluateKnowledgeTransition(root, i, original, { sources: sourcesFor(i), exact: exact || !!move, retirementCovered });
+            decisions.push(d);
+            if (d.blocking)
+                throw new KnowledgePolicyReviewRequired(d);
+            if (d.decision !== 'allowed') {
+                d.item.supersedes = d.item.supersedes.filter(id => !protectedKnowledge(byId.get(id) ?? i));
+                d.item.relations = (d.item.relations ?? []).filter(r => !['supersedes', 'consolidates', 'consolidated_into', 'superseded_by'].includes(r.type));
+            }
+            d.item.supersedes = d.item.supersedes.filter(id => { const source = byId.get(id); return !source || !protectedKnowledge(source) || coversProtection(source, d.item) || d.reasons.includes('trusted-current-operation'); });
+            d.item.relations = (d.item.relations ?? []).filter(r => { const source = byId.get(r.target); return !['supersedes', 'consolidates'].includes(r.type) || !source || !protectedKnowledge(source) || coversProtection(source, d.item) || d.reasons.includes('trusted-current-operation'); });
+            safe.set(w.path, d.item);
+        }
+    for (const w of proposed)
+        if (w.before !== null) {
+            const before = parseKnowledge(await fs.readFile(await checkedDataPath(root, w.path), 'utf8'), path.basename(w.path), 3), i = parsed.get(w.path);
+            const retirementCovered = [...safe.values(), ...current.filter(c => !proposed.some(w => parsed.get(w.path).id === c.id)), ...proposed.filter(w => w.before !== null).map(w => parsed.get(w.path)).filter(c => evaluateKnowledgeTransition(root, c, byId.get(c.id), { sources: sourcesFor(c) }).decision === 'allowed')].some(other => other.id !== i.id && other.status === 'active' && coversProtection(before, other) && (other.supersedes.includes(i.id) || other.related.includes(i.id) || (i.related ?? []).includes(other.id) || (other.relations ?? []).some(r => r.target === i.id && r.type === 'consolidates')));
+            const replacementRequested = [...parsed.values()].some(other => other.id !== i.id && (other.supersedes.includes(i.id) || (other.relations ?? []).some(r => ["supersedes", "consolidates"].includes(r.type) && r.target === i.id)) && !sameApplicability(other, before));
+            const d = evaluateKnowledgeTransition(root, i, before, { exact, retirementCovered, replacementRequested, sources: sourcesFor(i) });
+            decisions.push(d);
+            if (d.blocking)
+                throw new KnowledgePolicyReviewRequired(d);
+            if (d.decision !== 'allowed' && i.content !== before.content) {
+                const fork = evaluateKnowledgeTransition(root, inferredKnowledge({ ...i, id: `mem_policy_${sha256(JSON.stringify(i)).slice(0, 24)}`, status: 'active', supersedes: [], related: [before.id], relations: [{ type: 'related_to', target: before.id }] }), undefined, { sources: [before] }).item;
+                forks.push({ path: `local/memory/${fork.id}.md`, before: null, after: renderKnowledge(fork) });
+            }
+            d.item.supersedes = d.item.supersedes.filter(id => { const source = byId.get(id); return before.supersedes.includes(id) || !source || !protectedKnowledge(source) || coversProtection(source, d.item) || d.reasons.includes('trusted-current-operation'); });
+            d.item.relations = (d.item.relations ?? []).filter(r => { const source = byId.get(r.target); return (before.relations ?? []).some(old => old.type === r.type && old.target === r.target) || !['supersedes', 'consolidates'].includes(r.type) || !source || !protectedKnowledge(source) || coversProtection(source, d.item) || d.reasons.includes('trusted-current-operation'); });
+            safe.set(w.path, d.item);
+        }
+    const policy = summarizePolicyDecisions(decisions);
+    const preservedIds = decisions.filter(d => d.decision === 'review_recommended').map(d => d.item.id);
+    const result = writes.map(w => safe.has(w.path) ? { ...w, after: renderKnowledge(safe.get(w.path)) } : w);
+    const checkpoint = result.find(w => w.path.startsWith('checkpoints/'));
+    if (checkpoint) {
+        const c = JSON.parse(checkpoint.after);
+        c.policyTransitions = policy;
+        c.updatedMemory = (c.updatedMemory ?? []).filter((id) => !preservedIds.includes(id));
+        c.createdMemory = [...new Set([...(c.createdMemory ?? []), ...forks.map(w => path.basename(w.path, '.md'))])];
+        c.supersededMemory = (c.supersededMemory ?? []).filter((id) => [...safe.values()].some(i => i.id === id && i.status === 'superseded'));
+        if (c.summary) {
+            c.summary.consolidated = Math.max(0, (c.summary.consolidated ?? 0) - preservedIds.length);
+            c.summary.created = c.createdMemory.length;
+            c.summary.superseded = c.supersededMemory.length;
+        }
+        checkpoint.after = JSON.stringify(c, null, 2) + '\n';
+    }
+    result.splice(Math.max(0, result.length - 1), 0, ...forks);
+    const committed = checkpoint ? JSON.parse(checkpoint.after) : null;
+    return { writes: result, policy: { ...policy, preservedIds, createdIds: committed?.createdMemory, supersededIds: committed?.supersededMemory } };
+}
+//# sourceMappingURL=knowledge-write-policy.js.map

package/dist/core/language.js

@@ -0,0 +1,14 @@
+const CODE = /```[\s\S]*?```|`[^`]*`/g;
+/** Durable prose is English; identifiers and code literals may retain their source spelling. */
+export function assertEnglishProse(values, subject = "Durable Prodero prose") {
+    for (const value of values) {
+        if (!value)
+            continue;
+        const prose = value.replace(CODE, "");
+        for (const character of prose) {
+            if (/\p{L}/u.test(character) && !/\p{Script=Latin}/u.test(character))
+                throw new Error(`${subject} must be written in English; wrap exact non-English identifiers or code literals in backticks.`);
+        }
+    }
+}
+//# sourceMappingURL=language.js.map

package/dist/core/local-preferences.js

@@ -0,0 +1,76 @@
+import fs from 'node:fs/promises';
+import { modeSchema, themeSchema } from '../settings-definition.js';
+import { assertSafePath, projectDataPath, ensureSelfIgnoredPrivateDirectory, writeFileAtomic } from './storage.js';
+import { ownsSyncLock } from './sync-transaction.js';
+export const LOCAL_PREFERENCES_VERSION = 1;
+const relativePath = 'local/preferences.json';
+const object = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+// Extensions may round-trip, but a local file cannot masquerade as shared project policy.
+const sharedKeys = new Set(['context', 'knowledgeEngine', 'schemaVersion', 'knowledgeSchemaVersion', 'initializedWith', 'lastUpdatedWith', 'projectId', 'createdAt', 'contextPolicy', 'authority', '__proto__', 'constructor', 'prototype']);
+const forbidden = (key) => sharedKeys.has(key.split('.')[0]);
+const diagnostic = (code, cause) => ({ code, cause,
+    recovery: 'Preserve .prodero/local/preferences.json; repair it explicitly or use a compatible Curator before saving preferences.' });
+/** Read-only: no creation, legacy copy, permission changes, recovery or cleanup. */
+export async function readLocalPreferences(root) {
+    const fallback = { presentation: {}, diagnostics: [] };
+    let raw;
+    try {
+        const target = projectDataPath(root, relativePath);
+        await assertSafePath(target);
+        const stat = await fs.lstat(target);
+        if (!stat.isFile() || stat.nlink !== 1)
+            throw new Error('unsafe preference file');
+        raw = JSON.parse(await fs.readFile(target, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return fallback;
+        return { ...fallback, diagnostics: [diagnostic('PRODERO_LOCAL_PREFERENCES_UNAVAILABLE', 'Local preferences could not be safely read. Legacy project defaults are used.')] };
+    }
+    if (!object(raw) || raw.version !== LOCAL_PREFERENCES_VERSION) {
+        const newer = object(raw) && Number.isInteger(raw.version) && Number(raw.version) > LOCAL_PREFERENCES_VERSION;
+        return { ...fallback, diagnostics: [diagnostic(newer ? 'PRODERO_LOCAL_PREFERENCES_NEWER' : 'PRODERO_LOCAL_PREFERENCES_INVALID', newer ? 'Local preferences require a newer Curator. Legacy project defaults are used.' : 'Local preferences have an invalid format. Legacy project defaults are used.')] };
+    }
+    if (Object.keys(raw).some(forbidden) || (raw.presentation !== undefined && (!object(raw.presentation) || Object.keys(raw.presentation).some(forbidden)))) {
+        return { ...fallback, diagnostics: [diagnostic('PRODERO_LOCAL_PREFERENCES_INVALID', 'Local preferences must contain presentation overrides only; shared policy or identity overrides are not supported.')] };
+    }
+    const presentation = {}, diagnostics = [];
+    for (const [key, schema] of [['mode', modeSchema], ['theme', themeSchema]]) {
+        const value = raw.presentation?.[key];
+        if (value === undefined)
+            continue;
+        const parsed = schema.safeParse(value);
+        if (parsed.success)
+            Object.assign(presentation, { [key]: parsed.data });
+        else
+            diagnostics.push(diagnostic('PRODERO_LOCAL_PREFERENCES_INVALID', `Local presentation.${key} is invalid; its legacy project default is used.`));
+    }
+    // Valid sibling fields can resolve, but writes never overwrite a damaged document.
+    return { presentation, diagnostics, ...(diagnostics.length ? {} : { document: raw }) };
+}
+/** Caller owns the shared Sync/migration lock and has checked canonical write gates. */
+export async function saveLocalPreference(root, key, value, reset) {
+    if (!ownsSyncLock(root))
+        throw new Error('Local preferences require the shared project writer lock.');
+    if (key !== 'mode' && key !== 'theme')
+        throw new Error('Only presentation mode and theme may be saved as local preferences.');
+    if (reset && value !== undefined)
+        throw new Error('Reset requires no value.');
+    const parsed = reset ? undefined : (key === 'mode' ? modeSchema : themeSchema).parse(value);
+    const current = await readLocalPreferences(root);
+    if (current.diagnostics.length) {
+        const issue = current.diagnostics[0];
+        throw new Error(`${issue.code}: ${issue.cause} ${issue.recovery}`);
+    }
+    if (reset && current.document?.presentation?.[key] === undefined)
+        return;
+    const document = current.document ?? { version: LOCAL_PREFERENCES_VERSION };
+    const presentation = { ...document.presentation };
+    if (reset)
+        delete presentation[key];
+    else
+        presentation[key] = parsed;
+    await ensureSelfIgnoredPrivateDirectory(root, 'local');
+    await writeFileAtomic(projectDataPath(root, relativePath), `${JSON.stringify({ ...document, presentation }, null, 2)}\n`);
+}
+//# sourceMappingURL=local-preferences.js.map

package/dist/core/matching.js

@@ -0,0 +1,6 @@
+const STOP_WORDS = new Set(["a", "an", "and", "are", "as", "at", "be", "for", "from", "in", "is", "it", "must", "of", "on", "or", "the", "to", "use", "with"]);
+export function tokens(value) {
+    return new Set(value.toLowerCase().replace(/[`*_]/g, "").match(/[\p{L}\p{N}]+(?:[._/-][\p{L}\p{N}]+)*/gu)?.filter((token) => token.length > 1 && !STOP_WORDS.has(token)) ?? []);
+}
+export function normalized(value) { return [...tokens(value)].sort().join(" "); }
+//# sourceMappingURL=matching.js.map

package/dist/core/memory-index.js

@@ -0,0 +1,241 @@
+import { applicabilitySchema, validateApplicability, scopeProjection, sameApplicability } from "./applicability.js";
+import { knowledgePolicy, CONTEXT_POLICIES, KNOWLEDGE_AUTHORITIES } from "./knowledge-policy.js";
+import { knowledgeReadFence } from "./storage.js";
+import { assertNoSecrets } from "./secrets.js";
+import { z } from "zod";
+import fs from "node:fs/promises";
+import { normalized, tokens } from "./matching.js";
+import { parseKnowledge } from "./memory.js";
+import { estimateTokens, knowledgeText, MAX_CANONICAL_ITEM_TOKENS, STALE_STATE_AFTER_DAYS } from "./telemetry.js";
+import { ensureDerivedStateRoot, exists, projectDataPath, checkedDataPath, sha256, writeFileAtomic, readConfig } from "./storage.js";
+export const MAX_RELATED_MEMORY_CANDIDATES = 24;
+const DAY_MS = 86_400_000;
+const PRIORITY_SCORE = { critical: 40, important: 30, normal: 20, contextual: 10 };
+export function isStaleSummary(item, now = new Date()) {
+    if (item.status !== "active" || item.category !== "state" || item.priority === "critical")
+        return false;
+    const updated = Date.parse(item.updatedAt);
+    return Number.isFinite(updated) && now.getTime() - updated >= STALE_STATE_AFTER_DAYS * DAY_MS;
+}
+export function memoryHealth(summaries, now = new Date()) {
+    const active = summaries.filter((item) => item.status === "active");
+    const disputedItems = summaries.filter((item) => item.status === "disputed").length;
+    const staleActiveItems = active.filter((item) => isStaleSummary(item, now)).length;
+    // Compatibility counter: incomplete source/observation metadata, not evidence
+    // that source history was deleted. Do not infer or rewrite provenance here.
+    const missingProvenanceItems = active.filter((item) => (item.sourceSessionCount === 0 && (item.sourceEvidenceCount ?? 0) === 0) || item.derivedFromCount === 0).length;
+    const oversizedActiveItems = active.filter((item) => item.estimatedTokens > MAX_CANONICAL_ITEM_TOKENS).length;
+    return {
+        activeItems: active.length,
+        disputedItems,
+        historicalItems: summaries.length - active.length - disputedItems,
+        staleActiveItems,
+        missingProvenanceItems,
+        oversizedActiveItems,
+        status: disputedItems || missingProvenanceItems || oversizedActiveItems ? "attention" : "healthy",
+    };
+}
+function stamp(stat) { return { size: Number(stat.size), mtimeMs: Number(stat.mtimeMs), ctimeMs: Number(stat.ctimeMs) }; }
+function sameStamp(left, right) { return Boolean(left && left.size === right.size && left.mtimeMs === right.mtimeMs && left.ctimeMs === right.ctimeMs); }
+function summary(item, filename, relativePath, layer, fileStamp) {
+    return {
+        ...fileStamp,
+        id: item.id,
+        filename,
+        relativePath,
+        layer,
+        scope: item.scope,
+        scopeRef: item.scopeRef,
+        ...(item.scopeKind ? { scopeKind: item.scopeKind } : {}),
+        version: item.version ?? 3,
+        ...(item.applicability ? { applicability: item.applicability } : {}),
+        contextPolicy: knowledgePolicy(item).contextPolicy,
+        authority: knowledgePolicy(item).authority,
+        category: item.category,
+        priority: item.priority,
+        status: item.status,
+        title: item.title,
+        normalizedTitle: normalized(item.title),
+        normalizedContent: normalized(item.content),
+        tokens: [...tokens(`${item.title} ${item.content} ${item.scopeRef ?? ""}`)].sort(),
+        contentChars: item.content.length,
+        estimatedTokens: estimateTokens(knowledgeText(item)),
+        updatedAt: item.updatedAt,
+        sourceSessionCount: item.sourceSessions.length,
+        derivedFromCount: item.derivedFrom.length,
+        sourceEvidenceCount: item.evidence?.filter(e => e.kind === "source_file" && typeof e.ref === "string" && e.ref.length > 0).length ?? 0,
+        related: item.related,
+        supersedes: item.supersedes,
+        sourceSessions: item.sourceSessions,
+        relations: item.relations ?? [],
+    };
+}
+const summarySchema = z.object({
+    version: z.union([z.literal(1), z.literal(2), z.literal(3)]),
+    applicability: applicabilitySchema.optional(),
+    contextPolicy: z.enum(CONTEXT_POLICIES), authority: z.enum(KNOWLEDGE_AUTHORITIES),
+    size: z.number().nonnegative(), mtimeMs: z.number().finite(), ctimeMs: z.number().finite(),
+    id: z.string().regex(/^[a-zA-Z0-9_-]+$/), filename: z.string(), relativePath: z.string(), layer: z.enum(["local", "versioned"]),
+    scope: z.enum(["global", "module", "task"]), scopeRef: z.string().nullable(), scopeKind: z.enum(["path", "topic"]).optional(),
+    category: z.enum(["principle", "invariant", "decision", "constraint", "lesson", "state", "instruction"]),
+    priority: z.enum(["critical", "important", "normal", "contextual"]), status: z.enum(["active", "superseded", "deprecated", "consolidated", "duplicate", "disputed"]),
+    title: z.string(), normalizedTitle: z.string(), normalizedContent: z.string(), tokens: z.array(z.string()),
+    contentChars: z.number().nonnegative(), estimatedTokens: z.number().nonnegative(), updatedAt: z.string(),
+    sourceSessionCount: z.number().nonnegative(), derivedFromCount: z.number().nonnegative(), sourceEvidenceCount: z.number().nonnegative(),
+    related: z.array(z.string()), supersedes: z.array(z.string()), sourceSessions: z.array(z.string()),
+    relations: z.array(z.object({ type: z.enum(["related_to", "depends_on", "implements", "applies_to", "supersedes", "superseded_by", "consolidates", "consolidated_into", "contradicts", "learned_from"]), target: z.string() })),
+}).superRefine((entry, ctx) => {
+    if (entry.version !== 3)
+        return;
+    try {
+        const applicability = validateApplicability(entry.applicability, entry.contextPolicy);
+        if (applicability.kind !== 'legacy') {
+            const projection = scopeProjection(applicability);
+            if (entry.scope !== projection.scope || entry.scopeRef !== projection.scopeRef || entry.scopeKind !== projection.scopeKind)
+                throw new Error('Invalid applicability projection');
+        }
+    }
+    catch {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Invalid v3 applicability cache entry' });
+    }
+});
+const memoryCacheSchema = z.object({ version: z.literal(10), entries: z.record(summarySchema) });
+async function readCache(root, persistCache) {
+    if (persistCache)
+        await ensureDerivedStateRoot(root);
+    const target = await checkedDataPath(root, ".cache", "memory-index.json");
+    if (!(await exists(target)))
+        return { cache: { version: 10, entries: {} }, state: "missing" };
+    try {
+        const parsed = memoryCacheSchema.parse(JSON.parse(await fs.readFile(target, "utf8")));
+        assertNoSecrets(parsed);
+        if (Object.entries(parsed.entries).every(([key, e]) => key === e.relativePath && key === `${e.layer === "local" ? "local/memory" : "memory"}/${e.filename}` && /^[a-zA-Z0-9_-]+\.md$/.test(e.filename)))
+            return { cache: parsed, state: "warm" };
+    }
+    catch {
+        // Disposable derived JSON is rebuilt below; canonical Markdown is never repaired here.
+    }
+    if (persistCache)
+        await fs.rm(target, { force: true });
+    return { cache: { version: 10, entries: {} }, state: "invalid" };
+}
+export class MemoryCatalog {
+    root;
+    summaries;
+    filesScanned;
+    cacheState;
+    bodiesIndexed;
+    bodiesLoaded = 0;
+    staged = new Map();
+    originalHashes = new Map();
+    byId;
+    constructor(root, summaries, filesScanned, bodiesIndexed, cacheState) {
+        this.root = root;
+        this.summaries = summaries;
+        this.filesScanned = filesScanned;
+        this.bodiesIndexed = bodiesIndexed;
+        this.cacheState = cacheState;
+        this.byId = new Map(summaries.map((entry) => [entry.id, entry]));
+    }
+    selectRelated(query, limit = MAX_RELATED_MEMORY_CANDIDATES) {
+        const queryTokens = tokens(`${query.title} ${query.content} ${query.scopeRef ?? ""}`);
+        const explicit = new Set(query.explicitIds);
+        const shadowed = new Set(this.summaries.filter(m => m.status === "active" || m.status === "disputed").flatMap(m => m.supersedes));
+        return this.summaries
+            .filter(entry => explicit.has(entry.id) || !shadowed.has(entry.id))
+            .filter((entry) => (entry.status === "active" || entry.status === "disputed") && (explicit.has(entry.id) || (entry.scope === query.scope && entry.scopeRef === query.scopeRef && entry.scopeKind === query.scopeKind && entry.category === query.category && sameApplicability(entry, query))))
+            .map((entry) => {
+            const intersection = entry.tokens.filter((token) => queryTokens.has(token)).length;
+            let score = intersection * 10 + PRIORITY_SCORE[entry.priority];
+            if (explicit.has(entry.id))
+                score += 10_000;
+            const queryTitle = normalized(query.title);
+            const queryContent = normalized(query.content);
+            if (queryTitle && entry.normalizedTitle === queryTitle)
+                score += 1_000;
+            if (queryContent && entry.normalizedContent === queryContent)
+                score += 2_000;
+            if (entry.scopeRef && query.scopeRef === entry.scopeRef)
+                score += 100;
+            return { entry, score };
+        })
+            .filter(({ score }) => score > 0)
+            .sort((a, b) => b.score - a.score || a.entry.id.localeCompare(b.entry.id))
+            .slice(0, Math.max(1, limit))
+            .map(({ entry }) => entry);
+    }
+    async load(id) {
+        const entry = this.byId.get(id);
+        if (!entry)
+            throw new Error(`Canonical Prodero memory ${id} was not found.`);
+        this.bodiesLoaded += 1;
+        const staged = this.staged.get(id);
+        if (staged)
+            return structuredClone(staged);
+        const finishRead = await knowledgeReadFence(this.root);
+        const target = await checkedDataPath(this.root, entry.relativePath);
+        if (!sameStamp(entry, stamp(await fs.stat(target))))
+            throw new Error("Knowledge changed after context selection; retry");
+        const text = await fs.readFile(target, "utf8");
+        await finishRead();
+        this.originalHashes.set(id, sha256(text));
+        return parseKnowledge(text, entry.filename, (await readConfig(this.root))?.knowledgeSchemaVersion ?? 1);
+    }
+    /** In-memory overlay for a Sync plan; never persist virtual stamps in the derived cache. */
+    stage(item, layer = "local") {
+        const filename = `${item.id}.md`;
+        const relativePath = layer === "versioned" ? `memory/${filename}` : `local/memory/${filename}`;
+        const entry = summary(item, filename, relativePath, layer, { size: 0, mtimeMs: 0, ctimeMs: 0 });
+        const index = this.summaries.findIndex(candidate => candidate.id === item.id);
+        if (index >= 0)
+            this.summaries.splice(index, 1, entry);
+        else
+            this.summaries.push(entry);
+        this.byId.set(item.id, entry);
+        this.staged.set(item.id, structuredClone({ ...item, ...knowledgePolicy(item) }));
+    }
+    async save() {
+        if (this.staged.size)
+            throw new Error("Cannot persist an uncommitted knowledge plan as cache");
+        await ensureDerivedStateRoot(this.root);
+        const entries = Object.fromEntries(this.summaries.sort((a, b) => a.relativePath.localeCompare(b.relativePath)).map((entry) => [entry.relativePath, entry]));
+        await writeFileAtomic(projectDataPath(this.root, ".cache", "memory-index.json"), `${JSON.stringify({ version: 10, entries })}\n`);
+    }
+}
+export async function loadMemoryCatalog(root, options = {}) {
+    const finishRead = await knowledgeReadFence(root);
+    const { cache, state } = await readCache(root, options.persistCache !== false);
+    const summaries = [];
+    const schema = (await readConfig(root))?.knowledgeSchemaVersion ?? 1;
+    let bodiesIndexed = 0;
+    for (const layer of ["versioned", "local"]) {
+        const relativeDirectory = layer === "versioned" ? "memory" : "local/memory";
+        const directory = await checkedDataPath(root, ...relativeDirectory.split("/"));
+        if (!(await exists(directory)))
+            continue;
+        const names = (await fs.readdir(directory)).filter((name) => name.endsWith(".md") && !name.startsWith(".")).sort();
+        for (const name of names) {
+            const target = await checkedDataPath(root, relativeDirectory, name);
+            const stat = await fs.lstat(target);
+            if (stat.isSymbolicLink())
+                throw new Error(`Symlink in canonical ${layer} memory: ${name}`);
+            const fileStamp = stamp(stat);
+            const relativePath = `${relativeDirectory}/${name}`;
+            let entry = cache.entries[relativePath];
+            if (!sameStamp(entry, fileStamp) || (schema >= 2 && entry.version !== schema)) {
+                entry = summary(parseKnowledge(await fs.readFile(target, "utf8"), name, schema), name, relativePath, layer, fileStamp);
+                bodiesIndexed += 1;
+            }
+            if (summaries.some((candidate) => candidate.id === entry.id))
+                throw new Error(`Knowledge id ${entry.id} exists in both Local and Versioned Knowledge.`);
+            summaries.push(entry);
+        }
+    }
+    const cacheState = state === "warm" && bodiesIndexed > 0 ? "stale" : state;
+    const catalog = new MemoryCatalog(root, summaries, summaries.length, bodiesIndexed, cacheState);
+    await finishRead();
+    if (options.persistCache !== false)
+        await catalog.save();
+    return catalog;
+}
+//# sourceMappingURL=memory-index.js.map