@unbrained/pm-cli 2026.9.8 → 2026.9.9

package/dist/core/config/nested-settings.js

@@ -1,2 +1,2 @@
-!(function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="bdebba4f-e8e4-5171-97d2-099c8d65cdb4")}catch(e2){}})();const NESTED_SETTING_DESCRIPTORS=[{key:"search_provider",path:"search.provider",kind:"string",summary:"Search embedding provider name (e.g. openai, ollama, or an extension provider)."},{key:"search_mutation_refresh_policy",path:"search.mutation_refresh_policy",kind:"string",choices:["cache_only","semantic_configured","semantic_auto"],summary:"Mutation-time search refresh policy: cache_only, semantic_configured, or semantic_auto."},{key:"search_query_expansion_enabled",path:"search.query_expansion.enabled",kind:"boolean",summary:"Enable or disable query expansion for semantic/hybrid search."},{key:"search_query_expansion_provider",path:"search.query_expansion.provider",kind:"string",summary:"Query expansion provider name (built-in openai/ollama or extension provider)."},{key:"search_rerank_enabled",path:"search.rerank.enabled",kind:"boolean",summary:"Enable or disable post-retrieval reranking for hybrid search."},{key:"search_rerank_model",path:"search.rerank.model",kind:"string",summary:"Rerank model name override used by built-in providers."},{key:"search_rerank_top_k",path:"search.rerank.top_k",kind:"integer",min:1,summary:"Number of top hybrid candidates to rerank when rerank is enabled."},{key:"search_embedding_model",path:"search.embedding_model",kind:"string",summary:"Default embedding model name (overrides provider-specific model when set)."},{key:"search_embedding_corpus_max_characters",path:"search.embedding_corpus_max_characters",kind:"integer",min:1,summary:"Maximum semantic corpus characters per item before truncation."},{key:"search_embedding_batch_size",path:"search.embedding_batch_size",kind:"integer",min:1,summary:"Number of items embedded per request batch."},{key:"search_embedding_timeout_ms",path:"search.embedding_timeout_ms",kind:"integer",min:1,summary:"Per-request embedding timeout in milliseconds."},{key:"search_score_threshold",path:"search.score_threshold",kind:"number",summary:"Minimum score for a hit to be returned (0 keeps all matches)."},{key:"search_hybrid_semantic_weight",path:"search.hybrid_semantic_weight",kind:"ratio",summary:"Hybrid mode semantic weight in [0, 1] (1-weight goes to keyword)."},{key:"search_max_results",path:"search.max_results",kind:"integer",min:1,summary:"Default upper bound on search hits when --limit is not supplied."},{key:"search_bm25_k1",path:"search.bm25.k1",kind:"number",min:0,summary:"Offline BM25 term-frequency saturation (k1); higher saturates repeated terms slower (default 1.2)."},{key:"search_bm25_b",path:"search.bm25.b",kind:"ratio",summary:"Offline BM25 document-length normalization (b) in [0, 1]; 0 disables, 1 fully normalizes (default 0.75)."},{key:"openai_base_url",path:"providers.openai.base_url",kind:"string",summary:"OpenAI-compatible API base URL (LM Studio/vLLM also use this)."},{key:"openai_api_key",path:"providers.openai.api_key",kind:"string",summary:"OpenAI-compatible API key."},{key:"openai_model",path:"providers.openai.model",kind:"string",summary:"OpenAI-compatible embedding model name."},{key:"ollama_base_url",path:"providers.ollama.base_url",kind:"string",summary:"Ollama API base URL (typically http://localhost:11434)."},{key:"ollama_model",path:"providers.ollama.model",kind:"string",summary:"Ollama embedding model name (e.g. nomic-embed-text)."},{key:"vector_store_adapter",path:"vector_store.adapter",kind:"string",summary:"Vector store adapter name (lancedb, qdrant, or an extension adapter)."},{key:"vector_store_collection_name",path:"vector_store.collection_name",kind:"string",non_empty:true,summary:"Vector collection/table name shared by Qdrant and LanceDB adapters."},{key:"qdrant_url",path:"vector_store.qdrant.url",kind:"string",summary:"Qdrant HTTP API URL."},{key:"qdrant_api_key",path:"vector_store.qdrant.api_key",kind:"string",summary:"Qdrant API key (empty if running unauthenticated)."},{key:"lancedb_path",path:"vector_store.lancedb.path",kind:"string",summary:"LanceDB storage path (relative to pm root or absolute)."},{key:"id_prefix",path:"id_prefix",kind:"string",non_empty:true,summary:'Prefix for generated item IDs (e.g. "pm" produces pm-xxxx).'},{key:"author_default",path:"author_default",kind:"string",non_empty:true,summary:"Default author recorded on mutations when --author is not supplied."},{key:"agent_identity_probes_enabled",path:"agent_identity.probes_enabled",kind:"boolean",summary:"Allow privacy-bounded local harness provenance probes; no network or subprocess access is permitted."},{key:"mutation_guard_require_attributed_author",path:"mutation_guard.require_attributed_author",kind:"boolean",summary:"Reject mutations whose effective author resolves to unknown."},{key:"mutation_guard_secret_guard",path:"mutation_guard.secret_guard",kind:"string",choices:["off","advise","block"],summary:"Detect credential-shaped mutation content: off, advise, or block."},{key:"mutation_guard_stale_in_progress_hours",path:"mutation_guard.stale_in_progress_hours",kind:"integer",min:1,summary:"Age threshold for unclaimed in-progress work surfaced by health."},{key:"governance_duplicate_detection_mode",path:"governance.duplicate_detection_mode",kind:"string",choices:["off","advisory","strict"],summary:"Create/copy duplicate governance: off, advisory, or strict explicit-bypass enforcement."},{key:"governance_duplicate_detection_threshold",path:"governance.duplicate_detection_threshold",kind:"ratio",summary:"Minimum shared similarity score in [0, 1] for create/copy duplicate governance."},{key:"governance_duplicate_detection_limit",path:"governance.duplicate_detection_limit",kind:"integer",min:0,max:20,summary:"Maximum likely duplicates returned by create/copy governance (0-20)."},{key:"output_default_format",path:"output.default_format",kind:"string",choices:["toon","json"],summary:"Default output format for commands that support it: toon or json."},{key:"ux_deprecation_hints",path:"ux.deprecation_hints",kind:"boolean",summary:"Emit one stderr migration hint for deprecated command aliases."},{key:"locks_ttl_seconds",path:"locks.ttl_seconds",kind:"integer",min:1,summary:"Claim/lock time-to-live in seconds before a stale lock can be reclaimed."},{key:"locks_wait_ms",path:"locks.wait_ms",kind:"integer",min:0,summary:"Bounded jittered wait in milliseconds before a contended item mutation fails with lock_conflict; 0 fails fast. PM_LOCK_WAIT_MS overrides per invocation."},{key:"ids_token_length",path:"ids.token_length",kind:"integer",min:4,max:12,summary:"Random base36 token length for newly minted item ids (4-12, default 4). Raise it to shrink cross-branch id collision odds in concurrent multi-agent workflows (pm-pibw)."},{key:"checkpoints_retention_days",path:"checkpoints.retention_days",kind:"integer",min:1,summary:"Age in days above which pm gc --scope checkpoints prunes bulk-mutation rollback checkpoints."},{key:"schema_unknown_field_policy",path:"schema.unknown_field_policy",kind:"string",choices:["allow","warn","reject"],summary:"How item I/O handles metadata keys not in the field registry: allow, warn, or reject."},{key:"history_compact_policy_enabled",path:"history.compact_policy.enabled",kind:"boolean",summary:"Enable the history-compaction advisory: pm health warns on over-threshold streams."},{key:"history_compact_policy_max_entries",path:"history.compact_policy.max_entries",kind:"integer",min:1,summary:"Entry count above which a history stream is flagged (and the default pm history-compact --all-over threshold)."},{key:"history_compact_policy_trigger",path:"history.compact_policy.trigger",kind:"string",choices:["health_warn","auto"],summary:"History-compaction policy intent: health_warn (advisory only) or auto (scheduled sweeps expected)."}];const DESCRIPTOR_BY_KEY=new Map(NESTED_SETTING_DESCRIPTORS.flatMap(descriptor=>[[descriptor.key,descriptor],[descriptor.path.toLowerCase().replaceAll("-","_"),descriptor]]));function resolveNestedSettingDescriptor(raw){if(typeof raw!=="string"){return void 0}const normalized=raw.trim().toLowerCase().replaceAll("-","_");if(normalized.length===0){return void 0}return DESCRIPTOR_BY_KEY.get(normalized)}function parseNestedBooleanValue(descriptor,rawValue){const normalized=rawValue.trim().toLowerCase();if(normalized==="true"||normalized==="1"||normalized==="yes"||normalized==="on"){return{ok:true,parsed:{descriptor,value:true}}}if(normalized==="false"||normalized==="0"||normalized==="no"||normalized==="off"){return{ok:true,parsed:{descriptor,value:false}}}return{ok:false,error:{message:`Config set ${descriptor.key} requires a boolean value (true|false), got "${rawValue}"`}}}function parseNestedStringValue(descriptor,rawValue,trimmed){if(descriptor.non_empty===true&&trimmed.length===0){return{ok:false,error:{message:`Config set ${descriptor.key} requires a non-empty value`}}}if(descriptor.choices&&!descriptor.choices.includes(trimmed)){return{ok:false,error:{message:`Config set ${descriptor.key} must be one of ${descriptor.choices.join("|")}, got "${rawValue}"`}}}return{ok:true,parsed:{descriptor,value:trimmed}}}function parseFiniteNestedNumber(descriptor,rawValue,trimmed){if(trimmed.length===0){return{ok:false,error:{message:`Config set ${descriptor.key} requires a non-empty value`}}}const parsed=Number(trimmed);if(!Number.isFinite(parsed)){return{ok:false,error:{message:`Config set ${descriptor.key} requires a finite number, got "${rawValue}"`}}}return{ok:true,value:parsed}}function parseNestedIntegerValue(descriptor,rawValue,value){if(!Number.isInteger(value)||value<0){return{ok:false,error:{message:`Config set ${descriptor.key} requires a non-negative integer, got "${rawValue}"`}}}if(descriptor.min!==void 0&&value<descriptor.min){return{ok:false,error:{message:`Config set ${descriptor.key} requires an integer >= ${descriptor.min}, got "${rawValue}" (the runtime silently ignores 0 here and falls back to the default)`}}}if(descriptor.max!==void 0&&value>descriptor.max){return{ok:false,error:{message:`Config set ${descriptor.key} requires an integer <= ${descriptor.max}, got "${rawValue}"`}}}return{ok:true,parsed:{descriptor,value}}}function parseNestedRatioValue(descriptor,rawValue,value){if(value<0||value>1){return{ok:false,error:{message:`Config set ${descriptor.key} requires a number in [0, 1], got "${rawValue}"`}}}return{ok:true,parsed:{descriptor,value}}}function parseNestedNumberValue(descriptor,rawValue,value){if(descriptor.min!==void 0&&value<descriptor.min){return{ok:false,error:{message:`Config set ${descriptor.key} requires a number >= ${descriptor.min}, got "${rawValue}"`}}}return{ok:true,parsed:{descriptor,value}}}function parseNestedSettingValue(descriptor,rawValue){if(typeof rawValue!=="string"){return{ok:false,error:{message:`Config set ${descriptor.key} requires a string value`}}}const trimmed=rawValue.trim();if(descriptor.kind==="boolean"){return parseNestedBooleanValue(descriptor,rawValue)}if(descriptor.kind==="string"){return parseNestedStringValue(descriptor,rawValue,trimmed)}const parsed=parseFiniteNestedNumber(descriptor,rawValue,trimmed);if(!parsed.ok){return{ok:false,error:parsed.error}}if(descriptor.kind==="integer"){return parseNestedIntegerValue(descriptor,rawValue,parsed.value)}if(descriptor.kind==="ratio"){return parseNestedRatioValue(descriptor,rawValue,parsed.value)}return parseNestedNumberValue(descriptor,rawValue,parsed.value)}function readNestedSettingValue(settings,descriptor){const segments=descriptor.path.split(".");let cursor=settings;for(const segment of segments){if(typeof cursor!=="object"||cursor===null){return null}cursor=cursor[segment]}if(typeof cursor==="string"||typeof cursor==="number"||typeof cursor==="boolean"){return cursor}return null}function writeNestedSettingValue(settings,descriptor,value){const segments=descriptor.path.split(".");let cursor=settings;for(let index=0;index<segments.length-1;index+=1){const segment=segments[index];const existing=cursor[segment];if(typeof existing!=="object"||existing===null||Array.isArray(existing)){const next={};cursor[segment]=next;cursor=next}else{cursor=existing}}const leafKey=segments[segments.length-1];const previous=cursor[leafKey];if(previous===value){return false}cursor[leafKey]=value;return true}export{NESTED_SETTING_DESCRIPTORS,parseNestedSettingValue,readNestedSettingValue,resolveNestedSettingDescriptor,writeNestedSettingValue};
+!(function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="ae6d96af-b482-5238-af32-20bb7c3753cb")}catch(e2){}})();const NESTED_SETTING_DESCRIPTORS=[{key:"search_provider",path:"search.provider",kind:"string",summary:"Search embedding provider name (e.g. openai, ollama, or an extension provider)."},{key:"search_default_mode",path:"search.default_mode",kind:"string",choices:["auto","keyword","semantic","hybrid"],summary:"Mode a bare pm search runs in: auto (hybrid when semantic search is explicitly configured and runnable, else keyword), or a pinned keyword, semantic, or hybrid."},{key:"search_mutation_refresh_policy",path:"search.mutation_refresh_policy",kind:"string",choices:["cache_only","semantic_configured","semantic_auto"],summary:"Mutation-time search refresh policy: cache_only, semantic_configured, or semantic_auto."},{key:"search_query_expansion_enabled",path:"search.query_expansion.enabled",kind:"boolean",summary:"Enable or disable query expansion for semantic/hybrid search."},{key:"search_query_expansion_provider",path:"search.query_expansion.provider",kind:"string",summary:"Query expansion provider name (built-in openai/ollama or extension provider)."},{key:"search_rerank_enabled",path:"search.rerank.enabled",kind:"boolean",summary:"Enable or disable post-retrieval reranking for hybrid search."},{key:"search_rerank_model",path:"search.rerank.model",kind:"string",summary:"Rerank model name override used by built-in providers."},{key:"search_rerank_top_k",path:"search.rerank.top_k",kind:"integer",min:1,summary:"Number of top hybrid candidates to rerank when rerank is enabled."},{key:"search_embedding_model",path:"search.embedding_model",kind:"string",summary:"Default embedding model name (overrides provider-specific model when set)."},{key:"search_embedding_corpus_max_characters",path:"search.embedding_corpus_max_characters",kind:"integer",min:1,summary:"Maximum semantic corpus characters per item before truncation."},{key:"search_embedding_batch_size",path:"search.embedding_batch_size",kind:"integer",min:1,summary:"Number of items embedded per request batch."},{key:"search_embedding_timeout_ms",path:"search.embedding_timeout_ms",kind:"integer",min:1,summary:"Per-request embedding timeout in milliseconds."},{key:"search_score_threshold",path:"search.score_threshold",kind:"number",summary:"Minimum score for a hit to be returned (0 keeps all matches)."},{key:"search_hybrid_semantic_weight",path:"search.hybrid_semantic_weight",kind:"ratio",summary:"Hybrid mode semantic weight in [0, 1] (1-weight goes to keyword)."},{key:"search_max_results",path:"search.max_results",kind:"integer",min:1,summary:"Default upper bound on search hits when --limit is not supplied."},{key:"search_bm25_k1",path:"search.bm25.k1",kind:"number",min:0,summary:"Offline BM25 term-frequency saturation (k1); higher saturates repeated terms slower (default 1.2)."},{key:"search_bm25_b",path:"search.bm25.b",kind:"ratio",summary:"Offline BM25 document-length normalization (b) in [0, 1]; 0 disables, 1 fully normalizes (default 0.75)."},{key:"openai_base_url",path:"providers.openai.base_url",kind:"string",summary:"OpenAI-compatible API base URL (LM Studio/vLLM also use this)."},{key:"openai_api_key",path:"providers.openai.api_key",kind:"string",summary:"OpenAI-compatible API key."},{key:"openai_model",path:"providers.openai.model",kind:"string",summary:"OpenAI-compatible embedding model name."},{key:"ollama_base_url",path:"providers.ollama.base_url",kind:"string",summary:"Ollama API base URL (typically http://localhost:11434)."},{key:"ollama_model",path:"providers.ollama.model",kind:"string",summary:"Ollama embedding model name (e.g. nomic-embed-text)."},{key:"vector_store_adapter",path:"vector_store.adapter",kind:"string",summary:"Vector store adapter name (lancedb, qdrant, or an extension adapter)."},{key:"vector_store_collection_name",path:"vector_store.collection_name",kind:"string",non_empty:true,summary:"Vector collection/table name shared by Qdrant and LanceDB adapters."},{key:"qdrant_url",path:"vector_store.qdrant.url",kind:"string",summary:"Qdrant HTTP API URL."},{key:"qdrant_api_key",path:"vector_store.qdrant.api_key",kind:"string",summary:"Qdrant API key (empty if running unauthenticated)."},{key:"lancedb_path",path:"vector_store.lancedb.path",kind:"string",summary:"LanceDB storage path (relative to pm root or absolute)."},{key:"id_prefix",path:"id_prefix",kind:"string",non_empty:true,summary:'Prefix for generated item IDs (e.g. "pm" produces pm-xxxx).'},{key:"author_default",path:"author_default",kind:"string",non_empty:true,summary:"Default author recorded on mutations when --author is not supplied."},{key:"agent_identity_probes_enabled",path:"agent_identity.probes_enabled",kind:"boolean",summary:"Allow privacy-bounded local harness provenance probes; no network or subprocess access is permitted."},{key:"mutation_guard_require_attributed_author",path:"mutation_guard.require_attributed_author",kind:"boolean",summary:"Reject mutations whose effective author resolves to unknown."},{key:"mutation_guard_secret_guard",path:"mutation_guard.secret_guard",kind:"string",choices:["off","advise","block"],summary:"Detect credential-shaped mutation content: off, advise, or block."},{key:"mutation_guard_stale_in_progress_hours",path:"mutation_guard.stale_in_progress_hours",kind:"integer",min:1,summary:"Age threshold for unclaimed in-progress work surfaced by health."},{key:"governance_duplicate_detection_mode",path:"governance.duplicate_detection_mode",kind:"string",choices:["off","advisory","strict"],summary:"Create/copy duplicate governance: off, advisory, or strict explicit-bypass enforcement."},{key:"governance_duplicate_detection_threshold",path:"governance.duplicate_detection_threshold",kind:"ratio",summary:"Minimum shared similarity score in [0, 1] for create/copy duplicate governance."},{key:"governance_duplicate_detection_limit",path:"governance.duplicate_detection_limit",kind:"integer",min:0,max:20,summary:"Maximum likely duplicates returned by create/copy governance (0-20)."},{key:"output_default_format",path:"output.default_format",kind:"string",choices:["toon","json"],summary:"Default output format for commands that support it: toon or json."},{key:"ux_deprecation_hints",path:"ux.deprecation_hints",kind:"boolean",summary:"Emit one stderr migration hint for deprecated command aliases."},{key:"locks_ttl_seconds",path:"locks.ttl_seconds",kind:"integer",min:1,summary:"Claim/lock time-to-live in seconds before a stale lock can be reclaimed."},{key:"locks_wait_ms",path:"locks.wait_ms",kind:"integer",min:0,summary:"Bounded jittered wait in milliseconds before a contended item mutation fails with lock_conflict; 0 fails fast. PM_LOCK_WAIT_MS overrides per invocation."},{key:"ids_token_length",path:"ids.token_length",kind:"integer",min:4,max:12,summary:"Random base36 token length for newly minted item ids (4-12, default 4). Raise it to shrink cross-branch id collision odds in concurrent multi-agent workflows (pm-pibw)."},{key:"checkpoints_retention_days",path:"checkpoints.retention_days",kind:"integer",min:1,summary:"Age in days above which pm gc --scope checkpoints prunes bulk-mutation rollback checkpoints."},{key:"schema_unknown_field_policy",path:"schema.unknown_field_policy",kind:"string",choices:["allow","warn","reject"],summary:"How item I/O handles metadata keys not in the field registry: allow, warn, or reject."},{key:"history_compact_policy_enabled",path:"history.compact_policy.enabled",kind:"boolean",summary:"Enable the history-compaction advisory: pm health warns on over-threshold streams."},{key:"history_compact_policy_max_entries",path:"history.compact_policy.max_entries",kind:"integer",min:1,summary:"Entry count above which a history stream is flagged (and the default pm history-compact --all-over threshold)."},{key:"history_compact_policy_trigger",path:"history.compact_policy.trigger",kind:"string",choices:["health_warn","auto"],summary:"History-compaction policy intent: health_warn (advisory only) or auto (scheduled sweeps expected)."}];const DESCRIPTOR_BY_KEY=new Map(NESTED_SETTING_DESCRIPTORS.flatMap(descriptor=>[[descriptor.key,descriptor],[descriptor.path.toLowerCase().replaceAll("-","_"),descriptor]]));function resolveNestedSettingDescriptor(raw){if(typeof raw!=="string"){return void 0}const normalized=raw.trim().toLowerCase().replaceAll("-","_");if(normalized.length===0){return void 0}return DESCRIPTOR_BY_KEY.get(normalized)}function parseNestedBooleanValue(descriptor,rawValue){const normalized=rawValue.trim().toLowerCase();if(normalized==="true"||normalized==="1"||normalized==="yes"||normalized==="on"){return{ok:true,parsed:{descriptor,value:true}}}if(normalized==="false"||normalized==="0"||normalized==="no"||normalized==="off"){return{ok:true,parsed:{descriptor,value:false}}}return{ok:false,error:{message:`Config set ${descriptor.key} requires a boolean value (true|false), got "${rawValue}"`}}}function parseNestedStringValue(descriptor,rawValue,trimmed){if(descriptor.non_empty===true&&trimmed.length===0){return{ok:false,error:{message:`Config set ${descriptor.key} requires a non-empty value`}}}if(descriptor.choices&&!descriptor.choices.includes(trimmed)){return{ok:false,error:{message:`Config set ${descriptor.key} must be one of ${descriptor.choices.join("|")}, got "${rawValue}"`}}}return{ok:true,parsed:{descriptor,value:trimmed}}}function parseFiniteNestedNumber(descriptor,rawValue,trimmed){if(trimmed.length===0){return{ok:false,error:{message:`Config set ${descriptor.key} requires a non-empty value`}}}const parsed=Number(trimmed);if(!Number.isFinite(parsed)){return{ok:false,error:{message:`Config set ${descriptor.key} requires a finite number, got "${rawValue}"`}}}return{ok:true,value:parsed}}function parseNestedIntegerValue(descriptor,rawValue,value){if(!Number.isInteger(value)||value<0){return{ok:false,error:{message:`Config set ${descriptor.key} requires a non-negative integer, got "${rawValue}"`}}}if(descriptor.min!==void 0&&value<descriptor.min){return{ok:false,error:{message:`Config set ${descriptor.key} requires an integer >= ${descriptor.min}, got "${rawValue}" (the runtime silently ignores 0 here and falls back to the default)`}}}if(descriptor.max!==void 0&&value>descriptor.max){return{ok:false,error:{message:`Config set ${descriptor.key} requires an integer <= ${descriptor.max}, got "${rawValue}"`}}}return{ok:true,parsed:{descriptor,value}}}function parseNestedRatioValue(descriptor,rawValue,value){if(value<0||value>1){return{ok:false,error:{message:`Config set ${descriptor.key} requires a number in [0, 1], got "${rawValue}"`}}}return{ok:true,parsed:{descriptor,value}}}function parseNestedNumberValue(descriptor,rawValue,value){if(descriptor.min!==void 0&&value<descriptor.min){return{ok:false,error:{message:`Config set ${descriptor.key} requires a number >= ${descriptor.min}, got "${rawValue}"`}}}return{ok:true,parsed:{descriptor,value}}}function parseNestedSettingValue(descriptor,rawValue){if(typeof rawValue!=="string"){return{ok:false,error:{message:`Config set ${descriptor.key} requires a string value`}}}const trimmed=rawValue.trim();if(descriptor.kind==="boolean"){return parseNestedBooleanValue(descriptor,rawValue)}if(descriptor.kind==="string"){return parseNestedStringValue(descriptor,rawValue,trimmed)}const parsed=parseFiniteNestedNumber(descriptor,rawValue,trimmed);if(!parsed.ok){return{ok:false,error:parsed.error}}if(descriptor.kind==="integer"){return parseNestedIntegerValue(descriptor,rawValue,parsed.value)}if(descriptor.kind==="ratio"){return parseNestedRatioValue(descriptor,rawValue,parsed.value)}return parseNestedNumberValue(descriptor,rawValue,parsed.value)}function readNestedSettingValue(settings,descriptor){const segments=descriptor.path.split(".");let cursor=settings;for(const segment of segments){if(typeof cursor!=="object"||cursor===null){return null}cursor=cursor[segment]}if(typeof cursor==="string"||typeof cursor==="number"||typeof cursor==="boolean"){return cursor}return null}function writeNestedSettingValue(settings,descriptor,value){const segments=descriptor.path.split(".");let cursor=settings;for(let index=0;index<segments.length-1;index+=1){const segment=segments[index];const existing=cursor[segment];if(typeof existing!=="object"||existing===null||Array.isArray(existing)){const next={};cursor[segment]=next;cursor=next}else{cursor=existing}}const leafKey=segments[segments.length-1];const previous=cursor[leafKey];if(previous===value){return false}cursor[leafKey]=value;return true}export{NESTED_SETTING_DESCRIPTORS,parseNestedSettingValue,readNestedSettingValue,resolveNestedSettingDescriptor,writeNestedSettingValue};
 //# sourceMappingURL=nested-settings.js.map

package/dist/core/policy/workflow-policy-schema.d.ts

@@ -0,0 +1,312 @@
+/** JSON Schema for a single workflow policy, usable by package authoring tools. */
+export declare const WORKFLOW_POLICY_SCHEMA: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["id", "rule"];
+    readonly properties: {
+        readonly id: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly maxLength: 128;
+            readonly pattern: "^[a-zA-Z0-9][a-zA-Z0-9._-]*$";
+        };
+        readonly description: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly maxLength: 500;
+            readonly pattern: "\\S";
+        };
+        readonly effect: {
+            readonly enum: readonly ["advise", "warn", "refuse"];
+        };
+        readonly subject: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly dependency: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly required: readonly ["kind"];
+                    readonly properties: {
+                        readonly kind: {
+                            type: string;
+                            minLength: number;
+                            maxLength: number;
+                            pattern: string;
+                        };
+                        readonly id: {
+                            type: string;
+                            minLength: number;
+                            maxLength: number;
+                            pattern: string;
+                        };
+                    };
+                };
+            };
+        };
+        readonly rule: {
+            readonly oneOf: readonly [{
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["kind", "fields"];
+                readonly properties: {
+                    readonly kind: {
+                        readonly const: "require_fields";
+                    };
+                    readonly fields: {
+                        items: {
+                            pattern: string;
+                            type: string;
+                            minLength: number;
+                            maxLength: number;
+                        };
+                        type: string;
+                        minItems: number;
+                        maxItems: number;
+                    };
+                };
+            }, {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["kind", "authors"];
+                readonly properties: {
+                    readonly kind: {
+                        readonly const: "authors";
+                    };
+                    readonly authors: {
+                        type: string;
+                        minItems: number;
+                        maxItems: number;
+                        items: {
+                            type: string;
+                            minLength: number;
+                            maxLength: number;
+                            pattern: string;
+                        };
+                    };
+                };
+            }, ...{
+                type: string;
+                additionalProperties: boolean;
+                required: string[];
+                properties: {
+                    kind: {
+                        const: string;
+                    };
+                    fields: {
+                        items: {
+                            pattern: string;
+                            type: string;
+                            minLength: number;
+                            maxLength: number;
+                        };
+                        type: string;
+                        minItems: number;
+                        maxItems: number;
+                    };
+                    authors: {
+                        type: string;
+                        minItems: number;
+                        maxItems: number;
+                        items: {
+                            type: string;
+                            minLength: number;
+                            maxLength: number;
+                            pattern: string;
+                        };
+                    };
+                };
+            }[], {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["kind", "allowed"];
+                readonly properties: {
+                    readonly kind: {
+                        readonly const: "transition";
+                    };
+                    readonly allowed: {
+                        readonly type: "array";
+                        readonly maxItems: 64;
+                        readonly items: {
+                            readonly type: "array";
+                            readonly minItems: 2;
+                            readonly maxItems: 2;
+                            readonly items: {
+                                type: string;
+                                minLength: number;
+                                maxLength: number;
+                                pattern: string;
+                            };
+                        };
+                    };
+                };
+            }];
+        };
+    };
+};
+/** Versioned document schema exported with the SDK so consumers can validate policy files offline. */
+export declare const WORKFLOW_POLICY_DOCUMENT_SCHEMA: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly title: "pm workflow policy registry";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["version", "policies"];
+    readonly properties: {
+        readonly version: {
+            readonly const: 1;
+        };
+        readonly enforcement: {
+            readonly enum: readonly ["advise", "refuse"];
+            readonly default: "advise";
+        };
+        readonly policies: {
+            readonly type: "array";
+            readonly maxItems: 256;
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["id", "rule"];
+                readonly properties: {
+                    readonly id: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly maxLength: 128;
+                        readonly pattern: "^[a-zA-Z0-9][a-zA-Z0-9._-]*$";
+                    };
+                    readonly description: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly maxLength: 500;
+                        readonly pattern: "\\S";
+                    };
+                    readonly effect: {
+                        readonly enum: readonly ["advise", "warn", "refuse"];
+                    };
+                    readonly subject: {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly properties: {
+                            readonly dependency: {
+                                readonly type: "object";
+                                readonly additionalProperties: false;
+                                readonly required: readonly ["kind"];
+                                readonly properties: {
+                                    readonly kind: {
+                                        type: string;
+                                        minLength: number;
+                                        maxLength: number;
+                                        pattern: string;
+                                    };
+                                    readonly id: {
+                                        type: string;
+                                        minLength: number;
+                                        maxLength: number;
+                                        pattern: string;
+                                    };
+                                };
+                            };
+                        };
+                    };
+                    readonly rule: {
+                        readonly oneOf: readonly [{
+                            readonly type: "object";
+                            readonly additionalProperties: false;
+                            readonly required: readonly ["kind", "fields"];
+                            readonly properties: {
+                                readonly kind: {
+                                    readonly const: "require_fields";
+                                };
+                                readonly fields: {
+                                    items: {
+                                        pattern: string;
+                                        type: string;
+                                        minLength: number;
+                                        maxLength: number;
+                                    };
+                                    type: string;
+                                    minItems: number;
+                                    maxItems: number;
+                                };
+                            };
+                        }, {
+                            readonly type: "object";
+                            readonly additionalProperties: false;
+                            readonly required: readonly ["kind", "authors"];
+                            readonly properties: {
+                                readonly kind: {
+                                    readonly const: "authors";
+                                };
+                                readonly authors: {
+                                    type: string;
+                                    minItems: number;
+                                    maxItems: number;
+                                    items: {
+                                        type: string;
+                                        minLength: number;
+                                        maxLength: number;
+                                        pattern: string;
+                                    };
+                                };
+                            };
+                        }, ...{
+                            type: string;
+                            additionalProperties: boolean;
+                            required: string[];
+                            properties: {
+                                kind: {
+                                    const: string;
+                                };
+                                fields: {
+                                    items: {
+                                        pattern: string;
+                                        type: string;
+                                        minLength: number;
+                                        maxLength: number;
+                                    };
+                                    type: string;
+                                    minItems: number;
+                                    maxItems: number;
+                                };
+                                authors: {
+                                    type: string;
+                                    minItems: number;
+                                    maxItems: number;
+                                    items: {
+                                        type: string;
+                                        minLength: number;
+                                        maxLength: number;
+                                        pattern: string;
+                                    };
+                                };
+                            };
+                        }[], {
+                            readonly type: "object";
+                            readonly additionalProperties: false;
+                            readonly required: readonly ["kind", "allowed"];
+                            readonly properties: {
+                                readonly kind: {
+                                    readonly const: "transition";
+                                };
+                                readonly allowed: {
+                                    readonly type: "array";
+                                    readonly maxItems: 64;
+                                    readonly items: {
+                                        readonly type: "array";
+                                        readonly minItems: 2;
+                                        readonly maxItems: 2;
+                                        readonly items: {
+                                            type: string;
+                                            minLength: number;
+                                            maxLength: number;
+                                            pattern: string;
+                                        };
+                                    };
+                                };
+                            };
+                        }];
+                    };
+                };
+            };
+        };
+    };
+};

package/dist/core/policy/workflow-policy-schema.js

@@ -0,0 +1,2 @@
+!(function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="0daf7c89-abc5-5c35-ba3f-9772a50408c0")}catch(e2){}})();import{MAX_WORKFLOW_POLICIES,MAX_WORKFLOW_POLICY_TERMS}from"./workflow-policy.js";const text={type:"string",minLength:1,maxLength:128,pattern:"\\S"};const terms={type:"array",minItems:1,maxItems:MAX_WORKFLOW_POLICY_TERMS,items:text};const fields={...terms,items:{...text,pattern:"^(?!(?:.*\\.)?(?:__proto__|constructor|prototype)(?:\\.|$))[a-zA-Z_][a-zA-Z0-9_]*(?:\\.[a-zA-Z_][a-zA-Z0-9_]*){0,7}$"}};const WORKFLOW_POLICY_SCHEMA={type:"object",additionalProperties:false,required:["id","rule"],properties:{id:{type:"string",minLength:1,maxLength:128,pattern:"^[a-zA-Z0-9][a-zA-Z0-9._-]*$"},description:{type:"string",minLength:1,maxLength:500,pattern:"\\S"},effect:{enum:["advise","warn","refuse"]},subject:{type:"object",additionalProperties:false,properties:{...Object.fromEntries(["types","tags","statuses","operations","parents"].map(key=>[key,terms])),dependency:{type:"object",additionalProperties:false,required:["kind"],properties:{kind:text,id:text}}}},rule:{oneOf:[{type:"object",additionalProperties:false,required:["kind","fields"],properties:{kind:{const:"require_fields"},fields}},{type:"object",additionalProperties:false,required:["kind","authors"],properties:{kind:{const:"authors"},authors:terms}},...["field_writers","approval"].map(kind=>({type:"object",additionalProperties:false,required:["kind","fields","authors"],properties:{kind:{const:kind},fields,authors:terms}})),{type:"object",additionalProperties:false,required:["kind","allowed"],properties:{kind:{const:"transition"},allowed:{type:"array",maxItems:MAX_WORKFLOW_POLICY_TERMS,items:{type:"array",minItems:2,maxItems:2,items:text}}}}]}}};const WORKFLOW_POLICY_DOCUMENT_SCHEMA={$schema:"https://json-schema.org/draft/2020-12/schema",title:"pm workflow policy registry",type:"object",additionalProperties:false,required:["version","policies"],properties:{version:{const:1},enforcement:{enum:["advise","refuse"],default:"advise"},policies:{type:"array",maxItems:MAX_WORKFLOW_POLICIES,items:WORKFLOW_POLICY_SCHEMA}}};export{WORKFLOW_POLICY_DOCUMENT_SCHEMA,WORKFLOW_POLICY_SCHEMA};
+//# sourceMappingURL=workflow-policy-schema.js.map

package/dist/core/policy/workflow-policy-store.d.ts

@@ -0,0 +1,24 @@
+import type { ItemDocument, PmSettings } from "../../types/index.js";
+import { type WorkflowPolicyApproval, type WorkflowPolicyDocument, type WorkflowPolicyEvaluation, type WorkflowPolicyInput } from "./workflow-policy.js";
+/** Policy files are bounded independently from item or history corpus size. */
+export declare const MAX_WORKFLOW_POLICY_BYTES = 1048576;
+/** Maximum immutable evidence read for an approval-dependent transition. */
+export declare const MAX_WORKFLOW_APPROVAL_HISTORY_BYTES = 4194304;
+/** Decode a complete policy file; only an absent file means no configured policy. */
+export declare function decodeWorkflowPolicyDocument(raw: string | null): WorkflowPolicyDocument;
+/** Load the latest atomic registry snapshot; absent workspaces have no implicit enforcement. */
+export declare function readWorkflowPolicies(pmRoot: string): Promise<WorkflowPolicyDocument>;
+/** Read only verified approval entries and bind their actor to the actual history envelope. */
+export declare function readWorkflowApprovals(pmRoot: string, id: string): Promise<WorkflowPolicyApproval[]>;
+/** Evaluate a workspace snapshot, reading history only for applicable status-changing approvals. */
+export declare function evaluateWorkspacePolicies(pmRoot: string, document: WorkflowPolicyDocument, input: WorkflowPolicyInput): Promise<WorkflowPolicyEvaluation>;
+/** Enforce policy under the caller's item lock, returning evidence for the same history transaction. */
+export declare function enforceWorkflowMutation(params: {
+    pmRoot: string;
+    settings: PmSettings;
+    operation: string;
+    author: string;
+    before: ItemDocument | null;
+    after: ItemDocument | null;
+    dryRun?: boolean;
+}): Promise<WorkflowPolicyEvaluation>;

package/dist/core/policy/workflow-policy-store.js

@@ -0,0 +1,2 @@
+!(function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="3635d0ca-b4ee-5c99-9115-6eace5120147")}catch(e2){}})();import fs from"node:fs/promises";import path from"node:path";import{isUtf8}from"node:buffer";import{isFileMissingError}from"../fs/fs-utils.js";import{appendWorkspaceAuditEvent}from"../history/workspace-history.js";import{verifyHistoryChain}from"../history/replay.js";import{PmCliError}from"../shared/errors.js";import{EXIT_CODE}from"../shared/constants.js";import{getHistoryPath}from"../store/paths.js";import{evaluateWorkflowPolicies,parseWorkflowPolicyDocument,workflowPolicyApplies}from"./workflow-policy.js";const MAX_WORKFLOW_POLICY_BYTES=1048576;const MAX_WORKFLOW_APPROVAL_HISTORY_BYTES=4194304;async function readBoundedPolicyFile(file,maxBytes){let ancestor=path.dirname(file);while(ancestor!==path.parse(file).root){const stats=await fs.stat(ancestor).catch(error=>{if(isFileMissingError(error))return null;throw error});if(stats!==null){if(!stats.isDirectory())throw new PmCliError("Workflow policy storage ancestor must be a directory.",EXIT_CODE.CONFLICT,{code:"workflow_policy_input_unreadable",nextSteps:["Restore the policy or approval history directory before retrying."]});break}ancestor=path.dirname(ancestor)}const handle=await fs.open(file,"r").catch(error=>{if(isFileMissingError(error))return null;throw error});if(handle===null)return null;try{const size=(await handle.stat()).size;const buffer=Buffer.alloc(Math.min(maxBytes,size)+1);let offset=0;while(offset<buffer.length){const read=await handle.read(buffer,offset,buffer.length-offset,offset);if(read.bytesRead===0)break;offset+=read.bytesRead}if(offset===buffer.length||!isUtf8(buffer.subarray(0,offset))){throw new PmCliError("Workflow policy input exceeds its byte bound or is not valid UTF-8.",EXIT_CODE.CONFLICT,{code:"workflow_policy_input_unreadable",nextSteps:["Inspect the policy and approval history; reduce the declaration or use verified history compaction before retrying."]})}return buffer.toString("utf8",0,offset)}finally{await handle.close()}}function decodeWorkflowPolicyDocument(raw){if(raw===null)return{version:1,enforcement:"advise",policies:[]};let value;try{value=JSON.parse(raw)}catch{throw new PmCliError("schema/policies.json must contain valid JSON.",EXIT_CODE.CONFLICT,{code:"workflow_policy_registry_invalid",nextSteps:["Restore valid policy JSON before retrying the mutation."]})}return parseWorkflowPolicyDocument(value)}async function readWorkflowPolicies(pmRoot){return decodeWorkflowPolicyDocument(await readBoundedPolicyFile(path.join(pmRoot,"schema","policies.json"),MAX_WORKFLOW_POLICY_BYTES))}async function readWorkflowApprovals(pmRoot,id){const raw=await readBoundedPolicyFile(getHistoryPath(pmRoot,id),MAX_WORKFLOW_APPROVAL_HISTORY_BYTES);if(raw===null)return[];let entries;try{entries=raw.split(/\r?\n/).filter(line=>line.trim()).map(line=>JSON.parse(line));if(!verifyHistoryChain(entries).ok)throw new Error("invalid chain")}catch{throw new PmCliError("Approval evidence requires a valid item history chain.",EXIT_CODE.CONFLICT,{code:"workflow_policy_approval_history_invalid",nextSteps:[`Run pm history ${id} --verify before recording or using an approval.`]})}return entries.flatMap(entry=>{const approval=entry.context?.workflow_approval;if(entry.op!=="policy_approve"||entry.record_hash_version!==1||typeof entry.record_hash!=="string"||typeof approval!=="object"||approval===null)return[];const record=approval;if(typeof record.policy_fingerprint!=="string"||typeof record.content_fingerprint!=="string")return[];return[{policy_fingerprint:record.policy_fingerprint,content_fingerprint:record.content_fingerprint,author:entry.author}]})}async function evaluateWorkspacePolicies(pmRoot,document,input){const needsApproval=input.before?.status!==input.after?.status&&document.policies.some(policy=>policy.rule.kind==="approval"&&workflowPolicyApplies(policy,input));const id=input.before?.id??input.after?.id;const approvals=needsApproval&&typeof id==="string"?await readWorkflowApprovals(pmRoot,id):[];return evaluateWorkflowPolicies(document,{...input,approvals})}async function enforceWorkflowMutation(params){const document=await readWorkflowPolicies(params.pmRoot);const result=await evaluateWorkspacePolicies(params.pmRoot,document,{operation:params.operation,author:params.author,before:params.before?{...params.before.metadata,body:params.before.body}:null,after:params.after?{...params.after.metadata,body:params.after.body}:null});if(result.allowed)return result;const refused=result.decisions.filter(decision=>!decision.satisfied&&decision.effect==="refuse");if(!params.dryRun){try{await appendWorkspaceAuditEvent({pmRoot:params.pmRoot,op:"policy_refused",author:params.author,context:{item_id:params.after?.metadata.id??params.before?.metadata.id,operation:params.operation,workflow_policies:result.decisions},message:"Workflow policy refused a proposed item mutation.",lockTtlSeconds:params.settings.locks.ttl_seconds,lockWaitMs:params.settings.locks.wait_ms})}catch(cause){const error=new PmCliError("Workflow policy refusal could not be recorded in workspace history.",EXIT_CODE.CONFLICT,{code:"workflow_policy_audit_failed",nextSteps:["Resolve workspace-history lock or storage failures, then retry the refused mutation; no item changes were written."]});error.cause=cause;throw error}}const summary=refused.slice(0,3).map(decision=>`${decision.policy_id} (${decision.rule})`).join(", ");const remaining=refused.length>3?` and ${refused.length-3} more`:"";throw new PmCliError(`Workflow policy refused ${params.operation}: ${summary}${remaining}.`,EXIT_CODE.CONFLICT,{code:"workflow_policy_refused",reason:refused.slice(0,3).map(decision=>decision.policy_id).join(","),nextSteps:[...new Set(refused.map(decision=>decision.remediation))].slice(0,3)})}export{MAX_WORKFLOW_APPROVAL_HISTORY_BYTES,MAX_WORKFLOW_POLICY_BYTES,decodeWorkflowPolicyDocument,enforceWorkflowMutation,evaluateWorkspacePolicies,readWorkflowApprovals,readWorkflowPolicies};
+//# sourceMappingURL=workflow-policy-store.js.map

package/dist/core/policy/workflow-policy.d.ts

@@ -0,0 +1,139 @@
+/** Policy verbs carried under the existing schema command family. */
+export declare const WORKFLOW_POLICY_ACTIONS: readonly ["policies", "policy-put", "policy-remove", "policy-mode", "policy-check", "policy-approve", "policy-presets"];
+/** Portable schema-policy action vocabulary. */
+export type WorkflowPolicyAction = (typeof WORKFLOW_POLICY_ACTIONS)[number];
+/** Maximum declarations evaluated for one mutation, independent of corpus size. */
+export declare const MAX_WORKFLOW_POLICIES = 256;
+/** Maximum selectors or fields within one declaration. */
+export declare const MAX_WORKFLOW_POLICY_TERMS = 64;
+/** Policy response, with refusal requiring a separate workspace opt-in. */
+export type WorkflowPolicyEffect = "advise" | "warn" | "refuse";
+/** All supplied selectors must match; values within a selector are alternatives. */
+export interface WorkflowPolicySubject {
+    /** Case-insensitive item type names. */
+    types?: string[];
+    /** At least one of these exact tags must be present. */
+    tags?: string[];
+    /** Canonical target lifecycle statuses; deletion uses the previous status. */
+    statuses?: string[];
+    /** Exact mutation operation names, as recorded in history. */
+    operations?: string[];
+    /** Direct parent ids for scoping policies to a domain or programme. */
+    parents?: string[];
+    /** Outgoing edge requirement evaluated on the selected record. */
+    dependency?: {
+        kind: string;
+        id?: string;
+    };
+}
+/** Data-only requirements; no expressions, regexes, or executable code. */
+export type WorkflowPolicyRule = {
+    kind: "require_fields";
+    fields: string[];
+} | {
+    kind: "transition";
+    allowed: [string, string][];
+} | {
+    kind: "authors";
+    authors: string[];
+} | {
+    kind: "field_writers";
+    fields: string[];
+    authors: string[];
+} | {
+    kind: "approval";
+    fields: string[];
+    authors: string[];
+};
+/** One stable, explainable workflow requirement. */
+export interface WorkflowPolicy {
+    /** Stable declaration id retained in mutation evidence. */
+    id: string;
+    /** Human explanation of the invariant, at most 500 characters. */
+    description?: string;
+    /** Optional intersection of item and operation selectors. */
+    subject?: WorkflowPolicySubject;
+    /** Defaults to advise; refuse also requires document.enforcement=refuse. */
+    effect?: WorkflowPolicyEffect;
+    /** The requirement evaluated for matching mutations. */
+    rule: WorkflowPolicyRule;
+}
+/** Versioned workspace data stored in schema/policies.json. */
+export interface WorkflowPolicyDocument {
+    /** Version of the declaration semantics. */
+    version: 1;
+    /** Explicit workspace permission for policies to refuse mutations. */
+    enforcement: "advise" | "refuse";
+    /** Ordered, uniquely identified declarations. */
+    policies: WorkflowPolicy[];
+}
+/** Approval evidence resolved from a verified immutable item history. */
+export interface WorkflowPolicyApproval {
+    /** Exact policy declaration hash, including its selectors and effect. */
+    policy_fingerprint: string;
+    /** Hash of the declared approval fields and item id. */
+    content_fingerprint: string;
+    /** Recorded author of the approval event. */
+    author: string;
+}
+/** Presentation-independent mutation snapshot. Body is a normal selectable field. */
+export interface WorkflowPolicyInput {
+    /** History operation being evaluated; ignored by state-only completeness. */
+    operation: string;
+    /** Effective mutation actor; never taken from mutable item.author. */
+    author: string;
+    /** Previous record or null for creation. */
+    before: Readonly<Record<string, unknown>> | null;
+    /** Proposed record or null for deletion. */
+    after: Readonly<Record<string, unknown>> | null;
+    /** Verified approval events, omitted when no approval rule is applicable. */
+    approvals?: readonly WorkflowPolicyApproval[];
+    /** Inspect present fields using only require_fields rules without operation selectors. */
+    completeness_only?: boolean;
+}
+/** Bounded explanation recorded alongside a mutation or returned by a preview. */
+export interface WorkflowPolicyDecision {
+    /** Stable id of the declaration evaluated. */
+    policy_id: string;
+    /** Fingerprint needed to identify the precise rule revision. */
+    policy_fingerprint: string;
+    /** Requirement vocabulary entry. */
+    rule: WorkflowPolicyRule["kind"];
+    /** Effective response after applying workspace consent. */
+    effect: WorkflowPolicyEffect;
+    /** Whether the proposed record meets this requirement. */
+    satisfied: boolean;
+    /** Missing field paths, never their values. */
+    missing_fields: string[];
+    /** Corrective action without item content or credential values. */
+    remediation: string;
+}
+/** Complete decision set; callers may project it without weakening enforcement. */
+export interface WorkflowPolicyEvaluation {
+    /** False when at least one effective refusal is unsatisfied. */
+    allowed: boolean;
+    /** One result for every matched declaration. */
+    decisions: WorkflowPolicyDecision[];
+    /** Safe compact warnings for unsatisfied advisory requirements. */
+    warnings: string[];
+}
+/** Parse and normalize a declaration, rejecting unsupported selectors. */
+export declare function parseWorkflowPolicy(value: unknown): WorkflowPolicy;
+/** Validate a complete registry; absence is handled by the IO layer, never malformed data. */
+export declare function parseWorkflowPolicyDocument(value: unknown): WorkflowPolicyDocument;
+/** Read only own properties so prototype values cannot satisfy a declared field. */
+export declare function readWorkflowPolicyField(record: Readonly<Record<string, unknown>> | null, field: string): unknown;
+/** Fingerprint exactly the declaration semantics used by a decision. */
+export declare function workflowPolicyFingerprint(policy: WorkflowPolicy): string;
+/** Bind an approval to its item and declared fields, excluding unrelated metadata. */
+export declare function workflowApprovalFingerprint(policy: WorkflowPolicy, record: Readonly<Record<string, unknown>>): string;
+/** Match both sides so removing a tag or changing type cannot evade a rule. */
+export declare function workflowPolicyApplies(policy: WorkflowPolicy, input: WorkflowPolicyInput): boolean;
+/** Evaluate current declarations; a later advisory can never override a refusal. */
+export declare function evaluateWorkflowPolicies(document: WorkflowPolicyDocument, input: WorkflowPolicyInput): WorkflowPolicyEvaluation;
+/**
+ * Capture a private normalized declaration snapshot for repeated evaluation.
+ * Each policy is hashed once; later edits to the caller's mutable document do
+ * not alter this evaluator. Create another evaluator to adopt those edits.
+ */
+export declare function createWorkflowPolicyEvaluator(document: WorkflowPolicyDocument): (input: WorkflowPolicyInput) => WorkflowPolicyEvaluation;

package/dist/core/policy/workflow-policy.js

@@ -0,0 +1,2 @@
+!(function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="8b0d8654-211b-57bf-852f-8a153849e8fd")}catch(e2){}})();import{createHash}from"node:crypto";import{stableStringify,stableValueEquals}from"../shared/serialization.js";import{PmCliError}from"../shared/errors.js";import{EXIT_CODE}from"../shared/constants.js";const WORKFLOW_POLICY_ACTIONS=["policies","policy-put","policy-remove","policy-mode","policy-check","policy-approve","policy-presets"];const MAX_WORKFLOW_POLICIES=256;const MAX_WORKFLOW_POLICY_TERMS=64;function invalidPolicy(detail){throw new PmCliError(`Invalid workflow policy: ${detail}`,EXIT_CODE.USAGE,{code:"workflow_policy_invalid",nextSteps:["Inspect pm schema policies and correct the declaration using pm schema policy-put."]})}function policyObject(value,keys,label){if(typeof value!=="object"||value===null||Array.isArray(value))return invalidPolicy(`${label} must be an object`);const record=value;if(Object.keys(record).some(key=>!keys.includes(key)))return invalidPolicy(`${label} contains an unknown key`);return record}function policyText(value,label,max=128){if(typeof value!=="string"||!value.trim()||value.length>max)return invalidPolicy(`${label} must be nonempty text of at most ${max} characters`);return value.trim()}function policyTerms(value,label){if(!Array.isArray(value)||value.length===0||value.length>MAX_WORKFLOW_POLICY_TERMS)return invalidPolicy(`${label} requires 1-${MAX_WORKFLOW_POLICY_TERMS} terms`);const terms=value.map(entry=>policyText(entry,label));if(label==="fields"&&terms.some(term=>!/^[a-zA-Z_][a-zA-Z0-9_]*(?:\.[a-zA-Z_][a-zA-Z0-9_]*){0,7}$/.test(term)||term.split(".").some(part=>["__proto__","constructor","prototype"].includes(part))))return invalidPolicy("fields must be safe metadata paths of at most eight segments");return[...new Set(terms)]}function parsePolicyRule(value){const common=policyObject(value,["kind","fields","authors","allowed"],"rule");if(common.kind==="transition"){policyObject(common,["kind","allowed"],"transition rule");if(!Array.isArray(common.allowed)||common.allowed.length>MAX_WORKFLOW_POLICY_TERMS)return invalidPolicy("transition.allowed must be a bounded array");return{kind:"transition",allowed:common.allowed.map(pair=>{if(!Array.isArray(pair)||pair.length!==2)return invalidPolicy("transition pairs need two statuses");return[policyText(pair[0],"from"),policyText(pair[1],"to")]})}}if(common.kind==="authors"){policyObject(common,["kind","authors"],"authors rule");return{kind:"authors",authors:policyTerms(common.authors,"authors")}}if(common.kind==="require_fields"){policyObject(common,["kind","fields"],"require_fields rule");return{kind:"require_fields",fields:policyTerms(common.fields,"fields")}}if(common.kind==="field_writers"||common.kind==="approval"){policyObject(common,["kind","fields","authors"],"field rule");return{kind:common.kind,fields:policyTerms(common.fields,"fields"),authors:policyTerms(common.authors,"authors")}}return invalidPolicy("unknown rule kind")}function parsePolicySubject(value){const subject={};const source=policyObject(value,["types","tags","statuses","operations","parents","dependency"],"subject");for(const key of["types","tags","statuses","operations","parents"]){if(source[key]!==void 0)subject[key]=policyTerms(source[key],key)}if(source.dependency!==void 0){const edge=policyObject(source.dependency,["kind","id"],"dependency");subject.dependency={kind:policyText(edge.kind,"dependency kind"),...edge.id===void 0?{}:{id:policyText(edge.id,"dependency id")}}}return subject}function parseWorkflowPolicy(value){const raw=policyObject(value,["id","description","subject","effect","rule"],"policy");const id=policyText(raw.id,"id");if(!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(id))return invalidPolicy("id must be a stable token");if(raw.effect!==void 0&&(typeof raw.effect!=="string"||!["advise","warn","refuse"].includes(raw.effect)))return invalidPolicy("effect must be advise, warn, or refuse");return{id,rule:parsePolicyRule(raw.rule),...raw.subject===void 0?{}:{subject:parsePolicySubject(raw.subject)},...raw.description===void 0?{}:{description:policyText(raw.description,"description",500)},...raw.effect===void 0?{}:{effect:raw.effect}}}function parseWorkflowPolicyDocument(value){const raw=policyObject(value,["version","enforcement","policies"],"document");if(raw.version!==1)return invalidPolicy("unsupported version");if(raw.enforcement!==void 0&&raw.enforcement!=="advise"&&raw.enforcement!=="refuse")return invalidPolicy("enforcement must be advise or refuse");if(!Array.isArray(raw.policies)||raw.policies.length>MAX_WORKFLOW_POLICIES)return invalidPolicy(`policies must contain at most ${MAX_WORKFLOW_POLICIES} declarations`);const policies=raw.policies.map(parseWorkflowPolicy);if(new Set(policies.map(policy=>policy.id)).size!==policies.length)return invalidPolicy("duplicate policy id");return{version:1,enforcement:raw.enforcement??"advise",policies}}function readWorkflowPolicyField(record,field){let value=record;for(const key of field.split(".")){if(typeof value!=="object"||value===null||!Object.hasOwn(value,key))return void 0;value=value[key]}return value}function hasPolicyValue(value){if(value===void 0||value===null)return false;if(typeof value==="string")return value.trim().length>0;if(typeof value==="number")return Number.isFinite(value);if(Array.isArray(value))return value.length>0;if(typeof value==="object")return Object.keys(value).length>0;return true}function workflowPolicyFingerprint(policy){return createHash("sha256").update(stableStringify(policy)).digest("hex")}function workflowApprovalFingerprint(policy,record){const fields=policy.rule.kind==="approval"?policy.rule.fields:[];return createHash("sha256").update(stableStringify({id:record.id,fields:fields.map(field=>[field,readWorkflowPolicyField(record,field)])})).digest("hex")}function matchesPolicyDependency(expected,dependencies){return Array.isArray(dependencies)&&dependencies.some(edge=>typeof edge==="object"&&edge!==null&&"kind"in edge&&edge.kind===expected.kind&&(expected.id===void 0||"id"in edge&&edge.id===expected.id))}function matchesPolicySubject(subject,record,operation){if(subject.types&&!subject.types.some(type=>type.toLowerCase()===String(record.type).toLowerCase()))return false;if(subject.statuses&&!subject.statuses.includes(String(record.status)))return false;if(subject.operations&&!subject.operations.includes(operation))return false;if(subject.parents&&!subject.parents.includes(String(record.parent)))return false;if(subject.tags&&(!Array.isArray(record.tags)||!subject.tags.some(tag=>record.tags.includes(tag))))return false;if(subject.dependency&&!matchesPolicyDependency(subject.dependency,record.dependencies))return false;return true}function workflowPolicyApplies(policy,input){if(input.completeness_only&&(policy.rule.kind!=="require_fields"||policy.subject?.operations!==void 0))return false;if(policy.rule.kind==="approval"&&input.before===null)return false;const subject=policy.subject??{};const status=input.after?.status??input.before?.status;return[input.before,input.after].some(record=>record!==null&&matchesPolicySubject(subject,{...record,status},input.operation))}function missingRequiredPolicyFields(fields,input,changedStatus,fieldsChanged){const scopeChanged=["type","tags","parent","dependencies"].some(field=>!stableValueEquals(input.before?.[field],input.after?.[field]));const missing=input.after&&(input.completeness_only||changedStatus||fieldsChanged||scopeChanged)?fields.filter(field=>!hasPolicyValue(readWorkflowPolicyField(input.after,field))):[];return missing}function hasMatchingWorkflowApproval(policy,input,authors,policyFingerprint){const record=input.after??input.before;const contentFingerprint=workflowApprovalFingerprint(policy,record);return input.approvals?.some(approval=>approval.policy_fingerprint===policyFingerprint&&approval.content_fingerprint===contentFingerprint&&approval.author!==input.author&&authors.includes(approval.author))??false}function evaluatePolicyRule(policy,input,policyFingerprint){const rule=policy.rule;const changedStatus=input.before?.status!==input.after?.status;const fieldsChanged="fields"in rule&&rule.fields.some(field=>!stableValueEquals(readWorkflowPolicyField(input.before,field),readWorkflowPolicyField(input.after,field)));switch(rule.kind){case"require_fields":{const missing=missingRequiredPolicyFields(rule.fields,input,changedStatus,fieldsChanged);return{satisfied:missing.length===0,missing_fields:missing,remediation:"Supply the declared required fields before this lifecycle transition."}}case"transition":return{satisfied:!changedStatus||rule.allowed.some(([from,to])=>from===String(input.before?.status??"$create")&&to===String(input.after?.status??"$delete")),missing_fields:[],remediation:"Choose a declared allowed transition; inspect pm schema policies."};case"authors":return{satisfied:rule.authors.includes(input.author),missing_fields:[],remediation:"Have a declared workflow actor perform this operation."};case"field_writers":return{satisfied:!fieldsChanged||rule.authors.includes(input.author),missing_fields:[],remediation:"Have a declared field writer change the protected fields."};case"approval":return{satisfied:!changedStatus||hasMatchingWorkflowApproval(policy,input,rule.authors,policyFingerprint),missing_fields:[],remediation:`Record an independent approval with pm schema policy-approve <item-id> --policy ${policy.id} after preparing the reviewed fields.`}}}function evaluateWorkflowPolicySnapshot(document,input,fingerprint){const decisions=document.policies.filter(policy=>workflowPolicyApplies(policy,input)).map(policy=>{const requested=policy.effect??"advise";const policyFingerprint=fingerprint(policy);return{policy_id:policy.id,policy_fingerprint:policyFingerprint,rule:policy.rule.kind,effect:requested==="refuse"&&document.enforcement!=="refuse"?"warn":requested,...evaluatePolicyRule(policy,input,policyFingerprint)}});return{allowed:!decisions.some(decision=>!decision.satisfied&&decision.effect==="refuse"),decisions,warnings:decisions.filter(decision=>!decision.satisfied).map(decision=>`workflow_policy:${decision.effect}:${decision.policy_id}:${decision.rule}`)}}function evaluateWorkflowPolicies(document,input){return evaluateWorkflowPolicySnapshot(document,input,workflowPolicyFingerprint)}function createWorkflowPolicyEvaluator(document){const snapshot=parseWorkflowPolicyDocument(document);const fingerprints=new Map(snapshot.policies.map(policy=>[policy,workflowPolicyFingerprint(policy)]));return input=>evaluateWorkflowPolicySnapshot(snapshot,input,policy=>fingerprints.get(policy))}export{MAX_WORKFLOW_POLICIES,MAX_WORKFLOW_POLICY_TERMS,WORKFLOW_POLICY_ACTIONS,createWorkflowPolicyEvaluator,evaluateWorkflowPolicies,parseWorkflowPolicy,parseWorkflowPolicyDocument,readWorkflowPolicyField,workflowApprovalFingerprint,workflowPolicyApplies,workflowPolicyFingerprint};
+//# sourceMappingURL=workflow-policy.js.map