@tenphi/akno-core 0.7.0 → 0.9.0

package/dist/ops/retain.js

@@ -1,10 +1,12 @@
 import fsp from 'node:fs/promises';
 import path from 'node:path';
-import { RetainInput, } from '@tenphi/akno-protocol';
+import { AknoError, RetainInput, } from '@tenphi/akno-protocol';
 import { ModelClient } from "../models/client.js";
 import { folderCatalog } from "../kb/folders.js";
 import { parseFrontmatter, serializeYamlString } from "../kb/frontmatter.js";
 import { parsePage } from "../kb/page.js";
+import { contentWords } from "../kb/words.js";
+import { declaringRule, effectiveRule } from "../rules/compile.js";
 import { isReserved } from "../reserved.js";
 import { newPrefixedId, sha256 } from "../store/ids.js";
 import { restoreFile, writeFileAtomic } from "../write/atomic.js";
@@ -14,25 +16,33 @@ import { managedMemoryBlock, managedMemoryFingerprint, markerFromProvidedCandida
 import { appendManagedBlock, managedSourceReference, placeManagedItems } from "../write/placement.js";
 import { modelCallReceipt, runRetain, } from "../write/retain.js";
 import { resolveRememberFallback } from "../write/remember-fallback.js";
-import { reconcileRetainManagedSources } from "../write/retain-supports.js";
+import { pruneRetainEvidence, reconcileRetainManagedSources } from "../write/retain-supports.js";
 import { routeAutomaticCandidate } from "./remember.js";
-import { normalizeSlug } from "./write.js";
+import { read } from "./read.js";
+import { normalizeSlug, titleFromSlug } from "./write.js";
 export async function retain(ctx, rawInput) {
     const input = RetainInput.parse(rawInput);
     const results = [];
     for (const source of input.sources) {
         try {
-            results.push('input' in source
-                ? source.retention.mode === 'extract'
-                    ? await retainExtracted(ctx, source, input.dry_run ?? false)
-                    : await retainCandidates(ctx, source, source.retention.candidates, {
-                        dryRun: input.dry_run ?? false,
-                        selection: 'provided',
-                        placement: source.retention.placement,
-                        initialResults: [],
-                        modelUsage: { extraction: null, verification: null, placement: [] },
-                    })
-                : await retractSource(ctx, source, input.dry_run ?? false));
+            if (!('input' in source)) {
+                results.push(await retractSource(ctx, source, input.dry_run ?? false));
+                continue;
+            }
+            const resolved = await resolveRetainSource(ctx, source);
+            if ('result' in resolved) {
+                results.push(resolved.result);
+                continue;
+            }
+            results.push(source.retention.mode === 'extract'
+                ? await retainExtracted(ctx, resolved, input.dry_run ?? false)
+                : await retainCandidates(ctx, resolved, source.retention.candidates, {
+                    dryRun: input.dry_run ?? false,
+                    selection: 'provided',
+                    placement: source.retention.placement,
+                    initialResults: [],
+                    modelUsage: { extraction: null, verification: null, placement: [] },
+                }));
         }
         catch (error) {
             results.push({
@@ -53,24 +63,137 @@ export async function retain(ctx, rawInput) {
     const effective = results.filter((result) => result.outcome === 'ok').length;
     const degraded = [...new Set(results.flatMap((result) => result.degraded ?? []))];
     const allEmpty = results.length > 0 && results.every((result) => result.status === 'empty');
+    const allUnavailable = results.length > 0 && results.every((result) => result.status === 'unavailable');
     return {
-        status: degraded.length > 0 ? 'degraded' : allEmpty ? 'empty' : 'ok',
+        status: allUnavailable ? 'unavailable' : degraded.length > 0 ? 'degraded' : allEmpty ? 'empty' : 'ok',
         ...(degraded.length > 0 ? { degraded } : {}),
         outcome: incomplete && effective > 0 ? 'partial' : effective > 0 ? 'ok' : 'noop',
         sources: results,
     };
 }
-async function retainExtracted(ctx, source, dryRun) {
+async function resolveRetainSource(ctx, requested) {
+    const input = requested.input;
+    if ('text' in input || 'items' in input) {
+        const kind = 'text' in input ? 'text' : 'items';
+        return {
+            source: { ...requested, input },
+            requested,
+            sourceHash: sha256(JSON.stringify(input)),
+            sourceRef: requested.locator ?? requested.source_id,
+            binding: {
+                kind,
+                availability: 'available',
+                reextractable: requested.preserve_source !== undefined,
+                ...(requested.preserve_source
+                    ? { preservedSlug: normalizeSlug(requested.preserve_source.slug) }
+                    : {}),
+            },
+            degraded: [],
+        };
+    }
+    if ('page_slug' in input) {
+        const slug = normalizeSlug(input.page_slug);
+        const row = ctx.store.db.prepare('SELECT rel_path, role FROM pages WHERE slug = ?').get(slug);
+        if (!row)
+            return { result: unavailableSourceResult(requested, 'page', slug, 'source page is not indexed') };
+        if (row.role !== 'source') {
+            return {
+                result: unavailableSourceResult(requested, 'page', slug, 'page_slug accepts only a page whose effective role is source', 'validation_failed'),
+            };
+        }
+        const bytes = await fsp.readFile(path.join(ctx.config.aknoPath, row.rel_path), 'utf8').catch(() => null);
+        if (bytes === null) {
+            return { result: unavailableSourceResult(requested, 'page', slug, 'source page is unreadable') };
+        }
+        const sourceText = parsePage(row.rel_path, bytes).body;
+        if (!sourceText.trim()) {
+            return { result: unavailableSourceResult(requested, 'page', slug, 'source page has no readable body') };
+        }
+        return {
+            source: { ...requested, input: { text: sourceText } },
+            requested,
+            sourceHash: sha256(bytes),
+            sourceRef: requested.locator ?? slug,
+            binding: { kind: 'page', availability: 'available', reextractable: true, reference: slug },
+            degraded: [],
+        };
+    }
+    try {
+        const output = await read(ctx, { document: input.document_id });
+        if (!output.document) {
+            return {
+                result: unavailableSourceResult(requested, 'document', input.document_id, 'document reference did not resolve to readable document state'),
+            };
+        }
+        const document = output.document;
+        if (!document.text) {
+            return {
+                result: unavailableSourceResult(requested, 'document', document.id, output.note ?? 'document has no readable extraction or rendition'),
+            };
+        }
+        const degraded = output.status === 'ok' ? [] : (output.degraded ?? ['no_document_text']);
+        const documentParts = ctx.store.db
+            .prepare(`SELECT rel_path, sha256 FROM documents
+          WHERE group_key = (
+            SELECT group_key FROM documents WHERE id = ?
+          ) AND renders IS NULL
+          ORDER BY part`)
+            .all(document.id);
+        return {
+            source: { ...requested, input: { text: document.text } },
+            requested,
+            sourceHash: sha256(JSON.stringify({ id: document.id, parts: documentParts, text: document.text })),
+            sourceRef: requested.locator ?? document.rel_path,
+            binding: {
+                kind: 'document',
+                availability: output.status === 'ok' ? 'available' : 'degraded',
+                reextractable: true,
+                reference: document.id,
+            },
+            degraded,
+        };
+    }
+    catch (error) {
+        const note = error instanceof AknoError ? error.message : `document source failed: ${String(error)}`;
+        return { result: unavailableSourceResult(requested, 'document', input.document_id, note) };
+    }
+}
+function unavailableSourceResult(source, kind, reference, note, reasonCode = 'source_unavailable') {
+    return {
+        source_id: source.source_id,
+        revision: source.revision,
+        outcome: 'held',
+        status: 'unavailable',
+        reason_code: reasonCode,
+        candidates: [],
+        source: { kind, availability: 'unavailable', reextractable: true, reference },
+        note,
+    };
+}
+function sourceResultBinding(binding) {
+    return {
+        kind: binding.kind,
+        availability: binding.availability,
+        reextractable: binding.reextractable,
+        ...(binding.reference ? { reference: binding.reference } : {}),
+        ...(binding.preservedSlug ? { preserved_slug: binding.preservedSlug } : {}),
+    };
+}
+async function retainExtracted(ctx, resolved, dryRun) {
+    const source = resolved.source;
     if (source.retention.mode !== 'extract')
         throw new Error('retain extract received a provided source');
-    const sourceHash = sha256(JSON.stringify(source.input));
-    const requestHash = sha256(JSON.stringify(source));
+    const sourceHash = resolved.sourceHash;
+    const requestHash = sha256(JSON.stringify(resolved.requested));
     const replay = replayResult(ctx, source.source_id, source.revision, requestHash, sourceHash);
     if (replay)
         return replay;
     const groupIssue = sourceGroupIssue(ctx, source.source_id, source.source_group);
     if (groupIssue)
         return conflictResult(source.source_id, source.revision, groupIssue);
+    const correctionIssue = validateCorrectionTarget(ctx, source);
+    if (correctionIssue)
+        return correctionHoldResult(resolved, correctionIssue);
     const curator = retentionModel(ctx);
     const text = 'text' in source.input ? source.input.text : source.input.items.map((item) => item.text).join('\n');
     const extracted = await runRetain(text, curator, {
@@ -83,7 +206,7 @@ async function retainExtracted(ctx, source, dryRun) {
         revision: source.revision,
     });
     if (extracted.sourceHold) {
-        return retainCandidates(ctx, source, [], {
+        return retainCandidates(ctx, resolved, [], {
             dryRun,
             selection: 'extracted',
             placement: 'automatic',
@@ -94,18 +217,20 @@ async function retainExtracted(ctx, source, dryRun) {
     }
     const initialResults = extracted.held.map(heldCandidateResult);
     if (extracted.error) {
-        return {
-            source_id: source.source_id,
-            revision: source.revision,
-            outcome: 'held',
-            status: 'degraded',
-            degraded: [extracted.degradedReason ?? 'derive_failed'],
-            candidates: initialResults,
-            model_usage: { ...extracted.modelUsage, placement: [] },
-            note: `automatic retention could not complete: ${extracted.error}`,
-        };
+        return retainCandidates(ctx, resolved, [], {
+            dryRun,
+            selection: 'extracted',
+            placement: 'automatic',
+            initialResults,
+            modelUsage: { ...extracted.modelUsage, placement: [] },
+            additionalDegraded: [extracted.degradedReason ?? 'derive_failed'],
+            sourceHold: {
+                reason_code: initialResults[0]?.reason_code ?? 'apply_failed',
+                reason: `automatic retention could not complete: ${extracted.error}`,
+            },
+        });
     }
-    return retainCandidates(ctx, source, extracted.candidates, {
+    return retainCandidates(ctx, resolved, extracted.candidates, {
         dryRun,
         selection: 'extracted',
         placement: 'automatic',
@@ -113,16 +238,20 @@ async function retainExtracted(ctx, source, dryRun) {
         modelUsage: { ...extracted.modelUsage, placement: [] },
     });
 }
-async function retainCandidates(ctx, source, suppliedCandidates, options) {
-    const sourceHash = sha256(JSON.stringify(source.input));
-    const requestHash = sha256(JSON.stringify(source));
+async function retainCandidates(ctx, resolvedSource, suppliedCandidates, options) {
+    const source = resolvedSource.source;
+    const sourceHash = resolvedSource.sourceHash;
+    const requestHash = sha256(JSON.stringify(resolvedSource.requested));
     const replay = replayResult(ctx, source.source_id, source.revision, requestHash, sourceHash);
     if (replay)
         return replay;
     const groupIssue = sourceGroupIssue(ctx, source.source_id, source.source_group);
     if (groupIssue)
         return conflictResult(source.source_id, source.revision, groupIssue);
-    const resolved = options.placement === 'automatic'
+    const correctionIssue = validateCorrectionTarget(ctx, source);
+    if (correctionIssue)
+        return correctionHoldResult(resolvedSource, correctionIssue);
+    const resolved = options.placement === 'automatic' && !options.skipAutomaticRouting
         ? await resolveAutomaticCandidates(ctx, suppliedCandidates)
         : {
             candidates: suppliedCandidates.filter(hasDestination),
@@ -139,9 +268,74 @@ async function retainCandidates(ctx, source, suppliedCandidates, options) {
     const receiptFingerprint = managedMemoryFingerprint(`receipt:${source.source_id}:${source.revision}:${requestHash}`);
     const proofGroup = managedMemoryFingerprint(`proof:${source.source_group ?? source.source_id}`);
     const stages = new Map();
+    const effectiveBinding = options.sourceHold && resolvedSource.binding.preservedSlug
+        ? {
+            kind: resolvedSource.binding.kind,
+            availability: resolvedSource.binding.availability,
+            reextractable: false,
+            ...(resolvedSource.binding.reference ? { reference: resolvedSource.binding.reference } : {}),
+        }
+        : resolvedSource.binding;
+    if (effectiveBinding.preservedSlug) {
+        if (candidates.some((candidate) => normalizeSlug(candidate.destination.slug) === effectiveBinding.preservedSlug)) {
+            return {
+                source_id: source.source_id,
+                revision: source.revision,
+                outcome: 'held',
+                status: 'ok',
+                reason_code: 'validation_failed',
+                candidates: [],
+                source: sourceResultBinding({
+                    kind: effectiveBinding.kind,
+                    availability: effectiveBinding.availability,
+                    reextractable: false,
+                    ...(effectiveBinding.reference ? { reference: effectiveBinding.reference } : {}),
+                }),
+                note: 'a preserved source page cannot also be a retained-memory destination',
+            };
+        }
+        const preserved = await preservedSourceStage(ctx, stages, effectiveBinding.preservedSlug, resolvedSource.requested.input);
+        if ('issue' in preserved) {
+            return {
+                source_id: source.source_id,
+                revision: source.revision,
+                outcome: 'held',
+                status: 'ok',
+                reason_code: preserved.reasonCode,
+                candidates: [],
+                source: sourceResultBinding({
+                    kind: resolvedSource.binding.kind,
+                    availability: resolvedSource.binding.availability,
+                    reextractable: false,
+                    ...(resolvedSource.binding.reference ? { reference: resolvedSource.binding.reference } : {}),
+                }),
+                note: preserved.issue,
+            };
+        }
+    }
+    const correction = source.retracts
+        ? await stageRetractions(ctx, source.source_id, source.retracts.target_revision, source.retracts.candidate_ids, stages)
+        : { results: [], removed: [], valid: true };
+    if (!correction.valid) {
+        return {
+            source_id: source.source_id,
+            revision: source.revision,
+            outcome: 'held',
+            status: 'ok',
+            reason_code: 'conflict',
+            candidates: correction.results,
+            source: sourceResultBinding(effectiveBinding),
+            note: 'correction targets no longer match their owned memory blocks; nothing was changed',
+        };
+    }
     const pendingSupports = [];
-    const candidateResults = [...options.initialResults, ...resolved.held];
-    const candidateIds = new Set(suppliedCandidates.map((candidate) => candidate.candidate_id));
+    const suppliedCandidateIds = new Set(suppliedCandidates.map((candidate) => candidate.candidate_id));
+    const candidateResults = [
+        ...correction.results.filter((result) => !suppliedCandidateIds.has(result.candidate_id)),
+        ...options.initialResults,
+        ...resolved.held,
+    ];
+    const candidateIds = suppliedCandidateIds;
     const candidateOrder = new Map([
         ...options.initialResults.map((result) => result.candidate_id),
         ...suppliedCandidates.map((candidate) => candidate.candidate_id),
@@ -263,7 +457,7 @@ async function retainCandidates(ctx, source, suppliedCandidates, options) {
                         outcome: 'held',
                         slug,
                         reason_code: 'conflict',
-                        reason: 'conflict',
+                        reason: conflict.existing,
                     });
                     continue;
                 }
@@ -300,7 +494,7 @@ async function retainCandidates(ctx, source, suppliedCandidates, options) {
             selection: options.selection,
             evidence,
             evidence_hash: sha256(evidence),
-            source_ref: managedSourceReference(source.locator ?? source.source_id),
+            source_ref: managedSourceReference(resolvedSource.sourceRef),
             origin: sourceOrigin(candidate.attribution.source_role),
             input_hash: sourceHash,
         });
@@ -313,9 +507,42 @@ async function retainCandidates(ctx, source, suppliedCandidates, options) {
         (candidateOrder.get(right.candidate_id) ?? Number.MAX_SAFE_INTEGER));
     const changed = [...stages.values()].filter((stage) => stage.before !== stage.after);
     const placementDegraded = candidateResults.some((result) => result.reason_code === 'placement_degraded');
-    const degraded = placementDegraded
-        ? [retentionModel(ctx).available ? 'derive_failed' : 'no_derive_model']
-        : [];
+    const degraded = [
+        ...resolvedSource.degraded,
+        ...(options.additionalDegraded ?? []),
+        ...(placementDegraded
+            ? [retentionModel(ctx).available ? 'derive_failed' : 'no_derive_model']
+            : []),
+    ];
+    const acceptedCandidateIds = new Set(candidateResults
+        .filter((result) => ['written', 'support_added', 'duplicate'].includes(result.outcome))
+        .map((result) => result.candidate_id));
+    const correctionAdmissionFailed = source.retracts !== undefined &&
+        (suppliedCandidateIds.size === 0 ||
+            [...suppliedCandidateIds].some((candidateId) => !acceptedCandidateIds.has(candidateId)) ||
+            candidateResults.some((result) => result.outcome === 'held' || result.outcome === 'not_found'));
+    if (correctionAdmissionFailed) {
+        return {
+            source_id: source.source_id,
+            revision: source.revision,
+            outcome: 'held',
+            status: degraded.length > 0 ? 'degraded' : 'ok',
+            reason_code: 'validation_failed',
+            candidates: candidateResults.map((result) => result.outcome === 'held' || result.outcome === 'not_found'
+                ? result
+                : {
+                    candidate_id: result.candidate_id,
+                    outcome: 'held',
+                    ...(result.memory_id ? { memory_id: result.memory_id } : {}),
+                    ...(result.slug ? { slug: result.slug } : {}),
+                    reason_code: 'validation_failed',
+                    reason: 'not applied because the compound correction was not fully admissible',
+                }),
+            source: sourceResultBinding(effectiveBinding),
+            ...(degraded.length > 0 ? { degraded } : {}),
+            note: 'compound correction was not fully admissible; neither removal nor replacement was written',
+        };
+    }
     const preview = {
         source_id: source.source_id,
         revision: source.revision,
@@ -327,6 +554,7 @@ async function retainCandidates(ctx, source, suppliedCandidates, options) {
                     ? 'held'
                     : 'noop',
         candidates: candidateResults,
+        source: sourceResultBinding(effectiveBinding),
         ...(options.sourceHold ? { reason_code: options.sourceHold.reason_code } : {}),
         status: degraded.length > 0
             ? 'degraded'
@@ -348,7 +576,7 @@ async function retainCandidates(ctx, source, suppliedCandidates, options) {
     };
     if (options.dryRun)
         return preview;
-    const committed = await commitStages(ctx, changed, `retained ${candidateResults.filter((item) => ['written', 'support_added'].includes(item.outcome)).length} item(s) from one source revision`);
+    const committed = await commitStages(ctx, changed, `${options.journalOp === 'remember' ? 'remembered' : 'retained'} ${candidateResults.filter((item) => ['written', 'support_added'].includes(item.outcome)).length} item(s) from one source revision`, options.journalOp);
     const changeId = committed?.changeId ?? null;
     const result = { ...preview, ...(changeId ? { change_id: changeId } : {}) };
     try {
@@ -365,15 +593,58 @@ async function retainCandidates(ctx, source, suppliedCandidates, options) {
             result,
             changeId,
             supports: pendingSupports,
-            retracted: [],
+            retracted: correction.removed,
+            binding: effectiveBinding,
         });
     }
     catch (error) {
         await rollbackCommittedStages(ctx, committed, error);
     }
-    await reindexStages(ctx, changed);
+    options.onIndexed?.(await reindexStages(ctx, changed));
     return result;
 }
+/**
+ * Compatibility adapter entrypoint: remember keeps its public routing/action response, while
+ * validation, owned-block staging, source archives, journaling, receipts, and indexing execute
+ * through the same engine as keyed retain.
+ */
+export async function retainRememberCandidates(ctx, input) {
+    const inputHash = sha256(input.text);
+    const sourceId = `remember:${newPrefixedId('src')}`;
+    const requested = {
+        source_id: sourceId,
+        revision: '1',
+        source_group: `remember:${managedMemoryFingerprint(`${input.source ?? 'remember'}:${inputHash}`)}`,
+        source_kind: 'conversation',
+        ...(input.mentionedAt ? { mentioned_at: input.mentionedAt } : {}),
+        ...(input.timezone ? { timezone: input.timezone } : {}),
+        ...(input.source ? { locator: input.source } : {}),
+        input: { text: input.text },
+        retention: { mode: 'extract', ...(input.mission ? { mission: input.mission } : {}) },
+    };
+    const resolved = {
+        source: requested,
+        requested,
+        sourceHash: inputHash,
+        sourceRef: input.source ?? 'remember',
+        binding: { kind: 'text', availability: 'available', reextractable: false },
+        degraded: [],
+    };
+    let factsAdded = 0;
+    const result = await retainCandidates(ctx, resolved, input.candidates, {
+        dryRun: input.dryRun,
+        selection: 'extracted',
+        placement: 'automatic',
+        skipAutomaticRouting: true,
+        journalOp: 'remember',
+        onIndexed: (factsDerived) => {
+            factsAdded = factsDerived;
+        },
+        initialResults: [...input.held],
+        modelUsage: { ...input.modelUsage, placement: [] },
+    });
+    return { result, factsAdded };
+}
 async function resolveAutomaticCandidates(ctx, candidates) {
     const resolved = [];
     const held = [];
@@ -435,34 +706,45 @@ function heldCandidateResult(candidate) {
         reason: candidate.reason,
     };
 }
-async function retractSource(ctx, source, dryRun) {
-    const sourceHash = sha256('retraction');
-    const requestHash = sha256(JSON.stringify(source));
-    const replay = replayResult(ctx, source.source_id, source.revision, requestHash, sourceHash);
-    if (replay)
-        return replay;
+function validateCorrectionTarget(ctx, source) {
+    if (!source.retracts)
+        return null;
+    const target = ctx.store.db
+        .prepare('SELECT receipt_fingerprint FROM retain_receipts WHERE source_id = ? AND revision = ?')
+        .get(source.source_id, source.retracts.target_revision);
+    if (!target)
+        return 'correction target_revision was not retained for this source';
+    const active = new Set(ctx.store.db
+        .prepare(`SELECT candidate_id FROM retain_supports
+           WHERE receipt_fingerprint = ? AND retracted_by IS NULL AND forgotten_by IS NULL`)
+        .all(target.receipt_fingerprint).map((row) => row.candidate_id));
+    const missing = source.retracts.candidate_ids.find((candidateId) => !active.has(candidateId));
+    return missing ? `correction target candidate ${missing} is not active` : null;
+}
+function correctionHoldResult(source, note) {
+    return {
+        source_id: source.source.source_id,
+        revision: source.source.revision,
+        outcome: 'held',
+        status: 'ok',
+        reason_code: 'conflict',
+        candidates: [],
+        source: sourceResultBinding(source.binding),
+        note,
+    };
+}
+async function stageRetractions(ctx, sourceId, targetRevision, candidateIds, stages) {
     const target = ctx.store.db
         .prepare('SELECT * FROM retain_receipts WHERE source_id = ? AND revision = ?')
-        .get(source.source_id, source.retention.target_revision);
-    if (!target) {
-        return {
-            source_id: source.source_id,
-            revision: source.revision,
-            outcome: 'held',
-            reason_code: 'source_unavailable',
-            candidates: [],
-            note: 'target_revision was not retained',
-        };
-    }
+        .get(sourceId, targetRevision);
+    if (!target)
+        return { results: [], removed: [], valid: false };
     const selected = ctx.store.db
         .prepare(`SELECT * FROM retain_supports
        WHERE receipt_fingerprint = ? AND retracted_by IS NULL AND forgotten_by IS NULL
        ORDER BY candidate_id`)
         .all(target.receipt_fingerprint);
-    const wanted = source.retention.candidate_ids
-        ? new Set(source.retention.candidate_ids)
-        : new Set(selected.map((row) => row.candidate_id));
-    const stages = new Map();
+    const wanted = candidateIds ?? selected.map((row) => row.candidate_id);
     const results = [];
     const removed = [];
     for (const candidateId of wanted) {
@@ -513,6 +795,46 @@ async function retractSource(ctx, source, dryRun) {
             slug: support.slug,
         });
     }
+    return {
+        results,
+        removed,
+        valid: results.length === wanted.length && results.every((result) => result.outcome === 'retracted'),
+    };
+}
+async function retractSource(ctx, source, dryRun) {
+    const sourceHash = sha256('retraction');
+    const requestHash = sha256(JSON.stringify(source));
+    const replay = replayResult(ctx, source.source_id, source.revision, requestHash, sourceHash);
+    if (replay)
+        return replay;
+    const targetExists = ctx.store.db
+        .prepare('SELECT 1 FROM retain_receipts WHERE source_id = ? AND revision = ?')
+        .get(source.source_id, source.retention.target_revision);
+    if (!targetExists) {
+        return {
+            source_id: source.source_id,
+            revision: source.revision,
+            outcome: 'held',
+            reason_code: 'source_unavailable',
+            candidates: [],
+            note: 'target_revision was not retained',
+        };
+    }
+    const stages = new Map();
+    const staged = await stageRetractions(ctx, source.source_id, source.retention.target_revision, source.retention.candidate_ids, stages);
+    const results = staged.results;
+    const removed = staged.removed;
+    if (!staged.valid) {
+        return {
+            source_id: source.source_id,
+            revision: source.revision,
+            outcome: 'held',
+            status: 'ok',
+            reason_code: 'conflict',
+            candidates: results,
+            note: 'one or more retraction targets no longer match owned memory; nothing was changed',
+        };
+    }
     const changed = [...stages.values()].filter((stage) => stage.before !== stage.after);
     const preview = {
         source_id: source.source_id,
@@ -758,7 +1080,7 @@ async function pageStage(ctx, stages, slug, subject) {
     if (!row && (await fsp.stat(absolute).catch(() => null))) {
         return { issue: 'unindexed_page_exists' };
     }
-    const title = safeTitle(subject) || slugTitle(slug);
+    const title = managedPageTitle(subject, slug);
     const stage = {
         slug,
         relPath,
@@ -768,6 +1090,80 @@ async function pageStage(ctx, stages, slug, subject) {
     stages.set(slug, stage);
     return stage;
 }
+async function preservedSourceStage(ctx, stages, slug, input) {
+    if (!('text' in input || 'items' in input)) {
+        return { issue: 'only inline source input can be preserved', reasonCode: 'validation_failed' };
+    }
+    if (isReserved(slug, ctx.config)) {
+        return { issue: 'preserved source destination is reserved', reasonCode: 'no_writable_destination' };
+    }
+    const content = serializePreservedSource(slug, input);
+    const row = ctx.store.db
+        .prepare('SELECT rel_path, role, remember_management FROM pages WHERE slug = ?')
+        .get(slug);
+    if (row && (row.role !== 'source' || row.remember_management !== 'deny')) {
+        return {
+            issue: 'preserved source destination must be source + remember: deny',
+            reasonCode: 'no_writable_destination',
+        };
+    }
+    const relPath = row?.rel_path ?? `${slug}.md`;
+    const absolute = path.join(ctx.config.aknoPath, relPath);
+    if (row) {
+        const before = await fsp.readFile(absolute, 'utf8').catch(() => null);
+        if (before === null) {
+            return { issue: 'preserved source destination is unreadable', reasonCode: 'source_unavailable' };
+        }
+        if (before !== content) {
+            return {
+                issue: 'preserved source destination already contains different bytes',
+                reasonCode: 'conflict',
+            };
+        }
+        const stage = { slug, relPath, before, after: before };
+        stages.set(slug, stage);
+        return stage;
+    }
+    if (await fsp.stat(absolute).catch(() => null)) {
+        return { issue: 'an unindexed page exists at the preserved source destination', reasonCode: 'conflict' };
+    }
+    const policy = effectiveRule(slug, ctx.config.rules);
+    const roleRule = declaringRule(slug, ctx.config.rules, 'role');
+    const rememberRule = declaringRule(slug, ctx.config.rules, 'remember');
+    if (policy.role !== 'source' || policy.remember !== 'deny' || !roleRule || !rememberRule) {
+        return {
+            issue: 'preserved source folder must explicitly declare role: source and remember: deny',
+            reasonCode: 'no_writable_destination',
+        };
+    }
+    const gate = ctx.gate.check(slug, ctx.actor);
+    if (!gate.allowed) {
+        return {
+            issue: `preserved source folder is not declared: ${gate.requiresFolder.folder}`,
+            reasonCode: 'no_writable_destination',
+        };
+    }
+    const stage = { slug, relPath, before: null, after: content };
+    stages.set(slug, stage);
+    return stage;
+}
+function serializePreservedSource(slug, input) {
+    const title = slugTitle(slug);
+    const body = 'text' in input
+        ? input.text
+        : input.items
+            .map((item) => {
+            const attributes = [
+                `id=${encodeURIComponent(item.item_id)}`,
+                ...(item.role ? [`role=${item.role}`] : []),
+                ...(item.speaker ? [`speaker=${encodeURIComponent(item.speaker)}`] : []),
+                ...(item.mentioned_at ? [`mentioned-at=${encodeURIComponent(item.mentioned_at)}`] : []),
+            ];
+            return `<!-- akno:source-item ${attributes.join(' ')} -->\n${item.text}`;
+        })
+            .join('\n\n');
+    return `---\ntitle: ${serializeYamlString(title, 'title')}\nakno:\n  role: source\n  management:\n    remember: deny\n---\n\n# ${title}\n\n## Source\n\n${body}\n`;
+}
 async function existingPageStage(ctx, stages, slug) {
     const cached = stages.get(slug);
     if (cached)
@@ -833,7 +1229,7 @@ function removeBlock(content, markerIndex, payloadIndex) {
     lines.splice(markerIndex, payloadIndex - markerIndex + 1);
     return prefix + lines.join('\n').replace(/\n{3,}/g, '\n\n');
 }
-async function commitStages(ctx, stages, summary) {
+async function commitStages(ctx, stages, summary, op = 'retain') {
     if (stages.length === 0)
         return null;
     const files = [];
@@ -841,7 +1237,7 @@ async function commitStages(ctx, stages, summary) {
         for (const stage of stages) {
             files.push(fileEntry(await writeFileAtomic(ctx.config.aknoPath, stage.relPath, stage.after)));
         }
-        const changeId = ctx.journal.record({ actor: ctx.actor, op: 'retain', summary, files });
+        const changeId = ctx.journal.record({ actor: ctx.actor, op, summary, files });
         return { changeId, files };
     }
     catch (error) {
@@ -881,10 +1277,11 @@ async function rollbackCommittedStages(ctx, committed, cause) {
 }
 async function reindexStages(ctx, stages) {
     if (stages.length === 0)
-        return;
+        return 0;
     const paths = stages.map((stage) => stage.relPath);
-    await ctx.indexer.runForeground({ only: paths, modelPaths: [] });
+    const report = await ctx.indexer.runForeground({ only: paths, modelPaths: [] });
     ctx.derive.schedule(paths);
+    return report.factsDerived;
 }
 function persistReceipt(ctx, input) {
     const now = new Date().toISOString();
@@ -908,11 +1305,21 @@ function persistReceipt(ctx, input) {
         for (const support of input.retracted) {
             retract.run(input.receiptFingerprint, support.receipt_fingerprint, support.candidate_id);
         }
+        if (input.binding) {
+            ctx.store.db
+                .prepare(`INSERT INTO retain_source_bindings(
+             receipt_fingerprint, input_kind, input_ref, preserved_slug,
+             availability, reextractable, created_at
+           ) VALUES (?, ?, ?, ?, ?, ?, ?)`)
+                .run(input.receiptFingerprint, input.binding.kind, input.binding.reference ?? null, input.binding.preservedSlug ?? null, input.binding.availability, input.binding.reextractable ? 1 : 0, now);
+        }
     });
     reconcileRetainManagedSources(ctx, [
         ...input.supports.map((support) => support.memory_id),
         ...input.retracted.map((support) => support.memory_id),
     ]);
+    if (input.retracted.length > 0)
+        pruneRetainEvidence(ctx, { apply: true });
 }
 function sourceEvidence(candidate) {
     return candidate.discourse_frame.map((span) => span.quote).join('\n…\n');
@@ -975,6 +1382,17 @@ function slugTitle(slug) {
     const name = slug.slice(slug.lastIndexOf('/') + 1).replaceAll('-', ' ');
     return name.replace(/\b\w/g, (letter) => letter.toUpperCase());
 }
+function managedPageTitle(subject, slug) {
+    const cleaned = safeTitle(subject);
+    if (!cleaned)
+        return titleFromSlug(slug);
+    const named = contentWords(slug.slice(slug.lastIndexOf('/') + 1));
+    for (const word of contentWords(cleaned)) {
+        if (named.has(word))
+            return cleaned.charAt(0).toUpperCase() + cleaned.slice(1);
+    }
+    return titleFromSlug(slug);
+}
 function safeTitle(value) {
     return value
         .replaceAll('\r', ' ')