@unbrained/pm-cli 2026.9.7 → 2026.9.9

package/dist/sdk/history-compact.js

@@ -1,528 +1,2 @@
-/**
- * @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]="26c39ecd-5d72-5cc9-b22b-6abc33fbf4ac")}catch(e){}}();
-import { assertInitializedTracker } from "./environment/tracker-preflight.js";
-import fs from "node:fs/promises";
-import path from "node:path";
-import { createHistoryEntry, hashHistoryStream, sealHistoryRecord, SUPPORTED_HISTORY_ITEM_HASH_VERSIONS, } 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, replayHashVerificationCandidates, replayToItemDocument, toReplayDocument, verifyHistoryChain, } from "../core/history/replay.js";
-import { applyHistoryPatch } from "../core/history/projection.js";
-import { readHistoryEntries } from "../core/history/read.js";
-import { historyVersionOffset } from "../core/history/version-address.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 { normalizeBulkIdsValue, parseBulkIdsText, } from "../core/io/bulk-ids-input.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 { 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";
-/** Translate a durable version or timestamp boundary into physical compacted and retained counts. */
-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);
-        const offset = historyVersionOffset(entries);
-        if (!Number.isSafeInteger(version) ||
-            version < offset + 1 ||
-            version > offset + entries.length + 1) {
-            throw new PmCliError(`history-compact --before version must be between ${offset + 1} and ${offset + entries.length + 1}.`, EXIT_CODE.USAGE);
-        }
-        const compactCount = version - offset - 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,
-    };
-}
-/** Fold the already verified stream once, capturing its compaction checkpoint. */
-function replayHistoryAndResolveCheckpoint(entries, compactCount) {
-    let replay = cloneEmptyReplayDocument();
-    let checkpoint = cloneEmptyReplayDocument();
-    for (let index = 0; index < entries.length; index += 1) {
-        const entry = entries[index];
-        replay = applyHistoryPatch(replay, entry.patch, index + 1, entry.op);
-        if (index + 1 === compactCount) {
-            checkpoint = structuredClone(replay);
-        }
-    }
-    return {
-        checkpoint,
-        finalReplay: replay,
-    };
-}
-/** Snapshot the live item and compare it with the stream's supported historical hash surfaces. */
-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,
-        };
-    }
-    const lastEntry = historyEntries[historyEntries.length - 1];
-    return {
-        loadedItem,
-        currentItemRawBeforeLock: loadedItem.raw,
-        matchedChainBefore: SUPPORTED_HISTORY_ITEM_HASH_VERSIONS.some((version) => (lastEntry.item_hash_version === undefined || lastEntry.item_hash_version === version) &&
-            replayHashVerificationCandidates(toReplayDocument(loadedItem.document), version).includes(lastEntry.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}.`;
-}
-/** Replace the pruned prefix with a durable-addressed checkpoint while retaining original records and hash semantics. */
-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 offset = historyVersionOffset(params.historyEntries, true);
-    const baselineEntry = createHistoryEntry({
-        nowIso: params.historyEntries[params.boundary.compactCount - 1].ts,
-        author: params.author,
-        op: "history_compact_baseline",
-        before: replayToItemDocument(cloneEmptyReplayDocument()),
-        after: replayToItemDocument(checkpoint),
-        message: buildHistoryCompactBaselineMessage(params.boundary),
-        context: {
-            history_compaction: {
-                contract_version: 1,
-                version_offset: offset === null ? null : offset + params.boundary.compactCount - 1,
-                checkpoint_timestamp_semantics: "last_compacted_entry",
-                pruned_entry_count: params.boundary.compactCount,
-                pruned_stream_digest: hashHistoryStream(params.historyEntries.slice(0, params.boundary.compactCount)),
-                retained_proof: "stream_digest_and_checkpoint",
-                limitation: "individual_pruned_entries_require_pre_compaction_stream",
-            },
-        },
-    });
-    const checkpointEntry = params.historyEntries[params.boundary.compactCount - 1];
-    // Preserve the checkpoint's epoch and semantic hash variant. Do not introduce
-    // an explicit epoch into an unversioned stream: it would pin later legacy reads.
-    const rewrittenEntries = [sealHistoryRecord({
-            ...baselineEntry,
-            before_hash: params.historyEntries[0].before_hash,
-            after_hash: checkpointEntry.after_hash,
-            item_hash_version: checkpointEntry.item_hash_version,
-        }), ...retained];
-    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);
-    await assertInitializedTracker(pmRoot);
-    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 offset = historyVersionOffset(historyEntries, true);
-    const firstRetainedEntry = boundary.retainedCount > 0 && offset !== null ? offset + 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;
-function normalizeHistoryCompactBulkOptions(options) {
-    const normalizedIdsText = normalizeBulkIdsValue(options.ids);
-    if (options.ids !== undefined && normalizedIdsText === "") {
-        throw new PmCliError("history-compact ids requires at least one valid item ID.", EXIT_CODE.USAGE, {
-            code: "bulk_ids_input_empty",
-            required: "Provide one or more string or finite numeric IDs; non-finite and unsupported selector values are rejected.",
-        });
-    }
-    return {
-        ...options,
-        ids: normalizedIdsText === undefined
-            ? undefined
-            : parseBulkIdsText(normalizedIdsText),
-    };
-}
-/** 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 normalizedOptions = normalizeHistoryCompactBulkOptions(options);
-    const pmRoot = resolvePmRoot(process.cwd(), global.path);
-    await assertInitializedTracker(pmRoot);
-    const settings = await readSettings(pmRoot);
-    const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
-    const { candidates, preselectionErrors } = await collectHistoryCompactBulkCandidates({
-        pmRoot,
-        settings,
-        typeToFolder: typeRegistry.type_to_folder,
-    });
-    const mode = normalizedOptions.ids !== undefined && normalizedOptions.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: normalizedOptions.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: normalizedOptions,
-            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(),
-    };
-}
+!(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]="d6824edc-ca22-5900-b43b-645135e2562d")}catch(e2){}})();import fs from"node:fs/promises";import path from"node:path";import{createHistoryEntry,hashHistoryStream,sealHistoryRecord,SUPPORTED_HISTORY_ITEM_HASH_VERSIONS}from"../core/history/history.js";import{selectHistoryCompactBulkTargets}from"../core/history/history-compact-bulk.js";import{cloneEmptyReplayDocument,replayHashVerificationCandidates,replayToItemDocument,toReplayDocument}from"../core/history/replay.js";import{applyHistoryPatch}from"../core/history/projection.js";import{historyVersionOffset}from"../core/history/version-address.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}from"../core/fs/fs-utils.js";import{normalizeBulkIdsValue,parseBulkIdsText}from"../core/io/bulk-ids-input.js";import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";import{nowIso}from"../core/shared/time.js";import{runActiveOnReadHooks}from"../core/extensions/index.js";import{resolveHistoryWorkspace,resolveHistorySubject}from"./history/subject.js";import{runHistoryMaintenance}from"./history/maintenance.js";function parseBeforeBoundary(before,entries){if(before===void 0){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);const offset=historyVersionOffset(entries);if(!Number.isSafeInteger(version)||version<offset+1||version>offset+entries.length+1){throw new PmCliError(`history-compact --before version must be between ${offset+1} and ${offset+entries.length+1}.`,EXIT_CODE.USAGE)}const compactCount2=version-offset-1;return{kind:"version",raw,compactCount:compactCount2,retainedCount:entries.length-compactCount2}}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];replay=applyHistoryPatch(replay,entry.patch,index+1,entry.op);if(index+1===compactCount){checkpoint=structuredClone(replay)}}return{checkpoint,finalReplay:replay}}function describeHistoryCompactCurrentItem(loadedItem,historyEntries){if(!loadedItem){return{loadedItem:null,currentItemRawBeforeLock:null,matchedChainBefore:null}}const lastEntry=historyEntries[historyEntries.length-1];return{loadedItem,currentItemRawBeforeLock:loadedItem.raw,matchedChainBefore:SUPPORTED_HISTORY_ITEM_HASH_VERSIONS.some(version=>(lastEntry.item_hash_version===void 0||lastEntry.item_hash_version===version)&&replayHashVerificationCandidates(toReplayDocument(loadedItem.document),version).includes(lastEntry.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 offset=historyVersionOffset(params.historyEntries,true);const baselineEntry=createHistoryEntry({nowIso:params.historyEntries[params.boundary.compactCount-1].ts,author:params.author,op:"history_compact_baseline",before:replayToItemDocument(cloneEmptyReplayDocument()),after:replayToItemDocument(checkpoint),message:buildHistoryCompactBaselineMessage(params.boundary),context:{history_compaction:{contract_version:1,version_offset:offset===null?null:offset+params.boundary.compactCount-1,checkpoint_timestamp_semantics:"last_compacted_entry",pruned_entry_count:params.boundary.compactCount,pruned_stream_digest:hashHistoryStream(params.historyEntries.slice(0,params.boundary.compactCount)),retained_proof:"stream_digest_and_checkpoint",limitation:"individual_pruned_entries_require_pre_compaction_stream"}}});const checkpointEntry=params.historyEntries[params.boundary.compactCount-1];const rewrittenEntries=[sealHistoryRecord({...baselineEntry,before_hash:params.historyEntries[0].before_hash,after_hash:checkpointEntry.after_hash,item_hash_version:checkpointEntry.item_hash_version}),...retained];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 runHistoryCompact(id,options,global2){const{pmRoot,settings,typeRegistry}=await resolveHistoryWorkspace(global2.path);const subject=await resolveHistorySubject(pmRoot,id,settings,typeRegistry.type_to_folder);return runHistoryMaintenance({pmRoot,subject,settings,typeRegistry,operation:"history-compact",options,transform:snapshot=>buildHistoryCompactPlan(subject,options,snapshot)})}function buildHistoryCompactPlan(subject,options,snapshot){const historyPath=subject.historyPath;const historyEntries=snapshot.entries;const chainVerification=snapshot.verification;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=snapshot.author;const warnings=[];if(!changed){warnings.push("history_compact_noop_before_boundary")}const currentItem=describeHistoryCompactCurrentItem(snapshot.loadedItem,historyEntries);if(currentItem.matchedChainBefore===false){warnings.push("history_compact_item_chain_mismatch")}const{rewrittenEntries,baselineEntryAdded,auditEntryAdded}=buildHistoryCompactEntries({historyEntries,boundary,changed,dryRun,author,options});const offset=historyVersionOffset(historyEntries,true);const firstRetainedEntry=boundary.retainedCount>0&&offset!==null?offset+boundary.compactCount+1:null;return{changed,rewrittenEntries,report:({verification:rewrittenVerify,warnings:writeWarnings})=>({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,...writeWarnings])].sort((left,right)=>left.localeCompare(right)),generated_at:nowIso()})}}const HISTORY_COMPACT_BULK_DEFAULT_MIN_ENTRIES=3;function normalizeHistoryCompactBulkOptions(options){for(const key of["allOver","minEntries"]){const value=options[key];if(value!==void 0&&(!Number.isSafeInteger(value)||value<0)){throw new PmCliError(`history-compact ${key} must be a non-negative safe integer.`,EXIT_CODE.USAGE)}}const normalizedIdsText=normalizeBulkIdsValue(options.ids);if(options.ids!==void 0&&normalizedIdsText===""){throw new PmCliError("history-compact ids requires at least one valid item ID.",EXIT_CODE.USAGE,{code:"bulk_ids_input_empty",required:"Provide one or more string or finite numeric IDs; non-finite and unsupported selector values are rejected."})}return{...options,ids:normalizedIdsText===void 0?void 0:parseBulkIdsText(normalizedIdsText)}}function assertHistoryCompactTarget(id,bulk){const hasIds=bulk.ids!==void 0&&bulk.ids.length>0;const hasScan=bulk.allOver!==void 0||bulk.scope!==void 0;const selectorCount=(id!==void 0?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!==void 0&&(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,void 0,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,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,error:error instanceof Error?error.message:String(error)}}}}async function runHistoryCompactBulk(options,global2){const normalizedOptions=normalizeHistoryCompactBulkOptions(options);const{pmRoot,settings,typeRegistry}=await resolveHistoryWorkspace(global2.path);const{candidates,preselectionErrors}=await collectHistoryCompactBulkCandidates({pmRoot,settings,typeToFolder:typeRegistry.type_to_folder});const mode=normalizedOptions.ids!==void 0&&normalizedOptions.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===void 0&&policy.enabled;const allOver=options.allOver??(policyThresholdApplied?policy.max_entries:void 0);const selection=selectHistoryCompactBulkTargets(candidates,{ids:normalizedOptions.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:normalizedOptions,dryRun,global:global2});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()}}export{HISTORY_COMPACT_BULK_DEFAULT_MIN_ENTRIES,assertHistoryCompactTarget,runHistoryCompact,runHistoryCompactBulk};
 //# sourceMappingURL=history-compact.js.map
-//# debugId=26c39ecd-5d72-5cc9-b22b-6abc33fbf4ac

package/dist/sdk/history-mcp.js

@@ -1,69 +1,2 @@
-
-!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]="4888a558-7f50-5c28-8e29-fcd19180cbd4")}catch(e){}}();
-import { normalizeBulkIdsValue, parseBulkIdsText, } from "../core/io/bulk-ids-input.js";
-import { EXIT_CODE } from "../core/shared/constants.js";
-import { PmCliError } from "../core/shared/errors.js";
-import { assertHistoryCompactTarget, runHistoryCompact, runHistoryCompactBulk, } from "./history-compact.js";
-import { assertHistoryRepairTarget, runHistoryRepair, runHistoryRepairAll, } from "./history-repair.js";
-import { parseRuntimeInteger, readRuntimeString } from "./runtime-input.js";
-/** Dispatch single-stream or all-stream history repair from an MCP payload. */
-export function runMcpHistoryRepairAction(context) {
-    const repairAll = context.options.all === true;
-    const repairId = context.id ?? readRuntimeString(context.options, "id");
-    assertHistoryRepairTarget(repairId, repairAll);
-    return repairAll
-        ? runHistoryRepairAll(context.options, context.global)
-        : runHistoryRepair(repairId, context.options, context.global);
-}
-/** Dispatch single or bounded bulk history compaction from an MCP payload. */
-export function runMcpHistoryCompactAction(context) {
-    const idsSource = context.options.ids;
-    const normalizedIds = normalizeBulkIdsValue(idsSource);
-    if (idsSource !== undefined && normalizedIds === "") {
-        throw new PmCliError("history-compact ids requires at least one valid item ID.", EXIT_CODE.USAGE, {
-            code: "bulk_ids_input_empty",
-            required: "Provide one or more string or finite numeric IDs; non-finite and unsupported selector values are rejected.",
-        });
-    }
-    const ids = normalizedIds === undefined ? undefined : parseBulkIdsText(normalizedIds);
-    const allOver = parseRuntimeInteger(context.options.allOver ?? context.options.all_over, "history-compact allOver");
-    const minEntries = parseRuntimeInteger(context.options.minEntries ?? context.options.min_entries, "history-compact minEntries");
-    const explicitScope = readRuntimeString(context.options, "scope");
-    const requestedScopes = [];
-    if (context.options.closed === true)
-        requestedScopes.push("closed");
-    if (context.options.allStreams === true ||
-        context.options.all_streams === true) {
-        requestedScopes.push("all-streams");
-    }
-    if (explicitScope === "closed" || explicitScope === "all-streams") {
-        requestedScopes.push(explicitScope);
-    }
-    const distinctScopes = [...new Set(requestedScopes)];
-    if (distinctScopes.length > 1) {
-        throw new PmCliError("history-compact: closed and all-streams scopes are mutually exclusive.", EXIT_CODE.USAGE);
-    }
-    const scope = distinctScopes[0];
-    assertHistoryCompactTarget(context.id, { ids, allOver, scope });
-    if (context.id !== undefined) {
-        return runHistoryCompact(context.id, {
-            before: readRuntimeString(context.options, "before"),
-            dryRun: context.options.dryRun === true || context.options.dry_run === true,
-            author: readRuntimeString(context.options, "author"),
-            message: readRuntimeString(context.options, "message"),
-            force: context.force,
-        }, context.global);
-    }
-    return runHistoryCompactBulk({
-        ids,
-        scope,
-        allOver,
-        minEntries,
-        dryRun: context.options.dryRun === true || context.options.dry_run === true,
-        author: readRuntimeString(context.options, "author"),
-        message: readRuntimeString(context.options, "message"),
-        force: context.force,
-    }, context.global);
-}
+!(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]="41f0e5cd-5974-5451-9f34-2aec1d8df07c")}catch(e2){}})();import{normalizeBulkIdsValue,parseBulkIdsText}from"../core/io/bulk-ids-input.js";import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";import{assertHistoryCompactTarget,runHistoryCompact,runHistoryCompactBulk}from"./history-compact.js";import{assertHistoryRepairTarget,runHistoryRepair,runHistoryRepairAll}from"./history-repair.js";import{parseRuntimeInteger,readRuntimeString}from"./runtime-input.js";function runMcpHistoryRepairAction(context){const repairAll=context.options.all===true;const repairId=context.id??readRuntimeString(context.options,"id");assertHistoryRepairTarget(repairId,repairAll);return repairAll?runHistoryRepairAll(context.options,context.global):runHistoryRepair(repairId,context.options,context.global)}function runMcpHistoryCompactAction(context){const idsSource=context.options.ids;const normalizedIds=normalizeBulkIdsValue(idsSource);if(idsSource!==void 0&&normalizedIds===""){throw new PmCliError("history-compact ids requires at least one valid item ID.",EXIT_CODE.USAGE,{code:"bulk_ids_input_empty",required:"Provide one or more string or finite numeric IDs; non-finite and unsupported selector values are rejected."})}const ids=normalizedIds===void 0?void 0:parseBulkIdsText(normalizedIds);const allOver=parseRuntimeInteger(context.options.allOver??context.options.all_over,"history-compact allOver");const minEntries=parseRuntimeInteger(context.options.minEntries??context.options.min_entries,"history-compact minEntries");const explicitScope=readRuntimeString(context.options,"scope");const requestedScopes=[];if(context.options.closed===true)requestedScopes.push("closed");if(context.options.allStreams===true||context.options.all_streams===true){requestedScopes.push("all-streams")}if(explicitScope==="closed"||explicitScope==="all-streams"){requestedScopes.push(explicitScope)}const distinctScopes=[...new Set(requestedScopes)];if(distinctScopes.length>1){throw new PmCliError("history-compact: closed and all-streams scopes are mutually exclusive.",EXIT_CODE.USAGE)}const scope=distinctScopes[0];assertHistoryCompactTarget(context.id,{ids,allOver,scope});if(context.id!==void 0){return runHistoryCompact(context.id,{before:readRuntimeString(context.options,"before"),dryRun:context.options.dryRun===true||context.options.dry_run===true,author:readRuntimeString(context.options,"author"),message:readRuntimeString(context.options,"message"),force:context.force},context.global)}return runHistoryCompactBulk({ids,scope,allOver,minEntries,dryRun:context.options.dryRun===true||context.options.dry_run===true,author:readRuntimeString(context.options,"author"),message:readRuntimeString(context.options,"message"),force:context.force},context.global)}export{runMcpHistoryCompactAction,runMcpHistoryRepairAction};
 //# sourceMappingURL=history-mcp.js.map
-//# debugId=4888a558-7f50-5c28-8e29-fcd19180cbd4