@unbrained/pm-cli 2026.9.4 → 2026.9.5

package/dist/sdk/lifecycle/restore.js

@@ -4,13 +4,22 @@
  * Implements the SDK-owned restore lifecycle operation shared by every surface.
  */
 
-!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]="db5f3a6d-9ae5-5f9b-bedf-766b2b79324c")}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]="7a3effef-6ba8-51ba-ae99-436d4ef69813")}catch(e){}}();
 import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import jsonPatch from "fast-json-patch";
 import fs from "node:fs/promises";
-import { pathExists, readFileIfExists, writeFileAtomic, appendHistoryEntry, createHistoryEntry, replayToCanonicalItemDocument, replayToItemDocument, toReplayDocument, enforceHistoryStreamPolicyForItem, normalizeItemId, normalizeRawItemId, canonicalDocument, serializeItemDocument, resolveItemTypeRegistry, acquireLock, EXIT_CODE, PmCliError, nowIso, getActiveExtensionRegistrations, projectAfterCommandItemSnapshot, recordAfterCommandAffectedItem, runActiveOnWriteHooks, runActiveBeforeMutationHooks, locateItem, createMutationGuardSdk, readLocatedItem, getHistoryPath, getItemPath, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
+import { readLocatedItemSnapshot } from "../../core/store/item-store.js";
+import { historyVersionOffset } from "../../core/history/version-address.js";
+import { pathExists, readFileIfExists, writeFileAtomic, appendHistoryEntry, createHistoryEntry, replayToCanonicalItemDocument, replayToItemDocument, toReplayDocument, enforceHistoryStreamPolicyForItem, normalizeItemId, normalizeRawItemId, canonicalDocument, serializeItemDocument, resolveItemTypeRegistry, acquireLock, EXIT_CODE, PmCliError, nowIso, getActiveExtensionRegistrations, projectAfterCommandItemSnapshot, recordAfterCommandAffectedItem, runActiveOnWriteHooks, runActiveBeforeMutationHooks, locateItem, createMutationGuardSdk, getHistoryPath, getItemPath, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
 import { applyHistoryPatch, ensureMaterializedHistoryTarget as ensureMaterializedRestoreTarget, extractPatchFailureContext, readHistoryEntries, replayHistoryToTarget as replayToTarget, resolveHistoryTarget, } from "../history-read.js";
 import { acquireItemMetadataDerivedIndexLock, refreshItemMetadataDerivedIndex, } from "../item-metadata-index.js";
+/** Read a restore input without discarding unreadable bytes needed for rollback. */
+async function readRestoreItem(located, settings, history) {
+    const snapshot = await readLocatedItemSnapshot(located, { schema: settings.schema });
+    return snapshot.error === null
+        ? { raw: snapshot.raw, document: snapshot.document }
+        : { raw: snapshot.raw, document: replayCurrentDocument(history), recovered: true };
+}
 /** Resolve restore targets with the command's established wording and at-or-before timestamp semantics. */
 function ensureReplayTarget(target, history) {
     return resolveHistoryTarget(target, history, {
@@ -82,6 +91,7 @@ function changedFields(beforeDocument, afterDocument) {
     }
     return Array.from(fields).sort((a, b) => a.localeCompare(b));
 }
+/** Reload item and history under the caller's lock, refusing changes since the recovery snapshot. */
 async function loadRestoreStateUnderLock(params) {
     const historyRawUnderLock = await readFileIfExists(params.subject.historyPath);
     if (historyRawUnderLock !== params.historyRawBeforeLock) {
@@ -89,9 +99,7 @@ async function loadRestoreStateUnderLock(params) {
     }
     const locatedUnderLock = await locateItem(params.pmRoot, params.resolvedId, params.settings.id_prefix, params.settings.item_format, params.typeToFolder);
     const loadedItemUnderLock = locatedUnderLock
-        ? await readLocatedItem(locatedUnderLock, {
-            schema: params.settings.schema,
-        })
+        ? await readRestoreItem(locatedUnderLock, params.settings, params.history)
         : null;
     if ((loadedItemUnderLock?.raw ?? null) !== params.currentItemRawBeforeLock) {
         throw new PmCliError(`Item ${params.resolvedId} changed while waiting for lock; retry restore.`, EXIT_CODE.CONFLICT);
@@ -183,7 +191,7 @@ export async function runRestore(id, target, options, global) {
         throw new PmCliError(`Restore target resolved to item ${restoredDocument.metadata.id}, expected ${resolvedId}.`, EXIT_CODE.GENERIC_FAILURE);
     }
     const loadedItemBeforeLock = subject.located
-        ? await readLocatedItem(subject.located, { schema: settings.schema })
+        ? await readRestoreItem(subject.located, settings, history)
         : null;
     const currentItemRawBeforeLock = loadedItemBeforeLock?.raw ?? null;
     const author = resolveAuthor(options.author, settings.author_default);
@@ -197,6 +205,7 @@ export async function runRestore(id, target, options, global) {
             typeToFolder: typeRegistry.type_to_folder,
             historyRawBeforeLock,
             currentItemRawBeforeLock,
+            history,
         });
         const itemFormat = "toon";
         const currentState = resolveRestoreCurrentState(loadedItemUnderLock, history);
@@ -282,17 +291,20 @@ export async function runRestore(id, target, options, global) {
             changed_fields: restoreChangedFields,
         });
         const targetEntry = history[resolvedTarget.historyIndex];
+        const offset = historyVersionOffset(history, true);
         return {
             item: restoredDocument.metadata,
             restored_from: {
                 kind: resolvedTarget.kind,
                 target: resolvedTarget.raw,
                 history_index: resolvedTarget.historyIndex + 1,
+                version: offset === null ? null : offset + resolvedTarget.historyIndex + 1,
                 entry_ts: targetEntry.ts,
                 entry_op: targetEntry.op,
             },
             changed_fields: restoreChangedFields,
             warnings: [
+                ...(loadedItemUnderLock?.recovered ? ["restore_unreadable_item_recovered"] : []),
                 ...subject.historyPolicyWarnings,
                 ...ownershipWarnings,
                 ...derivedIndexWarnings,
@@ -316,4 +328,4 @@ export const _testOnlyRestoreCommand = {
     resolveRestoreSubject,
 };
 //# sourceMappingURL=restore.js.map
-//# debugId=db5f3a6d-9ae5-5f9b-bedf-766b2b79324c
+//# debugId=7a3effef-6ba8-51ba-ae99-436d4ef69813

package/dist/sdk/output-projection.d.ts

@@ -13,6 +13,8 @@ export interface OutputOmissionReceipt {
     omitted_field_group_count: number;
     /** Withheld groups and the exact opt-in that restores each one. */
     omitted_field_groups: OutputProjectionFieldGroup[];
+    /** Population counted by context summary regardless of bounded focus rows. */
+    summary_scope?: "matching_items";
 }
 /** Self-describing projection metadata that built-ins and extensions can use to derive receipts without command-specific code. */
 export interface OutputProjectionDeclaration {
@@ -59,7 +61,7 @@ export declare const PM_READ_ROW_CONTRACTS: {
         readonly fields: "supported";
     };
     readonly next: {
-        readonly row_keys: readonly ["recommended", "ready", "decision_needed", "blocked", "held_by_others"];
+        readonly row_keys: readonly ["recommended", "ready", "decision_needed", "gate_needed", "containers", "blocked", "held_by_others"];
         readonly fields: "unsupported";
     };
     readonly search: {

package/dist/sdk/output-projection.js

@@ -4,7 +4,7 @@
  * Declares machine-readable field-group omissions for bounded command results.
  */
 
-!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]="8ffd2cd5-8b7e-5ae1-a0c6-aab488edb73c")}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]="db6180ed-0b18-5bf8-bcc1-24171e2dfdc4")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 const MATERIAL_FIELD_GROUPS_BY_RESULT = new WeakMap();
@@ -24,6 +24,8 @@ export const PM_READ_ROW_CONTRACTS = {
             "recommended",
             "ready",
             "decision_needed",
+            "gate_needed",
+            "containers",
             "blocked",
             "held_by_others",
         ],
@@ -208,6 +210,8 @@ const READ_RESULT_SENTINEL_KEYS = {
         "recommended",
         "ready",
         "decision_needed",
+        "gate_needed",
+        "containers",
         "blocked",
         "held_by_others",
     ],
@@ -314,7 +318,11 @@ function resolveDeclaredProjectionReceipt(result) {
 function resolveContextReceipt(result) {
     if (!Array.isArray(result.sections_included))
         return undefined;
-    return createOutputOmissionReceipt(CONTEXT_FIELD_GROUPS, new Set(result.sections_included.filter((section) => typeof section === "string")));
+    const receipt = createOutputOmissionReceipt(CONTEXT_FIELD_GROUPS, new Set(result.sections_included.filter((section) => typeof section === "string")));
+    if (isRecord(result.summary) && result.summary.scope === "matching_items") {
+        receipt.summary_scope = "matching_items";
+    }
+    return receipt;
 }
 function resolveGetReceipt(result) {
     if (!isRecord(result.item))
@@ -420,4 +428,4 @@ export function attachOutputOmissionReceipt(command, result) {
         : { ...disclosedResult, omission_receipt: receipt };
 }
 //# sourceMappingURL=output-projection.js.map
-//# debugId=8ffd2cd5-8b7e-5ae1-a0c6-aab488edb73c
+//# debugId=db6180ed-0b18-5bf8-bcc1-24171e2dfdc4