@tenphi/akno-core 0.1.0

package/dist/kb/page.js

@@ -0,0 +1,243 @@
+import path from 'node:path';
+import { parseFrontmatter, readString, readTags } from "./frontmatter.js";
+import { sha256 } from "../store/ids.js";
+/**
+ * Reserved markers inside a page. This is the complete list — everything
+ * else in a body is prose Akno does not interpret.
+ */
+const SOURCE_FENCE = /^<!--\s*source\s*-->\s*$/i;
+export const AKNO_ITEM = /^\s*<!--\s*akno:item\s+(.+?)\s*-->\s*$/i;
+export function aknoItemId(line) {
+    const match = AKNO_ITEM.exec(line);
+    const id = match?.[1]?.trim().split(/\s+/)[0] ?? null;
+    return id && /^[A-Za-z0-9_-]{4,80}$/.test(id) ? id : null;
+}
+/** `- **2026-06-02** | Renewed the apartment lease. [[home/lease]]` */
+const EVENT_LINE = /^\s*[-*]\s+\*\*(\d{4}-\d{2}-\d{2})\*\*\s*\|\s*(.+?)\s*$/;
+const WIKILINK = /\[\[([^\]|#]+)(?:[#|][^\]]*)?\]\]/g;
+const MARKDOWN_LINK = /\[[^\]]*\]\(([^)\s]+\.md)(?:#[^)]*)?\)/g;
+/** `<page-basename>-<8 hex>.<ext>` is read as an attachment of that page. */
+export const ATTACHMENT_NAME = /^(.+)-([0-9a-f]{8})\.([A-Za-z0-9]+)$/;
+export function parsePage(relPath, content) {
+    const frontmatter = parseFrontmatter(content);
+    const body = content.slice(frontmatter.bodyOffset);
+    const lines = body.split('\n');
+    const bodyLine = frontmatter.bodyLine;
+    const slug = relPathToSlug(relPath);
+    let sourceFenceLine = null;
+    const events = [];
+    const links = [];
+    for (let i = 0; i < lines.length; i++) {
+        const raw = lines[i];
+        const absoluteLine = bodyLine + i;
+        if (sourceFenceLine === null && SOURCE_FENCE.test(raw)) {
+            sourceFenceLine = absoluteLine;
+        }
+        const event = EVENT_LINE.exec(raw);
+        if (event) {
+            const summary = event[2];
+            events.push({
+                date: event[1],
+                // The link is part of the line's syntax, not part of what happened.
+                summary: summary
+                    .replace(WIKILINK, '')
+                    .replace(/\s{2,}/g, ' ')
+                    .trim(),
+                targetSlug: firstWikilink(summary),
+                line: absoluteLine,
+            });
+        }
+        for (const match of raw.matchAll(WIKILINK)) {
+            const target = normalizeLinkTarget(match[1]);
+            links.push({
+                toSlug: target,
+                kind: isFileTarget(target) ? 'embed' : 'wikilink',
+                line: absoluteLine,
+            });
+        }
+        for (const match of raw.matchAll(MARKDOWN_LINK)) {
+            links.push({
+                toSlug: normalizeLinkTarget(match[1], slug),
+                kind: 'markdown',
+                line: absoluteLine,
+            });
+        }
+    }
+    const akno = readAknoData(frontmatter.data);
+    const declaredRole = readPageRole(akno.role);
+    const title = readString(frontmatter.data, 'title') ?? deriveTitle(lines, relPath);
+    const rawAbout = readStringArray(akno.about);
+    const rawAliases = readStringArray(akno.aliases);
+    const identityKeys = new Set([title, slug, slug.split('/').pop() ?? slug].map(identityKey));
+    return {
+        slug,
+        relPath,
+        frontmatter,
+        title,
+        type: readString(frontmatter.data, 'type'),
+        tags: readTags(frontmatter.data),
+        declaredRole,
+        declaredManagement: readManagement(akno.management),
+        about: rawAbout.filter((entry) => normalizeLinkTarget(entry) !== slug),
+        aliases: rawAliases.filter((entry) => !identityKeys.has(identityKey(entry))),
+        content,
+        body,
+        lines,
+        bodyLine,
+        bodyHash: sha256(body),
+        sourceFenceLine,
+        events: dedupeEvents(events),
+        links: dedupeLinks(links),
+        frontmatterId: readString(frontmatter.data, 'id'),
+    };
+}
+function readAknoData(data) {
+    const value = data.akno;
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function readPageRole(value) {
+    return value === 'knowledge' || value === 'source' || value === 'inference' || value === 'ignored'
+        ? value
+        : null;
+}
+function readManagement(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return {};
+    const record = value;
+    const remember = record.remember === 'deny' || record.remember === 'integrate' ? record.remember : null;
+    const dream = record.dream === 'none' || record.dream === 'hygiene' || record.dream === 'synthesize'
+        ? record.dream
+        : null;
+    return {
+        ...(remember ? { remember } : {}),
+        ...(dream ? { dream } : {}),
+    };
+}
+function readStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return [
+        ...new Set(value
+            .filter((entry) => typeof entry === 'string')
+            .map((entry) => entry.trim())
+            .filter(Boolean)),
+    ];
+}
+function identityKey(value) {
+    return value
+        .normalize('NFKC')
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}]+/gu, '');
+}
+/**
+ * Frontmatter `title:` wins; then the first `#` heading; then the filename
+ * un-slugified. A page with no title at all is common and should not read as
+ * `untitled` in a card.
+ */
+function deriveTitle(lines, relPath) {
+    for (const line of lines) {
+        const heading = /^#{1,3}\s+(.+?)\s*$/.exec(line);
+        if (heading)
+            return heading[1].replace(/[#*`]/g, '').trim();
+    }
+    const base = path.basename(relPath).replace(/\.(md|markdown)$/i, '');
+    return base.replace(/[-_]+/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+}
+function relPathToSlug(relPath) {
+    return relPath.replace(/\\/g, '/').replace(/\.(md|markdown)$/i, '');
+}
+function firstWikilink(text) {
+    const match = WIKILINK.exec(text);
+    WIKILINK.lastIndex = 0;
+    return match ? normalizeLinkTarget(match[1]) : null;
+}
+/**
+ * A link target may be written a dozen ways: `[[home/lease]]`, `[[Home/Lease]]`,
+ * `[[lease.md]]`, `[../home/lease.md]`. They all mean one page, and resolving
+ * that here is the difference between a working backlink graph and a wall of
+ * false "broken link" reports.
+ */
+/**
+ * True for a target that names a file rather than a page.
+ *
+ * `normalizeLinkTarget` has already stripped `.md`, so anything with an extension left is
+ * not a page: `[[receipt-3f8c1a2b.pdf]]`, `[[scan.jpg]]`. Counting those as page links made
+ * every embedded attachment show up in `doctor` as a wikilink pointing at a page that does
+ * not exist — noise that buries the real broken links.
+ */
+function isFileTarget(target) {
+    return /\.[A-Za-z0-9]{1,8}$/.test(target);
+}
+export function normalizeLinkTarget(target, fromSlug) {
+    let cleaned = target
+        .trim()
+        .replace(/\\/g, '/')
+        .replace(/\.(md|markdown)$/i, '');
+    if (cleaned.startsWith('./'))
+        cleaned = cleaned.slice(2);
+    if (fromSlug && (cleaned.startsWith('../') || !cleaned.includes('/'))) {
+        const fromDir = fromSlug.includes('/') ? fromSlug.slice(0, fromSlug.lastIndexOf('/')) : '';
+        cleaned = path.posix.normalize(path.posix.join(fromDir, cleaned));
+    }
+    // A target that resolves above the knowledge base root is clamped to it rather
+    // than kept with its `..` intact. These strings are only ever compared against
+    // `pages.slug`, never used as a path — but a slug that can express "outside the
+    // knowledge base" is one refactor away from being used as one.
+    return cleaned.replace(/^(?:\.\.\/)+/, '').replace(/^\/+/, '');
+}
+/** The same event written twice in one file is one event. */
+function dedupeEvents(events) {
+    const seen = new Set();
+    return events.filter((event) => {
+        const key = `${event.date}|${event.targetSlug ?? ''}|${event.summary.toLowerCase()}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+function dedupeLinks(links) {
+    const seen = new Set();
+    return links.filter((link) => {
+        if (link.toSlug.length === 0)
+            return false;
+        const key = `${link.toSlug}|${link.kind}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+export function resolveRole(page, rule, observationsPath) {
+    if (page.declaredRole)
+        return { role: page.declaredRole, source: 'frontmatter' };
+    if (rule?.role)
+        return { role: rule.role, source: 'rule', via: rule.glob };
+    // Provenance: pages the observe tier authored are inferences, not authored
+    // claims, and must never be admissible evidence for another observation.
+    if (page.slug === observationsPath || page.slug.startsWith(`${observationsPath}/`)) {
+        return { role: 'inference', source: 'provenance' };
+    }
+    return { role: 'knowledge', source: 'default' };
+}
+export function resolvePagePolicy(page, rule, observationsPath) {
+    const role = resolveRole(page, rule, observationsPath).role;
+    return {
+        role,
+        // Searchability is not write consent. A plain Markdown page remains useful knowledge,
+        // but `remember` may change it only when the page or its folder says so explicitly.
+        remember: page.declaredManagement.remember ?? rule?.remember ?? 'deny',
+        // Whole-page automatic authority must be visible on the page itself. Folder rules cannot
+        // make an existing page rewritable merely because it was moved under another path.
+        dream: page.declaredManagement.dream ?? 'none',
+        about: page.about.length > 0 ? page.about : (rule?.about ?? []).filter((slug) => slug !== page.slug),
+        aliases: page.aliases,
+    };
+}
+/** True for a page written by the observe tier — ranked below authored pages. */
+export function isObservation(slug, observationsPath) {
+    return slug === observationsPath || slug.startsWith(`${observationsPath}/`);
+}
+//# sourceMappingURL=page.js.map

package/dist/kb/page.js.map

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

package/dist/kb/scan.d.ts

@@ -0,0 +1,38 @@
+type FileKind = 'page' | 'attachment';
+export interface ScannedFile {
+    relPath: string;
+    absPath: string;
+    size: number;
+    /** Nanosecond mtime as a string — a float loses precision above ~2^53 ns. */
+    mtimeNs: string;
+    /** Filesystem birth time, kept only as visibly labelled metadata evidence. */
+    birthtimeNs: string;
+    kind: FileKind;
+    /** Present only once the file has actually been hashed. */
+    sha256?: string;
+    /**
+     * A knowledge base inside iCloud Drive or Dropbox with storage
+     * optimization on will have evicted files that look present but read as
+     * placeholders. Indexing a zero-byte stand-in as though the document were
+     * empty is worse than skipping it and saying so.
+     */
+    dataless?: boolean;
+}
+export interface ScanOptions {
+    root: string;
+    ignore: string[];
+    pageExtensions: string[];
+    maxPageBytes: number;
+}
+/**
+ * Walks the knowledge base and stats every file. Deliberately does not hash:
+ * The fast path is that a restart *stats* rather than re-indexing, and only
+ * files whose mtime or size moved get hashed.
+ */
+export declare function scanTree(options: ScanOptions): Promise<ScannedFile[]>;
+export declare function hashFile(absPath: string): Promise<string>;
+/** Bounded-concurrency map. Hashing 5,000 files takes ~116ms; the bound keeps a
+ *  slow disk or a network mount from opening every file at once. */
+export declare function mapWithConcurrency<T, R>(items: T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
+export {};
+//# sourceMappingURL=scan.d.ts.map

package/dist/kb/scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../../src/kb/scan.ts"],"names":[],"mappings":"AAKA,KAAK,QAAQ,GAAG,MAAM,GAAG,YAAY,CAAC;AAEtC,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,QAAQ,CAAC;IACf,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAK3E;AAoED,wBAAsB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAc/D;AAED;oEACoE;AACpE,wBAAsB,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAC3C,KAAK,EAAE,CAAC,EAAE,EACV,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GACzC,OAAO,CAAC,CAAC,EAAE,CAAC,CAYd"}

package/dist/kb/scan.js

@@ -0,0 +1,109 @@
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+/**
+ * Walks the knowledge base and stats every file. Deliberately does not hash:
+ * The fast path is that a restart *stats* rather than re-indexing, and only
+ * files whose mtime or size moved get hashed.
+ */
+export async function scanTree(options) {
+    const out = [];
+    const ignore = new Set(options.ignore.map((entry) => entry.replace(/\/+$/, '')));
+    await walk(options.root, '', out, ignore, options);
+    return out;
+}
+async function walk(root, relDir, out, ignore, options) {
+    const absDir = relDir ? path.join(root, relDir) : root;
+    let entries;
+    try {
+        entries = await fsp.readdir(absDir, { withFileTypes: true });
+    }
+    catch {
+        // An unreadable directory is reported by `doctor`, not fatal here — a
+        // permissions problem in one folder should not cost the whole index.
+        return;
+    }
+    for (const entry of entries) {
+        if (ignore.has(entry.name))
+            continue;
+        // Dotfiles are never knowledge. Obsidian, git, sync clients and editors all
+        // put working state in them, and none of it is a note.
+        if (entry.name.startsWith('.'))
+            continue;
+        const rel = relDir ? `${relDir}/${entry.name}` : entry.name;
+        if (ignore.has(rel))
+            continue;
+        if (entry.isDirectory()) {
+            await walk(root, rel, out, ignore, options);
+            continue;
+        }
+        // A symlink could point outside the knowledge base; following one turns
+        // "index this folder" into something the user did not agree to.
+        if (!entry.isFile())
+            continue;
+        const absPath = path.join(root, rel);
+        // `bigint: true` is what exposes mtimeNs. A float mtime loses precision above
+        // ~2^53 nanoseconds, which is well inside the range real timestamps use, and
+        // an imprecise mtime silently defeats the stat fast path.
+        let stat;
+        try {
+            stat = await fsp.stat(absPath, { bigint: true });
+        }
+        catch {
+            continue;
+        }
+        const extension = path.extname(entry.name).toLowerCase();
+        const isPage = options.pageExtensions.includes(extension);
+        const size = Number(stat.size);
+        const file = {
+            relPath: rel,
+            absPath,
+            size,
+            mtimeNs: String(stat.mtimeNs),
+            birthtimeNs: String(stat.birthtimeNs),
+            kind: isPage ? 'page' : 'attachment',
+        };
+        // A file that reports a size but occupies no blocks is the classic
+        // dataless signature: iCloud or Dropbox has evicted the contents and left a
+        // placeholder that reads as empty.
+        if (size > 0 && stat.blocks === 0n)
+            file.dataless = true;
+        if (isPage && size > options.maxPageBytes)
+            continue;
+        out.push(file);
+    }
+}
+export async function hashFile(absPath) {
+    const hash = createHash('sha256');
+    const handle = await fsp.open(absPath, 'r');
+    try {
+        const buffer = Buffer.allocUnsafe(64 * 1024);
+        for (;;) {
+            const { bytesRead } = await handle.read(buffer, 0, buffer.length, null);
+            if (bytesRead === 0)
+                break;
+            hash.update(buffer.subarray(0, bytesRead));
+        }
+    }
+    finally {
+        await handle.close();
+    }
+    return hash.digest('hex');
+}
+/** Bounded-concurrency map. Hashing 5,000 files takes ~116ms; the bound keeps a
+ *  slow disk or a network mount from opening every file at once. */
+export async function mapWithConcurrency(items, limit, fn) {
+    const results = new Array(items.length);
+    let next = 0;
+    const workers = Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, async () => {
+        for (;;) {
+            const index = next++;
+            if (index >= items.length)
+                return;
+            results[index] = await fn(items[index], index);
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}
+//# sourceMappingURL=scan.js.map

package/dist/kb/scan.js.map

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

package/dist/kb/words.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Comparing two sentences by what they are about rather than how they are worded.
+ *
+ * Used where the same claim can arrive twice in different words and only one copy should survive:
+ * a nightly observation re-derived from unchanged facts, and a timeline event added twice for one
+ * day. Both were caught only by exact string equality before, which is to say not caught at all —
+ * `They watched "Wicked: For Good"` and `The user watched "Wicked: For Good"` are one event and two
+ * strings.
+ *
+ * Deliberately not a model call. This runs on every write, and a comparison that costs a model is
+ * one that gets skipped when the model is missing — which is exactly when a knowledge base is
+ * accumulating duplicates fastest.
+ */
+/** The words of a sentence that say what it is about. */
+export declare function contentWords(text: string): Set<string>;
+/**
+ * Whether two sentences are about the same thing.
+ *
+ * **Containment, not symmetric overlap.** The second telling of an event is rarely the first one
+ * reworded — it is usually the first one *plus something*: "They watched Wicked: For Good in the
+ * evening" and "Watched Wicked: For Good and rated it 8 out of 10" are one evening, and they share
+ * three quarters of the shorter sentence while sharing only half of the two combined. Symmetric
+ * overlap therefore misses exactly the case that matters, and lowering its threshold far enough to
+ * catch it would also merge "the flight departed" with "the flight landed".
+ *
+ * The floor on the shorter sentence is what keeps that safe: two three-word summaries can share
+ * two words by accident, and without a minimum there is not enough sentence to be sure with.
+ */
+export declare function saysTheSame(a: string, b: string, threshold?: number): boolean;
+//# sourceMappingURL=words.d.ts.map

package/dist/kb/words.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"words.d.ts","sourceRoot":"","sources":["../../src/kb/words.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA6DH,yDAAyD;AACzD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAUtD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,SAAS,SAAM,GAAG,OAAO,CAS1E"}

package/dist/kb/words.js

@@ -0,0 +1,107 @@
+/**
+ * Comparing two sentences by what they are about rather than how they are worded.
+ *
+ * Used where the same claim can arrive twice in different words and only one copy should survive:
+ * a nightly observation re-derived from unchanged facts, and a timeline event added twice for one
+ * day. Both were caught only by exact string equality before, which is to say not caught at all —
+ * `They watched "Wicked: For Good"` and `The user watched "Wicked: For Good"` are one event and two
+ * strings.
+ *
+ * Deliberately not a model call. This runs on every write, and a comparison that costs a model is
+ * one that gets skipped when the model is missing — which is exactly when a knowledge base is
+ * accumulating duplicates fastest.
+ */
+/**
+ * Words that carry no subject matter, plus the ones a rephrasing swaps freely.
+ *
+ * `they`/`user`/`we` are here because who is being talked about is not what distinguishes two
+ * events on the same day: an assistant writing "they watched X" and "the user watched X" has
+ * written the same line twice.
+ */
+const STOPWORDS = new Set([
+    'the',
+    'a',
+    'an',
+    'and',
+    'or',
+    'of',
+    'to',
+    'in',
+    'on',
+    'at',
+    'for',
+    'with',
+    'is',
+    'are',
+    'was',
+    'were',
+    'be',
+    'been',
+    'has',
+    'have',
+    'had',
+    'this',
+    'that',
+    'these',
+    'those',
+    'it',
+    'its',
+    'as',
+    'by',
+    'from',
+    'usually',
+    'often',
+    'always',
+    'each',
+    'every',
+    'they',
+    'them',
+    'their',
+    'we',
+    'our',
+    'us',
+    'he',
+    'she',
+    'his',
+    'her',
+    'you',
+    'your',
+    'user',
+    'users',
+]);
+/** The words of a sentence that say what it is about. */
+export function contentWords(text) {
+    return new Set(text
+        .toLowerCase()
+        // Wikilinks are addresses, not content: two lines that differ only by a citation are one line.
+        .replace(/\[\[[^\]]*\]\]/g, ' ')
+        .replace(/[^a-z0-9\s]/g, ' ')
+        .split(/\s+/)
+        .filter((word) => word.length > 2 && !STOPWORDS.has(word)));
+}
+/**
+ * Whether two sentences are about the same thing.
+ *
+ * **Containment, not symmetric overlap.** The second telling of an event is rarely the first one
+ * reworded — it is usually the first one *plus something*: "They watched Wicked: For Good in the
+ * evening" and "Watched Wicked: For Good and rated it 8 out of 10" are one evening, and they share
+ * three quarters of the shorter sentence while sharing only half of the two combined. Symmetric
+ * overlap therefore misses exactly the case that matters, and lowering its threshold far enough to
+ * catch it would also merge "the flight departed" with "the flight landed".
+ *
+ * The floor on the shorter sentence is what keeps that safe: two three-word summaries can share
+ * two words by accident, and without a minimum there is not enough sentence to be sure with.
+ */
+export function saysTheSame(a, b, threshold = 0.7) {
+    const left = contentWords(a);
+    const right = contentWords(b);
+    const smaller = Math.min(left.size, right.size);
+    if (smaller < 3)
+        return false;
+    let shared = 0;
+    for (const word of right)
+        if (left.has(word))
+            shared += 1;
+    return shared / smaller >= threshold;
+}
+//# sourceMappingURL=words.js.map

package/dist/kb/words.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"words.js","sourceRoot":"","sources":["../../src/kb/words.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;;GAMG;AACH,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC;IACxB,KAAK;IACL,GAAG;IACH,IAAI;IACJ,KAAK;IACL,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,KAAK;IACL,MAAM;IACN,IAAI;IACJ,KAAK;IACL,KAAK;IACL,MAAM;IACN,IAAI;IACJ,MAAM;IACN,KAAK;IACL,MAAM;IACN,KAAK;IACL,MAAM;IACN,MAAM;IACN,OAAO;IACP,OAAO;IACP,IAAI;IACJ,KAAK;IACL,IAAI;IACJ,IAAI;IACJ,MAAM;IACN,SAAS;IACT,OAAO;IACP,QAAQ;IACR,MAAM;IACN,OAAO;IACP,MAAM;IACN,MAAM;IACN,OAAO;IACP,IAAI;IACJ,KAAK;IACL,IAAI;IACJ,IAAI;IACJ,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,MAAM;IACN,MAAM;IACN,OAAO;CACR,CAAC,CAAC;AAEH,yDAAyD;AACzD,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,OAAO,IAAI,GAAG,CACZ,IAAI;SACD,WAAW,EAAE;QACd,+FAA+F;SAC9F,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC;SAC/B,OAAO,CAAC,cAAc,EAAE,GAAG,CAAC;SAC5B,KAAK,CAAC,KAAK,CAAC;SACZ,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAC7D,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CAAC,CAAS,EAAE,CAAS,EAAE,SAAS,GAAG,GAAG;IAC/D,MAAM,IAAI,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;IAC7B,MAAM,KAAK,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;IAC9B,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;IAChD,IAAI,OAAO,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IAE9B,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,KAAK,MAAM,IAAI,IAAI,KAAK;QAAE,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,MAAM,IAAI,CAAC,CAAC;IAC1D,OAAO,MAAM,GAAG,OAAO,IAAI,SAAS,CAAC;AACvC,CAAC"}

package/dist/maintenance/adopt.d.ts

@@ -0,0 +1,65 @@
+import type { AknoContext } from '../context.ts';
+/**
+ * A page for a document that has none, written beside the file.
+ *
+ * An attachment nobody's page points at is already returned as a standalone document card.
+ * Adoption gives that evidence a durable, browsable home with page policy and links.
+ *
+ * The filing operation is the one `ingest` already applies to every arrival: give it a page that says what
+ * it is and embeds it. An orphan is simply an arrival nobody ran `ingest` on, so it gets the
+ * same shape of page, from the summary the extraction pass already produced — no model call of
+ * its own, and no inference beyond what the document says about itself.
+ *
+ * Three limits, because this writes files into somebody's notes:
+ *
+ * - **`ingest: "file"` is honoured.** That rule exists precisely for a folder of media where a
+ *   stub page per file would be noise rather than memory, and this is the behaviour it turns
+ *   off. `ingest: "ignore"` is skipped too.
+ * - **Capped per run.** A folder of 500 unowned PDFs should not become 500 pages overnight
+ *   before anyone has seen the first one; the cap makes the first night's report arrive while
+ *   it is still small enough to read — and `--dry-run` shows it without writing.
+ * - **The file is never touched.** Only the inbox moves files, ever. Nothing
+ *   here renames, moves, or rewrites a byte of the document.
+ */
+export interface AdoptedDocument {
+    slug: string;
+    /** The files the page now owns — parts of one document share a page. */
+    files: string[];
+    action: 'planned' | 'created' | 'skipped' | 'blocked' | 'rejected';
+    reason?: string;
+}
+export interface AdoptionDraft {
+    slug: string;
+    relPath: string;
+    inputHash: string;
+    after: string;
+    /** Persist the exact proposal, but do not decide or apply it until this condition is resolved. */
+    blockedReason?: string;
+    documents: {
+        id: string;
+        relPath: string;
+        sha256: string;
+        metadataHash: string;
+        groupKey: string;
+    }[];
+}
+export interface AdoptionSnapshot {
+    indexRevision: string;
+    knowledgeBaseFingerprint: string;
+    configurationFingerprint: string;
+}
+/**
+ * Seal exact page creations without touching the knowledge base.
+ *
+ * The document hashes become item inputs and the run-start manifest is retained as plan evidence.
+ * Apply rechecks both the source files and their orphaned index rows, so a page is never created
+ * from a stale summary or for a document somebody filed while the plan was waiting.
+ */
+export declare function planOrphanAdoptions(ctx: AknoContext, options: {
+    limit: number;
+    documentId?: string;
+}): Promise<{
+    adopted: AdoptedDocument[];
+    drafts: AdoptionDraft[];
+}>;
+//# sourceMappingURL=adopt.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"adopt.d.ts","sourceRoot":"","sources":["../../src/maintenance/adopt.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAOjD;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU,CAAC;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,kGAAkG;IAClG,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE;QACT,EAAE,EAAE,MAAM,CAAC;QACX,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,YAAY,EAAE,MAAM,CAAC;QACrB,QAAQ,EAAE,MAAM,CAAC;KAClB,EAAE,CAAC;CACL;AAED,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,wBAAwB,EAAE,MAAM,CAAC;IACjC,wBAAwB,EAAE,MAAM,CAAC;CAClC;AAgBD;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,WAAW,EAChB,OAAO,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9C,OAAO,CAAC;IAAE,OAAO,EAAE,eAAe,EAAE,CAAC;IAAC,MAAM,EAAE,aAAa,EAAE,CAAA;CAAE,CAAC,CAgGlE"}