@prodero/curator 0.0.0-stage → 0.1.0

package/dist/core/knowledge-graph.js

@@ -0,0 +1,191 @@
+import { listArchivePaths } from "./knowledge-provenance.js";
+import { assertCompatibleProject } from "./storage.js";
+import { isPathScope } from "./path-scope.js";
+import fs from "node:fs/promises";
+import { loadMemoryCatalog } from "./memory-index.js";
+import { sha256, exists, projectDataPath, writeFileAtomic } from "./storage.js";
+const MEMORY_ID = /^mem_[a-zA-Z0-9_]+$/;
+const EDGE_WEIGHT = {
+    depends_on: 24,
+    implements: 20,
+    related_to: 12,
+    supersedes: 8,
+    superseded_by: 0,
+    consolidates: 0,
+    consolidated_into: 0,
+    contradicts: 0,
+    applies_to: 0,
+    learned_from: 0,
+};
+const MAX_INFERRED_RELATED_PER_NODE = 3;
+const MAX_TOKEN_POSTINGS = 128;
+const RELATION_TYPES = new Set(["related_to", "depends_on", "implements", "applies_to", "supersedes", "superseded_by", "consolidates", "consolidated_into", "contradicts", "learned_from"]);
+function validCache(value, digest) {
+    if (!value || typeof value !== "object")
+        return false;
+    const cache = value;
+    return cache.version === 1 && cache.sourceDigest === digest
+        && Array.isArray(cache.nodes) && cache.nodes.every((node) => typeof node === "string")
+        && Array.isArray(cache.brokenReferences) && cache.brokenReferences.every((entry) => typeof entry === "string")
+        && Array.isArray(cache.edges) && cache.edges.every((edge) => edge && typeof edge.from === "string" && typeof edge.to === "string"
+        && RELATION_TYPES.has(edge.type) && typeof edge.inferred === "boolean" && typeof edge.weight === "number" && Number.isFinite(edge.weight));
+}
+function graphSourceDigest(summaries, archives = []) {
+    return sha256(JSON.stringify([archives, summaries.map((item) => ({
+            id: item.id, status: item.status, scope: item.scope, scopeRef: item.scopeRef, scopeKind: item.scopeKind, category: item.category,
+            title: item.normalizedTitle, content: item.normalizedContent, updatedAt: item.updatedAt,
+            related: item.related, supersedes: item.supersedes, sourceSessions: item.sourceSessions, relations: item.relations,
+        }))]));
+}
+const pathLike = isPathScope;
+function compatibleScope(left, right) {
+    if (pathLike(left) || pathLike(right))
+        return left.scope === right.scope && left.scopeRef === right.scopeRef && left.scopeKind === right.scopeKind;
+    if (left.scope === "module" || right.scope === "module")
+        return left.scope === right.scope && left.scopeRef === right.scopeRef && left.scopeKind === right.scopeKind;
+    return true;
+}
+function canonicalPair(from, to, type) {
+    return type === "related_to" || type === "contradicts" ? [from, to].sort() : [from, to];
+}
+function build(summaries, archives) {
+    const nodes = [...summaries.map((item) => item.id), ...archives].sort();
+    const knownIds = new Set(nodes);
+    const byId = new Map(summaries.map((item) => [item.id, item]));
+    const edges = new Map();
+    const broken = new Set();
+    const add = (from, to, type, inferred = false) => {
+        const needsMemoryTarget = type === "related_to" || type === "depends_on" || type === "implements" || type === "supersedes" || type === "superseded_by" || type === "consolidates" || type === "consolidated_into" || type === "contradicts";
+        if (needsMemoryTarget && (!MEMORY_ID.test(to) || !knownIds.has(to))) {
+            broken.add(`${from}:${type}:${to}`);
+            return;
+        }
+        const [edgeFrom, edgeTo] = canonicalPair(from, to, type);
+        const key = `${edgeFrom}\0${type}\0${edgeTo}`;
+        if (!edges.has(key) || !inferred)
+            edges.set(key, { from: edgeFrom, to: edgeTo, type, inferred, weight: EDGE_WEIGHT[type] });
+    };
+    for (const item of summaries) {
+        for (const target of item.supersedes)
+            add(item.id, target, "supersedes");
+        for (const target of item.related) {
+            const other = byId.get(target);
+            add(item.id, target, item.status === "disputed" && other?.status === "disputed" ? "contradicts" : "related_to");
+        }
+        for (const relation of item.relations)
+            add(item.id, relation.target, relation.type);
+        if (item.scopeRef)
+            add(item.id, `scope:${item.scopeRef}`, "applies_to");
+        for (const session of item.sourceSessions)
+            add(item.id, `session:${session}`, "learned_from");
+    }
+    const successors = new Map();
+    for (const item of summaries.filter((candidate) => candidate.status === "active" || candidate.status === "disputed"))
+        for (const target of item.supersedes) {
+            const ids = successors.get(target) ?? [];
+            ids.push(item.id);
+            successors.set(target, ids);
+        }
+    for (const edge of [...edges.values()]) {
+        const successor = successors.get(edge.to);
+        if (successor?.length === 1 && edge.type !== "supersedes" && edge.type !== "contradicts")
+            add(edge.from, successor[0], edge.type, true);
+    }
+    const current = summaries.filter((item) => item.status === "active" || item.status === "disputed");
+    const inverted = new Map();
+    for (const item of current)
+        for (const token of item.tokens.filter((value) => value.length >= 4)) {
+            const ids = inverted.get(token) ?? [];
+            ids.push(item.id);
+            inverted.set(token, ids);
+        }
+    for (const item of current) {
+        const overlap = new Map();
+        for (const token of item.tokens.filter((value) => value.length >= 4)) {
+            const postings = inverted.get(token) ?? [];
+            if (postings.length > MAX_TOKEN_POSTINGS)
+                continue;
+            for (const id of postings)
+                if (id !== item.id)
+                    overlap.set(id, (overlap.get(id) ?? 0) + 1);
+        }
+        const candidates = [...overlap].flatMap(([id, shared]) => {
+            const target = byId.get(id);
+            if (!compatibleScope(item, target))
+                return [];
+            const coverage = shared / Math.min(item.tokens.length || 1, target.tokens.length || 1);
+            if (shared < 2 || coverage < 0.3)
+                return [];
+            const targetTitle = target.normalizedTitle.split(" ").filter(Boolean);
+            const mentionsTitle = targetTitle.length > 0 && targetTitle.every((token) => item.tokens.includes(token));
+            const words = new Set(item.tokens);
+            const type = mentionsTitle && (words.has("depends") || words.has("dependency")) ? "depends_on"
+                : mentionsTitle && (words.has("implements") || words.has("implementation")) ? "implements" : "related_to";
+            return [{ target, shared, coverage, type }];
+        }).sort((a, b) => b.shared - a.shared || b.coverage - a.coverage || a.target.id.localeCompare(b.target.id));
+        for (const candidate of candidates.slice(0, MAX_INFERRED_RELATED_PER_NODE))
+            add(item.id, candidate.target.id, candidate.type, true);
+    }
+    return {
+        version: 1,
+        sourceDigest: graphSourceDigest(summaries, archives),
+        nodes,
+        edges: [...edges.values()].sort((a, b) => a.from.localeCompare(b.from) || a.type.localeCompare(b.type) || a.to.localeCompare(b.to) || Number(a.inferred) - Number(b.inferred)),
+        brokenReferences: [...broken].sort(),
+    };
+}
+function diagnostics(cache, cacheState) {
+    return {
+        cacheState,
+        nodeCount: cache.nodes.length,
+        edgeCount: cache.edges.length,
+        brokenReferences: cache.brokenReferences.length,
+        conflictEdges: cache.edges.filter((edge) => edge.type === "contradicts").length,
+    };
+}
+export class KnowledgeGraph {
+    adjacency = new Map();
+    diagnostics;
+    edges;
+    brokenReferences;
+    constructor(cache, cacheState) {
+        this.edges = cache.edges;
+        this.brokenReferences = cache.brokenReferences;
+        this.diagnostics = diagnostics(cache, cacheState);
+        for (const edge of cache.edges) {
+            const outgoing = this.adjacency.get(edge.from) ?? [];
+            outgoing.push(edge);
+            this.adjacency.set(edge.from, outgoing);
+            if (edge.type === "related_to" || edge.type === "contradicts") {
+                const incoming = this.adjacency.get(edge.to) ?? [];
+                incoming.push({ ...edge, from: edge.to, to: edge.from });
+                this.adjacency.set(edge.to, incoming);
+            }
+        }
+    }
+    neighbors(id) { return this.adjacency.get(id) ?? []; }
+}
+export async function loadKnowledgeGraph(root, suppliedCatalog, options = {}) {
+    await assertCompatibleProject(root);
+    const catalog = suppliedCatalog ?? await loadMemoryCatalog(root, options);
+    const target = projectDataPath(root, ".cache", "knowledge-graph.json");
+    const archives = (await listArchivePaths(root)).map(entry => entry.id).sort();
+    const digest = graphSourceDigest(catalog.summaries, archives);
+    let state = "missing";
+    if (await exists(target)) {
+        try {
+            const cached = JSON.parse(await fs.readFile(target, "utf8"));
+            if (validCache(cached, digest))
+                return new KnowledgeGraph(cached, "warm");
+            state = "stale";
+        }
+        catch {
+            state = "invalid";
+        }
+    }
+    const rebuilt = build(catalog.summaries, archives);
+    if (options.persistCache !== false)
+        await writeFileAtomic(target, `${JSON.stringify(rebuilt)}\n`);
+    return new KnowledgeGraph(rebuilt, state);
+}
+//# sourceMappingURL=knowledge-graph.js.map

package/dist/core/knowledge-lifecycle.js

@@ -0,0 +1,212 @@
+import { applicabilitySchema, applicabilityOf, sameApplicability, withApplicability } from "./applicability.js";
+import { inferredKnowledge, evaluateKnowledgeTransition, protectedKnowledge, coversProtection } from './knowledge-authority.js';
+import { inheritKnowledgePolicy } from './knowledge-policy.js';
+import { z } from 'zod';
+import { sortableId } from './ids.js';
+import { assertEnglishProse } from './language.js';
+import { parseKnowledge, renderKnowledge } from './memory.js';
+import { knowledgeArchivePath, provenanceEdges, readKnowledgeInventory } from './knowledge-provenance.js';
+import { assertCompatibleProject, listCheckpoints, sha256 } from './storage.js';
+import { commitSyncTransaction, recoverSyncTransaction, withSyncLock, ownsSyncLock } from './sync-transaction.js';
+const id = z.string().regex(/^[a-zA-Z0-9_-]+$/);
+const proposalSchema = z.object({
+    operationId: z.string().regex(/^[a-zA-Z0-9_-]{1,100}$/),
+    expectedRevisions: z.record(id, z.string().regex(/^[a-f0-9]{64}$/)).default({}),
+    create: z.array(z.object({
+        applicability: applicabilitySchema.optional(),
+        id: z.string().regex(/^mem_[a-zA-Z0-9_]+$/), layer: z.enum(['local', 'versioned']), title: z.string().trim().min(1).max(240), content: z.string().trim().min(1).max(10000),
+        scope: z.enum(['global', 'module', 'task']), scopeRef: z.string().nullable(), scopeKind: z.enum(['path', 'topic']).optional(),
+        category: z.enum(['instruction', 'principle', 'invariant', 'constraint', 'decision', 'lesson', 'state']),
+        priority: z.enum(['critical', 'important', 'normal', 'contextual']).default('normal'),
+        related: z.array(id).max(32).optional(), sourceSessions: z.array(id).optional(), derivedFrom: z.array(z.string()).optional(),
+    }).strict()).max(100).default([]),
+    links: z.array(z.object({ from: id, to: id, type: z.enum(['supersedes', 'consolidates']) }).strict()).max(1000).default([]),
+    archive: z.array(id).max(1000).default([]),
+}).strict();
+const digest = (value) => sha256(JSON.stringify(value));
+const inventoryHash = (records) => digest(records.map(r => [r.item.id, r.path, r.revision]));
+function validateGraph(items) {
+    const ids = new Set(items.map(i => i.id)), edges = provenanceEdges(items), adjacency = new Map();
+    for (const item of items)
+        for (const target of [...item.related, ...(item.relations ?? []).filter(r => !['applies_to', 'learned_from'].includes(r.type)).map(r => r.target)]) {
+            if (!ids.has(target))
+                throw new Error(`Missing relationship target: ${target}`);
+        }
+    for (const e of edges) {
+        if (!ids.has(e.from) || !ids.has(e.to))
+            throw new Error(`Missing provenance target: ${e.from} -> ${e.to}`);
+        if (e.from === e.to)
+            throw new Error('Self supersession/consolidation is forbidden');
+        const targets = adjacency.get(e.from) ?? [];
+        targets.push(e.to);
+        adjacency.set(e.from, targets);
+    }
+    // Iterative topological validation also handles long historical chains safely.
+    const indegree = new Map([...ids].map(id => [id, 0]));
+    for (const targets of adjacency.values())
+        for (const target of targets)
+            indegree.set(target, indegree.get(target) + 1);
+    const ready = [...ids].filter(id => indegree.get(id) === 0);
+    let visited = 0;
+    for (let i = 0; i < ready.length; i++) {
+        visited++;
+        for (const target of adjacency.get(ready[i]) ?? []) {
+            indegree.set(target, indegree.get(target) - 1);
+            if (indegree.get(target) === 0)
+                ready.push(target);
+        }
+    }
+    if (visited !== ids.size)
+        throw new Error('Knowledge provenance cycle');
+}
+function plan(root, records, proposal, createdAt) {
+    if (!Number.isFinite(Date.parse(createdAt)))
+        throw new Error('Invalid lifecycle timestamp');
+    const before = new Map(records.map(r => [r.item.id, r]));
+    for (const [id, revision] of Object.entries(proposal.expectedRevisions)) {
+        if (before.get(id)?.revision !== revision)
+            throw new Error(`Stale source revision: ${id}`);
+    }
+    // Incomparable source boundaries cannot be replaced by one broader record.
+    const skipped = new Set(proposal.create.filter(input => { const sources = proposal.links.filter(l => l.from === input.id).flatMap(l => before.has(l.to) ? [before.get(l.to).item] : []); return sources.length > 1 && !sources.every(s => sameApplicability(s, sources[0])); }).map(i => i.id));
+    const preserved = new Set(proposal.links.filter(l => skipped.has(l.from)).map(l => l.to));
+    const after = new Map(records.map(r => [r.item.id, structuredClone(r)]));
+    for (const input of proposal.create) {
+        if (skipped.has(input.id))
+            continue;
+        if (after.has(input.id))
+            throw new Error(`Knowledge ID already exists: ${input.id}`);
+        assertEnglishProse([input.title, input.content], 'Lifecycle knowledge');
+        const { layer, ...fields } = input;
+        const item = { ...fields, status: 'active', createdAt, updatedAt: createdAt, sourceSessions: input.sourceSessions ?? [], derivedFrom: input.derivedFrom ?? [], supersedes: [], related: input.related ?? [], relations: [] };
+        const sources = proposal.links.filter(l => l.from === item.id).flatMap(l => before.has(l.to) ? [before.get(l.to).item] : []);
+        Object.assign(item, withApplicability(inferredKnowledge(item), input.applicability ?? (sources[0] ? applicabilityOf(sources[0]) : { kind: 'legacy' })), { version: 3 });
+        inheritKnowledgePolicy(item, proposal.links.filter(link => link.from === item.id).flatMap(link => before.has(link.to) ? [before.get(link.to).item] : []));
+        Object.assign(item, evaluateKnowledgeTransition(root, item, undefined, { sources: proposal.links.filter(link => link.from === item.id).flatMap(link => before.has(link.to) ? [before.get(link.to).item] : []) }).item);
+        const parsed = parseKnowledge(renderKnowledge(item), `${item.id}.md`);
+        if (parsed.title !== item.title || parsed.content !== item.content)
+            throw new Error('Lifecycle formatting would alter semantic content; revise title/body explicitly');
+        after.set(item.id, { item: parsed, layer, path: `${layer === 'local' ? 'local/' : ''}memory/${item.id}.md`, revision: '', storage: 'current' });
+    }
+    for (const link of proposal.links) {
+        if (skipped.has(link.from))
+            continue;
+        const newer = after.get(link.from), older = after.get(link.to);
+        if (!newer || !older)
+            throw new Error('Missing knowledge ID in lifecycle link');
+        if (link.from === link.to)
+            throw new Error('Self supersession/consolidation is forbidden');
+        const exists = provenanceEdges([newer.item, older.item]).some(e => e.from === link.from && e.to === link.to && e.type === link.type);
+        if (exists)
+            continue;
+        if (newer.storage === 'archive')
+            throw new Error('Archived records are immutable provenance sources');
+        if (protectedKnowledge(older.item) && !coversProtection(older.item, newer.item))
+            continue;
+        if (link.type === 'supersedes')
+            newer.item.supersedes.push(link.to);
+        else
+            (newer.item.relations ??= []).push({ type: 'consolidates', target: link.to });
+    }
+    validateGraph([...after.values()].map(r => r.item));
+    const edges = provenanceEdges([...after.values()].map(r => r.item));
+    const affected = new Set(proposal.links.map(l => l.to));
+    const archiving = new Set(proposal.archive);
+    for (const id of new Set([...affected, ...archiving])) {
+        if (preserved.has(id))
+            continue;
+        const record = after.get(id);
+        if (!record)
+            throw new Error(`Missing knowledge ID: ${id}`);
+        if (record.storage === 'archive')
+            continue;
+        const incoming = edges.filter(e => e.to === id);
+        // Local provenance may reference Versioned sources without publishing a mutation to them.
+        if (incoming.length && (record.layer === 'local' || archiving.has(id))) {
+            if (incoming.some(e => e.type === 'supersedes'))
+                record.item.status = 'superseded';
+            else if (record.item.status === 'active')
+                record.item.status = 'consolidated';
+            // Consolidation must not erase an existing supersession, deprecation or dispute.
+        }
+        if (archiving.has(id)) {
+            if (protectedKnowledge(record.item) && (record.item.status === 'active' || record.item.status === 'disputed'))
+                continue;
+            if (record.item.status === 'active' || record.item.status === 'disputed')
+                throw new Error('Only historical knowledge can be archived');
+            record.item.archivedAt = createdAt;
+            record.path = knowledgeArchivePath(record.layer, createdAt, id);
+            record.storage = 'archive';
+        }
+    }
+    const changes = [];
+    for (const [id, record] of after) {
+        const original = before.get(id);
+        if (original && original.path === record.path && JSON.stringify(original.item) === JSON.stringify(record.item))
+            continue;
+        record.item.updatedAt = createdAt;
+        const text = renderKnowledge(record.item);
+        parseKnowledge(text, `${id}.md`);
+        changes.push({ id, layer: record.layer, from: original?.path ?? null, to: record.path, before: original?.revision ?? null, after: text });
+    }
+    changes.sort((a, b) => a.id.localeCompare(b.id));
+    const value = { version: 1, proposal, createdAt, inventoryHash: inventoryHash(records), changes, versionedChanges: changes.filter(c => c.layer === 'versioned').map(c => c.id) };
+    return { ...value, planId: digest(value) };
+}
+const withLifecycleLock = (root, operation) => ownsSyncLock(root) ? operation() : withSyncLock(root, operation);
+/** Recover pending work under the writer lock, then prepare a plan without applying it. */
+export async function previewKnowledgeLifecycle(root, input, createdAt = new Date().toISOString()) {
+    const proposal = proposalSchema.parse(input);
+    return withLifecycleLock(root, async () => {
+        await assertCompatibleProject(root);
+        await recoverSyncTransaction(root);
+        return plan(root, await readKnowledgeInventory(root), proposal, createdAt);
+    });
+}
+/** Only Core chooses paths and writes. Versioned writes require the exact reviewed preview. */
+export async function applyKnowledgeLifecycle(root, preview, review = {}) {
+    return withLifecycleLock(root, async () => {
+        await assertCompatibleProject(root);
+        await recoverSyncTransaction(root);
+        const proposal = proposalSchema.parse(preview.proposal), proposalHash = digest(proposal);
+        const { planId, ...value } = preview;
+        if (preview.version !== 1 || digest(value) !== planId)
+            throw new Error('Lifecycle preview was modified');
+        const checkpoints = await listCheckpoints(root);
+        const receipt = checkpoints.find(c => c.lifecycle?.operationId === proposal.operationId);
+        if (receipt) {
+            if (receipt.lifecycle?.planId !== planId || receipt.lifecycle.proposalHash !== proposalHash || receipt.lifecycle.transformationPreviewId !== review.transformationPreviewId)
+                throw new Error('Lifecycle operation ID already used by a different plan');
+            return { checkpoint: receipt.id, alreadyApplied: true, changed: receipt.createdMemory.length + receipt.updatedMemory.length };
+        }
+        const records = await readKnowledgeInventory(root);
+        if (inventoryHash(records) !== preview.inventoryHash)
+            throw new Error('Stale lifecycle preview: knowledge changed; prepare a new preview');
+        if (proposal.archive.length && preview.createdAt.slice(0, 7) !== new Date().toISOString().slice(0, 7))
+            throw new Error('Stale archive month: prepare a new lifecycle preview');
+        const computed = plan(root, records, proposal, preview.createdAt);
+        if (computed.planId !== planId)
+            throw new Error('Lifecycle preview does not match the validated proposal');
+        if (computed.versionedChanges.length && (!review.approvedVersioned || review.reviewedPlanId !== planId))
+            throw new Error('Versioned lifecycle changes require approval of this exact reviewed preview');
+        const writes = [], moves = [];
+        for (const c of computed.changes) {
+            const moving = c.from !== null && c.from !== c.to;
+            writes.push({ path: c.to, before: moving ? null : c.before, after: c.after });
+            if (moving)
+                moves.push({ from: c.from, to: c.to, before: c.before });
+        }
+        const checkpoint = {
+            id: sortableId('chk'), createdAt: new Date().toISOString(),
+            previousCheckpoint: checkpoints.at(-1)?.id ?? null, sessions: [], consolidation: 'not-performed',
+            createdMemory: computed.changes.filter(c => !c.from).map(c => c.id), updatedMemory: computed.changes.filter(c => c.from).map(c => c.id),
+            supersededMemory: computed.changes.filter(c => parseKnowledge(c.after, `${c.id}.md`).status === 'superseded').map(c => c.id), duplicateMemory: [], conflicts: [],
+            summary: { sessions: 0, candidates: 0, created: computed.changes.filter(c => !c.from).length, consolidated: 0, duplicates: 0, superseded: 0, conflicts: 0 },
+            lifecycle: { operationId: proposal.operationId, planId, proposalHash, ...(review.transformationPreviewId ? { transformationPreviewId: review.transformationPreviewId } : {}) },
+        };
+        writes.push({ path: `checkpoints/${checkpoint.id}.json`, before: null, after: JSON.stringify(checkpoint, null, 2) + '\n' });
+        await commitSyncTransaction(root, writes, { moves });
+        return { checkpoint: checkpoint.id, alreadyApplied: false, changed: computed.changes.length };
+    });
+}
+//# sourceMappingURL=knowledge-lifecycle.js.map

package/dist/core/knowledge-management.js

@@ -0,0 +1,113 @@
+import { applicabilitySchema, taskContextInputSchema, withApplicability, applicabilityLabel, buildTaskContext, evaluateApplicability } from "./applicability.js";
+import { safeRelative } from "./plugin-files.js";
+import { z } from 'zod';
+import { loadMemoryCatalog } from './memory-index.js';
+import { searchMemoryPage, forgetMemory } from './memory-operations.js';
+import { promotionRecommendations } from './promotion.js';
+import { assertNoSecrets } from './secrets.js';
+import { assertEnglishProse } from './language.js';
+import { renderKnowledge, parseKnowledge } from './memory.js';
+import { buildIndex } from './index.js';
+import { commitSyncTransaction, withSyncLock, recoverSyncTransaction } from './sync-transaction.js';
+import { listCheckpoints } from './storage.js';
+import { sortableId } from './ids.js';
+export const knowledgeQuerySchema = z.object({
+    task: z.string().max(2000).optional(), taskContext: taskContextInputSchema.optional(),
+    query: z.string().max(1000).default(''), layer: z.enum(['local', 'versioned']).optional(),
+    category: z.enum(['principle', 'invariant', 'decision', 'constraint', 'lesson', 'state', 'instruction']).optional(),
+    scope: z.enum(['global', 'project', 'path']).optional(), path: z.string().max(300).optional(),
+    includeHistorical: z.boolean().default(false), offset: z.number().int().min(0).default(0), limit: z.number().int().min(1).max(20).default(12),
+});
+export const knowledgeMutationSchema = z.object({
+    applicability: applicabilitySchema.optional(),
+    id: z.string().regex(/^[a-zA-Z0-9_-]+$/), revision: z.string().regex(/^[a-f0-9]{64}$/),
+    priority: z.enum(['critical', 'important', 'normal', 'contextual']).optional(),
+    scope: z.enum(['global', 'module', 'task']).optional(), scopeRef: z.string().trim().max(300).nullable().optional(), scopeKind: z.enum(['path', 'topic']).nullable().optional(),
+    action: z.enum(['edit', 'retire']), mode: z.enum(['local', 'repository-maintenance']).default('local'), approved: z.literal(true),
+    title: z.string().trim().min(1).max(200).regex(/^[^\r\n]+$/).optional(), content: z.string().trim().min(1).max(10000).optional(), reason: z.string().trim().max(1000).optional(),
+}).strict();
+export async function knowledgeView(root, raw = {}, id) {
+    const options = knowledgeQuerySchema.parse(raw);
+    if (options.scope === 'path') {
+        if (!options.path?.trim())
+            throw new Error('Path filtering requires a repository-relative path.');
+        options.path = safeRelative(options.path.trim().replace(/^\.\//, '').replace(/\/$/, ''));
+    }
+    const catalog = await loadMemoryCatalog(root);
+    const current = catalog.summaries.filter(i => ['active', 'disputed'].includes(i.status));
+    const recommendations = await promotionRecommendations(root);
+    const page = await searchMemoryPage(root, options.query, { ...options, includeShadowed: true });
+    const detailSummary = id ? catalog.summaries.find(i => i.id === id) : undefined;
+    if (id && !detailSummary)
+        throw new Error('Knowledge was not found. Refresh the list.');
+    const detail = detailSummary ? { ...await catalog.load(detailSummary.id), layer: detailSummary.layer, revision: catalog.originalHashes.get(detailSummary.id), recommendation: recommendations.find(r => r.id === id) } : null;
+    if (detail) {
+        Object.assign(detail, { appliesTo: applicabilityLabel(detail), ...(options.task || options.taskContext ? { applicabilityDecision: evaluateApplicability(detail, buildTaskContext(options.task, options.taskContext, catalog.summaries.flatMap(i => i.applicability?.kind === 'scoped' ? i.applicability.subsystems ?? [] : []), catalog.summaries.flatMap(i => i.applicability?.kind === 'scoped' ? i.applicability.paths ?? [] : [])), detail.contextPolicy === 'required' ? 'required' : 'relevant') } : {}) });
+    }
+    return { root, ...page, options, detail, counts: { local: current.filter(i => i.layer === 'local').length, versioned: current.filter(i => i.layer === 'versioned').length, recommended: recommendations.filter(r => r.recommended).length },
+        matches: page.matches.map(({ content, ...item }) => ({ ...item, contentPreview: content.slice(0, 240), recommendation: recommendations.find(r => r.id === item.id) })) };
+}
+/** Explicit editorial maintenance, preserving identity/topology and existing checkpoint history. */
+export async function mutateKnowledge(root, raw) {
+    assertNoSecrets(raw);
+    const input = knowledgeMutationSchema.parse(raw);
+    assertEnglishProse([input.title, input.content, input.reason], 'Knowledge maintenance');
+    if (input.action !== 'edit' && [input.priority, input.scope, input.scopeRef, input.scopeKind, input.applicability].some(v => v !== undefined))
+        throw new Error('Classification changes require an instruction edit.');
+    if (input.mode === 'local' && input.action === 'retire')
+        return forgetMemory(root, { id: input.id, revision: input.revision, reason: input.reason });
+    return withSyncLock(root, async () => {
+        await recoverSyncTransaction(root);
+        const catalog = await loadMemoryCatalog(root);
+        const summary = catalog.summaries.find(i => i.id === input.id);
+        if (!summary)
+            throw new Error('Knowledge was not found. Refresh the list.');
+        if ((summary.layer === 'versioned') !== (input.mode === 'repository-maintenance'))
+            throw new Error('Versioned Knowledge requires explicit repository-maintenance approval. Local operations cannot modify repository knowledge.');
+        const item = await catalog.load(input.id);
+        const before = catalog.originalHashes.get(input.id);
+        if (before !== input.revision)
+            throw new Error('Knowledge changed since it was opened. Reload and review the current revision.');
+        if (!['active', 'disputed'].includes(item.status))
+            throw new Error('Historical knowledge cannot be edited or reopened.');
+        if (input.action === 'edit' && (input.title === undefined || input.content === undefined))
+            throw new Error('Editing requires a title and complete statement.');
+        const classification = { priority: item.priority, scope: item.scope, scopeRef: item.scopeRef, scopeKind: item.scopeKind };
+        if (input.priority !== undefined || input.scope !== undefined || input.scopeRef !== undefined || input.scopeKind !== undefined) {
+            if (item.category !== 'instruction' || input.action !== 'edit')
+                throw new Error('Classification edits apply only to instruction edits.');
+            classification.priority = input.priority ?? item.priority;
+            classification.scope = input.scope ?? item.scope;
+            classification.scopeRef = input.scopeRef === undefined ? item.scopeRef : input.scopeRef;
+            classification.scopeKind = input.scopeKind === undefined ? item.scopeKind : input.scopeKind ?? undefined;
+            if (classification.scope === 'global') {
+                classification.scopeRef = null;
+                classification.scopeKind = undefined;
+            }
+            else if (!classification.scopeRef)
+                throw new Error('Scoped instructions require a scope reference.');
+            if (classification.scopeKind === 'path')
+                classification.scopeRef = safeRelative(classification.scopeRef);
+        }
+        if (input.action === 'edit' && !input.applicability && item.title === input.title && item.content === input.content && Object.entries(classification).every(([k, v]) => item[k] === v))
+            return { item, unchanged: true };
+        const now = new Date();
+        const checkpointId = sortableId('chk', now);
+        const updated = { ...item, ...classification, title: input.action === 'edit' ? input.title : item.title, content: input.action === 'edit' ? input.content : item.content,
+            status: input.action === 'retire' ? 'deprecated' : item.status, updatedAt: now.toISOString(),
+            derivedFrom: [...new Set([...item.derivedFrom, `user:maintenance:${checkpointId}`])],
+            evidence: [...(item.evidence ?? []), { kind: 'user_instruction', ref: input.reason || `Explicit ${input.mode} ${input.action}` }], };
+        if (input.applicability)
+            Object.assign(updated, withApplicability(updated, input.applicability), { version: 3 });
+        if (!input.applicability && item.applicability?.kind !== 'legacy' && [input.scope, input.scopeRef, input.scopeKind].some(v => v !== undefined) && (classification.scope !== item.scope || classification.scopeRef !== item.scopeRef || classification.scopeKind !== item.scopeKind)) {
+            throw new Error('Use structured applicability to change this record’s work boundary; its legacy scope fields are a projection.');
+        }
+        const after = renderKnowledge(updated);
+        parseKnowledge(after, summary.filename);
+        const checkpoint = { id: checkpointId, createdAt: now.toISOString(), previousCheckpoint: (await listCheckpoints(root)).at(-1)?.id ?? null, sessions: [], consolidation: 'not-performed', knowledgeBefore: [item], createdMemory: [], updatedMemory: [item.id], supersededMemory: [], duplicateMemory: [], conflicts: [], summary: { sessions: 0, candidates: 0, created: 0, consolidated: 0, duplicates: 0, superseded: 0, conflicts: 0 }, note: `Explicit ${input.mode} ${input.action}: ${item.id}` };
+        await commitSyncTransaction(root, [{ path: summary.relativePath, before, after }, { path: `checkpoints/${checkpointId}.json`, before: null, after: JSON.stringify(checkpoint, null, 2) + '\n' }], { policyMode: 'exact' });
+        await buildIndex(root);
+        return { item: await (await loadMemoryCatalog(root)).load(updated.id), checkpoint: checkpointId, layer: summary.layer };
+    });
+}
+//# sourceMappingURL=knowledge-management.js.map

package/dist/core/knowledge-migration.js

@@ -0,0 +1,84 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { checkedDataPath, exists, writeFileAtomic } from './storage.js';
+import { parseFrontmatter, frontmatter } from './format.js';
+import { parseKnowledge, renderKnowledge } from './memory.js';
+/** Current and historical canonical stores, in deterministic order. Checkpoint
+ * preimages remain historical evidence and are not rewritten as current records. */
+export async function knowledgeFiles(root) {
+    const directories = ['memory', 'local/memory'];
+    for (const archive of ['archive', 'local/archive']) {
+        const directory = await checkedDataPath(root, archive);
+        if (await exists(directory))
+            for (const month of (await fs.readdir(directory)).sort()) {
+                if (/^\d{4}_\d{2}$/.test(month))
+                    directories.push(`${archive}/${month}`);
+            }
+    }
+    const files = [];
+    for (const directory of directories) {
+        const target = await checkedDataPath(root, directory);
+        if (await exists(target))
+            for (const name of (await fs.readdir(target)).sort()) {
+                if (name.endsWith('.md') && !name.startsWith('.'))
+                    files.push(`${directory}/${name}`);
+            }
+    }
+    return files;
+}
+/** Mechanical compatibility conversion only: no lexical rules, scope inference,
+ * model calls, status filtering or authority promotion. */
+export async function migrateKnowledgeV1ToV2(root) {
+    for (const relative of await knowledgeFiles(root)) {
+        const target = await checkedDataPath(root, relative), filename = path.basename(relative);
+        const before = await fs.readFile(target, 'utf8');
+        const old = parseKnowledge(before, filename);
+        if (old.version === 2)
+            continue;
+        const { metadata, body } = parseFrontmatter(before, filename);
+        let after;
+        if (metadata.kind === 'knowledge') {
+            // Preserve bodies, provenance and unrelated metadata byte-for-byte. The old
+            // enforcement field was never canonical; remove that ignored draft alias.
+            const eol = before.startsWith('---\r\n') ? '\r\n' : '\n';
+            const end = before.indexOf(`${eol}---${eol}`, 3 + eol.length);
+            const header = before.slice(0, end).replace(/^enforcement:.*(?:\r?\n|$)/m, '');
+            after = header.replace(/^---\r?\n/, `---${eol}version: 2${eol}context_policy: ${old.contextPolicy}${eol}authority: legacy_inherited${eol}`) + before.slice(end);
+        }
+        else {
+            // Legacy unstructured Markdown acquires explicit structural metadata while
+            // keeping precisely the same effective title/content/defaults.
+            const canonical = parseFrontmatter(renderKnowledge({ ...old, version: 2 }), filename).metadata;
+            const { enforcement: _ignored, ...preserved } = metadata;
+            after = frontmatter({ ...preserved, ...canonical }, body);
+        }
+        const next = parseKnowledge(after, filename, 2);
+        if (JSON.stringify({ ...old, version: 2 }) !== JSON.stringify(next))
+            throw new Error(`Knowledge policy migration changed effective knowledge: ${relative}`);
+        await writeFileAtomic(target, after);
+    }
+}
+export async function validateKnowledgeV2(root) {
+    for (const relative of await knowledgeFiles(root)) {
+        parseKnowledge(await fs.readFile(await checkedDataPath(root, relative), 'utf8'), path.basename(relative), 2);
+    }
+}
+/** Preserve exact old selector semantics; never infer scope from prose. */
+export async function migrateKnowledgeV2ToV3(root) {
+    for (const relative of await knowledgeFiles(root)) {
+        const target = await checkedDataPath(root, relative), filename = path.basename(relative), before = await fs.readFile(target, 'utf8');
+        const old = parseKnowledge(before, filename, 2);
+        const eol = before.startsWith('---\r\n') ? '\r\n' : '\n';
+        const after = before.replace(/^version: 2\r?$/m, `version: 3${eol}applicability: {"kind":"legacy"}`);
+        const next = parseKnowledge(after, filename, 3);
+        const { applicability, ...rest } = next;
+        if (JSON.stringify({ ...old, version: 3 }) !== JSON.stringify(rest))
+            throw new Error(`Applicability migration changed canonical knowledge: ${relative}`);
+        await writeFileAtomic(target, after);
+    }
+}
+export async function validateKnowledgeV3(root) {
+    for (const relative of await knowledgeFiles(root))
+        parseKnowledge(await fs.readFile(await checkedDataPath(root, relative), 'utf8'), path.basename(relative), 3);
+}
+//# sourceMappingURL=knowledge-migration.js.map

package/dist/core/knowledge-policy.js

@@ -0,0 +1,38 @@
+export const CONTEXT_POLICIES = ['required', 'relevant'];
+export const KNOWLEDGE_AUTHORITIES = ['legacy_inherited', 'inferred', 'imported', 'explicit_user', 'reviewed'];
+/** Classification is not proof of user intent. Evidence remains in the existing
+ * evidence/sourceSessions/derivedFrom fields. No Phase 1A writer grants stronger
+ * authority merely on an agent's assertion or on publication approval. */
+export function validateKnowledgePolicy(category, policy, authority) {
+    if (!CONTEXT_POLICIES.includes(policy))
+        throw new Error('Invalid canonical knowledge contextPolicy');
+    if (!KNOWLEDGE_AUTHORITIES.includes(authority))
+        throw new Error('Invalid canonical knowledge authority');
+    if (policy === 'required' && category !== 'instruction')
+        throw new Error('Required contextPolicy is supported only for instruction records in Knowledge Schema v2');
+}
+/** Strict canonical v2/v3 policy plus a v1/trusted-draft compatibility adapter.
+ * Inference writers explicitly use inferredKnowledge and the transaction gate;
+ * unversioned draft defaults are not authorization to create mandatory knowledge. */
+export function knowledgePolicy(item) {
+    const contextPolicy = (item.version ?? 0) >= 2 ? item.contextPolicy : item.contextPolicy ?? (item.category === 'instruction' ? 'required' : 'relevant');
+    const authority = (item.version ?? 0) >= 2 ? item.authority : item.authority ?? (item.version === 1 ? 'legacy_inherited' : 'inferred');
+    validateKnowledgePolicy(item.category, contextPolicy, authority);
+    return { version: item.version === 3 ? 3 : 2, contextPolicy: contextPolicy, authority: authority,
+        ...(item.category === 'instruction' ? { kind: 'instruction', enforcement: contextPolicy } : {}) };
+}
+/** Preserve policy when editing/replacing canonical sources of the same category.
+ * Ambiguous source policies need a separate reviewed operation, not a guessed default. */
+export function inheritKnowledgePolicy(item, sources) {
+    const matching = sources.filter(source => source.category === item.category);
+    if (!matching.length)
+        return;
+    const policies = matching.map(knowledgePolicy);
+    if (new Set(policies.map(p => p.contextPolicy)).size !== 1) {
+        Object.assign(item, knowledgePolicy({ ...item, version: item.version === 3 ? 3 : 2, contextPolicy: 'relevant', authority: 'inferred' }));
+        return;
+    }
+    const authority = new Set(policies.map(p => p.authority)).size === 1 ? policies[0].authority : 'inferred';
+    Object.assign(item, knowledgePolicy({ ...item, version: item.version === 3 ? 3 : 2, contextPolicy: policies[0].contextPolicy, authority }));
+}
+//# sourceMappingURL=knowledge-policy.js.map