@tenphi/akno-core 0.10.1 → 0.12.0

package/dist/maintenance/managed-items.js

@@ -4,12 +4,13 @@ import { z } from 'zod';
 import { parseFrontmatter } from "../kb/frontmatter.js";
 import { parsePage, resolvePagePolicy } from "../kb/page.js";
 import { parseJsonLoose } from "../models/client.js";
+import { retainedTemporalBoundary } from "../memory/temporal-destination.js";
 import { isReserved } from "../reserved.js";
-import { effectiveRule } from "../rules/compile.js";
+import { declaringRule, effectiveRule } from "../rules/compile.js";
 import { sha256 } from "../store/ids.js";
 import { parseManagedMemoryMarker } from "../write/managed-memory.js";
 import { emptyManagedSourceMetrics, groundedManagedReplacement, managedSourceItemIds, pruneManagedSourceArchives, qualifyManagedSources, } from "./managed-item-sources.js";
-import { emptyManagedRoutingMetrics, hasH2, managedSectionHeading, qualifyManagedItemRouting, } from "./managed-item-routing.js";
+import { emptyManagedRoutingMetrics, hasH2, managedSectionHeading, qualifyManagedItemRouting, qualifyManagedRoutingDestination, repeatsManagedRoutingEdge, } from "./managed-item-routing.js";
 const MANAGED_ITEM_FINDING_CODES = [
     'empty_marker',
     'malformed_marker',
@@ -22,6 +23,9 @@ const MANAGED_ITEM_FINDING_CODES = [
     'routing_deferred',
     'routing_uncertain',
     'routing_unavailable',
+    'routing_oscillation',
+    'source_vacated',
+    'empty_knowledge_page',
     'wording_corrected',
     'wording_uncertain',
     'source_unavailable',
@@ -131,6 +135,12 @@ export function inspectManagedItems(content) {
     const after = prefix + lines.flatMap((line, index) => (remove.has(index) ? [] : [line])).join('\n');
     return { after, inspectedMarkers, findings, repairs, bindings };
 }
+/** A frontmatter-and-heading skeleton has no knowledge of its own to preserve as a standalone page. */
+function isEmptyKnowledgePageShell(content) {
+    const frontmatter = parseFrontmatter(content);
+    const body = content.slice(frontmatter.bodyOffset).replace(/<!--[^]*?-->/g, '');
+    return body.split(/\r?\n/).every((line) => line.trim() === '' || /^\s{0,3}#{1,6}(?:\s+.*)?$/.test(line));
+}
 /** The sealed replacement must be exactly the structural repair and qualified exact-block move it declares. */
 export function managedItemRepairIssue(before, after, placements = [], corrections = []) {
     const inspection = inspectManagedItems(before);
@@ -179,6 +189,9 @@ export function managedItemOperationsIssue(replacements, placements = [], correc
     if (!applied.ok || applied.source !== source.after || applied.destination !== destination.after) {
         return 'the managed-item output is broader than its exact cross-page transfer';
     }
+    if (!transfer.sourceIsFallbackQueue && isEmptyKnowledgePageShell(applied.source)) {
+        return 'a cross-page managed-item move may not vacate a normal knowledge page';
+    }
     return null;
 }
 export async function planManagedItems(ctx, options = {}) {
@@ -223,19 +236,26 @@ export async function planManagedItems(ctx, options = {}) {
         report.eligiblePages += 1;
         const inspection = inspectManagedItems(before);
         report.inspectedMarkers += inspection.inspectedMarkers;
+        if (inspection.inspectedMarkers === 0 && isEmptyKnowledgePageShell(before)) {
+            addFinding(report, { code: 'empty_knowledge_page', line: page.bodyLine, outcome: 'held' }, 'held', page.slug);
+        }
         eligible.push({ row, before, page, inspection });
     }
     if (sourceScanComplete)
         pruneManagedSourceArchives(ctx, liveManagedSourceIds);
     const crossPageCollisions = crossPageItemCollisions(eligible);
-    const facts = currentManagedFacts(ctx);
+    const memories = currentManagedMemories(ctx);
     const prepared = eligible.map((candidate) => ({
         candidate,
-        inspection: withBindingFindings(ctx, candidate, facts, crossPageCollisions, options),
+        inspection: withBindingFindings(candidate, memories, crossPageCollisions, options),
     }));
+    const fallbackSlug = ctx.config.maintenance.retain.fallbackPage;
     const routingPages = new Map(prepared
         .filter((entry) => entry.inspection.repairs.length === 0)
-        .map(({ candidate }) => [candidate.page.slug, managedRoutingPage(candidate)]));
+        .map(({ candidate }) => [
+        candidate.page.slug,
+        managedRoutingPage(ctx, candidate, candidate.page.slug === fallbackSlug),
+    ]));
     const occupiedPaths = new Set();
     const suppressedRoutingSources = new Set();
     const routingFindings = new Map();
@@ -248,17 +268,20 @@ export async function planManagedItems(ctx, options = {}) {
         for (const binding of inspection.bindings) {
             if (blockedLines.has(binding.markerLine))
                 continue;
-            const fact = facts.get(binding.id);
+            const memory = memories.get(binding.id);
             const removed = removeManagedBlock(candidate.before, binding);
-            if (!fact || !removed)
+            if (!memory || !removed)
                 continue;
-            const qualified = await qualifyManagedItemRouting(ctx, managedRoutingPage(candidate), removed.content, {
+            const routingSource = managedRoutingPage(ctx, candidate, candidate.page.slug === fallbackSlug);
+            const routingItem = {
                 id: binding.id,
                 payload: binding.payload,
-                subject: fact.subject,
-                attribute: fact.attribute,
+                subject: memory.routingSubject,
+                attribute: memory.attribute || binding.currentHeading || memory.kind,
                 currentHeading: binding.currentHeading,
-            }, routingPages);
+                temporalBoundary: binding.temporalBoundary,
+            };
+            const qualified = await qualifyManagedItemRouting(ctx, routingSource, removed.content, routingItem, routingPages);
             addRoutingMetrics(report.routing, qualified.metrics);
             if (qualified.decision.outcome === 'keep')
                 continue;
@@ -270,7 +293,7 @@ export async function planManagedItems(ctx, options = {}) {
             if (!destination ||
                 destination.inspection.repairs.length > 0 ||
                 occupiedPaths.has(destination.candidate.row.rel_path)) {
-                report.routing.moved -= 1;
+                retractRoutingMove(report.routing, qualified.decision.createHeading === true);
                 report.routing.unavailable += 1;
                 setRoutingFinding(routingFindings, candidate.row.rel_path, binding.markerLine, 'routing_unavailable', 'held');
                 continue;
@@ -284,15 +307,42 @@ export async function planManagedItems(ctx, options = {}) {
                 destinationSlug: destination.candidate.page.slug,
                 destinationHeading: qualified.decision.targetHeading,
                 createDestinationHeading: qualified.decision.createHeading,
-                destinationHeadingSource: qualified.decision.createHeading ? fact.attribute : undefined,
+                destinationHeadingSource: qualified.decision.createHeading
+                    ? memory.attribute || binding.currentHeading || memory.kind
+                    : undefined,
+                sourceIsFallbackQueue: candidate.page.slug === fallbackSlug,
             };
             const applied = applyManagedItemTransfer(candidate.before, destination.candidate.before, transfer);
             if (!applied.ok) {
-                report.routing.moved -= 1;
+                retractRoutingMove(report.routing, qualified.decision.createHeading === true);
                 report.routing.unavailable += 1;
                 setRoutingFinding(routingFindings, candidate.row.rel_path, binding.markerLine, 'routing_unavailable', 'held');
                 continue;
             }
+            if (repeatsManagedRoutingEdge(qualified.history, candidate.row.rel_path, destination.candidate.row.rel_path)) {
+                retractRoutingMove(report.routing, qualified.decision.createHeading === true);
+                report.routing.oscillationHolds += 1;
+                setRoutingFinding(routingFindings, candidate.row.rel_path, binding.markerLine, 'routing_oscillation', 'held');
+                continue;
+            }
+            if (!transfer.sourceIsFallbackQueue && isEmptyKnowledgePageShell(applied.source)) {
+                retractRoutingMove(report.routing, qualified.decision.createHeading === true);
+                report.routing.sourceVacatedHolds += 1;
+                setRoutingFinding(routingFindings, candidate.row.rel_path, binding.markerLine, 'source_vacated', 'held');
+                continue;
+            }
+            report.routing.classifierCalls += 1;
+            report.routing.validationCalls += 1;
+            const destinationValidation = await qualifyManagedRoutingDestination(ctx, routingSource, removed.content, routingItem, managedRoutingPage(ctx, destination.candidate, destination.candidate.page.slug === fallbackSlug), transfer.destinationHeading, qualified.history);
+            if (destinationValidation !== 'accept') {
+                retractRoutingMove(report.routing, qualified.decision.createHeading === true);
+                if (destinationValidation === 'unavailable')
+                    report.routing.unavailable += 1;
+                else
+                    report.routing.uncertain += 1;
+                setRoutingFinding(routingFindings, candidate.row.rel_path, binding.markerLine, destinationValidation === 'unavailable' ? 'routing_unavailable' : 'routing_uncertain', 'held');
+                continue;
+            }
             const inputHash = managedTransferInputHash(candidate.before, applied.source, destination.candidate.before, applied.destination, transfer);
             const finding = {
                 code: 'misrouted_item',
@@ -347,7 +397,7 @@ export async function planManagedItems(ctx, options = {}) {
         // First seal deterministic normalization on its own. Besides keeping the move verifier small,
         // this ensures semantic qualification always sees the exact canonical bytes it is judging.
         if (inspection.repairs.length === 0) {
-            const qualified = await qualifyManagedItemPlacement(ctx, candidate, inspection, facts);
+            const qualified = await qualifyManagedItemPlacement(ctx, candidate, inspection, memories);
             addPlacementMetrics(report.placement, qualified.metrics);
             const applied = applyQualifiedPlacementFindings(inspection, qualified);
             inspection = applied.inspection;
@@ -406,14 +456,23 @@ function deferPlacementUntilCanonical(inspection) {
     });
     return { inspection: { ...inspection, findings }, fragments };
 }
-function managedRoutingPage(candidate) {
+function managedRoutingPage(ctx, candidate, fallback) {
+    const rule = effectiveRule(candidate.page.slug, ctx.config.rules);
+    const purposeRule = declaringRule(candidate.page.slug, ctx.config.rules, 'description');
     return {
         id: candidate.row.id,
         slug: candidate.page.slug,
+        relPath: candidate.row.rel_path,
         title: candidate.page.title,
+        type: candidate.page.type ?? rule.type ?? null,
+        about: [...new Set([...candidate.page.about, ...(rule.about ?? [])])],
+        folderPath: path.posix.dirname(candidate.page.slug) === '.' ? '' : path.posix.dirname(candidate.page.slug),
+        folderRule: purposeRule?.glob ?? null,
+        folderPurpose: rule.description ?? null,
         bodyHash: candidate.page.bodyHash,
         body: candidate.page.body,
         headings: uniqueManagedHeadings(candidate.before),
+        fallback,
     };
 }
 function setRoutingFinding(findings, relPath, line, code, outcome) {
@@ -453,12 +512,28 @@ function applyRoutingFindings(inspection, routed) {
     }
     return { ...inspection, findings };
 }
-function currentManagedFacts(ctx) {
+function currentManagedMemories(ctx) {
     const rows = ctx.store.db
-        .prepare(`SELECT item_id, page_id, line_start, source_line_hash, subject, attribute
-         FROM facts WHERE item_id IS NOT NULL AND valid_to IS NULL`)
+        .prepare(`SELECT memory.memory_id AS item_id, memory.source_page AS page_id,
+              memory.payload_line AS line_start, memory.payload_hash AS source_line_hash,
+              COALESCE(fact.subject, entity.label, '') AS routing_subject,
+              COALESCE(fact.attribute, '') AS attribute, memory.kind
+         FROM managed_memory_entries memory
+         LEFT JOIN facts fact ON fact.item_id = memory.memory_id AND fact.valid_to IS NULL
+         LEFT JOIN graph_entities entity ON entity.id = memory.subject`)
         .all();
-    return new Map(rows.map((row) => [row.item_id, row]));
+    return new Map(rows.map((row) => [
+        row.item_id,
+        {
+            item_id: row.item_id,
+            page_id: row.page_id,
+            line_start: row.line_start,
+            source_line_hash: row.source_line_hash,
+            routingSubject: row.routing_subject,
+            attribute: row.attribute,
+            kind: row.kind,
+        },
+    ]));
 }
 function crossPageItemCollisions(pages) {
     const occurrences = new Map();
@@ -478,7 +553,7 @@ function crossPageItemCollisions(pages) {
     }
     return collisions;
 }
-function withBindingFindings(ctx, candidate, facts, collisions, options) {
+function withBindingFindings(candidate, memories, collisions, options) {
     const extra = new Map();
     for (const binding of candidate.inspection.bindings) {
         const collisionKey = `${candidate.row.rel_path}\0${binding.markerLine}`;
@@ -487,18 +562,14 @@ function withBindingFindings(ctx, candidate, facts, collisions, options) {
             extra.set(binding.markerLine, 'item_conflict');
             continue;
         }
-        if (!ctx.config.index.facts || candidate.row.derived_hash !== candidate.row.body_hash) {
+        const memory = memories.get(binding.id);
+        if (!memory) {
             extra.set(binding.markerLine, 'source_unavailable');
             continue;
         }
-        const fact = facts.get(binding.id);
-        if (!fact) {
-            extra.set(binding.markerLine, 'source_unavailable');
-            continue;
-        }
-        if (fact.page_id !== candidate.row.id ||
-            fact.line_start !== binding.payloadLine ||
-            fact.source_line_hash !== sha256(binding.payload.trim())) {
+        if (memory.page_id !== candidate.row.id ||
+            memory.line_start !== binding.payloadLine ||
+            memory.source_line_hash !== sha256(binding.payload.trim())) {
             extra.set(binding.markerLine, 'item_conflict');
         }
     }
@@ -512,7 +583,7 @@ function withBindingFindings(ctx, candidate, facts, collisions, options) {
     }
     return { ...candidate.inspection, findings };
 }
-async function qualifyManagedItemPlacement(ctx, candidate, inspection, facts) {
+async function qualifyManagedItemPlacement(ctx, candidate, inspection, memories) {
     const metrics = emptyPlacementMetrics();
     const blockedIds = new Set(inspection.findings
         .filter((finding) => [
@@ -520,6 +591,8 @@ async function qualifyManagedItemPlacement(ctx, candidate, inspection, facts) {
         'source_unavailable',
         'routing_uncertain',
         'routing_unavailable',
+        'routing_oscillation',
+        'source_vacated',
         'misrouted_item',
         'routing_deferred',
     ].includes(finding.code))
@@ -544,7 +617,8 @@ async function qualifyManagedItemPlacement(ctx, candidate, inspection, facts) {
     }
     const headings = uniqueManagedHeadings(candidate.before);
     const creatableHeadings = new Map(bindings.flatMap((binding) => {
-        const proposed = managedSectionHeading(facts.get(binding.id)?.attribute ?? '');
+        const memory = memories.get(binding.id);
+        const proposed = managedSectionHeading(memory?.attribute || binding.currentHeading || memory?.kind || '');
         return proposed && !hasH2(candidate.page.body, proposed.heading)
             ? [[binding.id, proposed]]
             : [];
@@ -647,7 +721,9 @@ async function qualifyManagedItemPlacement(ctx, candidate, inspection, facts) {
                 fromHeading: binding.currentHeading,
                 toHeading: decision.targetHeading,
                 createHeading: decision.createHeading,
-                headingSource: decision.createHeading ? facts.get(binding.id)?.attribute : undefined,
+                headingSource: decision.createHeading
+                    ? memories.get(binding.id)?.attribute || binding.currentHeading || memories.get(binding.id)?.kind
+                    : undefined,
             });
         }
     }
@@ -726,6 +802,8 @@ async function qualifyManagedItemSourceBindings(ctx, candidate, inspection) {
         'source_unavailable',
         'routing_uncertain',
         'routing_unavailable',
+        'routing_oscillation',
+        'source_vacated',
         'misrouted_item',
         'routing_deferred',
     ].includes(finding.code))
@@ -957,6 +1035,7 @@ function managedContentKey(marker) {
 }
 function managedBinding(marker, bodyLine, headings) {
     const context = headings.get(marker.markerIndex) ?? { heading: null, unique: false };
+    const temporalBoundary = retainedTemporalBoundary(marker.time, marker.payload);
     return {
         id: marker.id,
         origin: marker.sourceRole === 'user' || marker.sourceRole === 'assistant' ? marker.sourceRole : 'unknown',
@@ -967,6 +1046,7 @@ function managedBinding(marker, bodyLine, headings) {
         payloadIndex: marker.payloadIndex,
         currentHeading: context.heading,
         currentHeadingUnique: context.unique && normalizedHeading(context.heading ?? '') !== normalizedHeading('Unsorted'),
+        ...(temporalBoundary ? { temporalBoundary } : {}),
     };
 }
 /** A model may judge semantic fit later; these are only the structurally provable placement failures. */
@@ -1032,7 +1112,7 @@ function uniqueManagedHeadings(content) {
 function normalizedHeading(value) {
     return value.normalize('NFKC').trim().toLowerCase();
 }
-/** Move only the exact marker-through-payload bytes; every pre-existing surrounding byte survives. */
+/** Move the exact owned block and prune only a unique source heading left structurally empty. */
 export function applyManagedItemMoves(content, moves) {
     let current = content;
     for (const move of moves) {
@@ -1054,7 +1134,7 @@ export function applyManagedItemMoves(content, moves) {
     }
     return { ok: true, content: current };
 }
-/** Move one complete owned block between existing pages, optionally adding one sealed bounded heading. */
+/** Move one owned block between pages, optionally adding or pruning one structurally bounded heading. */
 export function applyManagedItemTransfer(sourceContent, destinationContent, transfer) {
     const sourceInspection = inspectManagedItems(sourceContent);
     const matches = sourceInspection.bindings.filter((binding) => binding.id === transfer.itemId);
@@ -1097,43 +1177,13 @@ function applyManagedItemCorrections(content, corrections) {
     return { ok: true, content: current };
 }
 function moveManagedBlock(content, binding, targetHeading, createHeading = false, headingSource) {
-    const frontmatter = parseFrontmatter(content);
-    const prefix = content.slice(0, frontmatter.bodyOffset);
-    const body = content.slice(frontmatter.bodyOffset);
-    const spans = rawLineSpans(body);
-    const marker = spans[binding.markerIndex];
-    const payload = spans[binding.payloadIndex];
-    if (!marker || !payload || payload.contentEnd < marker.start)
+    const removed = removeManagedBlock(content, binding);
+    if (!removed)
         return null;
-    const block = body.slice(marker.start, payload.contentEnd);
-    const without = body.slice(0, marker.start) + body.slice(payload.contentEnd);
     if (createHeading) {
-        return insertManagedBlockWithNewHeading(prefix + without, block, targetHeading, headingSource);
+        return insertManagedBlockWithNewHeading(removed.content, removed.block, targetHeading, headingSource);
     }
-    const targetKey = normalizedHeading(targetHeading);
-    const withoutSpans = rawLineSpans(without);
-    const targets = withoutSpans
-        .map((span, index) => ({
-        index,
-        span,
-        heading: /^\s{0,3}##(?:\s+(.+?)\s*|\s*)$/.exec(span.text)?.[1]?.trim(),
-    }))
-        .filter((entry) => entry.heading && normalizedHeading(entry.heading) === targetKey);
-    if (targets.length !== 1)
-        return null;
-    let insertionOffset = without.length;
-    for (let index = targets[0].index + 1; index < withoutSpans.length; index++) {
-        if (/^\s{0,3}#{1,2}(?:\s+|$)/.test(withoutSpans[index].text)) {
-            insertionOffset = withoutSpans[index].start;
-            break;
-        }
-    }
-    const before = without.slice(0, insertionOffset);
-    const after = without.slice(insertionOffset);
-    const eol = body.includes('\r\n') ? '\r\n' : '\n';
-    const beforeGap = lineGapBefore(before, eol);
-    const afterGap = lineGapAfter(after, eol, body.endsWith(eol));
-    return prefix + before + beforeGap + block + afterGap + after;
+    return insertManagedBlock(removed.content, removed.block, targetHeading);
 }
 function insertManagedBlockWithNewHeading(content, block, targetHeading, headingSource) {
     const guarded = managedSectionHeading(headingSource ?? '');
@@ -1158,11 +1208,47 @@ function removeManagedBlock(content, binding) {
     const payload = spans[binding.payloadIndex];
     if (!marker || !payload || payload.contentEnd < marker.start)
         return null;
+    const block = body.slice(marker.start, payload.contentEnd);
+    const sourceHeadingIndex = sourceHeadingForBinding(spans, binding);
+    if (sourceHeadingIndex !== null) {
+        const heading = spans[sourceHeadingIndex];
+        const sectionContentStart = spans[sourceHeadingIndex + 1]?.start ?? body.length;
+        const sectionEnd = spans.slice(binding.payloadIndex + 1).find((span) => /^\s{0,3}#{1,2}(?:\s+|$)/.test(span.text))
+            ?.start ?? body.length;
+        const remainingSection = body.slice(sectionContentStart, marker.start) + body.slice(payload.contentEnd, sectionEnd);
+        if (remainingSection.trim().length === 0) {
+            return {
+                content: prefix + body.slice(0, heading.start) + body.slice(sectionEnd),
+                block,
+            };
+        }
+    }
     return {
         content: prefix + body.slice(0, marker.start) + body.slice(payload.contentEnd),
-        block: body.slice(marker.start, payload.contentEnd),
+        block,
     };
 }
+/** Find only the unique H2 section that structurally owns this binding. */
+function sourceHeadingForBinding(spans, binding) {
+    if (!binding.currentHeading)
+        return null;
+    for (let index = binding.markerIndex - 1; index >= 0; index--) {
+        const heading = /^\s{0,3}(#{1,2})(?:\s+(.+?)\s*|\s*)$/.exec(spans[index].text);
+        if (!heading)
+            continue;
+        if (heading[1] === '#')
+            return null;
+        const key = normalizedHeading(heading[2]?.trim() ?? '');
+        if (key !== normalizedHeading(binding.currentHeading))
+            return null;
+        const occurrences = spans.filter((span) => {
+            const candidate = /^\s{0,3}##(?:\s+(.+?)\s*|\s*)$/.exec(span.text)?.[1]?.trim();
+            return candidate !== undefined && normalizedHeading(candidate) === key;
+        }).length;
+        return occurrences === 1 ? index : null;
+    }
+    return null;
+}
 function insertManagedBlock(content, block, targetHeading) {
     const frontmatter = parseFrontmatter(content);
     const prefix = content.slice(0, frontmatter.bodyOffset);
@@ -1307,6 +1393,11 @@ function addRoutingMetrics(target, addition) {
         target[key] += addition[key];
     }
 }
+function retractRoutingMove(metrics, createdHeading) {
+    metrics.moved = Math.max(0, metrics.moved - 1);
+    if (createdHeading)
+        metrics.sectionsCreated = Math.max(0, metrics.sectionsCreated - 1);
+}
 function addSourceMetrics(target, addition) {
     for (const key of Object.keys(target)) {
         target[key] += addition[key];