@unbrained/pm-cli 2026.7.14 → 2026.7.16

package/dist/sdk/history-compact.d.ts

@@ -0,0 +1,142 @@
+import { type HistoryCompactBulkSkipReason, type HistoryCompactScope } from "../core/history/history-compact-bulk.js";
+import type { GlobalOptions } from "../core/shared/command-types.js";
+/** Documents the history compact command options payload exchanged by command, SDK, and package integrations. */
+export interface HistoryCompactCommandOptions {
+    /** Value that configures or reports before for this contract. */
+    before?: string;
+    /** Value that configures or reports dry run for this contract. */
+    dryRun?: boolean;
+    /** Value that configures or reports author for this contract. */
+    author?: string;
+    /** Human-readable explanation suitable for logs and agent-facing output. */
+    message?: string;
+    /** Value that configures or reports force for this contract. */
+    force?: boolean;
+}
+type HistoryCompactBoundaryKind = "default" | "version" | "timestamp";
+/** Documents the history compact result payload exchanged by command, SDK, and package integrations. */
+export interface HistoryCompactResult {
+    /** Stable identifier used to reference this record across commands and storage. */
+    id: string;
+    /** Value that configures or reports dry run for this contract. */
+    dry_run: boolean;
+    /** Value that configures or reports changed for this contract. */
+    changed: boolean;
+    /** Value that configures or reports compact boundary for this contract. */
+    compact_boundary: {
+        kind: HistoryCompactBoundaryKind;
+        before: string | null;
+        entries_compacted: number;
+        entries_retained: number;
+        first_retained_entry: number | null;
+    };
+    /** Value that configures or reports history for this contract. */
+    history: {
+        path: string;
+        entries_scanned: number;
+        entries_after: number;
+        baseline_entry_added: boolean;
+        audit_entry_added: boolean;
+        verify_ok: boolean;
+        verify_errors: string[];
+    };
+    /** Value that configures or reports item for this contract. */
+    item: {
+        exists: boolean;
+        path: string | null;
+        matched_chain_before: boolean | null;
+    };
+    /** Value that configures or reports warnings for this contract. */
+    warnings: string[];
+    /** ISO 8601 timestamp recording when generated occurred. */
+    generated_at: string;
+}
+/** Implements run history compact for the public runtime surface of this module. */
+export declare function runHistoryCompact(id: string, options: HistoryCompactCommandOptions, global: GlobalOptions): Promise<HistoryCompactResult>;
+/** Default entry floor below which a stream is treated as already compact. */
+export declare const HISTORY_COMPACT_BULK_DEFAULT_MIN_ENTRIES = 3;
+/** Documents the bulk history compact command options payload exchanged by command, SDK, and package integrations. */
+export interface HistoryCompactBulkCommandOptions {
+    /** Value that configures or reports ids for this contract. */
+    ids?: string[];
+    /** Value that configures or reports scope for this contract. */
+    scope?: HistoryCompactScope;
+    /** Value that configures or reports all over for this contract. */
+    allOver?: number;
+    /** Value that configures or reports min entries for this contract. */
+    minEntries?: number;
+    /** Value that configures or reports dry run for this contract. */
+    dryRun?: boolean;
+    /** Value that configures or reports author for this contract. */
+    author?: string;
+    /** Human-readable explanation suitable for logs and agent-facing output. */
+    message?: string;
+    /** Value that configures or reports force for this contract. */
+    force?: boolean;
+}
+/** Per-item outcome row in a bulk compaction pass. */
+export interface HistoryCompactBulkItemResult {
+    /** Stable identifier used to reference this record across commands and storage. */
+    id: string;
+    /** Value that configures or reports outcome for this contract. */
+    outcome: "compacted" | "skipped" | "errored";
+    /** Value that configures or reports entries before for this contract. */
+    entries_before: number;
+    /** Value that configures or reports entries after for this contract. */
+    entries_after: number | null;
+    /** Value that configures or reports skip reason for this contract. */
+    skip_reason: HistoryCompactBulkSkipReason | null;
+    /** Value that configures or reports changed for this contract. */
+    changed: boolean;
+    /** Value that configures or reports error for this contract. */
+    error: string | null;
+}
+/** Documents the bulk history compact result payload exchanged by command, SDK, and package integrations. */
+export interface HistoryCompactBulkResult {
+    /** Value that configures or reports bulk for this contract. */
+    bulk: true;
+    /** Value that configures or reports dry run for this contract. */
+    dry_run: boolean;
+    /** Value that configures or reports mode for this contract. */
+    mode: "ids" | "scan";
+    /** Value that configures or reports scope for this contract. */
+    scope: HistoryCompactScope | null;
+    /** Value that configures or reports criteria for this contract. */
+    criteria: {
+        min_entries: number;
+        all_over: number | null;
+        policy_threshold_applied: boolean;
+    };
+    /** Value that configures or reports totals for this contract. */
+    totals: {
+        streams_considered: number;
+        selected: number;
+        items_compacted: number;
+        items_skipped: number;
+        items_errored: number;
+    };
+    /** Value that configures or reports results for this contract. */
+    results: HistoryCompactBulkItemResult[];
+    /** ISO 8601 timestamp recording when generated occurred. */
+    generated_at: string;
+}
+/** Enforce the `pm history-compact` target contract shared by the CLI and MCP surfaces: exactly one selection mode — a single item `<id>`, an explicit `--ids` list, or a scan selector (`--all-over` / `--closed` / `--all-streams`). */
+export declare function assertHistoryCompactTarget(id: string | undefined, bulk: {
+    ids?: string[];
+    allOver?: number;
+    scope?: HistoryCompactScope;
+}): void;
+/**
+ * Bulk history compaction: compact every history stream matching the requested
+ * selection (explicit `--ids`, a `--scope` lifecycle filter, and/or an
+ * `--all-over <N>` entry threshold) in one audited pass. Each selected stream is
+ * compacted with the same single-item logic ({@link runHistoryCompact}); one
+ * failing stream never aborts the rest, and the caller decides the exit code
+ * from `totals.items_errored`.
+ *
+ * When `history.compact_policy` is enabled and no explicit `--all-over` is
+ * given, the policy's `max_entries` is used as the scan threshold so the
+ * configured policy drives the sweep.
+ */
+export declare function runHistoryCompactBulk(options: HistoryCompactBulkCommandOptions, global: GlobalOptions): Promise<HistoryCompactBulkResult>;
+export {};

package/dist/sdk/history-compact.js

@@ -0,0 +1,508 @@
+/**
+ * @module sdk/history-compact
+ *
+ * Implements the pm history compact command surface and its agent-facing runtime behavior.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="a58bdcf8-a01b-55b7-ac6e-57432c9422bf")}catch(e){}}();
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createHistoryEntry } from "../core/history/history.js";
+import { selectHistoryCompactBulkTargets, } from "../core/history/history-compact-bulk.js";
+import { executeHistoryRewrite, writeHistoryRawWithRollback, } from "../core/history/history-rewrite.js";
+import { cloneEmptyReplayDocument, historyEntriesToRaw, replayHash, replayToItemDocument, toReplayDocument, verifyHistoryChain, } from "../core/history/replay.js";
+import { applyHistoryPatch } from "../core/history/projection.js";
+import { readHistoryEntries } from "../core/history/read.js";
+import { resolveItemTypeRegistry } from "../core/item/type-registry.js";
+import { lifecycleClassifierFromStatusRegistry } from "../core/governance/metadata-coverage.js";
+import { resolveRuntimeStatusRegistry } from "../core/schema/runtime-schema.js";
+import { listAllItemMetadataLight } from "../core/store/item-store.js";
+import { pathExists, readFileIfExists } from "../core/fs/fs-utils.js";
+import { EXIT_CODE } from "../core/shared/constants.js";
+import { PmCliError } from "../core/shared/errors.js";
+import { nowIso } from "../core/shared/time.js";
+import { getActiveExtensionRegistrations, runActiveOnReadHooks, runActiveOnWriteHooks, } from "../core/extensions/index.js";
+import { readLocatedItem } from "../core/store/item-store.js";
+import { getSettingsPath, resolvePmRoot } from "../core/store/paths.js";
+import { readSettings } from "../core/store/settings.js";
+import { resolveAuthor } from "../core/shared/author.js";
+import { resolveHistorySubject } from "./history-redact.js";
+function parseBeforeBoundary(before, entries) {
+    if (before === undefined) {
+        return {
+            kind: "default",
+            raw: null,
+            compactCount: entries.length,
+            retainedCount: 0,
+        };
+    }
+    const raw = before.trim();
+    if (raw.length === 0) {
+        throw new PmCliError("history-compact --before requires a non-empty value.", EXIT_CODE.USAGE);
+    }
+    if (/^\d+$/.test(raw)) {
+        const version = Number.parseInt(raw, 10);
+        if (!Number.isSafeInteger(version) ||
+            version < 1 ||
+            version > entries.length + 1) {
+            throw new PmCliError(`history-compact --before version must be between 1 and ${entries.length + 1}.`, EXIT_CODE.USAGE);
+        }
+        const compactCount = Math.max(0, Math.min(entries.length, version - 1));
+        return {
+            kind: "version",
+            raw,
+            compactCount,
+            retainedCount: entries.length - compactCount,
+        };
+    }
+    const beforeTs = Date.parse(raw);
+    if (!Number.isFinite(beforeTs)) {
+        throw new PmCliError(`Invalid history-compact --before value "${before}". Use a version number or ISO timestamp.`, EXIT_CODE.USAGE);
+    }
+    let compactCount = 0;
+    for (const [index, entry] of entries.entries()) {
+        const entryTs = Date.parse(entry.ts);
+        if (!Number.isFinite(entryTs)) {
+            throw new PmCliError(`History for this item contains invalid timestamp at entry ${index + 1}.`, EXIT_CODE.GENERIC_FAILURE);
+        }
+        if (entryTs >= beforeTs) {
+            break;
+        }
+        compactCount += 1;
+    }
+    return {
+        kind: "timestamp",
+        raw,
+        compactCount,
+        retainedCount: entries.length - compactCount,
+    };
+}
+function replayHistoryAndResolveCheckpoint(entries, compactCount) {
+    let replay = cloneEmptyReplayDocument();
+    let checkpoint = cloneEmptyReplayDocument();
+    for (let index = 0; index < entries.length; index += 1) {
+        const entry = entries[index];
+        if (replayHash(replay) !== entry.before_hash) {
+            throw new PmCliError(`history-compact detected before-hash drift at entry ${index + 1}; run pm history-repair first.`, EXIT_CODE.CONFLICT);
+        }
+        replay = applyHistoryPatch(replay, entry.patch, index + 1, entry.op);
+        if (replayHash(replay) !== entry.after_hash) {
+            throw new PmCliError(`history-compact detected after-hash drift at entry ${index + 1}; run pm history-repair first.`, EXIT_CODE.CONFLICT);
+        }
+        if (index + 1 === compactCount) {
+            checkpoint = structuredClone(replay);
+        }
+    }
+    return {
+        checkpoint,
+        finalReplay: replay,
+    };
+}
+function reanchorRetainedEntries(retainedEntries, seed, retainedEntryOffset) {
+    let replay = structuredClone(seed);
+    const rewritten = [];
+    for (const [index, entry] of retainedEntries.entries()) {
+        const beforeHash = replayHash(replay);
+        replay = applyHistoryPatch(replay, entry.patch, retainedEntryOffset + index + 1, entry.op);
+        rewritten.push({
+            ...entry,
+            before_hash: beforeHash,
+            after_hash: replayHash(replay),
+        });
+    }
+    return {
+        entries: rewritten,
+        finalReplay: replay,
+    };
+}
+async function loadHistoryCompactCurrentItem(subject, settings, historyEntries) {
+    const loadedItem = subject.located
+        ? await readLocatedItem(subject.located, { schema: settings.schema })
+        : null;
+    if (!loadedItem) {
+        return {
+            loadedItem: null,
+            currentItemRawBeforeLock: null,
+            matchedChainBefore: null,
+        };
+    }
+    return {
+        loadedItem,
+        currentItemRawBeforeLock: loadedItem.raw,
+        matchedChainBefore: replayHash(toReplayDocument(loadedItem.document)) ===
+            historyEntries[historyEntries.length - 1]?.after_hash,
+    };
+}
+function buildHistoryCompactMessage(options, boundary) {
+    if (typeof options.message === "string" &&
+        options.message.trim().length > 0) {
+        return options.message;
+    }
+    if (boundary.raw === null) {
+        return `history-compact compacted full stream (${boundary.compactCount} entr${boundary.compactCount === 1 ? "y" : "ies"}).`;
+    }
+    return `history-compact compacted ${boundary.compactCount} entr${boundary.compactCount === 1 ? "y" : "ies"} before ${boundary.raw}.`;
+}
+function buildHistoryCompactBaselineMessage(boundary) {
+    if (boundary.raw === null) {
+        return `history-compact baseline snapshot after compacting ${boundary.compactCount} entr${boundary.compactCount === 1 ? "y" : "ies"}.`;
+    }
+    return `history-compact baseline snapshot before ${boundary.raw}.`;
+}
+function buildHistoryCompactEntries(params) {
+    if (!params.changed) {
+        return {
+            rewrittenEntries: params.historyEntries,
+            baselineEntryAdded: false,
+            auditEntryAdded: false,
+        };
+    }
+    const { checkpoint, finalReplay } = replayHistoryAndResolveCheckpoint(params.historyEntries, params.boundary.compactCount);
+    const retained = params.historyEntries.slice(params.boundary.compactCount);
+    const reanchored = reanchorRetainedEntries(retained, checkpoint, params.boundary.compactCount);
+    const baselineEntry = createHistoryEntry({
+        nowIso: nowIso(),
+        author: params.author,
+        op: "history_compact_baseline",
+        before: replayToItemDocument(cloneEmptyReplayDocument()),
+        after: replayToItemDocument(checkpoint),
+        message: buildHistoryCompactBaselineMessage(params.boundary),
+    });
+    const rewrittenEntries = [baselineEntry, ...reanchored.entries];
+    if (!params.dryRun) {
+        rewrittenEntries.push(createHistoryEntry({
+            nowIso: nowIso(),
+            author: params.author,
+            op: "history_compact",
+            before: replayToItemDocument(finalReplay),
+            after: replayToItemDocument(finalReplay),
+            message: buildHistoryCompactMessage(params.options, params.boundary),
+        }));
+    }
+    return {
+        rewrittenEntries,
+        baselineEntryAdded: true,
+        auditEntryAdded: !params.dryRun,
+    };
+}
+async function applyHistoryCompactRewrite(params) {
+    return executeHistoryRewrite({
+        pmRoot: params.pmRoot,
+        subject: params.subject,
+        settings: params.settings,
+        typeRegistry: params.typeRegistry,
+        historyRawBeforeLock: params.historyRawBeforeLock,
+        currentItemRawBeforeLock: params.currentItemRawBeforeLock,
+        operation: "history-compact",
+        author: params.author,
+        force: params.force,
+        itemDocument: params.loadedItem?.document ?? null,
+        applyRewrite: async ({ historyRawUnderLock }) => writeHistoryRawWithRollback({
+            historyPath: params.historyPath,
+            nextHistoryRaw: historyEntriesToRaw(params.rewrittenEntries),
+            historyRawUnderLock,
+        }),
+        applyPostRewrite: async () => runActiveOnWriteHooks({
+            path: params.historyPath,
+            scope: "project",
+            op: "history_compact:history",
+        }),
+    });
+}
+/** Implements run history compact for the public runtime surface of this module. */
+export async function runHistoryCompact(id, options, global) {
+    const pmRoot = resolvePmRoot(process.cwd(), global.path);
+    if (!(await pathExists(getSettingsPath(pmRoot)))) {
+        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
+    }
+    const settings = await readSettings(pmRoot);
+    const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
+    const subject = await resolveHistorySubject(pmRoot, id, settings, typeRegistry.type_to_folder);
+    const historyPath = subject.historyPath;
+    const historyRawBeforeLock = await readFileIfExists(historyPath);
+    if (historyRawBeforeLock === null) {
+        throw new PmCliError(`No history stream exists for ${subject.id}.`, EXIT_CODE.NOT_FOUND);
+    }
+    const historyEntries = await readHistoryEntries(historyPath, subject.id);
+    if (historyEntries.length === 0) {
+        throw new PmCliError(`No history entries exist for ${subject.id}; nothing to compact.`, EXIT_CODE.USAGE);
+    }
+    const chainVerification = verifyHistoryChain(historyEntries);
+    if (!chainVerification.ok) {
+        throw new PmCliError(`history-compact requires a valid history chain (${chainVerification.errors.join(", ")}). Run pm history-repair ${subject.id} first.`, EXIT_CODE.CONFLICT);
+    }
+    const boundary = parseBeforeBoundary(options.before, historyEntries);
+    const changed = boundary.compactCount > 0;
+    const dryRun = Boolean(options.dryRun);
+    const author = resolveAuthor(options.author, settings.author_default);
+    const warnings = [];
+    if (!changed) {
+        warnings.push("history_compact_noop_before_boundary");
+    }
+    const currentItem = await loadHistoryCompactCurrentItem(subject, settings, historyEntries);
+    if (currentItem.matchedChainBefore === false) {
+        warnings.push("history_compact_item_chain_mismatch");
+    }
+    const { rewrittenEntries, baselineEntryAdded, auditEntryAdded } = buildHistoryCompactEntries({
+        historyEntries,
+        boundary,
+        changed,
+        dryRun,
+        author,
+        options,
+    });
+    const rewrittenVerify = verifyHistoryChain(rewrittenEntries);
+    if (!rewrittenVerify.ok) {
+        throw new PmCliError(`history-compact produced an invalid rewritten chain (${rewrittenVerify.errors.join(", ")}).`, EXIT_CODE.GENERIC_FAILURE);
+    }
+    if (changed && !dryRun) {
+        warnings.push(...(await applyHistoryCompactRewrite({
+            pmRoot,
+            subject,
+            settings,
+            typeRegistry,
+            historyRawBeforeLock,
+            currentItemRawBeforeLock: currentItem.currentItemRawBeforeLock,
+            author,
+            force: options.force,
+            loadedItem: currentItem.loadedItem,
+            historyPath,
+            rewrittenEntries,
+        })));
+    }
+    const firstRetainedEntry = boundary.retainedCount > 0 ? boundary.compactCount + 1 : null;
+    return {
+        id: subject.id,
+        dry_run: dryRun,
+        changed,
+        compact_boundary: {
+            kind: boundary.kind,
+            before: boundary.raw,
+            entries_compacted: boundary.compactCount,
+            entries_retained: boundary.retainedCount,
+            first_retained_entry: firstRetainedEntry,
+        },
+        history: {
+            path: historyPath,
+            entries_scanned: historyEntries.length,
+            entries_after: rewrittenEntries.length,
+            baseline_entry_added: baselineEntryAdded,
+            audit_entry_added: auditEntryAdded,
+            verify_ok: rewrittenVerify.ok,
+            verify_errors: rewrittenVerify.errors,
+        },
+        item: {
+            exists: subject.located !== null,
+            path: subject.located?.itemPath ?? null,
+            matched_chain_before: currentItem.matchedChainBefore,
+        },
+        warnings: [...new Set(warnings)].sort((left, right) => left.localeCompare(right)),
+        generated_at: nowIso(),
+    };
+}
+/** Default entry floor below which a stream is treated as already compact. */
+export const HISTORY_COMPACT_BULK_DEFAULT_MIN_ENTRIES = 3;
+/** Enforce the `pm history-compact` target contract shared by the CLI and MCP surfaces: exactly one selection mode — a single item `<id>`, an explicit `--ids` list, or a scan selector (`--all-over` / `--closed` / `--all-streams`). */
+export function assertHistoryCompactTarget(id, bulk) {
+    const hasIds = bulk.ids !== undefined && bulk.ids.length > 0;
+    const hasScan = bulk.allOver !== undefined || bulk.scope !== undefined;
+    const selectorCount = (id !== undefined ? 1 : 0) + (hasIds ? 1 : 0) + (hasScan ? 1 : 0);
+    if (selectorCount === 0) {
+        throw new PmCliError("history-compact: provide an item <id>, or a bulk selector (--ids, --all-over <N>, --closed, or --all-streams).", EXIT_CODE.USAGE);
+    }
+    if (id !== undefined && (hasIds || hasScan)) {
+        throw new PmCliError("history-compact: <id> and bulk selectors (--ids/--all-over/--closed/--all-streams) are mutually exclusive; pass one item id, or use bulk mode without a positional id.", EXIT_CODE.USAGE);
+    }
+    if (hasIds && hasScan) {
+        throw new PmCliError("history-compact: --ids is mutually exclusive with --all-over/--closed/--all-streams; pass an explicit id list or a scan selector, not both.", EXIT_CODE.USAGE);
+    }
+}
+function countHistoryStreamEntries(raw) {
+    let count = 0;
+    for (const line of raw.split(/\r?\n/)) {
+        if (line.trim().length > 0) {
+            count += 1;
+        }
+    }
+    return count;
+}
+async function collectHistoryCompactBulkCandidates(params) {
+    const statusRegistry = resolveRuntimeStatusRegistry(params.settings.schema);
+    const classifier = lifecycleClassifierFromStatusRegistry(statusRegistry);
+    const items = await listAllItemMetadataLight(params.pmRoot, params.settings.item_format, params.typeToFolder, undefined, params.settings.schema);
+    const bucketById = new Map(items.map((item) => [item.id, classifier.classify(item.status)]));
+    const historyDir = path.join(params.pmRoot, "history");
+    const candidates = [];
+    const preselectionErrors = [];
+    if (!(await pathExists(historyDir))) {
+        return { candidates, preselectionErrors };
+    }
+    const historyFiles = (await fs.readdir(historyDir))
+        .filter((entry) => entry.endsWith(".jsonl"))
+        .sort((left, right) => left.localeCompare(right));
+    for (const fileName of historyFiles) {
+        const historyPath = path.join(historyDir, fileName);
+        const id = fileName.slice(0, -".jsonl".length);
+        try {
+            const raw = await fs.readFile(historyPath, "utf8");
+            await runActiveOnReadHooks({ path: historyPath, scope: "project" });
+            candidates.push({
+                id,
+                entries: countHistoryStreamEntries(raw),
+                bucket: bucketById.get(id) ?? null,
+            });
+        }
+        catch (error) {
+            preselectionErrors.push({
+                id,
+                outcome: "errored",
+                entries_before: 0,
+                entries_after: null,
+                skip_reason: null,
+                changed: false,
+                /* c8 ignore next -- non-Error throws are normalized in defensive fallback. */
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return { candidates, preselectionErrors };
+}
+async function runHistoryCompactBulkRow(params) {
+    if (!params.row.selected) {
+        return {
+            selected: false,
+            compacted: false,
+            errored: false,
+            result: {
+                id: params.row.id,
+                outcome: "skipped",
+                entries_before: params.row.entries,
+                entries_after: null,
+                skip_reason: params.row.skip_reason,
+                changed: false,
+                error: null,
+            },
+        };
+    }
+    try {
+        const result = await runHistoryCompact(params.row.id, {
+            dryRun: params.dryRun,
+            author: params.options.author,
+            message: params.options.message,
+            force: params.options.force,
+        }, params.global);
+        return {
+            selected: true,
+            compacted: true,
+            errored: false,
+            result: {
+                id: params.row.id,
+                outcome: "compacted",
+                entries_before: params.row.entries,
+                entries_after: result.history.entries_after,
+                skip_reason: null,
+                changed: result.changed,
+                error: null,
+            },
+        };
+    }
+    catch (error) {
+        return {
+            selected: true,
+            compacted: false,
+            errored: true,
+            result: {
+                id: params.row.id,
+                outcome: "errored",
+                entries_before: params.row.entries,
+                entries_after: null,
+                skip_reason: null,
+                changed: false,
+                /* c8 ignore next -- non-Error throws are normalized in defensive fallback. */
+                error: error instanceof Error ? error.message : String(error),
+            },
+        };
+    }
+}
+/**
+ * Bulk history compaction: compact every history stream matching the requested
+ * selection (explicit `--ids`, a `--scope` lifecycle filter, and/or an
+ * `--all-over <N>` entry threshold) in one audited pass. Each selected stream is
+ * compacted with the same single-item logic ({@link runHistoryCompact}); one
+ * failing stream never aborts the rest, and the caller decides the exit code
+ * from `totals.items_errored`.
+ *
+ * When `history.compact_policy` is enabled and no explicit `--all-over` is
+ * given, the policy's `max_entries` is used as the scan threshold so the
+ * configured policy drives the sweep.
+ */
+export async function runHistoryCompactBulk(options, global) {
+    const pmRoot = resolvePmRoot(process.cwd(), global.path);
+    if (!(await pathExists(getSettingsPath(pmRoot)))) {
+        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
+    }
+    const settings = await readSettings(pmRoot);
+    const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
+    const { candidates, preselectionErrors } = await collectHistoryCompactBulkCandidates({
+        pmRoot,
+        settings,
+        typeToFolder: typeRegistry.type_to_folder,
+    });
+    const mode = options.ids !== undefined && options.ids.length > 0 ? "ids" : "scan";
+    const minEntries = options.minEntries ?? HISTORY_COMPACT_BULK_DEFAULT_MIN_ENTRIES;
+    const policy = settings.history.compact_policy;
+    const policyThresholdApplied = mode === "scan" && options.allOver === undefined && policy.enabled;
+    const allOver = options.allOver ??
+        (policyThresholdApplied ? policy.max_entries : undefined);
+    const selection = selectHistoryCompactBulkTargets(candidates, {
+        ids: options.ids,
+        scope: options.scope,
+        minEntries,
+        allOver,
+    });
+    const dryRun = Boolean(options.dryRun);
+    const results = [...preselectionErrors];
+    const totals = {
+        streams_considered: candidates.length + preselectionErrors.length,
+        selected: 0,
+        items_compacted: 0,
+        items_skipped: 0,
+        items_errored: preselectionErrors.length,
+    };
+    for (const row of selection) {
+        const outcome = await runHistoryCompactBulkRow({
+            row,
+            options,
+            dryRun,
+            global,
+        });
+        results.push(outcome.result);
+        if (!outcome.selected) {
+            totals.items_skipped += 1;
+            continue;
+        }
+        totals.selected += 1;
+        if (outcome.compacted) {
+            totals.items_compacted += 1;
+        }
+        if (outcome.errored) {
+            totals.items_errored += 1;
+        }
+    }
+    return {
+        bulk: true,
+        dry_run: dryRun,
+        mode,
+        scope: options.scope ?? null,
+        criteria: {
+            min_entries: minEntries,
+            all_over: allOver ?? null,
+            policy_threshold_applied: policyThresholdApplied,
+        },
+        totals,
+        results,
+        generated_at: nowIso(),
+    };
+}
+//# sourceMappingURL=history-compact.js.map
+//# debugId=a58bdcf8-a01b-55b7-ac6e-57432c9422bf