@unbrained/pm-cli 2026.7.14 → 2026.7.15

package/dist/cli-bundle/chunks/{chunk-Q37E63AM.js → chunk-6CFNAVTF.js}

@@ -1,15 +1,17 @@
 import {
-  resolveAuthor
-} from "./chunk-YRYYFGV3.js";
-import {
-  EMPTY_REPLAY_DOCUMENT,
-  normalizeReplayPatchOps,
+  applyHistoryPatch,
+  ensureMaterializedHistoryTarget,
+  extractPatchFailureContext,
   readHistoryEntries,
-  replayHash,
+  replayHistoryToTarget,
   replayToCanonicalItemDocument,
   replayToItemDocument,
+  resolveHistoryTarget,
   toReplayDocument
-} from "./chunk-4WREH7RT.js";
+} from "./chunk-TD3LVC7D.js";
+import {
+  resolveAuthor
+} from "./chunk-YRYYFGV3.js";
 import {
   acquireLock,
   appendHistoryEntry,
@@ -27,7 +29,7 @@ import {
   recordAfterCommandAffectedItem,
   runActiveOnWriteHooks,
   serializeItemDocument
-} from "./chunk-T4BRCB6Z.js";
+} from "./chunk-XSJUSQAE.js";
 import {
   EXIT_CODE,
   PmCliError,
@@ -39,7 +41,7 @@ import {
   resolveItemTypeRegistry,
   resolvePmRoot,
   writeFileAtomic
-} from "./chunk-AFWZRL7M.js";
+} from "./chunk-BSEQUTQP.js";
 
 // dist/cli/commands/restore.js
 import jsonPatch from "fast-json-patch";
@@ -47,140 +49,18 @@ import fs from "node:fs/promises";
 !(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] = "5f6ae6d9-dbf4-505e-9225-ee123604009e");
+    n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "85cceb36-61f7-52a0-9d61-a0159b3565dc");
   } catch (e2) {
   }
 })();
 function ensureReplayTarget(target, history) {
-  const trimmed = target.trim();
-  if (!trimmed) {
-    throw new PmCliError("Missing restore target. Use a timestamp or version number.", EXIT_CODE.USAGE);
-  }
-  if (/^\d+$/.test(trimmed)) {
-    const version = Number(trimmed);
-    if (!Number.isSafeInteger(version) || version < 1 || version > history.length) {
-      throw new PmCliError(`Restore version must be between 1 and ${history.length} for this item.`, EXIT_CODE.USAGE);
-    }
-    return {
-      kind: "version",
-      raw: trimmed,
-      historyIndex: version - 1
-    };
-  }
-  const parsedTarget = Date.parse(trimmed);
-  if (!Number.isFinite(parsedTarget)) {
-    throw new PmCliError(`Invalid restore target "${target}". Use a positive version number or ISO timestamp.`, EXIT_CODE.USAGE);
-  }
-  let index = -1;
-  for (let i = 0; i < history.length; i += 1) {
-    const entryTimestamp = Date.parse(history[i].ts);
-    if (!Number.isFinite(entryTimestamp)) {
-      throw new PmCliError(`History for this item contains invalid timestamp at entry ${i + 1}.`, EXIT_CODE.GENERIC_FAILURE);
-    }
-    if (entryTimestamp <= parsedTarget) {
-      index = i;
-    }
-  }
-  if (index < 0) {
-    throw new PmCliError(`No history entries exist at or before timestamp ${trimmed}.`, EXIT_CODE.USAGE);
-  }
-  return {
-    kind: "timestamp",
-    raw: trimmed,
-    historyIndex: index
-  };
-}
-function extractPatchFailureContext(patch, error) {
-  const context = {};
-  if (error instanceof Error && error.message.trim().length > 0) {
-    context.reason = error.message.trim();
-  }
-  if (typeof error !== "object" || error === null) {
-    return context;
-  }
-  const candidate = error;
-  if (typeof candidate.index === "number" && Number.isInteger(candidate.index) && candidate.index >= 0) {
-    context.patchIndex = candidate.index;
-  }
-  const operationRecord = typeof candidate.operation === "object" && candidate.operation !== null ? candidate.operation : null;
-  enrichPatchFailureContext(context, operationRecord, patch);
-  return context;
-}
-function enrichPatchFailureContext(context, operationRecord, patch) {
-  if (operationRecord && typeof operationRecord.op === "string") {
-    context.op = operationRecord.op;
-  }
-  if (operationRecord && typeof operationRecord.path === "string") {
-    context.path = operationRecord.path;
-  }
-  if (operationRecord && typeof operationRecord.from === "string") {
-    context.from = operationRecord.from;
-  }
-  if ((context.op === void 0 || context.path === void 0) && context.patchIndex !== void 0) {
-    const fallback = patch[context.patchIndex];
-    if (fallback) {
-      context.op = context.op ?? fallback.op;
-      context.path = context.path ?? fallback.path;
-      context.from = context.from ?? fallback.from;
-    }
-  }
-}
-function applyHistoryPatch(current, patch, entryNumber, entryOp) {
-  try {
-    const normalizedPatch = normalizeReplayPatchOps(patch);
-    const applied = jsonPatch.applyPatch(structuredClone(current), normalizedPatch, true, false).newDocument;
-    if (typeof applied !== "object" || applied === null || !("metadata" in applied) || !("body" in applied) || typeof applied.body !== "string" || typeof applied.metadata !== "object" || applied.metadata === null) {
-      throw new PmCliError(`History replay produced an invalid document shape at entry ${entryNumber}.`, EXIT_CODE.GENERIC_FAILURE);
-    }
-    const replay = applied;
-    return {
-      metadata: replay.metadata,
-      body: replay.body
-    };
-  } catch (error) {
-    if (error instanceof PmCliError) {
-      throw error;
-    }
-    const failureContext = extractPatchFailureContext(patch, error);
-    const contextTokens = [
-      `history_op=${entryOp}`,
-      /* c8 ignore next -- contextual fields are best-effort and may be absent depending on patch failure shape. */
-      failureContext.patchIndex !== void 0 ? `patch_index=${failureContext.patchIndex}` : null,
-      /* c8 ignore next -- contextual fields are best-effort and may be absent depending on patch failure shape. */
-      failureContext.op ? `op=${failureContext.op}` : null,
-      /* c8 ignore next -- contextual fields are best-effort and may be absent depending on patch failure shape. */
-      failureContext.path ? `path=${failureContext.path}` : null,
-      /* c8 ignore next -- contextual fields are best-effort and may be absent depending on patch failure shape. */
-      failureContext.from ? `from=${failureContext.from}` : null
-    ].filter((token) => token !== null);
-    const reasonSuffix = failureContext.reason ? ` ${failureContext.reason}` : "";
-    throw new PmCliError(`Failed to apply history patch at entry ${entryNumber} (${contextTokens.join(", ")}).${reasonSuffix}`, EXIT_CODE.GENERIC_FAILURE);
-  }
-}
-function replayToTarget(history, targetIndex) {
-  let document = structuredClone(EMPTY_REPLAY_DOCUMENT);
-  for (let i = 0; i <= targetIndex; i += 1) {
-    const entry = history[i];
-    const beforeHash = replayHash(document);
-    if (beforeHash !== entry.before_hash) {
-      throw new PmCliError(`History hash mismatch before replay at entry ${i + 1}.`, EXIT_CODE.GENERIC_FAILURE);
-    }
-    document = applyHistoryPatch(document, entry.patch, i + 1, entry.op);
-    const afterHash = replayHash(document);
-    if (afterHash !== entry.after_hash) {
-      throw new PmCliError(`History hash mismatch after replay at entry ${i + 1}.`, EXIT_CODE.GENERIC_FAILURE);
-    }
-  }
-  return document;
-}
-function ensureMaterializedRestoreTarget(replayDocument, target) {
-  if (Object.keys(replayDocument.metadata).length > 0) {
-    return replayDocument;
-  }
-  throw new PmCliError(`Restore target ${target.raw} resolves to a deleted state; choose a version or timestamp where the item exists.`, EXIT_CODE.USAGE);
+  return resolveHistoryTarget(target, history, {
+    errorSubject: "restore",
+    allowFutureTimestamp: true
+  });
 }
 function replayCurrentDocument(history) {
-  const currentReplay = replayToTarget(history, history.length - 1);
+  const currentReplay = replayHistoryToTarget(history, history.length - 1);
   if (Object.keys(currentReplay.metadata).length === 0) {
     return {
       metadata: {},
@@ -325,7 +205,7 @@ async function runRestore(id, target, options, global2) {
     throw new PmCliError(`No history exists for ${resolvedId}; restore is unavailable.`, EXIT_CODE.NOT_FOUND);
   }
   const resolvedTarget = ensureReplayTarget(target, history);
-  const replayDocument = ensureMaterializedRestoreTarget(replayToTarget(history, resolvedTarget.historyIndex), resolvedTarget);
+  const replayDocument = ensureMaterializedHistoryTarget(replayHistoryToTarget(history, resolvedTarget.historyIndex), resolvedTarget);
   const restoredDocument = replayToCanonicalItemDocument(replayDocument, {
     schema: settings.schema
   });
@@ -423,11 +303,11 @@ async function runRestore(id, target, options, global2) {
 var _testOnlyRestoreCommand = {
   applyHistoryPatch,
   changedFields,
-  ensureMaterializedRestoreTarget,
+  ensureMaterializedRestoreTarget: ensureMaterializedHistoryTarget,
   ensureReplayTarget,
   extractPatchFailureContext,
   replayCurrentDocument,
-  replayToTarget,
+  replayToTarget: replayHistoryToTarget,
   resolveRestoreSubject
 };
 
@@ -435,4 +315,4 @@ export {
   runRestore,
   _testOnlyRestoreCommand
 };
-//# sourceMappingURL=chunk-Q37E63AM.js.map
+//# sourceMappingURL=chunk-6CFNAVTF.js.map

package/dist/cli-bundle/chunks/chunk-6CFNAVTF.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../../../../cli/commands/restore.ts"],
+  "sourcesContent": ["/**\n * @module cli/commands/restore\n *\n * Implements the pm restore command surface and its agent-facing runtime behavior.\n */\nimport jsonPatch from \"fast-json-patch\";\nimport fs from \"node:fs/promises\";\nimport {\n  pathExists,\n  readFileIfExists,\n  writeFileAtomic,\n} from \"../../core/fs/fs-utils.js\";\nimport {\n  appendHistoryEntry,\n  createHistoryEntry,\n} from \"../../core/history/history.js\";\nimport {\n  replayToCanonicalItemDocument,\n  replayToItemDocument,\n  toReplayDocument,\n} from \"../../core/history/replay.js\";\nimport {\n  applyHistoryPatch,\n  ensureMaterializedHistoryTarget as ensureMaterializedRestoreTarget,\n  extractPatchFailureContext,\n  readHistoryEntries,\n  replayHistoryToTarget as replayToTarget,\n  resolveHistoryTarget,\n} from \"../../sdk/history-read.js\";\nimport { enforceHistoryStreamPolicyForItem } from \"../../core/history/history-stream-policy.js\";\nimport { normalizeItemId, normalizeRawItemId } from \"../../core/item/id.js\";\nimport {\n  canonicalDocument,\n  serializeItemDocument,\n} from \"../../core/item/item-format.js\";\nimport { resolveItemTypeRegistry } from \"../../core/item/type-registry.js\";\nimport { acquireLock } from \"../../core/lock/lock.js\";\nimport { EXIT_CODE } from \"../../core/shared/constants.js\";\nimport type { GlobalOptions } from \"../../core/shared/command-types.js\";\nimport { PmCliError } from \"../../core/shared/errors.js\";\nimport { nowIso } from \"../../core/shared/time.js\";\nimport {\n  getActiveExtensionRegistrations,\n  projectAfterCommandItemSnapshot,\n  recordAfterCommandAffectedItem,\n  runActiveOnWriteHooks,\n} from \"../../core/extensions/index.js\";\nimport { locateItem, readLocatedItem } from \"../../core/store/item-store.js\";\nimport {\n  getHistoryPath,\n  getItemPath,\n  getSettingsPath,\n  resolvePmRoot,\n} from \"../../core/store/paths.js\";\nimport { readSettings } from \"../../core/store/settings.js\";\nimport { resolveAuthor } from \"../../core/shared/author.js\";\nimport type {\n  HistoryEntry,\n  HistoryPatchOp,\n  ItemDocument,\n  ItemMetadata,\n} from \"../../types/index.js\";\n\ninterface ResolvedRestoreSubject {\n  id: string;\n  historyPath: string;\n  located: Awaited<ReturnType<typeof locateItem>>;\n  historyPolicyWarnings: string[];\n}\n\ninterface RestoreCurrentState {\n  document: ItemDocument;\n  originalRaw: string | null;\n}\n\n/** Documents the restore command options payload exchanged by command, SDK, and package integrations. */\nexport interface RestoreCommandOptions {\n  /** Value that configures or reports author for this contract. */\n  author?: string;\n  /** Human-readable explanation suitable for logs and agent-facing output. */\n  message?: string;\n  /** Value that configures or reports force for this contract. */\n  force?: boolean;\n}\n\n/** Documents the restore result payload exchanged by command, SDK, and package integrations. */\nexport interface RestoreResult {\n  /** Value that configures or reports item for this contract. */\n  item: ItemMetadata;\n  /** Value that configures or reports restored from for this contract. */\n  restored_from: {\n    kind: \"version\" | \"timestamp\";\n    target: string;\n    history_index: number;\n    entry_ts: string;\n    entry_op: string;\n  };\n  /** Value that configures or reports changed fields for this contract. */\n  changed_fields: string[];\n  /** Value that configures or reports warnings for this contract. */\n  warnings: string[];\n}\n\n/** Resolve restore targets with the command's established wording and at-or-before timestamp semantics. */\nfunction ensureReplayTarget(target: string, history: readonly HistoryEntry[]) {\n  return resolveHistoryTarget(target, history, {\n    errorSubject: \"restore\",\n    allowFutureTimestamp: true,\n  });\n}\n\nfunction replayCurrentDocument(history: HistoryEntry[]): ItemDocument {\n  const currentReplay = replayToTarget(history, history.length - 1);\n  if (Object.keys(currentReplay.metadata).length === 0) {\n    return {\n      metadata: {} as ItemMetadata,\n      body: currentReplay.body,\n    };\n  }\n  return canonicalDocument(replayToItemDocument(currentReplay));\n}\n\nasync function resolveRestoreSubject(\n  pmRoot: string,\n  id: string,\n  settings: Awaited<ReturnType<typeof readSettings>>,\n  typeToFolder: Record<string, string>,\n): Promise<ResolvedRestoreSubject> {\n  const located = await locateItem(\n    pmRoot,\n    id,\n    settings.id_prefix,\n    settings.item_format,\n    typeToFolder,\n  );\n  if (located) {\n    const historyPath = getHistoryPath(pmRoot, located.id);\n    const historyPolicy = await enforceHistoryStreamPolicyForItem({\n      pmRoot,\n      settings,\n      itemId: located.id,\n      commandLabel: \"restore\",\n    });\n    return {\n      id: located.id,\n      historyPath,\n      located,\n      historyPolicyWarnings: historyPolicy.warnings,\n    };\n  }\n\n  const normalizedId = normalizeItemId(id, settings.id_prefix);\n  const rawNormalizedId = normalizeRawItemId(id);\n  /* c8 ignore start -- raw-id fallback is covered by normalize-item-id utility tests. */\n  const candidateIds =\n    normalizedId === rawNormalizedId\n      ? [normalizedId]\n      : [normalizedId, rawNormalizedId];\n  /* c8 ignore stop */\n  for (const candidateId of candidateIds) {\n    const historyPath = getHistoryPath(pmRoot, candidateId);\n    if (await pathExists(historyPath)) {\n      return {\n        id: candidateId,\n        historyPath,\n        located: null,\n        historyPolicyWarnings: [],\n      };\n    }\n  }\n\n  throw new PmCliError(`Item ${id} not found`, EXIT_CODE.NOT_FOUND);\n}\n\nfunction changedFields(\n  beforeDocument: ItemDocument,\n  afterDocument: ItemDocument,\n): string[] {\n  const beforeReplay = toReplayDocument(beforeDocument);\n  const afterReplay = toReplayDocument(afterDocument);\n  const patch = jsonPatch.compare(\n    beforeReplay,\n    afterReplay,\n  ) as HistoryPatchOp[];\n  const fields = new Set<string>();\n\n  for (const op of patch) {\n    if (op.path === \"/body\" || op.path.startsWith(\"/body/\")) {\n      fields.add(\"body\");\n      continue;\n    }\n    const segment = op.path\n      .replace(/^\\/(?:metadata|front_matter)\\/?/, \"\")\n      .split(\"/\")[0];\n    fields.add(segment.replaceAll(\"~1\", \"/\").replaceAll(\"~0\", \"~\"));\n  }\n\n  return Array.from(fields).sort((a, b) => a.localeCompare(b));\n}\n\nasync function loadRestoreStateUnderLock(params: {\n  pmRoot: string;\n  resolvedId: string;\n  subject: ResolvedRestoreSubject;\n  settings: Awaited<ReturnType<typeof readSettings>>;\n  typeToFolder: Record<string, string>;\n  historyRawBeforeLock: string | null;\n  currentItemRawBeforeLock: string | null;\n}): Promise<{\n  loadedItemUnderLock: Awaited<ReturnType<typeof readLocatedItem>> | null;\n  existingItemPath: string | null;\n}> {\n  const historyRawUnderLock = await readFileIfExists(\n    params.subject.historyPath,\n  );\n  if (historyRawUnderLock !== params.historyRawBeforeLock) {\n    throw new PmCliError(\n      `History for ${params.resolvedId} changed while waiting for lock; retry restore.`,\n      EXIT_CODE.CONFLICT,\n    );\n  }\n  const locatedUnderLock = await locateItem(\n    params.pmRoot,\n    params.resolvedId,\n    params.settings.id_prefix,\n    params.settings.item_format,\n    params.typeToFolder,\n  );\n  const loadedItemUnderLock = locatedUnderLock\n    ? await readLocatedItem(locatedUnderLock, {\n        schema: params.settings.schema,\n      })\n    : null;\n  if ((loadedItemUnderLock?.raw ?? null) !== params.currentItemRawBeforeLock) {\n    throw new PmCliError(\n      `Item ${params.resolvedId} changed while waiting for lock; retry restore.`,\n      EXIT_CODE.CONFLICT,\n    );\n  }\n  return {\n    loadedItemUnderLock,\n    existingItemPath: locatedUnderLock?.itemPath ?? null,\n  };\n}\n\nfunction resolveRestoreCurrentState(\n  loadedItemUnderLock: Awaited<ReturnType<typeof readLocatedItem>> | null,\n  history: HistoryEntry[],\n): RestoreCurrentState {\n  if (loadedItemUnderLock) {\n    return {\n      document: loadedItemUnderLock.document,\n      originalRaw: loadedItemUnderLock.raw,\n    };\n  }\n  return { document: replayCurrentDocument(history), originalRaw: null };\n}\n\nfunction collectRestoreOwnershipWarnings(params: {\n  document: ItemDocument;\n  author: string;\n  force: boolean | undefined;\n  enforcement: \"strict\" | \"warn\" | \"none\";\n  resolvedId: string;\n}): string[] {\n  const assigned = params.document.metadata.assignee?.trim();\n  const hasOwnershipConflict =\n    assigned && assigned !== params.author && !params.force;\n  if (!hasOwnershipConflict) {\n    return [];\n  }\n  if (params.enforcement === \"strict\") {\n    throw new PmCliError(\n      `Item ${params.resolvedId} is assigned to ${assigned}. Use --force to override.`,\n      EXIT_CODE.CONFLICT,\n    );\n  }\n  return params.enforcement === \"warn\"\n    ? [`ownership_warning:assignee_conflict:${params.resolvedId}:${assigned}`]\n    : [];\n}\n\nasync function restorePreviousItemAfterHistoryFailure(params: {\n  existingItemPath: string | null;\n  resolvedOriginalRaw: string | null;\n  restoredItemPath: string;\n}): Promise<void> {\n  if (\n    params.existingItemPath &&\n    params.resolvedOriginalRaw !== null &&\n    params.restoredItemPath !== params.existingItemPath\n  ) {\n    await writeFileAtomic(params.existingItemPath, params.resolvedOriginalRaw);\n    await fs.rm(params.restoredItemPath, { force: true });\n    return;\n  }\n  if (params.existingItemPath && params.resolvedOriginalRaw !== null) {\n    await writeFileAtomic(params.existingItemPath, params.resolvedOriginalRaw);\n    return;\n  }\n  await fs.rm(params.restoredItemPath, { force: true });\n}\n\nasync function runRestoreWriteHooks(params: {\n  restoredItemPath: string;\n  historyPath: string;\n  before: ItemDocument;\n  after: ItemDocument;\n}): Promise<string[]> {\n  return [\n    ...(await runActiveOnWriteHooks({\n      path: params.restoredItemPath,\n      scope: \"project\",\n      op: \"restore\",\n      item_id: params.after.metadata.id,\n      item_type: params.after.metadata.type,\n      before: params.before,\n      after: params.after,\n      changed_fields: [\"restored\"],\n    })),\n    ...(await runActiveOnWriteHooks({\n      path: params.historyPath,\n      scope: \"project\",\n      op: \"restore:history\",\n      item_id: params.after.metadata.id,\n      item_type: params.after.metadata.type,\n      before: params.before,\n      after: params.after,\n      changed_fields: [\"restored\"],\n    })),\n  ];\n}\n\n/** Implements run restore for the public runtime surface of this module. */\nexport async function runRestore(\n  id: string,\n  target: string,\n  options: RestoreCommandOptions,\n  global: GlobalOptions,\n): Promise<RestoreResult> {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  if (!(await pathExists(getSettingsPath(pmRoot)))) {\n    throw new PmCliError(\n      `Tracker is not initialized at ${pmRoot}. Run pm init first.`,\n      EXIT_CODE.NOT_FOUND,\n    );\n  }\n\n  const settings = await readSettings(pmRoot);\n  const typeRegistry = resolveItemTypeRegistry(\n    settings,\n    getActiveExtensionRegistrations(),\n  );\n  const subject = await resolveRestoreSubject(\n    pmRoot,\n    id,\n    settings,\n    typeRegistry.type_to_folder,\n  );\n  const resolvedId = subject.id;\n  const historyRawBeforeLock = await readFileIfExists(subject.historyPath);\n  const history = await readHistoryEntries(subject.historyPath, resolvedId);\n  if (history.length === 0) {\n    throw new PmCliError(\n      `No history exists for ${resolvedId}; restore is unavailable.`,\n      EXIT_CODE.NOT_FOUND,\n    );\n  }\n\n  const resolvedTarget = ensureReplayTarget(target, history);\n  const replayDocument = ensureMaterializedRestoreTarget(\n    replayToTarget(history, resolvedTarget.historyIndex),\n    resolvedTarget,\n  );\n  const restoredDocument = replayToCanonicalItemDocument(replayDocument, {\n    schema: settings.schema,\n  });\n\n  if (restoredDocument.metadata.id !== resolvedId) {\n    throw new PmCliError(\n      `Restore target resolved to item ${restoredDocument.metadata.id}, expected ${resolvedId}.`,\n      EXIT_CODE.GENERIC_FAILURE,\n    );\n  }\n  const loadedItemBeforeLock = subject.located\n    ? await readLocatedItem(subject.located, { schema: settings.schema })\n    : null;\n  const currentItemRawBeforeLock = loadedItemBeforeLock?.raw ?? null;\n\n  const author = resolveAuthor(options.author, settings.author_default);\n  const releaseLock = await acquireLock(\n    pmRoot,\n    resolvedId,\n    settings.locks.ttl_seconds,\n    author,\n    Boolean(options.force),\n    settings.governance.force_required_for_stale_lock,\n    settings.locks.wait_ms,\n  );\n\n  try {\n    const { loadedItemUnderLock, existingItemPath } =\n      await loadRestoreStateUnderLock({\n        pmRoot,\n        resolvedId,\n        subject,\n        settings,\n        typeToFolder: typeRegistry.type_to_folder,\n        historyRawBeforeLock,\n        currentItemRawBeforeLock,\n      });\n    const itemFormat = \"toon\";\n    const currentState = resolveRestoreCurrentState(\n      loadedItemUnderLock,\n      history,\n    );\n    const ownershipWarnings = collectRestoreOwnershipWarnings({\n      document: currentState.document,\n      author,\n      force: options.force,\n      enforcement: settings.governance.ownership_enforcement,\n      resolvedId,\n    });\n\n    const serializedRestore = serializeItemDocument(restoredDocument, {\n      format: itemFormat,\n      schema: settings.schema,\n    });\n    /* c8 ignore next -- restored item path typing is exercised in restore integration workflows. */\n    const restoredItemPath = getItemPath(\n      pmRoot,\n      restoredDocument.metadata.type,\n      resolvedId,\n      itemFormat,\n      typeRegistry.type_to_folder,\n    );\n    await writeFileAtomic(restoredItemPath, serializedRestore);\n    if (existingItemPath && restoredItemPath !== existingItemPath) {\n      await fs.rm(existingItemPath);\n    }\n\n    const historyEntry = createHistoryEntry({\n      nowIso: nowIso(),\n      author,\n      op: \"restore\",\n      before: currentState.document,\n      after: restoredDocument,\n      message: options.message,\n    });\n\n    try {\n      await appendHistoryEntry(subject.historyPath, historyEntry);\n    } catch (error: unknown) {\n      await restorePreviousItemAfterHistoryFailure({\n        existingItemPath,\n        resolvedOriginalRaw: currentState.originalRaw,\n        restoredItemPath,\n      });\n      throw error;\n    }\n    const restoreChangedFields = changedFields(\n      currentState.document,\n      restoredDocument,\n    );\n    const hookWarnings = await runRestoreWriteHooks({\n      restoredItemPath,\n      historyPath: subject.historyPath,\n      before: currentState.document,\n      after: restoredDocument,\n    });\n    recordAfterCommandAffectedItem({\n      id: restoredDocument.metadata.id,\n      op: \"restore\",\n      item_type: restoredDocument.metadata.type,\n      previous_status: currentState.document.metadata.status,\n      status: restoredDocument.metadata.status,\n      previous: projectAfterCommandItemSnapshot(\n        currentState.document.metadata,\n        restoreChangedFields,\n      ),\n      current: projectAfterCommandItemSnapshot(\n        restoredDocument.metadata,\n        restoreChangedFields,\n      ),\n      changed_fields: restoreChangedFields,\n    });\n\n    const targetEntry = history[resolvedTarget.historyIndex];\n    return {\n      item: restoredDocument.metadata,\n      restored_from: {\n        kind: resolvedTarget.kind,\n        target: resolvedTarget.raw,\n        history_index: resolvedTarget.historyIndex + 1,\n        entry_ts: targetEntry.ts,\n        entry_op: targetEntry.op,\n      },\n      changed_fields: restoreChangedFields,\n      warnings: [\n        ...subject.historyPolicyWarnings,\n        ...ownershipWarnings,\n        ...hookWarnings,\n      ],\n    };\n  } finally {\n    await releaseLock();\n  }\n}\n\n/** Public contract for test only restore command, shared by SDK and presentation-layer consumers. */\nexport const _testOnlyRestoreCommand = {\n  applyHistoryPatch,\n  changedFields,\n  ensureMaterializedRestoreTarget,\n  ensureReplayTarget,\n  extractPatchFailureContext,\n  replayCurrentDocument,\n  replayToTarget,\n  resolveRestoreSubject,\n};\n"],
+  "mappings": "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",
+  "names": ["global"]
+}

package/dist/cli-bundle/chunks/{chunk-3TL7WOEF.js → chunk-6N2VXVTQ.js}

@@ -3,7 +3,7 @@
 import {
   BUILTIN_ITEM_TYPE_VALUES,
   toDefaultFolder
-} from "./chunk-GXXC7QSK.js";
+} from "./chunk-QKECXBBG.js";
 
 // dist/core/schema/item-types-file.js
 var BUILTIN_NAME_LOOKUP = new Map(BUILTIN_ITEM_TYPE_VALUES.map((name) => [name.toLowerCase(), name]));
@@ -258,6 +258,6 @@ export {
   buildInvalidTypeHint,
   buildInvalidTypeError
 };
-//# sourceMappingURL=chunk-3TL7WOEF.js.map
+//# sourceMappingURL=chunk-6N2VXVTQ.js.map
 
 //# debugId=74723401-1f8b-51b4-ab46-a5cd94e0f9f2

package/dist/cli-bundle/chunks/{chunk-ERL2YFJ2.js → chunk-6S3YSUYG.js}

@@ -14,7 +14,7 @@ import {
   recordAfterCommandAffectedItem,
   runActiveOnWriteHooks,
   serializeItemDocument
-} from "./chunk-T4BRCB6Z.js";
+} from "./chunk-XSJUSQAE.js";
 import {
   EXIT_CODE,
   ITEM_METADATA_KEY_ORDER,
@@ -29,7 +29,7 @@ import {
   resolvePmRoot,
   resolveRuntimeStatusRegistry,
   writeFileAtomic
-} from "./chunk-AFWZRL7M.js";
+} from "./chunk-BSEQUTQP.js";
 
 // dist/cli/commands/copy.js
 !(function() {
@@ -177,4 +177,4 @@ async function runCopy(sourceId, options, global2) {
 export {
   runCopy
 };
-//# sourceMappingURL=chunk-ERL2YFJ2.js.map
+//# sourceMappingURL=chunk-6S3YSUYG.js.map

package/dist/cli-bundle/chunks/{chunk-ZUKSZVBW.js → chunk-7B67ZL4N.js}

@@ -11,11 +11,11 @@ import {
   readFirstStringFromCommanderOptions,
   readFirstValueFromCommanderOptions,
   readStringArrayFromCommanderOptions
-} from "./chunk-2QIQGYPW.js";
+} from "./chunk-H5APFTHZ.js";
 import {
   printError,
   writeStdout
-} from "./chunk-JL7WZ4O2.js";
+} from "./chunk-IG3SWA4A.js";
 import {
   getActiveExtensionRegistrations,
   locateItem,
@@ -24,7 +24,7 @@ import {
   readSettings,
   runActiveServiceOverride,
   setActiveCommandResult
-} from "./chunk-T4BRCB6Z.js";
+} from "./chunk-XSJUSQAE.js";
 import {
   EXIT_CODE,
   PmCliError,
@@ -41,7 +41,7 @@ import {
   toNonEmptyString,
   trimTrailingSlashes,
   writeFileAtomic
-} from "./chunk-AFWZRL7M.js";
+} from "./chunk-BSEQUTQP.js";
 
 // dist/cli/registration-helpers.js
 import { Option } from "commander";
@@ -2168,7 +2168,7 @@ async function refreshSearchArtifactsForMutation(pmRoot, itemIds, options = {})
 !(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] = "3c5edb95-34a6-5552-9902-ad8d96098b8d");
+    n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "62e699ef-0924-5d10-b6b5-7d1965cc40ab");
   } catch (e2) {
   }
 })();
@@ -2246,7 +2246,8 @@ function getGlobalOptions(command) {
     path: typeof opts.pmPath === "string" ? opts.pmPath : typeof opts.path === "string" ? opts.path : void 0,
     noExtensions: opts.extensions === false,
     noPager: Boolean(opts.noPager),
-    profile: Boolean(opts.profile)
+    profile: Boolean(opts.profile),
+    author: typeof opts.author === "string" ? opts.author : void 0
   };
 }
 function getCommandPath(command) {
@@ -3034,4 +3035,4 @@ export {
   normalizeNextOptions,
   invalidateSearchCachesForMutation
 };
-//# sourceMappingURL=chunk-ZUKSZVBW.js.map
+//# sourceMappingURL=chunk-7B67ZL4N.js.map