@doxbrix/doxloop 0.1.5 → 0.2.0

package/dist/autosync.js

@@ -0,0 +1,442 @@
+import { readFile, writeFile, rename } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { ProjectBusyError, withProjectLock } from './project-lock.js';
+import { agentAuthenticationStatus, chooseAgent } from './agents.js';
+import { computeDrift, computeDriftFromChanges, formatDrift } from './drift.js';
+import { DoxloopError } from './errors.js';
+import { readEvidenceMap } from './evidence.js';
+import { emitJobOutcome } from './job-events.js';
+import { saveProjectSettings, sourceKind } from './project.js';
+import { heading, note, promptConfirm, promptSelect } from './prompts.js';
+import { monitorRemoteSources } from './remote-monitor.js';
+import { appendSyncLog, formatScheduleFrequency, installSchedule, readSyncLog, removeSchedule, scheduleFrequency, scheduleState, } from './schedule.js';
+import { collectSourceChanges, readSyncState, LOCAL_CONTENT_BASELINE } from './sync.js';
+import { createSyncRun, listSyncRuns, pendingRunCount } from './sync-runs.js';
+const MODE_LABELS = {
+    check: 'Just tell me — write nothing',
+    propose: 'Generate an isolated proposal for review',
+    auto: 'Automatically generate an isolated proposal',
+};
+export function replaySyncSetupCommand(sync) {
+    const parts = ['doxloop sync setup', `--mode ${sync.mode}`];
+    if (sync.branch)
+        parts.push(`--branch ${sync.branch}`);
+    parts.push(`--on ${sync.on.length > 0 ? sync.on.join(',') : 'manual'}`);
+    return parts.join(' ');
+}
+export function parseTriggerList(raw) {
+    if (raw.trim().toLowerCase() === 'manual')
+        return [];
+    if (raw.split(',').filter((value) => value.trim()).length > 1)
+        throw new DoxloopError('Choose one schedule per project; multiple triggers are not supported.');
+    return raw
+        .split(',')
+        .map((value) => value.trim())
+        .filter(Boolean)
+        .map((value) => {
+        if (/^every@\d+[mh]$/.test(value)) {
+            const amount = Number(value.match(/\d+/)?.[0]);
+            if ((value.endsWith('m') && amount >= 1 && amount <= 59) ||
+                (value.endsWith('h') && amount >= 1 && amount <= 24))
+                return value;
+        }
+        const daily = /^daily@(\d{2}):(\d{2})$/.exec(value);
+        if (daily && Number(daily[1]) <= 23 && Number(daily[2]) <= 59) {
+            return value;
+        }
+        const weekdays = /^weekdays@(\d{2}):(\d{2})$/.exec(value);
+        if (weekdays && Number(weekdays[1]) <= 23 && Number(weekdays[2]) <= 59) {
+            return value;
+        }
+        const weekly = /^weekly@(sun|mon|tue|wed|thu|fri|sat)@(\d{2}):(\d{2})$/.exec(value);
+        if (weekly && Number(weekly[2]) <= 23 && Number(weekly[3]) <= 59) {
+            return value;
+        }
+        const monthly = /^monthly@(\d{1,2})@(\d{2}):(\d{2})$/.exec(value);
+        if (monthly && Number(monthly[1]) >= 1 && Number(monthly[1]) <= 28 && Number(monthly[2]) <= 23 && Number(monthly[3]) <= 59) {
+            return value;
+        }
+        throw new DoxloopError(`Invalid --on value "${value}". Use daily@HH:MM, weekdays@HH:MM, weekly@day@HH:MM, monthly@day@HH:MM, every@Nm, every@Nh, or manual.`, 2);
+    });
+}
+export function parseSyncMode(raw) {
+    if (raw === 'check' || raw === 'propose' || raw === 'auto')
+        return raw;
+    throw new DoxloopError(`--mode must be check, propose, or auto.`, 2);
+}
+/** Use provider APIs whenever a remote source is configured. */
+export async function computeConfiguredDrift(root, project) {
+    if (!hasRemoteSources(project))
+        return computeDrift(root, project);
+    const monitored = await monitorRemoteSources(root, project);
+    return computeDriftFromChanges(root, project, monitored.changes);
+}
+const NATIVE_SCHEDULER = { install: installSchedule, remove: removeSchedule, state: scheduleState };
+/**
+ * Apply a sync configuration: persist it, then make the local machine match it.
+ * Installing and removing are the same operation with different inputs, so a
+ * project can move between trigger sets without leaving orphaned jobs behind.
+ * Local folders are checked in place: a Git checkout by its HEAD commit and
+ * working tree, any other folder by the content it held at the last sync.
+ * Nothing is fetched, pulled, or written in the source, so a local folder
+ * needs no remote to be scheduled.
+ */
+export async function applySyncConfig(root, project, sync, scheduler = NATIVE_SCHEDULER) {
+    const frequency = scheduleFrequency(sync.on);
+    const sources = sync.branch
+        ? project.sources.map((source) => source.remote
+            ? { ...source, remote: { ...source.remote, branch: sync.branch } }
+            : source)
+        : project.sources;
+    await saveProjectSettings(root, { sources, sync });
+    const lines = [];
+    if (frequency) {
+        const state = await scheduler.install(root, frequency);
+        lines.push(statusLine('✓', 'Schedule installed', `${formatScheduleFrequency(frequency)} · ${state.label}`));
+        for (const source of sources) {
+            if (sourceKind(source) !== 'directory' || source.remote)
+                continue;
+            lines.push(statusLine('✓', 'Local source', `${source.name} is checked in place; nothing is fetched or written there`));
+        }
+    }
+    else {
+        const existing = await scheduler.state(root);
+        if (existing.installed) {
+            await scheduler.remove(root);
+            lines.push(statusLine('✓', 'Schedule removed', existing.label));
+        }
+    }
+    lines.push(statusLine('✓', 'Settings saved', '.doxloop/project.json'));
+    return lines;
+}
+const LABEL_WIDTH = 20;
+function statusLine(mark, label, detail) {
+    return `  ${mark} ${label.padEnd(LABEL_WIDTH)}${detail}`;
+}
+function pageCount(count) {
+    return `${count} stale page${count === 1 ? '' : 's'}`;
+}
+export async function runSyncSetupWizard(options) {
+    const { root, project, io } = options;
+    const detected = project.sources.find((source) => source.remote)?.remote?.branch;
+    const current = project.sync;
+    const branch = await promptSelect({
+        message: 'Which branch should documentation follow?',
+        choices: [
+            ...(detected
+                ? [{ value: detected, label: detected, hint: 'detected default branch' }]
+                : []),
+            { value: undefined, label: 'Any branch', hint: 'never skip a run' },
+        ],
+        io,
+    });
+    const on = await promptSelect({
+        message: 'When should Doxloop look for drift?',
+        choices: [
+            {
+                value: ['every@15m'],
+                label: 'Every 15 minutes',
+                hint: 'recommended',
+            },
+            { value: ['every@1h'], label: 'Every hour' },
+            { value: ['daily@09:00'], label: 'Daily at 09:00 only' },
+            { value: [], label: 'Only when I run it myself' },
+        ],
+        io,
+    });
+    const mode = await promptSelect({
+        message: 'Documentation is stale. What should happen?',
+        choices: [
+            { value: 'check', label: MODE_LABELS.check, hint: 'no agent runs' },
+            { value: 'propose', label: MODE_LABELS.propose, hint: 'recommended' },
+            { value: 'auto', label: MODE_LABELS.auto },
+        ],
+        initialIndex: 1,
+        io,
+    });
+    const sync = {
+        ...current,
+        mode,
+        ...(branch ? { branch } : {}),
+        on,
+    };
+    heading(io, 'Automatic sync');
+    note(io, [
+        `Follows:      ${project.sources.map((source) => source.path).join(', ') || 'no configured source'}${branch ? ` @ ${branch}` : ''}`,
+        `Checks:       ${describeTriggers(on)}`,
+        `When stale:   ${MODE_LABELS[mode]}`,
+        mode === 'check'
+            ? 'Never:        starts an agent, deploys, or writes documentation'
+            : 'Never:        writes to the product repository or deploys',
+    ].join('\n'));
+    io.output.write('\n');
+    const proceed = await promptConfirm({ message: 'Set this up?', initial: true, io });
+    return proceed ? sync : undefined;
+}
+function describeTriggers(on) {
+    if (on.length === 0)
+        return 'only when you run doxloop check';
+    const parts = [];
+    const frequency = scheduleFrequency(on);
+    if (frequency)
+        parts.push(formatScheduleFrequency(frequency));
+    return parts.join(', ');
+}
+/**
+ * Prove the automation can actually run before anyone depends on it. An expired
+ * agent sign-in is the most common silent failure for unattended runs, so it is
+ * checked here rather than discovered at 09:00 three weeks later.
+ */
+export async function formatSyncStatus(root, project) {
+    const sync = project.sync;
+    const enabled = sync.on.length > 0;
+    const lines = [`Automatic sync: ${enabled ? 'ON' : 'OFF'}`, ''];
+    const syncState = await readSyncState(root);
+    for (const source of project.sources) {
+        if (sourceKind(source) !== 'directory')
+            continue;
+        if (source.remote) {
+            lines.push(statusLine('✓', 'Remote source', `${source.remote.provider}:${source.remote.repository} @ ${source.remote.branch}`));
+            continue;
+        }
+        const record = syncState.sources[source.name];
+        lines.push(statusLine('✓', 'Local source', `${source.name} · ${describeLocalBaseline(record?.commit)}`));
+    }
+    const schedule = await scheduleState(root);
+    const frequency = scheduleFrequency(sync.on);
+    const scheduleName = `${frequency ? formatScheduleFrequency(frequency) : 'installed'} · ${schedule.label}`;
+    if (!schedule.installed) {
+        lines.push(statusLine(frequency ? '✗' : '-', 'Schedule', 'not installed'));
+    }
+    else if (schedule.registered === false) {
+        lines.push(statusLine('✗', 'Schedule', `${scheduleName} · not loaded`));
+    }
+    else if (schedule.lastExitCode === 1) {
+        lines.push(statusLine('!', 'Schedule', `${scheduleName} · last exit 1 (drift or update failure)`));
+    }
+    else if (schedule.lastExitCode !== undefined && schedule.lastExitCode !== 0) {
+        lines.push(statusLine('✗', 'Schedule', `${scheduleName} · last exit ${schedule.lastExitCode}`));
+    }
+    else if (schedule.running) {
+        lines.push(statusLine('✓', 'Schedule', `${scheduleName} · running`));
+    }
+    else if (schedule.lastExitCode === 0) {
+        lines.push(statusLine('✓', 'Schedule', `${scheduleName} · smoke test passed`));
+    }
+    else {
+        lines.push(statusLine('!', 'Schedule', `${scheduleName} · never verified`));
+    }
+    if (sync.mode === 'check') {
+        lines.push(statusLine('-', 'Agent', 'not needed in check mode'));
+    }
+    else {
+        lines.push(await agentStatusLine(project));
+    }
+    const map = await readEvidenceMap(root);
+    lines.push(map
+        ? statusLine('✓', 'Evidence map', `${Object.keys(map.pages).length} page${Object.keys(map.pages).length === 1 ? '' : 's'} tracked`)
+        : statusLine('✗', 'Evidence map', 'missing — run `doxloop update` to build it'));
+    const log = await readSyncLog(root, 1);
+    lines.push('', `  Last run    ${log[0] ?? 'never'}`);
+    const pending = pendingRunCount(await listSyncRuns(root));
+    lines.push(`  Reviews     ${pending === 0 ? 'none pending' : `${pending} pending · open with: doxloop sync review --open`}`);
+    const drift = await computeConfiguredDrift(root, project);
+    lines.push(`  Drift now   ${drift.status === 'current'
+        ? 'none'
+        : drift.status === 'stale'
+            ? `${drift.pages.length} page${drift.pages.length === 1 ? '' : 's'} stale`
+            : 'cannot be determined'}`);
+    if (!enabled)
+        lines.push('', 'Enable it with: doxloop sync setup');
+    return lines.join('\n');
+}
+function describeLocalBaseline(commit) {
+    if (!commit)
+        return 'checked in place; no baseline recorded yet';
+    if (commit === LOCAL_CONTENT_BASELINE)
+        return 'compared by content (no Git history)';
+    return `Git HEAD, baseline ${commit.slice(0, 12)}`;
+}
+async function agentStatusLine(project) {
+    try {
+        const agent = await chooseAgent(project.defaultAgent);
+        const status = await agentAuthenticationStatus(agent);
+        if (status.status === 'authenticated') {
+            return statusLine('✓', 'Agent', `${agent.name}, signed in`);
+        }
+        if (status.status === 'unauthenticated') {
+            return statusLine('✗', 'Agent', status.detail);
+        }
+        return statusLine('-', 'Agent', `${agent.name}, sign-in not verifiable`);
+    }
+    catch (error) {
+        return statusLine('✗', 'Agent', error instanceof Error ? error.message : String(error));
+    }
+}
+export async function runSyncNow(options) {
+    try {
+        return await withProjectLock(options.root, 'monitor', () => withProjectLock(options.root, 'authoring', () => runSyncNowLocked(options), 0), 0);
+    }
+    catch (error) {
+        if (!(error instanceof ProjectBusyError))
+            throw error;
+        await appendSyncLog(options.root, `skipped: ${error.message}`);
+        emitJobOutcome({ kind: 'sync', status: 'skipped', message: error.message });
+        return 1;
+    }
+}
+async function runSyncNowLocked(options) {
+    const { root, project } = options;
+    const frequency = scheduleFrequency(project.sync.on);
+    if (options.trigger === 'schedule' && frequency?.kind === 'interval') {
+        const clockPath = join(root, '.doxloop', 'monitor-interval.json');
+        let last = 0;
+        try {
+            last = Number(JSON.parse(await readFile(clockPath, 'utf8')).startedAt);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        const now = Date.now();
+        if (last > 0 && now >= last && now - last < frequency.minutes * 60_000)
+            return 0;
+        const temporary = `${clockPath}.${randomUUID()}.tmp`;
+        await writeFile(temporary, JSON.stringify({ startedAt: now }), { mode: 0o600 });
+        await rename(temporary, clockPath);
+    }
+    const write = (text) => {
+        if (!options.quiet)
+            process.stdout.write(text);
+    };
+    const monitored = hasRemoteSources(project)
+        ? await monitorRemoteSources(root, project)
+        : undefined;
+    const drift = monitored
+        ? await computeDriftFromChanges(root, project, monitored.changes)
+        : await computeDrift(root, project);
+    const outcome = (status, message, extra = {}) => emitJobOutcome({ kind: 'sync', status, message, pages: drift.pages.length, ...extra });
+    if (drift.status === 'current' && !options.authoring) {
+        await appendSyncLog(root, 'check: no reader-visible changes');
+        write(`${formatDrift(drift)}\n`);
+        outcome('current', 'No reader-visible source changes since the last check.');
+        return 0;
+    }
+    write(`${formatDrift(drift)}\n`);
+    // Without a baseline (no documentation generated or accepted yet) nothing
+    // can be stale, so drafting an update would only spend agent time. Report
+    // it; the first accepted update records the baseline.
+    if (drift.status === 'unknown' && drift.pages.length === 0 && !options.authoring) {
+        const message = drift.notes.some((note) => /no sync baseline/i.test(note))
+            ? 'No documentation has been generated or accepted from these sources yet, so there is nothing to compare. Generate the documentation from the plan first.'
+            : drift.notes[0] ?? 'Doxloop could not determine whether the documentation is current.';
+        await appendSyncLog(root, `check: drift unknown, no update drafted`);
+        outcome('unknown', message);
+        return 1;
+    }
+    if (project.sync.mode === 'check' && !options.authoring) {
+        await appendSyncLog(root, `check: ${pageCount(drift.pages.length)}, reporting only`);
+        if (drift.status === 'stale')
+            outcome('stale', `${pageCount(drift.pages.length)} · monitoring is in check mode, so no proposal was drafted.`);
+        else
+            outcome('unknown', drift.notes[0] ?? 'Doxloop could not determine whether the documentation is current.');
+        return 1;
+    }
+    const pending = !options.authoring && (await listSyncRuns(root)).some((run) => ['generating', 'awaiting-review', 'partially-applied', 'conflicted'].includes(run.status) && !run.archivedAt);
+    if (pending) {
+        const message = 'An existing proposal needs review. Accept, reject, or archive it before monitoring drafts another update.';
+        await appendSyncLog(root, `skipped: ${message}`);
+        outcome('skipped', message);
+        return 1;
+    }
+    let blocked = await authoringBlocker(root, project);
+    if (!blocked && !options.author) {
+        try {
+            const agent = await chooseAgent(options.authoring?.agent ?? project.defaultAgent);
+            const authentication = await agentAuthenticationStatus(agent);
+            if (authentication.status === 'unauthenticated' || (options.trigger === 'schedule' && authentication.status !== 'authenticated'))
+                blocked = `sign in to ${agent.name} before unattended authoring: ${authentication.detail}`;
+        }
+        catch (error) {
+            blocked = error instanceof Error ? error.message : String(error);
+        }
+    }
+    if (blocked) {
+        await appendSyncLog(root, `skipped: ${blocked}`);
+        write(`\nSkipping the documentation update: ${blocked}\n`);
+        outcome('skipped', `${pageCount(drift.pages.length)} · the update was skipped because ${blocked}`);
+        return 1;
+    }
+    await reserveRun(root);
+    await appendSyncLog(root, `proposal: starting for ${pageCount(drift.pages.length)}`);
+    const changes = monitored?.changes ?? await collectSourceChanges(root, project.sources);
+    const proposal = await createSyncRun({
+        root,
+        project,
+        drift,
+        sourceChanges: changes,
+        ...(monitored ? { authoringSources: monitored.project.sources } : {}),
+        ...(monitored ? { nextSyncState: monitored.nextState } : {}),
+        ...(options.trigger ? { trigger: options.trigger } : {}),
+        ...(options.author ? { author: options.author } : {}),
+        ...(options.authoring ? { authoring: options.authoring } : {}),
+    });
+    if (proposal.status === 'failed') {
+        await appendSyncLog(root, `proposal: ${proposal.id} failed: ${proposal.error ?? 'unknown error'}`);
+        write(`\nDocumentation proposal failed: ${proposal.error ?? 'unknown error'}\n`);
+        outcome('failed', `The documentation proposal failed: ${proposal.error ?? 'unknown error'}`, { proposalId: proposal.id });
+        return 1;
+    }
+    await appendSyncLog(root, `proposal: ${proposal.id} ready for review with ${proposal.changes.length} changed files`);
+    write(`\nProposal ${proposal.id} is ready. The actual documentation is unchanged.\nReview and accept changes with:\n  doxloop sync review --open\n`);
+    outcome('proposal', `${options.authoring ? 'The requested update' : pageCount(drift.pages.length)} · proposal ${proposal.id} is ready for review with ${proposal.changes.length} changed file${proposal.changes.length === 1 ? '' : 's'}.`, { proposalId: proposal.id });
+    return 0;
+}
+/** A reason authoring must not start, or undefined when it may proceed. */
+async function authoringBlocker(root, project) {
+    const limit = project.sync.budget?.maxRunsPerDay;
+    if (limit !== undefined && (await runsToday(root)) >= limit) {
+        return `the configured budget of ${limit} run${limit === 1 ? '' : 's'} per day is spent.`;
+    }
+    return undefined;
+}
+async function budgetLedger(root) {
+    const date = new Date().toISOString().slice(0, 10);
+    try {
+        const ledger = JSON.parse(await readFile(join(root, '.doxloop', 'monitor-budget.json'), 'utf8'));
+        if (!Number.isInteger(ledger.count) || ledger.count < 0)
+            throw new DoxloopError('Monitoring budget state is invalid. Repair it before starting another run.');
+        return ledger.date === date ? ledger : { date, count: 0 };
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        // Migrate starts recorded before the durable ledger was introduced.
+        const log = await readSyncLog(root, 100_000);
+        return { date, count: log.filter((line) => line.startsWith(date) && (line.includes('proposal: starting') || line.includes('update: starting'))).length };
+    }
+}
+async function runsToday(root) { return (await budgetLedger(root)).count; }
+async function reserveRun(root) {
+    const ledger = await budgetLedger(root);
+    const path = join(root, '.doxloop', 'monitor-budget.json');
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    await writeFile(temporary, JSON.stringify({ ...ledger, count: ledger.count + 1 }), { mode: 0o600 });
+    await rename(temporary, path);
+}
+export async function disableSync(root, project) {
+    const lines = [];
+    const schedule = await scheduleState(root);
+    if (schedule.installed) {
+        await removeSchedule(root);
+        lines.push(statusLine('✓', 'Schedule removed', schedule.label));
+    }
+    await saveProjectSettings(root, { sync: { ...project.sync, on: [] } });
+    lines.push(statusLine('✓', 'Settings kept', 're-enable with: doxloop sync setup'));
+    return lines;
+}
+function hasRemoteSources(project) {
+    return project.sources.some((source) => sourceKind(source) === 'directory' && source.remote !== undefined);
+}
+//# sourceMappingURL=autosync.js.map

package/dist/batch-artifacts.d.ts

@@ -0,0 +1,81 @@
+import type { AuthoringBatch } from './authoring-batches.js';
+import type { DocumentationPlan } from './types.js';
+export interface BatchArtifacts {
+    /** Project-relative plan slice for the batch. */
+    slice: string;
+    /** Project-relative manifest slice, when the batch has screenshot guides. */
+    manifest?: string;
+    /** Project-relative evidence-map slice. */
+    evidence: string;
+}
+export declare function batchArtifactPaths(index: number): BatchArtifacts;
+/** Write the slices a batch session reads and fills in. */
+export declare function writeBatchArtifacts(workspace: string, plan: DocumentationPlan, batch: AuthoringBatch, slice: Record<string, unknown>, 
+/** Project-relative page files of the batch, for the evidence slice's keys. */
+pageFiles?: string[]): Promise<BatchArtifacts>;
+export interface BatchMergeReport {
+    guides: number;
+    evidencePages: number;
+    problems: string[];
+}
+/** Fold a finished batch's manifest and evidence slices back into the workspace files. */
+export declare function mergeBatchArtifacts(workspace: string, artifacts: BatchArtifacts): Promise<BatchMergeReport>;
+/** Run `worker` over `items` with at most `concurrency` in flight, preserving nothing about order. */
+export declare function runPool<T>(items: readonly T[], concurrency: number, worker: (item: T) => Promise<void>, shouldStop?: () => boolean): Promise<void>;
+/** A promise-chained mutex for the workspace files several sessions share. */
+export declare function createLock(): <T>(task: () => Promise<T>) => Promise<T>;
+export interface CaptureNormalization {
+    /** Steps whose saved image exists and passed the image checks. */
+    verified: string[];
+    /** Steps reset to planned, with the reason. */
+    reset: Array<{
+        step: string;
+        reason: string;
+    }>;
+}
+/**
+ * Decide each step's status from what is on disk, not from the word the agent
+ * wrote. Capture sessions have recorded `captured`, `done`, and `ok`; every
+ * such row failed the manifest check, and a real run retook thirteen images
+ * it already had. A step with a readable, non-blank PNG of usable size at its
+ * recorded path is verified; a step that claims a file it does not have goes
+ * back to planned so the retake knows about it.
+ */
+export declare function normalizeCaptureSteps(guides: Array<{
+    page: string;
+    steps: unknown[];
+}>, imageAt: (file: string) => {
+    width: number;
+    height: number;
+    blank: boolean;
+} | undefined): CaptureNormalization;
+/** Normalize the steps of a manifest file (a capture slice or the main manifest) against the images in the workspace. */
+export declare function normalizeCaptureManifest(workspace: string, manifestFile: string): Promise<CaptureNormalization>;
+/** Files a session read, grouped by configured source name, source-relative. */
+export type SessionSourceReads = Map<string, Set<string>>;
+/**
+ * Map the absolute paths a session opened to the configured sources they
+ * live in. Only files under a source count; a page the agent re-read or a
+ * cache file is not evidence.
+ */
+export declare function attributeReadsToSources(paths: Iterable<string>, sources: ReadonlyArray<{
+    name: string;
+    path: string;
+}>, workspace: string): SessionSourceReads;
+/** Paths named in a tool call: Read/Grep targets and the file arguments of a shell command. */
+export declare function pathsInToolCall(tool: string, input: Record<string, unknown>): string[];
+/**
+ * Doxloop owns the evidence map. An agent-written slice is input, not truth:
+ * its claims are kept, its source paths are kept only where the file exists,
+ * and the plan's citations plus the files this session actually read are
+ * always present. A page whose entry names no path it can be checked
+ * against is `inferred`, whatever the agent wrote.
+ */
+export declare function reconcileEvidenceSlice(workspace: string, sliceFile: string, plan: Pick<DocumentationPlan, 'target'>, pages: DocumentationPlan['pages'], sources: ReadonlyArray<{
+    name: string;
+    path: string;
+}>, reads: SessionSourceReads): Promise<{
+    pages: number;
+    droppedPaths: number;
+}>;
+//# sourceMappingURL=batch-artifacts.d.ts.map