@unbrained/pm-cli 2026.9.6 → 2026.9.8

package/dist/sdk/invocation-author.js

@@ -1,40 +1,2 @@
-/**
- * @module sdk/invocation-author
- *
- * Safely scopes invocation-wide mutation authors for one-shot and embedded CLI hosts.
- */
-
-!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]="8f7cca3d-9b19-53b4-a510-5290aaf75e12")}catch(e){}}();
-import { EXIT_CODE } from "../core/shared/constants.js";
-import { PmCliError } from "../core/shared/errors.js";
-import { readAuthorEnvironment, writeAuthorEnvironment, } from "../core/shared/author.js";
-/** Apply an optional author override and return an idempotent environment restorer. */
-export function applyInvocationAuthorOverride(author) {
-    if (author === undefined) {
-        return () => { };
-    }
-    const normalizedAuthor = author.trim();
-    if (normalizedAuthor.length === 0) {
-        throw new PmCliError("--author requires a non-empty value.", EXIT_CODE.USAGE, {
-            code: "missing_required_argument",
-            nextSteps: ["Pass an explicit author identifier with --author <id>."],
-        });
-    }
-    const previousAuthor = readAuthorEnvironment();
-    writeAuthorEnvironment(normalizedAuthor);
-    let restored = false;
-    return () => {
-        if (restored) {
-            return;
-        }
-        restored = true;
-        if (previousAuthor === undefined) {
-            writeAuthorEnvironment(undefined);
-        }
-        else {
-            writeAuthorEnvironment(previousAuthor);
-        }
-    };
-}
+!(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]="d22b586a-5c12-518e-b1ee-4baa0d04243b")}catch(e2){}})();import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";import{readAuthorEnvironment,writeAuthorEnvironment}from"../core/shared/author.js";function applyInvocationAuthorOverride(author){if(author===void 0){return()=>{}}const normalizedAuthor=author.trim();if(normalizedAuthor.length===0){throw new PmCliError("--author requires a non-empty value.",EXIT_CODE.USAGE,{code:"missing_required_argument",nextSteps:["Pass an explicit author identifier with --author <id>."]})}const previousAuthor=readAuthorEnvironment();writeAuthorEnvironment(normalizedAuthor);let restored=false;return()=>{if(restored){return}restored=true;if(previousAuthor===void 0){writeAuthorEnvironment(void 0)}else{writeAuthorEnvironment(previousAuthor)}}}export{applyInvocationAuthorOverride};
 //# sourceMappingURL=invocation-author.js.map
-//# debugId=8f7cca3d-9b19-53b4-a510-5290aaf75e12

package/dist/sdk/item-children.js

@@ -1,91 +1,2 @@
-/**
- * @module sdk/item-children
- *
- * Builds deterministic, bounded direct-child projections for every item type.
- * The primitive accepts metadata from either the persistent derived index or a
- * source scan, allowing CLI, MCP, packages, and custom hosts to share one graph
- * projection contract.
- */
-
-!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]="4b4d4bb6-8a17-5544-a18c-ad3fc49a759e")}catch(e){}}();
-import { isTerminalStatus } from "../core/item/status.js";
-import { EXIT_CODE } from "../core/shared/constants.js";
-import { PmCliError } from "../core/shared/errors.js";
-import { resolveWorkspaceRelationshipKindRegistry } from "./graph/assembly.js";
-import { collectHierarchyRelations, indexHierarchyRelations, } from "./graph/hierarchy-integrity.js";
-/** Maximum corpus rows inspected by one child projection. */
-export const MAX_CHILD_PROJECTION_ITEMS = 1_000_000;
-/** Default number of child summaries retained inline. */
-export const DEFAULT_CHILD_SAMPLE_LIMIT = 20;
-/**
- * Build a type-agnostic child rollup from indexed or source metadata. Input is
- * capped at one million rows to keep custom-host behavior explicitly bounded.
- */
-export function buildItemChildrenRollup(parentId, corpus, statusRegistry, sampleLimit = DEFAULT_CHILD_SAMPLE_LIMIT) {
-    if (!Number.isSafeInteger(sampleLimit) || sampleLimit < 0) {
-        throw new PmCliError("Child projection sample limit must be a non-negative integer.", EXIT_CODE.USAGE);
-    }
-    const normalizedParentId = parentId.trim().toLowerCase();
-    const byStatus = {};
-    const candidates = [];
-    let scanned = 0;
-    for (const candidate of corpus) {
-        scanned += 1;
-        if (scanned > MAX_CHILD_PROJECTION_ITEMS) {
-            throw new PmCliError(`Child projection exceeded the ${MAX_CHILD_PROJECTION_ITEMS.toLocaleString("en-US")} item safety bound.`, EXIT_CODE.GENERIC_FAILURE, {
-                code: "child_projection_item_bound_exceeded",
-                required: "Use an indexed or parent-filtered metadata source.",
-                why: "Unbounded graph scans can exhaust memory in universal project stores.",
-                nextSteps: [
-                    "Build the derived item index, then retry the parent read.",
-                ],
-            });
-        }
-        candidates.push(candidate);
-    }
-    const itemById = new Map(candidates.map((candidate) => [
-        candidate.id.trim().toLowerCase(),
-        candidate,
-    ]));
-    const hierarchyIndexes = indexHierarchyRelations(collectHierarchyRelations(candidates, resolveWorkspaceRelationshipKindRegistry()));
-    const childIds = new Set(hierarchyIndexes.children_by_parent.get(normalizedParentId) ?? []);
-    for (const candidate of candidates) {
-        if (candidate.parent?.trim().toLowerCase() === normalizedParentId) {
-            childIds.add(candidate.id.trim().toLowerCase());
-        }
-    }
-    const children = [...childIds].map((childId) => itemById.get(childId));
-    let active = 0;
-    for (const child of children) {
-        const status = child.status.trim().toLowerCase();
-        byStatus[status] = (byStatus[status] ?? 0) + 1;
-        if (!isTerminalStatus(status, statusRegistry)) {
-            active += 1;
-        }
-    }
-    children.sort((left, right) => left.id.localeCompare(right.id));
-    const sample = children.slice(0, sampleLimit).map((child) => ({
-        id: child.id,
-        title: child.title,
-        type: child.type,
-        status: child.status,
-        priority: child.priority,
-    }));
-    const truncated = children.length > sample.length;
-    const continuationLimit = sampleLimit === 0 ? DEFAULT_CHILD_SAMPLE_LIMIT : sampleLimit;
-    return {
-        count: children.length,
-        active,
-        by_status: Object.fromEntries(Object.entries(byStatus).sort(([left], [right]) => left.localeCompare(right))),
-        sample,
-        sample_limit: sampleLimit,
-        truncated,
-        next_offset: truncated ? sample.length : null,
-        continuation: truncated
-            ? `pm list --status all --parent ${parentId} --offset ${sample.length} --limit ${continuationLimit}`
-            : null,
-        scanned,
-    };
-}
+!(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]="acda1c64-cb50-57b5-868d-a27ca6912979")}catch(e2){}})();import{isTerminalStatus}from"../core/item/status.js";import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";import{resolveWorkspaceRelationshipKindRegistry}from"./graph/assembly.js";import{collectHierarchyRelations,indexHierarchyRelations}from"./graph/hierarchy-integrity.js";const MAX_CHILD_PROJECTION_ITEMS=1e6;const DEFAULT_CHILD_SAMPLE_LIMIT=20;function buildItemChildrenRollup(parentId,corpus,statusRegistry,sampleLimit=DEFAULT_CHILD_SAMPLE_LIMIT){if(!Number.isSafeInteger(sampleLimit)||sampleLimit<0){throw new PmCliError("Child projection sample limit must be a non-negative integer.",EXIT_CODE.USAGE)}const normalizedParentId=parentId.trim().toLowerCase();const byStatus={};const candidates=[];let scanned=0;for(const candidate of corpus){scanned+=1;if(scanned>MAX_CHILD_PROJECTION_ITEMS){throw new PmCliError(`Child projection exceeded the ${MAX_CHILD_PROJECTION_ITEMS.toLocaleString("en-US")} item safety bound.`,EXIT_CODE.GENERIC_FAILURE,{code:"child_projection_item_bound_exceeded",required:"Use an indexed or parent-filtered metadata source.",why:"Unbounded graph scans can exhaust memory in universal project stores.",nextSteps:["Build the derived item index, then retry the parent read."]})}candidates.push(candidate)}const itemById=new Map(candidates.map(candidate=>[candidate.id.trim().toLowerCase(),candidate]));const hierarchyIndexes=indexHierarchyRelations(collectHierarchyRelations(candidates,resolveWorkspaceRelationshipKindRegistry()));const childIds=new Set(hierarchyIndexes.children_by_parent.get(normalizedParentId)??[]);for(const candidate of candidates){if(candidate.parent?.trim().toLowerCase()===normalizedParentId){childIds.add(candidate.id.trim().toLowerCase())}}const children=[...childIds].map(childId=>itemById.get(childId));let active=0;for(const child of children){const status=child.status.trim().toLowerCase();byStatus[status]=(byStatus[status]??0)+1;if(!isTerminalStatus(status,statusRegistry)){active+=1}}children.sort((left,right)=>left.id.localeCompare(right.id));const sample=children.slice(0,sampleLimit).map(child=>({id:child.id,title:child.title,type:child.type,status:child.status,priority:child.priority}));const truncated=children.length>sample.length;const continuationLimit=sampleLimit===0?DEFAULT_CHILD_SAMPLE_LIMIT:sampleLimit;return{count:children.length,active,by_status:Object.fromEntries(Object.entries(byStatus).sort(([left],[right])=>left.localeCompare(right))),sample,sample_limit:sampleLimit,truncated,next_offset:truncated?sample.length:null,continuation:truncated?`pm list --status all --parent ${parentId} --offset ${sample.length} --limit ${continuationLimit}`:null,scanned}}export{DEFAULT_CHILD_SAMPLE_LIMIT,MAX_CHILD_PROJECTION_ITEMS,buildItemChildrenRollup};
 //# sourceMappingURL=item-children.js.map
-//# debugId=4b4d4bb6-8a17-5544-a18c-ad3fc49a759e

package/dist/sdk/item-metadata-index.js

@@ -1,16 +1,2 @@
-/**
- * @module sdk/item-metadata-index
- *
- * Exposes the rebuildable item-metadata index projection transaction used by
- * SDK hosts that commit authoritative item documents outside the stock CLI.
- * The lock may return a no-op release below
- * `DEFAULT_DERIVED_INDEX_MINIMUM_ITEMS` or when the manifest is absent. Hosts
- * must surface warning tokens returned by the refresh operation, including
- * invalid-path and refresh-failure diagnostics.
- */
-
-!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]="13c02696-29a7-598e-888a-3502fd88bfbe")}catch(e){}}();
-export { acquireItemMetadataDerivedIndexLock, DEFAULT_DERIVED_INDEX_MINIMUM_ITEMS, readItemMetadataDerivedIndexState, refreshItemMetadataDerivedIndex, } from "../core/store/item-metadata-cache.js";
-export { queryItemMetadataIndex, queryLinkedFileMetadataIndex, querySimilarItemMetadataIndex, } from "../core/store/item-metadata-query-index.js";
+!(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]="e524f0ad-faad-5d89-b8f5-1283979919ad")}catch(e2){}})();import{acquireItemMetadataDerivedIndexLock,DEFAULT_DERIVED_INDEX_MINIMUM_ITEMS,readItemMetadataDerivedIndexState,refreshItemMetadataDerivedIndex}from"../core/store/item-metadata-cache.js";import{queryItemMetadataIndex,queryLinkedFileMetadataIndex,querySimilarItemMetadataIndex}from"../core/store/item-metadata-query-index.js";export{DEFAULT_DERIVED_INDEX_MINIMUM_ITEMS,acquireItemMetadataDerivedIndexLock,queryItemMetadataIndex,queryLinkedFileMetadataIndex,querySimilarItemMetadataIndex,readItemMetadataDerivedIndexState,refreshItemMetadataDerivedIndex};
 //# sourceMappingURL=item-metadata-index.js.map
-//# debugId=13c02696-29a7-598e-888a-3502fd88bfbe

package/dist/sdk/item-schedule.js

@@ -1,28 +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]="80981c24-3442-57a2-8c35-e0e00d5425d6")}catch(e){}}();
-const BUILTIN_SCHEDULE_TYPES = new Set(["event", "meeting", "reminder"]);
-/** Return whether an item carries or semantically represents schedule data. */
-export function itemHasSchedule(item) {
-    return (BUILTIN_SCHEDULE_TYPES.has(item.type.trim().toLowerCase()) ||
-        item.deadline !== undefined ||
-        (item.reminders?.length ?? 0) > 0 ||
-        (item.events?.length ?? 0) > 0);
-}
-/** Build a deterministic schedule facet, or undefined for unscheduled items. */
-export function buildItemSchedule(item) {
-    if (!itemHasSchedule(item)) {
-        return undefined;
-    }
-    const events = [...(item.events ?? [])].sort((left, right) => left.start_at.localeCompare(right.start_at));
-    const primary = events[0];
-    return {
-        deadline: item.deadline ?? null,
-        start_at: primary?.start_at ?? null,
-        end_at: primary?.end_at ?? null,
-        location: primary?.location ?? null,
-        reminders: [...(item.reminders ?? [])],
-        events,
-    };
-}
+!(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]="926ca5b2-8cfc-56e7-8cbf-fb0e7152d834")}catch(e2){}})();const BUILTIN_SCHEDULE_TYPES=new Set(["event","meeting","reminder"]);function itemHasSchedule(item){return BUILTIN_SCHEDULE_TYPES.has(item.type.trim().toLowerCase())||item.deadline!==void 0||(item.reminders?.length??0)>0||(item.events?.length??0)>0}function buildItemSchedule(item){if(!itemHasSchedule(item)){return void 0}const events=[...item.events??[]].sort((left,right)=>left.start_at.localeCompare(right.start_at));const primary=events[0];return{deadline:item.deadline??null,start_at:primary?.start_at??null,end_at:primary?.end_at??null,location:primary?.location??null,reminders:[...item.reminders??[]],events}}export{buildItemSchedule,itemHasSchedule};
 //# sourceMappingURL=item-schedule.js.map
-//# debugId=80981c24-3442-57a2-8c35-e0e00d5425d6

package/dist/sdk/item-transaction.js

@@ -1,397 +1,2 @@
-/**
- * @module sdk/item-transaction
- *
- * Provides the bulk item-mutation convenience layer over
- * `commitWorkspaceTransaction`: atomic, resumable create/update/close batches
- * with correct-by-construction inspection and compensation wiring.
- */
-
-!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]="ea10685a-3187-533c-9699-73c23d377705")}catch(e){}}();
-import crypto from "node:crypto";
-import path from "node:path";
-import { transferMutationStdinTokenPolicy, } from "../core/item/parse.js";
-import { EXIT_CODE } from "../core/shared/constants.js";
-import { PmCliError } from "../core/shared/errors.js";
-import { stableStringify } from "../core/shared/serialization.js";
-import { readHistoryEntries } from "./history-read.js";
-import { close, create, deleteItem, get, release, restore, update, } from "./runtime.js";
-import { commitWorkspaceTransaction, } from "./workspace-transaction.js";
-function mergeTransactionMutationOptions(source, additions) {
-    const merged = { ...source, ...additions };
-    return source === undefined
-        ? merged
-        : transferMutationStdinTokenPolicy(source, merged);
-}
-/** Read one item's transaction-relevant fields, mapping not-found to undefined. */
-async function readItemSnapshot(pmRoot, id) {
-    try {
-        const located = await get(id, {}, { pmRoot });
-        const item = located.item;
-        return {
-            id: item.id,
-            closedAt: item.closed_at,
-            updatedAt: item.updated_at,
-            assignee: item.assignee,
-            claimPrincipal: item.claim_principal,
-        };
-    }
-    catch (error) {
-        if (error instanceof PmCliError && error.exitCode === EXIT_CODE.NOT_FOUND) {
-            return undefined;
-        }
-        throw error;
-    }
-}
-/** Derive a journal-safe step id bound to position, target, and payload. */
-function deriveStepId(mutation, index) {
-    const sanitizedTarget = mutation.id.replaceAll(/[^a-zA-Z0-9._-]/gu, "_");
-    const fingerprint = crypto
-        .createHash("sha256")
-        .update(stableStringify(mutation))
-        .digest("hex")
-        .slice(0, 12);
-    return `${index + 1}-${mutation.op}-${sanitizedTarget}-${fingerprint}`;
-}
-/** Derive the stable public outcome key without exposing journal internals. */
-function deriveOutcomeKey(mutation, index) {
-    const sanitizedTarget = mutation.id.replaceAll(/[^a-zA-Z0-9._-]/gu, "_");
-    return `${index + 1}-${mutation.op}-${sanitizedTarget}`;
-}
-/** Build the durable history-message marker for one bulk mutation phase. */
-function bulkHistoryMarker(transactionId, stepId, phase) {
-    return `bulk-item-transaction ${transactionId} ${stepId} ${phase}`;
-}
-/**
- * Report whether a step's forward mutation is durably applied. Mutable item
- * fields cannot prove transaction ownership, so the apply marker in immutable
- * history is the source of truth; a later compensation marker means the
- * mutation was rolled back and must re-apply.
- */
-async function isUpdateMarkerApplied(pmRoot, canonicalId, transactionId, stepId) {
-    const entries = await readHistoryEntries(path.join(pmRoot, "history", `${canonicalId}.jsonl`), canonicalId);
-    const applyMarker = bulkHistoryMarker(transactionId, stepId, "apply");
-    const compensateMarker = bulkHistoryMarker(transactionId, stepId, "compensate");
-    for (let index = entries.length - 1; index >= 0; index -= 1) {
-        const message = entries[index].message;
-        if (message === applyMarker) {
-            return true;
-        }
-        if (message === compensateMarker) {
-            return false;
-        }
-    }
-    return false;
-}
-/** Capture the restore target used to compensate an update or close mutation. */
-async function prepareRestoreCompensation(pmRoot, mutation) {
-    const snapshot = await readItemSnapshot(pmRoot, mutation.id);
-    if (snapshot?.updatedAt === undefined) {
-        throw new PmCliError(`Bulk ${mutation.op} target ${mutation.id} does not exist or has no restorable version`, EXIT_CODE.NOT_FOUND);
-    }
-    return { target_updated_at: snapshot.updatedAt };
-}
-/** Idempotently restore an item to its captured pre-mutation version. */
-async function compensateByRestore(config, itemId, stepId, data) {
-    const target = data !== null && typeof data === "object" && !Array.isArray(data)
-        ? data.target_updated_at
-        : undefined;
-    if (typeof target !== "string") {
-        return;
-    }
-    if ((await readItemSnapshot(config.pmRoot, itemId)) === undefined) {
-        return;
-    }
-    await restore(itemId, target, {
-        force: true,
-        author: config.author,
-        message: bulkHistoryMarker(config.transactionId, stepId, "compensate"),
-    }, { pmRoot: config.pmRoot });
-}
-/** Build the workspace-transaction step for one item creation. */
-function buildCreateStep(config, mutation, stepId) {
-    return {
-        id: stepId,
-        async inspect() {
-            const snapshot = await readItemSnapshot(config.pmRoot, mutation.id);
-            if (snapshot === undefined) {
-                return { state: "pending" };
-            }
-            return { state: "applied", result: { id: snapshot.id, op: "create" } };
-        },
-        async apply() {
-            const created = await create(mergeTransactionMutationOptions(mutation.options, {
-                author: config.author,
-                id: mutation.id,
-            }), { pmRoot: config.pmRoot });
-            const createdItem = created.item;
-            return { id: String(createdItem.id), op: "create" };
-        },
-        async compensate() {
-            const snapshot = await readItemSnapshot(config.pmRoot, mutation.id);
-            if (snapshot === undefined) {
-                return;
-            }
-            if (config.createCompensation === "delete") {
-                await deleteItem(mutation.id, {
-                    force: true,
-                    author: config.author,
-                    message: `Compensate interrupted bulk transaction ${config.transactionId}`,
-                }, { pmRoot: config.pmRoot });
-                return;
-            }
-            if (snapshot.closedAt !== undefined) {
-                return;
-            }
-            await close(mutation.id, `Compensated: interrupted bulk transaction ${config.transactionId}`, { force: true, author: config.author }, { pmRoot: config.pmRoot });
-        },
-    };
-}
-/** Build the workspace-transaction step for one item update. */
-function buildUpdateStep(config, mutation, stepId) {
-    return {
-        id: stepId,
-        async inspect() {
-            const snapshot = await readItemSnapshot(config.pmRoot, mutation.id);
-            if (snapshot === undefined) {
-                return { state: "pending" };
-            }
-            const applied = await isUpdateMarkerApplied(config.pmRoot, snapshot.id, config.transactionId, stepId);
-            if (!applied) {
-                return { state: "pending" };
-            }
-            return { state: "applied", result: { id: snapshot.id, op: "update" } };
-        },
-        async prepareCompensation() {
-            return prepareRestoreCompensation(config.pmRoot, mutation);
-        },
-        async apply() {
-            const updated = await update(mutation.id, mergeTransactionMutationOptions(mutation.options, {
-                author: config.author,
-                message: bulkHistoryMarker(config.transactionId, stepId, "apply"),
-            }), { pmRoot: config.pmRoot });
-            const updatedItem = updated.item;
-            return { id: String(updatedItem.id), op: "update" };
-        },
-        async compensate(data) {
-            await compensateByRestore(config, mutation.id, stepId, data);
-        },
-    };
-}
-/** Build the workspace-transaction step for one item closure. */
-function buildCloseStep(config, mutation, stepId) {
-    return {
-        id: stepId,
-        // An already-terminal target counts as applied: closing it again would
-        // fight legitimate prior closure, and recovery must adopt completed work.
-        async inspect() {
-            const snapshot = await readItemSnapshot(config.pmRoot, mutation.id);
-            if (snapshot === undefined) {
-                return { state: "pending" };
-            }
-            if (await isUpdateMarkerApplied(config.pmRoot, snapshot.id, config.transactionId, stepId)) {
-                return { state: "applied", result: { id: snapshot.id, op: "close" } };
-            }
-            if (snapshot.closedAt === undefined) {
-                return { state: "pending" };
-            }
-            return { state: "applied", result: { id: snapshot.id, op: "close" } };
-        },
-        async prepareCompensation() {
-            return prepareRestoreCompensation(config.pmRoot, mutation);
-        },
-        async apply() {
-            const closed = await close(mutation.id, mutation.reason, mergeTransactionMutationOptions(mutation.options, {
-                author: config.author,
-                message: bulkHistoryMarker(config.transactionId, stepId, "apply"),
-            }), { pmRoot: config.pmRoot });
-            const closedItem = closed.item;
-            return { id: String(closedItem.id), op: "close" };
-        },
-        async compensate(data) {
-            await compensateByRestore(config, mutation.id, stepId, data);
-        },
-    };
-}
-/** Build the workspace-transaction step for one claim release. */
-function buildReleaseStep(config, mutation, stepId) {
-    return {
-        id: stepId,
-        async inspect() {
-            const snapshot = await readItemSnapshot(config.pmRoot, mutation.id);
-            if (snapshot === undefined) {
-                return { state: "pending" };
-            }
-            if (await isUpdateMarkerApplied(config.pmRoot, snapshot.id, config.transactionId, stepId)) {
-                return { state: "applied", result: { id: snapshot.id, op: "release" } };
-            }
-            if (snapshot.assignee !== undefined ||
-                snapshot.claimPrincipal !== undefined) {
-                return { state: "pending" };
-            }
-            return { state: "applied", result: { id: snapshot.id, op: "release" } };
-        },
-        async prepareCompensation() {
-            return prepareRestoreCompensation(config.pmRoot, mutation);
-        },
-        async apply() {
-            const released = await release(mutation.id, mergeTransactionMutationOptions(mutation.options, {
-                author: config.author,
-                message: bulkHistoryMarker(config.transactionId, stepId, "apply"),
-            }), { pmRoot: config.pmRoot });
-            const releasedItem = released.item;
-            return { id: String(releasedItem.id), op: "release" };
-        },
-        async compensate(data) {
-            await compensateByRestore(config, mutation.id, stepId, data);
-        },
-    };
-}
-/** Convert one validated bulk mutation into its workspace-transaction step. */
-function buildStepForMutation(config, mutation, index) {
-    const stepId = deriveStepId(mutation, index);
-    switch (mutation.op) {
-        case "create":
-            return buildCreateStep(config, mutation, stepId);
-        case "update":
-            return buildUpdateStep(config, mutation, stepId);
-        case "close":
-            return buildCloseStep(config, mutation, stepId);
-        case "release":
-            return buildReleaseStep(config, mutation, stepId);
-    }
-}
-/** Reject malformed bulk mutation rows before any journal or lock work. */
-function assertValidBulkMutation(mutation, index) {
-    if (mutation === null ||
-        typeof mutation !== "object" ||
-        Array.isArray(mutation)) {
-        throw new TypeError(`Bulk mutation ${index + 1} must be an object`);
-    }
-    if (!["create", "update", "close", "release"].includes(mutation.op)) {
-        throw new TypeError(`Bulk mutation ${index + 1} op must be create, update, close, or release`);
-    }
-    if (typeof mutation.id !== "string" || mutation.id.trim().length === 0) {
-        throw new TypeError(`Bulk mutation ${index + 1} requires a non-empty id`);
-    }
-    if (mutation.op === "close" &&
-        (typeof mutation.reason !== "string" || mutation.reason.trim().length === 0)) {
-        throw new TypeError(`Bulk close mutation ${index + 1} requires a non-empty reason`);
-    }
-}
-/**
- * Commit an ordered batch of item create/update/close mutations atomically
- * (all-or-nothing) in one durable workspace transaction. This is the
- * high-level companion to `commitWorkspaceTransaction`: instead of
- * hand-writing `inspect`/`prepareCompensation`/`apply`/`compensate` for the
- * ubiquitous bulk import/sync case, callers describe the mutations and the
- * helper wires the crash-consistency contract — exists-by-id inspection for
- * creates, version-restore compensation for updates and closes, and
- * close-or-delete compensation for creates. A stable `transactionId` makes
- * interrupted batches resumable across processes and agents.
- */
-export async function commitItemMutations(options) {
-    const mutations = [...options.mutations];
-    if (mutations.length === 0) {
-        throw new TypeError("Bulk item transaction requires at least one mutation");
-    }
-    for (const [index, mutation] of mutations.entries()) {
-        assertValidBulkMutation(mutation, index);
-    }
-    const createCompensation = options.createCompensation ?? "close";
-    if (!["close", "delete"].includes(createCompensation)) {
-        throw new TypeError("Bulk item transaction createCompensation must be close or delete");
-    }
-    const stepConfig = {
-        pmRoot: options.pmRoot,
-        author: options.author,
-        transactionId: options.transactionId,
-        createCompensation,
-    };
-    const committed = await commitWorkspaceTransaction({
-        pmRoot: options.pmRoot,
-        transactionId: options.transactionId,
-        author: options.author,
-        steps: mutations.map((mutation, index) => buildStepForMutation(stepConfig, mutation, index)),
-        ...(options.lockTtlSeconds === undefined
-            ? {}
-            : { lockTtlSeconds: options.lockTtlSeconds }),
-        ...(options.lockWaitMs === undefined
-            ? {}
-            : { lockWaitMs: options.lockWaitMs }),
-        ...(options.onTransition === undefined
-            ? {}
-            : { onTransition: options.onTransition }),
-    });
-    const results = {};
-    for (const [index, mutation] of mutations.entries()) {
-        const stepId = deriveStepId(mutation, index);
-        const value = committed.results[stepId];
-        // Journal values round-trip this module's own step outputs, which are
-        // always {id, op} objects — the cast restores the concrete outcome shape.
-        results[deriveOutcomeKey(mutation, index)] =
-            value;
-    }
-    return {
-        transactionId: committed.transactionId,
-        status: "committed",
-        recovered: committed.recovered,
-        results,
-    };
-}
-/** Build the ordered mutation sequence used by atomic item completion. */
-export function buildItemCompletionMutations(options) {
-    const mutations = [];
-    if (options.evidence !== undefined &&
-        Object.keys(options.evidence).length > 0) {
-        mutations.push({ op: "update", id: options.id, options: options.evidence });
-    }
-    mutations.push({
-        op: "close",
-        id: options.id,
-        reason: options.reason,
-        ...(options.closeOptions === undefined
-            ? {}
-            : { options: options.closeOptions }),
-    }, {
-        op: "release",
-        id: options.id,
-        ...(options.releaseOptions === undefined
-            ? {}
-            : { options: options.releaseOptions }),
-    });
-    return mutations;
-}
-/**
- * Record evidence, close an item, and release its claim as one compensating
- * transaction. A failure restores the exact pre-completion item version, so
- * callers never observe the protocol's otherwise possible half-finished
- * states through a committed result.
- */
-export function commitItemCompletion(options) {
-    return commitItemMutations({
-        pmRoot: options.pmRoot,
-        transactionId: options.transactionId,
-        author: options.author,
-        mutations: buildItemCompletionMutations(options),
-        ...(options.lockTtlSeconds === undefined
-            ? {}
-            : { lockTtlSeconds: options.lockTtlSeconds }),
-        ...(options.lockWaitMs === undefined
-            ? {}
-            : { lockWaitMs: options.lockWaitMs }),
-        ...(options.onTransition === undefined
-            ? {}
-            : { onTransition: options.onTransition }),
-    });
-}
-/** Public contract for test only item transaction internals, shared with white-box specs. */
-export const _testOnlyItemTransaction = {
-    buildCreateStep,
-    bulkHistoryMarker,
-    compensateByRestore,
-    deriveStepId,
-    isUpdateMarkerApplied,
-    readItemSnapshot,
-};
+!(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]="4b7656bd-36a9-5b97-971f-60f717e8e81f")}catch(e2){}})();import crypto from"node:crypto";import path from"node:path";import{transferMutationStdinTokenPolicy}from"../core/item/parse.js";import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";import{stableStringify}from"../core/shared/serialization.js";import{readHistoryEntries}from"./history-read.js";import{close,create,deleteItem,get,release,restore,update}from"./runtime.js";import{commitWorkspaceTransaction}from"./workspace-transaction.js";function mergeTransactionMutationOptions(source,additions){const merged={...source,...additions};return source===void 0?merged:transferMutationStdinTokenPolicy(source,merged)}async function readItemSnapshot(pmRoot,id){try{const located=await get(id,{},{pmRoot});const item=located.item;return{id:item.id,closedAt:item.closed_at,updatedAt:item.updated_at,assignee:item.assignee,claimPrincipal:item.claim_principal}}catch(error){if(error instanceof PmCliError&&error.exitCode===EXIT_CODE.NOT_FOUND){return void 0}throw error}}function deriveStepId(mutation,index){const sanitizedTarget=mutation.id.replaceAll(/[^a-zA-Z0-9._-]/gu,"_");const fingerprint=crypto.createHash("sha256").update(stableStringify(mutation)).digest("hex").slice(0,12);return`${index+1}-${mutation.op}-${sanitizedTarget}-${fingerprint}`}function deriveOutcomeKey(mutation,index){const sanitizedTarget=mutation.id.replaceAll(/[^a-zA-Z0-9._-]/gu,"_");return`${index+1}-${mutation.op}-${sanitizedTarget}`}function bulkHistoryMarker(transactionId,stepId,phase){return`bulk-item-transaction ${transactionId} ${stepId} ${phase}`}async function isUpdateMarkerApplied(pmRoot,canonicalId,transactionId,stepId){const entries=await readHistoryEntries(path.join(pmRoot,"history",`${canonicalId}.jsonl`),canonicalId);const applyMarker=bulkHistoryMarker(transactionId,stepId,"apply");const compensateMarker=bulkHistoryMarker(transactionId,stepId,"compensate");for(let index=entries.length-1;index>=0;index-=1){const message=entries[index].message;if(message===applyMarker){return true}if(message===compensateMarker){return false}}return false}async function prepareRestoreCompensation(pmRoot,mutation){const snapshot=await readItemSnapshot(pmRoot,mutation.id);if(snapshot?.updatedAt===void 0){throw new PmCliError(`Bulk ${mutation.op} target ${mutation.id} does not exist or has no restorable version`,EXIT_CODE.NOT_FOUND)}return{target_updated_at:snapshot.updatedAt}}async function compensateByRestore(config,itemId,stepId,data){const target=data!==null&&typeof data==="object"&&!Array.isArray(data)?data.target_updated_at:void 0;if(typeof target!=="string"){return}if(await readItemSnapshot(config.pmRoot,itemId)===void 0){return}await restore(itemId,target,{force:true,author:config.author,message:bulkHistoryMarker(config.transactionId,stepId,"compensate")},{pmRoot:config.pmRoot})}function buildCreateStep(config,mutation,stepId){return{id:stepId,async inspect(){const snapshot=await readItemSnapshot(config.pmRoot,mutation.id);if(snapshot===void 0){return{state:"pending"}}return{state:"applied",result:{id:snapshot.id,op:"create"}}},async apply(){const created=await create(mergeTransactionMutationOptions(mutation.options,{author:config.author,id:mutation.id}),{pmRoot:config.pmRoot});const createdItem=created.item;return{id:String(createdItem.id),op:"create"}},async compensate(){const snapshot=await readItemSnapshot(config.pmRoot,mutation.id);if(snapshot===void 0){return}if(config.createCompensation==="delete"){await deleteItem(mutation.id,{force:true,author:config.author,message:`Compensate interrupted bulk transaction ${config.transactionId}`},{pmRoot:config.pmRoot});return}if(snapshot.closedAt!==void 0){return}await close(mutation.id,`Compensated: interrupted bulk transaction ${config.transactionId}`,{force:true,author:config.author},{pmRoot:config.pmRoot})}}}function buildUpdateStep(config,mutation,stepId){return{id:stepId,async inspect(){const snapshot=await readItemSnapshot(config.pmRoot,mutation.id);if(snapshot===void 0){return{state:"pending"}}const applied=await isUpdateMarkerApplied(config.pmRoot,snapshot.id,config.transactionId,stepId);if(!applied){return{state:"pending"}}return{state:"applied",result:{id:snapshot.id,op:"update"}}},async prepareCompensation(){return prepareRestoreCompensation(config.pmRoot,mutation)},async apply(){const updated=await update(mutation.id,mergeTransactionMutationOptions(mutation.options,{author:config.author,message:bulkHistoryMarker(config.transactionId,stepId,"apply")}),{pmRoot:config.pmRoot});const updatedItem=updated.item;return{id:String(updatedItem.id),op:"update"}},async compensate(data){await compensateByRestore(config,mutation.id,stepId,data)}}}function buildCloseStep(config,mutation,stepId){return{id:stepId,async inspect(){const snapshot=await readItemSnapshot(config.pmRoot,mutation.id);if(snapshot===void 0){return{state:"pending"}}if(await isUpdateMarkerApplied(config.pmRoot,snapshot.id,config.transactionId,stepId)){return{state:"applied",result:{id:snapshot.id,op:"close"}}}if(snapshot.closedAt===void 0){return{state:"pending"}}return{state:"applied",result:{id:snapshot.id,op:"close"}}},async prepareCompensation(){return prepareRestoreCompensation(config.pmRoot,mutation)},async apply(){const closed=await close(mutation.id,mutation.reason,mergeTransactionMutationOptions(mutation.options,{author:config.author,message:bulkHistoryMarker(config.transactionId,stepId,"apply")}),{pmRoot:config.pmRoot});const closedItem=closed.item;return{id:String(closedItem.id),op:"close"}},async compensate(data){await compensateByRestore(config,mutation.id,stepId,data)}}}function buildReleaseStep(config,mutation,stepId){return{id:stepId,async inspect(){const snapshot=await readItemSnapshot(config.pmRoot,mutation.id);if(snapshot===void 0){return{state:"pending"}}if(await isUpdateMarkerApplied(config.pmRoot,snapshot.id,config.transactionId,stepId)){return{state:"applied",result:{id:snapshot.id,op:"release"}}}if(snapshot.assignee!==void 0||snapshot.claimPrincipal!==void 0){return{state:"pending"}}return{state:"applied",result:{id:snapshot.id,op:"release"}}},async prepareCompensation(){return prepareRestoreCompensation(config.pmRoot,mutation)},async apply(){const released=await release(mutation.id,mergeTransactionMutationOptions(mutation.options,{author:config.author,message:bulkHistoryMarker(config.transactionId,stepId,"apply")}),{pmRoot:config.pmRoot});const releasedItem=released.item;return{id:String(releasedItem.id),op:"release"}},async compensate(data){await compensateByRestore(config,mutation.id,stepId,data)}}}function buildStepForMutation(config,mutation,index){const stepId=deriveStepId(mutation,index);switch(mutation.op){case"create":return buildCreateStep(config,mutation,stepId);case"update":return buildUpdateStep(config,mutation,stepId);case"close":return buildCloseStep(config,mutation,stepId);case"release":return buildReleaseStep(config,mutation,stepId)}}function assertValidBulkMutation(mutation,index){if(mutation===null||typeof mutation!=="object"||Array.isArray(mutation)){throw new TypeError(`Bulk mutation ${index+1} must be an object`)}if(!["create","update","close","release"].includes(mutation.op)){throw new TypeError(`Bulk mutation ${index+1} op must be create, update, close, or release`)}if(typeof mutation.id!=="string"||mutation.id.trim().length===0){throw new TypeError(`Bulk mutation ${index+1} requires a non-empty id`)}if(mutation.op==="close"&&(typeof mutation.reason!=="string"||mutation.reason.trim().length===0)){throw new TypeError(`Bulk close mutation ${index+1} requires a non-empty reason`)}}async function commitItemMutations(options){const mutations=[...options.mutations];if(mutations.length===0){throw new TypeError("Bulk item transaction requires at least one mutation")}for(const[index,mutation]of mutations.entries()){assertValidBulkMutation(mutation,index)}const createCompensation=options.createCompensation??"close";if(!["close","delete"].includes(createCompensation)){throw new TypeError("Bulk item transaction createCompensation must be close or delete")}const stepConfig={pmRoot:options.pmRoot,author:options.author,transactionId:options.transactionId,createCompensation};const committed=await commitWorkspaceTransaction({pmRoot:options.pmRoot,transactionId:options.transactionId,author:options.author,steps:mutations.map((mutation,index)=>buildStepForMutation(stepConfig,mutation,index)),...options.lockTtlSeconds===void 0?{}:{lockTtlSeconds:options.lockTtlSeconds},...options.lockWaitMs===void 0?{}:{lockWaitMs:options.lockWaitMs},...options.onTransition===void 0?{}:{onTransition:options.onTransition}});const results={};for(const[index,mutation]of mutations.entries()){const stepId=deriveStepId(mutation,index);const value=committed.results[stepId];results[deriveOutcomeKey(mutation,index)]=value}return{transactionId:committed.transactionId,status:"committed",recovered:committed.recovered,results}}function buildItemCompletionMutations(options){const mutations=[];if(options.evidence!==void 0&&Object.keys(options.evidence).length>0){mutations.push({op:"update",id:options.id,options:options.evidence})}mutations.push({op:"close",id:options.id,reason:options.reason,...options.closeOptions===void 0?{}:{options:options.closeOptions}},{op:"release",id:options.id,...options.releaseOptions===void 0?{}:{options:options.releaseOptions}});return mutations}function commitItemCompletion(options){return commitItemMutations({pmRoot:options.pmRoot,transactionId:options.transactionId,author:options.author,mutations:buildItemCompletionMutations(options),...options.lockTtlSeconds===void 0?{}:{lockTtlSeconds:options.lockTtlSeconds},...options.lockWaitMs===void 0?{}:{lockWaitMs:options.lockWaitMs},...options.onTransition===void 0?{}:{onTransition:options.onTransition}})}const _testOnlyItemTransaction={buildCreateStep,bulkHistoryMarker,compensateByRestore,deriveStepId,isUpdateMarkerApplied,readItemSnapshot};export{_testOnlyItemTransaction,buildItemCompletionMutations,commitItemCompletion,commitItemMutations};
 //# sourceMappingURL=item-transaction.js.map
-//# debugId=ea10685a-3187-533c-9699-73c23d377705

package/dist/sdk/learnings.js

@@ -1,30 +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]="972816c9-b407-5b89-a744-249c9771451f")}catch(e){}}();
-import { parseAnnotationTextInput, resolveAnnotationInput, runAnnotationCommand, } from "./annotations.js";
-/** Implements run learnings for the public runtime surface of this module. */
-export async function runLearnings(id, options, global) {
-    return runAnnotationCommand(id, options, global, {
-        input: await resolveAnnotationInput(options, "learning"),
-        collectionKey: "learnings",
-        op: "learning_add",
-        editOp: "learning_edit",
-        deleteOp: "learning_delete",
-        parseText: (raw) => parseAnnotationTextInput(raw),
-        createEntry: (entry) => entry,
-        bypassOwnershipConflict: Boolean(options.edit === undefined &&
-            options.delete === undefined &&
-            options.ownershipAppendBypass),
-        conflictGuidance: {
-            required: "For an approved append-only handoff on another owner's item, use the package-provided ownership bypass before considering --force.",
-            examples: [
-                'pm learnings pm-a1b2 --add "review learning" --author "reviewer" --force',
-            ],
-            nextSteps: [
-                "Use an installed package's narrow append-only ownership bypass when available.",
-                "Use --force only when an ownership override is explicitly approved.",
-            ],
-        },
-    });
-}
+!(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]="99f91321-fd91-5ec6-8d09-1493f40dacb1")}catch(e2){}})();import{parseAnnotationTextInput,resolveAnnotationInput,runAnnotationCommand}from"./annotations.js";async function runLearnings(id,options,global2){return runAnnotationCommand(id,options,global2,{input:await resolveAnnotationInput(options,"learning"),collectionKey:"learnings",op:"learning_add",editOp:"learning_edit",deleteOp:"learning_delete",parseText:raw=>parseAnnotationTextInput(raw),createEntry:entry=>entry,bypassOwnershipConflict:Boolean(options.edit===void 0&&options.delete===void 0&&options.ownershipAppendBypass),conflictGuidance:{required:"For an approved append-only handoff on another owner's item, use the package-provided ownership bypass before considering --force.",examples:['pm learnings pm-a1b2 --add "review learning" --author "reviewer" --force'],nextSteps:["Use an installed package's narrow append-only ownership bypass when available.","Use --force only when an ownership override is explicitly approved."]}})}export{runLearnings};
 //# sourceMappingURL=learnings.js.map
-//# debugId=972816c9-b407-5b89-a744-249c9771451f