@tenphi/akno-core 0.1.0

package/dist/write/journal.js

@@ -0,0 +1,187 @@
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { AknoError } from '@tenphi/akno-protocol';
+import { newPrefixedId } from "../store/ids.js";
+import { restoreFile } from "./atomic.js";
+export class Journal {
+    #store;
+    #aknoPath;
+    #trashDir;
+    constructor(store, aknoPath, trashDir) {
+        this.#store = store;
+        this.#aknoPath = aknoPath;
+        this.#trashDir = trashDir;
+    }
+    /**
+     * Records a change that has already been applied to disk. Deliberately after
+     * the fact: a journal entry for a write that then failed is a lie in the one
+     * table that has to be trustworthy, and the failure mode of recording late (a
+     * crash between write and journal leaves an un-undoable change) is both rarer
+     * and far less confusing than the reverse.
+     */
+    record(input) {
+        const changeId = newPrefixedId('chg');
+        const now = new Date().toISOString();
+        this.#store.transaction(() => {
+            this.#store.db
+                .prepare('INSERT INTO changes(id, at, actor, op, summary, status) VALUES(?, ?, ?, ?, ?, ?)')
+                .run(changeId, now, input.actor, input.op, input.summary, 'applied');
+            const insert = this.#store.db.prepare(`INSERT INTO change_files(change_id, ord, rel_path, action, before, after, snapshot, moved_to)
+         VALUES(?, ?, ?, ?, ?, ?, ?, ?)`);
+            input.files.forEach((file, index) => {
+                insert.run(changeId, index, file.relPath, file.action, file.before, file.after, file.snapshot ?? null, file.movedTo ?? null);
+            });
+        });
+        return changeId;
+    }
+    /**
+     * Reverses a change: every file back to its previous bytes, in reverse order.
+     *
+     * Reverse order matters for a move — the change created the destination and
+     * deleted the source, so undoing destination-first leaves the source free to be
+     * recreated. Forward order would try to recreate the source while the
+     * destination still holds it.
+     */
+    async undo(changeId) {
+        const change = this.#store.db.prepare('SELECT * FROM changes WHERE id = ?').get(changeId);
+        if (!change)
+            throw new AknoError('not_found', `no change with id ${changeId}`);
+        if (change.status === 'undone') {
+            throw new AknoError('invalid', `${changeId} has already been undone`);
+        }
+        const files = this.#store.db
+            .prepare('SELECT * FROM change_files WHERE change_id = ? ORDER BY ord DESC')
+            .all(changeId);
+        const restored = [];
+        const removed = [];
+        const reversedMoves = [];
+        for (const file of files) {
+            if (file.moved_to) {
+                // The change was a rename, so its reversal is the rename back. Nothing was created
+                // and nothing was destroyed, which is why this case cannot go through `restoreFile`.
+                const from = path.join(this.#aknoPath, file.moved_to);
+                const target = path.join(this.#aknoPath, file.rel_path);
+                await fsp.mkdir(path.dirname(target), { recursive: true });
+                let reversed = true;
+                await fsp.rename(from, target).catch(async (err) => {
+                    // Already gone is not a reason to abandon the rest of the reversal — the file was
+                    // moved again, or removed, since. Everything else still goes back.
+                    if (err.code !== 'ENOENT')
+                        throw err;
+                    reversed = false;
+                });
+                if (reversed)
+                    reversedMoves.push({ from: file.moved_to, to: file.rel_path });
+                restored.push(file.rel_path);
+                continue;
+            }
+            if (file.snapshot) {
+                // A binary: the bytes are in trash, not in the journal.
+                const source = path.join(this.#trashDir, file.snapshot);
+                const target = path.join(this.#aknoPath, file.rel_path);
+                await fsp.mkdir(path.dirname(target), { recursive: true });
+                await fsp.copyFile(source, target);
+            }
+            else {
+                await restoreFile(this.#aknoPath, file.rel_path, file.before);
+            }
+            // No prior content and no snapshot means the change created this file, so putting it
+            // back is deleting it. Two opposite outcomes reported under one word is one of them
+            // being reported wrongly.
+            if (!file.snapshot && file.before === null)
+                removed.push(file.rel_path);
+            else
+                restored.push(file.rel_path);
+        }
+        // A document row carries retained extraction and provenance that a structural re-index cannot
+        // always reproduce without another model call. Follow successful attachment renames back before
+        // the scanner runs, just as the forward move follows them, rather than deleting and recreating
+        // the row from its content-derived id.
+        if (reversedMoves.length > 0) {
+            this.#store.transaction(() => {
+                const moveDocument = this.#store.db.prepare('UPDATE OR IGNORE documents SET rel_path = ? WHERE rel_path = ?');
+                const moveRenders = this.#store.db.prepare('UPDATE documents SET renders = ? WHERE renders = ?');
+                const moveGroup = this.#store.db.prepare('UPDATE documents SET group_key = ? WHERE group_key = ?');
+                for (const move of reversedMoves)
+                    moveDocument.run(move.to, move.from);
+                for (const move of reversedMoves) {
+                    moveRenders.run(move.to, move.from);
+                    moveGroup.run(move.to, move.from);
+                }
+            });
+        }
+        this.#store.db
+            .prepare("UPDATE changes SET status = 'undone', undone_at = ? WHERE id = ?")
+            .run(new Date().toISOString(), changeId);
+        return { restored, removed, summary: change.summary };
+    }
+    list(limit = 20) {
+        // By rowid, not by `at`: two changes in the same millisecond have identical
+        // timestamps, and "the most recent change" then depends on SQLite's scan order.
+        // `undo --list` showing them out of order is how you undo the wrong one.
+        const rows = this.#store.db.prepare('SELECT * FROM changes ORDER BY rowid DESC LIMIT ?').all(limit);
+        const filesFor = this.#store.db.prepare('SELECT rel_path, action FROM change_files WHERE change_id = ? ORDER BY ord');
+        return rows.map((row) => ({
+            ...row,
+            files: filesFor.all(row.id).map((file) => ({
+                relPath: file.rel_path,
+                action: file.action,
+            })),
+        }));
+    }
+    /**
+     * Moves a file into `trash/<change>/` and returns the snapshot path:
+     * `forget({slug})` moves a whole page to trash and stays undoable for the
+     * retention window — deleting outright would make "reversible" a lie.
+     */
+    async trash(relPath, changeToken) {
+        const snapshot = path.join(changeToken, relPath);
+        const target = path.join(this.#trashDir, snapshot);
+        await fsp.mkdir(path.dirname(target), { recursive: true });
+        await fsp.rename(path.join(this.#aknoPath, relPath), target).catch(async (err) => {
+            // A rename across devices fails; trash may sit on a different volume.
+            if (err.code !== 'EXDEV')
+                throw err;
+            await fsp.copyFile(path.join(this.#aknoPath, relPath), target);
+            await fsp.rm(path.join(this.#aknoPath, relPath));
+        });
+        return snapshot;
+    }
+    /**
+     * Drops trashed files past the retention window. Called from the maintenance
+     * path, never from a write — a delete that also expires somebody else's older
+     * delete is a surprise nobody asked for.
+     */
+    async expireTrash(retentionDays) {
+        if (retentionDays <= 0)
+            return 0;
+        const cutoff = Date.now() - retentionDays * 86_400_000;
+        let removed = 0;
+        let entries;
+        try {
+            entries = await fsp.readdir(this.#trashDir);
+        }
+        catch {
+            return 0;
+        }
+        for (const entry of entries) {
+            const abs = path.join(this.#trashDir, entry);
+            const stat = await fsp.stat(abs).catch(() => null);
+            if (!stat || stat.mtimeMs > cutoff)
+                continue;
+            await fsp.rm(abs, { recursive: true, force: true });
+            removed++;
+        }
+        return removed;
+    }
+}
+/** Convenience: turn an atomic write result into the journal's shape. */
+export function fileEntry(result) {
+    return {
+        relPath: result.relPath,
+        action: result.created ? 'created' : 'modified',
+        before: result.before,
+        after: result.after,
+    };
+}
+//# sourceMappingURL=journal.js.map

package/dist/write/journal.js.map

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

package/dist/write/ledger.d.ts

@@ -0,0 +1,28 @@
+export interface LedgerEvent {
+    date: string;
+    summary: string;
+    /** The page holding the detail. Plenty of events will never have one. */
+    slug?: string | null;
+}
+export interface LedgerInsert {
+    content: string;
+    /** 1-based line the new event landed on, so it can be cited as `timeline:47`. */
+    line: number;
+}
+export declare function formatEventLine(event: LedgerEvent): string;
+/**
+ * Inserts an event under its year heading, creating the heading if the year is new.
+ *
+ * Placement within a year is newest-first, but only among lines Akno can read as
+ * events — an unparseable line a human wrote is stepped over, never reordered
+ * around. If the year heading is absent it is added in the right place among the
+ * other year headings, so a ledger stays readable without anything being rewritten.
+ */
+export declare function insertEvent(content: string, event: LedgerEvent): LedgerInsert;
+/**
+ * The header a ledger gets when a write has to create it. Startup creates this on
+ * startup only when asked; an event write creates it because the caller asked for
+ * an event and there is nowhere else to put it.
+ */
+export declare function newLedger(year: string): string;
+//# sourceMappingURL=ledger.d.ts.map

package/dist/write/ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.d.ts","sourceRoot":"","sources":["../../src/write/ledger.ts"],"names":[],"mappings":"AA0BA,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;CACd;AAKD,wBAAgB,eAAe,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAM1D;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,YAAY,CAiF7E;AASD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAU9C"}

package/dist/write/ledger.js

@@ -0,0 +1,141 @@
+/**
+ * The event ledger.
+ *
+ * **The ledger is a source file, not a rendered view.** Generating it from the
+ * events index would always be tidy and correctly sorted, and it is rejected: a
+ * rendered file silently discards hand edits, and the whole point of a Markdown
+ * knowledge base is that hand edits are legitimate.
+ *
+ * So Akno maintains it **by appending only** — inserting under the right year
+ * heading and never rewriting or reordering what is already there. No edit a human
+ * made can be lost, and a hand-written line is indexed exactly like a generated
+ * one. Automatic upkeep without the destructive part.
+ *
+ * Nothing about this line syntax ever reaches a prompt: there is no
+ * `add_event` op). A caller hands over `{date, summary}`.
+ */
+import { saysTheSame } from "../kb/words.js";
+/** The summary out of a formatted event line, without the date marker or the citation. */
+function summaryOf(line) {
+    return line
+        .replace(EVENT_DATE, '')
+        .replace(/\[\[[^\]]*\]\]/g, '')
+        .trim();
+}
+/** The same shape the indexer matches, used here to read dates already in place. */
+const EVENT_DATE = /^\s*[-*]\s+\*\*(\d{4}-\d{2}-\d{2})\*\*\s*\|/;
+export function formatEventLine(event) {
+    const summary = event.summary.trim().replace(/\s+/g, ' ');
+    const link = event.slug ? ` [[${event.slug}]]` : '';
+    // The bold date and the `|` are what make a line an event: the indexer matches
+    // that exact shape, and prose it cannot match is invisible to search.
+    return `- **${event.date}** | ${summary}${link}`;
+}
+/**
+ * Inserts an event under its year heading, creating the heading if the year is new.
+ *
+ * Placement within a year is newest-first, but only among lines Akno can read as
+ * events — an unparseable line a human wrote is stepped over, never reordered
+ * around. If the year heading is absent it is added in the right place among the
+ * other year headings, so a ledger stays readable without anything being rewritten.
+ */
+export function insertEvent(content, event) {
+    const line = formatEventLine(event);
+    const lines = content.length === 0 ? [] : content.replace(/\n$/, '').split('\n');
+    const year = event.date.slice(0, 4);
+    // Already present, byte for byte: appending it twice is not append-only upkeep,
+    // it is duplication. The index collapses duplicates; this avoids making
+    // one in the file.
+    const existing = lines.indexOf(line);
+    if (existing !== -1)
+        return { content, line: existing + 1 };
+    // Already present in different words. Two callers describing one day's event will not agree on
+    // the wording — `They watched "Wicked: For Good"` and `The user watched "Wicked: For Good"` are
+    // one event and two strings, and the byte comparison above sees only the strings.
+    //
+    // Scoped to the date, which is what makes it safe: a ledger is full of events that resemble each
+    // other across days — a weekly delivery, a monthly payment — and those are genuinely separate
+    // things that happened. Two similar summaries on *one* day are almost always one thing described
+    // twice.
+    const sameDay = lines.findIndex((text) => {
+        const date = EVENT_DATE.exec(text)?.[1];
+        if (date !== event.date)
+            return false;
+        // A shared subject, place and date are not enough: scheduling something and later doing it
+        // are separate events whose nouns can overlap heavily. The default 0.7 containment boundary
+        // collapsed exactly that transition. Ledger deduplication is intentionally stricter because
+        // an extra line is visible and repairable, while a missing completion event is silent loss.
+        return saysTheSame(summaryOf(text), event.summary, 0.8);
+    });
+    if (sameDay !== -1)
+        return { content, line: sameDay + 1 };
+    const headings = lines
+        .map((text, index) => ({ text, index, year: /^##\s+(\d{4})\s*$/.exec(text)?.[1] }))
+        .filter((entry) => Boolean(entry.year));
+    const target = headings.find((heading) => heading.year === year);
+    if (target) {
+        // The block ends at the next heading, but its *content* ends before the blank
+        // line that separates the years. Inserting after that blank puts the line under
+        // the next year's heading as far as any reader is concerned.
+        const nextHeading = nextHeadingIndex(lines, target.index);
+        let blockEnd = nextHeading;
+        while (blockEnd > target.index + 1 && lines[blockEnd - 1].trim().length === 0)
+            blockEnd--;
+        let at = target.index + 1;
+        while (at < blockEnd && lines[at].trim().length === 0)
+            at++;
+        // Newest first, by date, among the lines Akno can read as events. A
+        // backdated entry — last week's appointment recorded today — belongs below
+        // the newer ones, and putting it at the top would make the ledger wrong in a
+        // way nobody notices until they read it.
+        //
+        // Still pure insertion: an unparseable line a human wrote is stepped over,
+        // never moved, so "never rewrites or reorders" holds.
+        for (let i = at; i < blockEnd; i++) {
+            const existingDate = EVENT_DATE.exec(lines[i])?.[1];
+            if (existingDate && existingDate < event.date) {
+                at = i;
+                break;
+            }
+            if (i === blockEnd - 1)
+                at = blockEnd;
+        }
+        lines.splice(at, 0, line);
+        return { content: `${lines.join('\n')}\n`, line: at + 1 };
+    }
+    // A new year. Newer years go above older ones, matching newest-first.
+    const laterHeading = headings.find((heading) => heading.year < year);
+    const insertAt = laterHeading ? laterHeading.index : lines.length;
+    const block = [`## ${year}`, line];
+    // Keep one blank line between year blocks, and none at the very top of a file
+    // that is only a header.
+    const needsGapBefore = insertAt > 0 && lines[insertAt - 1].trim().length > 0;
+    const needsGapAfter = insertAt < lines.length;
+    lines.splice(insertAt, 0, ...(needsGapBefore ? [''] : []), ...block, ...(needsGapAfter ? [''] : []));
+    return {
+        content: `${lines.join('\n')}\n`,
+        line: insertAt + (needsGapBefore ? 1 : 0) + 2,
+    };
+}
+function nextHeadingIndex(lines, from) {
+    for (let i = from + 1; i < lines.length; i++) {
+        if (/^##?\s+/.test(lines[i]))
+            return i;
+    }
+    return lines.length;
+}
+/**
+ * The header a ledger gets when a write has to create it. Startup creates this on
+ * startup only when asked; an event write creates it because the caller asked for
+ * an event and there is nowhere else to put it.
+ */
+export function newLedger(year) {
+    return (`---\ntype: timeline\ntitle: Timeline\n---\n\n# Timeline\n\n` +
+        `What actually happened, newest first. One line per event; the detail lives on the linked\n` +
+        `page, so this stays an index and never a second copy of a fact.\n\n` +
+        `Append-only: never edit or remove a line, correct it with a new one. Each line reads\n` +
+        `\`- **YYYY-MM-DD** | what happened. [[page/with/detail]]\` — that exact shape is what\n` +
+        `makes a line an event, and prose Akno cannot match is invisible to search.\n\n` +
+        `## ${year}\n`);
+}
+//# sourceMappingURL=ledger.js.map

package/dist/write/ledger.js.map

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

package/dist/write/placement.d.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import { type ModelClient } from '../models/client.ts';
+export interface ManagedItem {
+    id: string;
+    text: string;
+    source: string;
+    origin: 'user' | 'assistant' | 'unknown';
+}
+export interface PlacementResult {
+    content: string;
+    unsorted: string[];
+    error: string | null;
+}
+/** `id` is checked against the supplied set afterwards — a grammar can require a string
+ *  there, not that it is one of the ids the model was actually given. */
+export declare const PLACEMENT_SCHEMA: z.ZodObject<{
+    placements: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        heading: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * One model call places all managed items bound for a page. The model chooses only section names;
+ * deterministic code performs the edit and preserves every existing byte outside the insertion.
+ */
+export declare function placeManagedItems(content: string, items: ManagedItem[], model: ModelClient): Promise<PlacementResult>;
+/** Return the exact source label that survives the bounded marker encoding. */
+export declare function managedSourceReference(value: string): string;
+//# sourceMappingURL=placement.d.ts.map

package/dist/write/placement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"placement.d.ts","sourceRoot":"","sources":["../../src/write/placement.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvE,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;CAC1C;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAYD;yEACyE;AACzE,eAAO,MAAM,gBAAgB;;;;;iBAE3B,CAAC;AAEH;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,WAAW,EAAE,EACpB,KAAK,EAAE,WAAW,GACjB,OAAO,CAAC,eAAe,CAAC,CA8C1B;AAwCD,+EAA+E;AAC/E,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAS5D"}

package/dist/write/placement.js

@@ -0,0 +1,140 @@
+import { z } from 'zod';
+import { parseFrontmatter } from "../kb/frontmatter.js";
+import { parseJsonLoose } from "../models/client.js";
+const SYSTEM = `You place durable knowledge into one Markdown page.
+
+Reply with JSON only:
+{"placements":[{"id":"exact supplied id","heading":"exact existing ## heading, or a concise new heading"}]}
+
+Choose the most specific semantically correct section for every item. Reuse an existing ## heading
+when one fits. A new heading is allowed when it materially improves the page. Do not rewrite,
+rephrase, merge or omit items. Do not use the title as a heading. Never return "Unsorted"; the
+caller owns that fallback.`;
+/** `id` is checked against the supplied set afterwards — a grammar can require a string
+ *  there, not that it is one of the ids the model was actually given. */
+export const PLACEMENT_SCHEMA = z.object({
+    placements: z.array(z.object({ id: z.string(), heading: z.string() })),
+});
+/**
+ * One model call places all managed items bound for a page. The model chooses only section names;
+ * deterministic code performs the edit and preserves every existing byte outside the insertion.
+ */
+export async function placeManagedItems(content, items, model) {
+    if (items.length === 0)
+        return { content, unsorted: [], error: null };
+    const frontmatter = parseFrontmatter(content);
+    const body = content.slice(frontmatter.bodyOffset);
+    const existing = secondLevelHeadings(body);
+    let chosen = new Map();
+    let error = null;
+    if (model.available) {
+        const result = await model.chat([
+            { role: 'system', content: SYSTEM },
+            {
+                role: 'user',
+                content: `Page:\n${body.slice(0, 24_000)}\n\nExisting ## headings: ${JSON.stringify(existing)}\n\n` +
+                    `Items:\n${JSON.stringify(items.map(({ id, text }) => ({ id, text })))}`,
+            },
+        ], { schema: PLACEMENT_SCHEMA, maxTokens: Math.min(1600, 200 + items.length * 100) });
+        if (result.ok && result.value) {
+            const parsed = parseJsonLoose(result.value);
+            chosen = cleanPlacements(parsed?.placements, new Set(items.map((item) => item.id)));
+            if (chosen.size !== items.length)
+                error = 'placement omitted or invalidated one or more items';
+        }
+        else {
+            error = result.error ?? 'placement failed';
+        }
+    }
+    else {
+        error = model.unavailableReason ?? 'placement model unavailable';
+    }
+    let nextBody = body;
+    const unsorted = [];
+    for (const item of items) {
+        const heading = chosen.get(item.id) ?? 'Unsorted';
+        if (heading === 'Unsorted')
+            unsorted.push(item.id);
+        nextBody = appendManagedBlock(nextBody, heading, managedBlock(item));
+    }
+    return {
+        content: content.slice(0, frontmatter.bodyOffset) + nextBody,
+        unsorted,
+        error,
+    };
+}
+function cleanPlacements(value, itemIds) {
+    const out = new Map();
+    if (!Array.isArray(value))
+        return out;
+    for (const entry of value) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const record = entry;
+        if (typeof record.id !== 'string' || !itemIds.has(record.id) || out.has(record.id))
+            continue;
+        if (typeof record.heading !== 'string')
+            continue;
+        const heading = cleanHeading(record.heading);
+        if (heading)
+            out.set(record.id, heading);
+    }
+    return out;
+}
+function cleanHeading(raw) {
+    const heading = raw
+        .replace(/^#+\s*/, '')
+        .replace(/[\r\n[\]<>]/g, '')
+        .trim();
+    if (heading.length === 0 || heading.length > 80 || heading.toLowerCase() === 'unsorted')
+        return null;
+    return heading;
+}
+function secondLevelHeadings(body) {
+    return body
+        .split('\n')
+        .map((line) => /^##\s+(.+?)\s*$/.exec(line)?.[1]?.trim())
+        .filter((heading) => Boolean(heading));
+}
+function managedBlock(item) {
+    return `<!-- akno:item ${item.id} source=${encodeMarker(item.source)} origin=${item.origin} -->\n${item.text.trim()}`;
+}
+function encodeMarker(value) {
+    return encodeURIComponent(managedSourceReference(value));
+}
+/** Return the exact source label that survives the bounded marker encoding. */
+export function managedSourceReference(value) {
+    const cleaned = value.replace(/-->/g, '') || 'remember';
+    let bounded = '';
+    for (const character of cleaned) {
+        const candidate = bounded + character;
+        if (encodeURIComponent(candidate).length > 300)
+            break;
+        bounded = candidate;
+    }
+    return bounded || 'remember';
+}
+function appendManagedBlock(body, heading, block) {
+    const lines = body.replace(/\s+$/, '').split('\n');
+    const wanted = heading.toLowerCase();
+    const matches = lines
+        .map((line, index) => ({ index, match: /^##\s+(.+?)\s*$/.exec(line) }))
+        .filter((entry) => entry.match?.[1]?.trim().toLowerCase() === wanted);
+    if (matches.length !== 1) {
+        const gap = lines.length === 1 && lines[0] === '' ? [] : ['', ''];
+        return `${[...lines, ...gap, `## ${heading}`, '', block].join('\n').replace(/^\n+/, '')}\n`;
+    }
+    const start = matches[0].index;
+    let end = lines.length;
+    for (let index = start + 1; index < lines.length; index++) {
+        if (/^#{1,2}\s+/.test(lines[index])) {
+            end = index;
+            break;
+        }
+    }
+    while (end > start + 1 && lines[end - 1].trim() === '')
+        end--;
+    lines.splice(end, 0, '', block);
+    return `${lines.join('\n').replace(/\n{3,}/g, '\n\n')}\n`;
+}
+//# sourceMappingURL=placement.js.map

package/dist/write/placement.js.map

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

package/dist/write/remember-fallback.d.ts

@@ -0,0 +1,18 @@
+import type { AknoContext } from '../context.ts';
+import { type FolderCatalogEntry } from '../kb/folders.ts';
+type RememberFallbackUnavailableReason = 'reserved_path' | 'existing_page_not_admitted' | 'unindexed_page_exists' | 'folder_not_admitted';
+export type RememberFallbackResolution = {
+    slug: string;
+    status: 'existing_page' | 'new_page';
+} | {
+    slug: string;
+    status: 'unavailable';
+    reason: RememberFallbackUnavailableReason;
+};
+/**
+ * Resolve the explicit catch-all independently of semantic routing. Configuration names one exact page;
+ * admission still comes from the page or its parent folder, so this option cannot grant itself write authority.
+ */
+export declare function resolveRememberFallback(ctx: AknoContext, catalog?: FolderCatalogEntry[]): Promise<RememberFallbackResolution | null>;
+export {};
+//# sourceMappingURL=remember-fallback.d.ts.map

package/dist/write/remember-fallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remember-fallback.d.ts","sourceRoot":"","sources":["../../src/write/remember-fallback.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAiB,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAG1E,KAAK,iCAAiC,GACpC,eAAe,GAAG,4BAA4B,GAAG,uBAAuB,GAAG,qBAAqB,CAAC;AAEnG,MAAM,MAAM,0BAA0B,GAClC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,eAAe,GAAG,UAAU,CAAA;CAAE,GACtD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,iCAAiC,CAAA;CAAE,CAAC;AAEvF;;;GAGG;AACH,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,WAAW,EAChB,OAAO,GAAE,kBAAkB,EAAyC,GACnE,OAAO,CAAC,0BAA0B,GAAG,IAAI,CAAC,CA8B5C"}

package/dist/write/remember-fallback.js

@@ -0,0 +1,48 @@
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { folderCatalog } from "../kb/folders.js";
+import { isReserved } from "../reserved.js";
+/**
+ * Resolve the explicit catch-all independently of semantic routing. Configuration names one exact page;
+ * admission still comes from the page or its parent folder, so this option cannot grant itself write authority.
+ */
+export async function resolveRememberFallback(ctx, catalog = folderCatalog(ctx.config, ctx.store)) {
+    const slug = ctx.config.maintenance.retain.fallbackPage;
+    if (!slug)
+        return null;
+    if (isReserved(slug, ctx.config))
+        return { slug, status: 'unavailable', reason: 'reserved_path' };
+    const row = ctx.store.db.prepare('SELECT role, remember_management FROM pages WHERE slug = ?').get(slug);
+    if (row) {
+        return row.role === 'knowledge' && row.remember_management === 'integrate'
+            ? { slug, status: 'existing_page' }
+            : { slug, status: 'unavailable', reason: 'existing_page_not_admitted' };
+    }
+    // An indexed page has policy metadata. Existing bytes without an index row do not, and treating them as a
+    // new managed page would overwrite user-authored content before Akno had classified it.
+    if (await fallbackFileExists(ctx, slug)) {
+        return { slug, status: 'unavailable', reason: 'unindexed_page_exists' };
+    }
+    const parent = slug.slice(0, slug.lastIndexOf('/'));
+    const admitted = catalog.some((folder) => folder.path === parent &&
+        folder.role === 'knowledge' &&
+        folder.remember === 'integrate' &&
+        folder.creatable);
+    return admitted
+        ? { slug, status: 'new_page' }
+        : { slug, status: 'unavailable', reason: 'folder_not_admitted' };
+}
+async function fallbackFileExists(ctx, slug) {
+    for (const extension of ctx.config.pageExtensions) {
+        try {
+            if ((await fsp.stat(path.join(ctx.config.aknoPath, `${slug}${extension}`))).isFile())
+                return true;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=remember-fallback.js.map