@tenphi/akno-core 0.1.0

package/dist/maintenance/dream.js

@@ -0,0 +1,1632 @@
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { AknoError } from '@tenphi/akno-protocol';
+import { normalizeSlug } from "../ops/write.js";
+import { sha256 } from "../store/ids.js";
+import { rebuildEvidenceGraph } from "../index/graph.js";
+import { runObserveMission } from "./observe.js";
+import { planBrokenLinks } from "./link-repairs.js";
+import { claimKey, findCrossPageConflicts, ineligibleConflictClaims, verifyConflicts, } from "./conflicts.js";
+import { planContradictions } from "./contradictions.js";
+import { housekeeping } from "./housekeeping.js";
+import { ModelClient } from "../models/client.js";
+import { planOrphanAdoptions } from "./adopt.js";
+import { addedLines, logDreamRun } from "./log.js";
+import { curatePages } from "./curate.js";
+import { addSemanticMergeDiscoveryMetrics, } from "./semantic-merge-discovery.js";
+import { applyMaintenancePlan, blockMaintenanceDependencies, createAdoptionPlan, createCurationPlan, createObservationPlan, createReflectionPlan, decideMaintenancePlanWithCurator, estimateAuditAutoCuratorWork, deferUnmetMaintenanceDependency, deferStaleMaintenanceItems, finalizeRetryableMaintenancePlans, findActiveMaintenancePlan, getMaintenancePlan, maintenanceItemApplySchedule, pruneMaintenancePlans, supersedeDependencyMaintenancePlan, } from "./plans.js";
+import { beginDreamRun, completeDreamRun, dreamRunFileManifest, dreamRunIndexRevisionMatches, failDreamRun, refreshDreamRunSnapshot, } from "./runs.js";
+import { assertMaintenanceModeAllowed, effectiveTransformPolicy, highestPolicyMode, policyMode, profileMode, } from "./profile.js";
+import { createMaintenanceBudget, maintenanceBudgetReceipt, } from "./budget.js";
+import { DreamModelTelemetry, } from "./model-telemetry.js";
+import { verifyDreamRun } from "./run-verification.js";
+import { Indexer } from "../index/indexer.js";
+import { planManagedItems } from "./managed-items.js";
+import { planRuleDrifts, ruleDriftPaths } from "./rule-drift.js";
+import { assertProfileAutomaticApplyAvailable, configWithMaintenanceRecovery, maintenanceRecoveryStatus, recordMaintenanceRecovery, } from "./recovery.js";
+/**
+ * Order matters twice.
+ *
+ * `conflicts` runs first because unresolved knowledge must be filtered before observation,
+ * reflection, or synthesis sees it. The retention ladder remains a user-facing hierarchy, not
+ * permission for a disputed claim to influence a higher tier before inspection.
+ *
+ * `housekeeping` runs last, so its report describes the knowledge base after plan-backed curation and
+ * adoption. Broken-link planning queries the complete structural index directly; it never consumes the
+ * housekeeping list, which is capped for readability.
+ */
+export const DREAM_PHASES = [
+    'conflicts',
+    'observe',
+    'reflect',
+    'curate',
+    'adopt',
+    'repair',
+    'housekeeping',
+];
+const CURATE_POLICY_KINDS = [
+    'hygiene',
+    'managed_item',
+    'synthesis',
+    'split',
+    'extract',
+    'merge',
+    'contradiction',
+    'broken_link',
+    'rule_drift',
+];
+export async function dream(ctx, options = {}) {
+    if (options.mode && options.dryRun) {
+        throw new AknoError('invalid', 'choose `mode: audit` instead of combining a mode with dryRun');
+    }
+    assertMaintenanceModeAllowed(ctx.config, options);
+    const started = performance.now();
+    // The tiers run unattended and are worth a better model than indexing needs — measured:
+    // the same observe pass over one knowledge base produced 15 candidates worth about four with a
+    // local 3B, and 8 candidates with no guard violations at all with a strong one. When
+    // `maintenance.model` is set, the whole cycle uses it and nothing else does.
+    const baseCycleModel = ctx.config.maintenance.model
+        ? new ModelClient(ctx.config.maintenance.model)
+        : ctx.models.derive;
+    const telemetry = new DreamModelTelemetry(baseCycleModel.modelId);
+    let modelStage = options.phase ?? 'conflicts';
+    const pendingDerivation = new QueuedDeriveScheduler();
+    const runMode = dreamRunMode(ctx, options);
+    const recovery = maintenanceRecoveryStatus(ctx);
+    const cycle = {
+        ...ctx,
+        config: configWithMaintenanceRecovery(ctx.config, recovery, runMode),
+        models: {
+            ...ctx.models,
+            derive: baseCycleModel.withOutcomeObserver((observation) => telemetry.observe(modelStage, observation)),
+        },
+        // A maintenance write still indexes structure before it is verified. Hold its expensive
+        // follow-up until every planned write has landed, so changed facts can be re-derived and
+        // reclassified once, synchronously, before this run certifies its outcome.
+        derive: pendingDerivation,
+    };
+    const wanted = options.phase ? [options.phase] : DREAM_PHASES;
+    const startedRun = beginDreamRun(cycle, {
+        requestedPhase: options.phase ?? null,
+        requestedPhases: wanted,
+        mode: runMode,
+        dryRun: options.dryRun ?? false,
+        modelId: cycle.models.derive.modelId,
+    });
+    const report = {
+        run: startedRun,
+        phases: [],
+        observations: [],
+        curated: [],
+        managedItems: {
+            eligiblePages: 0,
+            inspectedMarkers: 0,
+            plannedPages: 0,
+            suppressedPages: 0,
+            findings: {
+                empty_marker: 0,
+                malformed_marker: 0,
+                duplicate_item: 0,
+                misplaced_item: 0,
+                placement_uncertain: 0,
+                placement_unavailable: 0,
+                section_created: 0,
+                misrouted_item: 0,
+                routing_deferred: 0,
+                routing_uncertain: 0,
+                routing_unavailable: 0,
+                wording_corrected: 0,
+                wording_uncertain: 0,
+                source_unavailable: 0,
+                item_conflict: 0,
+                valid: 0,
+            },
+            outcomes: { planned: 0, held: 0, valid: 0, suppressed: 0 },
+            placement: {
+                pagesConsidered: 0,
+                classifierCalls: 0,
+                cacheHits: 0,
+                kept: 0,
+                moved: 0,
+                sectionsCreated: 0,
+                uncertain: 0,
+                unavailable: 0,
+            },
+            routing: {
+                pagesConsidered: 0,
+                itemsConsidered: 0,
+                candidatesConsidered: 0,
+                classifierCalls: 0,
+                cacheHits: 0,
+                kept: 0,
+                moved: 0,
+                sectionsCreated: 0,
+                deferred: 0,
+                uncertain: 0,
+                unavailable: 0,
+            },
+            source: {
+                pagesConsidered: 0,
+                classifierCalls: 0,
+                cacheHits: 0,
+                supported: 0,
+                corrected: 0,
+                uncertain: 0,
+                unavailable: 0,
+            },
+            details: [],
+        },
+        rejected: [],
+        adopted: [],
+        conflicts: [],
+        repaired: null,
+        repairChangeId: null,
+        housekeeping: null,
+        changeId: null,
+        adoptChangeId: null,
+        curateChangeId: null,
+        maintenancePlan: null,
+        maintenancePlans: [],
+        planPrune: null,
+        budget: maintenanceBudgetReceipt(createMaintenanceBudget(ctx.config.maintenance.limits)),
+        modelUsage: telemetry.usage(),
+        degraded: telemetry.degradation(),
+        semanticMerge: null,
+        verification: null,
+        conflictRefresh: null,
+        autoEstimate: null,
+        warnings: [],
+        durationMs: 0,
+    };
+    for (const entry of recovery.transforms.filter((candidate) => candidate.pausedAt !== null)) {
+        report.warnings.push(`automatic ${entry.transform} maintenance is paused after ${entry.consecutiveFailures} consecutive verification rollbacks; resume it explicitly after inspection`);
+    }
+    // Collected whether or not anything reads it, because the phases are where the information
+    // is and threading it out conditionally is how a debugging flag ends up logging half a run.
+    const applied = [];
+    const budget = createMaintenanceBudget(ctx.config.maintenance.limits);
+    const deferAutomaticApply = !options.phase && !options.dryRun;
+    const lastWritablePlanner = Math.max(...['observe', 'reflect', 'curate', 'adopt'].map((phase) => wanted.lastIndexOf(phase)));
+    let plannerBarrier = null;
+    const releasePlannerBarrier = async () => {
+        if (!plannerBarrier)
+            return;
+        const barrier = plannerBarrier;
+        let revisionMatches = false;
+        let invalidated = false;
+        try {
+            revisionMatches = dreamRunIndexRevisionMatches(ctx, startedRun);
+        }
+        finally {
+            plannerBarrier = null;
+            invalidated = (await barrier.release()).invalidated;
+        }
+        if (invalidated) {
+            // A foreground mutation has already won and structurally indexed. Recheck the exact
+            // sealed inputs so affected proposals become typed stale work; unrelated proposals may be
+            // reused by a fresh run, but this mixed-revision invocation never reaches a curator.
+            await deferStaleMaintenanceItems(cycle, report.maintenancePlans.map((plan) => plan.id));
+            throw new AknoError('conflict', 'a foreground memory write changed the indexed revision during dream planning; nothing was applied', { retryable: true });
+        }
+        if (!revisionMatches) {
+            throw new AknoError('internal', 'the indexed revision changed inside the dream planner barrier');
+        }
+    };
+    try {
+        assertProfileAutomaticApplyAvailable(recovery, runMode);
+        if (!options.phase && ctx.writable) {
+            plannerBarrier = await ctx.indexer.acquireRevisionBarrier();
+            // `beginDreamRun` claims exclusivity before waiting for an in-flight index pass. Once the
+            // barrier owns the lane, this becomes the exact revision every full-run planner reads.
+            refreshDreamRunSnapshot(ctx, startedRun);
+        }
+        if (cycle.writable)
+            finalizeRetryableMaintenancePlans(cycle);
+        // A selected inference or curation phase still gets the same safety boundary as a full run.
+        // It does not add a second visible phase to the report; it supplies that phase's prerequisites.
+        if (options.phase &&
+            options.phase !== 'conflicts' &&
+            ['observe', 'reflect', 'curate'].includes(options.phase) &&
+            cycle.config.maintenance.conflicts.enabled) {
+            modelStage = 'conflicts';
+            await inspectConflicts(cycle, report, telemetry);
+        }
+        for (const [phaseIndex, phase] of wanted.entries()) {
+            modelStage = phase;
+            const phaseStarted = performance.now();
+            const skipped = await runPhase(cycle, phase, options, report, applied, budget, deferAutomaticApply, telemetry);
+            report.phases.push({
+                phase,
+                ran: skipped === null,
+                ...(skipped ? { skipped } : {}),
+                durationMs: Math.round(performance.now() - phaseStarted),
+            });
+            if (plannerBarrier?.invalidated)
+                await releasePlannerBarrier();
+            if (deferAutomaticApply && phaseIndex === lastWritablePlanner) {
+                await releasePlannerBarrier();
+                await decideAndApplyPlannedPhases(cycle, report, applied, budget, telemetry);
+                await retryDependencyDeferredPhases(cycle, options, report, applied, budget, telemetry, (stage) => {
+                    modelStage = stage;
+                });
+                modelStage = 'conflicts';
+                report.conflictRefresh = await refreshChangedClaimEligibility(cycle, pendingDerivation, report, telemetry);
+            }
+        }
+        await releasePlannerBarrier();
+        if (!deferAutomaticApply) {
+            modelStage = 'conflicts';
+            report.conflictRefresh = await refreshChangedClaimEligibility(cycle, pendingDerivation, report, telemetry);
+        }
+        report.budget = maintenanceBudgetReceipt(budget);
+        report.modelUsage = telemetry.usage();
+        report.degraded = telemetry.degradation();
+        report.verification = await verifyDreamRun(cycle, report.maintenancePlans.map((plan) => plan.id), budget, report.budget, report.modelUsage, dreamRunFileManifest(startedRun));
+        report.autoEstimate =
+            report.run.mode === 'audit'
+                ? estimateAuditAutoCuratorWork(cycle, report.maintenancePlans.map((plan) => plan.id), { sealedPlans: !report.run.dryRun })
+                : null;
+        report.durationMs = Math.round(performance.now() - started);
+        recordMaintenanceRecovery(cycle, {
+            runId: startedRun.id,
+            mode: runMode,
+            planIds: report.maintenancePlans.map((plan) => plan.id),
+            verification: report.verification,
+        });
+        report.planPrune = pruneMaintenancePlans(cycle, {
+            apply: cycle.writable && !(options.dryRun ?? false),
+        });
+        if (report.planPrune.applied && report.planPrune.payloads.plans > 0) {
+            for (const planned of [...report.maintenancePlans]) {
+                try {
+                    recordMaintenancePlan(report, getMaintenancePlan(cycle, planned.id));
+                }
+                catch (error) {
+                    if (AknoError.from(error).code !== 'not_found')
+                        throw error;
+                    // A zero-day compact receipt window deliberately removes even this run's terminal
+                    // plan. The run receipt still records its id and the pruning receipt explains why.
+                }
+            }
+        }
+        if (ctx.config.maintenance.logChanges) {
+            const logPath = await logDreamRun(ctx, report, applied, { dryRun: options.dryRun ?? false });
+            if (logPath)
+                report.logPath = logPath;
+        }
+        report.run = completeDreamRun(ctx, startedRun, report);
+        // Any non-knowledge work, conflicts-disabled work, or failed derivation resumes through the
+        // ordinary post-response worker only after the run has sealed its observed final state.
+        ctx.derive.schedule(pendingDerivation.take());
+        return report;
+    }
+    catch (error) {
+        try {
+            await releasePlannerBarrier();
+        }
+        catch {
+            // The original failure remains the run error. Releasing the in-process lane is mandatory;
+            // queued index callers keep their own typed outcome and final tree verification did not run.
+        }
+        // A valid write must not lose its ordinary background indexing merely because a later
+        // planner or final verifier failed before the changed-claim barrier could consume it.
+        ctx.derive.schedule(pendingDerivation.take());
+        report.durationMs = Math.round(performance.now() - started);
+        report.budget = maintenanceBudgetReceipt(budget);
+        report.modelUsage = telemetry.usage();
+        report.degraded = telemetry.degradation();
+        report.run = failDreamRun(ctx, startedRun, error, report.durationMs, report.phases, report.budget, report);
+        try {
+            recordMaintenanceRecovery(cycle, {
+                runId: startedRun.id,
+                mode: runMode,
+                planIds: report.maintenancePlans.map((plan) => plan.id),
+                verification: report.verification,
+            });
+        }
+        catch {
+            // Preserve the original lifecycle error. A store that cannot retain recovery state is
+            // already surfaced by that failure and must not replace its more specific cause.
+        }
+        throw error;
+    }
+}
+/** Collect paths without starting the ordinary post-response worker. */
+class QueuedDeriveScheduler {
+    #paths = new Set();
+    schedule(relPaths) {
+        for (const relPath of relPaths)
+            this.#paths.add(relPath);
+    }
+    async flush() {
+        // Deliberately idle: `dream` owns the barrier and drains the queue explicitly.
+    }
+    take() {
+        const paths = [...this.#paths];
+        this.#paths.clear();
+        return paths;
+    }
+}
+/**
+ * Re-derive facts changed by successful maintenance writes and rebuild conflict eligibility.
+ *
+ * Structural indexing deliberately leaves a changed page's previous `derived_hash` in place.
+ * That mismatch is the durable stale marker: until a complete fact derivation succeeds, readers
+ * must exclude the page's old facts rather than treating pre-write claims as current evidence.
+ */
+async function refreshChangedClaimEligibility(ctx, pending, report, telemetry) {
+    const paths = pending.take();
+    const checkedAt = new Date().toISOString();
+    if (paths.length === 0) {
+        return emptyConflictRefresh('no_claim_changes', checkedAt);
+    }
+    const pages = livePagesForPaths(ctx, paths);
+    const knowledge = pages.filter((page) => page.role === 'knowledge');
+    if (knowledge.length === 0) {
+        pending.schedule(paths);
+        return {
+            ...emptyConflictRefresh('no_claim_changes', checkedAt),
+            changedFiles: paths.length,
+        };
+    }
+    if (!ctx.config.maintenance.conflicts.enabled) {
+        pending.schedule(paths);
+        return {
+            ...emptyConflictRefresh('conflicts_disabled', checkedAt),
+            changedFiles: paths.length,
+            knowledgePages: knowledge.length,
+        };
+    }
+    if (!ctx.config.index.facts) {
+        // The structural pass has already rebuilt the graph. With fact mining disabled there is no
+        // changed claim set to derive; summaries may still finish through the ordinary worker.
+        await inspectConflicts(ctx, report, telemetry);
+        pending.schedule(paths);
+        return {
+            status: 'passed',
+            cause: 'facts_disabled',
+            changedFiles: paths.length,
+            knowledgePages: knowledge.length,
+            currentPages: 0,
+            stalePages: 0,
+            candidates: report.conflicts.length,
+            unverified: report.conflicts.filter((conflict) => conflict.verdict === 'unverified').length,
+            checkedAt,
+        };
+    }
+    if (!ctx.models.derive.available) {
+        telemetry.degrade('conflicts', ctx.models.derive.degradedReason({}), 'unavailable');
+    }
+    else {
+        try {
+            const indexer = new Indexer(ctx.config, ctx.store, {
+                embedding: ctx.models.embedding,
+                derive: ctx.models.derive,
+            });
+            await indexer.run({ only: paths, modelPaths: paths, reindexUnchanged: true });
+        }
+        catch (error) {
+            // Preserve the ordinary retry path for infrastructure failures. Semantic model failures
+            // return an index report instead and are represented by the stale hash below.
+            pending.schedule(paths);
+            throw error;
+        }
+    }
+    const refreshed = livePagesForPaths(ctx, paths).filter((page) => page.role === 'knowledge');
+    const current = refreshed.filter((page) => page.derived_hash === page.body_hash);
+    const stale = refreshed.length - current.length;
+    if (stale > 0 && ctx.models.derive.available) {
+        telemetry.degrade('conflicts', 'derive_failed');
+    }
+    if (stale > 0) {
+        pending.schedule(ctx.models.derive.available
+            ? refreshed.filter((page) => page.derived_hash !== page.body_hash).map((page) => page.rel_path)
+            : paths);
+    }
+    // This replaces the pre-write report as well as rebuilding the graph. New claim fingerprints
+    // naturally miss old cached verdicts, while unchanged fingerprints may safely reuse them.
+    await inspectConflicts(ctx, report, telemetry);
+    const unverified = report.conflicts.filter((conflict) => conflict.verdict === 'unverified').length;
+    return {
+        status: stale > 0 || (ctx.config.maintenance.conflicts.verify && unverified > 0) ? 'degraded' : 'passed',
+        cause: null,
+        changedFiles: paths.length,
+        knowledgePages: refreshed.length,
+        currentPages: current.length,
+        stalePages: stale,
+        candidates: report.conflicts.length,
+        unverified,
+        checkedAt,
+    };
+}
+function emptyConflictRefresh(cause, checkedAt) {
+    return {
+        status: 'not_needed',
+        cause,
+        changedFiles: 0,
+        knowledgePages: 0,
+        currentPages: 0,
+        stalePages: 0,
+        candidates: 0,
+        unverified: 0,
+        checkedAt,
+    };
+}
+function livePagesForPaths(ctx, paths) {
+    if (paths.length === 0)
+        return [];
+    return ctx.store.db
+        .prepare(`SELECT rel_path, role, body_hash, derived_hash FROM pages
+        WHERE rel_path IN (${paths.map(() => '?').join(',')})`)
+        .all(...paths);
+}
+function dreamRunMode(ctx, options) {
+    if (options.dryRun)
+        return 'audit';
+    if (options.mode)
+        return options.mode;
+    return profileMode(ctx.config.maintenance.profile);
+}
+function curationPolicies(ctx, options) {
+    return Object.fromEntries(CURATE_POLICY_KINDS.map((kind) => {
+        const effective = effectiveTransformPolicy(ctx.config, kind, options.mode);
+        return [kind, policyMode(effective) ?? 'off'];
+    }));
+}
+function planMatchesPolicies(plan, policies) {
+    return plan.items.every((item) => item.policy === policies[item.kind]);
+}
+async function runPhase(ctx, phase, options, report, applied, budget, deferAutomaticApply, telemetry) {
+    switch (phase) {
+        case 'observe': {
+            if (!ctx.config.maintenance.observe.enabled)
+                return 'disabled in config';
+            if (!policyMode(effectiveTransformPolicy(ctx.config, 'observe', options.mode))) {
+                return 'observe policy is off';
+            }
+            if (!ctx.models.derive.available) {
+                telemetry.degrade('observe', ctx.models.derive.degradedReason({}), 'unavailable');
+                return `no model for the cycle: ${ctx.models.derive.unavailableReason ?? 'unavailable'}`;
+            }
+            await observePhase(ctx, options, report, applied, budget, deferAutomaticApply, telemetry);
+            return null;
+        }
+        case 'reflect': {
+            // Reflect ships as an extension point, off by default. At a few hundred pages a
+            // "pattern" is one coincidence away from noise, so the default is not a placeholder —
+            // it is the recommendation.
+            if (!ctx.config.maintenance.reflect.enabled) {
+                return 'off by default — enable it once the knowledge base has the volume for it';
+            }
+            if (!policyMode(effectiveTransformPolicy(ctx.config, 'reflect', options.mode))) {
+                return 'reflect policy is off';
+            }
+            if (!ctx.models.derive.available) {
+                telemetry.degrade('reflect', ctx.models.derive.degradedReason({}), 'unavailable');
+                return `no model for the cycle: ${ctx.models.derive.unavailableReason ?? 'unavailable'}`;
+            }
+            await reflectPhase(ctx, options, report, applied, budget, deferAutomaticApply, telemetry);
+            return null;
+        }
+        case 'curate': {
+            const policyMatrix = !options.dryRun;
+            const policies = curationPolicies(ctx, options);
+            const managedItemResult = policies.managed_item === 'off'
+                ? { drafts: [], report: report.managedItems }
+                : await planManagedItems(ctx, {
+                    conflictClaims: ineligibleConflictClaims(report.conflicts),
+                });
+            report.managedItems = managedItemResult.report;
+            if (managedItemResult.report.outcomes.held > 0) {
+                report.warnings.push(`${managedItemResult.report.outcomes.held} managed-item finding${managedItemResult.report.outcomes.held === 1 ? '' : 's'} require${managedItemResult.report.outcomes.held === 1 ? 's' : ''} inspection; surrounding page bytes were not changed`);
+            }
+            const allowedKinds = new Set(['hygiene', 'synthesis', 'split', 'extract', 'merge'].filter((kind) => policies[kind] !== 'off'));
+            // A configured mode is how a full scheduled run gets plan-backed curation without
+            // turning the scheduler into a curate-only command. An explicit dry run keeps its
+            // existing read-only path; creating a durable plan needs the service's write handle.
+            const mode = policyMatrix ? highestPolicyMode(Object.values(policies)) : null;
+            if (policyMatrix && !mode)
+                return 'all curation policies are off';
+            if (!ctx.models.derive.available && !mode) {
+                telemetry.degrade('curate', ctx.models.derive.degradedReason({}), 'unavailable');
+                return `no model for the cycle: ${ctx.models.derive.unavailableReason ?? 'unavailable'}`;
+            }
+            if (mode) {
+                // Reuse every unfinished plan, not only autonomous ones. Re-running audit or review must
+                // not spend another model call to rediscover a decision already waiting in the queue.
+                let plan = findActiveMaintenancePlan(ctx, mode, 'curate');
+                if (plan && policyMatrix && !planMatchesPolicies(plan, policies))
+                    plan = null;
+                if (plan) {
+                    report.curated = plan.items.filter(isGeneralCurationItem).map((item) => ({
+                        slug: item.subject,
+                        mode: item.kind === 'hygiene' ? 'hygiene' : 'synthesize',
+                        action: 'would-update',
+                        splits: item.kind === 'split'
+                            ? item.operations
+                                .filter((operation) => operation.type === 'create')
+                                .map((operation) => operation.relPath.replace(/\\/g, '/').replace(/\.(md|markdown)$/i, ''))
+                            : [],
+                        extractions: item.kind === 'extract'
+                            ? item.operations
+                                .filter((operation) => operation.type === 'create')
+                                .map((operation) => operation.relPath.replace(/\\/g, '/').replace(/\.(md|markdown)$/i, ''))
+                            : [],
+                        merges: item.kind === 'merge'
+                            ? item.operations
+                                .filter((operation) => operation.type === 'delete')
+                                .map((operation) => operation.relPath.replace(/\\/g, '/').replace(/\.(md|markdown)$/i, ''))
+                            : [],
+                        issues: [],
+                    }));
+                    report.repaired = repairResultFromPlan(plan);
+                }
+                else {
+                    if (!ctx.models.derive.available) {
+                        telemetry.degrade('curate', ctx.models.derive.degradedReason({}), 'unavailable');
+                    }
+                    const contradictionResult = ctx.config.maintenance.conflicts.resolve && (!policyMatrix || policies.contradiction !== 'off')
+                        ? await planContradictions(ctx, report.conflicts)
+                        : { drafts: [], warnings: [] };
+                    report.warnings.push(...contradictionResult.warnings);
+                    const managedPaths = new Set(managedItemResult.drafts.map((draft) => draft.relPath));
+                    const contradictionDrafts = contradictionResult.drafts.filter((draft) => draft.operations.every((operation) => !managedPaths.has(operation.relPath)));
+                    if (contradictionDrafts.length !== contradictionResult.drafts.length) {
+                        report.warnings.push(`${contradictionResult.drafts.length - contradictionDrafts.length} contradiction repair${contradictionResult.drafts.length - contradictionDrafts.length === 1 ? '' : 's'} deferred behind an owned managed-item repair`);
+                    }
+                    const linkResult = ctx.config.maintenance.repair.links && (!policyMatrix || policies.broken_link !== 'off')
+                        ? await planBrokenLinks(ctx, ctx.config.maintenance.repair.maxChanges)
+                        : { drafts: [], report: { links: [], claims: [], declined: [] } };
+                    report.repaired = linkResult.report;
+                    const ruleDriftDrafts = !policyMatrix || policies.rule_drift !== 'off'
+                        ? await planRuleDrifts(ctx, { limit: ctx.config.maintenance.curate.maxRuleDrifts })
+                        : [];
+                    const result = ctx.models.derive.available
+                        ? await curatePages(ctx, {
+                            dryRun: true,
+                            // Planning may update derived curation fingerprints even though it cannot touch KB
+                            // bytes. Persisting unchanged and guard-rejected inputs is what makes the next cycle
+                            // converge; staged pages remain `preview` until their durable item is decided.
+                            recordState: true,
+                            includePreviewed: true,
+                            ...(policyMatrix ? { allowedKinds } : {}),
+                        })
+                        : {
+                            pages: [],
+                            drafts: [],
+                            degraded: [],
+                            semanticMerge: null,
+                            warnings: [
+                                `page transformations were skipped because no maintenance model is available: ${ctx.models.derive.unavailableReason ?? 'unavailable'}`,
+                            ],
+                        };
+                    report.curated = result.pages;
+                    report.warnings.push(...result.warnings);
+                    report.semanticMerge = addSemanticMergeDiscoveryMetrics(report.semanticMerge, result.semanticMerge);
+                    for (const degradation of result.degraded) {
+                        telemetry.degrade('curate', degradation.reason, degradation.failure);
+                    }
+                    // A contradiction item has priority over a general synthesis of the same page. Two
+                    // sealed items replacing one input would make the second stale by construction.
+                    const contradictionPaths = new Set(contradictionDrafts.flatMap((draft) => draft.operations.map((operation) => operation.relPath)));
+                    const linkDrafts = [];
+                    const linkMutations = new Set([...managedPaths, ...contradictionPaths]);
+                    const linkSeals = new Set();
+                    for (const draft of linkResult.drafts) {
+                        const mutations = draft.operations.map((operation) => operation.relPath);
+                        const seals = draft.targets.map((target) => target.relPath);
+                        const overlaps = mutations.some((relPath) => linkMutations.has(relPath) || linkSeals.has(relPath)) ||
+                            seals.some((relPath) => linkMutations.has(relPath));
+                        if (overlaps)
+                            continue;
+                        linkDrafts.push(draft);
+                        for (const relPath of mutations)
+                            linkMutations.add(relPath);
+                        for (const relPath of seals)
+                            linkSeals.add(relPath);
+                    }
+                    for (const draft of linkResult.drafts.filter((candidate) => !linkDrafts.includes(candidate))) {
+                        for (const repair of draft.repairs) {
+                            report.repaired.links = report.repaired.links.filter((entry) => entry !== repair);
+                            report.repaired.declined.push({
+                                what: `[[${repair.brokenTarget}]]`,
+                                reason: 'deferred until an overlapping maintenance item settles',
+                            });
+                        }
+                    }
+                    const occupiedRuleDriftPaths = new Set([...linkMutations, ...linkSeals]);
+                    const selectedRuleDrifts = [];
+                    for (const draft of ruleDriftDrafts) {
+                        const paths = ruleDriftPaths(draft);
+                        if (paths.some((relPath) => occupiedRuleDriftPaths.has(relPath)))
+                            continue;
+                        selectedRuleDrifts.push(draft);
+                        for (const relPath of paths)
+                            occupiedRuleDriftPaths.add(relPath);
+                    }
+                    const protectedPaths = new Set([
+                        ...managedPaths,
+                        ...contradictionPaths,
+                        ...linkDrafts.flatMap(linkDraftPaths),
+                        ...selectedRuleDrifts.flatMap(ruleDriftPaths),
+                    ]);
+                    const curationDrafts = result.drafts.filter((draft) => !operationsTouchedByCurateDraft(draft).some((relPath) => protectedPaths.has(relPath)));
+                    const deferredSlugs = new Set(result.drafts.filter((draft) => !curationDrafts.includes(draft)).map((draft) => draft.slug));
+                    report.curated = report.curated.map((page) => deferredSlugs.has(page.slug)
+                        ? {
+                            ...page,
+                            action: 'rejected',
+                            issues: ['general synthesis deferred until a higher-priority bounded item settles'],
+                        }
+                        : page);
+                    plan = createCurationPlan(ctx, mode, curationDrafts, contradictionDrafts, linkDrafts, managedItemResult.drafts, selectedRuleDrifts, policies);
+                }
+                if (!plan)
+                    return null;
+                if (mode === 'auto' && !deferAutomaticApply) {
+                    if (plan.items.some((item) => item.status === 'proposed' && item.policy === 'auto')) {
+                        plan = await decideDreamPlanWithCurator(ctx, plan.id, telemetry);
+                    }
+                    if (plan.items.some((item) => ['approved', 'applying', 'verification_pending'].includes(item.status))) {
+                        const appliedResult = await applyMaintenancePlan(ctx, plan.id, budget);
+                        plan = appliedResult.plan;
+                        applied.push(...appliedResult.files.map((file) => asApplied('curate', file)));
+                    }
+                }
+                report.curated = curationReportFromPlan(report.curated, plan);
+                report.repaired = repairResultFromPlan(plan, report.repaired?.declined ?? []);
+                recordMaintenancePlan(report, plan);
+                return null;
+            }
+            const result = await curatePages(ctx, { dryRun: true, recordState: false, allowedKinds });
+            report.curated = result.pages;
+            report.curateChangeId = result.changeId;
+            report.warnings.push(...result.warnings);
+            report.semanticMerge = addSemanticMergeDiscoveryMetrics(report.semanticMerge, result.semanticMerge);
+            for (const degradation of result.degraded) {
+                telemetry.degrade('curate', degradation.reason, degradation.failure);
+            }
+            applied.push(...result.files.map((file) => asApplied('curate', file)));
+            return null;
+        }
+        case 'adopt': {
+            const adoptPolicy = policyMode(effectiveTransformPolicy(ctx.config, 'adopt', options.mode));
+            if (!adoptPolicy)
+                return 'adopt policy is off';
+            const result = await planOrphanAdoptions(ctx, {
+                limit: ctx.config.maintenance.adopt.maxPages,
+            });
+            report.adopted = result.adopted;
+            if (options.dryRun)
+                return null;
+            const mode = adoptPolicy;
+            let plan = findActiveMaintenancePlan(ctx, mode, 'adopt');
+            if (plan && !planMatchesPolicies(plan, { adopt: adoptPolicy }))
+                plan = null;
+            if (!plan && result.drafts.length > 0) {
+                plan = createAdoptionPlan(ctx, mode, result.drafts, report.run.snapshot, adoptPolicy);
+            }
+            if (!plan)
+                return null;
+            for (const item of plan.items.filter((candidate) => candidate.kind === 'adopt')) {
+                if (report.adopted.some((entry) => entry.slug === item.subject))
+                    continue;
+                report.adopted.push({
+                    slug: item.subject,
+                    files: item.evidence.flatMap((entry) => entry.type === 'document' && entry.documentRelPath ? [entry.documentRelPath] : []),
+                    action: 'planned',
+                });
+            }
+            if (mode === 'auto' && !deferAutomaticApply) {
+                if (plan.items.some((item) => item.status === 'proposed' && item.policy === 'auto')) {
+                    plan = await decideDreamPlanWithCurator(ctx, plan.id, telemetry);
+                }
+                if (plan.items.some((item) => ['approved', 'applying', 'verification_pending'].includes(item.status))) {
+                    const appliedResult = await applyMaintenancePlan(ctx, plan.id, budget);
+                    plan = appliedResult.plan;
+                    applied.push(...appliedResult.files.map((file) => asApplied('adopt', file)));
+                }
+            }
+            report.adopted = adoptionReportFromPlan(report.adopted, plan);
+            const adoptionChanges = plan.items
+                .map((item) => item.changeId)
+                .filter((id) => id !== null);
+            // Compatibility for callers that adopted one orphan before adoption gained per-item plans.
+            report.adoptChangeId = adoptionChanges.length === 1 ? adoptionChanges[0] : null;
+            recordMaintenancePlan(report, plan);
+            return null;
+        }
+        case 'conflicts': {
+            if (!ctx.config.maintenance.conflicts.enabled)
+                return 'disabled in config';
+            await inspectConflicts(ctx, report, telemetry);
+            return null;
+        }
+        case 'repair': {
+            if (!ctx.config.maintenance.repair.enabled)
+                return 'disabled in config';
+            return repairPhase(ctx, report);
+        }
+        case 'housekeeping': {
+            report.housekeeping = await housekeeping(ctx);
+            return null;
+        }
+    }
+}
+async function inspectConflicts(ctx, report, telemetry) {
+    const candidates = findCrossPageConflicts(ctx, ctx.config.maintenance.conflicts.maxPairs);
+    if (!ctx.config.maintenance.conflicts.verify) {
+        report.conflicts = candidates;
+        return;
+    }
+    if (candidates.length > 0 && !ctx.models.derive.available) {
+        telemetry.degrade('conflicts', ctx.models.derive.degradedReason({}), 'unavailable');
+    }
+    const verified = await verifyConflicts(ctx, candidates);
+    report.conflicts = verified.conflicts;
+    report.warnings.push(...verified.warnings);
+    // Conflict verdicts are content-addressed graph eligibility. Refresh immediately after
+    // caching them so an audit-only cycle does not leave relationship edges one night behind.
+    if (ctx.writable) {
+        rebuildEvidenceGraph(ctx.store, {
+            conflictModelId: ctx.models.derive.modelId,
+            contextualModelId: ctx.config.graph.contextualResolution.enabled ? ctx.models.derive.modelId : null,
+        });
+    }
+}
+function operationsTouchedByCurateDraft(draft) {
+    return [
+        draft.relPath,
+        ...draft.children.map((child) => child.relPath),
+        ...draft.extractions.map((extraction) => extraction.relPath),
+        ...(draft.merge?.linkUpdates.map((update) => update.relPath) ?? []),
+        ...(draft.merge ? [draft.merge.sourceRelPath] : []),
+    ];
+}
+function linkDraftPaths(draft) {
+    return [
+        ...draft.operations.map((operation) => operation.relPath),
+        ...draft.targets.map((target) => target.relPath),
+    ];
+}
+function isGeneralCurationItem(item) {
+    return (item.kind !== 'observe' &&
+        item.kind !== 'reflect' &&
+        item.kind !== 'contradiction' &&
+        item.kind !== 'managed_item' &&
+        item.kind !== 'broken_link' &&
+        item.kind !== 'rule_drift' &&
+        item.kind !== 'adopt');
+}
+function repairResultFromPlan(plan, declined = []) {
+    const links = plan.items.flatMap((item) => {
+        if (item.kind !== 'broken_link')
+            return [];
+        const action = item.status === 'applied'
+            ? 'applied'
+            : ['rejected', 'blocked', 'stale', 'verification_failed'].includes(item.status)
+                ? 'rejected'
+                : 'planned';
+        return item.evidence.flatMap((entry) => entry.type === 'link' && entry.brokenTarget && entry.newTarget && entry.signal
+            ? [
+                {
+                    from: entry.source,
+                    brokenTarget: entry.brokenTarget,
+                    newTarget: entry.newTarget,
+                    signal: entry.signal,
+                    action,
+                },
+            ]
+            : []);
+    });
+    return { links, claims: [], declined };
+}
+function maintenancePlanForReport(plan) {
+    const { items, ...summary } = plan;
+    return {
+        ...summary,
+        items: items.map((item) => ({
+            id: item.id,
+            kind: item.kind,
+            policy: item.policy,
+            risk: item.risk,
+            componentCount: item.componentCount,
+            subject: item.subject,
+            status: item.status,
+            statusCode: item.statusCode,
+            decision: item.decision,
+            statusReason: item.statusReason,
+            changeId: item.changeId,
+            verification: item.verification,
+        })),
+    };
+}
+function recordMaintenancePlan(report, plan) {
+    const summary = maintenancePlanForReport(plan);
+    const existing = report.maintenancePlans.findIndex((candidate) => candidate.id === plan.id);
+    if (existing === -1)
+        report.maintenancePlans.push(summary);
+    else
+        report.maintenancePlans[existing] = summary;
+    // Kept for older clients and single-phase callers. Multi-phase clients should use the array.
+    report.maintenancePlan = summary;
+}
+/**
+ * A full policy-backed cycle reaches this barrier only after every writable planner has sealed
+ * its current phase plan. Curator calls and knowledge-base writes therefore cannot influence a
+ * later planner in the same invocation. Single-phase commands deliberately keep their immediate
+ * decide/apply behavior.
+ */
+async function decideDreamPlanWithCurator(ctx, planId, telemetry) {
+    const curatorContext = {
+        ...ctx,
+        models: {
+            ...ctx.models,
+            derive: ctx.models.derive.withOutcomeObserver((observation) => telemetry.observe('curator', observation)),
+        },
+    };
+    return decideMaintenancePlanWithCurator(curatorContext, planId);
+}
+async function decideAndApplyPlannedPhases(ctx, report, applied, budget, telemetry) {
+    const planIds = report.maintenancePlans.map((plan) => plan.id);
+    const pagePaths = new Map(ctx.store.db.prepare('SELECT slug, rel_path FROM pages').all().map((row) => [row.slug, row.rel_path]));
+    const schedule = maintenanceItemApplySchedule(planIds.map((planId) => getMaintenancePlan(ctx, planId)), pagePaths);
+    await deferStaleMaintenanceItems(ctx, planIds);
+    blockMaintenanceDependencies(ctx, planIds);
+    // Decide every sealed item before applying any of them. A target creator may move ahead of an
+    // earlier-phase referencer, but its bytes must never influence that referencer's curator prompt.
+    for (const planId of planIds) {
+        let plan = getMaintenancePlan(ctx, planId);
+        if (plan.mode === 'auto') {
+            if (plan.items.some((item) => item.status === 'proposed' && item.policy === 'auto')) {
+                plan = await decideDreamPlanWithCurator(ctx, plan.id, telemetry);
+            }
+        }
+    }
+    for (const step of schedule) {
+        let plan = getMaintenancePlan(ctx, step.planId);
+        const item = plan.items.find((candidate) => candidate.id === step.itemId);
+        if (!item || !['approved', 'applying', 'verification_pending'].includes(item.status))
+            continue;
+        const prerequisiteMissing = step.dependsOn.some((dependency) => {
+            const prerequisite = getMaintenancePlan(ctx, dependency.planId).items.find((candidate) => candidate.id === dependency.itemId);
+            return prerequisite?.status !== 'applied';
+        });
+        if (prerequisiteMissing) {
+            deferUnmetMaintenanceDependency(ctx, plan.id, item.id);
+            continue;
+        }
+        const result = await applyMaintenancePlan(ctx, plan.id, budget, {
+            onlyItemIds: new Set([item.id]),
+        });
+        plan = result.plan;
+        applied.push(...result.files.map((file) => asApplied(plan.phase, file)));
+    }
+    for (const planId of planIds) {
+        const plan = getMaintenancePlan(ctx, planId);
+        refreshReportFromPlan(report, plan);
+        recordMaintenancePlan(report, plan);
+    }
+}
+/**
+ * One bounded post-apply planning wave closes the common autonomous case where an earlier item
+ * safely changed a later item's sealed evidence. Every affected phase replans from the newly
+ * indexed state before any retry curator call, then all retry plans share one final barrier and
+ * the original run budget. A dependency created inside this wave waits for the next cycle; this
+ * function is deliberately not recursive.
+ */
+async function retryDependencyDeferredPhases(ctx, options, report, applied, budget, telemetry, setModelStage) {
+    const deferred = report.maintenancePlans.filter((plan) => plan.status === 'failed' && plan.items.some((item) => item.statusCode === 'dependency_conflict'));
+    if (deferred.length === 0)
+        return;
+    const retryPhases = new Set(deferred.map((plan) => plan.phase));
+    const retryReport = {
+        ...report,
+        phases: [],
+        observations: [],
+        curated: [],
+        rejected: [],
+        adopted: [],
+        repaired: null,
+        repairChangeId: null,
+        housekeeping: null,
+        changeId: null,
+        adoptChangeId: null,
+        curateChangeId: null,
+        maintenancePlan: null,
+        maintenancePlans: [],
+        budget: maintenanceBudgetReceipt(budget),
+        warnings: [],
+        durationMs: 0,
+    };
+    for (const plan of deferred) {
+        recordMaintenancePlan(report, supersedeDependencyMaintenancePlan(ctx, plan.id));
+    }
+    for (const phase of DREAM_PHASES) {
+        if (!retryPhases.has(phase))
+            continue;
+        setModelStage(phase);
+        await runPhase(ctx, phase, options, retryReport, applied, budget, true, telemetry);
+    }
+    await decideAndApplyPlannedPhases(ctx, retryReport, applied, budget, telemetry);
+    mergeRetryReport(report, retryReport);
+}
+function mergeRetryReport(report, retry) {
+    report.observations = mergeByKey(report.observations, retry.observations, (entry) => `${entry.slug}\0${entry.pattern}`);
+    report.curated = mergeByKey(report.curated, retry.curated, (entry) => entry.slug);
+    report.rejected = mergeByKey(report.rejected, retry.rejected, (entry) => `${entry.pattern}\0${entry.reason}`);
+    report.adopted = mergeByKey(report.adopted, retry.adopted, (entry) => entry.slug);
+    report.repaired = mergeRepairResults(report.repaired, retry.repaired);
+    if (retry.changeId !== null)
+        report.changeId = retry.changeId;
+    if (retry.adoptChangeId !== null)
+        report.adoptChangeId = retry.adoptChangeId;
+    if (retry.curateChangeId !== null)
+        report.curateChangeId = retry.curateChangeId;
+    report.warnings.push(...retry.warnings);
+    for (const plan of retry.maintenancePlans) {
+        const existing = report.maintenancePlans.findIndex((candidate) => candidate.id === plan.id);
+        if (existing === -1)
+            report.maintenancePlans.push(plan);
+        else
+            report.maintenancePlans[existing] = plan;
+    }
+    if (retry.maintenancePlan)
+        report.maintenancePlan = retry.maintenancePlan;
+}
+function mergeRepairResults(current, retry) {
+    if (!current)
+        return retry;
+    if (!retry)
+        return current;
+    return {
+        links: mergeByKey(current.links, retry.links, (entry) => `${entry.from}\0${entry.brokenTarget}`),
+        claims: mergeByKey(current.claims, retry.claims, (entry) => `${entry.slug}\0${entry.line}\0${entry.before}`),
+        declined: mergeByKey(current.declined, retry.declined, (entry) => `${entry.what}\0${entry.reason}`),
+    };
+}
+function mergeByKey(current, retry, key) {
+    const merged = new Map(current.map((entry) => [key(entry), entry]));
+    for (const entry of retry)
+        merged.set(key(entry), entry);
+    return [...merged.values()];
+}
+function refreshReportFromPlan(report, plan) {
+    if (plan.phase === 'observe' || plan.phase === 'reflect') {
+        for (const item of plan.items.filter((candidate) => candidate.kind === 'observe' || candidate.kind === 'reflect')) {
+            const next = observationFromPlanItem(item);
+            const existing = report.observations.findIndex((entry) => entry.slug === next.slug && entry.pattern === next.pattern);
+            if (existing === -1)
+                report.observations.push(next);
+            else
+                report.observations[existing] = next;
+        }
+        const changes = plan.items.map((item) => item.changeId).filter((id) => id !== null);
+        report.changeId = changes.length === 1 ? changes[0] : null;
+        return;
+    }
+    if (plan.phase === 'curate') {
+        report.curated = curationReportFromPlan(report.curated, plan);
+        report.repaired = repairResultFromPlan(plan, report.repaired?.declined ?? []);
+        return;
+    }
+    report.adopted = adoptionReportFromPlan(report.adopted, plan);
+    const changes = plan.items.map((item) => item.changeId).filter((id) => id !== null);
+    report.adoptChangeId = changes.length === 1 ? changes[0] : null;
+}
+function curationReportFromPlan(pages, plan) {
+    return pages.map((page) => {
+        const item = plan.items.find((candidate) => isGeneralCurationItem(candidate) && maintenanceItemCoversSlug(candidate, page.slug));
+        if (!item)
+            return page;
+        if (item.status === 'applied')
+            return { ...page, action: 'updated', issues: [] };
+        if (item.status === 'verification_pending') {
+            return {
+                ...page,
+                action: 'updated',
+                issues: [item.verification?.detail ?? 'post-write verification is pending'],
+            };
+        }
+        if (['rejected', 'blocked', 'stale', 'verification_failed'].includes(item.status)) {
+            return {
+                ...page,
+                action: 'rejected',
+                issues: [
+                    item.verification?.detail ??
+                        item.decision?.reason ??
+                        item.statusReason ??
+                        `maintenance item is ${item.status}`,
+                ],
+            };
+        }
+        return page;
+    });
+}
+function maintenanceItemCoversSlug(item, slug) {
+    return (item.subject === slug ||
+        item.evidence.some((entry) => entry.type === 'component' && entry.source === slug));
+}
+function adoptionReportFromPlan(entries, plan) {
+    return entries.map((entry) => {
+        if (entry.action !== 'planned')
+            return entry;
+        const item = plan.items.find((candidate) => candidate.subject === entry.slug);
+        if (!item)
+            return entry;
+        if (item.status === 'applied')
+            return { ...entry, action: 'created' };
+        if (['rejected', 'blocked', 'stale', 'verification_failed'].includes(item.status)) {
+            return {
+                ...entry,
+                action: 'rejected',
+                reason: item.verification?.detail ??
+                    item.decision?.reason ??
+                    item.statusReason ??
+                    `maintenance item is ${item.status}`,
+            };
+        }
+        return entry;
+    });
+}
+/**
+ * The second tier, and the phase that writes the most.
+ *
+ * The guards that need the knowledge base rather than the text are applied here, before the
+ * model sees anything:
+ *
+ * - **Knowledge pages only.** A source page is somebody else's words. "Maria prefers X"
+ *   inferred from a marketing email she was cc'd on is exactly the failure this must not have.
+ * - **Never self-feeding.** An observation is not admissible evidence for another observation.
+ *   No inference cascades.
+ */
+async function repairPhase(ctx, report) {
+    if (!report.repaired) {
+        const result = ctx.config.maintenance.repair.links
+            ? await planBrokenLinks(ctx, ctx.config.maintenance.repair.maxChanges)
+            : { report: { links: [], claims: [], declined: [] } };
+        report.repaired = result.report;
+    }
+    report.warnings.push('the legacy repair phase is report-only; use the curate phase in audit, review, or auto mode to persist guarded link fixes');
+    return null;
+}
+async function observePhase(ctx, options, report, applied, budget, deferAutomaticApply, telemetry) {
+    if (options.dryRun) {
+        await previewObservePhase(ctx, report);
+        return;
+    }
+    const observePolicy = policyMode(effectiveTransformPolicy(ctx.config, 'observe', options.mode));
+    if (!observePolicy)
+        return;
+    let plan = findActiveMaintenancePlan(ctx, observePolicy, 'observe');
+    if (plan && !planMatchesPolicies(plan, { observe: observePolicy }))
+        plan = null;
+    const previouslyRejected = [];
+    if (!plan) {
+        const prepared = await collectPreparedObservations(ctx, report);
+        const drafts = [];
+        for (const entry of prepared) {
+            if (!entry.draft)
+                continue;
+            if (inferenceWasRejected(ctx, 'observe', entry.draft)) {
+                previouslyRejected.push({ ...entry.written, action: 'rejected' });
+            }
+            else {
+                drafts.push(entry.draft);
+            }
+        }
+        plan = createObservationPlan(ctx, observePolicy, drafts, observePolicy);
+    }
+    if (!plan) {
+        report.observations.push(...previouslyRejected);
+        return;
+    }
+    if (observePolicy === 'auto' && !deferAutomaticApply) {
+        if (plan.items.some((item) => item.status === 'proposed' && item.policy === 'auto')) {
+            plan = await decideDreamPlanWithCurator(ctx, plan.id, telemetry);
+        }
+        if (plan.items.some((item) => ['approved', 'applying', 'verification_pending'].includes(item.status))) {
+            const result = await applyMaintenancePlan(ctx, plan.id, budget);
+            plan = result.plan;
+            applied.push(...result.files.map((file) => asApplied('observe', file)));
+        }
+    }
+    report.observations.push(...plan.items.map(observationFromPlanItem), ...previouslyRejected);
+    const changeIds = plan.items
+        .map((item) => item.changeId)
+        .filter((changeId) => changeId !== null);
+    // Compatibility for callers from before observations gained per-item journal changes.
+    report.changeId = changeIds.length === 1 ? changeIds[0] : null;
+    recordMaintenancePlan(report, plan);
+}
+async function previewObservePhase(ctx, report) {
+    const prepared = await collectPreparedObservations(ctx, report);
+    for (const entry of prepared) {
+        report.observations.push(asPreviewObservation(entry.written));
+    }
+}
+function asPreviewObservation(entry) {
+    if (entry.action === 'created')
+        return { ...entry, action: 'would-create' };
+    if (entry.action === 'refined')
+        return { ...entry, action: 'would-refine' };
+    return entry;
+}
+async function collectPreparedObservations(ctx, report) {
+    const groups = subjectGroups(ctx, ctx.config.maintenance.observe.maxSubjects, report.conflicts);
+    if (groups.length === 0)
+        return [];
+    const prepared = [];
+    // Gathered once for the whole phase, not per group: fifteen groups reading the same two things
+    // fifteen times is the same answer at fifteen times the cost.
+    const knownFacts = liveFactClaims(ctx, report.conflicts);
+    const observationsBySlug = await allObservations(ctx);
+    for (const group of groups) {
+        const result = await runObserveMission({
+            // The folder travels with the subject so the model knows what kind of thing it is
+            // looking at: "price, in shopping" is a question; "price" on its own is a word.
+            subject: group.folder === '.' ? group.subject : `${group.subject}, in ${group.folder}`,
+            facts: group.facts,
+            model: ctx.models.derive,
+            mission: ctx.config.maintenance.observe.mission,
+            minEvidence: ctx.config.maintenance.observe.minEvidence,
+            // What last night already concluded about this subject. The facts rarely change between one
+            // night and the next, so without this the same insight comes back reworded every night and
+            // the page accumulates paraphrases of one sentence.
+            existing: observationsBySlug.get(observationSlug(ctx, group.slug)) ?? [],
+            // Everything already observed elsewhere, plus anything written earlier in this same run —
+            // two groups can reach one conclusion from overlapping facts, and each would otherwise write
+            // it to its own page where neither looks like a duplicate.
+            otherObservations: [...observationsBySlug].flatMap(([slug, lines]) => slug === observationSlug(ctx, group.slug) ? [] : lines),
+            knownFacts,
+        });
+        if (result.error) {
+            report.warnings.push(`observe (${group.subject}): ${result.error}`);
+            continue;
+        }
+        report.rejected.push(...result.rejected);
+        for (const observation of result.observations) {
+            const outcome = await prepareObservation(ctx, { title: group.subject, slug: group.slug }, observation);
+            prepared.push(outcome);
+            if (outcome.rejectionReason) {
+                report.rejected.push({ pattern: observation.pattern, reason: outcome.rejectionReason });
+            }
+            // So a later group in this same run sees it. Without this, cross-page duplicates are caught
+            // only from the second night onwards — the night they are created, they both go through.
+            const slug = observationSlug(ctx, group.slug);
+            observationsBySlug.set(slug, [...(observationsBySlug.get(slug) ?? []), observation.pattern]);
+        }
+    }
+    return prepared;
+}
+/**
+ * Live facts from knowledge, non-observation pages, grouped by **folder and subject**.
+ *
+ * Not by subject alone, which is what the first version did and what a real knowledge base
+ * immediately exposed. A small deriver writes the *attribute* into `subject` — "price",
+ * "address", "location", "opening hours" — so grouping on it joined a bag with a drum kit
+ * ("Price is $79 during sales"), and a Roman church with a person's page ("Address is central
+ * and near a major landmark"). Given unrelated facts under one heading, the model does what it
+ * is asked and finds a pattern across them; the input was the bug.
+ *
+ * A folder is the coarsest thing in a knowledge base that means "these are about the same kind
+ * of thing", and it is the user's own division rather than one Akno invented. Two pages in
+ * `shopping/` sharing a subject are at least comparable. Ordered by how recently the pages were
+ * touched, so a capped run looks at what is moving.
+ */
+function subjectGroups(ctx, maxSubjects, conflicts) {
+    const observations = ctx.config.paths.observations;
+    const ineligible = ineligibleConflictClaims(conflicts);
+    const rows = ctx.store.db
+        .prepare(`SELECT f.subject, f.claim, f.line_start, p.slug, p.updated_at
+         FROM facts f JOIN pages p ON p.id = f.page_id
+        WHERE f.valid_to IS NULL
+          AND f.subject IS NOT NULL
+          AND f.confidence >= 0.5
+          -- Only canonical claims. A source page is evidence someone else wrote.
+          AND p.role = 'knowledge'
+          AND p.derived_hash = p.body_hash
+          -- Never self-feeding. An observation is not evidence for another observation.
+          AND p.slug != ?
+          AND p.slug NOT LIKE ?
+        ORDER BY p.updated_at DESC`)
+        .all(observations, `${observations}/%`);
+    const groups = new Map();
+    for (const row of rows) {
+        if (ineligible.has(claimKey(row.slug, row.line_start)))
+            continue;
+        const subject = row.subject.toLowerCase().replace(/\s+/g, ' ').trim();
+        if (subject.length === 0)
+            continue;
+        const folder = row.slug.includes('/') ? row.slug.slice(0, row.slug.indexOf('/')) : '.';
+        const key = `${folder}|${subject}`;
+        const existing = groups.get(key);
+        if (existing) {
+            if (existing.facts.length < 30)
+                existing.facts.push({ claim: row.claim, slug: row.slug });
+        }
+        else {
+            groups.set(key, {
+                subject: row.subject,
+                folder,
+                slug: folder === '.' ? slugify(subject) : `${slugify(folder)}-${slugify(subject)}`,
+                facts: [{ claim: row.claim, slug: row.slug }],
+            });
+        }
+    }
+    return [...groups.values()]
+        .filter((group) => new Set(group.facts.map((fact) => fact.slug)).size >= 2)
+        .slice(0, maxSubjects);
+}
+/**
+ * **Refine, never overwrite** — a changed pattern gets a new dated line. **Add and
+ * refine, never delete** — a curator that can delete loses things nobody watched it delete.
+ *
+ * So the page is only ever appended to, and an observation already on it is left exactly as it
+ * is. That is also what makes the phase safe to re-run: a second pass over unchanged facts
+ * reports `unchanged` and writes nothing.
+ */
+/** Where a subject's observations live. */
+function observationSlug(ctx, pageSlug) {
+    return normalizeSlug(`${ctx.config.paths.observations}/${pageSlug}`);
+}
+/**
+ * Every observation already written, by page.
+ *
+ * Read from the files rather than the index because the index is a reading of the files and this
+ * runs inside the same cycle that writes them.
+ */
+async function allObservations(ctx) {
+    const root = path.join(ctx.config.aknoPath, ctx.config.paths.observations);
+    const bySlug = new Map();
+    const entries = await fsp.readdir(root, { withFileTypes: true, recursive: true }).catch(() => []);
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.md'))
+            continue;
+        const abs = path.join(entry.parentPath ?? root, entry.name);
+        // Skipped for the same reason `scanTree` and the watcher skip them: a dot path is
+        // sync-client or editor state, not an observation. Checked on the whole relative
+        // path rather than `entry.name`, because a recursive readdir reports a file inside
+        // `.trash/` with a perfectly ordinary basename. It also has to happen before
+        // `normalizeSlug` below, which now refuses a dot segment — an unfiltered walk would
+        // turn one stray `.backup.md` into a throw inside the nightly cycle.
+        if (path
+            .relative(root, abs)
+            .split(path.sep)
+            .some((segment) => segment.startsWith('.'))) {
+            continue;
+        }
+        const body = await fsp.readFile(abs, 'utf8').catch(() => null);
+        if (body === null)
+            continue;
+        const lines = body
+            .split('\n')
+            .filter((line) => /^- \d{4}-\d{2}-\d{2} — /.test(line))
+            .map((line) => line
+            .replace(/^- \d{4}-\d{2}-\d{2} — /, '')
+            .replace(/\s*\[\[[^\]]*\]\]/g, '')
+            .trim())
+            .filter(Boolean);
+        if (lines.length === 0)
+            continue;
+        const relative = path.relative(ctx.config.aknoPath, abs).replace(/\.md$/, '');
+        bySlug.set(normalizeSlug(relative), lines);
+    }
+    return bySlug;
+}
+/**
+ * Every live claim in the knowledge base, so an "observation" cannot be one of them handed back.
+ *
+ * Superseded claims are left out: their sentence has already been replaced, and an observation is
+ * not a repeat of something the knowledge base no longer says.
+ */
+function liveFactClaims(ctx, conflicts = []) {
+    const ineligible = ineligibleConflictClaims(conflicts);
+    const rows = ctx.store.db
+        .prepare(`SELECT f.claim, f.line_start, p.slug
+       FROM facts f JOIN pages p ON p.id = f.page_id
+       WHERE f.valid_to IS NULL AND p.derived_hash = p.body_hash`)
+        .all();
+    return rows.filter((row) => !ineligible.has(claimKey(row.slug, row.line_start))).map((row) => row.claim);
+}
+async function prepareObservation(ctx, page, observation, evidenceRole = 'knowledge') {
+    const slug = normalizeSlug(`${ctx.config.paths.observations}/${page.slug}`);
+    const relPath = `${slug}.md`;
+    const absPath = path.join(ctx.config.aknoPath, relPath);
+    const existing = await fsp.readFile(absPath, 'utf8').catch(() => null);
+    // A page is never evidence for itself, whichever caller got here. `reflect` reads the folder it
+    // writes into, so it found `principles` among its own sources and cited it — and a claim offered
+    // as its own support reads, later, as a claim with support.
+    const evidence = observation.evidence.filter((cited) => normalizeSlug(cited) !== slug);
+    if (evidence.length === 0) {
+        return {
+            written: { slug, pattern: observation.pattern, evidence: [], action: 'unchanged' },
+            draft: null,
+        };
+    }
+    observation = { ...observation, evidence };
+    if (existing !== null && existing.includes(observation.pattern)) {
+        return {
+            written: { slug, pattern: observation.pattern, evidence: observation.evidence, action: 'unchanged' },
+            draft: null,
+        };
+    }
+    const today = new Date().toISOString().slice(0, 10);
+    // Deliberately not `- **YYYY-MM-DD** |`, which is read as a timeline event anywhere it
+    // appears. An inferred pattern is not something that happened on a date.
+    const line = `- ${today} — ${observation.pattern} ${citation(observation.evidence)}`;
+    const next = existing === null
+        ? newObservationPage(page.title, observation, today)
+        : appendObservation(existing, line, observation.evidence);
+    const written = {
+        slug,
+        pattern: observation.pattern,
+        evidence: observation.evidence,
+        action: existing === null ? 'created' : 'refined',
+    };
+    const sealedEvidence = await observationEvidence(ctx, observation.evidence, evidenceRole);
+    if (sealedEvidence.length !== observation.evidence.length) {
+        return {
+            written: { ...written, action: 'rejected' },
+            draft: null,
+            rejectionReason: 'evidence changed or stopped being live before the observation was sealed',
+        };
+    }
+    const inputHash = sha256(JSON.stringify({
+        slug,
+        beforeHash: existing === null ? null : sha256(existing),
+        pattern: observation.pattern,
+        evidence: sealedEvidence,
+    }));
+    return {
+        written,
+        draft: { slug, relPath, inputHash, before: existing, after: next, evidence: sealedEvidence },
+    };
+}
+async function observationEvidence(ctx, slugs, role) {
+    const out = [];
+    for (const slug of slugs) {
+        const row = ctx.store.db
+            .prepare('SELECT rel_path FROM pages WHERE slug = ? AND role = ?')
+            .get(slug, role);
+        if (!row)
+            continue;
+        const content = await fsp
+            .readFile(path.join(ctx.config.aknoPath, row.rel_path), 'utf8')
+            .catch(() => null);
+        if (content === null)
+            continue;
+        out.push({ slug, contentHash: sha256(content) });
+    }
+    return out;
+}
+function inferenceWasRejected(ctx, kind, draft) {
+    const row = ctx.store.db
+        .prepare(`SELECT 1 FROM maintenance_items
+        WHERE kind = ? AND status = 'rejected' AND subject = ? AND input_hash = ?
+        LIMIT 1`)
+        .get(kind, draft.slug, draft.inputHash);
+    return row !== undefined;
+}
+function observationFromPlanItem(item) {
+    const operation = item.operations[0];
+    if (operation.type === 'move')
+        throw new Error('an inference item cannot move a document');
+    const after = operation.type === 'delete' ? operation.before : operation.after;
+    const lastLine = after.trimEnd().split('\n').at(-1) ?? '';
+    const pattern = /^- \d{4}-\d{2}-\d{2} — (.+?)(?:\s+\[\[[^\]]+\]\])+$/.exec(lastLine)?.[1] ?? '';
+    const proposed = operation.type === 'create' ? 'would-create' : 'would-refine';
+    const action = item.status === 'applied'
+        ? operation.type === 'create'
+            ? 'created'
+            : 'refined'
+        : ['rejected', 'blocked', 'stale', 'verification_failed'].includes(item.status)
+            ? 'rejected'
+            : proposed;
+    return {
+        slug: item.subject,
+        pattern,
+        evidence: item.evidence.filter((entry) => entry.type === 'page').map((entry) => entry.source),
+        action,
+    };
+}
+/**
+ * `derived` and `evidence` are the two keys Akno writes on `observations/` pages it
+ * authors. They are what makes an inference identifiable as one after the fact — by a reader,
+ * by recall's ranking, and by the guard that refuses to feed observations back in.
+ */
+function newObservationPage(subject, observation, today) {
+    const title = subject.charAt(0).toUpperCase() + subject.slice(1);
+    return (`---\ntitle: ${title}\nderived: true\nevidence:\n${observation.evidence
+        .map((slug) => `  - ${slug}`)
+        .join('\n')}\n---\n\n` +
+        `# ${title}\n\n` +
+        `Patterns Akno inferred from pages listed as evidence. Not authored claims.\n\n` +
+        `- ${today} — ${observation.pattern} ${citation(observation.evidence)}\n`);
+}
+/** Appends the new line and unions the evidence, leaving every existing line alone. */
+function appendObservation(current, line, evidence) {
+    const merged = mergeEvidence(current, evidence);
+    return `${merged.replace(/\s+$/, '')}\n${line}\n`;
+}
+function mergeEvidence(current, evidence) {
+    const match = /^---\n([\s\S]*?)\n---\n/.exec(current);
+    if (!match)
+        return current;
+    const front = match[1];
+    const listed = new Set([...front.matchAll(/^\s*-\s*(\S+)\s*$/gm)].map((entry) => entry[1]));
+    const missing = evidence.filter((slug) => !listed.has(slug));
+    if (missing.length === 0)
+        return current;
+    // Appended under the existing `evidence:` key, or added as one. Every other frontmatter key
+    // is left byte for byte: that promise holds for pages Akno authors too.
+    const added = missing.map((slug) => `  - ${slug}`).join('\n');
+    const nextFront = /^evidence:/m.test(front)
+        ? front.replace(/^(evidence:(?:\n\s*-\s*\S+)*)/m, `$1\n${added}`)
+        : `${front}\nevidence:\n${added}`;
+    return current.replace(match[0], `---\n${nextFront}\n---\n`);
+}
+function citation(evidence) {
+    return evidence.map((slug) => `[[${slug}]]`).join(' ');
+}
+function slugify(subject) {
+    return (subject
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 60) || 'pattern');
+}
+// ─── Reflect ────────────────────────────────────────────────────────────────
+/**
+ * The third tier — **off by default**, and shipped as an extension point rather than a
+ * finished tier because at a few hundred pages a "pattern" is one coincidence away from noise.
+ *
+ * The plumbing is real: enabling it runs the observe writer over the tier above, so principles
+ * are built from observations and the pages behind them. What it deliberately does not do is
+ * invent a second set of guardrails — the same evidence floor, the same refusal to hedge, the
+ * same append-only writing.
+ */
+/** The one page `reflect` writes, and the one page it must not read. */
+const PRINCIPLES_SLUG = 'principles';
+async function reflectPhase(ctx, options, report, applied, budget, deferAutomaticApply, telemetry) {
+    if (options.dryRun) {
+        await previewReflectPhase(ctx, report);
+        return;
+    }
+    const reflectPolicy = policyMode(effectiveTransformPolicy(ctx.config, 'reflect', options.mode));
+    if (!reflectPolicy)
+        return;
+    let plan = findActiveMaintenancePlan(ctx, reflectPolicy, 'reflect');
+    if (plan && !planMatchesPolicies(plan, { reflect: reflectPolicy }))
+        plan = null;
+    const previouslyRejected = [];
+    if (!plan) {
+        const prepared = await collectPreparedReflections(ctx, report);
+        const drafts = [];
+        for (const entry of prepared) {
+            if (!entry.draft)
+                continue;
+            if (inferenceWasRejected(ctx, 'reflect', entry.draft)) {
+                previouslyRejected.push({ ...entry.written, action: 'rejected' });
+            }
+            else {
+                drafts.push(entry.draft);
+            }
+        }
+        plan = createReflectionPlan(ctx, reflectPolicy, drafts, reflectPolicy);
+    }
+    if (!plan) {
+        report.observations.push(...previouslyRejected);
+        return;
+    }
+    if (reflectPolicy === 'auto' && !deferAutomaticApply) {
+        if (plan.items.some((item) => item.status === 'proposed' && item.policy === 'auto')) {
+            plan = await decideDreamPlanWithCurator(ctx, plan.id, telemetry);
+        }
+        if (plan.items.some((item) => ['approved', 'applying', 'verification_pending'].includes(item.status))) {
+            const result = await applyMaintenancePlan(ctx, plan.id, budget);
+            plan = result.plan;
+            applied.push(...result.files.map((file) => asApplied('reflect', file)));
+        }
+    }
+    report.observations.push(...plan.items.map(observationFromPlanItem), ...previouslyRejected);
+    const changeIds = plan.items
+        .map((item) => item.changeId)
+        .filter((changeId) => changeId !== null);
+    report.changeId = changeIds.length === 1 ? changeIds[0] : null;
+    recordMaintenancePlan(report, plan);
+}
+async function previewReflectPhase(ctx, report) {
+    const prepared = await collectPreparedReflections(ctx, report);
+    for (const outcome of prepared) {
+        report.observations.push(asPreviewObservation(outcome.written));
+    }
+}
+async function collectPreparedReflections(ctx, report) {
+    // The page this phase writes to is under `observations/` like everything it reads, so without
+    // excluding it the tier feeds on its own output: from the second night onwards `principles` has a
+    // summary, is selected as a source, and is cited as evidence for the principle it already
+    // contains. A conclusion that is its own evidence is not a conclusion.
+    const target = observationSlug(ctx, PRINCIPLES_SLUG);
+    const observations = await allObservations(ctx);
+    const ineligibleSources = ineligibleConflictSourceSlugs(report.conflicts);
+    const rows = ctx.store.db
+        .prepare(`SELECT slug, summary, frontmatter FROM pages
+        WHERE (slug = ? OR slug LIKE ?) AND slug != ? AND summary IS NOT NULL
+        ORDER BY updated_at DESC LIMIT 40`)
+        .all(ctx.config.paths.observations, `${ctx.config.paths.observations}/%`, target).filter((row) => !frontmatterEvidence(row.frontmatter).some((slug) => ineligibleSources.has(slug)));
+    if (rows.length < 2) {
+        report.warnings.push('reflect had fewer than two observations to build on — nothing was written');
+        return [];
+    }
+    const result = await runObserveMission({
+        subject: 'decision principles',
+        facts: rows.map((row) => ({ claim: row.summary, slug: row.slug })),
+        model: ctx.models.derive,
+        mission: ctx.config.maintenance.reflect.mission ??
+            'State durable decision principles and long-term tendencies, not individual patterns.',
+        // A tier further from the evidence needs more of it.
+        minEvidence: Math.max(3, ctx.config.maintenance.observe.minEvidence),
+        // This tier appends to one page every night from observations that rarely change, so without
+        // its own previous answers it restates them — the same way `observe` did, one tier up.
+        existing: observations.get(target) ?? [],
+        // A principle that is one of the observation lines verbatim is not a tier above them. Its
+        // sources here are page *summaries*, so the lines themselves are not otherwise checked.
+        otherObservations: [...observations].flatMap(([slug, lines]) => (slug === target ? [] : lines)),
+        // Nor a raw claim promoted to a principle. `facts` for this phase is the observations, so
+        // without this the knowledge base's own facts are the one thing it is not compared against.
+        knownFacts: liveFactClaims(ctx, report.conflicts),
+    });
+    if (result.error) {
+        report.warnings.push(`reflect: ${result.error}`);
+        return [];
+    }
+    report.rejected.push(...result.rejected);
+    const prepared = [];
+    for (const observation of result.observations) {
+        const outcome = await prepareObservation(ctx, { title: 'Principles', slug: PRINCIPLES_SLUG }, observation, 'inference');
+        prepared.push(outcome);
+        if (outcome.rejectionReason) {
+            report.rejected.push({ pattern: observation.pattern, reason: outcome.rejectionReason });
+        }
+    }
+    return prepared;
+}
+function ineligibleConflictSourceSlugs(conflicts) {
+    const keys = ineligibleConflictClaims(conflicts);
+    const slugs = new Set();
+    for (const conflict of conflicts) {
+        for (const claim of conflict.claims) {
+            if (keys.has(claimKey(claim.slug, claim.line)))
+                slugs.add(claim.slug);
+        }
+    }
+    return slugs;
+}
+function frontmatterEvidence(frontmatter) {
+    try {
+        const value = JSON.parse(frontmatter);
+        return Array.isArray(value.evidence)
+            ? value.evidence.filter((entry) => typeof entry === 'string')
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** A journal entry, as the log wants it: which phase, and what the write added. */
+function asApplied(phase, file) {
+    return {
+        phase,
+        relPath: file.relPath,
+        action: file.action,
+        added: file.after === null ? [] : addedLines(file.before, file.after),
+    };
+}
+/** Guard for the CLI: a phase name that is not one. */
+export function parsePhase(value) {
+    if (DREAM_PHASES.includes(value))
+        return value;
+    throw new AknoError('invalid', `unknown phase '${value}' — expected one of ${DREAM_PHASES.join(', ')}`);
+}
+//# sourceMappingURL=dream.js.map