@tenphi/akno-core 0.1.0

package/dist/ingest/name.d.ts

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+import { type ModelClient } from '../models/client.ts';
+/**
+ * **Files arrive with useless names.** `IMG_4821.HEIC`. `Scan 2026-08-06 at
+ * 14.22.pdf`. `document(3).pdf`. A camera or a scanner named these, and the name says
+ * nothing about what is inside — six months later nobody can find them, and neither
+ * can search, because the filename is indexed and contributes only noise.
+ *
+ * Akno already has the text. Once it has that, naming is nearly free: **one call to
+ * the derive model over the extracted text returns title, slug, summary, type and
+ * a suggested folder together.** Not five calls — the model is reading the document
+ * once either way.
+ *
+ * Two guards, both of which matter more than the naming does:
+ *
+ * - **A good name is left alone.** `2024-lease-agreement.pdf` carries information and
+ *   is kept. Renaming only fires when the filename adds nothing the content does not
+ *   already say.
+ * - **Low confidence means no rename.** A photo of a garden or a corrupt scan keeps
+ *   its name, gets no page, and is flagged in `doctor` rather than given a confident
+ *   wrong one.
+ */
+export interface NamedDocument {
+    title: string;
+    /** Basename only. The folder is decided by routing, not here. */
+    slug: string;
+    summary: string;
+    type: string | null;
+    /** A folder the model thinks fits. Advisory — routing decides. */
+    suggestedFolder: string | null;
+    /** The model's own confidence that it understood the document at all, 0..1. */
+    confidence: number;
+    error: string | null;
+}
+/** `folder` is nullable rather than optional: the prompt offers `null` explicitly as the
+ *  answer for "none fit", and a nullable field keeps that a stated choice instead of an
+ *  absence that could equally mean the model forgot. */
+export declare const NAME_SCHEMA: z.ZodObject<{
+    title: z.ZodString;
+    slug: z.ZodString;
+    summary: z.ZodString;
+    type: z.ZodString;
+    folder: z.ZodNullable<z.ZodString>;
+    confidence: z.ZodNumber;
+}, z.core.$strip>;
+export interface NameOptions {
+    /** Extracted text. Truncated before the call — a name does not need 40 pages. */
+    text: string;
+    originalName: string;
+    /** Folders that exist, so the suggestion is a real place and not an invention. */
+    folders: string[];
+    derive: ModelClient;
+}
+export declare function nameDocument(options: NameOptions): Promise<NamedDocument>;
+/**
+ * A title a small model produced by echoing the slug — `ip-datagrams-on-avian-carriers` —
+ * turned back into words.
+ *
+ * The prompt asks for "what a person would call this", and models answer that with a slug
+ * often enough to matter: the title is what every recall card shows, so it is the one
+ * field where a machine-shaped answer is most visible. Only fired when there is no space
+ * at all, so a hyphenated title someone meant — `Zephyr QX-100 warranty` — is untouched.
+ */
+export declare function unslug(title: string | null): string | null;
+/**
+ * A model asked for a filename will sometimes answer with a path, an extension, or
+ * a sentence. Only the basename shape survives — the folder is routing's decision,
+ * and a slug that can express `../` is one refactor away from being used as a path.
+ */
+export declare function cleanSlug(value: unknown): string | null;
+export declare function nameIsUseless(originalName: string): boolean;
+//# sourceMappingURL=name.d.ts.map

package/dist/ingest/name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"name.d.ts","sourceRoot":"","sources":["../../src/ingest/name.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvE;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,kEAAkE;IAClE,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,+EAA+E;IAC/E,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAiCD;;wDAEwD;AACxD,eAAO,MAAM,WAAW;;;;;;;iBAOtB,CAAC;AAEH,MAAM,WAAW,WAAW;IAC1B,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,WAAW,CAAC;CACrB;AAED,wBAAsB,YAAY,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC,CAsD/E;AAED;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAI1D;AAcD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAevD;AAwCD,wBAAgB,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAc3D"}

package/dist/ingest/name.js

@@ -0,0 +1,208 @@
+import path from 'node:path';
+import { z } from 'zod';
+import { parseJsonLoose } from "../models/client.js";
+const SYSTEM = `You are naming a document for a personal knowledge base from its extracted text.
+
+Reply with JSON only:
+{
+  "title": "what a person would call this, 3-8 words",
+  "slug": "kebab-case-file-name, no folder, no extension",
+  "summary": "one or two sentences: what it is, and its most load-bearing values",
+  "type": "one lowercase word, e.g. invoice receipt contract statement policy letter report photo note",
+  "folder": "an existing folder from the list you were given, or null if none fit",
+  "confidence": 0.0
+}
+
+The naming rule is **kind + subject + date**, from the content:
+  invoice-northern-water-2026-07
+  contract-apartment-lease-2024-08
+  receipt-car-rental-2026-06
+
+Rules:
+- Name it from what the text says. Never from the original filename — that is the
+  thing being replaced.
+- Include a date in the slug when the document has one, in YYYY-MM or YYYY-MM-DD.
+- No personal names in the slug unless the document is *about* that person
+  (an identity document, a contract in their name).
+- "confidence" is how sure you are that you understood what this document is:
+    0.9+  the text plainly says what it is
+    0.5   you can guess from fragments
+    0.2   the text is garbled, or too short to tell
+    0.0   you cannot tell at all
+  Be honest. A low number is useful; a confident wrong name is not.
+- Reply with confidence 0 rather than inventing a title for text you cannot read.`;
+/** `folder` is nullable rather than optional: the prompt offers `null` explicitly as the
+ *  answer for "none fit", and a nullable field keeps that a stated choice instead of an
+ *  absence that could equally mean the model forgot. */
+export const NAME_SCHEMA = z.object({
+    title: z.string(),
+    slug: z.string(),
+    summary: z.string(),
+    type: z.string(),
+    folder: z.string().nullable(),
+    confidence: z.number(),
+});
+export async function nameDocument(options) {
+    const empty = {
+        title: '',
+        slug: '',
+        summary: '',
+        type: null,
+        suggestedFolder: null,
+        confidence: 0,
+        error: null,
+    };
+    if (!options.derive.available) {
+        return { ...empty, error: options.derive.unavailableReason ?? 'derive model unavailable' };
+    }
+    if (options.text.trim().length < 20) {
+        return { ...empty, error: 'too little text to name the document from' };
+    }
+    // The opening of a document says what it is. 6000 characters covers a multi-page
+    // contract's first pages, and sending 40 pages to choose 5 words is waste.
+    const excerpt = options.text.slice(0, 6000);
+    const folders = options.folders.slice(0, 60).join(', ');
+    const result = await options.derive.chat([
+        { role: 'system', content: SYSTEM },
+        {
+            role: 'user',
+            content: `Existing folders: ${folders || '(none yet)'}\n\nExtracted text:\n\n${excerpt}`,
+        },
+    ], { schema: NAME_SCHEMA, maxTokens: 500 });
+    if (!result.ok || !result.value)
+        return { ...empty, error: result.error ?? 'naming failed' };
+    const parsed = parseJsonLoose(result.value);
+    if (!parsed)
+        return { ...empty, error: 'naming returned unparseable JSON' };
+    const slug = cleanSlug(parsed.slug);
+    const title = unslug(cleanText(parsed.title, 120));
+    if (!slug || !title)
+        return { ...empty, error: 'naming returned no usable slug or title' };
+    const suggested = cleanText(parsed.folder, 200);
+    return {
+        title,
+        slug,
+        summary: cleanText(parsed.summary, 400) ?? '',
+        type: cleanType(parsed.type),
+        // Only a folder that actually exists. A model inventing `invoices/` and Akno
+        // creating it is exactly the action the gate exists to prevent.
+        suggestedFolder: suggested && options.folders.includes(suggested) ? suggested : null,
+        confidence: clampConfidence(parsed.confidence),
+        error: null,
+    };
+}
+/**
+ * A title a small model produced by echoing the slug — `ip-datagrams-on-avian-carriers` —
+ * turned back into words.
+ *
+ * The prompt asks for "what a person would call this", and models answer that with a slug
+ * often enough to matter: the title is what every recall card shows, so it is the one
+ * field where a machine-shaped answer is most visible. Only fired when there is no space
+ * at all, so a hyphenated title someone meant — `Zephyr QX-100 warranty` — is untouched.
+ */
+export function unslug(title) {
+    if (title === null || /\s/.test(title))
+        return title;
+    if (!/[-_]/.test(title))
+        return title;
+    return title.replace(/[-_]+/g, ' ');
+}
+function cleanText(value, max) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim().replace(/\s+/g, ' ');
+    return trimmed.length > 0 ? trimmed.slice(0, max) : null;
+}
+function cleanType(value) {
+    if (typeof value !== 'string')
+        return null;
+    const type = value.trim().toLowerCase().split(/\s+/)[0] ?? '';
+    return /^[a-z][a-z-]{1,30}$/.test(type) ? type : null;
+}
+/**
+ * A model asked for a filename will sometimes answer with a path, an extension, or
+ * a sentence. Only the basename shape survives — the folder is routing's decision,
+ * and a slug that can express `../` is one refactor away from being used as a path.
+ */
+export function cleanSlug(value) {
+    if (typeof value !== 'string')
+        return null;
+    const base = value
+        .trim()
+        .toLowerCase()
+        .split('/')
+        .pop()
+        .replace(/\.[a-z0-9]{1,8}$/, '')
+        .normalize('NFKD')
+        .replace(/[\u0300-\u036f]/g, '')
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 80)
+        .replace(/-+$/, '');
+    return base.length >= 3 ? base : null;
+}
+/**
+ * Renaming only fires when the filename adds nothing the content does not
+ * already say — camera and scanner patterns, bare hashes and UUIDs, `document(3)`, or
+ * a name with no words in it beyond a date.
+ *
+ * The bias is deliberately toward keeping: a name someone chose carries intent that
+ * no model can reconstruct, and getting this wrong is destructive in a way a bad
+ * summary is not.
+ */
+const USELESS_NAME = [
+    /^img[_-]?\d+$/i,
+    /^dsc[_-]?\d+$/i,
+    /^dscn\d+$/i,
+    /^p\d{7,}$/i,
+    // Pixel and other Android cameras: PXL_20260806_141500, MVIMG_, PANO_, VID_.
+    /^(pxl|mvimg|pano|vid|burst)[_-]?\d+/i,
+    // Photo Booth and the iOS simulator.
+    /^photo on \d{4}-\d{2}-\d{2}/i,
+    /^simulator screenshot/i,
+    /^photo[_ -]?\d*$/i,
+    /^image[_ -]?\d*$/i,
+    /^screenshot[_ -]/i,
+    /^screen shot /i,
+    /^scan(ned)?([_ -]|$)/i,
+    /^scan \d{4}-\d{2}-\d{2} at /i,
+    /^document\s*\(\d+\)$/i,
+    /^document\d*$/i,
+    /^untitled/i,
+    /^file[_-]?\d*$/i,
+    /^download(\s*\(\d+\))?$/i,
+    /^whatsapp (image|document|video)/i,
+    /^telegram/i,
+    /^[0-9a-f]{16,}$/i,
+    /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
+    /^\d{8,}$/,
+    /^[\d\s._-]+$/,
+];
+export function nameIsUseless(originalName) {
+    const file = path.basename(originalName).trim();
+    // `path.extname('.pdf')` is '' — a leading dot means a hidden file, not an
+    // extension — so a name that is nothing but an extension has to be caught here.
+    if (/^\.[A-Za-z0-9]{1,8}$/.test(file))
+        return true;
+    const base = path.basename(file, path.extname(file)).trim();
+    if (base.length === 0)
+        return true;
+    if (USELESS_NAME.some((pattern) => pattern.test(base)))
+        return true;
+    // A name whose only content is a date says when, never what. Common for scanners.
+    const withoutDates = base.replace(/\d{4}[-_.]?\d{2}[-_.]?\d{2}|\d{2}[-_.]\d{2}[-_.]\d{4}/g, '');
+    const words = withoutDates.split(/[^A-Za-z]+/).filter((word) => word.length >= 3);
+    return words.length === 0;
+}
+/**
+ * The second naming guard depends on this number being meaningful, so an absent or
+ * nonsense value reads as **no** confidence rather than as full confidence. A model
+ * that forgets the field must not thereby get permission to rename.
+ */
+function clampConfidence(value) {
+    const parsed = typeof value === 'number' ? value : Number(value);
+    if (!Number.isFinite(parsed))
+        return 0;
+    return Math.round(Math.max(0, Math.min(1, parsed)) * 100) / 100;
+}
+//# sourceMappingURL=name.js.map

package/dist/ingest/name.js.map

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

package/dist/ingest/parts.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Scanning a passport gives you `passport.pdf` and `passport-2.pdf`. They are not two
+ * documents — they are one document someone's scanner cut in half.
+ *
+ * Treating them separately produces two pages, two summaries and two half-answers, and
+ * "page 2" of the second file is really page 5 of the passport. So files that differ only
+ * by a trailing `-<n>` are read as **parts of one document**: one owning page, one summary,
+ * and page numbers that run through the whole thing.
+ *
+ * The rule is deliberately narrow, because the cost of a wrong guess is two unrelated
+ * documents welded together:
+ *
+ * - The extension must match. `passport.jpg` beside `passport.pdf` is a second rendition of
+ *   the same thing, not its second half, and merging their text would interleave two
+ *   readings of one page.
+ * - The suffix must be one or two digits **not preceded by a digit**. `bill-2026.pdf` is a
+ *   year and `invoice-100.pdf` is an invoice number — but the case that actually bit was
+ *   `waternet-annual-bill-2026-07-28.pdf`, read as part 28 of a bill that does not exist.
+ *   Two bills dated `-27` and `-28` would have been welded into one document.
+ * - Part one must exist on disk. A lone `-<n>` file is its own document, whatever its name
+ *   suggests, because the alternative is inventing a document out of a filename.
+ * - A content-addressed attachment (`<page>-<8 hex>.<ext>`) is never a part. Its suffix is
+ *   a hash, and Akno wrote it.
+ */
+/**
+ * The other thing a second file beside a document can be.
+ *
+ * The part rule above excludes a differing extension because `passport.jpg` beside
+ * `passport.pdf` is "a second rendition of the same thing, not its second half". That
+ * category was named and then had nowhere to go. This is where it goes: `contract.pdf.txt`
+ * holds the *same* text as `contract.pdf`, in a format anything can open.
+ *
+ * The distinction is not cosmetic. Parts concatenate — `read` joins their text and page
+ * numbers run through the whole group — while a rendition must never be joined to what it
+ * renders, or a contract's every phrase comes back twice.
+ *
+ * Two spellings, because both occur. Akno writes `contract.pdf.txt`; a person who ran
+ * `pdftotext` before Akno existed wrote `contract.txt` beside `contract.pdf`, and that
+ * second one is the case that was quietly costing double hits on every phrase in the file.
+ *
+ * The rule stays as narrow as the part rule, and for the same reasons:
+ *
+ * - **Only a `.txt` is ever a rendition.** `passport.jpg` beside `passport.pdf` is two
+ *   renderings with no way to say which is the document, so neither is folded into the other.
+ * - **The source must exist, and be a format text is extracted *from*.** A `.txt` beside a
+ *   `.csv` is two text files, not a rendering of one.
+ * - **An ambiguous stem is refused.** `contract.txt` beside both `contract.pdf` and
+ *   `contract.docx` names no one document, and picking either would attach the text of one
+ *   file to a different file's name.
+ * - `.txt.txt` is refused. Whatever it is, it is not a rendering of a text file.
+ */
+export interface DocumentRendition {
+    /** The rel_path of the file this one renders. */
+    source: string;
+}
+export interface RenditionOptions {
+    /** Names of the files in a directory, for finding a same-stem sibling. */
+    entries: (directory: string) => string[];
+}
+export declare function documentRendition(relPath: string, options: RenditionOptions): DocumentRendition | null;
+export interface DocumentPart {
+    /**
+     * The rel_path of part one — the group's identity, whether or not that file exists. Files
+     * sharing one `groupKey` are one document.
+     */
+    groupKey: string;
+    /** 1 for the bare file, `n` for `-<n>`. Parts are ordered by this. */
+    part: number;
+}
+export interface PartOptions {
+    /**
+     * Whether the group's part one exists. Without this check a date-suffixed name invents a
+     * document: the guard is that a part implies something to be a part *of*.
+     */
+    hasPartOne?: (groupKey: string) => boolean;
+}
+export declare function documentPart(relPath: string, options?: PartOptions): DocumentPart;
+//# sourceMappingURL=parts.d.ts.map

package/dist/ingest/parts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parts.d.ts","sourceRoot":"","sources":["../../src/ingest/parts.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,WAAW,iBAAiB;IAChC,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,0EAA0E;IAC1E,OAAO,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,EAAE,CAAC;CAC1C;AAKD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,iBAAiB,GAAG,IAAI,CAmBtG;AAaD,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;CACd;AAID,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;CAC5C;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,YAAY,CAoBrF"}

package/dist/ingest/parts.js

@@ -0,0 +1,52 @@
+import path from 'node:path';
+/** Formats whose text is a copy of somebody else's, so a `.txt` of one adds nothing. */
+const PLAIN = new Set(['.txt', '.md', '.markdown', '.csv', '.tsv', '.json', '.yaml', '.yml', '.log']);
+export function documentRendition(relPath, options) {
+    const normalized = relPath.replaceAll('\\', '/');
+    if (path.posix.extname(normalized).toLowerCase() !== '.txt')
+        return null;
+    const directory = path.posix.dirname(normalized);
+    const stem = path.posix.basename(normalized.slice(0, -'.txt'.length));
+    const siblings = options.entries(directory);
+    const inDirectory = (name) => (directory === '.' ? name : `${directory}/${name}`);
+    // Asked of the folder rather than of the name. Whether a stem "has an extension" cannot be
+    // decided by looking for a dot: `Rental Agreement … A. N. Marlow … Aug 5 2031` has four, and
+    // none of them starts an extension. Whether a file of that exact name is *there* is a fact.
+    if (siblings.includes(stem)) {
+        return isExtractable(stem) ? { source: inDirectory(stem) } : null;
+    }
+    // Otherwise the folder has to hold exactly one document this could be the text of.
+    const candidates = siblings.filter((name) => isExtractable(name) && withoutExtension(name) === stem).sort();
+    return candidates.length === 1 ? { source: inDirectory(candidates[0]) } : null;
+}
+/** A format text is extracted *from*, rather than one that is already text. */
+function isExtractable(name) {
+    const extension = path.posix.extname(name).toLowerCase();
+    return extension.length > 0 && !PLAIN.has(extension);
+}
+function withoutExtension(name) {
+    const extension = path.posix.extname(name);
+    return extension ? name.slice(0, -extension.length) : name;
+}
+const PART_SUFFIX = /^(.*[^\d-])-(\d{1,2})$/;
+export function documentPart(relPath, options = {}) {
+    const normalized = relPath.replaceAll('\\', '/');
+    const extension = path.posix.extname(normalized);
+    const base = path.posix.basename(normalized, extension);
+    const directory = path.posix.dirname(normalized);
+    const match = PART_SUFFIX.exec(base);
+    if (!match)
+        return { groupKey: normalized, part: 1 };
+    const part = Number(match[2]);
+    // 0 is not a part number anyone writes, and a leading-zero form (`-02`) is a page label
+    // from a scanner rather than a sequence Akno should reorder.
+    if (part < 1 || match[2].startsWith('0'))
+        return { groupKey: normalized, part: 1 };
+    const stem = match[1];
+    const groupBase = `${stem}${extension}`;
+    const groupKey = directory === '.' ? groupBase : `${directory}/${groupBase}`;
+    if (options.hasPartOne && !options.hasPartOne(groupKey))
+        return { groupKey: normalized, part: 1 };
+    return { groupKey, part };
+}
+//# sourceMappingURL=parts.js.map

package/dist/ingest/parts.js.map

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

package/dist/ingest/rendition.d.ts

@@ -0,0 +1,75 @@
+import type { Extraction } from './extract.ts';
+/**
+ * The extracted text, written beside the file it came from.
+ *
+ * The text of a stored document already exists — `documents.text`, read once on arrival —
+ * and `read({document})` hands back every character of it. What did not exist is a way for
+ * anything that is *not* Akno to see it: a `grep`, an editor, a git diff, an agent that
+ * has a folder and no socket. The page beside a stored PDF is two sentences on purpose, and
+ * two sentences cannot hold a nine-page lease, so the text had nowhere on disk to live and
+ * the only way back to it was to OCR the PDF again.
+ *
+ * A rendition is that file. It is derived, regenerable and never authoritative: the source
+ * bytes are the document, `documents.text` is what search reads, and this is a convenience
+ * copy that says so in its own first three lines.
+ */
+export interface RenditionSource {
+    relPath: string;
+    text: string;
+    pageCount: number | null;
+    ocr: boolean;
+    via: Extraction['via'];
+    confidence: number | null;
+}
+export interface RenditionGate {
+    minChars: number;
+    /** The `ingest` verb of the folder rule in force for the owning page. */
+    ingestRule: 'page' | 'document' | 'file' | 'auto' | 'ignore' | undefined;
+}
+/**
+ * Whether a document earns a file beside it — and, when it does not, why not.
+ *
+ * An allowlist on `via` rather than a denylist, so a format added later has to say out loud
+ * that its text is the document's own words before those words are written to disk under
+ * the document's name.
+ */
+export declare function renditionWanted(source: RenditionSource, gate: RenditionGate): {
+    write: boolean;
+    reason: string;
+};
+/**
+ * Whether Akno wrote this, judged from the file itself.
+ *
+ * The same question `looksLikeLedger` asks of a `timeline.md`, and answered the same way:
+ * a reserved path that exists and is not what Akno expects is left completely alone.
+ * Somebody who opened `contract.pdf.txt` and fixed three OCR mistakes by hand did something
+ * useful, and reverting it on the next index pass is not a recoverable mistake.
+ */
+export declare function looksLikeRendition(head: string): boolean;
+/**
+ * A provenance header, a blank line, then the text exactly as it is stored.
+ *
+ * The header is three lines against tens of thousands of characters, and it buys the thing
+ * `provenanceLines` exists for: text recognised from a scan at 0.87 confidence is a good
+ * guess, not a transcript, and a file that does not say so invites being quoted as one.
+ *
+ * **No page markers.** The temptation is real — a citation wants "page 9" — but the per-page
+ * sections and the joined text are built separately during extraction and are not the same
+ * string for a PDF with a text layer. A rendition assembled from sections would therefore
+ * hold different bytes from the text `read` returns and the summary was written from: one
+ * document with two texts that can quietly disagree. Page numbers already live where they
+ * survive being checked, on the chunks recall cites.
+ */
+export declare function renditionBody(source: RenditionSource): string;
+/**
+ * Where the text of a document goes: the document's own name, with `.txt` for an extension.
+ *
+ * `contract.txt` beside `contract.pdf` rather than `contract.pdf.txt`, because a document is
+ * one thing and its stem is its name — the same reason `passport.pdf` and `passport-2.pdf`
+ * are one document. Appending instead of replacing produces a second file beside anyone who
+ * already ran `pdftotext`, which is two copies of one text under two names.
+ *
+ * The reader accepts both spellings; only this one is written.
+ */
+export declare function renditionPathFor(relPath: string): string;
+//# sourceMappingURL=rendition.d.ts.map

package/dist/ingest/rendition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rendition.d.ts","sourceRoot":"","sources":["../../src/ingest/rendition.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,GAAG,EAAE,OAAO,CAAC;IACb,GAAG,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC;IACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,UAAU,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;CAC1E;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,eAAe,EACvB,IAAI,EAAE,aAAa,GAClB;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CA2BpC;AAKD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAmB7D;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGxD"}

package/dist/ingest/rendition.js

@@ -0,0 +1,92 @@
+import path from 'node:path';
+/**
+ * Whether a document earns a file beside it — and, when it does not, why not.
+ *
+ * An allowlist on `via` rather than a denylist, so a format added later has to say out loud
+ * that its text is the document's own words before those words are written to disk under
+ * the document's name.
+ */
+export function renditionWanted(source, gate) {
+    if (gate.ingestRule === 'ignore' || gate.ingestRule === 'file') {
+        // `ingest: "file"` means "index the bytes, write me no pages here". A rendition is a
+        // file written into that folder, so the rule covers it for the same reason.
+        return { write: false, reason: `the folder rule says ingest: "${gate.ingestRule}"` };
+    }
+    if (source.text.length === 0)
+        return { write: false, reason: 'nothing was extracted' };
+    // The file already *is* its text. A byte-for-byte copy under a longer name is not a
+    // convenience, it is a second thing to keep in step.
+    if (source.via === 'plain')
+        return { write: false, reason: 'the file is already text' };
+    // A model looking at a photograph and saying what it sees is not the file's words. Writing
+    // that into `garden.jpg.txt` would claim it is, and a reader deciding whether to trust a
+    // number has no way left to tell.
+    if (source.via === 'vision') {
+        return { write: false, reason: "the text is a model's description of an image, not the file's words" };
+    }
+    if (source.via === 'none')
+        return { write: false, reason: 'the text could not be read' };
+    if (source.text.length < gate.minChars) {
+        return {
+            write: false,
+            reason: `${source.text.length} characters is under ingest.text_rendition_min_chars (${gate.minChars})`,
+        };
+    }
+    return { write: true, reason: 'the text is the document’s own and does not fit on its page' };
+}
+/** The first thing in every rendition, and the only claim of authorship there is. */
+const HEADER = '# Extracted text of ';
+/**
+ * Whether Akno wrote this, judged from the file itself.
+ *
+ * The same question `looksLikeLedger` asks of a `timeline.md`, and answered the same way:
+ * a reserved path that exists and is not what Akno expects is left completely alone.
+ * Somebody who opened `contract.pdf.txt` and fixed three OCR mistakes by hand did something
+ * useful, and reverting it on the next index pass is not a recoverable mistake.
+ */
+export function looksLikeRendition(head) {
+    return head.startsWith(HEADER);
+}
+/**
+ * A provenance header, a blank line, then the text exactly as it is stored.
+ *
+ * The header is three lines against tens of thousands of characters, and it buys the thing
+ * `provenanceLines` exists for: text recognised from a scan at 0.87 confidence is a good
+ * guess, not a transcript, and a file that does not say so invites being quoted as one.
+ *
+ * **No page markers.** The temptation is real — a citation wants "page 9" — but the per-page
+ * sections and the joined text are built separately during extraction and are not the same
+ * string for a PDF with a text layer. A rendition assembled from sections would therefore
+ * hold different bytes from the text `read` returns and the summary was written from: one
+ * document with two texts that can quietly disagree. Page numbers already live where they
+ * survive being checked, on the chunks recall cites.
+ */
+export function renditionBody(source) {
+    const name = path.posix.basename(source.relPath.replaceAll('\\', '/'));
+    const pages = source.pageCount !== null ? `${source.pageCount} page${source.pageCount === 1 ? '' : 's'}, ` : '';
+    const confidence = source.confidence !== null ? ` at ${source.confidence.toFixed(2)} mean confidence` : '';
+    const how = source.via === 'ocr'
+        ? `recognised by OCR${confidence}, not typed`
+        : source.via === 'textutil'
+            ? 'converted from the original format'
+            : "read from the file's own text layer";
+    return (`${HEADER}${name}\n` +
+        `# ${pages}${how}.\n` +
+        `# Written by Akno from the file beside it. Edits here are overwritten; edit the source.\n` +
+        `\n${source.text}\n`);
+}
+/**
+ * Where the text of a document goes: the document's own name, with `.txt` for an extension.
+ *
+ * `contract.txt` beside `contract.pdf` rather than `contract.pdf.txt`, because a document is
+ * one thing and its stem is its name — the same reason `passport.pdf` and `passport-2.pdf`
+ * are one document. Appending instead of replacing produces a second file beside anyone who
+ * already ran `pdftotext`, which is two copies of one text under two names.
+ *
+ * The reader accepts both spellings; only this one is written.
+ */
+export function renditionPathFor(relPath) {
+    const extension = path.posix.extname(relPath.replaceAll('\\', '/'));
+    return `${extension ? relPath.slice(0, -extension.length) : relPath}.txt`;
+}
+//# sourceMappingURL=rendition.js.map

package/dist/ingest/rendition.js.map

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