@unbrained/pm-cli 2026.11.3 → 2026.11.5

package/dist/core/config/positional-value.d.ts

@@ -39,7 +39,7 @@ reason:string;
 /** Restricts config positional result values accepted by command, SDK, and storage contracts. */
 export type ConfigPositionalResult = ConfigPositionalRouted | ConfigPositionalNotRoutable;
 /** Canonical snake-case config keys accepted by the config command and positional router. */
-export type ConfigKey = "definition_of_done" | "item_format" | "history_missing_stream_policy" | "sprint_release_format_policy" | "parent_reference_policy" | "metadata_validation_profile" | "metadata_required_fields" | "lifecycle_stale_blocker_reason_patterns" | "lifecycle_closure_like_blocked_reason_patterns" | "lifecycle_closure_like_resolution_patterns" | "lifecycle_closure_like_actual_result_patterns" | "governance_preset" | "governance_ownership_enforcement" | "governance_create_mode_default" | "governance_close_validation_default" | "governance_require_close_reason" | "governance_create_default_type" | "governance_workflow_enforcement" | "governance_parent_reference_policy" | "governance_metadata_validation_profile" | "governance_force_required_for_stale_lock" | "test_result_tracking" | "untrusted_linked_test_execution" | "telemetry_tracking" | "agent_identity_vocabulary" | "context";
+export type ConfigKey = "definition_of_done" | "item_format" | "history_missing_stream_policy" | "sprint_release_format_policy" | "parent_reference_policy" | "metadata_validation_profile" | "metadata_required_fields" | "lifecycle_stale_blocker_reason_patterns" | "lifecycle_closure_like_blocked_reason_patterns" | "lifecycle_closure_like_resolution_patterns" | "lifecycle_closure_like_actual_result_patterns" | "governance_preset" | "governance_ownership_enforcement" | "governance_create_mode_default" | "governance_close_validation_default" | "governance_require_close_reason" | "governance_create_default_type" | "governance_workflow_enforcement" | "governance_start_blocker_enforcement" | "governance_parent_reference_policy" | "governance_metadata_validation_profile" | "governance_force_required_for_stale_lock" | "test_result_tracking" | "untrusted_linked_test_execution" | "telemetry_tracking" | "agent_identity_vocabulary" | "context";
 /**
  * Resolve which typed flag a positional `pm config set <key> <value>` value should
  * populate, plus the normalized value.
@@ -49,3 +49,9 @@ export type ConfigKey = "definition_of_done" | "item_format" | "history_missing_
  * can fall back to the existing invalid-key path.
  */
 export declare function resolveConfigPositionalValue(canonicalKeyOrAlias:string,value:string):ConfigPositionalResult;
+/**
+ * The scope a config call without an explicit scope targets. Telemetry consent is
+ * read only from the global profile, so `telemetry-tracking` defaults there and the
+ * documented `pm config set telemetry-tracking off` opts out (GH-1660).
+ */
+export declare function defaultConfigScope(key:string | undefined):"project" | "global";

package/dist/core/config/positional-value.js

@@ -1,2 +1,2 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="78e92b9c-f3da-594e-8158-00409222308f")}catch{}})();const FORMAT_KEYS=new Set(["item_format"]),CRITERIA_KEYS=new Set(["definition_of_done","metadata_required_fields","lifecycle_stale_blocker_reason_patterns","lifecycle_closure_like_blocked_reason_patterns","lifecycle_closure_like_resolution_patterns","lifecycle_closure_like_actual_result_patterns"]),POLICY_KEYS=new Set(["history_missing_stream_policy","sprint_release_format_policy","parent_reference_policy","metadata_validation_profile","governance_preset","governance_ownership_enforcement","governance_create_mode_default","governance_close_validation_default","governance_require_close_reason","governance_create_default_type","governance_workflow_enforcement","governance_parent_reference_policy","governance_metadata_validation_profile","governance_force_required_for_stale_lock","test_result_tracking","untrusted_linked_test_execution","telemetry_tracking","agent_identity_vocabulary"]),ENABLED_DISABLED_POLICY_KEYS=new Set(["governance_require_close_reason","governance_force_required_for_stale_lock","test_result_tracking","untrusted_linked_test_execution","telemetry_tracking"]),ENABLED_DISABLED_SYNONYMS={off:"disabled",on:"enabled",true:"enabled",false:"disabled",enabled:"enabled",disabled:"disabled"};function toCanonicalKey(keyOrAlias){const normalized=keyOrAlias.trim().toLowerCase().replaceAll("-","_");if(FORMAT_KEYS.has(normalized)||CRITERIA_KEYS.has(normalized)||POLICY_KEYS.has(normalized)||normalized==="context")return normalized}function normalizeEnabledDisabled(value){const normalized=value.trim().toLowerCase();return ENABLED_DISABLED_SYNONYMS[normalized]??value}function resolveConfigPositionalValue(canonicalKeyOrAlias,value){const key=toCanonicalKey(canonicalKeyOrAlias);return key===void 0?{routable:!1,reason:`Unknown config key "${canonicalKeyOrAlias}" cannot route a positional value.`}:key==="context"?{routable:!1,reason:"Config set context does not accept a positional value. Use --default-depth, --activity-limit, --stale-threshold-days, or --section-<name> flags."}:FORMAT_KEYS.has(key)?{routable:!0,flag:"format",value}:CRITERIA_KEYS.has(key)?{routable:!0,flag:"criterion",values:[value]}:{routable:!0,flag:"policy",value:ENABLED_DISABLED_POLICY_KEYS.has(key)?normalizeEnabledDisabled(value):value}}export{resolveConfigPositionalValue};
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="7a401405-3370-53a5-811d-5e52287f1d2a")}catch{}})();const FORMAT_KEYS=new Set(["item_format"]),CRITERIA_KEYS=new Set(["definition_of_done","metadata_required_fields","lifecycle_stale_blocker_reason_patterns","lifecycle_closure_like_blocked_reason_patterns","lifecycle_closure_like_resolution_patterns","lifecycle_closure_like_actual_result_patterns"]),POLICY_KEYS=new Set(["history_missing_stream_policy","sprint_release_format_policy","parent_reference_policy","metadata_validation_profile","governance_preset","governance_ownership_enforcement","governance_create_mode_default","governance_close_validation_default","governance_require_close_reason","governance_create_default_type","governance_workflow_enforcement","governance_start_blocker_enforcement","governance_parent_reference_policy","governance_metadata_validation_profile","governance_force_required_for_stale_lock","test_result_tracking","untrusted_linked_test_execution","telemetry_tracking","agent_identity_vocabulary"]),ENABLED_DISABLED_POLICY_KEYS=new Set(["governance_require_close_reason","governance_force_required_for_stale_lock","test_result_tracking","untrusted_linked_test_execution","telemetry_tracking"]),ENABLED_DISABLED_SYNONYMS={off:"disabled",on:"enabled",true:"enabled",false:"disabled",enabled:"enabled",disabled:"disabled"};function toCanonicalKey(keyOrAlias){const normalized=keyOrAlias.trim().toLowerCase().replaceAll("-","_");if(FORMAT_KEYS.has(normalized)||CRITERIA_KEYS.has(normalized)||POLICY_KEYS.has(normalized)||normalized==="context")return normalized}function normalizeEnabledDisabled(value){const normalized=value.trim().toLowerCase();return ENABLED_DISABLED_SYNONYMS[normalized]??value}function resolveConfigPositionalValue(canonicalKeyOrAlias,value){const key=toCanonicalKey(canonicalKeyOrAlias);return key===void 0?{routable:!1,reason:`Unknown config key "${canonicalKeyOrAlias}" cannot route a positional value.`}:key==="context"?{routable:!1,reason:"Config set context does not accept a positional value. Use --default-depth, --activity-limit, --stale-threshold-days, or --section-<name> flags."}:FORMAT_KEYS.has(key)?{routable:!0,flag:"format",value}:CRITERIA_KEYS.has(key)?{routable:!0,flag:"criterion",values:[value]}:{routable:!0,flag:"policy",value:ENABLED_DISABLED_POLICY_KEYS.has(key)?normalizeEnabledDisabled(value):value}}function defaultConfigScope(key){return/^telemetry[-_]tracking$/u.test(key??"")?"global":"project"}export{defaultConfigScope,resolveConfigPositionalValue};
 //# sourceMappingURL=positional-value.js.map

package/dist/core/extensions/reserved-host-flags.js

@@ -1,2 +1,2 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="c24357cc-5dad-5cd7-aa89-cddd2945aab7")}catch{}})();const RESERVED_EXTENSION_HOST_FLAGS=Object.freeze([{flag:"--json"},{flag:"--lean"},{flag:"--token-accounting"},{flag:"--output-include",value_name:"fields"},{flag:"--output-limit",value_name:"count"},{flag:"--output-budget",value_name:"tokens"},{flag:"--output-format",value_name:"toon|json"},{flag:"--output-session",value_name:"state"},{flag:"--output-cursor",value_name:"cursor"},{flag:"--output-row-contract"},{flag:"--quiet"},{flag:"--no-changed-fields"},{flag:"--full-changed-fields"},{flag:"--id-only"},{flag:"--pm-path",aliases:["--path"]},{flag:"--no-extensions"},{flag:"--no-pager"},{flag:"--profile"},{flag:"--help"},{flag:"--author",value_name:"id"}]),RESERVED_EXTENSION_HOST_FLAG_NAMES=new Set(RESERVED_EXTENSION_HOST_FLAGS.flatMap(definition=>[definition.flag,...definition.aliases??[]]));export{RESERVED_EXTENSION_HOST_FLAGS,RESERVED_EXTENSION_HOST_FLAG_NAMES};
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="32b0a81e-6a21-528a-8cf8-3e764f382044")}catch{}})();const RESERVED_EXTENSION_HOST_FLAGS=Object.freeze([{flag:"--json"},{flag:"--lean"},{flag:"--token-accounting"},{flag:"--output-include",value_name:"fields"},{flag:"--output-limit",value_name:"count"},{flag:"--output-budget",value_name:"tokens"},{flag:"--output-format",value_name:"toon|json"},{flag:"--output-session",value_name:"state"},{flag:"--output-cursor",value_name:"cursor"},{flag:"--output-row-contract"},{flag:"--quiet"},{flag:"--no-changed-fields"},{flag:"--full-changed-fields"},{flag:"--id-only"},{flag:"--pm-path",aliases:["--path"]},{flag:"--no-extensions"},{flag:"--no-pager"},{flag:"--profile"},{flag:"--help"},{flag:"--author",value_name:"id"},{flag:"--expect-hash",value_name:"revision"}]),RESERVED_EXTENSION_HOST_FLAG_NAMES=new Set(RESERVED_EXTENSION_HOST_FLAGS.flatMap(definition=>[definition.flag,...definition.aliases??[]]));export{RESERVED_EXTENSION_HOST_FLAGS,RESERVED_EXTENSION_HOST_FLAG_NAMES};
 //# sourceMappingURL=reserved-host-flags.js.map

package/dist/core/history/history-rewrite.js

@@ -1,2 +1,2 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="eeaf2318-5964-5d98-ad90-9faa7fc69975")}catch{}})();import fs from"node:fs/promises";import{readFileIfExists,writeFileAtomic}from"../fs/fs-utils.js";import{acquireLock}from"../lock/lock.js";import{EXIT_CODE}from"../shared/constants.js";import{PmCliError}from"../shared/errors.js";import{locateItem,readLocatedItem}from"../store/item-store.js";import{resolveGovernanceKnobs}from"../store/settings.js";import{invalidateHistoryDriftCacheForPath}from"./drift-cache.js";function checkHistoryRewriteOwnership(params){if(!params.itemDocument)return[];const assigned=params.itemDocument.metadata?.assignee?.trim();if(!assigned||assigned===params.author||params.force)return[];const governance=resolveGovernanceKnobs(params.settings);if(governance.ownership_enforcement==="strict")throw new PmCliError(`Item ${params.subjectId} is assigned to ${assigned}. Use --force to override.`,EXIT_CODE.CONFLICT);return governance.ownership_enforcement==="warn"?[`ownership_warning:assignee_conflict:${params.subjectId}:${assigned}`]:[]}async function verifyHistoryRewriteNoDrift(params){const historyRawUnderLock=await readFileIfExists(params.subject.historyPath);if(historyRawUnderLock!==params.historyRawBeforeLock)throw new PmCliError(`History for ${params.subject.id} changed while waiting for lock; retry ${params.operation}.`,EXIT_CODE.CONFLICT);const locatedUnderLock=await locateItem(params.pmRoot,params.subject.id,params.settings.id_prefix,params.settings.item_format,params.typeRegistry.type_to_folder),loadedItemUnderLock=locatedUnderLock?params.readItem?await params.readItem(locatedUnderLock):await readLocatedItem(locatedUnderLock,{schema:params.settings.schema}):null;if((loadedItemUnderLock?.raw??null)!==(params.currentItemRawBeforeLock??null))throw new PmCliError(`Item ${params.subject.id} changed while waiting for lock; retry ${params.operation}.`,EXIT_CODE.CONFLICT);return{historyRawUnderLock,locatedUnderLock,loadedItemUnderLock}}async function writeHistoryRawWithRollback(params){const writeHistoryRaw=params.writeHistoryRaw??writeFileAtomic;try{await writeHistoryRaw(params.historyPath,params.nextHistoryRaw),await invalidateHistoryDriftCacheForPath(params.historyPath)}catch(error){try{params.historyRawUnderLock===null?await fs.rm(params.historyPath,{force:!0}):await writeHistoryRaw(params.historyPath,params.historyRawUnderLock),await invalidateHistoryDriftCacheForPath(params.historyPath)}catch(rollbackError){throw new AggregateError([error,rollbackError],`History rewrite failed and rollback also failed: ${String(error)}`)}throw error}}async function executeHistoryRewrite(params){const warnings=[...checkHistoryRewriteOwnership({itemDocument:params.itemDocument,subjectId:params.subject.id,author:params.author,force:params.force,settings:params.settings})],releaseLock=await acquireLock(params.pmRoot,params.subject.id,params.settings.locks.ttl_seconds,params.author,!!params.force,params.settings.governance.force_required_for_stale_lock,params.settings.locks.wait_ms);try{const verified=await verifyHistoryRewriteNoDrift({pmRoot:params.pmRoot,subject:params.subject,settings:params.settings,typeRegistry:params.typeRegistry,historyRawBeforeLock:params.historyRawBeforeLock,currentItemRawBeforeLock:params.currentItemRawBeforeLock,operation:params.operation});return await params.applyRewrite(verified),params.applyPostRewrite&&warnings.push(...await params.applyPostRewrite(verified)),warnings}finally{await releaseLock()}}export{checkHistoryRewriteOwnership,executeHistoryRewrite,verifyHistoryRewriteNoDrift,writeHistoryRawWithRollback};
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="5f3ae68b-2ae8-505c-bfc8-10e605c39a9e")}catch{}})();import fs from"node:fs/promises";import{readFileIfExists,writeFileAtomic}from"../fs/fs-utils.js";import{acquireLock}from"../lock/lock.js";import{EMPTY_CANONICAL_DOCUMENT,EXIT_CODE}from"../shared/constants.js";import{PmCliError}from"../shared/errors.js";import{locateItem,readLocatedItem}from"../store/item-store.js";import{advanceItemMutationPreconditions,assertItemMutationPreconditions,hasActiveItemRevisionScope}from"../store/item-mutation-precondition.js";import{resolveGovernanceKnobs}from"../store/settings.js";import{invalidateHistoryDriftCacheForPath}from"./drift-cache.js";function checkHistoryRewriteOwnership(params){if(!params.itemDocument)return[];const assigned=params.itemDocument.metadata?.assignee?.trim();if(!assigned||assigned===params.author||params.force)return[];const governance=resolveGovernanceKnobs(params.settings);if(governance.ownership_enforcement==="strict")throw new PmCliError(`Item ${params.subjectId} is assigned to ${assigned}. Use --force to override.`,EXIT_CODE.CONFLICT);return governance.ownership_enforcement==="warn"?[`ownership_warning:assignee_conflict:${params.subjectId}:${assigned}`]:[]}async function assertDeclaredRevisionOnDrift(params){if(!hasActiveItemRevisionScope(params.pmRoot))return;const located=await locateItem(params.pmRoot,params.subject.id,params.settings.id_prefix,params.settings.item_format,params.typeRegistry.type_to_folder),document=located===null?EMPTY_CANONICAL_DOCUMENT:(await readLocatedItem(located,{schema:params.settings.schema}).catch(()=>null))?.document;document!==void 0&&assertItemMutationPreconditions(params.pmRoot,document,params.subject.id)}async function verifyHistoryRewriteNoDrift(params){const historyRawUnderLock=await readFileIfExists(params.subject.historyPath);if(historyRawUnderLock!==params.historyRawBeforeLock)throw await assertDeclaredRevisionOnDrift(params),new PmCliError(`History for ${params.subject.id} changed while waiting for lock; retry ${params.operation}.`,EXIT_CODE.CONFLICT);const locatedUnderLock=await locateItem(params.pmRoot,params.subject.id,params.settings.id_prefix,params.settings.item_format,params.typeRegistry.type_to_folder),loadedItemUnderLock=locatedUnderLock?params.readItem?await params.readItem(locatedUnderLock):await readLocatedItem(locatedUnderLock,{schema:params.settings.schema}):null;if((loadedItemUnderLock?.raw??null)!==(params.currentItemRawBeforeLock??null))throw await assertDeclaredRevisionOnDrift(params),new PmCliError(`Item ${params.subject.id} changed while waiting for lock; retry ${params.operation}.`,EXIT_CODE.CONFLICT);return{historyRawUnderLock,locatedUnderLock,loadedItemUnderLock}}async function writeHistoryRawWithRollback(params){const writeHistoryRaw=params.writeHistoryRaw??writeFileAtomic;try{await writeHistoryRaw(params.historyPath,params.nextHistoryRaw),await invalidateHistoryDriftCacheForPath(params.historyPath)}catch(error){try{params.historyRawUnderLock===null?await fs.rm(params.historyPath,{force:!0}):await writeHistoryRaw(params.historyPath,params.historyRawUnderLock),await invalidateHistoryDriftCacheForPath(params.historyPath)}catch(rollbackError){throw new AggregateError([error,rollbackError],`History rewrite failed and rollback also failed: ${String(error)}`)}throw error}}async function executeHistoryRewrite(params){const warnings=[...checkHistoryRewriteOwnership({itemDocument:params.itemDocument,subjectId:params.subject.id,author:params.author,force:params.force,settings:params.settings})],releaseLock=await acquireLock(params.pmRoot,params.subject.id,params.settings.locks.ttl_seconds,params.author,!!params.force,params.settings.governance.force_required_for_stale_lock,params.settings.locks.wait_ms);try{const verified=await verifyHistoryRewriteNoDrift({pmRoot:params.pmRoot,subject:params.subject,settings:params.settings,typeRegistry:params.typeRegistry,historyRawBeforeLock:params.historyRawBeforeLock,currentItemRawBeforeLock:params.currentItemRawBeforeLock,operation:params.operation}),tombstone=EMPTY_CANONICAL_DOCUMENT;if(assertItemMutationPreconditions(params.pmRoot,verified.loadedItemUnderLock?.document??tombstone,params.subject.id),await params.applyRewrite(verified),hasActiveItemRevisionScope(params.pmRoot)){const relocated=await locateItem(params.pmRoot,params.subject.id,params.settings.id_prefix,params.settings.item_format,params.typeRegistry.type_to_folder),rewritten=relocated===null?tombstone:(await readLocatedItem(relocated,{schema:params.settings.schema})).document;advanceItemMutationPreconditions(params.pmRoot,rewritten,params.subject.id)}return params.applyPostRewrite&&warnings.push(...await params.applyPostRewrite(verified)),warnings}finally{await releaseLock()}}export{checkHistoryRewriteOwnership,executeHistoryRewrite,verifyHistoryRewriteNoDrift,writeHistoryRawWithRollback};
 //# sourceMappingURL=history-rewrite.js.map

package/dist/core/item/literal-mutation-input.d.ts

@@ -10,3 +10,20 @@ export declare function isLiteralMutationInput(input:object,field?:PropertyKey):
 export declare function preserveLiteralMutationInputFields<T extends object>(input:T,fields:Iterable<PropertyKey>):T;
 /** Preserve literal-data provenance when an internal adapter clones an option bag. */
 export declare function transferLiteralMutationInput<T extends object>(source:object,target:T):T;
+/** Vocabulary a mutation refusal uses: CLI flags, or the option keys a typed SDK or MCP caller passed (GH-1655). */
+export type MutationInputAudience = "cli" | "sdk";
+/**
+ * Who supplied a resolved option bag. Typed SDK and MCP input is marked literal
+ * before resolution and keeps that mark; a CLI adapter's bag never carries it.
+ */
+export declare function mutationInputAudience(input:object):MutationInputAudience;
+/** Name an option for its caller: `--blocked-by` on the CLI, `blockedBy` for SDK and MCP callers. */
+export declare function mutationOptionLabel(audience:MutationInputAudience,flag:string):string;
+/**
+ * The remedy that clears one scalar field for typed SDK and MCP callers, named
+ * by its `unset` token: the one clear form both transports accept (MCP has no
+ * typed null). The CLI keeps its own wording at each call site.
+ */
+export declare function sdkClearRemedy(unsetToken:string):string;
+/** Refusal text for an empty scalar option: the CLI wording unchanged, or the SDK option key and its clear remedy. */
+export declare function emptyMutationOptionMessage(audience:MutationInputAudience,flag:string,cliRemedy?:string):string;

package/dist/core/item/literal-mutation-input.js

@@ -1,2 +1,2 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="cef883fa-81be-5092-a07b-7a5ca961fbc7")}catch{}})();const literalInputs=new WeakSet,literalFields=new WeakMap,cliInputs=new WeakSet;function markCliMutationInput(input){return cliInputs.add(input),input}function isCliMutationInput(input){return cliInputs.has(input)}function preserveLiteralMutationInput(input){literalInputs.add(input);for(const[key,value]of Object.entries(input)){if(!Array.isArray(value))continue;const owned=[...value];Reflect.set(input,key,owned),literalInputs.add(owned)}return input}function isLiteralMutationInput(input,field){return literalInputs.has(input)||field!==void 0&&literalFields.get(input)?.has(field)===!0}function preserveLiteralMutationInputFields(input,fields){const selected=new Set(fields);literalFields.set(input,selected);for(const field of selected){const value=Reflect.get(input,field);if(!Array.isArray(value))continue;const owned=[...value];Reflect.set(input,field,owned),literalInputs.add(owned)}return input}function transferLiteralMutationInput(source,target){if(isCliMutationInput(source)&&markCliMutationInput(target),isLiteralMutationInput(source))return preserveLiteralMutationInput(target);const fields=literalFields.get(source);return fields?preserveLiteralMutationInputFields(target,fields):target}export{isCliMutationInput,isLiteralMutationInput,markCliMutationInput,preserveLiteralMutationInput,preserveLiteralMutationInputFields,transferLiteralMutationInput};
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="8dd367eb-617e-5645-8f8a-57862f8385f7")}catch{}})();const literalInputs=new WeakSet,literalFields=new WeakMap,cliInputs=new WeakSet;function markCliMutationInput(input){return cliInputs.add(input),input}function isCliMutationInput(input){return cliInputs.has(input)}function preserveLiteralMutationInput(input){literalInputs.add(input);for(const[key,value]of Object.entries(input)){if(!Array.isArray(value))continue;const owned=[...value];Reflect.set(input,key,owned),literalInputs.add(owned)}return input}function isLiteralMutationInput(input,field){return literalInputs.has(input)||field!==void 0&&literalFields.get(input)?.has(field)===!0}function preserveLiteralMutationInputFields(input,fields){const selected=new Set(fields);literalFields.set(input,selected);for(const field of selected){const value=Reflect.get(input,field);if(!Array.isArray(value))continue;const owned=[...value];Reflect.set(input,field,owned),literalInputs.add(owned)}return input}function transferLiteralMutationInput(source,target){if(isCliMutationInput(source)&&markCliMutationInput(target),isLiteralMutationInput(source))return preserveLiteralMutationInput(target);const fields=literalFields.get(source);return fields?preserveLiteralMutationInputFields(target,fields):target}function mutationInputAudience(input){return isLiteralMutationInput(input)?"sdk":"cli"}function mutationOptionLabel(audience,flag){return audience==="cli"?`--${flag}`:flag.replace(/-([a-z])/gu,(_match,letter)=>letter.toUpperCase())}function sdkClearRemedy(unsetToken){return`Pass unset: ["${unsetToken}"] to clear it`}function emptyMutationOptionMessage(audience,flag,cliRemedy=""){return audience==="cli"?`--${flag} must not be empty${cliRemedy}`:`${mutationOptionLabel("sdk",flag)} must not be empty. ${sdkClearRemedy(flag)}, or omit ${mutationOptionLabel("sdk",flag)}.`}export{emptyMutationOptionMessage,isCliMutationInput,isLiteralMutationInput,markCliMutationInput,mutationInputAudience,mutationOptionLabel,preserveLiteralMutationInput,preserveLiteralMutationInputFields,sdkClearRemedy,transferLiteralMutationInput};
 //# sourceMappingURL=literal-mutation-input.js.map

package/dist/core/item/parent-reference-policy.d.ts

@@ -4,15 +4,19 @@
  * Defines item parsing, formatting, and lifecycle helpers for Parent Reference Policy.
  */
 import type { ParentReferencePolicy } from "../../types/index.js";
+import { type MutationInputAudience } from "./literal-mutation-input.js";
 /** Implements normalize parent reference policy for the public runtime surface of this module. */
 export declare function normalizeParentReferencePolicy(value:string | undefined):ParentReferencePolicy;
-/** Implements normalize parent reference value for the public runtime surface of this module. */
-export declare function normalizeParentReferenceValue(rawValue:unknown):string;
+/**
+ * Normalize a parent reference. `audience` selects the refusal vocabulary: CLI
+ * flags by default, or the SDK option and its `unset` remedy for typed callers.
+ */
+export declare function normalizeParentReferenceValue(rawValue:unknown,audience?:MutationInputAudience):string;
 /** Detects parent-style placeholder tokens that should never become stored ids. */
 export declare function isPlaceholderReferenceToken(value:string):boolean;
 /** Implements validate missing parent reference for the public runtime surface of this module. */
-export declare function validateMissingParentReference(parentId:string,policy:ParentReferencePolicy):{
+export declare function validateMissingParentReference(parentId:string,policy:ParentReferencePolicy,audience?:MutationInputAudience):{
 warnings:string[];
 };
 /** Rejects the one-node hierarchy cycle where an item points at itself. */
-export declare function assertParentReferenceIsNotSelf(itemId:string,parentId:string,prefix:string):void;
+export declare function assertParentReferenceIsNotSelf(itemId:string,parentId:string,prefix:string,audience?:MutationInputAudience):void;

package/dist/core/item/parent-reference-policy.js

@@ -1,2 +1,2 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="2fd342e6-06cc-56d4-aa0e-2af269234b59")}catch{}})();import{normalizeItemId}from"./id.js";import{EXIT_CODE}from"../shared/constants.js";import{PmCliError}from"../shared/errors.js";const PLACEHOLDER_REFERENCE_TOKENS=new Set(["none","null","undefined"]);function normalizeParentReferencePolicy(value){const normalized=value?.trim().toLowerCase().replaceAll("-","_");if(normalized==="warn"||normalized==="strict_error")return normalized;if(normalized==="strict")return"strict_error";throw new PmCliError("Config set parent-reference-policy requires --policy with one of: warn, strict_error (alias: strict)",EXIT_CODE.USAGE)}function normalizeParentReferenceValue(rawValue){if(typeof rawValue!="string")throw new PmCliError("--parent must be a string. Use --unset parent to clear this field.",EXIT_CODE.USAGE);const value=rawValue.trim();if(value.length===0)throw new PmCliError("--parent must not be empty. Use --parent none to unset.",EXIT_CODE.USAGE);if(isPlaceholderReferenceToken(value))throw new PmCliError(`--parent must not use placeholder token "${value}". Use --unset parent to clear this field.`,EXIT_CODE.USAGE);return value}function isPlaceholderReferenceToken(value){return PLACEHOLDER_REFERENCE_TOKENS.has(value.trim().toLowerCase())}function validateMissingParentReference(parentId,policy){if(policy==="strict_error")throw new PmCliError(`Parent item "${parentId}" was not found. Create it first or use --parent none.`,EXIT_CODE.USAGE);return{warnings:[`validation_warning:parent_reference_missing:${parentId}`]}}function assertParentReferenceIsNotSelf(itemId,parentId,prefix){const normalizedItemId=normalizeItemId(itemId,prefix),normalizedParentId=normalizeItemId(parentId,prefix);if(normalizedItemId!==normalizedParentId)return;const normalizationDetail=parentId!==normalizedParentId||itemId!==normalizedItemId?` (normalized from parent "${parentId}" and item "${itemId}")`:"";throw new PmCliError(`Parent item "${normalizedParentId}" cannot be the same as item "${normalizedItemId}"${normalizationDetail}. Use --unset parent to clear this field.`,EXIT_CODE.USAGE)}export{assertParentReferenceIsNotSelf,isPlaceholderReferenceToken,normalizeParentReferencePolicy,normalizeParentReferenceValue,validateMissingParentReference};
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="0394e0c1-ff68-5553-b022-1e8b6fff04f0")}catch{}})();import{normalizeItemId}from"./id.js";import{EXIT_CODE}from"../shared/constants.js";import{PmCliError}from"../shared/errors.js";import{emptyMutationOptionMessage,sdkClearRemedy}from"./literal-mutation-input.js";const PLACEHOLDER_REFERENCE_TOKENS=new Set(["none","null","undefined"]);function normalizeParentReferencePolicy(value){const normalized=value?.trim().toLowerCase().replaceAll("-","_");if(normalized==="warn"||normalized==="strict_error")return normalized;if(normalized==="strict")return"strict_error";throw new PmCliError("Config set parent-reference-policy requires --policy with one of: warn, strict_error (alias: strict)",EXIT_CODE.USAGE)}function normalizeParentReferenceValue(rawValue,audience="cli"){const sdk=audience==="sdk";if(typeof rawValue!="string")throw new PmCliError(sdk?`parent must be a string. ${sdkClearRemedy("parent")}.`:"--parent must be a string. Use --unset parent to clear this field.",EXIT_CODE.USAGE);const value=rawValue.trim();if(value.length===0)throw new PmCliError(emptyMutationOptionMessage(audience,"parent",". Use --parent none to unset."),EXIT_CODE.USAGE);if(isPlaceholderReferenceToken(value))throw new PmCliError(sdk?`parent must not be the placeholder "${value}". ${sdkClearRemedy("parent")}, or omit parent.`:`--parent must not use placeholder token "${value}". Use --unset parent to clear this field.`,EXIT_CODE.USAGE);return value}function isPlaceholderReferenceToken(value){return PLACEHOLDER_REFERENCE_TOKENS.has(value.trim().toLowerCase())}function validateMissingParentReference(parentId,policy,audience="cli"){if(policy==="strict_error")throw new PmCliError(`Parent item "${parentId}" was not found. Create it first or ${audience==="sdk"?"omit parent":"use --parent none"}.`,EXIT_CODE.USAGE);return{warnings:[`validation_warning:parent_reference_missing:${parentId}`]}}function assertParentReferenceIsNotSelf(itemId,parentId,prefix,audience="cli"){const normalizedItemId=normalizeItemId(itemId,prefix),normalizedParentId=normalizeItemId(parentId,prefix);if(normalizedItemId!==normalizedParentId)return;const normalizationDetail=parentId!==normalizedParentId||itemId!==normalizedItemId?` (normalized from parent "${parentId}" and item "${itemId}")`:"";throw new PmCliError(`Parent item "${normalizedParentId}" cannot be the same as item "${normalizedItemId}"${normalizationDetail}. ${audience==="sdk"?`${sdkClearRemedy("parent")}.`:"Use --unset parent to clear this field."}`,EXIT_CODE.USAGE)}export{assertParentReferenceIsNotSelf,isPlaceholderReferenceToken,normalizeParentReferencePolicy,normalizeParentReferenceValue,validateMissingParentReference};
 //# sourceMappingURL=parent-reference-policy.js.map

package/dist/core/item/sprint-release-format.d.ts

@@ -4,10 +4,11 @@
  * Defines item parsing, formatting, and lifecycle helpers for Sprint Release Format.
  */
 import type { SprintReleaseFormatPolicy } from "../../types/index.js";
+import { type MutationInputAudience } from "./literal-mutation-input.js";
 /** Implements normalize sprint release format policy for the public runtime surface of this module. */
 export declare function normalizeSprintReleaseFormatPolicy(value:string | undefined):SprintReleaseFormatPolicy;
 /** Implements validate sprint or release value for the public runtime surface of this module. */
-export declare function validateSprintOrReleaseValue(field:"sprint" | "release",rawValue:string,policy:SprintReleaseFormatPolicy):{
+export declare function validateSprintOrReleaseValue(field:"sprint" | "release",rawValue:string,policy:SprintReleaseFormatPolicy,audience?:MutationInputAudience):{
 value:string;
 warnings:string[];
 };

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

@@ -1,2 +1,2 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="b6206b0e-0cd8-5827-acbd-6ac064dbcad7")}catch{}})();import{EXIT_CODE}from"../shared/constants.js";import{PmCliError}from"../shared/errors.js";const SPRINT_RELEASE_VALUE_PATTERN=/^[A-Za-z0-9][A-Za-z0-9._/-]*$/,SPRINT_RELEASE_MAX_LENGTH=64;function normalizeSprintReleaseFormatPolicy(value){const normalized=value?.trim().toLowerCase().replaceAll("-","_");if(normalized==="warn"||normalized==="strict_error")return normalized;if(normalized==="strict")return"strict_error";throw new PmCliError("Config set sprint-release-format-policy requires --policy with one of: warn, strict_error (alias: strict)",EXIT_CODE.USAGE)}function validateSprintOrReleaseValue(field,rawValue,policy){const value=rawValue.trim();if(value.length===0)throw new PmCliError(`--${field} must not be empty. Use --${field} none to unset.`,EXIT_CODE.USAGE);if(value.length<=SPRINT_RELEASE_MAX_LENGTH&&SPRINT_RELEASE_VALUE_PATTERN.test(value))return{value,warnings:[]};const guidance="Expected 1-64 characters matching [A-Za-z0-9][A-Za-z0-9._/-]* (no spaces).";if(policy==="strict_error")throw new PmCliError(`Invalid --${field} value "${value}". ${guidance}`,EXIT_CODE.USAGE);return{value,warnings:[`validation_warning:${field}_format:${value}`]}}export{normalizeSprintReleaseFormatPolicy,validateSprintOrReleaseValue};
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="6012e77b-7cdd-5496-a668-c9240a811b1a")}catch{}})();import{EXIT_CODE}from"../shared/constants.js";import{PmCliError}from"../shared/errors.js";import{emptyMutationOptionMessage}from"./literal-mutation-input.js";const SPRINT_RELEASE_VALUE_PATTERN=/^[A-Za-z0-9][A-Za-z0-9._/-]*$/,SPRINT_RELEASE_MAX_LENGTH=64;function normalizeSprintReleaseFormatPolicy(value){const normalized=value?.trim().toLowerCase().replaceAll("-","_");if(normalized==="warn"||normalized==="strict_error")return normalized;if(normalized==="strict")return"strict_error";throw new PmCliError("Config set sprint-release-format-policy requires --policy with one of: warn, strict_error (alias: strict)",EXIT_CODE.USAGE)}function validateSprintOrReleaseValue(field,rawValue,policy,audience="cli"){const value=rawValue.trim();if(value.length===0)throw new PmCliError(emptyMutationOptionMessage(audience,field,`. Use --${field} none to unset.`),EXIT_CODE.USAGE);if(value.length<=SPRINT_RELEASE_MAX_LENGTH&&SPRINT_RELEASE_VALUE_PATTERN.test(value))return{value,warnings:[]};const guidance="Expected 1-64 characters matching [A-Za-z0-9][A-Za-z0-9._/-]* (no spaces).";if(policy==="strict_error")throw new PmCliError(`Invalid ${audience==="sdk"?field:`--${field}`} value "${value}". ${guidance}`,EXIT_CODE.USAGE);return{value,warnings:[`validation_warning:${field}_format:${value}`]}}export{normalizeSprintReleaseFormatPolicy,validateSprintOrReleaseValue};
 //# sourceMappingURL=sprint-release-format.js.map

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

@@ -1,2 +1,2 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="ea19c980-44aa-54eb-b853-d829335e520e")}catch{}})();import{unicodeSafePrefix}from"../shared/text-normalization.js";const CHANGED_FIELDS_KEY="changed_fields",CHANGED_FIELD_COUNT_KEY="changed_field_count",ROWS_KEY="rows",UPDATE_MANY_MUTATION_MODES=new Set(["apply","rollback"]),DELETE_OUTCOMES=new Set(["deleted","would_delete"]),COMPACT_RECURRENCE_TEXT_LIMIT=256,COMPOUND_MUTATION_STEPS={start_task:["claim","update"],pause_task:["update","release"],close_task:["close","release"]};function projectCompoundMutation(result,options){if(!isPlainObject(result)||typeof result.action!="string"||typeof result.id!="string"||result.id.length===0)return null;const steps=Object.hasOwn(COMPOUND_MUTATION_STEPS,result.action)?COMPOUND_MUTATION_STEPS[result.action]:void 0;if(!steps||!steps.every(step=>{const value=result[step];return isPlainObject(value)&&isPlainObject(value.item)&&value.item.id===result.id&&Array.isArray(value.changed_fields)&&value.changed_fields.every(field=>typeof field=="string")}))return null;const final=result[steps.at(-1)],identity=projectIdOnlyResult(final);return options.idOnly?identity:!options.compactEnvelope&&options.changedFields!=="compact"?null:{...result,...options.compactEnvelope?{...identity,changed_field_count:new Set(steps.flatMap(step=>result[step].changed_fields)).size}:{},...Object.fromEntries(steps.map(step=>[step,projectMutationResult(result[step],options)]))}}function truncateCompactRecurrenceText(value){return typeof value!="string"||value.length<=COMPACT_RECURRENCE_TEXT_LIMIT?value:`${unicodeSafePrefix(value,COMPACT_RECURRENCE_TEXT_LIMIT-1)}\u2026`}function projectCompactRecurrence(value){if(!isPlainObject(value))return null;const recurrence={...value};return recurrence.reason=truncateCompactRecurrenceText(recurrence.reason),isPlainObject(recurrence.previous_terminal)&&(recurrence.previous_terminal=Object.fromEntries(Object.entries(recurrence.previous_terminal).map(([key,entry])=>[key,truncateCompactRecurrenceText(entry)]))),recurrence}function isPlainObject(value){if(typeof value!="object"||value===null||Array.isArray(value))return!1;const proto=Object.getPrototypeOf(value);return proto===null||proto===Object.prototype}function compactOwnChangedFields(envelope){const changedFields=envelope[CHANGED_FIELDS_KEY];if(!Array.isArray(changedFields))return null;const projected=Object.getPrototypeOf(envelope)===null?Object.create(null):{};for(const[key,value]of Object.entries(envelope))key!==CHANGED_FIELDS_KEY&&(projected[key]=value);return projected[CHANGED_FIELD_COUNT_KEY]=changedFields.length,projected}function isMutationEnvelope(value){return"item"in value&&Array.isArray(value[CHANGED_FIELDS_KEY])}function isUpdateManyMutationEnvelope(value){return typeof value.mode=="string"&&UPDATE_MANY_MUTATION_MODES.has(value.mode)&&Array.isArray(value[ROWS_KEY])}function replaceRows(envelope,rows){const projected=Object.getPrototypeOf(envelope)===null?Object.create(null):{};return Object.assign(projected,envelope),projected[ROWS_KEY]=rows,projected}function projectIdOnlyResult(result){if(!isPlainObject(result))return null;const subject=isPlainObject(result.item)?result.item:isPlainObject(result.plan)?result.plan:null;if(subject===null)return null;const id=typeof subject.id=="string"?subject.id:void 0,status=typeof result.outcome=="string"&&DELETE_OUTCOMES.has(result.outcome)?result.outcome:typeof subject.status=="string"?subject.status:void 0;return id?status?{id,status,...typeof result.deleted=="boolean"?{deleted:result.deleted}:{}}:{id}:null}function projectCompactMutationEnvelope(result,includeItem){if(!isPlainObject(result))return null;if(isPlainObject(result.plan)&&isPlainObject(result.mutation_receipt)&&result.mutation_receipt.kind==="plan_mutation"&&result.mutation_receipt.id===result.plan.id&&result.mutation_receipt.action===result.action)return result.mutation_receipt;if(!includeItem||!isPlainObject(result.item)||typeof result.item.id!="string")return null;const changedFields=result[CHANGED_FIELDS_KEY];if(!Array.isArray(changedFields))return null;const compact={id:result.item.id,...typeof result.outcome=="string"&&DELETE_OUTCOMES.has(result.outcome)?{status:result.outcome}:typeof result.item.status=="string"?{status:result.item.status}:{},...typeof result.deleted=="boolean"?{deleted:result.deleted}:{},...typeof result.previous_status=="string"?{previous_status:result.previous_status}:{},changed_field_count:changedFields.length};return appendCompactMutationEvidence(result,result.item,compact),compact}function appendCompactMutationEvidence(result,item,compact){const closeReason=typeof result.close_reason=="string"?result.close_reason:typeof item.close_reason=="string"?item.close_reason:void 0;closeReason!==void 0&&(compact.close_reason=closeReason);const recurrence=projectCompactRecurrence(result.recurrence);recurrence!==null&&(compact.recurrence=recurrence),Array.isArray(result.warnings)&&result.warnings.length>0&&(compact.warnings=result.warnings);for(const key of["recovery","follow_up","handoff","completion","start"])isPlainObject(result[key])&&(compact[key]=result[key]);if(typeof result.claimed_by=="string"||typeof result.released_by=="string")for(const key of["claimed_by","released_by","previous_assignee","forced","skipped","available","attempts","suggestions"])Object.hasOwn(result,key)&&(compact[key]=result[key])}function compactUpdateManyRows(envelope){const rows=isUpdateManyMutationEnvelope(envelope)?envelope[ROWS_KEY]:void 0;if(!Array.isArray(rows))return{projected:envelope,changed:!1};let rowsChanged=!1;const nextRows=rows.map(row=>{if(!isPlainObject(row))return row;const compactedRow=compactOwnChangedFields(row);return compactedRow?(rowsChanged=!0,compactedRow):row});return rowsChanged?{projected:replaceRows(envelope,nextRows),changed:!0}:{projected:envelope,changed:!1}}function projectMutationResult(result,options={}){const compound=projectCompoundMutation(result,options);if(compound!==null)return compound;if(options.idOnly===!0){const idOnly=projectIdOnlyResult(result);if(idOnly!==null)return idOnly}if(options.compactEnvelope===!0||options.changedFields==="compact"){const compact=projectCompactMutationEnvelope(result,options.compactEnvelope===!0);if(compact!==null)return compact}if((options.changedFields??"full")==="full"||!isPlainObject(result))return result;let changed=!1,projected=result;const compactedTop=isMutationEnvelope(result)?compactOwnChangedFields(result):null;compactedTop!==null&&(projected=compactedTop,changed=!0);const rowProjection=compactUpdateManyRows(projected);return rowProjection.changed&&(projected=rowProjection.projected,changed=!0),changed?projected:result}export{projectMutationResult};
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="2335ae7f-c7aa-5bdd-ac2e-e6d7a74be2e1")}catch{}})();import{unicodeSafePrefix}from"../shared/text-normalization.js";const CHANGED_FIELDS_KEY="changed_fields",CHANGED_FIELD_COUNT_KEY="changed_field_count",ROWS_KEY="rows",UPDATE_MANY_MUTATION_MODES=new Set(["apply","rollback"]),DELETE_OUTCOMES=new Set(["deleted","would_delete"]),COMPACT_RECURRENCE_TEXT_LIMIT=256,COMPOUND_MUTATION_STEPS={start_task:["claim","update"],pause_task:["update","release"],close_task:["close","release"]};function projectCompoundMutation(result,options){if(!isPlainObject(result)||typeof result.action!="string"||typeof result.id!="string"||result.id.length===0)return null;const steps=Object.hasOwn(COMPOUND_MUTATION_STEPS,result.action)?COMPOUND_MUTATION_STEPS[result.action]:void 0;if(!steps||!steps.every(step=>{const value=result[step];return isPlainObject(value)&&isPlainObject(value.item)&&value.item.id===result.id&&Array.isArray(value.changed_fields)&&value.changed_fields.every(field=>typeof field=="string")}))return null;const final=result[steps.at(-1)],identity=projectIdOnlyResult(final);return options.idOnly?identity:!options.compactEnvelope&&options.changedFields!=="compact"?null:{...result,...options.compactEnvelope?{...identity,changed_field_count:new Set(steps.flatMap(step=>result[step].changed_fields)).size}:{},...Object.fromEntries(steps.map(step=>[step,projectMutationResult(result[step],options)]))}}function truncateCompactRecurrenceText(value){return typeof value!="string"||value.length<=COMPACT_RECURRENCE_TEXT_LIMIT?value:`${unicodeSafePrefix(value,COMPACT_RECURRENCE_TEXT_LIMIT-1)}\u2026`}function projectCompactRecurrence(value){if(!isPlainObject(value))return null;const recurrence={...value};return recurrence.reason=truncateCompactRecurrenceText(recurrence.reason),isPlainObject(recurrence.previous_terminal)&&(recurrence.previous_terminal=Object.fromEntries(Object.entries(recurrence.previous_terminal).map(([key,entry])=>[key,truncateCompactRecurrenceText(entry)]))),recurrence}function isPlainObject(value){if(typeof value!="object"||value===null||Array.isArray(value))return!1;const proto=Object.getPrototypeOf(value);return proto===null||proto===Object.prototype}function compactOwnChangedFields(envelope){const changedFields=envelope[CHANGED_FIELDS_KEY];if(!Array.isArray(changedFields))return null;const projected=Object.getPrototypeOf(envelope)===null?Object.create(null):{};for(const[key,value]of Object.entries(envelope))key!==CHANGED_FIELDS_KEY&&(projected[key]=value);return projected[CHANGED_FIELD_COUNT_KEY]=changedFields.length,projected}function isMutationEnvelope(value){return"item"in value&&Array.isArray(value[CHANGED_FIELDS_KEY])}function isUpdateManyMutationEnvelope(value){return typeof value.mode=="string"&&UPDATE_MANY_MUTATION_MODES.has(value.mode)&&Array.isArray(value[ROWS_KEY])}function replaceRows(envelope,rows){const projected=Object.getPrototypeOf(envelope)===null?Object.create(null):{};return Object.assign(projected,envelope),projected[ROWS_KEY]=rows,projected}function projectIdOnlyResult(result){if(!isPlainObject(result))return null;const subject=isPlainObject(result.item)?result.item:isPlainObject(result.plan)?result.plan:null;if(subject===null)return null;const id=typeof subject.id=="string"?subject.id:void 0,status=typeof result.outcome=="string"&&DELETE_OUTCOMES.has(result.outcome)?result.outcome:typeof subject.status=="string"?subject.status:void 0;return id?status?{id,status,...typeof result.deleted=="boolean"?{deleted:result.deleted}:{}}:{id}:null}function projectCompactMutationEnvelope(result,includeItem){if(!isPlainObject(result))return null;if(isPlainObject(result.plan)&&isPlainObject(result.mutation_receipt)&&result.mutation_receipt.kind==="plan_mutation"&&result.mutation_receipt.id===result.plan.id&&result.mutation_receipt.action===result.action)return result.mutation_receipt;if(!includeItem||!isPlainObject(result.item)||typeof result.item.id!="string")return null;const changedFields=result[CHANGED_FIELDS_KEY];if(!Array.isArray(changedFields))return null;const compact={id:result.item.id,...typeof result.outcome=="string"&&DELETE_OUTCOMES.has(result.outcome)?{status:result.outcome}:typeof result.item.status=="string"?{status:result.item.status}:{},...typeof result.deleted=="boolean"?{deleted:result.deleted}:{},...typeof result.previous_status=="string"?{previous_status:result.previous_status}:{},changed_field_count:changedFields.length};return appendCompactMutationEvidence(result,result.item,compact),compact}function appendCompactMutationEvidence(result,item,compact){const closeReason=typeof result.close_reason=="string"?result.close_reason:typeof item.close_reason=="string"?item.close_reason:void 0;closeReason!==void 0&&(compact.close_reason=closeReason);const recurrence=projectCompactRecurrence(result.recurrence);recurrence!==null&&(compact.recurrence=recurrence),Array.isArray(result.warnings)&&result.warnings.length>0&&(compact.warnings=result.warnings);for(const key of["recovery","follow_up","handoff","completion","start"])isPlainObject(result[key])&&(compact[key]=result[key]);if(typeof result.claimed_by=="string"||typeof result.released_by=="string")for(const key of["claimed_by","released_by","previous_assignee","forced","skipped","available","attempts","start_refused","suggestions"])Object.hasOwn(result,key)&&(compact[key]=result[key])}function compactUpdateManyRows(envelope){const rows=isUpdateManyMutationEnvelope(envelope)?envelope[ROWS_KEY]:void 0;if(!Array.isArray(rows))return{projected:envelope,changed:!1};let rowsChanged=!1;const nextRows=rows.map(row=>{if(!isPlainObject(row))return row;const compactedRow=compactOwnChangedFields(row);return compactedRow?(rowsChanged=!0,compactedRow):row});return rowsChanged?{projected:replaceRows(envelope,nextRows),changed:!0}:{projected:envelope,changed:!1}}function projectMutationResult(result,options={}){const compound=projectCompoundMutation(result,options);if(compound!==null)return compound;if(options.idOnly===!0){const idOnly=projectIdOnlyResult(result);if(idOnly!==null)return idOnly}if(options.compactEnvelope===!0||options.changedFields==="compact"){const compact=projectCompactMutationEnvelope(result,options.compactEnvelope===!0);if(compact!==null)return compact}if((options.changedFields??"full")==="full"||!isPlainObject(result))return result;let changed=!1,projected=result;const compactedTop=isMutationEnvelope(result)?compactOwnChangedFields(result):null;compactedTop!==null&&(projected=compactedTop,changed=!0);const rowProjection=compactUpdateManyRows(projected);return rowProjection.changed&&(projected=rowProjection.projected,changed=!0),changed?projected:result}export{projectMutationResult};
 //# sourceMappingURL=mutation-projection.js.map

package/dist/core/shared/command-types.d.ts

@@ -43,6 +43,13 @@ noPager?:boolean;
 profile?:boolean;
 /** Invocation-wide mutation author override. */
 author?:string;
+/**
+     * CLI-parsed `--expect-hash` tokens (`<item_hash>` or `<id>=<item_hash>`).
+     * Only the CLI invocation scope enforces them; direct `run*` SDK calls do not
+     * read this field. SDK callers guard writes with `withExpectedItemRevisions`,
+     * `PmClient.withExpectedItemRevisions`, or `runAction`/MCP `expectHash`.
+     */
+expectHash?:string[];
 /** Fallback output format used when callers do not provide an override. */
 defaultOutputFormat?:"toon" | "json";
 }

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

@@ -10,10 +10,76 @@ historyContext?:Record<string,unknown>;
 }
 /** Scope a target-specific precondition to an awaited mutation without affecting concurrent callers. */
 export declare function runWithItemMutationPrecondition<T>(condition:ItemMutationPrecondition,operation:() => Promise<T>):Promise<T>;
-/** Evaluate matching preconditions only after the item lock has been acquired and its document read. */
-export declare function assertItemMutationPreconditions(pmRoot:string,document:ItemDocument):void;
-/** Notify matching scoped guards of their own committed document before releasing the item lock. */
-export declare function advanceItemMutationPreconditions(pmRoot:string,document:ItemDocument):void;
-/** Collect target-scoped immutable attribution without attributing another caller's writes. */
-export declare function itemMutationPreconditionHistoryContext(pmRoot:string,document:ItemDocument):Record<string,unknown>;
+/** One caller-declared revision of one item, as returned by `item_hash` reads. */
+interface ItemRevisionScopeEntry {
+/** Revision the caller decided on. */
+declared:string;
+/** Revision the next locked write must find; advances past this scope's own commits. */
+expected:string;
+/** Whether any locked write evaluated this expectation. */
+checked:boolean;
+/**
+     * Whether this scope durably committed a write to the item. Tracked apart from
+     * `expected`, which can return to `declared` (a restore then delete reproduces
+     * the declared tombstone).
+     */
+committed:boolean;
+}
+/**
+ * Mutable expected-revision scope for one invocation. Hosts open it before the
+ * command runs and bind it once the tracker root and canonical ids are known,
+ * so expectations reach every locked item write the invocation makes.
+ */
+export interface ItemRevisionScope {
+/** Resolved tracker root, unset until the host binds the scope. */
+pmRoot?:string;
+/** Canonical item id to declared revision state. */
+entries:Map<string,ItemRevisionScopeEntry>;
+}
+/** Create an empty, unbound expected-revision scope. */
+export declare function createItemRevisionScope():ItemRevisionScope;
+/** Run an operation with an expected-revision scope visible to every locked item write it makes. */
+export declare function runWithItemRevisionScope<T>(scope:ItemRevisionScope,operation:() => Promise<T>):Promise<T>;
+/**
+ * Bind canonical expectations to a scope. The same id may repeat only with the
+ * same revision, because two different revisions of one item cannot both hold.
+ */
+export declare function bindItemRevisionScope(scope:ItemRevisionScope,pmRoot:string,expectations:readonly {
+id:string;
+itemHash:string;
+}[]):void;
+/** Report which bound expectations a locked write evaluated, in binding order. */
+export declare function itemRevisionScopeReceipt(scope:ItemRevisionScope):{
+checked:string[];
+unchecked:string[];
+};
+/**
+ * Whether any active scope declared a revision on this tracker, so writers that
+ * must read a document to learn its embedded id can skip that read otherwise.
+ */
+export declare function hasActiveItemRevisionScope(pmRoot:string):boolean;
+/**
+ * Refuse a guarded write over a live item that cannot be read as a document
+ * (restore recovering corrupt bytes). No declared revision describes those bytes,
+ * so the guard refuses rather than judging the history reconstruction restore
+ * would write from. `current_revision` is the SHA-256 of the unreadable text.
+ */
+export declare function assertItemRevisionExpectationsOnUnreadable(pmRoot:string,targetId:string,raw:string):void;
+/**
+ * Evaluate matching preconditions only after the item lock has been acquired
+ * and its document read. `targetId` names the locked item explicitly, so a
+ * deleted item's empty tombstone document is still judged against its own
+ * expectations instead of matching nothing.
+ */
+export declare function assertItemMutationPreconditions(pmRoot:string,document:ItemDocument,targetId?:string):void;
+/**
+ * Notify matching scoped guards of their own committed document (a tombstone
+ * after delete) before releasing the item lock. `aliasIds` carries identities
+ * the committed document no longer has, such as a deleted item's embedded id.
+ * `revision` overrides the document's hash when the stored state is not that
+ * document (a storage override persisted something the store cannot parse).
+ */
+export declare function advanceItemMutationPreconditions(pmRoot:string,document:ItemDocument,targetId?:string,aliasIds?:readonly string[],revision?:string):void;
+/** Collect target-scoped immutable attribution (keyed by either identity of the locked item) without attributing another caller's writes. */
+export declare function itemMutationPreconditionHistoryContext(pmRoot:string,ids:readonly unknown[]):Record<string,unknown>;
 export {};

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

@@ -1,2 +1,2 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="39bf765c-1374-5ba5-b8a9-44137f80c976")}catch{}})();import{AsyncLocalStorage}from"node:async_hooks";import path from"node:path";const preconditions=new AsyncLocalStorage;function runWithItemMutationPrecondition(condition,operation){return preconditions.run([...preconditions.getStore()??[],{...condition,pmRoot:path.resolve(condition.pmRoot)}],operation)}function assertItemMutationPreconditions(pmRoot,document){for(const condition of preconditions.getStore()??[])condition.pmRoot===path.resolve(pmRoot)&&condition.id===document.metadata.id&&condition.validate(document)}function advanceItemMutationPreconditions(pmRoot,document){for(const condition of preconditions.getStore()??[])condition.pmRoot===path.resolve(pmRoot)&&condition.id===document.metadata.id&&condition.committed?.(document)}function itemMutationPreconditionHistoryContext(pmRoot,document){return Object.assign({},...(preconditions.getStore()??[]).filter(condition=>condition.pmRoot===path.resolve(pmRoot)&&condition.id===document.metadata.id).map(condition=>condition.historyContext))}export{advanceItemMutationPreconditions,assertItemMutationPreconditions,itemMutationPreconditionHistoryContext,runWithItemMutationPrecondition};
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="82ccccc7-c505-51c2-b207-93afa945f718")}catch{}})();import{AsyncLocalStorage}from"node:async_hooks";import{realpathSync}from"node:fs";import path from"node:path";import{hashDocument}from"../history/history.js";import{sha256Hex}from"../shared/serialization.js";import{EXIT_CODE}from"../shared/constants.js";import{PmCliError}from"../shared/errors.js";const preconditions=new AsyncLocalStorage;function runWithItemMutationPrecondition(condition,operation){return preconditions.run([...preconditions.getStore()??[],{...condition,pmRoot:path.resolve(condition.pmRoot)}],operation)}const REVISION_SCOPES_KEY=Symbol.for("@unbrained/pm-cli/item-revision-scopes"),revisionScopeRegistry=globalThis,revisionScopes=revisionScopeRegistry[REVISION_SCOPES_KEY]??=new AsyncLocalStorage;function canonicalTrackerRoot(pmRoot){const resolved=path.resolve(pmRoot);try{return realpathSync.native(resolved)}catch{return resolved}}function createItemRevisionScope(){return{entries:new Map}}function runWithItemRevisionScope(scope,operation){return revisionScopes.run([...revisionScopes.getStore()??[],scope],operation)}function bindItemRevisionScope(scope,pmRoot,expectations){const resolvedRoot=canonicalTrackerRoot(pmRoot);if(scope.pmRoot!==void 0&&scope.pmRoot!==resolvedRoot)throw new PmCliError("An expected-revision scope is already bound to another tracker.",EXIT_CODE.USAGE,{code:"expected_revision_scope_conflict",required:"Bind expected item revisions for one tracker per scope."});scope.pmRoot=resolvedRoot;for(const{id,itemHash}of expectations){const existing=scope.entries.get(id);if(existing!==void 0&&existing.declared!==itemHash)throw new PmCliError(`Item ${id} has two different expected revisions.`,EXIT_CODE.USAGE,{code:"expected_revision_duplicate",item_id:id,required:"Declare at most one expected revision per item."});scope.entries.set(id,existing??{declared:itemHash,expected:itemHash,checked:!1,committed:!1})}}function itemRevisionScopeReceipt(scope){const entries=[...scope.entries.entries()];return{checked:entries.filter(([,entry])=>entry.checked).map(([id])=>id),unchecked:entries.filter(([,entry])=>!entry.checked).map(([id])=>id)}}function matchingRevisionEntries(pmRoot,ids){const scopes=revisionScopes.getStore()??[];if(scopes.length===0)return[];const resolvedRoot=canonicalTrackerRoot(pmRoot),keys=new Set(ids.filter(id=>typeof id=="string"));return[...new Set(scopes.flatMap(scope=>scope.pmRoot===resolvedRoot?[...keys].flatMap(key=>scope.entries.get(key)??[]):[]))]}function hasActiveItemRevisionScope(pmRoot){const resolvedRoot=canonicalTrackerRoot(pmRoot);return(revisionScopes.getStore()??[]).some(scope=>scope.pmRoot===resolvedRoot&&scope.entries.size>0)}function assertItemRevisionExpectations(pmRoot,document,targetId){const entries=matchingRevisionEntries(pmRoot,[targetId,document.metadata.id]);entries.length>0&&assertRevisionEntries(entries,targetId,hashDocument(document),!1)}function assertItemRevisionExpectationsOnUnreadable(pmRoot,targetId,raw){const entries=matchingRevisionEntries(pmRoot,[targetId]);entries.length>0&&assertRevisionEntries(entries,targetId,sha256Hex(raw),!0)}function assertRevisionEntries(entries,targetId,current,unreadable){for(const entry of entries)if(entry.checked=!0,!(!unreadable&&entry.expected===current))throw new PmCliError(`Item ${targetId} is no longer at the expected revision ${entry.expected.slice(0,12)}${unreadable?" (its live document cannot be read)":""}; refusing to write over a revision this decision did not see.${entry.committed?" Earlier writes by this same invocation already committed.":" Nothing was written to this item."}`,EXIT_CODE.CONFLICT,{code:"item_revision_conflict",item_id:targetId,expected_revision:entry.expected,current_revision:current,required:unreadable?`Recover ${targetId} without --expect-hash (pm restore ${targetId} <version>), since no declared revision describes an unreadable document.`:`Re-read ${targetId} (pm get ${targetId} --json reports item_hash), decide again against the current revision, then retry with --expect-hash <item_hash>.`,why:"The caller declared the revision its decision was based on, and another write changed the item before this locked write.",examples:[`pm get ${targetId} --fields item_hash --json`,`pm history ${targetId} --limit 5`],nextSteps:[`pm get ${targetId} --json`,`pm history ${targetId} --limit 5`]})}function assertItemMutationPreconditions(pmRoot,document,targetId=document.metadata.id){assertItemRevisionExpectations(pmRoot,document,targetId);for(const condition of conditionsFor(pmRoot,[targetId,document.metadata.id]))condition.validate(document)}function conditionsFor(pmRoot,ids){const resolvedRoot=path.resolve(pmRoot);return(preconditions.getStore()??[]).filter(condition=>condition.pmRoot===resolvedRoot&&ids.includes(condition.id))}function advanceItemMutationPreconditions(pmRoot,document,targetId=document.metadata.id,aliasIds=[],revision){const entries=matchingRevisionEntries(pmRoot,[targetId,document.metadata.id,...aliasIds]);if(entries.length>0){const committed=revision??hashDocument(document);for(const entry of entries)entry.expected=committed,entry.committed=!0}for(const condition of conditionsFor(pmRoot,[targetId,document.metadata.id,...aliasIds]))condition.committed?.(document)}function itemMutationPreconditionHistoryContext(pmRoot,ids){return Object.assign({},...conditionsFor(pmRoot,ids).map(condition=>condition.historyContext))}export{advanceItemMutationPreconditions,assertItemMutationPreconditions,assertItemRevisionExpectationsOnUnreadable,bindItemRevisionScope,createItemRevisionScope,hasActiveItemRevisionScope,itemMutationPreconditionHistoryContext,itemRevisionScopeReceipt,runWithItemMutationPrecondition,runWithItemRevisionScope};
 //# sourceMappingURL=item-mutation-precondition.js.map

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

@@ -1,2 +1,2 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="8266acd6-5564-5d56-8025-82608136296d")}catch{}})();import fs from"node:fs/promises";import{buildDeletedItemError}from"../history/tombstone.js";import{normalizeHistoryOperationForWrite}from"../history/operation-contract.js";import{enforceWorkflowMutation}from"../policy/workflow-policy-store.js";import{recordItemMetadataEnumeration}from"./item-metadata-read-work.js";import{advanceItemMutationPreconditions,assertItemMutationPreconditions,itemMutationPreconditionHistoryContext}from"./item-mutation-precondition.js";import{checkpointMutationHistoryContext}from"../checkpoint/mutation-context.js";import path from"node:path";import{getActiveExtensionRegistrations,projectAfterCommandItemSnapshot,recordAfterCommandAffectedItem,runActiveOnReadHooks,runActiveBeforeMutationHooks,runActiveOnWriteHooks,runActiveServiceOverride}from"../extensions/index.js";import{collectRegisteredItemFieldNames}from"../extensions/item-fields.js";import{EMPTY_CANONICAL_DOCUMENT,EXIT_CODE,TYPE_TO_FOLDER}from"../shared/constants.js";import{PmCliError}from"../shared/errors.js";import{levenshteinDistanceWithinLimit}from"../shared/levenshtein.js";import{appendHistoryEntry,createHistoryEntry}from"../history/history.js";import{enforceHistoryStreamPolicyForItem}from"../history/history-stream-policy.js";import{canonicalDocument,parseItemDocument,serializeItemDocument}from"../item/item-format.js";import{resolveItemTypeRegistry}from"../item/type-registry.js";import{effectiveItemFormatVersion,requiredItemFormatVersion}from"../item/item-format-version.js";import{assertProjectRuntimeFormatGuard}from"../../sdk/environment/project-runtime-compatibility.js";import{acquireLockLease}from"../lock/lock.js";import{isFileMissingError,writeFileAtomic}from"../fs/fs-utils.js";import{isUtf8}from"node:buffer";import{normalizeItemId,normalizeRawItemId}from"../item/id.js";import{acquireItemMetadataDerivedIndexLock,listAllDocumentCandidatesCached,listAllDocumentsCached,listAllDocumentsCachedLight,refreshItemMetadataDerivedIndex}from"./item-metadata-cache.js";import{getHistoryPath,getItemPath,ITEM_FILE_EXTENSIONS,resolveWorkspaceRoot}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){try{return await fs.access(targetPath),!0}catch{return!1}}function isErrno(error,code){return typeof error=="object"&&error!==null&&"code"in error&&error.code===code}function appendWarning(warnings,warning){warnings&&(warnings.includes(warning)||warnings.push(warning))}function resolveActiveExtensionFieldNames(explicit){return explicit??collectRegisteredItemFieldNames(getActiveExtensionRegistrations())}function resolveItemFormatSearchOrder(preferredFormat){return preferredFormat==="toon"?["toon","json_markdown"]:preferredFormat==="json_markdown"?["json_markdown","toon"]:["toon","json_markdown"]}async function locateItem(pmRoot,rawId,idPrefix="pm-",preferredFormat,typeToFolder=TYPE_TO_FOLDER){const trimmedRawId=rawId.trim(),exactRawId=trimmedRawId.startsWith("#")?trimmedRawId.slice(1):trimmedRawId;if(exactRawId.length===0)return null;const normalizedId=normalizeItemId(rawId,idPrefix),rawNormalizedId=normalizeRawItemId(rawId),candidateIds=[...new Set([exactRawId,normalizedId,rawNormalizedId])].filter(candidateId=>candidateId.length>0),entries=Object.entries(typeToFolder),searchOrder=resolveItemFormatSearchOrder(preferredFormat);for(const candidateId of candidateIds){const matches=new Map;for(const[type]of entries)for(const itemFormat of searchOrder){const itemPath=getItemPath(pmRoot,type,candidateId,itemFormat,typeToFolder);await fileExists(itemPath)&&matches.set(itemPath,matches.get(itemPath)??{id:candidateId,type,itemPath,item_format:itemFormat})}if(matches.size>1){const paths=[...matches.keys()].map(itemPath=>path.relative(pmRoot,itemPath).split(path.sep).join("/")).sort();throw new PmCliError(`Item ${candidateId} has ambiguous identity across ${paths.join(", ")}. Preserve both documents and inspect pm ops validate --check-storage-integrity before resolving the collision.`,EXIT_CODE.CONFLICT,{code:"item_identity_ambiguous",item_id:candidateId,paths})}for(const match of matches.values())return match}return null}async function readLocatedItem(item,options={}){const snapshot=await readLocatedItemSnapshot(item,options);if(snapshot.error!==null)throw snapshot.error;return{raw:snapshot.raw,document:snapshot.document}}async function readLocatedItemSnapshot(item,options={}){const bytes=await fs.readFile(item.itemPath);if(!isUtf8(bytes))throw new PmCliError("Item contains invalid UTF-8; preserve a binary backup before recovering it.",EXIT_CODE.CONFLICT,{code:"item_document_encoding_invalid",item_id:item.id,item_path:item.itemPath,byte_length:bytes.length,empty:!1});const raw=bytes.toString("utf8");await runActiveOnReadHooks({path:item.itemPath,scope:"project"});let document;try{document=parseItemDocument(raw,{format:item.item_format,requireSupportedFormat:!0,schema:options.schema,extensionFieldNames:resolveActiveExtensionFieldNames(options.extensionFieldNames),onWarning:warning=>appendWarning(options.warnings,warning)})}catch(error){if(error instanceof PmCliError&&error.code==="item_format_version_unsupported")throw new PmCliError(`Item ${item.id}: ${error.message}`,error.exitCode,{...error.context,item_id:item.id,item_path:item.itemPath});if(error instanceof PmCliError&&error.code==="item_document_invalid")return{raw,document:null,error:new PmCliError(`Cannot read ${item.id} at ${item.itemPath}${bytes.length===0?" (zero-length file)":""}: ${error.message}`,error.exitCode,{...error.context,item_id:item.id,item_path:item.itemPath,byte_length:bytes.length,empty:bytes.length===0,nextSteps:[`Run pm history ${item.id} --full, then pm restore ${item.id} <version> to recover a recorded state.`]})};throw error}return{raw,document,error:null}}async function listAllItemMetadata(pmRoot,preferredFormat,typeToFolder=TYPE_TO_FOLDER,warnings,schema){await assertReadableTrackerRoot(pmRoot);const documents=await listAllDocumentsCached(pmRoot,preferredFormat,typeToFolder,warnings,schema);return recordItemMetadataEnumeration(documents.length),documents.map(document=>document.metadata)}async function listAllItemMetadataLight(pmRoot,preferredFormat,typeToFolder=TYPE_TO_FOLDER,warnings,schema){await assertReadableTrackerRoot(pmRoot);const documents=await listAllDocumentsCachedLight(pmRoot,preferredFormat,typeToFolder,warnings,schema);return recordItemMetadataEnumeration(documents.length),documents.map(document=>document.metadata)}async function listAllItemMetadataWithBody(pmRoot,preferredFormat,typeToFolder=TYPE_TO_FOLDER,warnings,schema,options={}){await assertReadableTrackerRoot(pmRoot);const candidates=await listAllDocumentCandidatesCached(pmRoot,preferredFormat,typeToFolder,warnings,schema,{includeBody:!0,forceSourceScan:options.forceSourceScan});return recordItemMetadataEnumeration(candidates.length),candidates.map(candidate=>({...candidate.metadata,body:candidate.body}))}function createMutationGuardSdk(params){return{async get(id){const located=await locateItem(params.pmRoot,id,params.settings.id_prefix,params.settings.item_format,params.typeToFolder);if(!located)return null;const{document}=await readLocatedItem(located,{schema:params.settings.schema});return{item:document.metadata,body:document.body}},list:()=>listAllItemMetadata(params.pmRoot,params.settings.item_format,params.typeToFolder,void 0,params.settings.schema)}}async function listKnownItemIds(pmRoot,typeToFolder){const folders=new Set(Object.values(typeToFolder)),allIds=[];return await Promise.all([...folders].map(async folder=>{try{const entries=await fs.readdir(path.join(pmRoot,folder));for(const entry of entries)for(const ext of ITEM_FILE_EXTENSIONS)if(entry.toLowerCase().endsWith(ext)){allIds.push(entry.slice(0,-ext.length));break}}catch{}})),allIds}async function buildDidYouMeanSuggestions(pmRoot,badId,idPrefix,typeToFolder){const normalized=normalizeItemId(badId,idPrefix),ids=await listKnownItemIds(pmRoot,typeToFolder);if(ids.length===0)return[];const limit=Math.max(3,Math.floor(normalized.length/2));return ids.map(id=>({id,distance:levenshteinDistanceWithinLimit(id,normalized,limit)})).filter(entry=>entry.distance!==null).sort((left,right)=>left.distance-right.distance).slice(0,3).map(entry=>entry.id)}async function buildItemNotFoundError(pmRoot,badId,idPrefix,typeToFolder){const deleted=await buildDeletedItemError(pmRoot,badId,idPrefix);if(deleted)return deleted;const suggestions=await buildDidYouMeanSuggestions(pmRoot,badId,idPrefix,typeToFolder),nextSteps=["Confirm the active --path/PM_PATH scope, then retry with a valid id."];return suggestions.length>0&&nextSteps.unshift(`Did you mean one of: ${suggestions.join(", ")}?`),new PmCliError(`Item ${badId} not found`,EXIT_CODE.NOT_FOUND,{code:"item_not_found",id:badId,nextSteps})}function bypassesAssigneeConflict(op,bypassAssigneeConflict){return op==="claim"||bypassAssigneeConflict===!0&&(op==="comment_add"||op==="comment_edit"||op==="comment_delete"||op==="note_add"||op==="learning_add"||op==="release"||op==="update"||op==="update_ownership_bypass"||op==="update_audit")}async function prepareLockedItem(params){const typeToFolder=params.typeToFolder??resolveItemTypeRegistry(params.settings,getActiveExtensionRegistrations()).type_to_folder,located=await locateItem(params.pmRoot,params.id,params.settings.id_prefix,params.settings.item_format,typeToFolder);if(!located)throw await buildItemNotFoundError(params.pmRoot,params.id,params.settings.id_prefix,typeToFolder);const lease=await acquireLockLease(params.pmRoot,located.id,params.settings.locks.ttl_seconds,params.author,!!params.force,params.settings.governance.force_required_for_stale_lock,params.settings.locks.wait_ms,{waitPolicy:"progress"}),releaseLock=lease.release;try{const warnings=[],{raw:originalRaw,document}=await readLocatedItem(located,{schema:params.settings.schema,extensionFieldNames:params.extensionFieldNames,warnings}),assigned=document.metadata.assignee?.trim(),assignedPrincipal=document.metadata.claim_principal?.trim()||assigned,callerPrincipal=resolveClaimPrincipal(params.author),governance=resolveGovernanceKnobs(params.settings);if(assigned&&assignedPrincipal!==callerPrincipal&&!params.force&&!bypassesAssigneeConflict(params.op,params.bypassAssigneeConflict)){if(governance.ownership_enforcement==="strict")throw new PmCliError(`Item ${located.id} is assigned to ${assigned}. Use --force to override.`,EXIT_CODE.CONFLICT);governance.ownership_enforcement==="warn"&&warnings.push(`ownership_warning:assignee_conflict:${located.id}:${assigned}`)}return{typeToFolder,located,originalRaw,document,warnings,releaseLock,lease}}catch(error){throw await releaseLock(),error}}async function commitLockedItemWrite(lease,located,originalRaw,commit){return lease.fence(async()=>{let currentRaw;try{currentRaw=await fs.readFile(located.itemPath,"utf8")}catch(error){if(!isFileMissingError(error))throw error;currentRaw=null}if(currentRaw!==originalRaw)throw new PmCliError(`Item ${located.id} changed after this mutation read it; refusing to overwrite the newer revision. Nothing was written.`,EXIT_CODE.CONFLICT,{code:"stale_revision",item_id:located.id,reason:currentRaw===null?"item_removed":"item_revision_changed",required:"Re-read the item and apply the mutation again; the newer stored revision was kept."});return commit()})}function resolveItemStoreWriteOverride(serviceWriteOverride,targetItemPath,serializedAfter){if(!serviceWriteOverride.handled||typeof serviceWriteOverride.result!="object"||serviceWriteOverride.result===null)return{effectiveTargetItemPath:targetItemPath,effectiveSerializedAfter:serializedAfter,skipItemWrite:!1};const overrideRecord=serviceWriteOverride.result;return{effectiveTargetItemPath:typeof overrideRecord.target_item_path=="string"&&overrideRecord.target_item_path.trim().length>0?overrideRecord.target_item_path:targetItemPath,effectiveSerializedAfter:typeof overrideRecord.contents=="string"?overrideRecord.contents:serializedAfter,skipItemWrite:overrideRecord.skip_write===!0}}async function resolveItemStoreDeleteOverride(payload){const override=await runActiveServiceOverride("item_store_delete",payload),record=override.handled&&typeof override.result=="object"&&override.result!==null?override.result:{};return{effectiveItemPath:typeof record.item_path=="string"&&record.item_path.trim().length>0?record.item_path:payload.item_path,skipDelete:record.skip_delete===!0,warnings:override.warnings}}async function rollbackMutatedItemWrite(params){if(!params.skipItemWrite){if(params.effectiveTargetItemPath!==params.originalItemPath){await writeFileAtomic(params.originalItemPath,params.originalRaw),await fs.rm(params.effectiveTargetItemPath,{force:!0});return}await writeFileAtomic(params.originalItemPath,params.originalRaw)}}async function mutateItemWithDeferredHistoryContext(params){normalizeHistoryOperationForWrite(params.op);const prepared=await prepareLockedItem({pmRoot:params.pmRoot,settings:params.settings,id:params.id,op:params.op,author:params.author,force:params.force,bypassAssigneeConflict:params.bypassAssigneeConflict,extensionFieldNames:params.extensionFieldNames,typeToFolder:params.typeToFolder}),{typeToFolder,located,originalRaw,document,warnings:parseWarnings,releaseLock,lease}=prepared;try{assertItemMutationPreconditions(params.pmRoot,document);const beforeDocument=canonicalDocument(document,{schema:params.settings.schema,extensionFieldNames:params.extensionFieldNames}),mutableDocument=canonicalDocument(structuredClone(document),{schema:params.settings.schema,extensionFieldNames:params.extensionFieldNames}),mutation=await params.mutate(mutableDocument);if(params.skipNoop===!0&&mutation.changedFields.length===0)return{item:beforeDocument.metadata,body:beforeDocument.body,changedFields:[],warnings:[...parseWarnings,...mutation.warnings??[]]};const historyContext={...params.resolveHistoryContext?.(),...checkpointMutationHistoryContext(params.pmRoot,located.id),...itemMutationPreconditionHistoryContext(params.pmRoot,document)},requiredFormat=Math.max(requiredItemFormatVersion(beforeDocument.metadata),requiredItemFormatVersion(mutableDocument.metadata));assertProjectRuntimeFormatGuard(resolveWorkspaceRoot(params.pmRoot),requiredFormat),requiredFormat>effectiveItemFormatVersion(mutableDocument.metadata)&&(mutableDocument.metadata.pm_format_version=requiredFormat,mutation.changedFields.push("pm_format_version")),mutableDocument.metadata.updated_at=nowIso();const afterDocument=canonicalDocument(mutableDocument,{schema:params.settings.schema,extensionFieldNames:params.extensionFieldNames}),workflowPolicy=await enforceWorkflowMutation({pmRoot:params.pmRoot,settings:params.settings,operation:params.op,author:params.author,before:beforeDocument,after:afterDocument});await runActiveBeforeMutationHooks({pm_root:params.pmRoot,operation:params.op,before:beforeDocument,after:afterDocument,changed_fields:mutation.changedFields,sdk:createMutationGuardSdk({pmRoot:params.pmRoot,settings:params.settings,typeToFolder})});const historyPolicy=await enforceHistoryStreamPolicyForItem({pmRoot:params.pmRoot,settings:params.settings,itemId:located.id,commandLabel:params.op}),targetItemFormat="toon",serializedAfter=serializeItemDocument(afterDocument,{format:targetItemFormat,schema:params.settings.schema,extensionFieldNames:params.extensionFieldNames}),targetItemPath=getItemPath(params.pmRoot,afterDocument.metadata.type,located.id,targetItemFormat,typeToFolder),historyPath=getHistoryPath(params.pmRoot,located.id),committed=await commitLockedItemWrite(lease,located,originalRaw,async()=>{const serviceWriteOverride=await runActiveServiceOverride("item_store_write",{op:params.op,pm_root:params.pmRoot,item_id:located.id,source_item_path:located.itemPath,target_item_path:targetItemPath,history_path:historyPath,item_format:targetItemFormat,before:beforeDocument,after:afterDocument,contents:serializedAfter}),{effectiveTargetItemPath:effectiveTargetItemPath2,effectiveSerializedAfter,skipItemWrite}=resolveItemStoreWriteOverride(serviceWriteOverride,targetItemPath,serializedAfter),releaseDerivedIndexLock=await acquireItemMetadataDerivedIndexLock(params.pmRoot,params.author);let derivedIndexWarnings2=[];try{skipItemWrite||await writeFileAtomic(effectiveTargetItemPath2,effectiveSerializedAfter),!skipItemWrite&&effectiveTargetItemPath2!==located.itemPath&&await fs.rm(located.itemPath);const entry=createHistoryEntry({nowIso:afterDocument.metadata.updated_at,author:params.author,op:params.op,before:beforeDocument,after:afterDocument,message:params.message,context:workflowPolicy.decisions.length===0?Object.keys(historyContext).length===0?void 0:historyContext:{...historyContext,workflow_policies:workflowPolicy.decisions}});try{await appendHistoryEntry(historyPath,entry)}catch(error){throw await rollbackMutatedItemWrite({skipItemWrite,effectiveTargetItemPath:effectiveTargetItemPath2,originalItemPath:located.itemPath,originalRaw}),error}skipItemWrite||(derivedIndexWarnings2=await refreshItemMetadataDerivedIndex({pmRoot:params.pmRoot,preferredFormat:params.settings.item_format,typeToFolder,schema:params.settings.schema,itemPath:effectiveTargetItemPath2,previousItemPath:located.itemPath,document:afterDocument}))}finally{await releaseDerivedIndexLock()}return{derivedIndexWarnings:derivedIndexWarnings2,effectiveTargetItemPath:effectiveTargetItemPath2,overrideWarnings:serviceWriteOverride.warnings}}),{derivedIndexWarnings,effectiveTargetItemPath}=committed;advanceItemMutationPreconditions(params.pmRoot,afterDocument);const hookWarnings=[...await runActiveOnWriteHooks({path:effectiveTargetItemPath,scope:"project",op:params.op,item_id:afterDocument.metadata.id,item_type:afterDocument.metadata.type,before:beforeDocument,after:afterDocument,changed_fields:mutation.changedFields}),...await runActiveOnWriteHooks({path:historyPath,scope:"project",op:`${params.op}:history`,item_id:afterDocument.metadata.id,item_type:afterDocument.metadata.type,before:beforeDocument,after:afterDocument,changed_fields:mutation.changedFields})];return recordAfterCommandAffectedItem({id:afterDocument.metadata.id,op:params.op,item_type:afterDocument.metadata.type,previous_status:beforeDocument.metadata.status,status:afterDocument.metadata.status,previous:projectAfterCommandItemSnapshot(beforeDocument.metadata,mutation.changedFields),current:projectAfterCommandItemSnapshot(afterDocument.metadata,mutation.changedFields),changed_fields:mutation.changedFields}),{item:afterDocument.metadata,body:afterDocument.body,changedFields:mutation.changedFields,warnings:[...parseWarnings,...mutation.warnings??[],...workflowPolicy.warnings,...historyPolicy.warnings,...committed.overrideWarnings,...derivedIndexWarnings,...hookWarnings]}}finally{await releaseLock()}}async function mutateItemWithHistoryContext(params){const{historyContext,...mutationParams}=params;return mutateItemWithDeferredHistoryContext({...mutationParams,resolveHistoryContext:()=>historyContext})}async function mutateItemWithHistoryContextResolver(params){return mutateItemWithDeferredHistoryContext(params)}async function mutateItem(params){return mutateItemWithDeferredHistoryContext(params)}const itemStoreTestOnly={appendWarning,bypassesAssigneeConflict,buildDidYouMeanSuggestions,isErrno};async function deleteItem(params){const prepared=await prepareLockedItem({pmRoot:params.pmRoot,settings:params.settings,id:params.id,op:"delete",author:params.author,force:params.force}),{located,originalRaw,document,warnings:parseWarnings,releaseLock,lease}=prepared;try{assertItemMutationPreconditions(params.pmRoot,document);const extensionFieldNames=resolveActiveExtensionFieldNames(void 0),beforeDocument=canonicalDocument(document,{schema:params.settings.schema,extensionFieldNames}),workflowPolicy=await enforceWorkflowMutation({pmRoot:params.pmRoot,settings:params.settings,operation:"delete",author:params.author,before:beforeDocument,after:null,dryRun:params.dryRun});await runActiveBeforeMutationHooks({pm_root:params.pmRoot,operation:"delete",before:beforeDocument,after:null,changed_fields:["deleted"],sdk:createMutationGuardSdk({pmRoot:params.pmRoot,settings:params.settings,typeToFolder:prepared.typeToFolder})});const historyPolicy=await enforceHistoryStreamPolicyForItem({pmRoot:params.pmRoot,settings:params.settings,itemId:located.id,commandLabel:"delete"}),deletionTimestamp=nowIso(),tombstoneDocument=EMPTY_CANONICAL_DOCUMENT,historyEntry=createHistoryEntry({nowIso:deletionTimestamp,author:params.author,op:"delete",before:beforeDocument,after:tombstoneDocument,message:params.message,context:workflowPolicy.decisions.length===0?void 0:{workflow_policies:workflowPolicy.decisions}}),historyPath=getHistoryPath(params.pmRoot,located.id),runDeleteOverride=()=>resolveItemStoreDeleteOverride({op:"delete",pm_root:params.pmRoot,item_id:located.id,item_path:located.itemPath,history_path:historyPath,before:beforeDocument});if(params.dryRun===!0){const preview=await runDeleteOverride();return{item:beforeDocument.metadata,changedFields:["deleted"],targetPath:preview.effectiveItemPath,warnings:[...parseWarnings,...workflowPolicy.warnings,...historyPolicy.warnings,...preview.warnings]}}const committed=await commitLockedItemWrite(lease,located,originalRaw,async()=>{const{effectiveItemPath:effectiveItemPath2,skipDelete,warnings}=await runDeleteOverride(),releaseDerivedIndexLock=await acquireItemMetadataDerivedIndexLock(params.pmRoot,params.author);let derivedIndexWarnings2=[];try{skipDelete||await fs.rm(effectiveItemPath2);try{await appendHistoryEntry(historyPath,historyEntry)}catch(error){throw skipDelete||await writeFileAtomic(effectiveItemPath2,originalRaw),error}skipDelete||(derivedIndexWarnings2=await refreshItemMetadataDerivedIndex({pmRoot:params.pmRoot,preferredFormat:params.settings.item_format,typeToFolder:prepared.typeToFolder,schema:params.settings.schema,itemPath:effectiveItemPath2,document:null}))}finally{await releaseDerivedIndexLock()}return{derivedIndexWarnings:derivedIndexWarnings2,effectiveItemPath:effectiveItemPath2,overrideWarnings:warnings}}),{derivedIndexWarnings,effectiveItemPath}=committed,hookWarnings=[...await runActiveOnWriteHooks({path:effectiveItemPath,scope:"project",op:"delete",item_id:beforeDocument.metadata.id,item_type:beforeDocument.metadata.type,before:beforeDocument,after:tombstoneDocument,changed_fields:["deleted"]}),...await runActiveOnWriteHooks({path:historyPath,scope:"project",op:"delete:history",item_id:beforeDocument.metadata.id,item_type:beforeDocument.metadata.type,before:beforeDocument,after:tombstoneDocument,changed_fields:["deleted"]})];return recordAfterCommandAffectedItem({id:beforeDocument.metadata.id,op:"delete",item_type:beforeDocument.metadata.type,previous_status:beforeDocument.metadata.status,previous:projectAfterCommandItemSnapshot(beforeDocument.metadata,Object.keys(beforeDocument.metadata)),changed_fields:["deleted"]}),{item:beforeDocument.metadata,changedFields:["deleted"],warnings:[...parseWarnings,...workflowPolicy.warnings,...historyPolicy.warnings,...committed.overrideWarnings,...derivedIndexWarnings,...hookWarnings]}}finally{await releaseLock()}}export{buildItemNotFoundError,createMutationGuardSdk,deleteItem,itemStoreTestOnly,listAllItemMetadata,listAllItemMetadataLight,listAllItemMetadataWithBody,locateItem,mutateItem,mutateItemWithHistoryContext,mutateItemWithHistoryContextResolver,readLocatedItem,readLocatedItemSnapshot};
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="2bc3df8a-c200-52a0-8227-0deda053a955")}catch{}})();import fs from"node:fs/promises";import{buildDeletedItemError}from"../history/tombstone.js";import{normalizeHistoryOperationForWrite}from"../history/operation-contract.js";import{enforceWorkflowMutation}from"../policy/workflow-policy-store.js";import{recordItemMetadataEnumeration}from"./item-metadata-read-work.js";import{advanceItemMutationPreconditions,assertItemMutationPreconditions,itemMutationPreconditionHistoryContext}from"./item-mutation-precondition.js";import{checkpointMutationHistoryContext}from"../checkpoint/mutation-context.js";import path from"node:path";import{getActiveExtensionRegistrations,projectAfterCommandItemSnapshot,recordAfterCommandAffectedItem,runActiveOnReadHooks,runActiveBeforeMutationHooks,runActiveOnWriteHooks,runActiveServiceOverride}from"../extensions/index.js";import{collectRegisteredItemFieldNames}from"../extensions/item-fields.js";import{EMPTY_CANONICAL_DOCUMENT,EXIT_CODE,TYPE_TO_FOLDER}from"../shared/constants.js";import{PmCliError}from"../shared/errors.js";import{levenshteinDistanceWithinLimit}from"../shared/levenshtein.js";import{appendHistoryEntry,createHistoryEntry}from"../history/history.js";import{enforceHistoryStreamPolicyForItem}from"../history/history-stream-policy.js";import{canonicalDocument,parseItemDocument,serializeItemDocument}from"../item/item-format.js";import{resolveItemTypeRegistry}from"../item/type-registry.js";import{effectiveItemFormatVersion,requiredItemFormatVersion}from"../item/item-format-version.js";import{assertProjectRuntimeFormatGuard}from"../../sdk/environment/project-runtime-compatibility.js";import{acquireLockLease}from"../lock/lock.js";import{isFileMissingError,writeFileAtomic}from"../fs/fs-utils.js";import{isUtf8}from"node:buffer";import{normalizeItemId,normalizeRawItemId}from"../item/id.js";import{acquireItemMetadataDerivedIndexLock,listAllDocumentCandidatesCached,listAllDocumentsCached,listAllDocumentsCachedLight,refreshItemMetadataDerivedIndex}from"./item-metadata-cache.js";import{getHistoryPath,getItemPath,ITEM_FILE_EXTENSIONS,resolveWorkspaceRoot}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){try{return await fs.access(targetPath),!0}catch{return!1}}function isErrno(error,code){return typeof error=="object"&&error!==null&&"code"in error&&error.code===code}function appendWarning(warnings,warning){warnings&&(warnings.includes(warning)||warnings.push(warning))}function resolveActiveExtensionFieldNames(explicit){return explicit??collectRegisteredItemFieldNames(getActiveExtensionRegistrations())}function resolveItemFormatSearchOrder(preferredFormat){return preferredFormat==="toon"?["toon","json_markdown"]:preferredFormat==="json_markdown"?["json_markdown","toon"]:["toon","json_markdown"]}async function locateItem(pmRoot,rawId,idPrefix="pm-",preferredFormat,typeToFolder=TYPE_TO_FOLDER){const trimmedRawId=rawId.trim(),exactRawId=trimmedRawId.startsWith("#")?trimmedRawId.slice(1):trimmedRawId;if(exactRawId.length===0)return null;const normalizedId=normalizeItemId(rawId,idPrefix),rawNormalizedId=normalizeRawItemId(rawId),candidateIds=[...new Set([exactRawId,normalizedId,rawNormalizedId])].filter(candidateId=>candidateId.length>0),entries=Object.entries(typeToFolder),searchOrder=resolveItemFormatSearchOrder(preferredFormat);for(const candidateId of candidateIds){const matches=new Map;for(const[type]of entries)for(const itemFormat of searchOrder){const itemPath=getItemPath(pmRoot,type,candidateId,itemFormat,typeToFolder);await fileExists(itemPath)&&matches.set(itemPath,matches.get(itemPath)??{id:candidateId,type,itemPath,item_format:itemFormat})}if(matches.size>1){const paths=[...matches.keys()].map(itemPath=>path.relative(pmRoot,itemPath).split(path.sep).join("/")).sort();throw new PmCliError(`Item ${candidateId} has ambiguous identity across ${paths.join(", ")}. Preserve both documents and inspect pm ops validate --check-storage-integrity before resolving the collision.`,EXIT_CODE.CONFLICT,{code:"item_identity_ambiguous",item_id:candidateId,paths})}for(const match of matches.values())return match}return null}async function readLocatedItem(item,options={}){const snapshot=await readLocatedItemSnapshot(item,options);if(snapshot.error!==null)throw snapshot.error;return{raw:snapshot.raw,document:snapshot.document}}async function readLocatedItemSnapshot(item,options={}){const bytes=await fs.readFile(item.itemPath);if(!isUtf8(bytes))throw new PmCliError("Item contains invalid UTF-8; preserve a binary backup before recovering it.",EXIT_CODE.CONFLICT,{code:"item_document_encoding_invalid",item_id:item.id,item_path:item.itemPath,byte_length:bytes.length,empty:!1});const raw=bytes.toString("utf8");await runActiveOnReadHooks({path:item.itemPath,scope:"project"});let document;try{document=parseItemDocument(raw,{format:item.item_format,requireSupportedFormat:!0,schema:options.schema,extensionFieldNames:resolveActiveExtensionFieldNames(options.extensionFieldNames),onWarning:warning=>appendWarning(options.warnings,warning)})}catch(error){if(error instanceof PmCliError&&error.code==="item_format_version_unsupported")throw new PmCliError(`Item ${item.id}: ${error.message}`,error.exitCode,{...error.context,item_id:item.id,item_path:item.itemPath});if(error instanceof PmCliError&&error.code==="item_document_invalid")return{raw,document:null,error:new PmCliError(`Cannot read ${item.id} at ${item.itemPath}${bytes.length===0?" (zero-length file)":""}: ${error.message}`,error.exitCode,{...error.context,item_id:item.id,item_path:item.itemPath,byte_length:bytes.length,empty:bytes.length===0,nextSteps:[`Run pm history ${item.id} --full, then pm restore ${item.id} <version> to recover a recorded state.`]})};throw error}return{raw,document,error:null}}async function listAllItemMetadata(pmRoot,preferredFormat,typeToFolder=TYPE_TO_FOLDER,warnings,schema){await assertReadableTrackerRoot(pmRoot);const documents=await listAllDocumentsCached(pmRoot,preferredFormat,typeToFolder,warnings,schema);return recordItemMetadataEnumeration(documents.length),documents.map(document=>document.metadata)}async function listAllItemMetadataLight(pmRoot,preferredFormat,typeToFolder=TYPE_TO_FOLDER,warnings,schema){await assertReadableTrackerRoot(pmRoot);const documents=await listAllDocumentsCachedLight(pmRoot,preferredFormat,typeToFolder,warnings,schema);return recordItemMetadataEnumeration(documents.length),documents.map(document=>document.metadata)}async function listAllItemMetadataWithBody(pmRoot,preferredFormat,typeToFolder=TYPE_TO_FOLDER,warnings,schema,options={}){await assertReadableTrackerRoot(pmRoot);const candidates=await listAllDocumentCandidatesCached(pmRoot,preferredFormat,typeToFolder,warnings,schema,{includeBody:!0,forceSourceScan:options.forceSourceScan});return recordItemMetadataEnumeration(candidates.length),candidates.map(candidate=>({...candidate.metadata,body:candidate.body}))}function createMutationGuardSdk(params){return{async get(id){const located=await locateItem(params.pmRoot,id,params.settings.id_prefix,params.settings.item_format,params.typeToFolder);if(!located)return null;const{document}=await readLocatedItem(located,{schema:params.settings.schema});return{item:document.metadata,body:document.body}},list:()=>listAllItemMetadata(params.pmRoot,params.settings.item_format,params.typeToFolder,void 0,params.settings.schema)}}async function listKnownItemIds(pmRoot,typeToFolder){const folders=new Set(Object.values(typeToFolder)),allIds=[];return await Promise.all([...folders].map(async folder=>{try{const entries=await fs.readdir(path.join(pmRoot,folder));for(const entry of entries)for(const ext of ITEM_FILE_EXTENSIONS)if(entry.toLowerCase().endsWith(ext)){allIds.push(entry.slice(0,-ext.length));break}}catch{}})),allIds}async function buildDidYouMeanSuggestions(pmRoot,badId,idPrefix,typeToFolder){const normalized=normalizeItemId(badId,idPrefix),ids=await listKnownItemIds(pmRoot,typeToFolder);if(ids.length===0)return[];const limit=Math.max(3,Math.floor(normalized.length/2));return ids.map(id=>({id,distance:levenshteinDistanceWithinLimit(id,normalized,limit)})).filter(entry=>entry.distance!==null).sort((left,right)=>left.distance-right.distance).slice(0,3).map(entry=>entry.id)}async function buildItemNotFoundError(pmRoot,badId,idPrefix,typeToFolder){const deleted=await buildDeletedItemError(pmRoot,badId,idPrefix);if(deleted)return deleted;const suggestions=await buildDidYouMeanSuggestions(pmRoot,badId,idPrefix,typeToFolder),nextSteps=["Confirm the active --path/PM_PATH scope, then retry with a valid id."];return suggestions.length>0&&nextSteps.unshift(`Did you mean one of: ${suggestions.join(", ")}?`),new PmCliError(`Item ${badId} not found`,EXIT_CODE.NOT_FOUND,{code:"item_not_found",id:badId,nextSteps})}function bypassesAssigneeConflict(op,bypassAssigneeConflict){return op==="claim"||bypassAssigneeConflict===!0&&(op==="comment_add"||op==="comment_edit"||op==="comment_delete"||op==="note_add"||op==="learning_add"||op==="release"||op==="update"||op==="update_ownership_bypass"||op==="update_audit")}async function prepareLockedItem(params){const typeToFolder=params.typeToFolder??resolveItemTypeRegistry(params.settings,getActiveExtensionRegistrations()).type_to_folder,located=await locateItem(params.pmRoot,params.id,params.settings.id_prefix,params.settings.item_format,typeToFolder);if(!located)throw await buildItemNotFoundError(params.pmRoot,params.id,params.settings.id_prefix,typeToFolder);const lease=await acquireLockLease(params.pmRoot,located.id,params.settings.locks.ttl_seconds,params.author,!!params.force,params.settings.governance.force_required_for_stale_lock,params.settings.locks.wait_ms,{waitPolicy:"progress"}),releaseLock=lease.release;try{const warnings=[],{raw:originalRaw,document}=await readLocatedItem(located,{schema:params.settings.schema,extensionFieldNames:params.extensionFieldNames,warnings}),assigned=document.metadata.assignee?.trim(),assignedPrincipal=document.metadata.claim_principal?.trim()||assigned,callerPrincipal=resolveClaimPrincipal(params.author),governance=resolveGovernanceKnobs(params.settings);if(assigned&&assignedPrincipal!==callerPrincipal&&!params.force&&!bypassesAssigneeConflict(params.op,params.bypassAssigneeConflict)){if(governance.ownership_enforcement==="strict")throw new PmCliError(`Item ${located.id} is assigned to ${assigned}. Use --force to override.`,EXIT_CODE.CONFLICT);governance.ownership_enforcement==="warn"&&warnings.push(`ownership_warning:assignee_conflict:${located.id}:${assigned}`)}return{typeToFolder,located,originalRaw,document,warnings,releaseLock,lease}}catch(error){throw await releaseLock(),error}}async function commitLockedItemWrite(lease,located,originalRaw,commit){return lease.fence(async()=>{let currentRaw;try{currentRaw=await fs.readFile(located.itemPath,"utf8")}catch(error){if(!isFileMissingError(error))throw error;currentRaw=null}if(currentRaw!==originalRaw)throw new PmCliError(`Item ${located.id} changed after this mutation read it; refusing to overwrite the newer revision. Nothing was written.`,EXIT_CODE.CONFLICT,{code:"stale_revision",item_id:located.id,reason:currentRaw===null?"item_removed":"item_revision_changed",required:"Re-read the item and apply the mutation again; the newer stored revision was kept."});return commit()})}function resolveItemStoreWriteOverride(serviceWriteOverride,targetItemPath,serializedAfter){if(!serviceWriteOverride.handled||typeof serviceWriteOverride.result!="object"||serviceWriteOverride.result===null)return{effectiveTargetItemPath:targetItemPath,effectiveSerializedAfter:serializedAfter,skipItemWrite:!1};const overrideRecord=serviceWriteOverride.result;return{effectiveTargetItemPath:typeof overrideRecord.target_item_path=="string"&&overrideRecord.target_item_path.trim().length>0?overrideRecord.target_item_path:targetItemPath,effectiveSerializedAfter:typeof overrideRecord.contents=="string"?overrideRecord.contents:serializedAfter,skipItemWrite:overrideRecord.skip_write===!0}}async function readOverriddenCommitRevision(params){try{const located=await locateItem(params.pmRoot,params.id,params.settings.id_prefix,params.settings.item_format,params.typeToFolder);if(!located)return{document:EMPTY_CANONICAL_DOCUMENT};const document=parseItemDocument(await fs.readFile(located.itemPath,"utf8"),{format:located.item_format,requireSupportedFormat:!0,schema:params.settings.schema,extensionFieldNames:resolveActiveExtensionFieldNames(params.extensionFieldNames)});return document.metadata.id===params.embeddedId?{document}:{document:params.fallback,revision:UNREADABLE_COMMIT_REVISION}}catch{return{document:params.fallback,revision:UNREADABLE_COMMIT_REVISION}}}const UNREADABLE_COMMIT_REVISION="unreadable-after-storage-override";async function resolveItemStoreDeleteOverride(payload){const override=await runActiveServiceOverride("item_store_delete",payload),record=override.handled&&typeof override.result=="object"&&override.result!==null?override.result:{};return{effectiveItemPath:typeof record.item_path=="string"&&record.item_path.trim().length>0?record.item_path:payload.item_path,skipDelete:record.skip_delete===!0,warnings:override.warnings}}async function rollbackMutatedItemWrite(params){if(!params.skipItemWrite){if(params.effectiveTargetItemPath!==params.originalItemPath){await writeFileAtomic(params.originalItemPath,params.originalRaw),await fs.rm(params.effectiveTargetItemPath,{force:!0});return}await writeFileAtomic(params.originalItemPath,params.originalRaw)}}async function mutateItemWithDeferredHistoryContext(params){normalizeHistoryOperationForWrite(params.op);const prepared=await prepareLockedItem({pmRoot:params.pmRoot,settings:params.settings,id:params.id,op:params.op,author:params.author,force:params.force,bypassAssigneeConflict:params.bypassAssigneeConflict,extensionFieldNames:params.extensionFieldNames,typeToFolder:params.typeToFolder}),{typeToFolder,located,originalRaw,document,warnings:parseWarnings,releaseLock,lease}=prepared;try{assertItemMutationPreconditions(params.pmRoot,document,located.id);const beforeDocument=canonicalDocument(document,{schema:params.settings.schema,extensionFieldNames:params.extensionFieldNames}),mutableDocument=canonicalDocument(structuredClone(document),{schema:params.settings.schema,extensionFieldNames:params.extensionFieldNames}),mutation=await params.mutate(mutableDocument);if(params.skipNoop===!0&&mutation.changedFields.length===0)return{item:beforeDocument.metadata,body:beforeDocument.body,changedFields:[],warnings:[...parseWarnings,...mutation.warnings??[]]};const historyContext={...params.resolveHistoryContext?.(),...checkpointMutationHistoryContext(params.pmRoot,located.id),...itemMutationPreconditionHistoryContext(params.pmRoot,[located.id,document.metadata.id])},requiredFormat=Math.max(requiredItemFormatVersion(beforeDocument.metadata),requiredItemFormatVersion(mutableDocument.metadata));assertProjectRuntimeFormatGuard(resolveWorkspaceRoot(params.pmRoot),requiredFormat),requiredFormat>effectiveItemFormatVersion(mutableDocument.metadata)&&(mutableDocument.metadata.pm_format_version=requiredFormat,mutation.changedFields.push("pm_format_version")),mutableDocument.metadata.updated_at=nowIso();const afterDocument=canonicalDocument(mutableDocument,{schema:params.settings.schema,extensionFieldNames:params.extensionFieldNames}),workflowPolicy=await enforceWorkflowMutation({pmRoot:params.pmRoot,settings:params.settings,operation:params.op,author:params.author,before:beforeDocument,after:afterDocument});await runActiveBeforeMutationHooks({pm_root:params.pmRoot,operation:params.op,before:beforeDocument,after:afterDocument,changed_fields:mutation.changedFields,sdk:createMutationGuardSdk({pmRoot:params.pmRoot,settings:params.settings,typeToFolder})});const historyPolicy=await enforceHistoryStreamPolicyForItem({pmRoot:params.pmRoot,settings:params.settings,itemId:located.id,commandLabel:params.op}),targetItemFormat="toon",serializedAfter=serializeItemDocument(afterDocument,{format:targetItemFormat,schema:params.settings.schema,extensionFieldNames:params.extensionFieldNames}),targetItemPath=getItemPath(params.pmRoot,afterDocument.metadata.type,located.id,targetItemFormat,typeToFolder),historyPath=getHistoryPath(params.pmRoot,located.id),committed=await commitLockedItemWrite(lease,located,originalRaw,async()=>{const serviceWriteOverride=await runActiveServiceOverride("item_store_write",{op:params.op,pm_root:params.pmRoot,item_id:located.id,source_item_path:located.itemPath,target_item_path:targetItemPath,history_path:historyPath,item_format:targetItemFormat,before:beforeDocument,after:afterDocument,contents:serializedAfter}),{effectiveTargetItemPath:effectiveTargetItemPath2,effectiveSerializedAfter,skipItemWrite}=resolveItemStoreWriteOverride(serviceWriteOverride,targetItemPath,serializedAfter),releaseDerivedIndexLock=await acquireItemMetadataDerivedIndexLock(params.pmRoot,params.author);let derivedIndexWarnings2=[];try{skipItemWrite||await writeFileAtomic(effectiveTargetItemPath2,effectiveSerializedAfter),!skipItemWrite&&effectiveTargetItemPath2!==located.itemPath&&await fs.rm(located.itemPath);const entry=createHistoryEntry({nowIso:afterDocument.metadata.updated_at,author:params.author,op:params.op,before:beforeDocument,after:afterDocument,message:params.message,context:workflowPolicy.decisions.length===0?Object.keys(historyContext).length===0?void 0:historyContext:{...historyContext,workflow_policies:workflowPolicy.decisions}});try{await appendHistoryEntry(historyPath,entry)}catch(error){throw await rollbackMutatedItemWrite({skipItemWrite,effectiveTargetItemPath:effectiveTargetItemPath2,originalItemPath:located.itemPath,originalRaw}),error}skipItemWrite||(derivedIndexWarnings2=await refreshItemMetadataDerivedIndex({pmRoot:params.pmRoot,preferredFormat:params.settings.item_format,typeToFolder,schema:params.settings.schema,itemPath:effectiveTargetItemPath2,previousItemPath:located.itemPath,document:afterDocument}))}finally{await releaseDerivedIndexLock()}const overridden=skipItemWrite||effectiveTargetItemPath2!==targetItemPath||effectiveSerializedAfter!==serializedAfter;return{derivedIndexWarnings:derivedIndexWarnings2,effectiveTargetItemPath:effectiveTargetItemPath2,overrideWarnings:serviceWriteOverride.warnings,stored:overridden?await readOverriddenCommitRevision({pmRoot:params.pmRoot,settings:params.settings,id:located.id,typeToFolder,extensionFieldNames:params.extensionFieldNames,fallback:afterDocument,embeddedId:afterDocument.metadata.id}):{document:afterDocument}}}),{derivedIndexWarnings,effectiveTargetItemPath,stored}=committed;advanceItemMutationPreconditions(params.pmRoot,stored.document,located.id,[afterDocument.metadata.id],stored.revision);const hookWarnings=[...await runActiveOnWriteHooks({path:effectiveTargetItemPath,scope:"project",op:params.op,item_id:afterDocument.metadata.id,item_type:afterDocument.metadata.type,before:beforeDocument,after:afterDocument,changed_fields:mutation.changedFields}),...await runActiveOnWriteHooks({path:historyPath,scope:"project",op:`${params.op}:history`,item_id:afterDocument.metadata.id,item_type:afterDocument.metadata.type,before:beforeDocument,after:afterDocument,changed_fields:mutation.changedFields})];return recordAfterCommandAffectedItem({id:afterDocument.metadata.id,op:params.op,item_type:afterDocument.metadata.type,previous_status:beforeDocument.metadata.status,status:afterDocument.metadata.status,previous:projectAfterCommandItemSnapshot(beforeDocument.metadata,mutation.changedFields),current:projectAfterCommandItemSnapshot(afterDocument.metadata,mutation.changedFields),changed_fields:mutation.changedFields}),{item:afterDocument.metadata,body:afterDocument.body,changedFields:mutation.changedFields,warnings:[...parseWarnings,...mutation.warnings??[],...workflowPolicy.warnings,...historyPolicy.warnings,...committed.overrideWarnings,...derivedIndexWarnings,...hookWarnings]}}finally{await releaseLock()}}async function mutateItemWithHistoryContext(params){const{historyContext,...mutationParams}=params;return mutateItemWithDeferredHistoryContext({...mutationParams,resolveHistoryContext:()=>historyContext})}async function mutateItemWithHistoryContextResolver(params){return mutateItemWithDeferredHistoryContext(params)}async function mutateItem(params){return mutateItemWithDeferredHistoryContext(params)}const itemStoreTestOnly={appendWarning,bypassesAssigneeConflict,buildDidYouMeanSuggestions,isErrno};async function deleteItem(params){const prepared=await prepareLockedItem({pmRoot:params.pmRoot,settings:params.settings,id:params.id,op:"delete",author:params.author,force:params.force}),{located,originalRaw,document,warnings:parseWarnings,releaseLock,lease}=prepared;try{assertItemMutationPreconditions(params.pmRoot,document,located.id);const extensionFieldNames=resolveActiveExtensionFieldNames(void 0),beforeDocument=canonicalDocument(document,{schema:params.settings.schema,extensionFieldNames}),workflowPolicy=await enforceWorkflowMutation({pmRoot:params.pmRoot,settings:params.settings,operation:"delete",author:params.author,before:beforeDocument,after:null,dryRun:params.dryRun});await runActiveBeforeMutationHooks({pm_root:params.pmRoot,operation:"delete",before:beforeDocument,after:null,changed_fields:["deleted"],sdk:createMutationGuardSdk({pmRoot:params.pmRoot,settings:params.settings,typeToFolder:prepared.typeToFolder})});const historyPolicy=await enforceHistoryStreamPolicyForItem({pmRoot:params.pmRoot,settings:params.settings,itemId:located.id,commandLabel:"delete"}),deletionTimestamp=nowIso(),tombstoneDocument=EMPTY_CANONICAL_DOCUMENT,historyEntry=createHistoryEntry({nowIso:deletionTimestamp,author:params.author,op:"delete",before:beforeDocument,after:tombstoneDocument,message:params.message,context:workflowPolicy.decisions.length===0?void 0:{workflow_policies:workflowPolicy.decisions}}),historyPath=getHistoryPath(params.pmRoot,located.id),runDeleteOverride=()=>resolveItemStoreDeleteOverride({op:"delete",pm_root:params.pmRoot,item_id:located.id,item_path:located.itemPath,history_path:historyPath,before:beforeDocument});if(params.dryRun===!0){const preview=await runDeleteOverride();return{item:beforeDocument.metadata,changedFields:["deleted"],targetPath:preview.effectiveItemPath,warnings:[...parseWarnings,...workflowPolicy.warnings,...historyPolicy.warnings,...preview.warnings]}}const committed=await commitLockedItemWrite(lease,located,originalRaw,async()=>{const{effectiveItemPath:effectiveItemPath2,skipDelete,warnings}=await runDeleteOverride(),releaseDerivedIndexLock=await acquireItemMetadataDerivedIndexLock(params.pmRoot,params.author);let derivedIndexWarnings2=[];try{skipDelete||await fs.rm(effectiveItemPath2);try{await appendHistoryEntry(historyPath,historyEntry)}catch(error){throw skipDelete||await writeFileAtomic(effectiveItemPath2,originalRaw),error}skipDelete||(derivedIndexWarnings2=await refreshItemMetadataDerivedIndex({pmRoot:params.pmRoot,preferredFormat:params.settings.item_format,typeToFolder:prepared.typeToFolder,schema:params.settings.schema,itemPath:effectiveItemPath2,document:null}))}finally{await releaseDerivedIndexLock()}return{derivedIndexWarnings:derivedIndexWarnings2,effectiveItemPath:effectiveItemPath2,overrideWarnings:warnings,stored:skipDelete||effectiveItemPath2!==located.itemPath?await readOverriddenCommitRevision({pmRoot:params.pmRoot,settings:params.settings,id:located.id,typeToFolder:prepared.typeToFolder,fallback:tombstoneDocument,embeddedId:document.metadata.id}):{document:tombstoneDocument}}}),{derivedIndexWarnings,effectiveItemPath,stored}=committed;advanceItemMutationPreconditions(params.pmRoot,stored.document,located.id,[document.metadata.id],stored.revision);const hookWarnings=[...await runActiveOnWriteHooks({path:effectiveItemPath,scope:"project",op:"delete",item_id:beforeDocument.metadata.id,item_type:beforeDocument.metadata.type,before:beforeDocument,after:tombstoneDocument,changed_fields:["deleted"]}),...await runActiveOnWriteHooks({path:historyPath,scope:"project",op:"delete:history",item_id:beforeDocument.metadata.id,item_type:beforeDocument.metadata.type,before:beforeDocument,after:tombstoneDocument,changed_fields:["deleted"]})];return recordAfterCommandAffectedItem({id:beforeDocument.metadata.id,op:"delete",item_type:beforeDocument.metadata.type,previous_status:beforeDocument.metadata.status,previous:projectAfterCommandItemSnapshot(beforeDocument.metadata,Object.keys(beforeDocument.metadata)),changed_fields:["deleted"]}),{item:beforeDocument.metadata,changedFields:["deleted"],warnings:[...parseWarnings,...workflowPolicy.warnings,...historyPolicy.warnings,...committed.overrideWarnings,...derivedIndexWarnings,...hookWarnings]}}finally{await releaseLock()}}export{buildItemNotFoundError,createMutationGuardSdk,deleteItem,itemStoreTestOnly,listAllItemMetadata,listAllItemMetadataLight,listAllItemMetadataWithBody,locateItem,mutateItem,mutateItemWithHistoryContext,mutateItemWithHistoryContextResolver,readLocatedItem,readLocatedItemSnapshot};
 //# sourceMappingURL=item-store.js.map

package/dist/core/store/settings-validator.js

@@ -1,2 +1,2 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="c7f9d249-e2c2-5edd-afbd-b14ac1c12e81")}catch{}})();import{GOVERNANCE_PRESET_VALUES,RUNTIME_FIELD_COMMAND_VALUES,RUNTIME_FIELD_TYPE_VALUES,RUNTIME_STATUS_ROLE_VALUES,RUNTIME_UNKNOWN_FIELD_POLICY_VALUES}from"../../types.js";const FAIL={ok:!1,path:[]};function failAt(segment,failure){return{ok:!1,path:[segment,...failure.path]}}const vString=input=>typeof input=="string"?{ok:!0,value:input}:FAIL,vBoolean=input=>typeof input=="boolean"?{ok:!0,value:input}:FAIL;function vNumber(options={}){return input=>typeof input!="number"||!Number.isFinite(input)||options.int&&(!Number.isInteger(input)||!Number.isSafeInteger(input))||options.positive&&input<=0||typeof options.min=="number"&&input<options.min||typeof options.max=="number"&&input>options.max?FAIL:{ok:!0,value:input}}function vLiteral(...allowed){return input=>typeof input=="string"&&allowed.includes(input)?{ok:!0,value:input}:FAIL}function vArray(item,maxLength){return input=>{if(!Array.isArray(input)||maxLength!==void 0&&input.length>maxLength)return FAIL;const value=[];for(const[index,element]of input.entries()){const result=item(element);if(!result.ok)return failAt(String(index),result);value.push(result.value)}return{ok:!0,value}}}function vBoundedNormalizedString(maxLength,pattern){return input=>typeof input=="string"&&input.length>0&&input.length<=maxLength&&input===input.trim()&&(pattern===void 0||pattern.test(input))?{ok:!0,value:input}:FAIL}function vOptional(inner){return input=>input===void 0?{ok:!0,value:void 0}:inner(input)}function vRecordOf(valueCheck){return input=>{if(typeof input!="object"||input===null||Array.isArray(input))return FAIL;const value={};for(const[key,raw]of Object.entries(input)){const result=valueCheck(raw);if(!result.ok)return failAt(key,result);value[key]=result.value}return{ok:!0,value}}}function vObject(shape){return input=>{if(typeof input!="object"||input===null||Array.isArray(input))return FAIL;const record=input,value={};for(const[key,check]of Object.entries(shape)){const result=check(record[key]);if(!result.ok)return failAt(key,result);result.value!==void 0&&(value[key]=result.value)}return{ok:!0,value}}}const itemTypeOption=vObject({key:vString,values:vArray(vString),required:vOptional(vBoolean),aliases:vOptional(vArray(vString)),description:vOptional(vString)}),itemTypeCommandOptionPolicy=vObject({command:vLiteral("create","update"),option:vString,required:vOptional(vBoolean),visible:vOptional(vBoolean),enabled:vOptional(vBoolean)}),itemTypeDefinition=vObject({name:vString,description:vOptional(vString),default_status:vOptional(vString),execution_role:vOptional(vLiteral("agent","human","gate")),folder:vOptional(vString),aliases:vOptional(vArray(vString)),required_create_fields:vOptional(vArray(vString)),required_create_repeatables:vOptional(vArray(vString)),options:vOptional(vArray(itemTypeOption)),command_option_policies:vOptional(vArray(itemTypeCommandOptionPolicy))}),runtimeStatusDefinition=vObject({id:vString,aliases:vOptional(vArray(vString)),roles:vOptional(vArray(vLiteral(...RUNTIME_STATUS_ROLE_VALUES))),description:vOptional(vString),order:vOptional(vNumber())}),runtimeFieldDefinition=vObject({key:vString,metadata_key:vOptional(vString),front_matter_key:vOptional(vString),cli_flag:vOptional(vString),cli_aliases:vOptional(vArray(vString)),description:vOptional(vString),type:vOptional(vLiteral(...RUNTIME_FIELD_TYPE_VALUES)),commands:vOptional(vArray(vLiteral(...RUNTIME_FIELD_COMMAND_VALUES))),repeatable:vOptional(vBoolean),required:vOptional(vBoolean),required_on_create:vOptional(vBoolean),required_types:vOptional(vArray(vString)),allow_unset:vOptional(vBoolean)}),statusTransitionPair=input=>{if(!Array.isArray(input)||input.length!==2)return FAIL;const[from,to]=input;return typeof from!="string"||typeof to!="string"?FAIL:{ok:!0,value:[from,to]}},typeWorkflowDefinition=vObject({type:vString,allowed_transitions:vArray(statusTransitionPair)}),runtimeSchemaSettings=vOptional(vObject({version:vOptional(vNumber({int:!0})),files:vOptional(vObject({types:vOptional(vString),statuses:vOptional(vString),fields:vOptional(vString),workflows:vOptional(vString)})),statuses:vOptional(vArray(runtimeStatusDefinition)),fields:vOptional(vArray(runtimeFieldDefinition)),workflow:vOptional(vObject({draft_status:vOptional(vString),open_status:vOptional(vString),in_progress_status:vOptional(vString),blocked_status:vOptional(vString),close_status:vOptional(vString),canceled_status:vOptional(vString)})),type_workflows:vOptional(vArray(typeWorkflowDefinition)),unknown_field_policy:vOptional(vLiteral(...RUNTIME_UNKNOWN_FIELD_POLICY_VALUES))})),governanceSettings=vOptional(vObject({preset:vOptional(vLiteral(...GOVERNANCE_PRESET_VALUES)),ownership_enforcement:vOptional(vLiteral("none","warn","strict")),create_mode_default:vOptional(vLiteral("progressive","strict")),close_validation_default:vOptional(vLiteral("off","warn","strict")),require_close_reason:vOptional(vBoolean),parent_reference:vOptional(vLiteral("warn","strict_error")),metadata_profile:vOptional(vLiteral("core","strict","custom")),force_required_for_stale_lock:vOptional(vBoolean),create_default_type:vOptional(vString),workflow_enforcement:vOptional(vLiteral("off","warn","strict")),duplicate_detection_mode:vOptional(vLiteral("off","advisory","strict")),duplicate_detection_threshold:vOptional(vNumber({min:0,max:1})),duplicate_detection_limit:vOptional(vNumber({int:!0,min:0,max:20}))})),extensionPolicyOverride=vObject({name:vString,disabled:vOptional(vBoolean),require_trusted:vOptional(vBoolean),require_provenance:vOptional(vBoolean),sandbox_profile:vOptional(vLiteral("none","restricted","strict")),allowed_capabilities:vOptional(vArray(vString)),blocked_capabilities:vOptional(vArray(vString)),allowed_surfaces:vOptional(vArray(vString)),blocked_surfaces:vOptional(vArray(vString)),allowed_commands:vOptional(vArray(vString)),blocked_commands:vOptional(vArray(vString)),allowed_actions:vOptional(vArray(vString)),blocked_actions:vOptional(vArray(vString)),allowed_services:vOptional(vArray(vString)),blocked_services:vOptional(vArray(vString))}),pmMaxVersionExceededModeLiteral=vLiteral("block","warn"),pmMaxVersionExceededMode=input=>typeof input=="string"?pmMaxVersionExceededModeLiteral(input):vObject({global:vOptional(pmMaxVersionExceededModeLiteral),project:vOptional(pmMaxVersionExceededModeLiteral)})(input),extensionPolicy=vOptional(vObject({mode:vOptional(vLiteral("off","warn","enforce")),trust_mode:vOptional(vLiteral("off","warn","enforce")),pm_max_version_exceeded_mode:vOptional(pmMaxVersionExceededMode),require_provenance:vOptional(vBoolean),trusted_extensions:vOptional(vArray(vString)),default_sandbox_profile:vOptional(vLiteral("none","restricted","strict")),allowed_extensions:vOptional(vArray(vString)),blocked_extensions:vOptional(vArray(vString)),allowed_capabilities:vOptional(vArray(vString)),blocked_capabilities:vOptional(vArray(vString)),allowed_surfaces:vOptional(vArray(vString)),blocked_surfaces:vOptional(vArray(vString)),allowed_commands:vOptional(vArray(vString)),blocked_commands:vOptional(vArray(vString)),allowed_actions:vOptional(vArray(vString)),blocked_actions:vOptional(vArray(vString)),allowed_services:vOptional(vArray(vString)),blocked_services:vOptional(vArray(vString)),extension_overrides:vOptional(vArray(extensionPolicyOverride))})),harnessSignalLiteral=vBoundedNormalizedString(128),harnessSignalDescriptor=vObject({harness:vBoundedNormalizedString(128,/^[a-z0-9]+(?:-[a-z0-9]+)*$/u),environment_keys:vOptional(vArray(harnessSignalLiteral,64)),model_environment_keys:vOptional(vArray(harnessSignalLiteral,64)),session_environment_keys:vOptional(vArray(harnessSignalLiteral,64)),provenance_environment_keys:vOptional(vRecordOf(vArray(harnessSignalLiteral,64))),provenance_resolvers:vOptional(vRecordOf(vLiteral("ai_agent_version","claude_session_file"))),provenance_unavailable_dimensions:vOptional(vArray(harnessSignalLiteral,64)),argv_markers:vOptional(vArray(harnessSignalLiteral,64)),client_names:vOptional(vArray(harnessSignalLiteral,64))}),SETTINGS_SHAPE={version:vNumber({int:!0}),id_prefix:vString,ids:vOptional(vObject({token_length:vOptional(vNumber({int:!0,min:4,max:12}))})),author_default:vString,agent_identity:vOptional(vObject({probes_enabled:vOptional(vBoolean),identity_vocabulary:vOptional(vObject({version:vNumber({int:!0,positive:!0}),aliases:vRecordOf(vBoundedNormalizedString(128,/^[a-z0-9]+(?:-[a-z0-9]+)*$/u))})),harness_signals:vArray(harnessSignalDescriptor)})),mutation_guard:vOptional(vObject({require_attributed_author:vOptional(vBoolean),secret_guard:vOptional(vLiteral("off","advise","block")),stale_in_progress_hours:vOptional(vNumber({int:!0,positive:!0}))})),item_format:vOptional(vLiteral("toon","json_markdown")),locks:vObject({ttl_seconds:vNumber({int:!0}),wait_ms:vOptional(vNumber({int:!0,min:0}))}),checkpoints:vOptional(vObject({retention_days:vOptional(vNumber({int:!0,positive:!0}))})),output:vObject({default_format:vLiteral("toon","json")}),ux:vOptional(vObject({deprecation_hints:vOptional(vBoolean)})),history:vOptional(vObject({missing_stream:vLiteral("auto_create","strict_error"),compact_policy:vOptional(vObject({enabled:vOptional(vBoolean),max_entries:vOptional(vNumber({int:!0,positive:!0})),trigger:vOptional(vLiteral("health_warn","auto"))}))})),validation:vOptional(vObject({sprint_release_format:vLiteral("warn","strict_error"),parent_reference:vOptional(vLiteral("warn","strict_error")),metadata_profile:vOptional(vLiteral("core","strict","custom")),metadata_required_fields:vOptional(vArray(vString)),lifecycle_stale_blocker_reason_patterns:vOptional(vArray(vString)),lifecycle_closure_like_blocked_reason_patterns:vOptional(vArray(vString)),lifecycle_closure_like_resolution_patterns:vOptional(vArray(vString)),lifecycle_closure_like_actual_result_patterns:vOptional(vArray(vString)),estimate_defaults_by_type:vOptional(vRecordOf(vNumber({int:!0,positive:!0})))})),governance:governanceSettings,workflow:vOptional(vObject({definition_of_done:vArray(vString)})),testing:vOptional(vObject({record_results_to_items:vBoolean,allow_untrusted_linked_tests:vOptional(vBoolean)})),telemetry:vOptional(vObject({enabled:vBoolean,first_run_prompt_completed:vOptional(vBoolean),capture_level:vOptional(vLiteral("minimal","redacted","max")),endpoint:vOptional(vString),installation_id:vOptional(vString),retention_days:vOptional(vNumber({int:!0,positive:!0}))})),agent_guidance:vOptional(vObject({prompt_completed:vOptional(vBoolean),declined:vOptional(vBoolean),declined_at:vOptional(vString),template_version:vOptional(vNumber({int:!0,positive:!0})),last_checked_files:vOptional(vArray(vString))})),item_types:vOptional(vObject({definitions:vArray(itemTypeDefinition)})),schema:runtimeSchemaSettings,context:vOptional(vObject({default_depth:vOptional(vLiteral("brief","standard","deep")),activity_limit:vOptional(vNumber({int:!0,positive:!0})),stale_threshold_days:vOptional(vNumber({int:!0,positive:!0})),next_ranking_policy:vOptional(vLiteral("priority_floor","weighted")),sections:vOptional(vObject({hierarchy:vOptional(vBoolean),activity:vOptional(vBoolean),progress:vOptional(vBoolean),recently_created:vOptional(vBoolean),unparented:vOptional(vBoolean),blockers:vOptional(vBoolean),files:vOptional(vBoolean),workload:vOptional(vBoolean),staleness:vOptional(vBoolean),tests:vOptional(vBoolean)}))})),extensions:vObject({enabled:vArray(vString),disabled:vArray(vString),policy:extensionPolicy}),search:vObject({score_threshold:vNumber(),hybrid_semantic_weight:vOptional(vNumber()),max_results:vNumber({int:!0}),embedding_model:vString,embedding_corpus_max_characters:vOptional(vNumber()),embedding_batch_size:vNumber({int:!0}),embedding_timeout_ms:vOptional(vNumber({int:!0})),scanner_max_batch_retries:vNumber({int:!0}),provider:vOptional(vString),default_mode:vOptional(vLiteral("auto","keyword","semantic","hybrid")),corpus_fields:vOptional(vArray(vString)),mutation_refresh_policy:vOptional(vLiteral("cache_only","semantic_configured","semantic_auto")),query_expansion:vOptional(vObject({enabled:vOptional(vBoolean),provider:vOptional(vString)})),rerank:vOptional(vObject({enabled:vOptional(vBoolean),model:vOptional(vString),top_k:vOptional(vNumber({int:!0,positive:!0}))})),bm25:vOptional(vObject({k1:vOptional(vNumber()),b:vOptional(vNumber())}))}),providers:vObject({openai:vObject({base_url:vString,api_key:vString,model:vString}),ollama:vObject({base_url:vString,model:vString})}),vector_store:vObject({adapter:vOptional(vString),collection_name:vOptional(vString),qdrant:vObject({url:vString,api_key:vString}),lancedb:vObject({path:vString})})},settingsCheck=vObject(SETTINGS_SHAPE),CORE_SETTINGS_SECTION_KEYS=Object.freeze(Object.keys(SETTINGS_SHAPE));function validateSettings(raw){const result=settingsCheck(raw);return result.ok?{success:!0,data:result.value}:{success:!1,path:result.path.join(".")}}export{CORE_SETTINGS_SECTION_KEYS,validateSettings};
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="33d6dc97-17d3-5db3-ab0d-6857be0e5827")}catch{}})();import{GOVERNANCE_PRESET_VALUES,RUNTIME_FIELD_COMMAND_VALUES,RUNTIME_FIELD_TYPE_VALUES,RUNTIME_STATUS_ROLE_VALUES,RUNTIME_UNKNOWN_FIELD_POLICY_VALUES}from"../../types.js";const FAIL={ok:!1,path:[]};function failAt(segment,failure){return{ok:!1,path:[segment,...failure.path]}}const vString=input=>typeof input=="string"?{ok:!0,value:input}:FAIL,vBoolean=input=>typeof input=="boolean"?{ok:!0,value:input}:FAIL;function vNumber(options={}){return input=>typeof input!="number"||!Number.isFinite(input)||options.int&&(!Number.isInteger(input)||!Number.isSafeInteger(input))||options.positive&&input<=0||typeof options.min=="number"&&input<options.min||typeof options.max=="number"&&input>options.max?FAIL:{ok:!0,value:input}}function vLiteral(...allowed){return input=>typeof input=="string"&&allowed.includes(input)?{ok:!0,value:input}:FAIL}function vArray(item,maxLength){return input=>{if(!Array.isArray(input)||maxLength!==void 0&&input.length>maxLength)return FAIL;const value=[];for(const[index,element]of input.entries()){const result=item(element);if(!result.ok)return failAt(String(index),result);value.push(result.value)}return{ok:!0,value}}}function vBoundedNormalizedString(maxLength,pattern){return input=>typeof input=="string"&&input.length>0&&input.length<=maxLength&&input===input.trim()&&(pattern===void 0||pattern.test(input))?{ok:!0,value:input}:FAIL}function vOptional(inner){return input=>input===void 0?{ok:!0,value:void 0}:inner(input)}function vRecordOf(valueCheck){return input=>{if(typeof input!="object"||input===null||Array.isArray(input))return FAIL;const value={};for(const[key,raw]of Object.entries(input)){const result=valueCheck(raw);if(!result.ok)return failAt(key,result);value[key]=result.value}return{ok:!0,value}}}function vObject(shape){return input=>{if(typeof input!="object"||input===null||Array.isArray(input))return FAIL;const record=input,value={};for(const[key,check]of Object.entries(shape)){const result=check(record[key]);if(!result.ok)return failAt(key,result);result.value!==void 0&&(value[key]=result.value)}return{ok:!0,value}}}const itemTypeOption=vObject({key:vString,values:vArray(vString),required:vOptional(vBoolean),aliases:vOptional(vArray(vString)),description:vOptional(vString)}),itemTypeCommandOptionPolicy=vObject({command:vLiteral("create","update"),option:vString,required:vOptional(vBoolean),visible:vOptional(vBoolean),enabled:vOptional(vBoolean)}),itemTypeDefinition=vObject({name:vString,description:vOptional(vString),default_status:vOptional(vString),execution_role:vOptional(vLiteral("agent","human","gate")),folder:vOptional(vString),aliases:vOptional(vArray(vString)),required_create_fields:vOptional(vArray(vString)),required_create_repeatables:vOptional(vArray(vString)),options:vOptional(vArray(itemTypeOption)),command_option_policies:vOptional(vArray(itemTypeCommandOptionPolicy))}),runtimeStatusDefinition=vObject({id:vString,aliases:vOptional(vArray(vString)),roles:vOptional(vArray(vLiteral(...RUNTIME_STATUS_ROLE_VALUES))),description:vOptional(vString),order:vOptional(vNumber())}),runtimeFieldDefinition=vObject({key:vString,metadata_key:vOptional(vString),front_matter_key:vOptional(vString),cli_flag:vOptional(vString),cli_aliases:vOptional(vArray(vString)),description:vOptional(vString),type:vOptional(vLiteral(...RUNTIME_FIELD_TYPE_VALUES)),commands:vOptional(vArray(vLiteral(...RUNTIME_FIELD_COMMAND_VALUES))),repeatable:vOptional(vBoolean),required:vOptional(vBoolean),required_on_create:vOptional(vBoolean),required_types:vOptional(vArray(vString)),allow_unset:vOptional(vBoolean)}),statusTransitionPair=input=>{if(!Array.isArray(input)||input.length!==2)return FAIL;const[from,to]=input;return typeof from!="string"||typeof to!="string"?FAIL:{ok:!0,value:[from,to]}},typeWorkflowDefinition=vObject({type:vString,allowed_transitions:vArray(statusTransitionPair)}),runtimeSchemaSettings=vOptional(vObject({version:vOptional(vNumber({int:!0})),files:vOptional(vObject({types:vOptional(vString),statuses:vOptional(vString),fields:vOptional(vString),workflows:vOptional(vString)})),statuses:vOptional(vArray(runtimeStatusDefinition)),fields:vOptional(vArray(runtimeFieldDefinition)),workflow:vOptional(vObject({draft_status:vOptional(vString),open_status:vOptional(vString),in_progress_status:vOptional(vString),blocked_status:vOptional(vString),close_status:vOptional(vString),canceled_status:vOptional(vString)})),type_workflows:vOptional(vArray(typeWorkflowDefinition)),unknown_field_policy:vOptional(vLiteral(...RUNTIME_UNKNOWN_FIELD_POLICY_VALUES))})),governanceSettings=vOptional(vObject({preset:vOptional(vLiteral(...GOVERNANCE_PRESET_VALUES)),ownership_enforcement:vOptional(vLiteral("none","warn","strict")),create_mode_default:vOptional(vLiteral("progressive","strict")),close_validation_default:vOptional(vLiteral("off","warn","strict")),require_close_reason:vOptional(vBoolean),parent_reference:vOptional(vLiteral("warn","strict_error")),metadata_profile:vOptional(vLiteral("core","strict","custom")),force_required_for_stale_lock:vOptional(vBoolean),create_default_type:vOptional(vString),workflow_enforcement:vOptional(vLiteral("off","warn","strict")),start_blocker_enforcement:vOptional(vLiteral("off","warn","strict")),duplicate_detection_mode:vOptional(vLiteral("off","advisory","strict")),duplicate_detection_threshold:vOptional(vNumber({min:0,max:1})),duplicate_detection_limit:vOptional(vNumber({int:!0,min:0,max:20}))})),extensionPolicyOverride=vObject({name:vString,disabled:vOptional(vBoolean),require_trusted:vOptional(vBoolean),require_provenance:vOptional(vBoolean),sandbox_profile:vOptional(vLiteral("none","restricted","strict")),allowed_capabilities:vOptional(vArray(vString)),blocked_capabilities:vOptional(vArray(vString)),allowed_surfaces:vOptional(vArray(vString)),blocked_surfaces:vOptional(vArray(vString)),allowed_commands:vOptional(vArray(vString)),blocked_commands:vOptional(vArray(vString)),allowed_actions:vOptional(vArray(vString)),blocked_actions:vOptional(vArray(vString)),allowed_services:vOptional(vArray(vString)),blocked_services:vOptional(vArray(vString))}),pmMaxVersionExceededModeLiteral=vLiteral("block","warn"),pmMaxVersionExceededMode=input=>typeof input=="string"?pmMaxVersionExceededModeLiteral(input):vObject({global:vOptional(pmMaxVersionExceededModeLiteral),project:vOptional(pmMaxVersionExceededModeLiteral)})(input),extensionPolicy=vOptional(vObject({mode:vOptional(vLiteral("off","warn","enforce")),trust_mode:vOptional(vLiteral("off","warn","enforce")),pm_max_version_exceeded_mode:vOptional(pmMaxVersionExceededMode),require_provenance:vOptional(vBoolean),trusted_extensions:vOptional(vArray(vString)),default_sandbox_profile:vOptional(vLiteral("none","restricted","strict")),allowed_extensions:vOptional(vArray(vString)),blocked_extensions:vOptional(vArray(vString)),allowed_capabilities:vOptional(vArray(vString)),blocked_capabilities:vOptional(vArray(vString)),allowed_surfaces:vOptional(vArray(vString)),blocked_surfaces:vOptional(vArray(vString)),allowed_commands:vOptional(vArray(vString)),blocked_commands:vOptional(vArray(vString)),allowed_actions:vOptional(vArray(vString)),blocked_actions:vOptional(vArray(vString)),allowed_services:vOptional(vArray(vString)),blocked_services:vOptional(vArray(vString)),extension_overrides:vOptional(vArray(extensionPolicyOverride))})),harnessSignalLiteral=vBoundedNormalizedString(128),harnessSignalDescriptor=vObject({harness:vBoundedNormalizedString(128,/^[a-z0-9]+(?:-[a-z0-9]+)*$/u),environment_keys:vOptional(vArray(harnessSignalLiteral,64)),model_environment_keys:vOptional(vArray(harnessSignalLiteral,64)),session_environment_keys:vOptional(vArray(harnessSignalLiteral,64)),provenance_environment_keys:vOptional(vRecordOf(vArray(harnessSignalLiteral,64))),provenance_resolvers:vOptional(vRecordOf(vLiteral("ai_agent_version","claude_session_file"))),provenance_unavailable_dimensions:vOptional(vArray(harnessSignalLiteral,64)),argv_markers:vOptional(vArray(harnessSignalLiteral,64)),client_names:vOptional(vArray(harnessSignalLiteral,64))}),SETTINGS_SHAPE={version:vNumber({int:!0}),id_prefix:vString,ids:vOptional(vObject({token_length:vOptional(vNumber({int:!0,min:4,max:12}))})),author_default:vString,agent_identity:vOptional(vObject({probes_enabled:vOptional(vBoolean),identity_vocabulary:vOptional(vObject({version:vNumber({int:!0,positive:!0}),aliases:vRecordOf(vBoundedNormalizedString(128,/^[a-z0-9]+(?:-[a-z0-9]+)*$/u))})),harness_signals:vArray(harnessSignalDescriptor)})),mutation_guard:vOptional(vObject({require_attributed_author:vOptional(vBoolean),secret_guard:vOptional(vLiteral("off","advise","block")),stale_in_progress_hours:vOptional(vNumber({int:!0,positive:!0}))})),item_format:vOptional(vLiteral("toon","json_markdown")),locks:vObject({ttl_seconds:vNumber({int:!0}),wait_ms:vOptional(vNumber({int:!0,min:0}))}),checkpoints:vOptional(vObject({retention_days:vOptional(vNumber({int:!0,positive:!0}))})),output:vObject({default_format:vLiteral("toon","json")}),ux:vOptional(vObject({deprecation_hints:vOptional(vBoolean)})),history:vOptional(vObject({missing_stream:vLiteral("auto_create","strict_error"),compact_policy:vOptional(vObject({enabled:vOptional(vBoolean),max_entries:vOptional(vNumber({int:!0,positive:!0})),trigger:vOptional(vLiteral("health_warn","auto"))}))})),validation:vOptional(vObject({sprint_release_format:vLiteral("warn","strict_error"),parent_reference:vOptional(vLiteral("warn","strict_error")),metadata_profile:vOptional(vLiteral("core","strict","custom")),metadata_required_fields:vOptional(vArray(vString)),lifecycle_stale_blocker_reason_patterns:vOptional(vArray(vString)),lifecycle_closure_like_blocked_reason_patterns:vOptional(vArray(vString)),lifecycle_closure_like_resolution_patterns:vOptional(vArray(vString)),lifecycle_closure_like_actual_result_patterns:vOptional(vArray(vString)),estimate_defaults_by_type:vOptional(vRecordOf(vNumber({int:!0,positive:!0})))})),governance:governanceSettings,workflow:vOptional(vObject({definition_of_done:vArray(vString)})),testing:vOptional(vObject({record_results_to_items:vBoolean,allow_untrusted_linked_tests:vOptional(vBoolean)})),telemetry:vOptional(vObject({enabled:vBoolean,first_run_prompt_completed:vOptional(vBoolean),capture_level:vOptional(vLiteral("minimal","redacted","max")),endpoint:vOptional(vString),installation_id:vOptional(vString),retention_days:vOptional(vNumber({int:!0,positive:!0}))})),agent_guidance:vOptional(vObject({prompt_completed:vOptional(vBoolean),declined:vOptional(vBoolean),declined_at:vOptional(vString),template_version:vOptional(vNumber({int:!0,positive:!0})),last_checked_files:vOptional(vArray(vString))})),item_types:vOptional(vObject({definitions:vArray(itemTypeDefinition)})),schema:runtimeSchemaSettings,context:vOptional(vObject({default_depth:vOptional(vLiteral("brief","standard","deep")),activity_limit:vOptional(vNumber({int:!0,positive:!0})),stale_threshold_days:vOptional(vNumber({int:!0,positive:!0})),next_ranking_policy:vOptional(vLiteral("priority_floor","weighted")),sections:vOptional(vObject({hierarchy:vOptional(vBoolean),activity:vOptional(vBoolean),progress:vOptional(vBoolean),recently_created:vOptional(vBoolean),unparented:vOptional(vBoolean),blockers:vOptional(vBoolean),files:vOptional(vBoolean),workload:vOptional(vBoolean),staleness:vOptional(vBoolean),tests:vOptional(vBoolean)}))})),extensions:vObject({enabled:vArray(vString),disabled:vArray(vString),policy:extensionPolicy}),search:vObject({score_threshold:vNumber(),hybrid_semantic_weight:vOptional(vNumber()),max_results:vNumber({int:!0}),embedding_model:vString,embedding_corpus_max_characters:vOptional(vNumber()),embedding_batch_size:vNumber({int:!0}),embedding_timeout_ms:vOptional(vNumber({int:!0})),scanner_max_batch_retries:vNumber({int:!0}),provider:vOptional(vString),default_mode:vOptional(vLiteral("auto","keyword","semantic","hybrid")),corpus_fields:vOptional(vArray(vString)),mutation_refresh_policy:vOptional(vLiteral("cache_only","semantic_configured","semantic_auto")),query_expansion:vOptional(vObject({enabled:vOptional(vBoolean),provider:vOptional(vString)})),rerank:vOptional(vObject({enabled:vOptional(vBoolean),model:vOptional(vString),top_k:vOptional(vNumber({int:!0,positive:!0}))})),bm25:vOptional(vObject({k1:vOptional(vNumber()),b:vOptional(vNumber())}))}),providers:vObject({openai:vObject({base_url:vString,api_key:vString,model:vString}),ollama:vObject({base_url:vString,model:vString})}),vector_store:vObject({adapter:vOptional(vString),collection_name:vOptional(vString),qdrant:vObject({url:vString,api_key:vString}),lancedb:vObject({path:vString})})},settingsCheck=vObject(SETTINGS_SHAPE),CORE_SETTINGS_SECTION_KEYS=Object.freeze(Object.keys(SETTINGS_SHAPE));function validateSettings(raw){const result=settingsCheck(raw);return result.ok?{success:!0,data:result.value}:{success:!1,path:result.path.join(".")}}export{CORE_SETTINGS_SECTION_KEYS,validateSettings};
 //# sourceMappingURL=settings-validator.js.map

package/dist/core/store/settings.d.ts

@@ -127,6 +127,20 @@ export interface WriteSettingsOptions {
      * option (pm-4zpq71).
      */
 assignedPaths?:readonly string[];
+/**
+     * Top-level sections a full write (one without a stored-document snapshot)
+     * leaves out unless the stored document already has them. Snapshot writes
+     * keep the stored shape, so an omitted section stays absent (GH-1660: project
+     * files carry no telemetry block, which only the global profile governs).
+     */
+omitSections?:readonly "telemetry"[];
+/**
+     * Compare-and-set, consulted under the settings lock with the stored
+     * document when one exists. Returning true writes nothing: the file, its
+     * history and the caller's snapshot stay unchanged, so a value another writer
+     * recorded after the caller's read stands (GH-1660).
+     */
+skipIfStored?:(stored:unknown) => boolean;
 }
 /** Implements read settings for the public runtime surface of this module. */
 export declare function readSettings(pmRoot:string):Promise<PmSettings>;