@unbrained/pm-cli 2026.8.19 → 2026.8.21

package/dist/core/output/mutation-projection.js

@@ -19,12 +19,33 @@
  * MCP server, and returns the original reference unchanged when nothing is compacted.
  */
 
-!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]="c873f95b-c435-5b0d-a631-565fb195b5cd")}catch(e){}}();
+!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]="a3e0573a-01fd-54fb-a568-51c5287b696c")}catch(e){}}();
 const CHANGED_FIELDS_KEY = "changed_fields";
 const CHANGED_FIELD_COUNT_KEY = "changed_field_count";
 const ROWS_KEY = "rows";
 const UPDATE_MANY_MUTATION_MODES = new Set(["apply", "rollback"]);
 const DELETE_OUTCOMES = new Set(["deleted", "would_delete"]);
+const COMPACT_RECURRENCE_TEXT_LIMIT = 256;
+function truncateCompactRecurrenceText(value) {
+    if (typeof value !== "string" ||
+        value.length <= COMPACT_RECURRENCE_TEXT_LIMIT) {
+        return value;
+    }
+    return `${value.slice(0, COMPACT_RECURRENCE_TEXT_LIMIT - 1)}…`;
+}
+function projectCompactRecurrence(value) {
+    if (!isPlainObject(value))
+        return null;
+    const recurrence = { ...value };
+    recurrence.reason = truncateCompactRecurrenceText(recurrence.reason);
+    if (isPlainObject(recurrence.previous_terminal)) {
+        recurrence.previous_terminal = Object.fromEntries(Object.entries(recurrence.previous_terminal).map(([key, entry]) => [
+            key,
+            truncateCompactRecurrenceText(entry),
+        ]));
+    }
+    return recurrence;
+}
 function isPlainObject(value) {
     if (typeof value !== "object" || value === null || Array.isArray(value)) {
         return false;
@@ -123,6 +144,9 @@ function projectCompactMutationEnvelope(result) {
             : undefined;
     if (closeReason !== undefined)
         compact.close_reason = closeReason;
+    const recurrence = projectCompactRecurrence(result.recurrence);
+    if (recurrence !== null)
+        compact.recurrence = recurrence;
     if (Array.isArray(result.warnings) && result.warnings.length > 0)
         compact.warnings = result.warnings;
     return compact;
@@ -184,4 +208,4 @@ export function projectMutationResult(result, options = {}) {
     return changed ? projected : result;
 }
 //# sourceMappingURL=mutation-projection.js.map
-//# debugId=c873f95b-c435-5b0d-a631-565fb195b5cd
+//# debugId=a3e0573a-01fd-54fb-a568-51c5287b696c

package/dist/core/shared/constants.d.ts

@@ -4,6 +4,7 @@
  * Provides shared primitives and utilities for Constants.
  */
 import type { BuiltinItemType, GovernancePreset, GovernanceSettings, PmSettings, RuntimeStatusDefinition, RuntimeWorkflowDefinition } from "../../types/index.js";
+export { ITEM_METADATA_KEY_ORDER, ITEM_PROJECT_CONTEXT_KEYS, } from "./item-metadata-contract.js";
 /**
  * Canonical default lifecycle status model and workflow role mapping.
  *
@@ -28,10 +29,6 @@ export declare const PM_OPTIONAL_TYPE_SUBDIRS: readonly ["decisions", "events",
 export declare const PM_REQUIRED_SUBDIRS: readonly ["", "epics", "features", "tasks", "chores", "issues", "schema", "history", "search", "extensions", "locks", "decisions", "events", "reminders", "milestones", "meetings", "plans"];
 /** Public contract for type to folder, shared by SDK and presentation-layer consumers. */
 export declare const TYPE_TO_FOLDER: Record<BuiltinItemType, string>;
-/** Portable project-context fields shared by storage order and structured mutation IO. */
-export declare const ITEM_PROJECT_CONTEXT_KEYS: readonly ["goal", "objective", "value", "impact", "outcome", "why_now", "parent", "reviewer", "risk", "confidence", "sprint", "release", "blocked_by", "blocked_reason", "unblock_note", "reporter", "severity", "environment", "repro_steps", "resolution", "expected_result", "actual_result"];
-/** Public contract for item metadata key order, shared by SDK and presentation-layer consumers. */
-export declare const ITEM_METADATA_KEY_ORDER: ReadonlyArray<string>;
 type BuiltinGovernancePreset = Exclude<GovernancePreset, "custom">;
 /** Public contract for governance preset defaults, shared by SDK and presentation-layer consumers. */
 export declare const GOVERNANCE_PRESET_DEFAULTS: Record<BuiltinGovernancePreset, Omit<GovernanceSettings, "preset">>;
@@ -67,4 +64,3 @@ export type TelemetryErrorCategory = "usage" | "validation" | "conflict" | "runt
 export declare const TELEMETRY_ERROR_CATEGORY_BY_CODE: Readonly<Record<string, TelemetryErrorCategory>>;
 /** Implements resolve telemetry error category for the public runtime surface of this module. */
 export declare function resolveTelemetryErrorCategory(errorCode: string | undefined): TelemetryErrorCategory;
-export {};

package/dist/core/shared/constants.js

@@ -1,6 +1,7 @@
 
-!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]="45e1dcb9-d2d6-52d7-b0b0-a57556a3fb03")}catch(e){}}();
+!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]="70cce114-b8a7-5770-ae42-eec473515709")}catch(e){}}();
 import { createDefaultExtensionGovernancePolicy } from "../extensions/extension-types.js";
+export { ITEM_METADATA_KEY_ORDER, ITEM_PROJECT_CONTEXT_KEYS, } from "./item-metadata-contract.js";
 /**
  * Canonical default lifecycle status model and workflow role mapping.
  *
@@ -93,85 +94,6 @@ export const TYPE_TO_FOLDER = {
     Meeting: "meetings",
     Plan: "plans",
 };
-/** Portable project-context fields shared by storage order and structured mutation IO. */
-export const ITEM_PROJECT_CONTEXT_KEYS = [
-    "goal",
-    "objective",
-    "value",
-    "impact",
-    "outcome",
-    "why_now",
-    "parent",
-    "reviewer",
-    "risk",
-    "confidence",
-    "sprint",
-    "release",
-    "blocked_by",
-    "blocked_reason",
-    "unblock_note",
-    "reporter",
-    "severity",
-    "environment",
-    "repro_steps",
-    "resolution",
-    "expected_result",
-    "actual_result",
-];
-/** Public contract for item metadata key order, shared by SDK and presentation-layer consumers. */
-export const ITEM_METADATA_KEY_ORDER = [
-    "id",
-    "title",
-    "description",
-    "type",
-    "pm_format_version",
-    "source_type",
-    "type_options",
-    "status",
-    "priority",
-    "tags",
-    "created_at",
-    "updated_at",
-    "deadline",
-    "reminders",
-    "events",
-    "closed_at",
-    "completed_at",
-    "assignee",
-    "claim_principal",
-    "source_owner",
-    "author",
-    "estimated_minutes",
-    "acceptance_criteria",
-    "design",
-    "external_ref",
-    "definition_of_ready",
-    "order",
-    ...ITEM_PROJECT_CONTEXT_KEYS,
-    "affected_version",
-    "fixed_version",
-    "component",
-    "regression",
-    "customer_impact",
-    "dependencies",
-    "comments",
-    "notes",
-    "learnings",
-    "files",
-    "tests",
-    "test_runs",
-    "docs",
-    "close_reason",
-    "duplicate_of",
-    "plan_mode",
-    "plan_scope",
-    "plan_harness",
-    "plan_resume_context",
-    "plan_validation",
-    "plan_decisions",
-    "plan_discoveries",
-    "plan_steps",
-];
 /** Public contract for governance preset defaults, shared by SDK and presentation-layer consumers. */
 export const GOVERNANCE_PRESET_DEFAULTS = {
     minimal: {
@@ -480,4 +402,4 @@ export function resolveTelemetryErrorCategory(errorCode) {
     return "unknown";
 }
 //# sourceMappingURL=constants.js.map
-//# debugId=45e1dcb9-d2d6-52d7-b0b0-a57556a3fb03
+//# debugId=70cce114-b8a7-5770-ae42-eec473515709

package/dist/core/shared/errors.d.ts

@@ -79,6 +79,10 @@ export interface PmCliErrorContext {
     check?: string;
     /** Serialization format involved in a parse failure. */
     format?: string;
+    /** CLI flag whose supplied value violated a shared mutation grammar. */
+    flag?: string;
+    /** Supplied scalar value that violated a shared mutation grammar. */
+    value?: string;
     /** Item format version involved in a compatibility failure. */
     format_version?: number;
     /** Schema type that determines the shape and validation rules for this value. */
@@ -99,6 +103,18 @@ export interface PmCliErrorContext {
     nextSteps?: string[];
     /** Exact selectors that could not be matched by a lossless removal. */
     unmatched?: string[];
+    /** Dependency selectors that matched no stored edge. */
+    unmatched_selectors?: Array<{
+        id: string;
+        kind?: string;
+        source_kind?: string;
+    }>;
+    /** Compact stored dependency identities available when a removal failed. */
+    available_dependencies?: Array<{
+        id: string;
+        kind: string;
+        source_kind?: string;
+    }>;
     /** Exact verifier findings that caused an integrity-sensitive operation to refuse. */
     verification_errors?: string[];
     /** Local dependency targets that could not be resolved before mutation. */

package/dist/core/shared/errors.js

@@ -1,6 +1,6 @@
 /** Implements the exported pm cli error runtime abstraction for core/shared/errors.ts. */
 
-!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]="a19ff5c0-2c4d-5576-a551-cab35276fdc3")}catch(e){}}();
+!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]="e8873345-5824-5832-9fa3-79719ddc6b58")}catch(e){}}();
 export class PmCliError extends Error {
     /** Value that configures or reports exit code for this contract. */
     exitCode;
@@ -18,4 +18,4 @@ export class PmCliError extends Error {
     }
 }
 //# sourceMappingURL=errors.js.map
-//# debugId=a19ff5c0-2c4d-5576-a551-cab35276fdc3
+//# debugId=e8873345-5824-5832-9fa3-79719ddc6b58

package/dist/core/shared/item-metadata-contract.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @module core/shared/item-metadata-contract
+ *
+ * Declares the dependency-free canonical item metadata vocabulary shared by
+ * storage, query projections, generated contracts, and package consumers.
+ */
+/** Portable project-context fields shared by storage order and structured mutation IO. */
+export declare const ITEM_PROJECT_CONTEXT_KEYS: readonly ["goal", "objective", "value", "impact", "outcome", "why_now", "parent", "reviewer", "risk", "confidence", "sprint", "release", "blocked_by", "blocked_reason", "unblock_note", "reporter", "severity", "environment", "repro_steps", "resolution", "expected_result", "actual_result"];
+declare const ITEM_METADATA_KEY_ORDER_VALUES: readonly ["id", "title", "description", "type", "pm_format_version", "source_type", "type_options", "status", "priority", "tags", "created_at", "updated_at", "deadline", "reminders", "events", "closed_at", "completed_at", "assignee", "claim_principal", "source_owner", "author", "estimated_minutes", "acceptance_criteria", "design", "external_ref", "definition_of_ready", "order", "goal", "objective", "value", "impact", "outcome", "why_now", "parent", "reviewer", "risk", "confidence", "sprint", "release", "blocked_by", "blocked_reason", "unblock_note", "reporter", "severity", "environment", "repro_steps", "resolution", "expected_result", "actual_result", "affected_version", "fixed_version", "component", "regression", "customer_impact", "dependencies", "comments", "notes", "learnings", "files", "tests", "test_runs", "docs", "close_reason", "duplicate_of", "plan_mode", "plan_scope", "plan_harness", "plan_resume_context", "plan_validation", "plan_decisions", "plan_discoveries", "plan_steps"];
+/** Literal union of every canonical built-in item metadata key. */
+export type ItemMetadataKey = (typeof ITEM_METADATA_KEY_ORDER_VALUES)[number];
+/** Public contract for item metadata key order, shared by SDK and presentation-layer consumers. */
+export declare const ITEM_METADATA_KEY_ORDER: ReadonlyArray<string>;
+export {};

package/dist/core/shared/item-metadata-contract.js

@@ -0,0 +1,90 @@
+/**
+ * @module core/shared/item-metadata-contract
+ *
+ * Declares the dependency-free canonical item metadata vocabulary shared by
+ * storage, query projections, generated contracts, and package consumers.
+ */
+/** Portable project-context fields shared by storage order and structured mutation IO. */
+
+!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]="27c5eac3-4580-5f6f-8ae9-b04d0281766d")}catch(e){}}();
+export const ITEM_PROJECT_CONTEXT_KEYS = [
+    "goal",
+    "objective",
+    "value",
+    "impact",
+    "outcome",
+    "why_now",
+    "parent",
+    "reviewer",
+    "risk",
+    "confidence",
+    "sprint",
+    "release",
+    "blocked_by",
+    "blocked_reason",
+    "unblock_note",
+    "reporter",
+    "severity",
+    "environment",
+    "repro_steps",
+    "resolution",
+    "expected_result",
+    "actual_result",
+];
+const ITEM_METADATA_KEY_ORDER_VALUES = [
+    "id",
+    "title",
+    "description",
+    "type",
+    "pm_format_version",
+    "source_type",
+    "type_options",
+    "status",
+    "priority",
+    "tags",
+    "created_at",
+    "updated_at",
+    "deadline",
+    "reminders",
+    "events",
+    "closed_at",
+    "completed_at",
+    "assignee",
+    "claim_principal",
+    "source_owner",
+    "author",
+    "estimated_minutes",
+    "acceptance_criteria",
+    "design",
+    "external_ref",
+    "definition_of_ready",
+    "order",
+    ...ITEM_PROJECT_CONTEXT_KEYS,
+    "affected_version",
+    "fixed_version",
+    "component",
+    "regression",
+    "customer_impact",
+    "dependencies",
+    "comments",
+    "notes",
+    "learnings",
+    "files",
+    "tests",
+    "test_runs",
+    "docs",
+    "close_reason",
+    "duplicate_of",
+    "plan_mode",
+    "plan_scope",
+    "plan_harness",
+    "plan_resume_context",
+    "plan_validation",
+    "plan_decisions",
+    "plan_discoveries",
+    "plan_steps",
+];
+/** Public contract for item metadata key order, shared by SDK and presentation-layer consumers. */
+export const ITEM_METADATA_KEY_ORDER = ITEM_METADATA_KEY_ORDER_VALUES;
+//# sourceMappingURL=item-metadata-contract.js.map
+//# debugId=27c5eac3-4580-5f6f-8ae9-b04d0281766d

package/dist/core/store/item-store.d.ts

@@ -50,6 +50,66 @@ declare function buildDidYouMeanSuggestions(pmRoot: string, badId: string, idPre
 /** Implements build item not found error for the public runtime surface of this module. */
 export declare function buildItemNotFoundError(pmRoot: string, badId: string, idPrefix: string, typeToFolder: Record<string, string>): Promise<PmCliError>;
 declare function bypassesAssigneeConflict(op: string, bypassAssigneeConflict?: boolean): boolean;
+interface ItemMutationResult {
+    item: ItemMetadata;
+    body: string;
+    changedFields: string[];
+    warnings: string[];
+}
+interface ItemMutationParams {
+    pmRoot: string;
+    settings: PmSettings;
+    id: string;
+    op: string;
+    author: string;
+    message?: string;
+    /** Structured immutable context attached to the appended history entry. */
+    historyContext?: Record<string, unknown>;
+    force?: boolean;
+    bypassAssigneeConflict?: boolean;
+    skipNoop?: boolean;
+    extensionFieldNames?: readonly string[];
+    typeToFolder?: Record<string, string>;
+    mutate: (document: ItemDocument) => {
+        changedFields: string[];
+        warnings?: string[];
+    } | Promise<{
+        changedFields: string[];
+        warnings?: string[];
+    }>;
+}
+/** Mutate one item while attaching structured context to its immutable history event. */
+export declare function mutateItemWithHistoryContext(params: {
+    pmRoot: string;
+    settings: PmSettings;
+    id: string;
+    op: string;
+    author: string;
+    message?: string;
+    /** Structured immutable context attached to the appended history entry. */
+    historyContext?: Record<string, unknown>;
+    force?: boolean;
+    bypassAssigneeConflict?: boolean;
+    skipNoop?: boolean;
+    extensionFieldNames?: readonly string[];
+    typeToFolder?: Record<string, string>;
+    mutate: (document: ItemDocument) => {
+        changedFields: string[];
+        warnings?: string[];
+    } | Promise<{
+        changedFields: string[];
+        warnings?: string[];
+    }>;
+}): Promise<{
+    item: ItemMetadata;
+    body: string;
+    changedFields: string[];
+    warnings: string[];
+}>;
+/** Mutate one item while resolving structured history context after its locked mutation. */
+export declare function mutateItemWithHistoryContextResolver(params: Omit<ItemMutationParams, "historyContext"> & {
+    resolveHistoryContext: () => Record<string, unknown> | undefined;
+}): Promise<ItemMutationResult>;
 /** Implements mutate item for the public runtime surface of this module. */
 export declare function mutateItem(params: {
     pmRoot: string;

package/dist/core/store/item-store.js

@@ -4,7 +4,7 @@
  * Reads and writes tracker storage with format-aware helpers for Item Store.
  */
 
-!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]="d24d61bf-7db8-5f35-8dbc-5ef93ec8220b")}catch(e){}}();
+!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]="f49b5141-f348-5954-a87e-8fd957593113")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { getActiveExtensionRegistrations, projectAfterCommandItemSnapshot, recordAfterCommandAffectedItem, runActiveOnReadHooks, runActiveBeforeMutationHooks, runActiveOnWriteHooks, runActiveServiceOverride, } from "../extensions/index.js";
@@ -20,8 +20,9 @@ import { acquireLock } from "../lock/lock.js";
 import { writeFileAtomic } from "../fs/fs-utils.js";
 import { normalizeItemId, normalizeRawItemId } from "../item/id.js";
 import { acquireItemMetadataDerivedIndexLock, listAllDocumentCandidatesCached, listAllDocumentsCached, listAllDocumentsCachedLight, refreshItemMetadataDerivedIndex, } from "./item-metadata-cache.js";
-import { getHistoryPath, getItemPath, ITEM_FILE_EXTENSIONS, } from "./paths.js";
+import { getHistoryPath, getItemPath, ITEM_FILE_EXTENSIONS } from "./paths.js";
 import { resolveGovernanceKnobs } from "./settings.js";
+import { assertReadableTrackerRoot } from "./tracker-preflight.js";
 import { resolveClaimPrincipal } from "../shared/author.js";
 import { nowIso } from "../shared/time.js";
 async function fileExists(targetPath) {
@@ -60,92 +61,6 @@ function resolveItemFormatSearchOrder(preferredFormat) {
     }
     return ["toon", "json_markdown"];
 }
-function trackerRootNotDirectoryError(pmRoot) {
-    return new PmCliError(`Tracker root is not a directory at ${pmRoot}.`, EXIT_CODE.USAGE, {
-        code: "tracker_root_not_directory",
-        reason: "not_a_directory",
-        nextSteps: [
-            "Pass the tracker directory itself, usually <workspace>/.agents/pm.",
-        ],
-    });
-}
-function trackerRootUnreadableError(pmRoot) {
-    return new PmCliError(`Tracker root is not readable at ${pmRoot}.`, EXIT_CODE.GENERIC_FAILURE, {
-        code: "tracker_root_unreadable",
-        reason: "unreadable",
-        nextSteps: [
-            "Grant read and directory-search permission to the tracker root, then retry the SDK read.",
-        ],
-    });
-}
-async function assertMissingMetadataRootAncestors(pmRoot) {
-    const filesystemRoot = path.parse(path.resolve(pmRoot)).root;
-    let ancestor = path.dirname(path.resolve(pmRoot));
-    while (ancestor !== filesystemRoot) {
-        let ancestorStats;
-        try {
-            ancestorStats = await fs.stat(ancestor);
-        }
-        catch (error) {
-            if (isErrno(error, "ENOTDIR")) {
-                throw trackerRootNotDirectoryError(pmRoot);
-            }
-            if (!isErrno(error, "ENOENT")) {
-                throw error;
-            }
-            ancestor = path.dirname(ancestor);
-            continue;
-        }
-        if (!ancestorStats.isDirectory()) {
-            throw trackerRootNotDirectoryError(pmRoot);
-        }
-        break;
-    }
-}
-/** Require metadata enumeration to start from a real directory so an invalid source cannot masquerade as an empty tracker. */
-async function assertItemMetadataRoot(pmRoot) {
-    let stats;
-    try {
-        stats = await fs.stat(pmRoot);
-    }
-    catch (error) {
-        if (isErrno(error, "ENOENT")) {
-            await assertMissingMetadataRootAncestors(pmRoot);
-            throw new PmCliError(`Tracker root does not exist at ${pmRoot}.`, EXIT_CODE.NOT_FOUND, {
-                code: "tracker_root_missing",
-                reason: "missing",
-                nextSteps: [
-                    "Confirm the tracker root path and retry the SDK read.",
-                    "Initialize a tracker before enumerating its item metadata.",
-                ],
-            });
-        }
-        if (isErrno(error, "ENOTDIR")) {
-            throw trackerRootNotDirectoryError(pmRoot);
-        }
-        if (isErrno(error, "EACCES") || isErrno(error, "EPERM")) {
-            throw trackerRootUnreadableError(pmRoot);
-        }
-        throw error;
-    }
-    if (!stats.isDirectory()) {
-        throw trackerRootNotDirectoryError(pmRoot);
-    }
-    if (process.platform !== "win32" &&
-        ((stats.mode & 0o444) === 0 || (stats.mode & 0o111) === 0)) {
-        throw trackerRootUnreadableError(pmRoot);
-    }
-    try {
-        const directory = await fs.opendir(pmRoot);
-        await directory.close();
-    }
-    catch (error) {
-        if (isErrno(error, "EACCES") || isErrno(error, "EPERM")) {
-            throw trackerRootUnreadableError(pmRoot);
-        }
-        throw error;
-    }
-}
 /** Implements locate item for the public runtime surface of this module. */
 export async function locateItem(pmRoot, rawId, idPrefix = "pm-", preferredFormat, typeToFolder = TYPE_TO_FOLDER) {
     const normalizedId = normalizeItemId(rawId, idPrefix);
@@ -189,7 +104,7 @@ export async function readLocatedItem(item, options = {}) {
 }
 /** Implements list all item metadata for the public runtime surface of this module. */
 export async function listAllItemMetadata(pmRoot, preferredFormat, typeToFolder = TYPE_TO_FOLDER, warnings, schema) {
-    await assertItemMetadataRoot(pmRoot);
+    await assertReadableTrackerRoot(pmRoot);
     const documents = await listAllDocumentsCached(pmRoot, preferredFormat, typeToFolder, warnings, schema);
     return documents.map((document) => document.metadata);
 }
@@ -200,13 +115,13 @@ export async function listAllItemMetadata(pmRoot, preferredFormat, typeToFolder
  * read just the light scalar/small fields — see {@link listAllDocumentsCachedLight}.
  */
 export async function listAllItemMetadataLight(pmRoot, preferredFormat, typeToFolder = TYPE_TO_FOLDER, warnings, schema) {
-    await assertItemMetadataRoot(pmRoot);
+    await assertReadableTrackerRoot(pmRoot);
     const documents = await listAllDocumentsCachedLight(pmRoot, preferredFormat, typeToFolder, warnings, schema);
     return documents.map((document) => document.metadata);
 }
 /** List item metadata with bodies, optionally bypassing the derived-index fast path when an integrity workflow must re-read authoritative files. */
 export async function listAllItemMetadataWithBody(pmRoot, preferredFormat, typeToFolder = TYPE_TO_FOLDER, warnings, schema, options = {}) {
-    await assertItemMetadataRoot(pmRoot);
+    await assertReadableTrackerRoot(pmRoot);
     const candidates = await listAllDocumentCandidatesCached(pmRoot, preferredFormat, typeToFolder, warnings, schema, {
         includeBody: true,
         forceSourceScan: options.forceSourceScan,
@@ -377,8 +292,7 @@ async function rollbackMutatedItemWrite(params) {
     }
     await writeFileAtomic(params.originalItemPath, params.originalRaw);
 }
-/** Implements mutate item for the public runtime surface of this module. */
-export async function mutateItem(params) {
+async function mutateItemWithDeferredHistoryContext(params) {
     const prepared = await prepareLockedItem({
         pmRoot: params.pmRoot,
         settings: params.settings,
@@ -409,6 +323,7 @@ export async function mutateItem(params) {
                 warnings: [...parseWarnings, ...(mutation.warnings ?? [])],
             };
         }
+        const historyContext = params.resolveHistoryContext?.();
         mutableDocument.metadata.updated_at = nowIso();
         const afterDocument = canonicalDocument(mutableDocument, {
             schema: params.settings.schema,
@@ -469,6 +384,7 @@ export async function mutateItem(params) {
                 before: beforeDocument,
                 after: afterDocument,
                 message: params.message,
+                context: historyContext,
             });
             try {
                 await appendHistoryEntry(historyPath, entry);
@@ -547,6 +463,22 @@ export async function mutateItem(params) {
         await releaseLock();
     }
 }
+/** Mutate one item while attaching structured context to its immutable history event. */
+export async function mutateItemWithHistoryContext(params) {
+    const { historyContext, ...mutationParams } = params;
+    return mutateItemWithDeferredHistoryContext({
+        ...mutationParams,
+        resolveHistoryContext: () => historyContext,
+    });
+}
+/** Mutate one item while resolving structured history context after its locked mutation. */
+export async function mutateItemWithHistoryContextResolver(params) {
+    return mutateItemWithDeferredHistoryContext(params);
+}
+/** Mutate one item through the compatibility overload while preserving transactional storage and immutable history semantics. */
+export async function mutateItem(params) {
+    return mutateItemWithDeferredHistoryContext(params);
+}
 /** Public contract for item store test only, shared by SDK and presentation-layer consumers. */
 export const itemStoreTestOnly = {
     appendWarning,
@@ -710,4 +642,4 @@ export async function deleteItem(params) {
     }
 }
 //# sourceMappingURL=item-store.js.map
-//# debugId=d24d61bf-7db8-5f35-8dbc-5ef93ec8220b
+//# debugId=f49b5141-f348-5954-a87e-8fd957593113

package/dist/core/store/tracker-preflight.d.ts

@@ -0,0 +1,7 @@
+import { type PmCliErrorRecoveryPayload } from "../shared/errors.js";
+/** Build the non-interactive, tokenized retry that initializes a selected tracker root. */
+export declare function buildTrackerInitializationRecovery(pmRoot: string): PmCliErrorRecoveryPayload;
+/** Require a tracker root to be a readable directory without requiring initialized settings. */
+export declare function assertReadableTrackerRoot(pmRoot: string): Promise<void>;
+/** Require the selected tracker root and its settings marker before an SDK command reads or mutates project state. */
+export declare function assertInitializedTracker(pmRoot: string): Promise<void>;