@unbrained/pm-cli 2026.9.7 → 2026.9.9

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

package/dist/core/profile/profile-describe.js

@@ -1,84 +1,2 @@
-/**
- * @module core/profile/profile-describe
- *
- * Author-time *describe* primitive for a {@link ProjectProfileDefinition}: the
- * project-profile analogue of the extension surface's `describeExtensionBlueprint`.
- * It distills a profile into a deterministic, side-effect-free summary — the
- * per-dimension counts plus the resolved entry identifiers — so the CLI
- * `pm profile show`/`list` formatters and SDK consumers share one source of truth
- * for "what does this profile stage?" rather than each recomputing it inline.
- *
- * Identifier derivation deliberately mirrors what {@link module:core/profile/profile-plan}
- * upserts: item type names, status ids, and field keys all flow through the same
- * `normalizeAddTypeInput` / `normalizeAddStatusInput` / `normalizeAddFieldInput`
- * canonicalization the planner uses, so describe reports the exact ids/keys
- * `pm profile apply` stages (not the author's raw casing/spelling). Workflows,
- * config, templates, and packages surface their authored identity verbatim.
- *
- * Describe is intentionally lenient: it feeds read-only `pm profile show`/`list`,
- * so a semantically-invalid entry from an untrusted extension-contributed profile
- * (a built-in-named or empty type/status/field the normalizer rejects) falls back
- * to its raw identifier rather than throwing — surfacing the actual defect is the
- * job of {@link module:core/profile/profile-lint lintProjectProfile}, not describe.
- */
-
-!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]="933d8f74-c4aa-58d0-bd3b-8932a35d3702")}catch(e){}}();
-import { normalizeAddFieldInput } from "../schema/fields-file.js";
-import { normalizeAddStatusInput } from "../schema/status-defs-file.js";
-import { normalizeAddTypeInput } from "../schema/item-types-file.js";
-/** Computes the per-dimension counts for a profile. */
-export function describeProfileComposition(profile) {
-    return {
-        types: profile.types.length,
-        statuses: profile.statuses.length,
-        fields: profile.fields.length,
-        workflows: profile.workflows.length,
-        config: profile.config.length,
-        templates: profile.templates.length,
-        packages: profile.packages.length,
-    };
-}
-/**
- * Distills a profile definition into a deterministic composition summary. Pure
- * and tracker-independent; the resolved identifiers match exactly what
- * `pm profile apply` stages for each dimension.
- *
- * @param profile The profile definition to describe.
- * @returns The profile's metadata, per-dimension counts, and resolved entry
- *   identifiers.
- */
-export function describeProjectProfile(profile) {
-    return {
-        name: profile.name,
-        title: profile.title,
-        summary: profile.summary,
-        composition: describeProfileComposition(profile),
-        types: profile.types.map((type) => lenientIdentifier(() => normalizeAddTypeInput(type).name, () => String(type.name ?? ""))),
-        statuses: profile.statuses.map((status) => lenientIdentifier(() => normalizeAddStatusInput(status).id, () => String(status.id ?? ""))),
-        fields: profile.fields.map((field) => lenientIdentifier(() => normalizeAddFieldInput(field).key, () => String(field.key ?? ""))),
-        workflows: profile.workflows.map((workflow) => workflow.type),
-        config: profile.config.map((entry) => `${entry.key}=${entry.value}`),
-        templates: profile.templates.map((template) => template.name),
-        packages: profile.packages.map((recommendation) => ({
-            spec: recommendation.spec,
-            reason: recommendation.reason,
-        })),
-    };
-}
-/**
- * Resolves a dimension entry's identifier through the planner's canonicalizing
- * normalizer so describe reports exactly what `pm profile apply` stages, falling
- * back to the entry's raw identifier when the normalizer rejects a semantically
- * invalid value (a built-in-named or empty type/status/field) — surfacing the
- * defect is the job of {@link module:core/profile/profile-lint}, not describe.
- */
-function lenientIdentifier(normalize, raw) {
-    try {
-        return normalize();
-    }
-    catch {
-        return raw();
-    }
-}
+!(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]="ab26bcb3-fb2a-5f2f-96e7-7965787b924e")}catch(e2){}})();import{normalizeAddFieldInput}from"../schema/fields-file.js";import{normalizeAddStatusInput}from"../schema/status-defs-file.js";import{normalizeAddTypeInput}from"../schema/item-types-file.js";function describeProfileComposition(profile){return{types:profile.types.length,statuses:profile.statuses.length,fields:profile.fields.length,workflows:profile.workflows.length,config:profile.config.length,templates:profile.templates.length,packages:profile.packages.length}}function describeProjectProfile(profile){return{name:profile.name,title:profile.title,summary:profile.summary,composition:describeProfileComposition(profile),types:profile.types.map(type=>lenientIdentifier(()=>normalizeAddTypeInput(type).name,()=>String(type.name??""))),statuses:profile.statuses.map(status=>lenientIdentifier(()=>normalizeAddStatusInput(status).id,()=>String(status.id??""))),fields:profile.fields.map(field=>lenientIdentifier(()=>normalizeAddFieldInput(field).key,()=>String(field.key??""))),workflows:profile.workflows.map(workflow=>workflow.type),config:profile.config.map(entry=>`${entry.key}=${entry.value}`),templates:profile.templates.map(template=>template.name),packages:profile.packages.map(recommendation=>({spec:recommendation.spec,reason:recommendation.reason}))}}function lenientIdentifier(normalize,raw){try{return normalize()}catch{return raw()}}export{describeProfileComposition,describeProjectProfile};
 //# sourceMappingURL=profile-describe.js.map
-//# debugId=933d8f74-c4aa-58d0-bd3b-8932a35d3702