@tenphi/akno-core 0.1.0

package/dist/maintenance/recovery.js

@@ -0,0 +1,217 @@
+import { AknoError } from '@tenphi/akno-protocol';
+import { MAINTENANCE_TRANSFORMS } from "../config/schema.js";
+export const MAINTENANCE_ROLLBACK_PAUSE_THRESHOLD = 3;
+export function maintenanceRecoveryStatus(ctx) {
+    if (!recoveryTableAvailable(ctx))
+        return emptyMaintenanceRecoveryStatus();
+    const rows = ctx.store.db
+        .prepare('SELECT * FROM maintenance_recovery_state ORDER BY scope, transform')
+        .all();
+    const entries = rows.flatMap((row) => {
+        const entry = recoveryEntry(row);
+        return entry ? [entry] : [];
+    });
+    const profile = entries.find((entry) => entry.scope === 'profile') ?? null;
+    const transforms = entries.filter((entry) => entry.scope === 'transform');
+    return {
+        automaticApply: profile
+            ? 'paused'
+            : transforms.some((entry) => entry.pausedAt !== null)
+                ? 'partially_paused'
+                : 'available',
+        profile,
+        transforms,
+    };
+}
+export function resumeMaintenanceRecovery(ctx, scope) {
+    if (!ctx.writable)
+        throw new AknoError('read_only', 'resuming automatic maintenance needs the write handle');
+    if (!recoveryTableAvailable(ctx))
+        return emptyMaintenanceRecoveryStatus();
+    const key = 'profile' in scope ? 'profile' : `transform:${scope.transform}`;
+    const removed = ctx.store.db.prepare('DELETE FROM maintenance_recovery_state WHERE scope_key = ?').run(key);
+    if (removed.changes === 0) {
+        throw new AknoError('not_found', `${recoveryScopeLabel(scope)} is not paused and has no failure streak`);
+    }
+    return maintenanceRecoveryStatus(ctx);
+}
+/** Lower only automatic authority. Audit/review runs remain available while recovery is pending. */
+export function configWithMaintenanceRecovery(config, status, mode) {
+    if (mode !== 'auto')
+        return config;
+    const paused = status.transforms
+        .filter((entry) => entry.pausedAt !== null && entry.transform !== null)
+        .map((entry) => entry.transform);
+    if (paused.length === 0)
+        return config;
+    const policies = { ...config.maintenance.policies };
+    for (const transform of paused)
+        policies[transform] = 'off';
+    return { ...config, maintenance: { ...config.maintenance, policies } };
+}
+export function assertProfileAutomaticApplyAvailable(status, mode) {
+    if (mode !== 'auto' || !status.profile)
+        return;
+    throw new AknoError('conflict', 'automatic maintenance is paused because Akno could not prove a safe apply state; inspect status and recovery plans, then run `akno dream resume --profile`', { maintenance_pause: 'profile', reason: status.profile.reason });
+}
+export function recordMaintenanceRecovery(ctx, input) {
+    if (!ctx.writable || !recoveryTableAvailable(ctx))
+        return maintenanceRecoveryStatus(ctx);
+    const now = new Date().toISOString();
+    const rollbacks = new Map();
+    const successes = new Set();
+    let profileReason = verificationPauseReason(input.verification);
+    ctx.store.transaction(() => {
+        for (const planId of new Set(input.planIds)) {
+            const plan = ctx.store.db
+                .prepare('SELECT 1 AS present FROM maintenance_plans WHERE id = ?')
+                .get(planId);
+            if (!plan) {
+                profileReason ??= 'plan_store_unavailable';
+                continue;
+            }
+            const items = ctx.store.db
+                .prepare(`SELECT id, kind, status, verification FROM maintenance_items
+            WHERE plan_id = ? AND recovery_recorded_at IS NULL
+              AND status IN ('applied', 'verification_failed')
+            ORDER BY ord, rowid`)
+                .all(planId);
+            for (const item of items) {
+                const transform = maintenanceTransform(item.kind);
+                const verificationStatus = storedVerificationStatus(item.verification);
+                if (item.status === 'verification_failed') {
+                    if (verificationStatus === 'rolled_back' && transform && input.mode === 'auto') {
+                        rollbacks.set(transform, (rollbacks.get(transform) ?? 0) + 1);
+                    }
+                    else if (verificationStatus === 'failed') {
+                        profileReason ??= 'live_bytes_uncertain';
+                    }
+                }
+                else if (transform && verificationStatus === 'passed' && input.mode === 'auto') {
+                    successes.add(transform);
+                }
+                ctx.store.db
+                    .prepare('UPDATE maintenance_items SET recovery_recorded_at = ? WHERE id = ?')
+                    .run(now, item.id);
+            }
+        }
+        for (const transform of MAINTENANCE_TRANSFORMS) {
+            const failures = rollbacks.get(transform) ?? 0;
+            if (failures > 0) {
+                recordRollbackFailures(ctx, transform, failures, input.runId, now);
+            }
+            else if (successes.has(transform)) {
+                clearUnpausedTransformStreak(ctx, transform);
+            }
+        }
+        if (profileReason)
+            pauseProfile(ctx, profileReason, input.runId, now);
+    });
+    return maintenanceRecoveryStatus(ctx);
+}
+function recordRollbackFailures(ctx, transform, failures, runId, now) {
+    const key = `transform:${transform}`;
+    const existing = ctx.store.db
+        .prepare('SELECT consecutive_failures, paused_at FROM maintenance_recovery_state WHERE scope_key = ?')
+        .get(key);
+    const consecutive = (existing?.consecutive_failures ?? 0) + failures;
+    const pausedAt = existing?.paused_at ?? (consecutive >= MAINTENANCE_ROLLBACK_PAUSE_THRESHOLD ? now : null);
+    ctx.store.db
+        .prepare(`INSERT INTO maintenance_recovery_state
+        (scope_key, scope, transform, reason_code, consecutive_failures, paused_at,
+         last_failure_at, last_run_id, updated_at)
+       VALUES (?, 'transform', ?, 'rollback_threshold', ?, ?, ?, ?, ?)
+       ON CONFLICT(scope_key) DO UPDATE SET
+         reason_code = excluded.reason_code,
+         consecutive_failures = excluded.consecutive_failures,
+         paused_at = excluded.paused_at,
+         last_failure_at = excluded.last_failure_at,
+         last_run_id = excluded.last_run_id,
+         updated_at = excluded.updated_at`)
+        .run(key, transform, consecutive, pausedAt, now, runId, now);
+}
+function clearUnpausedTransformStreak(ctx, transform) {
+    ctx.store.db
+        .prepare(`DELETE FROM maintenance_recovery_state
+        WHERE scope_key = ? AND scope = 'transform' AND paused_at IS NULL`)
+        .run(`transform:${transform}`);
+}
+function pauseProfile(ctx, reason, runId, now) {
+    ctx.store.db
+        .prepare(`INSERT INTO maintenance_recovery_state
+        (scope_key, scope, transform, reason_code, consecutive_failures, paused_at,
+         last_failure_at, last_run_id, updated_at)
+       VALUES ('profile', 'profile', NULL, ?, 1, ?, ?, ?, ?)
+       ON CONFLICT(scope_key) DO UPDATE SET
+         reason_code = excluded.reason_code,
+         consecutive_failures = CASE
+           WHEN maintenance_recovery_state.last_run_id = excluded.last_run_id
+             THEN maintenance_recovery_state.consecutive_failures
+           ELSE maintenance_recovery_state.consecutive_failures + 1
+         END,
+         paused_at = coalesce(maintenance_recovery_state.paused_at, excluded.paused_at),
+         last_failure_at = excluded.last_failure_at,
+         last_run_id = excluded.last_run_id,
+         updated_at = excluded.updated_at`)
+        .run(reason, now, now, runId, now);
+}
+function verificationPauseReason(verification) {
+    if (!verification)
+        return null;
+    const codes = new Set(verification.issues.map((issue) => issue.code));
+    if (codes.has('plan_unavailable'))
+        return 'plan_store_unavailable';
+    if (codes.has('missing_change_id'))
+        return 'journal_receipt_missing';
+    if (codes.has('affected_path_mismatch') || codes.has('snapshot_scan_failed')) {
+        return 'verification_unproven';
+    }
+    return null;
+}
+function recoveryEntry(row) {
+    const transform = row.transform ? maintenanceTransform(row.transform) : null;
+    if (row.scope === 'transform' && !transform)
+        return null;
+    return {
+        scope: row.scope,
+        transform,
+        reason: row.reason_code,
+        consecutiveFailures: row.consecutive_failures,
+        pausedAt: row.paused_at,
+        lastFailureAt: row.last_failure_at,
+        lastRunId: row.last_run_id,
+        recoveryCommand: row.paused_at === null
+            ? null
+            : row.scope === 'profile'
+                ? 'akno dream resume --profile'
+                : `akno dream resume --transform ${transform}`,
+    };
+}
+function storedVerificationStatus(value) {
+    if (!value)
+        return null;
+    try {
+        const parsed = JSON.parse(value);
+        return typeof parsed.status === 'string' ? parsed.status : null;
+    }
+    catch {
+        return null;
+    }
+}
+function maintenanceTransform(value) {
+    return MAINTENANCE_TRANSFORMS.includes(value)
+        ? value
+        : null;
+}
+function recoveryScopeLabel(scope) {
+    return 'profile' in scope ? 'the maintenance profile' : `${scope.transform} maintenance`;
+}
+function recoveryTableAvailable(ctx) {
+    return Boolean(ctx.store.db
+        .prepare("SELECT 1 AS present FROM sqlite_master WHERE type = 'table' AND name = ?")
+        .get('maintenance_recovery_state'));
+}
+function emptyMaintenanceRecoveryStatus() {
+    return { automaticApply: 'available', profile: null, transforms: [] };
+}
+//# sourceMappingURL=recovery.js.map

package/dist/maintenance/recovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery.js","sourceRoot":"","sources":["../../src/maintenance/recovery.ts"],"names":[],"mappings":"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"}

package/dist/maintenance/repair.d.ts

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+import type { AknoContext } from '../context.ts';
+import type { CrossPageConflict } from './conflicts.ts';
+/**
+ * Similarity-only candidates for explaining why a broken link was declined.
+ *
+ * These candidates never authorize a write. Plan-backed link repair requires an exact alias,
+ * canonical identity, or recorded move; resemblance is useful diagnostic context, not identity.
+ */
+export declare function candidatesFor(target: string, slugs: string[]): string[];
+export declare const REWRITE_SCHEMA: z.ZodObject<{
+    line: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Turn a superseded claim into a past-tense one.
+ *
+ * The sentence is what makes a fact: the deriver reads the file, so a fact marked stale only in the
+ * database is live again the next time its page is indexed. Rewriting the line is therefore the only
+ * durable way to say "this was true once" — and it is also the least destructive, because the claim
+ * and its value are still on the page for anyone reading it.
+ */
+declare function rewriteAsHistory(ctx: AknoContext, stale: string, current: string, boundary?: string): Promise<string | null>;
+/**
+ * Whether a rewrite kept the numbers it was told to keep.
+ *
+ * The guard that matters. Changing the tense of a claim is a tidy-up; changing its value is the
+ * model quietly deciding what is true about somebody's rent, and no verdict is worth that. Every
+ * number in the original must survive into the rewrite.
+ */
+export declare function preservesValues(before: string, after: string): boolean;
+export declare function preservesAuthoredTokens(before: string, after: string): boolean;
+/** The exact tokens behind `preservesValues`, for guardrail diagnostics and audit logs. */
+export declare function missingNumericValues(before: string, after: string): string[];
+/** Conflicts worth acting on: judged real, with a claim the model named as current. */
+export declare function actionable(conflicts: CrossPageConflict[]): CrossPageConflict[];
+export { rewriteAsHistory as rewriteAsHistoryForTesting };
+//# sourceMappingURL=repair.d.ts.map

package/dist/maintenance/repair.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repair.d.ts","sourceRoot":"","sources":["../../src/maintenance/repair.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAExD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAiBvE;AAsCD,eAAO,MAAM,cAAc;;iBAA4C,CAAC;AAExE;;;;;;;GAOG;AACH,iBAAe,gBAAgB,CAC7B,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAwBxB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAEtE;AAoCD,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAE9E;AAED,2FAA2F;AAC3F,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAI5E;AA6CD,uFAAuF;AACvF,wBAAgB,UAAU,CAAC,SAAS,EAAE,iBAAiB,EAAE,GAAG,iBAAiB,EAAE,CAI9E;AAED,OAAO,EAAE,gBAAgB,IAAI,0BAA0B,EAAE,CAAC"}

package/dist/maintenance/repair.js

@@ -0,0 +1,183 @@
+import { z } from 'zod';
+import { parseJsonLoose } from "../models/client.js";
+/**
+ * Similarity-only candidates for explaining why a broken link was declined.
+ *
+ * These candidates never authorize a write. Plan-backed link repair requires an exact alias,
+ * canonical identity, or recorded move; resemblance is useful diagnostic context, not identity.
+ */
+export function candidatesFor(target, slugs) {
+    const wanted = tokens(target);
+    if (wanted.length === 0)
+        return [];
+    // A one-word link — `[[Boiler]]` — is matched only against a page whose own last segment is that
+    // word. Coverage would let it match anything containing it, and one word is not an
+    // identification: `[[passport]]` on its own could be anybody's.
+    if (wanted.length === 1) {
+        const only = wanted[0];
+        return slugs.filter((slug) => tokens(slug.split('/').pop() ?? slug).join('') === only);
+    }
+    return slugs.filter((slug) => {
+        const has = new Set(tokens(slug));
+        const covered = wanted.filter((token) => has.has(token)).length;
+        return covered / wanted.length >= 0.75;
+    });
+}
+/**
+ * The words of a slug, path included.
+ *
+ * The path matters, which is the whole trick. `personal/residence-permit-ada-marlow` and
+ * `ada-marlow/residence-permit` are one page reorganised: every word survives the move, only its
+ * position changed. Compare last segments alone and the two look unrelated; compare whole slugs and
+ * they are four words out of five.
+ *
+ * It is also what keeps the dangerous case out. `bo-winters/spare-travel-passport`
+ * against a page called `ada-marlow/passport` shares one word in five — a different person's
+ * document, which an earlier version repointed with full confidence because `passport` was a
+ * substring. Found on a dry run, before it touched anything.
+ */
+function tokens(slug) {
+    return slug
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((token) => token.length > 1);
+}
+const REWRITE_STALE = `A personal knowledge base holds two claims about the same thing, and one of them is no longer
+current. You are given the sentence that is out of date, the claim that replaced it, and the exact effective
+date established by that current claim.
+
+Rewrite the out-of-date sentence so it reads as history rather than as a current fact. Reply with JSON only:
+
+{"line": "the rewritten sentence"}
+
+Rules:
+- Keep every number, name and date exactly as it appears. You are changing the tense, not the value.
+- State explicitly that the old claim applied before the supplied effective date. Copy that date exactly.
+- Do not add any other number or date.
+- Keep the sentence's own formatting: if it starts with "- " or "**Rent:**", keep that.
+- One line. Never add a second sentence, and never add anything that was not already known.
+- If the sentence cannot be rewritten without changing what it says, reply {"line": null}.`;
+export const REWRITE_SCHEMA = z.object({ line: z.string().nullable() });
+/**
+ * Turn a superseded claim into a past-tense one.
+ *
+ * The sentence is what makes a fact: the deriver reads the file, so a fact marked stale only in the
+ * database is live again the next time its page is indexed. Rewriting the line is therefore the only
+ * durable way to say "this was true once" — and it is also the least destructive, because the claim
+ * and its value are still on the page for anyone reading it.
+ */
+async function rewriteAsHistory(ctx, stale, current, boundary) {
+    if (!ctx.models.derive.available)
+        return null;
+    const result = await ctx.models.derive.chat([
+        { role: 'system', content: REWRITE_STALE },
+        {
+            role: 'user',
+            content: `Out of date:\n${stale}\n\nReplaced by:\n${current}` +
+                (boundary ? `\n\nEffective date:\n${boundary}` : ''),
+        },
+    ], { schema: REWRITE_SCHEMA, maxTokens: 300 });
+    if (!result.ok || !result.value)
+        return null;
+    const parsed = parseJsonLoose(result.value);
+    if (!parsed || (typeof parsed.line !== 'string' && parsed.line !== null)) {
+        ctx.models.derive.reportInvalidResponse();
+        return null;
+    }
+    const line = typeof parsed?.line === 'string' ? parsed.line.trim() : '';
+    if (!line || line.includes('\n'))
+        return null;
+    return line;
+}
+/**
+ * Whether a rewrite kept the numbers it was told to keep.
+ *
+ * The guard that matters. Changing the tense of a claim is a tidy-up; changing its value is the
+ * model quietly deciding what is true about somebody's rent, and no verdict is worth that. Every
+ * number in the original must survive into the rewrite.
+ */
+export function preservesValues(before, after) {
+    return missingNumericValues(before, after).length === 0;
+}
+/**
+ * A history rewrite may change grammar, but it may not silently rename a subject, place, product,
+ * or other authored content. Common glue words are excluded so adding "Previously" and changing
+ * "is" to "was" remains possible; every meaningful alphanumeric token must survive.
+ */
+function missingAuthoredTokens(before, after) {
+    const ignored = new Set([
+        'and',
+        'are',
+        'been',
+        'for',
+        'from',
+        'has',
+        'have',
+        'into',
+        'is',
+        'its',
+        'of',
+        'on',
+        'the',
+        'to',
+        'was',
+        'were',
+        'with',
+    ]);
+    const authoredTokens = (value) => value
+        .toLowerCase()
+        .match(/[\p{L}\p{N}]+/gu)
+        ?.filter((token) => token.length >= 3 && !ignored.has(token)) ?? [];
+    const present = new Set(authoredTokens(after));
+    return [...new Set(authoredTokens(before).filter((token) => !present.has(token)))];
+}
+export function preservesAuthoredTokens(before, after) {
+    return missingAuthoredTokens(before, after).length === 0;
+}
+/** The exact tokens behind `preservesValues`, for guardrail diagnostics and audit logs. */
+export function missingNumericValues(before, after) {
+    const afterValues = new Set(numericValues(after).map((value) => value.canonical));
+    const missing = numericValues(before).filter((value) => !afterValues.has(value.canonical));
+    return [...new Set(missing.map((value) => value.raw))];
+}
+/**
+ * Values, not punctuation that happens to follow them.
+ *
+ * The old digit-and-punctuation regex included the comma in `1902,` and the full stop in `25.`. A model
+ * moving that value to the middle of a sentence was therefore treated like one deleting it.
+ * Composite dates, times and ranges are captured first so harmless separator and leading-zero
+ * changes compare semantically rather than as typography.
+ */
+function numericValues(text) {
+    const pattern = /\d{4}[-/]\d{1,2}[-/]\d{1,2}|\d{1,2}:\d{2}|\d+(?:[.,]\d+)*(?:\s*[\u2013\u2014-]\s*\d+(?:[.,]\d+)*)?/g;
+    return [...text.matchAll(pattern)].map((match) => ({
+        raw: match[0],
+        canonical: canonicalNumericValue(match[0]),
+    }));
+}
+function canonicalNumericValue(raw) {
+    const compact = raw.replace(/\s+/g, '').replace(/[\u2013\u2014]/g, '-');
+    if (/^\d{4}[-/]\d{1,2}[-/]\d{1,2}$/.test(compact)) {
+        const [year, month, day] = compact.split(/[-/]/);
+        return `${year}-${Number(month)}-${Number(day)}`;
+    }
+    if (/^\d{1,2}:\d{2}$/.test(compact)) {
+        const [hour, minute] = compact.split(':');
+        return `${Number(hour)}:${minute}`;
+    }
+    const range = /^(.*?)-(.*)$/.exec(compact);
+    if (range)
+        return `${canonicalNumber(range[1])}-${canonicalNumber(range[2])}`;
+    return canonicalNumber(compact);
+}
+function canonicalNumber(value) {
+    // A comma followed by groups of exactly three digits is a thousands separator. A decimal
+    // comma remains significant, as does a decimal point.
+    return /^\d{1,3}(?:,\d{3})+$/.test(value) ? value.replaceAll(',', '') : value;
+}
+/** Conflicts worth acting on: judged real, with a claim the model named as current. */
+export function actionable(conflicts) {
+    return conflicts.filter((conflict) => conflict.verdict === 'superseded' && conflict.likelyCurrent && conflict.claims.length >= 2);
+}
+export { rewriteAsHistory as rewriteAsHistoryForTesting };
+//# sourceMappingURL=repair.js.map

package/dist/maintenance/repair.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repair.js","sourceRoot":"","sources":["../../src/maintenance/repair.ts"],"names":[],"mappings":"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"}

package/dist/maintenance/rule-drift.d.ts

@@ -0,0 +1,104 @@
+import type { AknoContext } from '../context.ts';
+interface RuleDriftBase {
+    kind: 'rule_drift';
+    slug: string;
+    relPath: string;
+    inputHash: string;
+    ruleGlob: string;
+    ruleFingerprint: string;
+}
+interface TypeRuleDriftDraft extends RuleDriftBase {
+    correction: 'type';
+    before: string;
+    after: string;
+    expectedType: string;
+    foundType: string;
+}
+interface DepthRuleDriftDraft extends RuleDriftBase {
+    correction: 'max_depth';
+    before: string;
+    sourceAfter: string;
+    pageId: string;
+    maxDepth: number;
+    foundDepth: number;
+    relocateTo: string;
+    destinationSlug: string;
+    destinationRelPath: string;
+    documents: RuleDriftDocumentMove[];
+    inbound: {
+        slug: string;
+        relPath: string;
+        before: string;
+        after: string;
+        rewriteAbout: boolean;
+        rewriteLinks: boolean;
+    }[];
+}
+export interface RuleDriftDocumentMove {
+    id: string;
+    relPath: string;
+    destinationRelPath: string;
+    hash: string;
+    renders: string | null;
+    destinationRenders: string | null;
+    groupKey: string | null;
+    destinationGroupKey: string | null;
+}
+export type RuleDriftDraft = TypeRuleDriftDraft | DepthRuleDriftDraft;
+interface RuleDriftCandidateBase {
+    pageId: string;
+    slug: string;
+    relPath: string;
+    role: string;
+    ruleGlob: string;
+}
+export type RuleDriftCandidate = RuleDriftCandidateBase & ({
+    field: 'type';
+    expectedType: string;
+    foundType: string;
+} | {
+    field: 'slug_pattern';
+} | {
+    field: 'max_depth';
+    maxDepth: number;
+    foundDepth: number;
+});
+export type RuleRepairAssessment = {
+    status: 'ready';
+    code: 'exact_type' | 'exact_relocation';
+    reason: string;
+} | {
+    status: 'report_only';
+    code: 'slug_has_no_exact_repair' | 'relocation_not_declared';
+    reason: string;
+} | {
+    status: 'held';
+    code: 'role_not_knowledge' | 'policy_off' | 'planner_limit_zero' | 'reserved_source' | 'source_unreadable' | 'type_not_scalar' | 'relocation_rule_invalid' | 'destination_unsafe' | 'destination_occupied' | 'destination_not_knowledge' | 'destination_rule_conflict' | 'location_dependent_reference' | 'document_unavailable' | 'document_unreadable' | 'document_changed' | 'document_destination_occupied' | 'document_destination_conflict' | 'document_relationship_unsafe' | 'reference_about' | 'about_unreadable' | 'about_unrewritable' | 'reference_backlink' | 'backlink_unreadable' | 'backlink_unrewritable';
+    reason: string;
+};
+export interface RuleRepairPreparation {
+    assessment: RuleRepairAssessment;
+    draft: RuleDriftDraft | null;
+}
+/** Every path whose bytes or identity one sealed rule repair owns. */
+export declare function ruleDriftPaths(draft: RuleDriftDraft): string[];
+/**
+ * Plan only drift with one exact correction. An explicit `type` has one exact scalar replacement.
+ * An over-deep page has one exact destination only when the same rule also declares `relocate_to`.
+ * Source pages are excluded: reference material is searchable evidence, not autonomous rewrite scope.
+ */
+export declare function planRuleDrifts(ctx: AknoContext, options: {
+    limit: number;
+}): Promise<RuleDriftDraft[]>;
+/** Shared deterministic analysis used by both planning and housekeeping explanations. */
+export declare function prepareRuleRepair(ctx: AknoContext, candidate: RuleDriftCandidate): Promise<RuleRepairPreparation>;
+/** Preserve source-page link meaning while its folder changes, without interpreting prose. */
+export declare function rewriteRelocatedPageReferences(content: string, fromSlug: string, toSlug: string, documents: Pick<RuleDriftDocumentMove, 'relPath' | 'destinationRelPath'>[]): {
+    after: string;
+} | {
+    issue: string;
+};
+/** Losslessly retarget page links, retaining aliases, fragments, labels, and titles. */
+export declare function rewritePageLinks(text: string, fromPage: string, oldSlug: string, newSlug: string): string;
+export {};
+//# sourceMappingURL=rule-drift.d.ts.map

package/dist/maintenance/rule-drift.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-drift.d.ts","sourceRoot":"","sources":["../../src/maintenance/rule-drift.ts"],"names":[],"mappings":"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"}