@zenera/cli 1.1.23 → 1.1.25

package/dist/meta/finetune/command.js

@@ -0,0 +1,338 @@
+import { liveHolder } from '@zenera/neo';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { editorFiles } from "../editor.js";
+import { bold, cyan, dim, green, invalidError, json, note, parse, red, usageError, write, yellow, } from "../host.js";
+import { drift } from "./dataset/drift.js";
+import { DatasetStore } from "./dataset/store.js";
+import { runLoop } from "./loop.js";
+import { attemptsOf } from "./report.js";
+import { retry } from "./retry.js";
+import { resultOf, selection } from "./sampler.js";
+import { DEFAULTS, FAILURES_IN_A_ROW, FINETUNE_DIR, LEGACY_FINETUNE_DIR, spawnZen, Tuning, } from "./tuning.js";
+// ---------------------------------------------------------------------------
+// zen meta finetune
+// ---------------------------------------------------------------------------
+export const FINETUNE_USAGE = 'zen meta finetune <start|status|stop|retry|session> [options]';
+export const FINETUNE_HELP = [
+    'Tuning:',
+    '  zen meta finetune start [options]         train every case: run, analyze, apply, run again',
+    '  zen meta finetune [status]                where it stands; the detail is finetune/STATUS.md',
+    '  zen meta finetune stop                    finish the steps in flight, then stop',
+    '  zen meta finetune retry --difficult       give difficult cases another round, then start',
+    "  zen meta finetune session <case>          resume that case's analyze session",
+    '',
+    '  start: -N <workers> (4), -M <apply at> (= workers), --tries <n> (4), --mem-tries <n> (3),',
+    '  --merge-every <k> (3), --seed <n>, --class <c>, --id <glob>, --rubric yes|no, --limit <n>,',
+    '  --force (past drift).',
+    '  In a terminal start draws what runs now, the tokens and the log; --plain does not.',
+    '  Settings are kept in finetune/loop.json; start again to resume where it stopped.',
+];
+export const FINETUNE_SUMMARY = "Tune the project's prose on its dataset, a case at a time, N cases at once.";
+/** The page `zen meta finetune --help` prints. */
+export const FINETUNE_DETAILS = [
+    'Verbs:',
+    '  start                  Train every case: run, analyze, apply, run again. Resumes.',
+    '  status                 Where it stands (the default). The detail: finetune/STATUS.md',
+    '  stop                   Let the steps in flight finish, then stop the running tuning.',
+    '  retry [ids...]         Another round for difficult cases: --difficult takes them all,',
+    '                         ids and globs add to it, --class narrows. Run them with start.',
+    "  session <case>         Print the command that resumes that case's analyze session.",
+    '',
+    'Options for start:',
+    '  -N, --workers <n>      Cases trained at once. Default 4.',
+    '  -M, --apply-at <n>     Apply once this many requests wait. Default: the workers.',
+    '  --tries <n>            Tries without memory before a case is difficult. Default 4.',
+    '  --mem-tries <n>        Tries with memory. Default 3.',
+    '  --merge-every <k>      Merge the kept memories after k more arrive. Default 3.',
+    '  --seed <n>             Order of cases inside a class. Default 1.',
+    '  --class <c>            Only this class. Repeatable.',
+    '  --id <glob>            Only cases whose id matches. Repeatable.',
+    '  --rubric yes|no        Only cases with, or without, a rubric.',
+    '  --limit <n>            Only the first n cases of the order.',
+    '  --force                Start even though the dataset drifted from its sources.',
+    '  --plain                No live view: print a line per start and stop, as in a pipe.',
+    '  --project <name|dir>   Which project. Default: the one you are in.',
+    '',
+    'One case: without memory, run it and /analyze it until the analysis says done -',
+    'parking it until the next apply after each try that is not - then the same with',
+    'the memory the passing run wrote. Tries used up: the case is difficult.',
+    '',
+    'No run shares a memory: each try has its own private directory. A case whose',
+    'with-memory run passes submits a copy of that memory; every k submissions are',
+    'merged, with the last merge, into finetune/memories/merged/mNN - numbered,',
+    'never rewritten, each listing the cases it holds.',
+    '',
+    'A parked case gives its worker back, so another case runs meanwhile; woken cases',
+    'take a worker before new ones. Requests are applied in batches by /finetune-apply:',
+    'when -M cases are parked, or once nothing is running and no case is left to start.',
+    'No run starts during an apply. zen check must pass,',
+    'or the edit is undone. Every apply is a new version of agents.yaml + agents/.',
+    '',
+    'A case is difficult when its tries run out and the analysis still says no; that is',
+    'final for its revision until `retry` gives it another round on the prose of the day.',
+    'A case fails instead when something outside the prose broke - the sandbox, a',
+    'provider, a key: it keeps its tries and carries on from that step at the next start.',
+    `After ${FAILURES_IN_A_ROW} failures in a row the tuning stops, and says what broke;`,
+    'a container engine that fails stops it at once. A run its analysis finds void -',
+    'the network or a service under it down - is set aside and runs again.',
+    '',
+    'Ctrl-C (or stop) finishes the steps in flight; Ctrl-C again kills them. Start',
+    'again to carry on: every step is kept on disk, and nothing finished is repeated.',
+    'Settings given to start are kept in finetune/loop.json.',
+    '',
+    'Examples:',
+    '  zen meta finetune start -N 4',
+    '  zen meta finetune start --class search --limit 6 -N 2 -M 2',
+    '  zen meta finetune',
+    '  zen meta finetune retry --difficult --class merge',
+    '  zen meta finetune session plan-day',
+];
+const OPTIONS = {
+    project: { type: 'string' },
+    workers: { type: 'string', short: 'N' },
+    'apply-at': { type: 'string', short: 'M' },
+    tries: { type: 'string' },
+    'mem-tries': { type: 'string' },
+    'merge-every': { type: 'string' },
+    seed: { type: 'string' },
+    class: { type: 'string', multiple: true },
+    id: { type: 'string', multiple: true },
+    rubric: { type: 'string' },
+    limit: { type: 'string' },
+    force: { type: 'boolean' },
+    plain: { type: 'boolean' },
+    difficult: { type: 'boolean' },
+    yes: { type: 'boolean' },
+};
+export function finetuneProjectFlag(args) {
+    return parse(args, OPTIONS, FINETUNE_USAGE).values.project;
+}
+export async function runFinetune(ctx, project, options = {}) {
+    const { values, positionals } = parse(ctx.args, OPTIONS, FINETUNE_USAGE);
+    const [verb = 'status', ...rest] = positionals;
+    moveLegacyDir(project.dir);
+    switch (verb) {
+        case 'start':
+            return start(ctx, project, values, options);
+        case 'status':
+            return status(ctx, project);
+        case 'stop':
+            return stop(project);
+        case 'retry':
+            return retryCases(ctx, project, values, rest);
+        case 'session':
+            return session(project, rest);
+        default:
+            throw usageError(`unknown finetune verb: ${verb}`, 'one of: start, status, stop, retry, session');
+    }
+}
+/**
+ * A tuning used to live in `.finetune/`. Moves it to `finetune/` once, so a
+ * project tuned before the rename resumes where it stopped. Refuses while a
+ * loop of the old version still holds its lock there: renaming its folder out
+ * from under it would split one tuning across two directories.
+ */
+export function moveLegacyDir(projectDir) {
+    const legacy = join(projectDir, LEGACY_FINETUNE_DIR);
+    const current = join(projectDir, FINETUNE_DIR);
+    if (!existsSync(legacy)) {
+        return;
+    }
+    if (existsSync(current)) {
+        note(yellow(`both ${LEGACY_FINETUNE_DIR}/ and ${FINETUNE_DIR}/ exist; using ${FINETUNE_DIR}/ - remove ${LEGACY_FINETUNE_DIR}/ once nothing in it is wanted`));
+        return;
+    }
+    const holder = liveHolder(join(legacy, 'loop.lock'));
+    if (holder) {
+        throw invalidError(`a tuning is still running in ${LEGACY_FINETUNE_DIR}/ (pid ${holder.pid})`, `let it finish or stop that process, then run this again to move it to ${FINETUNE_DIR}/`);
+    }
+    renameSync(legacy, current);
+    note(dim(`moved ${LEGACY_FINETUNE_DIR}/ to ${FINETUNE_DIR}/`));
+}
+function whole(text, flag, min = 1) {
+    if (text === undefined) {
+        return undefined;
+    }
+    const n = Number(text);
+    if (!Number.isInteger(n) || n < min) {
+        throw usageError(`${flag} takes a whole number of at least ${min}`, `got "${text}"`);
+    }
+    return n;
+}
+const configFile = (dir) => join(dir, FINETUNE_DIR, 'loop.json');
+export function readConfig(dir) {
+    try {
+        return {
+            ...DEFAULTS,
+            ...JSON.parse(readFileSync(configFile(dir), 'utf8')),
+        };
+    }
+    catch {
+        return { ...DEFAULTS };
+    }
+}
+function configFrom(dir, v) {
+    const saved = readConfig(dir);
+    const workers = whole(v.workers, '-N') ?? saved.workers;
+    if (v.rubric !== undefined && v.rubric !== 'yes' && v.rubric !== 'no') {
+        throw usageError('--rubric takes yes or no');
+    }
+    const config = {
+        ...saved,
+        workers,
+        applyAt: whole(v['apply-at'], '-M') ?? (v.workers ? workers : saved.applyAt),
+        tries: whole(v.tries, '--tries') ?? saved.tries,
+        memTries: whole(v['mem-tries'], '--mem-tries') ?? saved.memTries,
+        mergeEvery: whole(v['merge-every'], '--merge-every') ?? saved.mergeEvery,
+        seed: whole(v.seed, '--seed', 0) ?? saved.seed,
+        ...(v.class ? { classes: v.class } : {}),
+        ...(v.id ? { ids: v.id } : {}),
+        ...(v.rubric ? { rubric: v.rubric === 'yes' } : {}),
+        ...(v.limit ? { limit: whole(v.limit, '--limit') } : {}),
+    };
+    mkdirSync(join(dir, FINETUNE_DIR), { recursive: true });
+    writeFileSync(configFile(dir), `${JSON.stringify(config, null, 2)}\n`);
+    return config;
+}
+async function start(ctx, project, values, options) {
+    const store = DatasetStore.open(project.dir);
+    if (!store.exists()) {
+        throw invalidError('there is no dataset to tune on', 'build one: zen meta run /dataset');
+    }
+    const report = drift(store);
+    if (!report.clean && !values.force) {
+        throw invalidError(`the dataset has drifted from its sources (${report.cases.length} case(s), ${report.uncovered.length} section(s))`, 'refresh it: zen meta run /dataset - or start with --force');
+    }
+    const config = configFrom(project.dir, values);
+    const children = new Set();
+    const t = new Tuning(project.dir, config, options.zen ?? spawnZen(project.dir, children), options.tickMs);
+    if (!options.zen) {
+        editorFiles(project.dir);
+    }
+    let interrupts = 0;
+    let drawing = false;
+    const onInterrupt = () => {
+        interrupts++;
+        if (interrupts === 1) {
+            if (!drawing) {
+                note(yellow('stopping: the steps in flight finish first - Ctrl-C again to kill them'));
+            }
+            t.stop('interrupted');
+            return;
+        }
+        for (const child of children) {
+            try {
+                process.kill(-child.pid, 'SIGTERM');
+            }
+            catch {
+                // Already gone.
+            }
+        }
+        process.exit(130);
+    };
+    process.on('SIGINT', onInterrupt);
+    note(`${bold('tuning')} ${project.name} · ${config.workers} workers · apply at ${config.applyAt}`);
+    note(dim(`follow it: file://${join(t.dir, 'STATUS.html')}`));
+    let close;
+    if (!ctx.json && !values.plain && !options.zen && process.stderr.isTTY && process.stdin.isTTY) {
+        const { watch } = await import("./tui.js");
+        close = await watch(t, onInterrupt);
+        drawing = true;
+    }
+    try {
+        await runLoop(t);
+    }
+    finally {
+        close?.();
+        process.off('SIGINT', onInterrupt);
+    }
+    if (!ctx.json) {
+        await status(ctx, project);
+    }
+}
+function counts(dir) {
+    const t = new Tuning(dir, readConfig(dir), async () => ({ code: 1, stdout: '' }));
+    const out = { total: 0, queued: 0, stopped: 0, completed: 0, difficult: 0, failed: 0 };
+    for (const c of selection(t)) {
+        out.total++;
+        const r = resultOf(t, c);
+        if (r) {
+            out[r.state]++;
+        }
+        else if (attemptsOf(t, c).length > 0) {
+            out.stopped++;
+        }
+        else {
+            out.queued++;
+        }
+    }
+    return out;
+}
+function status(ctx, project) {
+    const dir = join(project.dir, FINETUNE_DIR);
+    if (!DatasetStore.open(project.dir).exists()) {
+        throw invalidError('there is no dataset to tune on', 'build one: zen meta run /dataset');
+    }
+    const holder = liveHolder(join(dir, 'loop.lock'));
+    const c = counts(project.dir);
+    if (ctx.json) {
+        return json({
+            running: Boolean(holder),
+            ...c,
+            status: join(dir, 'STATUS.md'),
+            html: join(dir, 'STATUS.html'),
+        });
+    }
+    write(`${bold(project.name)}  ${holder ? green(`running (pid ${holder.pid})`) : dim('not running')}`);
+    write(`${c.total} cases: ${green(`${c.completed} completed`)}, ${yellow(`${c.difficult} difficult`)}, ${c.failed ? `${red(`${c.failed} failed`)}, ` : ''}${c.stopped} part-way, ${c.queued} not started`);
+    if (!holder && c.queued + c.stopped + c.failed > 0) {
+        note(dim(`${c.stopped + c.failed > 0 ? 'resume it' : 'start it'}: ${cyan(`zen meta ${project.name} finetune start`)} [-N <workers>] - see zen meta finetune --help`));
+    }
+    if (!holder && c.difficult > 0) {
+        note(dim(`another round for the difficult ones: ${cyan(`zen meta ${project.name} finetune retry --difficult`)}`));
+    }
+    if (existsSync(join(dir, 'STATUS.md'))) {
+        note(dim(`the detail: ${cyan(join(dir, 'STATUS.md'))} · ${cyan(`file://${join(dir, 'STATUS.html')}`)}`));
+    }
+}
+function stop(project) {
+    const dir = join(project.dir, FINETUNE_DIR);
+    if (!liveHolder(join(dir, 'loop.lock'))) {
+        note('no tuning is running here');
+        return;
+    }
+    writeFileSync(join(dir, 'stop'), `${new Date().toISOString()}\n`);
+    note('asked it to stop: the steps in flight finish first');
+}
+async function retryCases(ctx, project, values, ids) {
+    const t = new Tuning(project.dir, readConfig(project.dir), async () => ({
+        code: 1,
+        stdout: '',
+    }));
+    const plan = await retry(t, {
+        difficult: values.difficult,
+        classes: values.class,
+        ids: [...ids, ...(values.id ?? [])],
+        yes: values.yes,
+    });
+    if (ctx.json) {
+        json({ retried: plan.take.map((c) => c.id), skipped: plan.skip, tokens: plan.tokens });
+    }
+}
+function session(project, rest) {
+    const [id] = rest;
+    if (!id) {
+        throw usageError('session of which case?', 'zen meta finetune session <case>');
+    }
+    const c = DatasetStore.open(project.dir).get(id);
+    if (!c) {
+        throw invalidError(`no case ${id}`);
+    }
+    const file = join(project.dir, FINETUNE_DIR, 'cases', id, `r${c.rev}`, 'session');
+    if (!existsSync(file)) {
+        throw invalidError(`${id} has not been analyzed yet at revision ${c.rev}`);
+    }
+    write(`zen meta resume ${project.name} ${readFileSync(file, 'utf8').trim()}`);
+}
+//# sourceMappingURL=command.js.map

package/dist/meta/finetune/dataset/anchors.d.ts

@@ -0,0 +1,41 @@
+import { type Anchor } from './types.ts';
+export type Found = {
+    found: true;
+    text: string;
+    sha256: string;
+} | {
+    found: false;
+    why: 'no file' | 'not found' | 'ambiguous' | 'unreadable';
+};
+interface Heading {
+    level: number;
+    title: string;
+    path: string[];
+    /** first line, and one past the last line of its section */
+    start: number;
+    end: number;
+}
+export declare const sha256: (text: string) => string;
+/** Every ATX heading outside a code fence, with the extent of its section. */
+export declare function headingsOf(text: string): Heading[];
+/** Sorted keys, so reformatting or reordering a document is not a change. */
+export declare function canonical(value: unknown): string;
+/** One read of each file per instance: a drift check asks about many cases per file. */
+export declare class Sources {
+    #private;
+    readonly root: string;
+    constructor(root: string);
+    text(file: string): string | undefined;
+    /** Of the bytes as they are: any edit at all, even one no case sees. */
+    hash(file: string): string | undefined;
+    section(file: string, anchor: Anchor | undefined): Found;
+    /**
+     * Sections of a file no case and no ignore accounts for: headings at the
+     * levels the covered ones sit at, or the siblings of covered pointers. A
+     * section inside a covered one is part of that case, and a section around one
+     * is its context, so neither is reported.
+     */
+    uncovered(file: string, covered: readonly (Anchor | undefined)[]): Anchor[];
+}
+export {};
+//# sourceMappingURL=anchors.d.ts.map

package/dist/meta/finetune/dataset/anchors.js

@@ -0,0 +1,239 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { extname, resolve } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import {} from "./types.js";
+export const sha256 = (text) => createHash('sha256').update(text).digest('hex');
+const normal = (text) => text
+    .replace(/\r\n?/g, '\n')
+    .split('\n')
+    .map((line) => line.trimEnd())
+    .join('\n')
+    .replace(/\n+$/, '');
+const title = (text) => text.replace(/\s+/g, ' ').trim();
+/** Every ATX heading outside a code fence, with the extent of its section. */
+export function headingsOf(text) {
+    const lines = text.replace(/\r\n?/g, '\n').split('\n');
+    const found = [];
+    const stack = [];
+    let fence;
+    lines.forEach((line, i) => {
+        const marker = /^ {0,3}(`{3,}|~{3,})/.exec(line);
+        if (marker) {
+            const char = marker[1][0];
+            if (!fence) {
+                fence = { char, size: marker[1].length };
+            }
+            else if (fence.char === char && marker[1].length >= fence.size) {
+                fence = undefined;
+            }
+            return;
+        }
+        if (fence) {
+            return;
+        }
+        const m = /^ {0,3}(#{1,6})(?:[ \t]+(.*?))?(?:[ \t]+#+)?[ \t]*$/.exec(line);
+        if (!m || !m[2]?.trim()) {
+            return;
+        }
+        const level = m[1].length;
+        while (stack.length > 0 && stack[stack.length - 1].level >= level) {
+            stack.pop();
+        }
+        const heading = {
+            level,
+            title: title(m[2]),
+            path: [...stack.map((h) => h.title), title(m[2])],
+            start: i,
+            end: lines.length,
+        };
+        stack.push(heading);
+        found.push(heading);
+    });
+    for (let i = 0; i < found.length; i++) {
+        const next = found.slice(i + 1).find((h) => h.level <= found[i].level);
+        found[i].end = next ? next.start : lines.length;
+    }
+    return found;
+}
+/**
+ * The last name must be the heading's own; the names before it must appear, in
+ * order, among its ancestors. So `["Query: organize my day"]` is enough while it
+ * is unique, and an author adds a parent only to tell two apart.
+ */
+function matches(path, heading) {
+    const want = path.map(title);
+    if (want[want.length - 1] !== heading.title) {
+        return false;
+    }
+    let at = 0;
+    for (const name of heading.path.slice(0, -1)) {
+        if (at < want.length - 1 && name === want[at]) {
+            at++;
+        }
+    }
+    return at === want.length - 1;
+}
+/** RFC 6901, over a parsed JSON or YAML document. */
+function follow(doc, pointer) {
+    if (pointer === '') {
+        return { ok: true, value: doc };
+    }
+    let at = doc;
+    for (const raw of pointer.slice(1).split('/')) {
+        const key = raw.replace(/~1/g, '/').replace(/~0/g, '~');
+        if (Array.isArray(at) && /^\d+$/.test(key) && Number(key) < at.length) {
+            at = at[Number(key)];
+        }
+        else if (at !== null && typeof at === 'object' && !Array.isArray(at) && key in at) {
+            at = at[key];
+        }
+        else {
+            return { ok: false };
+        }
+    }
+    return { ok: true, value: at };
+}
+const escapeKey = (key) => key.replace(/~/g, '~0').replace(/\//g, '~1');
+/** Sorted keys, so reformatting or reordering a document is not a change. */
+export function canonical(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map(canonical).join(',')}]`;
+    }
+    if (value !== null && typeof value === 'object') {
+        const keys = Object.keys(value).sort();
+        return `{${keys
+            .map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}
+/** One read of each file per instance: a drift check asks about many cases per file. */
+export class Sources {
+    root;
+    #text = new Map();
+    #headings = new Map();
+    #docs = new Map();
+    constructor(root) {
+        this.root = root;
+    }
+    text(file) {
+        if (!this.#text.has(file)) {
+            let text;
+            try {
+                text = readFileSync(resolve(this.root, file), 'utf8');
+            }
+            catch {
+                text = undefined;
+            }
+            this.#text.set(file, text);
+        }
+        return this.#text.get(file);
+    }
+    /** Of the bytes as they are: any edit at all, even one no case sees. */
+    hash(file) {
+        const text = this.text(file);
+        return text === undefined ? undefined : sha256(text);
+    }
+    #headingsOf(file, text) {
+        let found = this.#headings.get(file);
+        if (!found) {
+            found = headingsOf(text);
+            this.#headings.set(file, found);
+        }
+        return found;
+    }
+    #doc(file, text) {
+        let parsed = this.#docs.get(file);
+        if (!parsed) {
+            try {
+                const ext = extname(file).toLowerCase();
+                parsed = { ok: true, doc: ext === '.json' ? JSON.parse(text) : parseYaml(text) };
+            }
+            catch {
+                parsed = { ok: false };
+            }
+            this.#docs.set(file, parsed);
+        }
+        return parsed;
+    }
+    section(file, anchor) {
+        const text = this.text(file);
+        if (text === undefined) {
+            return { found: false, why: 'no file' };
+        }
+        if (anchor?.heading) {
+            const hits = this.#headingsOf(file, text).filter((h) => matches(anchor.heading, h));
+            if (hits.length !== 1) {
+                return { found: false, why: hits.length === 0 ? 'not found' : 'ambiguous' };
+            }
+            const lines = text.replace(/\r\n?/g, '\n').split('\n');
+            const body = normal(lines.slice(hits[0].start, hits[0].end).join('\n'));
+            return { found: true, text: body, sha256: sha256(body) };
+        }
+        if (anchor?.pointer !== undefined) {
+            const parsed = this.#doc(file, text);
+            if (!parsed.ok) {
+                return { found: false, why: 'unreadable' };
+            }
+            const hit = follow(parsed.doc, anchor.pointer);
+            if (!hit.ok) {
+                return { found: false, why: 'not found' };
+            }
+            const body = canonical(hit.value);
+            return { found: true, text: body, sha256: sha256(body) };
+        }
+        const body = normal(text);
+        return { found: true, text: body, sha256: sha256(body) };
+    }
+    /**
+     * Sections of a file no case and no ignore accounts for: headings at the
+     * levels the covered ones sit at, or the siblings of covered pointers. A
+     * section inside a covered one is part of that case, and a section around one
+     * is its context, so neither is reported.
+     */
+    uncovered(file, covered) {
+        const text = this.text(file);
+        if (text === undefined || covered.some((a) => !a?.heading && a?.pointer === undefined)) {
+            return [];
+        }
+        const out = [];
+        const paths = covered.flatMap((a) => (a?.heading ? [a.heading] : []));
+        if (paths.length > 0) {
+            const all = this.#headingsOf(file, text);
+            const hit = all.filter((h) => paths.some((p) => matches(p, h)));
+            const levels = new Set(hit.map((h) => h.level));
+            const near = (h) => hit.some((c) => c === h ||
+                (c.start <= h.start && h.start < c.end) ||
+                (h.start <= c.start && c.start < h.end));
+            for (const h of all) {
+                if (levels.has(h.level) && !near(h)) {
+                    out.push({ heading: h.path });
+                }
+            }
+        }
+        const pointers = covered.flatMap((a) => (a?.pointer ? [a.pointer] : []));
+        if (pointers.length > 0) {
+            const parsed = this.#doc(file, text);
+            const taken = new Set(pointers);
+            const parents = new Set(pointers.map((p) => p.slice(0, p.lastIndexOf('/'))));
+            for (const parent of parents) {
+                const hit = parsed.ok ? follow(parsed.doc, parent) : { ok: false };
+                if (!hit.ok || hit.value === null || typeof hit.value !== 'object') {
+                    continue;
+                }
+                const keys = Array.isArray(hit.value)
+                    ? hit.value.map((_, i) => String(i))
+                    : Object.keys(hit.value);
+                for (const key of keys) {
+                    const pointer = `${parent}/${escapeKey(key)}`;
+                    if (!taken.has(pointer)) {
+                        out.push({ pointer });
+                    }
+                }
+            }
+        }
+        return out;
+    }
+}
+//# sourceMappingURL=anchors.js.map

package/dist/meta/finetune/dataset/changes.d.ts

@@ -0,0 +1,36 @@
+import type { Proposed, ProposedRubric } from './schema.ts';
+import type { Commit, DatasetStore } from './store.ts';
+import { type By, type Case, type Manifest, type RubricItem } from './types.ts';
+export interface Plan extends Commit {
+    /** cases that were looked at and found the same */
+    unchanged: string[];
+}
+/**
+ * Rubric items keep their ids across edits, so a note saying `r3 failed` still
+ * means the same line. An explicit id wins; otherwise the same words are the
+ * same item; anything else is new.
+ */
+export declare function assignRubric(before: readonly RubricItem[], proposed: readonly ProposedRubric[]): RubricItem[];
+/**
+ * A proposal, applied. Whole by default: an active case the proposal does not
+ * name is retired. `partial` touches only the cases it names — what a refresh
+ * of a few drifted sections writes.
+ */
+export declare function planApply(store: DatasetStore, proposed: readonly Proposed[], options: {
+    partial: boolean;
+    why: string;
+    by: By;
+}): Plan;
+/** One case, changed by hand. `override` keeps the change through later re-extractions. */
+export declare function planEdit(store: DatasetStore, id: string, edit: (c: Case) => Case, options: {
+    why: string;
+    by: By;
+    override?: readonly string[];
+}): Plan;
+export declare function planStatus(store: DatasetStore, ids: readonly string[], status: Case['status'], options: {
+    why: string;
+    by: By;
+}): Plan;
+/** The ignore list changed: no case moves, so no revision; the manifest is rewritten. */
+export declare function planIgnored(store: DatasetStore, ignored: Manifest['ignored']): Plan;
+//# sourceMappingURL=changes.d.ts.map