@unbrained/pm-cli 2026.8.4 → 2026.8.6

package/dist/core/extensions/activation-summary.js

@@ -1,5 +1,5 @@
 
-!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]="8d5e0d6f-5ffa-5302-87da-3e741b80b716")}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]="1d184acd-e639-5b28-a294-98d22de2ebc7")}catch(e){}}();
 import { collectUsedExtensionCapabilities, normalizeExtensionName, } from "./capability-usage.js";
 /**
  * Canonical lifecycle hook kinds paired with their {@link ExtensionHookRegistry}
@@ -77,10 +77,13 @@ export function describeExtensionActivation(activation, options = {}) {
             ? { renderer_ownership: rendererOwnership }
             : {}),
         preflight_overrides: preflight.overrides.filter((entry) => matches(entry.name)).length,
+        preflight_ownership: preflight.overrides
+            .filter((entry) => matches(entry.name))
+            .map((entry) => ({ commands: [...(entry.commands ?? [])] })),
     };
 }
 function sortUnique(values) {
     return [...new Set(values)].sort((left, right) => left.localeCompare(right));
 }
 //# sourceMappingURL=activation-summary.js.map
-//# debugId=8d5e0d6f-5ffa-5302-87da-3e741b80b716
+//# debugId=1d184acd-e639-5b28-a294-98d22de2ebc7

package/dist/core/extensions/contribution-inventory.d.ts

@@ -22,4 +22,5 @@ export declare function createExtensionContributionInventory(summary: {
     renderer_overrides: string[];
     renderer_ownership?: ExtensionContributionInventory["renderer_ownership"];
     preflight_overrides: number;
+    preflight_ownership?: ExtensionContributionInventory["preflight_ownership"];
 }): ExtensionContributionInventory;

package/dist/core/extensions/contribution-inventory.js

@@ -4,7 +4,7 @@
  * Validates and canonicalizes the serializable extension surface inventory.
  */
 
-!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]="8ba4e82a-ab38-5527-84cf-ec553f434a22")}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]="2c4e3831-6644-5db3-a28b-1c6a131da2e1")}catch(e){}}();
 import { normalizeCommandName } from "./extension-runtime-helpers.js";
 const COMMAND_PATH_FIELDS = new Set([
     "commands",
@@ -75,6 +75,29 @@ function normalizeRendererOwnership(value) {
     }
     return ownership.sort((left, right) => left.format.localeCompare(right.format));
 }
+/** Validate preflight command ownership without importing extension code. */
+function normalizePreflightOwnership(value) {
+    if (!Array.isArray(value))
+        return null;
+    const ownership = [];
+    for (const rawEntry of value) {
+        if (typeof rawEntry !== "object" || rawEntry === null)
+            return null;
+        const commands = rawEntry.commands;
+        if (!Array.isArray(commands) ||
+            commands.some((command) => typeof command !== "string")) {
+            return null;
+        }
+        ownership.push({
+            commands: [
+                ...new Set(commands.map((command) => normalizeCommandName(command))),
+            ]
+                .filter((command) => command.length > 0)
+                .sort((left, right) => left.localeCompare(right)),
+        });
+    }
+    return ownership;
+}
 /** Normalize an optional contribution inventory, returning null for malformed data. */
 export function normalizeExtensionContributionInventory(value) {
     if (value === undefined || value === null)
@@ -102,6 +125,13 @@ export function normalizeExtensionContributionInventory(value) {
             return null;
         inventory.renderer_ownership = ownership;
     }
+    const rawPreflightOwnership = record.preflight_ownership;
+    if (rawPreflightOwnership !== undefined) {
+        const ownership = normalizePreflightOwnership(rawPreflightOwnership);
+        if (ownership === null)
+            return null;
+        inventory.preflight_ownership = ownership;
+    }
     return inventory;
 }
 /** Project an activation summary into the versioned static inventory contract. */
@@ -131,7 +161,10 @@ export function createExtensionContributionInventory(summary) {
             ? { renderer_ownership: summary.renderer_ownership }
             : {}),
         preflight_overrides: summary.preflight_overrides,
+        ...(summary.preflight_ownership
+            ? { preflight_ownership: summary.preflight_ownership }
+            : {}),
     };
 }
 //# sourceMappingURL=contribution-inventory.js.map
-//# debugId=8ba4e82a-ab38-5527-84cf-ec553f434a22
+//# debugId=2c4e3831-6644-5db3-a28b-1c6a131da2e1

package/dist/core/extensions/extension-hook-runtime.js

@@ -4,7 +4,7 @@
  * Implements extension runtime contracts and governance for Extension Hook Runtime.
  */
 
-!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]="4c40667c-1e20-5813-b2f3-eb4cb966b246")}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]="ac377139-8ce2-58ad-8005-0ac907a9baed")}catch(e){}}();
 import { cloneCommandOptionsSnapshot, cloneContextSnapshot, cloneGlobalOptionsSnapshot, normalizeCommandName, } from "./extension-runtime-helpers.js";
 import { stableValueEquals } from "../shared/serialization.js";
 import { EXIT_CODE } from "../shared/constants.js";
@@ -337,7 +337,6 @@ export async function runParserOverride(parsers, context) {
 }
 /** Implements run preflight override for the public runtime surface of this module. */
 export async function runPreflightOverride(preflight, context) {
-    const matched = [...preflight.overrides].reverse()[0];
     const baseContext = {
         command: normalizeCommandName(context.command),
         args: cloneContextSnapshot(context.args),
@@ -349,6 +348,9 @@ export async function runPreflightOverride(preflight, context) {
         pm_root_rel: context.pm_root_rel,
     };
     const baseDecision = cloneContextSnapshot(context.decision);
+    const matched = [...preflight.overrides]
+        .reverse()
+        .find((entry) => !entry.commands?.length || entry.commands.includes(baseContext.command));
     if (!matched) {
         return {
             overridden: false,
@@ -693,4 +695,4 @@ export function runRendererOverride(renderers, context) {
     }
 }
 //# sourceMappingURL=extension-hook-runtime.js.map
-//# debugId=4c40667c-1e20-5813-b2f3-eb4cb966b246
+//# debugId=ac377139-8ce2-58ad-8005-0ac907a9baed

package/dist/core/extensions/extension-types.d.ts

@@ -162,6 +162,11 @@ export interface ExtensionContributionInventory {
     }>;
     /** Number of preflight overrides in the package. */
     preflight_overrides?: number;
+    /** Optional command ownership for each preflight override. Empty commands mean global ownership. */
+    preflight_ownership?: Array<{
+        /** Command paths on which the override may run. */
+        commands: string[];
+    }>;
 }
 /** Documents the extension manifest payload exchanged by command, SDK, and package integrations. */
 export interface ExtensionManifest {
@@ -457,6 +462,16 @@ export type CommandHandler = (context: CommandHandlerContext) => unknown;
 export type ParserOverride = (context: ParserOverrideContext) => ParserOverrideDelta | Promise<ParserOverrideDelta>;
 /** Restricts preflight override values accepted by command, SDK, and storage contracts. */
 export type PreflightOverride = (context: PreflightOverrideContext) => PreflightOverrideDelta | Promise<PreflightOverrideDelta>;
+/** Static ownership declaration used to select and diagnose preflight overrides. */
+export interface PreflightOverrideOwnership {
+    /** Normalized command paths on which this preflight override may run. */
+    commands?: string[];
+}
+/** Declarative preflight override paired with statically inspectable ownership. */
+export interface ScopedPreflightOverrideDefinition extends PreflightOverrideOwnership {
+    /** Preflight handler invoked only for a declared command, or globally when unscoped. */
+    run: PreflightOverride;
+}
 /** Explicitly claims or declines one service payload without relying on object identity. */
 export type ServiceOverrideDecision = {
     handled: true;
@@ -1065,6 +1080,8 @@ export interface RegisteredExtensionPreflightOverride {
     name: string;
     /** Value that configures or reports run for this contract. */
     run: PreflightOverride;
+    /** Normalized command paths owned by this preflight override. */
+    commands?: string[];
 }
 /** Documents the registered extension service override payload exchanged by command, SDK, and package integrations. */
 export interface RegisteredExtensionServiceOverride {
@@ -1330,7 +1347,7 @@ export interface ExtensionApi {
     /** Value that configures or reports register parser for this contract. */
     registerParser(command: string, override: ParserOverride): void;
     /** Value that configures or reports register preflight for this contract. */
-    registerPreflight(override: PreflightOverride): void;
+    registerPreflight(override: PreflightOverride | ScopedPreflightOverrideDefinition): void;
     /** Value that configures or reports register service for this contract. */
     registerService(service: ExtensionServiceName, override: ServiceOverride): void;
     /** Value that configures or reports register flags for this contract. */

package/dist/core/extensions/extension-types.js

@@ -1,6 +1,6 @@
 /** Public contract for known extension capabilities, shared by SDK and presentation-layer consumers. */
 
-!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]="938c39a8-6545-5d8b-b717-69138932d528")}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]="50ad61f1-6719-541c-b4e0-4a88468725cf")}catch(e){}}();
 export const KNOWN_EXTENSION_CAPABILITIES = [
     "commands",
     "renderers",
@@ -99,4 +99,4 @@ export function createDefaultExtensionGovernancePolicy() {
     };
 }
 //# sourceMappingURL=extension-types.js.map
-//# debugId=938c39a8-6545-5d8b-b717-69138932d528
+//# debugId=50ad61f1-6719-541c-b4e0-4a88468725cf

package/dist/core/extensions/loader.js

@@ -4,7 +4,7 @@
  * Implements extension runtime contracts and governance for Loader.
  */
 
-!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]="b21c2101-ceac-54b1-acaa-6c8d9c25ae8b")}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]="3d5208e5-0ea5-54a5-82a8-50294b4a0655")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
@@ -17,6 +17,7 @@ import { flattenFlagListValue, isFlagDefaultValueCoercible, resolveFlagValueKind
 import { KNOWN_ITEM_FIELD_TYPES, normalizeItemFieldType, suggestKnownItemFieldType, } from "./item-field-types.js";
 import { snapshotExtensionModuleGraph } from "./module-graph-snapshot.js";
 import { captureExtensionActivationRollback } from "./activation-transaction.js";
+import { collectPreflightCollisionWarnings, normalizePreflightOverride, } from "./preflight-ownership.js";
 import { assertCommandDefinitionMetadataStrings } from "./command-visibility-tier.js";
 import { asRegistrationRecord, assertOptionalBooleanField, assertOptionalFlagDefaultField, assertOptionalStringArrayField, assertOptionalStringField, normalizeOptionalStringArrayField, } from "./registration-validation.js";
 import { describeExtensionLongFlagFailure, findExtensionFlagTokenFailure, } from "./flag-definition-validation.js";
@@ -1675,11 +1676,11 @@ class ExtensionApiRegistrar {
         if (!this.allowRegistration("preflight.override", "registerPreflight", "preflight")) {
             return;
         }
-        assertFunctionHandler("registerPreflight override", override);
+        const normalized = normalizePreflightOverride(override);
         this.#preflightRegistry.overrides.push({
             layer: this.#loadedExtension.layer,
             name: this.#loadedExtension.name,
-            run: override,
+            ...normalized,
         });
     }
     registerService(service, override) {
@@ -2143,6 +2144,9 @@ function collectRendererCollisionWarnings(renderers) {
         }
         const winner = bucket[bucket.length - 1];
         for (const displaced of bucket.slice(0, -1)) {
+            if (winner.commands?.length && displaced.commands?.length && !displaced.commands.some((command) => winner.commands?.includes(command))) {
+                continue;
+            }
             warnings.push(`extension_renderer_collision:${format}:${winner.layer}:${winner.name}:${displaced.layer}:${displaced.name}`);
         }
     }
@@ -2168,15 +2172,6 @@ function collectParserCollisionWarnings(parsers) {
     }
     return warnings;
 }
-function collectPreflightCollisionWarnings(preflight) {
-    if (preflight.overrides.length <= 1) {
-        return [];
-    }
-    const winner = preflight.overrides[preflight.overrides.length - 1];
-    return preflight.overrides
-        .slice(0, -1)
-        .map((displaced) => `extension_preflight_override_collision:${winner.layer}:${winner.name}:${displaced.layer}:${displaced.name}`);
-}
 // Services whose runtime semantics are chain/fall-through (each override gets a chance);
 // for those, registering multiple overrides is by design, not a collision.
 const CHAINED_SERVICE_NAMES = new Set(["output_format"]);
@@ -2317,4 +2312,4 @@ export const _testOnlyLoader = {
     },
 };
 //# sourceMappingURL=loader.js.map
-//# debugId=b21c2101-ceac-54b1-acaa-6c8d9c25ae8b
+//# debugId=3d5208e5-0ea5-54a5-82a8-50294b4a0655

package/dist/core/extensions/preflight-ownership.d.ts

@@ -0,0 +1,5 @@
+import type { ExtensionPreflightRegistry, PreflightOverride, RegisteredExtensionPreflightOverride, ScopedPreflightOverrideDefinition } from "./extension-types.js";
+/** Normalize one callback or scoped definition into a registered handler payload. */
+export declare function normalizePreflightOverride(override: PreflightOverride | ScopedPreflightOverrideDefinition): Pick<RegisteredExtensionPreflightOverride, "run" | "commands">;
+/** Report pairwise overlap while permitting disjoint scoped ownership. */
+export declare function collectPreflightCollisionWarnings(preflight: ExtensionPreflightRegistry): string[];

package/dist/core/extensions/preflight-ownership.js

@@ -0,0 +1,42 @@
+/**
+ * @module core/extensions/preflight-ownership
+ *
+ * Normalizes preflight ownership and diagnoses competing registrations.
+ */
+
+!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]="065f61c6-2123-5a6d-984a-569bb14d6911")}catch(e){}}();
+import { normalizeCommandName } from "./extension-runtime-helpers.js";
+/** Normalize one callback or scoped definition into a registered handler payload. */
+export function normalizePreflightOverride(override) {
+    const run = typeof override === "function" ? override : override.run;
+    if (typeof run !== "function") {
+        throw new TypeError("registerPreflight override requires a function handler");
+    }
+    const commands = [
+        ...new Set((typeof override === "function" ? [] : (override.commands ?? [])).map((command) => {
+            if (typeof command !== "string" || command.trim().length === 0) {
+                throw new TypeError("registerPreflight ownership.commands must contain non-empty command paths");
+            }
+            return normalizeCommandName(command);
+        })),
+    ];
+    return { run, ...(commands.length > 0 ? { commands } : {}) };
+}
+/** Report pairwise overlap while permitting disjoint scoped ownership. */
+export function collectPreflightCollisionWarnings(preflight) {
+    const warnings = [];
+    for (let winnerIndex = 1; winnerIndex < preflight.overrides.length; winnerIndex += 1) {
+        const winner = preflight.overrides[winnerIndex];
+        for (const displaced of preflight.overrides.slice(0, winnerIndex)) {
+            if (winner.commands?.length &&
+                displaced.commands?.length &&
+                !displaced.commands.some((command) => winner.commands.includes(command))) {
+                continue;
+            }
+            warnings.push(`extension_preflight_override_collision:${winner.layer}:${winner.name}:${displaced.layer}:${displaced.name}`);
+        }
+    }
+    return warnings;
+}
+//# sourceMappingURL=preflight-ownership.js.map
+//# debugId=065f61c6-2123-5a6d-984a-569bb14d6911

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

@@ -4,7 +4,7 @@
  * Defines item parsing, formatting, and lifecycle helpers for Item Format.
  */
 
-!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]="c9225594-bc3b-5b07-8703-1debd1a98693")}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]="a4c22692-fe27-5178-bba2-190ac3f80628")}catch(e){}}();
 import { encode as encodeToon } from "@toon-format/toon";
 import { isDeepStrictEqual } from "node:util";
 import { CONFIDENCE_TEXT_VALUES, ISSUE_SEVERITY_VALUES, PLAN_STEP_STATUS_VALUES, RECURRENCE_FREQUENCY_VALUES, RECURRENCE_WEEKDAY_VALUES, STATUS_VALUES, weekdayOrderIndex, } from "../../types/index.js";
@@ -116,6 +116,12 @@ function assertItemMetadataCondition(condition, message) {
         validationError(message);
     }
 }
+function requireItemMetadataRecord(value, message) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        validationError(message);
+    }
+    return value;
+}
 function assertTimestampField(record, fieldName) {
     const rawValue = record[fieldName];
     assertItemMetadataCondition(typeof rawValue === "string", `${fieldName} must be a string`);
@@ -168,10 +174,7 @@ function assertRecurrenceExdates(value) {
     }
 }
 function assertValidRecurrenceRule(recurrence) {
-    assertItemMetadataCondition(typeof recurrence === "object" &&
-        recurrence !== null &&
-        !Array.isArray(recurrence), "event.recurrence must be an object");
-    const recurrenceRecord = recurrence;
+    const recurrenceRecord = requireItemMetadataRecord(recurrence, "event.recurrence must be an object");
     assertItemMetadataCondition(typeof recurrenceRecord.freq === "string", "event.recurrence.freq must be a string");
     const frequency = recurrenceRecord.freq.trim().toLowerCase();
     assertItemMetadataCondition(RECURRENCE_FREQUENCY_VALUES.includes(frequency), `event.recurrence.freq must be one of: ${RECURRENCE_FREQUENCY_VALUES.join(", ")}`);
@@ -261,10 +264,7 @@ function assertReminderEntries(record) {
     }
     assertItemMetadataCondition(Array.isArray(reminders), "reminders must be an array");
     for (const reminder of reminders) {
-        assertItemMetadataCondition(typeof reminder === "object" &&
-            reminder !== null &&
-            !Array.isArray(reminder), "reminders entries must be objects");
-        const reminderRecord = reminder;
+        const reminderRecord = requireItemMetadataRecord(reminder, "reminders entries must be objects");
         assertItemMetadataCondition(typeof reminderRecord.at === "string", "reminder.at must be a string");
         assertItemMetadataCondition(isTimestampLiteral(reminderRecord.at), "reminder.at must be a valid ISO timestamp");
         assertItemMetadataCondition(typeof reminderRecord.text === "string", "reminder.text must be a string");
@@ -294,8 +294,7 @@ function assertEventRecurrence(eventRecord) {
     }
 }
 function assertCalendarEventEntry(event) {
-    assertItemMetadataCondition(typeof event === "object" && event !== null && !Array.isArray(event), "events entries must be objects");
-    const eventRecord = event;
+    const eventRecord = requireItemMetadataRecord(event, "events entries must be objects");
     assertItemMetadataCondition(typeof eventRecord.start_at === "string", "event.start_at must be a string");
     assertItemMetadataCondition(isTimestampLiteral(eventRecord.start_at), "event.start_at must be a valid ISO timestamp");
     if (eventRecord.end_at !== undefined) {
@@ -337,10 +336,8 @@ function assertTypeOptionsField(record) {
     if (typeOptions === undefined) {
         return;
     }
-    assertItemMetadataCondition(typeof typeOptions === "object" &&
-        typeOptions !== null &&
-        !Array.isArray(typeOptions), "type_options must be an object");
-    for (const [optionKey, optionValue] of Object.entries(typeOptions)) {
+    const typeOptionsRecord = requireItemMetadataRecord(typeOptions, "type_options must be an object");
+    for (const [optionKey, optionValue] of Object.entries(typeOptionsRecord)) {
         assertItemMetadataCondition(optionKey.trim().length > 0, "type_options keys must be non-empty");
         assertItemMetadataCondition(typeof optionValue === "string", "type_options values must be strings");
         const optionText = optionValue;
@@ -386,10 +383,7 @@ function assertRuntimeUnknownItemMetadataFields(record, runtimeContext) {
     }
 }
 function assertValidItemMetadata(itemMetadata, runtimeContext) {
-    assertItemMetadataCondition(typeof itemMetadata === "object" &&
-        itemMetadata !== null &&
-        !Array.isArray(itemMetadata), "item metadata must be an object");
-    const record = itemMetadata;
+    const record = requireItemMetadataRecord(itemMetadata, "item metadata must be an object");
     const itemType = assertRequiredItemMetadataFields(record);
     assertStatusItemMetadataField(record, runtimeContext);
     assertPriorityAndTags(record);
@@ -1428,4 +1422,4 @@ export const _testOnlyItemFormat = {
     sortTests,
 };
 //# sourceMappingURL=item-format.js.map
-//# debugId=c9225594-bc3b-5b07-8703-1debd1a98693
+//# debugId=a4c22692-fe27-5178-bba2-190ac3f80628

package/dist/core/shared/constants.js

@@ -1,5 +1,5 @@
 
-!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]="8a44d44d-70c7-5321-b436-08aa6505a854")}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]="46d7e58b-d1b6-5f9d-86cb-76ca671ed127")}catch(e){}}();
 import { createDefaultExtensionGovernancePolicy } from "../extensions/extension-types.js";
 /**
  * Canonical default lifecycle status model and workflow role mapping.
@@ -442,6 +442,7 @@ export const TELEMETRY_ERROR_CATEGORY_BY_CODE = Object.freeze({
     lock_conflict: "conflict",
     terminal_state_conflict: "conflict",
     dependency_failed: "runtime",
+    init_gitignore_unwritable: "runtime",
     merge_git_config_unwritable: "runtime",
     command_failed: "runtime",
     unknown_error: "runtime",
@@ -474,4 +475,4 @@ export function resolveTelemetryErrorCategory(errorCode) {
     return "unknown";
 }
 //# sourceMappingURL=constants.js.map
-//# debugId=8a44d44d-70c7-5321-b436-08aa6505a854
+//# debugId=46d7e58b-d1b6-5f9d-86cb-76ca671ed127

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]="827bddce-74c6-5b36-ae56-bf3b14625f82")}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]="f43e1170-e797-5a0c-b02e-d31e002ab275")}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";
@@ -684,4 +684,4 @@ export async function deleteItem(params) {
     }
 }
 //# sourceMappingURL=item-store.js.map
-//# debugId=827bddce-74c6-5b36-ae56-bf3b14625f82
+//# debugId=f43e1170-e797-5a0c-b02e-d31e002ab275

package/dist/core/store/settings.js

@@ -4,7 +4,7 @@
  * Reads and writes tracker storage with format-aware helpers for Settings.
  */
 
-!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]="9381a512-7436-5d2c-9667-3845b777b901")}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]="a434b9ea-4692-51c5-8761-0f1759fff394")}catch(e){}}();
 import { validateSettings } from "./settings-validator.js";
 import { runActiveOnReadHooks, runActiveOnWriteHooks, } from "../extensions/index.js";
 import { GOVERNANCE_PRESET_DEFAULTS, SETTINGS_DEFAULTS, } from "../shared/constants.js";
@@ -1298,4 +1298,4 @@ export const settingsStoreTestOnly = {
     selectedSettingsReadCacheSignaturesEqual,
 };
 //# sourceMappingURL=settings.js.map
-//# debugId=9381a512-7436-5d2c-9667-3845b777b901
+//# debugId=a434b9ea-4692-51c5-8761-0f1759fff394

package/dist/mcp/server.js

@@ -5,7 +5,7 @@
  * Runs the MCP server adapter that exposes pm actions and contracts to external agents.
  */
 
-!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]="fdff0dd1-1651-5f01-b822-60c075d14ad2")}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]="561c51e0-d7d9-5303-b116-443ad5037943")}catch(e){}}();
 import { realpathSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
@@ -20,7 +20,7 @@ import { PM_MCP_PROMPT_CONTRACTS, PM_MCP_RESOURCE_CONTRACTS, } from "../sdk/agen
 import { commitItemMutations } from "../sdk/item-transaction.js";
 import { isRuntimeRecord } from "../sdk/runtime-input.js";
 import { attachOutputTokenAccounting } from "../sdk/output-token-accounting.js";
-import { parseAtomicMutationControls, validateItemMutationRows, } from "../sdk/structured-mutations.js";
+import { parseAtomicMutationControls, resolveItemMutationDocument, } from "../sdk/structured-mutations.js";
 import { resolveAuthor, resolvePmRoot } from "../sdk/runtime-primitives.js";
 const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
 function resolvePmPackageRoot() {
@@ -99,18 +99,23 @@ const HANDLERS = {
     pm_run: (args) => runAction(args),
     pm_mutate: async (args) => {
         const transactionId = readRequiredString(args, "transactionId");
-        const mutations = validateItemMutationRows(args.mutations);
         const controls = parseAtomicMutationControls(args);
+        const cwd = typeof args.cwd === "string" ? args.cwd : process.cwd();
+        const pmRoot = resolvePmRoot(cwd, typeof args.path === "string" ? args.path : undefined);
+        const resolved = resolveItemMutationDocument(JSON.stringify({ schema_version: 1, mutations: args.mutations }), {
+            transactionId,
+            idPrefix: (await readSettings(pmRoot)).id_prefix,
+        });
+        const { mutations, references } = resolved;
         if (args.dryRun === true) {
             return {
                 transaction_id: transactionId,
                 dry_run: true,
                 mutation_count: mutations.length,
                 mutations,
+                references,
             };
         }
-        const cwd = typeof args.cwd === "string" ? args.cwd : process.cwd();
-        const pmRoot = resolvePmRoot(cwd, typeof args.path === "string" ? args.path : undefined);
         const result = await runWithActiveExtensions({
             cwd: typeof args.cwd === "string" ? args.cwd : undefined,
             path: typeof args.path === "string" ? args.path : undefined,
@@ -127,6 +132,7 @@ const HANDLERS = {
             ...commitResult,
             transaction_id: committedTransactionId,
             mutation_count: mutations.length,
+            references,
         };
     },
     ...Object.fromEntries(Object.entries(NARROW_TOOL_ACTIONS).map(([tool, action]) => [
@@ -615,4 +621,4 @@ if (isInvokedAsMcpMainModule(process.argv[1], import.meta.url)) {
 }
 /* c8 ignore stop */
 //# sourceMappingURL=server.js.map
-//# debugId=fdff0dd1-1651-5f01-b822-60c075d14ad2
+//# debugId=561c51e0-d7d9-5303-b116-443ad5037943

package/dist/mcp/tool-definitions.js

@@ -4,7 +4,7 @@
  * Defines the Tool Definitions module for pm CLI source.
  */
 
-!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]="ade687e6-6547-5a2f-818f-0ed06dce9de5")}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]="89c1ac6d-c217-54ea-8728-5a58762f86d9")}catch(e){}}();
 import { GRAPH_SUBCOMMAND_VALUES, PM_TOOL_ACTIONS, } from "../sdk/cli-contracts/enum-contracts.js";
 import { buildPmActionToolInputSchema } from "../sdk/cli-contracts/tool-schema.js";
 import { RUNTIME_STATUS_ROLE_VALUES } from "../types.js";
@@ -254,8 +254,8 @@ const RAW_TOOLS = [
     },
     {
         name: "pm_mutate",
-        description: "Apply an ordered create/update/close batch atomically through the public pm SDK. " +
-            "Use a stable transactionId to resume interrupted work; set dryRun=true to validate and preview without writes.",
+        description: "Apply an ordered create/update/close/release batch atomically through the public pm SDK. " +
+            "Create rows may declare ref and omit id; @ref forward references resolve deterministically from the stable transactionId. Set dryRun=true to validate and preview without writes.",
         inputSchema: objectSchema({
             transactionId: {
                 type: "string",
@@ -264,16 +264,23 @@ const RAW_TOOLS = [
             mutations: {
                 type: "array",
                 minItems: 1,
-                description: "Ordered rows shaped as {op:create|update|close,id,options?,reason?}.",
+                description: "Ordered rows shaped as {op:create|update|close|release,id?,ref?,options?,reason?}.",
                 items: {
                     type: "object",
                     properties: {
-                        op: { type: "string", enum: ["create", "update", "close"] },
+                        op: {
+                            type: "string",
+                            enum: ["create", "update", "close", "release"],
+                        },
                         id: idSchema,
+                        ref: {
+                            type: "string",
+                            description: "Batch-local create alias; its deterministic id can be referenced as @alias by any row.",
+                        },
                         reason: { type: "string" },
                         options: { type: "object" },
                     },
-                    required: ["op", "id"],
+                    required: ["op"],
                     additionalProperties: false,
                 },
             },
@@ -728,4 +735,4 @@ export function buildMcpToolContracts() {
     }).sort((left, right) => left.name.localeCompare(right.name));
 }
 //# sourceMappingURL=tool-definitions.js.map
-//# debugId=ade687e6-6547-5a2f-818f-0ed06dce9de5
+//# debugId=89c1ac6d-c217-54ea-8728-5a58762f86d9

package/dist/sdk/cli-contracts/agent-output-contracts.d.ts

@@ -1,11 +1,3 @@
-/**
- * @module sdk/cli-contracts/agent-output-contracts
- *
- * Declares the agent-facing output budget vocabulary shared by CLI, SDK,
- * packages, contract discovery, and regression gates. The contracts describe
- * output policy without coupling package authors to pm's renderer.
- */
-import { PM_CORE_COMMAND_NAMES } from "./enum-contracts.js";
 /** Stable degradation stages applied when an output exceeds its token budget. */
 export declare const PM_OUTPUT_DEGRADATION_STEPS: readonly ["full", "compact", "brief", "summary", "counts"];
 /** Restricts deterministic output degradation stages. */
@@ -17,11 +9,16 @@ export type PmOutputBudgetClass = (typeof PM_OUTPUT_BUDGET_CLASSES)[number];
 /** Describes one command's default agent-output budget and degradation policy. */
 export interface PmCommandOutputBudgetContract {
     /** Canonical or compatibility command name. */
-    command: (typeof PM_CORE_COMMAND_NAMES)[number];
+    command: string;
     /** Workload class that selected the default ceiling. */
     budget_class: PmOutputBudgetClass;
     /** Default estimated-token ceiling for representative output. */
     default_max_estimated_tokens: number;
+    /** Encoding-specific ceilings generated from the workload-class default. */
+    default_max_estimated_tokens_by_format: Readonly<{
+        toon: number;
+        json: number;
+    }>;
     /** Ordered fallback projections, from richest to smallest. */
     degradation_ladder: readonly PmOutputDegradationStep[];
     /** Whether callers may explicitly request an unbounded result. */
@@ -29,6 +26,10 @@ export interface PmCommandOutputBudgetContract {
     /** Stable estimate used by gates and SDK consumers. */
     token_estimate: "ceil(utf8_bytes / 4)";
 }
+/** Infer the conservative workload class for a core or package command. */
+export declare function inferPmOutputBudgetClass(command: string): PmOutputBudgetClass;
+/** Build the generated default budget for a core or package command. */
+export declare function createPmCommandOutputBudget(command: string, budgetClass?: PmOutputBudgetClass): PmCommandOutputBudgetContract;
 /**
  * Declares one budget contract while preserving literal command metadata for
  * package-authored registries and test fixtures. Rejects ceilings that cannot
@@ -36,15 +37,14 @@ export interface PmCommandOutputBudgetContract {
  */
 export declare function definePmCommandOutputBudget<TContract extends PmCommandOutputBudgetContract>(contract: TContract): TContract;
 /** Public default budget contract for every built-in pm command. */
-export declare const PM_COMMAND_OUTPUT_BUDGET_CONTRACTS: {
-    command: "search" | "create" | "update" | "list" | "context" | "release" | "schema" | "test" | "test-all" | "events" | "comments" | "notes" | "learnings" | "files" | "docs" | "copy" | "activity" | "history" | "item" | "extension" | "package" | "config" | "packages" | "event" | "list-all" | "list-draft" | "list-open" | "list-in-progress" | "list-blocked" | "list-closed" | "list-canceled" | "ctx" | "init" | "install" | "upgrade" | "focus" | "aggregate" | "get" | "next" | "eval" | "workspace" | "history-redact" | "history-repair" | "history-author-acknowledge" | "history-compact" | "merge" | "profile" | "plan" | "restore" | "update-many" | "close" | "close-many" | "delete" | "append" | "deps" | "graph" | "telemetry" | "health" | "validate" | "gc" | "stats" | "duplicates" | "contracts" | "claim" | "start-task" | "pause-task" | "close-task" | "meet" | "remind" | "help";
-    budget_class: "governance" | "mutation" | "read" | "discovery";
-    default_max_estimated_tokens: number;
-    degradation_ladder: readonly ["full", "compact", "brief", "summary", "counts"];
-    allows_unbounded_opt_out: true;
-    token_estimate: "ceil(utf8_bytes / 4)";
-}[];
+export declare const PM_COMMAND_OUTPUT_BUDGET_CONTRACTS: PmCommandOutputBudgetContract[];
 /** Resolve the declared output budget for one built-in command. */
-export declare function resolvePmCommandOutputBudget(command: string): PmCommandOutputBudgetContract | null;
+export declare function resolvePmCommandOutputBudget(command: string, options: {
+    generateFallback: true;
+}): PmCommandOutputBudgetContract;
+/** Resolve a declared output budget without generating a package fallback. */
+export declare function resolvePmCommandOutputBudget(command: string, options?: {
+    generateFallback?: false;
+}): PmCommandOutputBudgetContract | null;
 /** Estimate conservative token usage from UTF-8 output bytes. */
 export declare function estimatePmOutputTokens(utf8Bytes: number): number;