@unbrained/pm-cli 2026.10.25 → 2026.10.26

package/dist/sdk/lifecycle/restore.js

@@ -1,2 +1,2 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="ce212ffb-1f13-5893-9690-31dbb4e0de13")}catch{}})();import{assertInitializedTracker}from"../environment/tracker-preflight.js";import{normalizeItemFormatVersion,requiredItemFormatVersion}from"../../core/item/item-format-version.js";import{assertProjectRuntimeFormatGuard}from"../environment/project-runtime-compatibility.js";import{enforceWorkflowMutation}from"../../core/policy/workflow-policy-store.js";import jsonPatch from"fast-json-patch";import fs from"node:fs/promises";import{readLocatedItemSnapshot}from"../../core/store/item-store.js";import{readHistorySnapshot}from"../../core/history/read.js";import{verifyHistoryRewriteNoDrift}from"../../core/history/history-rewrite.js";import{resolveHistorySubject}from"../history/subject.js";import{historyVersionOffset}from"../../core/history/version-address.js";import{writeFileAtomic,appendHistoryEntry,createHistoryEntry,replayToCanonicalItemDocument,replayToItemDocument,toReplayDocument,enforceHistoryStreamPolicyForItem,canonicalDocument,serializeItemDocument,resolveItemTypeRegistry,acquireLockLease,EXIT_CODE,PmCliError,nowIso,getActiveExtensionRegistrations,projectAfterCommandItemSnapshot,recordAfterCommandAffectedItem,runActiveOnWriteHooks,runActiveBeforeMutationHooks,createMutationGuardSdk,getItemPath,resolvePmRoot,resolveWorkspaceRoot,readSettings,resolveAuthor}from"../runtime-primitives.js";import{applyHistoryPatch,ensureMaterializedHistoryTarget as ensureMaterializedRestoreTarget,extractPatchFailureContext,replayHistoryToTarget as replayToTarget,resolveHistoryTarget}from"../history-read.js";import{acquireItemMetadataDerivedIndexLock,refreshItemMetadataDerivedIndex}from"../item-metadata-index.js";async function readRestoreItem(located,settings,history){const snapshot=await readLocatedItemSnapshot(located,{schema:settings.schema});return snapshot.error===null?{raw:snapshot.raw,document:snapshot.document}:{raw:snapshot.raw,document:replayCurrentDocument(history),recovered:!0}}function ensureReplayTarget(target,history){return resolveHistoryTarget(target,history,{errorSubject:"restore",allowFutureTimestamp:!0})}function replayCurrentDocument(history){const currentReplay=replayToTarget(history,history.length-1);return Object.keys(currentReplay.metadata).length===0?{metadata:{},body:currentReplay.body}:canonicalDocument(replayToItemDocument(currentReplay))}async function resolveRestoreSubject(pmRoot,id,settings,typeToFolder){const subject=await resolveHistorySubject(pmRoot,id,settings,typeToFolder),historyPolicy=subject.located?await enforceHistoryStreamPolicyForItem({pmRoot,settings,itemId:subject.id,commandLabel:"restore"}):{warnings:[]};return{...subject,historyPolicyWarnings:historyPolicy.warnings}}function changedFields(beforeDocument,afterDocument){const beforeReplay=toReplayDocument(beforeDocument),afterReplay=toReplayDocument(afterDocument),patch=jsonPatch.compare(beforeReplay,afterReplay),fields=new Set;for(const op of patch){if(op.path==="/body"||op.path.startsWith("/body/")){fields.add("body");continue}const segment=op.path.replace(/^\/(?:metadata|front_matter)\/?/,"").split("/")[0];fields.add(segment.replaceAll("~1","/").replaceAll("~0","~"))}return Array.from(fields).sort((a,b)=>a.localeCompare(b))}async function loadRestoreStateUnderLock(params){const verified=await verifyHistoryRewriteNoDrift({pmRoot:params.pmRoot,subject:params.subject,settings:params.settings,typeRegistry:params.typeRegistry,historyRawBeforeLock:params.historyRawBeforeLock,currentItemRawBeforeLock:params.currentItemRawBeforeLock,operation:"restore",readItem:located=>readRestoreItem(located,params.settings,params.history)});return{loadedItemUnderLock:verified.loadedItemUnderLock,existingItemPath:verified.locatedUnderLock?.itemPath??null}}function resolveRestoreCurrentState(loadedItemUnderLock,history){return loadedItemUnderLock?{document:loadedItemUnderLock.document,originalRaw:loadedItemUnderLock.raw}:{document:replayCurrentDocument(history),originalRaw:null}}function collectRestoreOwnershipWarnings(params){const assigned=params.document.metadata.assignee?.trim();if(!(assigned&&assigned!==params.author&&!params.force))return[];if(params.enforcement==="strict")throw new PmCliError(`Item ${params.resolvedId} is assigned to ${assigned}. Use --force to override.`,EXIT_CODE.CONFLICT);return params.enforcement==="warn"?[`ownership_warning:assignee_conflict:${params.resolvedId}:${assigned}`]:[]}async function restorePreviousItemAfterHistoryFailure(params){if(params.existingItemPath&&params.resolvedOriginalRaw!==null&&params.restoredItemPath!==params.existingItemPath){await writeFileAtomic(params.existingItemPath,params.resolvedOriginalRaw),await fs.rm(params.restoredItemPath,{force:!0});return}if(params.existingItemPath&&params.resolvedOriginalRaw!==null){await writeFileAtomic(params.existingItemPath,params.resolvedOriginalRaw);return}await fs.rm(params.restoredItemPath,{force:!0})}async function runRestoreWriteHooks(params){return[...await runActiveOnWriteHooks({path:params.restoredItemPath,scope:"project",op:"restore",item_id:params.after.metadata.id,item_type:params.after.metadata.type,before:params.before,after:params.after,changed_fields:["restored"]}),...await runActiveOnWriteHooks({path:params.historyPath,scope:"project",op:"restore:history",item_id:params.after.metadata.id,item_type:params.after.metadata.type,before:params.before,after:params.after,changed_fields:["restored"]})]}async function runRestore(id,target,options,global2){const pmRoot=resolvePmRoot(process.cwd(),global2.path);await assertInitializedTracker(pmRoot);const settings=await readSettings(pmRoot),typeRegistry=resolveItemTypeRegistry(settings,getActiveExtensionRegistrations()),subject=await resolveRestoreSubject(pmRoot,id,settings,typeRegistry.type_to_folder),resolvedId=subject.id,{raw:historyRawBeforeLock,entries:history}=await readHistorySnapshot(subject.historyPath,resolvedId);if(history.length===0)throw new PmCliError(`No history exists for ${resolvedId}; restore is unavailable.`,EXIT_CODE.NOT_FOUND);const resolvedTarget=ensureReplayTarget(target,history),replayDocument=ensureMaterializedRestoreTarget(replayToTarget(history,resolvedTarget.historyIndex),resolvedTarget),restoredDocument=replayToCanonicalItemDocument(replayDocument,{schema:settings.schema});if(restoredDocument.metadata.id!==resolvedId)throw new PmCliError(`Restore target resolved to item ${restoredDocument.metadata.id}, expected ${resolvedId}.`,EXIT_CODE.GENERIC_FAILURE);const currentItemRawBeforeLock=(subject.located?await readRestoreItem(subject.located,settings,history):null)?.raw??null,author=resolveAuthor(options.author,settings.author_default),lease=await acquireLockLease(pmRoot,resolvedId,settings.locks.ttl_seconds,author,!!options.force,settings.governance.force_required_for_stale_lock,settings.locks.wait_ms,{waitPolicy:"progress"}),releaseLock=lease.release;try{const{loadedItemUnderLock,existingItemPath}=await loadRestoreStateUnderLock({pmRoot,subject,settings,typeRegistry,historyRawBeforeLock,currentItemRawBeforeLock,history}),itemFormat="toon",currentState=resolveRestoreCurrentState(loadedItemUnderLock,history);restoredDocument.metadata.pm_format_version=normalizeItemFormatVersion(Math.max(requiredItemFormatVersion(restoredDocument.metadata),requiredItemFormatVersion(currentState.document.metadata))),assertProjectRuntimeFormatGuard(resolveWorkspaceRoot(pmRoot),requiredItemFormatVersion(restoredDocument.metadata));const ownershipWarnings=collectRestoreOwnershipWarnings({document:currentState.document,author,force:options.force,enforcement:settings.governance.ownership_enforcement,resolvedId}),restoreChangedFields=changedFields(currentState.document,restoredDocument),workflowPolicy=await enforceWorkflowMutation({pmRoot,settings,operation:"restore",author,before:currentState.document,after:restoredDocument});await runActiveBeforeMutationHooks({pm_root:pmRoot,operation:"restore",before:currentState.document,after:restoredDocument,changed_fields:restoreChangedFields,sdk:createMutationGuardSdk({pmRoot,settings,typeToFolder:typeRegistry.type_to_folder})});const serializedRestore=serializeItemDocument(restoredDocument,{format:itemFormat,schema:settings.schema}),restoredItemPath=getItemPath(pmRoot,restoredDocument.metadata.type,resolvedId,itemFormat,typeRegistry.type_to_folder),derivedIndexWarnings=await lease.fence(async()=>{const releaseDerivedIndexLock=await acquireItemMetadataDerivedIndexLock(pmRoot,author);let derivedIndexWarnings2;try{await writeFileAtomic(restoredItemPath,serializedRestore),existingItemPath&&restoredItemPath!==existingItemPath&&await fs.rm(existingItemPath);const historyEntry=createHistoryEntry({nowIso:nowIso(),author,op:"restore",before:currentState.document,after:restoredDocument,message:options.message,context:workflowPolicy.decisions.length===0?void 0:{workflow_policies:workflowPolicy.decisions}});try{await appendHistoryEntry(subject.historyPath,historyEntry)}catch(error){throw await restorePreviousItemAfterHistoryFailure({existingItemPath,resolvedOriginalRaw:currentState.originalRaw,restoredItemPath}),error}derivedIndexWarnings2=await refreshItemMetadataDerivedIndex({pmRoot,preferredFormat:settings.item_format,typeToFolder:typeRegistry.type_to_folder,schema:settings.schema,itemPath:restoredItemPath,previousItemPath:existingItemPath??void 0,document:restoredDocument})}finally{await releaseDerivedIndexLock()}return derivedIndexWarnings2}),hookWarnings=await runRestoreWriteHooks({restoredItemPath,historyPath:subject.historyPath,before:currentState.document,after:restoredDocument});recordAfterCommandAffectedItem({id:restoredDocument.metadata.id,op:"restore",item_type:restoredDocument.metadata.type,previous_status:currentState.document.metadata.status,status:restoredDocument.metadata.status,previous:projectAfterCommandItemSnapshot(currentState.document.metadata,restoreChangedFields),current:projectAfterCommandItemSnapshot(restoredDocument.metadata,restoreChangedFields),changed_fields:restoreChangedFields});const targetEntry=history[resolvedTarget.historyIndex],offset=historyVersionOffset(history,!0);return{item:restoredDocument.metadata,restored_from:{kind:resolvedTarget.kind,target:resolvedTarget.raw,history_index:resolvedTarget.historyIndex+1,version:offset===null?null:offset+resolvedTarget.historyIndex+1,entry_ts:targetEntry.ts,entry_op:targetEntry.op},changed_fields:restoreChangedFields,warnings:[...workflowPolicy.warnings,...loadedItemUnderLock?.recovered?["restore_unreadable_item_recovered"]:[],...subject.historyPolicyWarnings,...ownershipWarnings,...derivedIndexWarnings,...hookWarnings]}}finally{await releaseLock()}}const _testOnlyRestoreCommand={applyHistoryPatch,changedFields,ensureMaterializedRestoreTarget,ensureReplayTarget,extractPatchFailureContext,replayCurrentDocument,replayToTarget,resolveRestoreSubject};export{_testOnlyRestoreCommand,runRestore};
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="f3145f17-e911-571b-9da3-f014e6fdde1c")}catch{}})();import{assertInitializedTracker}from"../environment/tracker-preflight.js";import{normalizeItemFormatVersion,requiredItemFormatVersion}from"../../core/item/item-format-version.js";import{assertProjectRuntimeFormatGuard}from"../environment/project-runtime-compatibility.js";import{enforceWorkflowMutation}from"../../core/policy/workflow-policy-store.js";import jsonPatch from"fast-json-patch";import fs from"node:fs/promises";import{readLocatedItemSnapshot}from"../../core/store/item-store.js";import{assertItemMutationPreconditions}from"../../core/store/item-mutation-precondition.js";import{readHistorySnapshot}from"../../core/history/read.js";import{verifyHistoryRewriteNoDrift}from"../../core/history/history-rewrite.js";import{resolveHistorySubject}from"../history/subject.js";import{historyVersionOffset}from"../../core/history/version-address.js";import{writeFileAtomic,appendHistoryEntry,createHistoryEntry,replayToCanonicalItemDocument,replayToItemDocument,toReplayDocument,enforceHistoryStreamPolicyForItem,canonicalDocument,serializeItemDocument,resolveItemTypeRegistry,acquireLockLease,EXIT_CODE,PmCliError,nowIso,getActiveExtensionRegistrations,projectAfterCommandItemSnapshot,recordAfterCommandAffectedItem,runActiveOnWriteHooks,runActiveBeforeMutationHooks,createMutationGuardSdk,getItemPath,resolvePmRoot,resolveWorkspaceRoot,readSettings,resolveAuthor}from"../runtime-primitives.js";import{applyHistoryPatch,ensureMaterializedHistoryTarget as ensureMaterializedRestoreTarget,extractPatchFailureContext,replayHistoryToTarget as replayToTarget,resolveHistoryTarget}from"../history-read.js";import{acquireItemMetadataDerivedIndexLock,refreshItemMetadataDerivedIndex}from"../item-metadata-index.js";async function readRestoreItem(located,settings,history){const snapshot=await readLocatedItemSnapshot(located,{schema:settings.schema});return snapshot.error===null?{raw:snapshot.raw,document:snapshot.document}:{raw:snapshot.raw,document:replayCurrentDocument(history),recovered:!0}}function ensureReplayTarget(target,history){return resolveHistoryTarget(target,history,{errorSubject:"restore",allowFutureTimestamp:!0})}function replayCurrentDocument(history){const currentReplay=replayToTarget(history,history.length-1);return Object.keys(currentReplay.metadata).length===0?{metadata:{},body:currentReplay.body}:canonicalDocument(replayToItemDocument(currentReplay))}async function resolveRestoreSubject(pmRoot,id,settings,typeToFolder){const subject=await resolveHistorySubject(pmRoot,id,settings,typeToFolder),historyPolicy=subject.located?await enforceHistoryStreamPolicyForItem({pmRoot,settings,itemId:subject.id,commandLabel:"restore"}):{warnings:[]};return{...subject,historyPolicyWarnings:historyPolicy.warnings}}function changedFields(beforeDocument,afterDocument){const beforeReplay=toReplayDocument(beforeDocument),afterReplay=toReplayDocument(afterDocument),patch=jsonPatch.compare(beforeReplay,afterReplay),fields=new Set;for(const op of patch){if(op.path==="/body"||op.path.startsWith("/body/")){fields.add("body");continue}const segment=op.path.replace(/^\/(?:metadata|front_matter)\/?/,"").split("/")[0];fields.add(segment.replaceAll("~1","/").replaceAll("~0","~"))}return Array.from(fields).sort((a,b)=>a.localeCompare(b))}async function loadRestoreStateUnderLock(params){const verified=await verifyHistoryRewriteNoDrift({pmRoot:params.pmRoot,subject:params.subject,settings:params.settings,typeRegistry:params.typeRegistry,historyRawBeforeLock:params.historyRawBeforeLock,currentItemRawBeforeLock:params.currentItemRawBeforeLock,operation:"restore",readItem:located=>readRestoreItem(located,params.settings,params.history)});return{loadedItemUnderLock:verified.loadedItemUnderLock,existingItemPath:verified.locatedUnderLock?.itemPath??null}}function resolveRestoreCurrentState(loadedItemUnderLock,history){return loadedItemUnderLock?{document:loadedItemUnderLock.document,originalRaw:loadedItemUnderLock.raw}:{document:replayCurrentDocument(history),originalRaw:null}}function collectRestoreOwnershipWarnings(params){const assigned=params.document.metadata.assignee?.trim();if(!(assigned&&assigned!==params.author&&!params.force))return[];if(params.enforcement==="strict")throw new PmCliError(`Item ${params.resolvedId} is assigned to ${assigned}. Use --force to override.`,EXIT_CODE.CONFLICT);return params.enforcement==="warn"?[`ownership_warning:assignee_conflict:${params.resolvedId}:${assigned}`]:[]}async function restorePreviousItemAfterHistoryFailure(params){if(params.existingItemPath&&params.resolvedOriginalRaw!==null&&params.restoredItemPath!==params.existingItemPath){await writeFileAtomic(params.existingItemPath,params.resolvedOriginalRaw),await fs.rm(params.restoredItemPath,{force:!0});return}if(params.existingItemPath&&params.resolvedOriginalRaw!==null){await writeFileAtomic(params.existingItemPath,params.resolvedOriginalRaw);return}await fs.rm(params.restoredItemPath,{force:!0})}async function runRestoreWriteHooks(params){return[...await runActiveOnWriteHooks({path:params.restoredItemPath,scope:"project",op:"restore",item_id:params.after.metadata.id,item_type:params.after.metadata.type,before:params.before,after:params.after,changed_fields:["restored"]}),...await runActiveOnWriteHooks({path:params.historyPath,scope:"project",op:"restore:history",item_id:params.after.metadata.id,item_type:params.after.metadata.type,before:params.before,after:params.after,changed_fields:["restored"]})]}async function runRestore(id,target,options,global2){const pmRoot=resolvePmRoot(process.cwd(),global2.path);await assertInitializedTracker(pmRoot);const settings=await readSettings(pmRoot),typeRegistry=resolveItemTypeRegistry(settings,getActiveExtensionRegistrations()),subject=await resolveRestoreSubject(pmRoot,id,settings,typeRegistry.type_to_folder),resolvedId=subject.id,{raw:historyRawBeforeLock,entries:history}=await readHistorySnapshot(subject.historyPath,resolvedId);if(history.length===0)throw new PmCliError(`No history exists for ${resolvedId}; restore is unavailable.`,EXIT_CODE.NOT_FOUND);const resolvedTarget=ensureReplayTarget(target,history),replayDocument=ensureMaterializedRestoreTarget(replayToTarget(history,resolvedTarget.historyIndex),resolvedTarget),restoredDocument=replayToCanonicalItemDocument(replayDocument,{schema:settings.schema});if(restoredDocument.metadata.id!==resolvedId)throw new PmCliError(`Restore target resolved to item ${restoredDocument.metadata.id}, expected ${resolvedId}.`,EXIT_CODE.GENERIC_FAILURE);const currentItemRawBeforeLock=(subject.located?await readRestoreItem(subject.located,settings,history):null)?.raw??null,author=resolveAuthor(options.author,settings.author_default),lease=await acquireLockLease(pmRoot,resolvedId,settings.locks.ttl_seconds,author,!!options.force,settings.governance.force_required_for_stale_lock,settings.locks.wait_ms,{waitPolicy:"progress"}),releaseLock=lease.release;try{const{loadedItemUnderLock,existingItemPath}=await loadRestoreStateUnderLock({pmRoot,subject,settings,typeRegistry,historyRawBeforeLock,currentItemRawBeforeLock,history}),itemFormat="toon",currentState=resolveRestoreCurrentState(loadedItemUnderLock,history);assertItemMutationPreconditions(pmRoot,currentState.document),restoredDocument.metadata.pm_format_version=normalizeItemFormatVersion(Math.max(requiredItemFormatVersion(restoredDocument.metadata),requiredItemFormatVersion(currentState.document.metadata))),assertProjectRuntimeFormatGuard(resolveWorkspaceRoot(pmRoot),requiredItemFormatVersion(restoredDocument.metadata));const ownershipWarnings=collectRestoreOwnershipWarnings({document:currentState.document,author,force:options.force,enforcement:settings.governance.ownership_enforcement,resolvedId}),restoreChangedFields=changedFields(currentState.document,restoredDocument),workflowPolicy=await enforceWorkflowMutation({pmRoot,settings,operation:"restore",author,before:currentState.document,after:restoredDocument});await runActiveBeforeMutationHooks({pm_root:pmRoot,operation:"restore",before:currentState.document,after:restoredDocument,changed_fields:restoreChangedFields,sdk:createMutationGuardSdk({pmRoot,settings,typeToFolder:typeRegistry.type_to_folder})});const serializedRestore=serializeItemDocument(restoredDocument,{format:itemFormat,schema:settings.schema}),restoredItemPath=getItemPath(pmRoot,restoredDocument.metadata.type,resolvedId,itemFormat,typeRegistry.type_to_folder),derivedIndexWarnings=await lease.fence(async()=>{const releaseDerivedIndexLock=await acquireItemMetadataDerivedIndexLock(pmRoot,author);let derivedIndexWarnings2;try{await writeFileAtomic(restoredItemPath,serializedRestore),existingItemPath&&restoredItemPath!==existingItemPath&&await fs.rm(existingItemPath);const historyEntry=createHistoryEntry({nowIso:nowIso(),author,op:"restore",before:currentState.document,after:restoredDocument,message:options.message,context:workflowPolicy.decisions.length===0?void 0:{workflow_policies:workflowPolicy.decisions}});try{await appendHistoryEntry(subject.historyPath,historyEntry)}catch(error){throw await restorePreviousItemAfterHistoryFailure({existingItemPath,resolvedOriginalRaw:currentState.originalRaw,restoredItemPath}),error}derivedIndexWarnings2=await refreshItemMetadataDerivedIndex({pmRoot,preferredFormat:settings.item_format,typeToFolder:typeRegistry.type_to_folder,schema:settings.schema,itemPath:restoredItemPath,previousItemPath:existingItemPath??void 0,document:restoredDocument})}finally{await releaseDerivedIndexLock()}return derivedIndexWarnings2}),hookWarnings=await runRestoreWriteHooks({restoredItemPath,historyPath:subject.historyPath,before:currentState.document,after:restoredDocument});recordAfterCommandAffectedItem({id:restoredDocument.metadata.id,op:"restore",item_type:restoredDocument.metadata.type,previous_status:currentState.document.metadata.status,status:restoredDocument.metadata.status,previous:projectAfterCommandItemSnapshot(currentState.document.metadata,restoreChangedFields),current:projectAfterCommandItemSnapshot(restoredDocument.metadata,restoreChangedFields),changed_fields:restoreChangedFields});const targetEntry=history[resolvedTarget.historyIndex],offset=historyVersionOffset(history,!0);return{item:restoredDocument.metadata,restored_from:{kind:resolvedTarget.kind,target:resolvedTarget.raw,history_index:resolvedTarget.historyIndex+1,version:offset===null?null:offset+resolvedTarget.historyIndex+1,entry_ts:targetEntry.ts,entry_op:targetEntry.op},changed_fields:restoreChangedFields,warnings:[...workflowPolicy.warnings,...loadedItemUnderLock?.recovered?["restore_unreadable_item_recovered"]:[],...subject.historyPolicyWarnings,...ownershipWarnings,...derivedIndexWarnings,...hookWarnings]}}finally{await releaseLock()}}const _testOnlyRestoreCommand={applyHistoryPatch,changedFields,ensureMaterializedRestoreTarget,ensureReplayTarget,extractPatchFailureContext,replayCurrentDocument,replayToTarget,resolveRestoreSubject};export{_testOnlyRestoreCommand,runRestore};
 //# sourceMappingURL=restore.js.map

package/dist/sdk/lifecycle-policy.d.ts

@@ -33,6 +33,8 @@ lifecyclePolicy?:Partial<TerminalTransitionPolicy>;
 }
 /** Result returned by the public close-item operation. */
 export interface CloseOperationResult {
+/** Completion timestamp and the input that supplied it for this close event. */
+completion?:CloseCompletionReceipt;
 /** Closed item projected as a stable record. */
 item:Record<string,unknown>;
 /** Metadata fields changed by the transition. */
@@ -42,6 +44,15 @@ follow_up?:CloseEvidenceFollowUp;
 /** Validation and lifecycle policy receipts. */
 warnings:string[];
 }
+/** Per-close completion provenance, also sealed into the immutable close event. */
+export interface CloseCompletionReceipt {
+/** Actual persisted completed_at value. */
+timestamp:string;
+/** Caller assertion, preserved metadata, or inferred tracker close time. */
+source:"asserted" | "existing" | "close_time";
+/** Actionable correction guidance when completion was inferred. */
+hint?:string;
+}
 /** Optional evidence completion after a successful, durable close. */
 export interface CloseEvidenceFollowUp {
 /** Close succeeded; this guidance does not request another close attempt. */

package/dist/sdk/lifecycle-policy.js

@@ -1,2 +1,2 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="8e07b07a-fde3-5173-bb7c-7e8ade88570c")}catch{}})();import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";const DEFAULT_TERMINAL_TRANSITION_POLICY=Object.freeze({requireCloseReason:!0,orderingEdges:"preserve"});function resolveTerminalReason(input){const candidates=[{source:"explicit",value:input.explicit},{source:"duplicate",value:input.duplicateOf===void 0?void 0:`Duplicate of ${input.duplicateOf}`},{source:"resolution",value:input.resolution},{source:"message",value:input.message}];for(const candidate of candidates){const normalized=candidate.value?.trim();if(normalized)return{closeReason:normalized,source:candidate.source}}return{source:"none"}}function requireTerminalReason(input,required){return requireTerminalReasonWithRecovery(input,required,{operation:"close"})}function requireTerminalReasonWithRecovery(input,required,recovery){const resolution=resolveTerminalReason(input);if(!required||resolution.closeReason!==void 0)return resolution;const examples=recovery.operation==="create"?[`pm create --title "<title>" --type <type> --status ${recovery.status??"closed"} --close-reason "<closing summary>"`,`pm create --title "<title>" --type <type> --status ${recovery.status??"closed"} --resolution "<resolution summary>"`,"pm create --stdin-json < item.json"]:['pm close <id> "Done: <what changed and why>"','pm close <id> --reason "<closing summary>"','pm close <id> -m "<closing summary>"',"pm close <id> --duplicate-of <canonical-id>"];throw new PmCliError("Close reason text is required because governance.require_close_reason is enabled",EXIT_CODE.USAGE,{code:"close_reason_required",required:"Provide an author-controlled closing summary as the reason, message, resolution, or duplicate target.",why:"governance.require_close_reason is enabled, so tools must not invent immutable closure evidence.",examples,nextSteps:[`Re-run the ${recovery.operation} operation with a closing summary.`,"To stop requiring reasons, run: pm config set governance-require-close-reason --policy disabled"]})}function applyTerminalOrderingPolicy(metadata,policy){const previousBlockedBy=typeof metadata.blocked_by=="string"?metadata.blocked_by.trim():"",hadBlockedBy=metadata.blocked_by!==void 0,dependencies=metadata.dependencies??[],predecessorEdges=dependencies.filter(dependency=>dependency.kind==="blocked_by"),hadBlockedReason=metadata.blocked_reason!==void 0,changedFields=[];if(hadBlockedBy&&(delete metadata.blocked_by,changedFields.push("blocked_by")),hadBlockedReason&&(delete metadata.blocked_reason,changedFields.push("blocked_reason")),policy.orderingEdges==="remove"&&predecessorEdges.length>0){const removed=new Set(predecessorEdges),retained=dependencies.filter(dependency=>!removed.has(dependency));retained.length>0?metadata.dependencies=retained:delete metadata.dependencies,changedFields.push("dependencies")}if(policy.orderingEdges==="remove")return{changedFields,warnings:[...previousBlockedBy?[`closed_cleared_blocked_by:${metadata.id}:${previousBlockedBy}`]:[],...predecessorEdges.length>0?[`closed_removed_predecessors:${metadata.id}:${predecessorEdges.map(edge=>edge.id).join(",")}`,`closed_removed_predecessors_count:${metadata.id}:${predecessorEdges.length}`]:[]]};const blockerIds=[...new Set([...previousBlockedBy?[previousBlockedBy]:[],...predecessorEdges.map(dependency=>dependency.id)])];return blockerIds.length===0?{changedFields,warnings:[]}:{changedFields,warnings:[`closed_preserved_predecessors:${metadata.id}:${blockerIds.join(",")}`]}}export{DEFAULT_TERMINAL_TRANSITION_POLICY,applyTerminalOrderingPolicy,requireTerminalReason,requireTerminalReasonWithRecovery,resolveTerminalReason};
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="1430dcf8-9363-556d-aa33-184cea5421f9")}catch{}})();import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";const DEFAULT_TERMINAL_TRANSITION_POLICY=Object.freeze({requireCloseReason:!0,orderingEdges:"preserve"});function resolveTerminalReason(input){const candidates=[{source:"explicit",value:input.explicit},{source:"duplicate",value:input.duplicateOf===void 0?void 0:`Duplicate of ${input.duplicateOf}`},{source:"resolution",value:input.resolution},{source:"message",value:input.message}];for(const candidate of candidates){const normalized=candidate.value?.trim();if(normalized)return{closeReason:normalized,source:candidate.source}}return{source:"none"}}function requireTerminalReason(input,required){return requireTerminalReasonWithRecovery(input,required,{operation:"close"})}function requireTerminalReasonWithRecovery(input,required,recovery){const resolution=resolveTerminalReason(input);if(!required||resolution.closeReason!==void 0)return resolution;const examples=recovery.operation==="create"?[`pm create --title "<title>" --type <type> --status ${recovery.status??"closed"} --close-reason "<closing summary>"`,`pm create --title "<title>" --type <type> --status ${recovery.status??"closed"} --resolution "<resolution summary>"`,"pm create --stdin-json < item.json"]:['pm close <id> "Done: <what changed and why>"','pm close <id> --reason "<closing summary>"','pm close <id> -m "<closing summary>"',"pm close <id> --duplicate-of <canonical-id>"];throw new PmCliError("Close reason text is required because governance.require_close_reason is enabled",EXIT_CODE.USAGE,{code:"close_reason_required",required:"Provide an author-controlled closing summary as the reason, message, resolution, or duplicate target.",why:"governance.require_close_reason is enabled, so tools must not invent immutable closure evidence.",examples,nextSteps:[`Re-run the ${recovery.operation} operation with a closing summary.`,"To stop requiring reasons, run: pm config set governance-require-close-reason --policy disabled"]})}function applyTerminalOrderingPolicy(metadata,policy){const previousBlockedBy=typeof metadata.blocked_by=="string"?metadata.blocked_by.trim():"",hadBlockedBy=metadata.blocked_by!==void 0,dependencies=metadata.dependencies??[],predecessorEdges=dependencies.filter(dependency=>dependency.kind==="blocked_by"),hadBlockedReason=metadata.blocked_reason!==void 0,changedFields=[];if(hadBlockedBy&&(delete metadata.blocked_by,changedFields.push("blocked_by")),hadBlockedReason&&(delete metadata.blocked_reason,changedFields.push("blocked_reason")),policy.orderingEdges==="remove"&&predecessorEdges.length>0){const removed=new Set(predecessorEdges),retained=dependencies.filter(dependency=>!removed.has(dependency));retained.length>0?metadata.dependencies=retained:delete metadata.dependencies,changedFields.push("dependencies")}if(policy.orderingEdges==="remove")return{changedFields,warnings:[...previousBlockedBy?[`closed_cleared_blocked_by:${metadata.id}:${previousBlockedBy}`]:[],...predecessorEdges.length>0?[`closed_removed_predecessors:${metadata.id}:${predecessorEdges.map(edge=>edge.id).join(",")}`,`closed_removed_predecessors_count:${metadata.id}:${predecessorEdges.length}`]:[]]};const blockerIds=[...new Set([...previousBlockedBy?[previousBlockedBy]:[],...predecessorEdges.map(dependency=>dependency.id)])];return blockerIds.length===0?{changedFields,warnings:[]}:{changedFields,warnings:[`closed_preserved_predecessors:${metadata.id}:${blockerIds.join(",")}`]}}export{DEFAULT_TERMINAL_TRANSITION_POLICY,applyTerminalOrderingPolicy,requireTerminalReason,requireTerminalReasonWithRecovery,resolveTerminalReason};
 //# sourceMappingURL=lifecycle-policy.js.map

package/dist/sdk/mutation-guard.d.ts

@@ -4,7 +4,8 @@
  * Provides SDK-first pre-write provenance and secret-detection guardrails for
  * CLI, MCP, and package-owned mutation dispatchers.
  */
-import { SECRET_RULES } from "../core/shared/secret-rules.js";
+import { SECRET_RULES,type SecretNormalizationKind } from "../core/shared/secret-rules.js";
+export type { SecretNormalizationKind } from "../core/shared/secret-rules.js";
 /** Configurable handling mode for credential-shaped mutation content. */
 export type SecretGuardMode = "off" | "advise" | "block";
 /** Settings consumed by the shared mutation guard. */
@@ -22,6 +23,10 @@ export interface SecretGuardFinding {
 rule:(typeof SECRET_RULES)[number]["mutationRule"];
 /** Object path or argument index containing the match. */
 path:string;
+/** Detection-only transformations, without original or decoded coordinate values. */
+normalizations?:SecretNormalizationKind[];
+/** Remaining encoded input exceeded the finite inspection envelope and requires explicit review. */
+normalization_incomplete?:true;
 }
 /** Result of a non-blocking or bypassed mutation guard evaluation. */
 export interface MutationGuardResult {

package/dist/sdk/mutation-guard.js

@@ -1,2 +1,2 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="b75bf20f-d341-5fa2-943d-db02211ca80d")}catch{}})();import{SECRET_RULES,acceptsSecretMatch}from"../core/shared/secret-rules.js";import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";const PM_MUTATION_ACTION_CONTRACTS=[{action:"append",history_scope:"item"},{action:"claim",history_scope:"item"},{action:"close",history_scope:"item"},{action:"close-many",history_scope:"item"},{action:"close-task",history_scope:"item"},{action:"comments",history_scope:"conditional"},{action:"config",history_scope:"conditional"},{action:"copy",history_scope:"item"},{action:"create",history_scope:"item"},{action:"delete",history_scope:"item"},{action:"deps",history_scope:"conditional"},{action:"discover",history_scope:"item"},{action:"docs",history_scope:"conditional"},{action:"files",history_scope:"conditional"},{action:"focus",history_scope:"conditional"},{action:"gc",history_scope:"conditional"},{action:"history-compact",history_scope:"history"},{action:"history-author-acknowledge",history_scope:"workspace"},{action:"history-redact",history_scope:"history"},{action:"history-repair",history_scope:"history"},{action:"init",history_scope:"workspace"},{action:"install",history_scope:"conditional"},{action:"learnings",history_scope:"conditional"},{action:"notes",history_scope:"conditional"},{action:"package",history_scope:"conditional"},{action:"pause-task",history_scope:"item"},{action:"plan",history_scope:"conditional"},{action:"profile",history_scope:"conditional"},{action:"release",history_scope:"item"},{action:"restore",history_scope:"item"},{action:"schema",history_scope:"conditional"},{action:"start-task",history_scope:"item"},{action:"templates",history_scope:"conditional"},{action:"test",history_scope:"conditional"},{action:"test-all",history_scope:"conditional"},{action:"update",history_scope:"item"},{action:"update-many",history_scope:"item"},{action:"upgrade",history_scope:"conditional"}],MUTATION_ACTION_CONTRACTS_BY_NAME=new Map(PM_MUTATION_ACTION_CONTRACTS.map(contract=>[contract.action,contract]));function stringLeaves(value,path="$",seen=new WeakSet){return typeof value=="string"?[{path,value}]:typeof value!="object"||value===null?[]:seen.has(value)?[]:(seen.add(value),Array.isArray(value)?value.flatMap((entry,index)=>stringLeaves(entry,`${path}[${index}]`,seen)):Object.entries(value).flatMap(([key,entry])=>stringLeaves(entry,`${path}.${key}`,seen)))}function scanMutationSecrets(payload){const findings=[];for(const leaf of stringLeaves(payload))for(const rule of SECRET_RULES){rule.regex.lastIndex=0;for(const match of leaf.value.matchAll(rule.regex))if(acceptsSecretMatch(rule,match)){findings.push({rule:rule.mutationRule,path:leaf.path});break}}return findings.filter((finding,index,all)=>all.findIndex(candidate=>candidate.rule===finding.rule&&candidate.path===finding.path)===index)}function evaluateMutationGuard(options){const author=options.author.trim()||"unknown";if(options.settings.require_attributed_author&&author.toLowerCase()==="unknown")throw new PmCliError("Mutation author is required by workspace policy.",EXIT_CODE.USAGE,{code:"mutation_author_required",required:"Pass --author <id>, set PM_AUTHOR, or configure author_default.",nextSteps:["Retry with --author <stable-agent-id>.","Set PM_AUTHOR for this agent session."]});if(options.settings.secret_guard==="off")return{author,findings:[],warnings:[],override_applied:!1};let findings;try{findings=scanMutationSecrets(options.payload)}catch{return{author,findings:[],warnings:["secret_guard_scan_failed_open"],override_applied:!1}}if(findings.length===0)return{author,findings,warnings:[],override_applied:!1};const ruleSummary=[...new Set(findings.map(finding=>finding.rule))].sort().join(",");if(options.settings.secret_guard==="block"&&options.force!==!0)throw new PmCliError(`Mutation blocked by secret guard (${ruleSummary}). No detected value was logged.`,EXIT_CODE.CONFLICT,{code:"mutation_secret_guard_blocked",required:"Remove the credential-shaped content or retry with --force after explicit review.",nextSteps:["Replace the value with a secret-manager reference.","Use pm history-redact if equivalent content already entered history."],recovery:{recovery_mode:"compact",attempted_command:"pm <mutation> [REDACTED]",normalized_args:["[REDACTED]"],suggested_retry:"Remove credential-shaped content, then retry the mutation."}});return{author,findings,warnings:[`secret_guard_detected:${findings.length}:rules=${ruleSummary}`,...options.settings.secret_guard==="block"&&options.force===!0?["secret_guard_force_override"]:[]],override_applied:options.settings.secret_guard==="block"&&options.force===!0}}function isMutationAction(action){return MUTATION_ACTION_CONTRACTS_BY_NAME.has(action.trim().toLowerCase())}function listMutationActions(){return[...MUTATION_ACTION_CONTRACTS_BY_NAME.keys()].sort((left,right)=>left.localeCompare(right))}function getMutationActionContract(action){return MUTATION_ACTION_CONTRACTS_BY_NAME.get(action.trim().toLowerCase())}export{PM_MUTATION_ACTION_CONTRACTS,evaluateMutationGuard,getMutationActionContract,isMutationAction,listMutationActions,scanMutationSecrets};
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="d6059407-bf03-5ae8-8b01-e3e7c5b28030")}catch{}})();import{SECRET_RULES,findSecretRuleMatches}from"../core/shared/secret-rules.js";import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";const PM_MUTATION_ACTION_CONTRACTS=[{action:"append",history_scope:"item"},{action:"claim",history_scope:"item"},{action:"close",history_scope:"item"},{action:"close-many",history_scope:"item"},{action:"close-task",history_scope:"item"},{action:"comments",history_scope:"conditional"},{action:"config",history_scope:"conditional"},{action:"copy",history_scope:"item"},{action:"create",history_scope:"item"},{action:"delete",history_scope:"item"},{action:"deps",history_scope:"conditional"},{action:"discover",history_scope:"item"},{action:"docs",history_scope:"conditional"},{action:"files",history_scope:"conditional"},{action:"focus",history_scope:"conditional"},{action:"gc",history_scope:"conditional"},{action:"history-compact",history_scope:"history"},{action:"history-author-acknowledge",history_scope:"workspace"},{action:"history-redact",history_scope:"history"},{action:"history-repair",history_scope:"history"},{action:"init",history_scope:"workspace"},{action:"install",history_scope:"conditional"},{action:"learnings",history_scope:"conditional"},{action:"notes",history_scope:"conditional"},{action:"package",history_scope:"conditional"},{action:"pause-task",history_scope:"item"},{action:"plan",history_scope:"conditional"},{action:"profile",history_scope:"conditional"},{action:"release",history_scope:"item"},{action:"restore",history_scope:"item"},{action:"schema",history_scope:"conditional"},{action:"start-task",history_scope:"item"},{action:"templates",history_scope:"conditional"},{action:"test",history_scope:"conditional"},{action:"test-all",history_scope:"conditional"},{action:"update",history_scope:"item"},{action:"update-many",history_scope:"item"},{action:"upgrade",history_scope:"conditional"}],MUTATION_ACTION_CONTRACTS_BY_NAME=new Map(PM_MUTATION_ACTION_CONTRACTS.map(contract=>[contract.action,contract]));function stringLeaves(value,path="$",seen=new WeakSet){return typeof value=="string"?[{path,value}]:typeof value!="object"||value===null?[]:seen.has(value)?[]:(seen.add(value),Array.isArray(value)?value.flatMap((entry,index)=>stringLeaves(entry,`${path}[${index}]`,seen)):Object.entries(value).flatMap(([key,entry])=>stringLeaves(entry,`${path}.${key}`,seen)))}function preflightRuleMatch(rule,value){const matches=findSecretRuleMatches(rule,value),first=matches.next().value;if(!first||rule.mutationRule!=="absolute_home_path"||first.normalization_incomplete)return first;for(const later of matches)if(later.normalization_incomplete)return{...first,normalizations:[...new Set([first.normalizations,later.normalizations].flatMap(kinds=>kinds??[]))],normalization_incomplete:!0};return first}function scanMutationSecrets(payload){const findings=[];for(const leaf of stringLeaves(payload))for(const rule of SECRET_RULES){const match=preflightRuleMatch(rule,leaf.value);if(match){const finding={rule:rule.mutationRule,path:leaf.path};match.normalizations&&(finding.normalizations=match.normalizations),match.normalization_incomplete&&(finding.normalization_incomplete=!0),findings.push(finding)}}return findings.filter((finding,index,all)=>all.findIndex(candidate=>candidate.rule===finding.rule&&candidate.path===finding.path)===index)}function evaluateMutationGuard(options){const author=options.author.trim()||"unknown";if(options.settings.require_attributed_author&&author.toLowerCase()==="unknown")throw new PmCliError("Mutation author is required by workspace policy.",EXIT_CODE.USAGE,{code:"mutation_author_required",required:"Pass --author <id>, set PM_AUTHOR, or configure author_default.",nextSteps:["Retry with --author <stable-agent-id>.","Set PM_AUTHOR for this agent session."]});if(options.settings.secret_guard==="off")return{author,findings:[],warnings:[],override_applied:!1};let findings;try{findings=scanMutationSecrets(options.payload)}catch{return{author,findings:[],warnings:["secret_guard_scan_failed_open"],override_applied:!1}}if(findings.length===0)return{author,findings,warnings:[],override_applied:!1};const ruleSummary=[...new Set(findings.map(finding=>finding.rule))].sort().join(",");if(options.settings.secret_guard==="block"&&options.force!==!0)throw new PmCliError(`Mutation blocked by secret guard (${ruleSummary}). No detected value was logged.`,EXIT_CODE.CONFLICT,{code:"mutation_secret_guard_blocked",required:"Remove the credential-shaped content or retry with --force after explicit review.",nextSteps:["Replace the value with a secret-manager reference.","Use pm history-redact if equivalent content already entered history."],recovery:{recovery_mode:"compact",attempted_command:"pm <mutation> [REDACTED]",normalized_args:["[REDACTED]"],suggested_retry:"Remove credential-shaped content, then retry the mutation."}});return{author,findings,warnings:[`secret_guard_detected:${findings.length}:rules=${ruleSummary}`,...options.settings.secret_guard==="block"&&options.force===!0?["secret_guard_force_override"]:[]],override_applied:options.settings.secret_guard==="block"&&options.force===!0}}function isMutationAction(action){return MUTATION_ACTION_CONTRACTS_BY_NAME.has(action.trim().toLowerCase())}function listMutationActions(){return[...MUTATION_ACTION_CONTRACTS_BY_NAME.keys()].sort((left,right)=>left.localeCompare(right))}function getMutationActionContract(action){return MUTATION_ACTION_CONTRACTS_BY_NAME.get(action.trim().toLowerCase())}export{PM_MUTATION_ACTION_CONTRACTS,evaluateMutationGuard,getMutationActionContract,isMutationAction,listMutationActions,scanMutationSecrets};
 //# sourceMappingURL=mutation-guard.js.map

package/dist/sdk/output/fit-envelope.d.ts

@@ -0,0 +1,98 @@
+/** Deterministic admission policy; neither policy reorders or splits rows. */
+export type OutputEnvelopeFitPolicy = "prefix" | "skip";
+/** SDK-owned receipt included in every measured envelope as output_fit. */
+export interface OutputEnvelopeFitReceipt {
+/** Receipt schema version. */
+version:1;
+/** Admission policy applied in caller order. */
+policy:OutputEnvelopeFitPolicy;
+/** Number of rows offered before fitting. */
+total_candidates:number;
+/** Original positions of the retained rows. */
+included_indices:readonly number[];
+/** Number of whole rows withheld by the policy. */
+omitted_count:number;
+/** Binding ceiling in the caller's token estimator units. */
+token_budget:number;
+/** Greatest complete-envelope estimate across all required renderers. */
+estimated_tokens:number;
+/** Greatest UTF-8 byte count across all required renderers. */
+output_bytes:number;
+}
+/** Envelope with the reserved, SDK-owned accounting and omission receipt. */
+export type FittedOutputEnvelope<Envelope> = Omit<Envelope,"output_fit"> & {
+/** Self-accounting receipt, including its own bytes and framing. */
+readonly output_fit:Readonly<OutputEnvelopeFitReceipt>;
+};
+/** One complete rendering, ready to emit without reserializing or reframing. */
+export interface OutputEnvelopeRendering {
+/** Caller-selected transport identity. */
+name:string;
+/** Complete output, including any caller-supplied newline or framing. */
+text:string;
+/** UTF-8 bytes of text, including the receipt. */
+bytes:number;
+/** Estimate of text under the selected estimator. */
+estimated_tokens:number;
+}
+/** Actual fitting work, kept outside the measured output to avoid self-counting. */
+export interface OutputEnvelopeFitWork {
+/** Candidate admission trials performed, excluding the minimum envelope. */
+evaluated_candidates:number;
+/** Renderer calls across all fixed-point passes and admission trials. */
+render_calls:number;
+/** Hard ceiling on renderer calls. */
+max_render_calls:number;
+}
+/** Explicit failure to produce a verified packet; no oversized output is returned. */
+export declare class OutputEnvelopeFitError extends RangeError {
+/** Stable refusal reason suitable for package-specific error translation. */
+readonly code:"output_envelope_infeasible" | "output_envelope_work_limit" | "output_envelope_unstable";
+/** Work completed before refusal. */
+readonly work:Readonly<OutputEnvelopeFitWork>;
+/** Measured minimum-envelope estimate when the budget is infeasible. */
+readonly minimum_tokens:number | undefined;
+/** Capture immutable refusal evidence without serializing caller data. */
+constructor(code:OutputEnvelopeFitError["code"],work:OutputEnvelopeFitWork,minimumTokens?:number);
+}
+/** Caller-owned envelope construction, renderers and finite work controls. */
+export interface FitOutputEnvelopeOptions<Row,Envelope extends Record<string,unknown>> {
+/** Maximum complete-envelope estimate accepted by every required renderer. */
+tokenBudget:number;
+/** Preserve a prefix by default; skip may retain later smaller rows. */
+policy?:OutputEnvelopeFitPolicy;
+/** Construct mandatory domain metadata; output_fit is reserved and overwritten by the SDK. Must be pure and deterministic. */
+buildEnvelope:(rows:readonly Row[],receipt:Readonly<OutputEnvelopeFitReceipt>) => Envelope;
+/** Nonempty set of pure deterministic renderers, including all output framing. */
+renderers:Readonly<Record<string,(envelope:FittedOutputEnvelope<Envelope>) => string>>;
+/** Estimate the exact rendered text; defaults to ceil(UTF-8 bytes / 4). Stronger estimators may be supplied. */
+estimateTokens?:(text:string) => number;
+/** Hard renderer-call ceiling; defaults to 10,000. */
+maxRenderCalls?:number;
+/** Fixed-point pass ceiling per admission trial; defaults to 16. */
+maxStabilizationPasses?:number;
+}
+/** Verified envelope and cached renderings; work is diagnostic, not emitted packet data. */
+export interface OutputEnvelopeFitResult<Row,Envelope> {
+/** Whole caller rows retained in original order. */
+rows:readonly Row[];
+/** Domain metadata plus the exact measured receipt. */
+envelope:FittedOutputEnvelope<Envelope>;
+/** Cached complete outputs; every rendering satisfies the budget. */
+renderings:readonly OutputEnvelopeRendering[];
+/** True only when all candidates were retained. */
+complete:boolean;
+/** Actual bounded fitting work. */
+work:Readonly<OutputEnvelopeFitWork>;
+}
+/**
+ * Fit whole ordered rows against every required complete rendering. First prove
+ * the empty mandatory envelope fits, then admit rows under prefix or skip
+ * policy. No monotonic-size assumption or binary search is used. Callbacks
+ * must be pure and return promptly; call/pass ceilings bound SDK fitting work,
+ * not arbitrary callback execution time. Emit the cached renderings directly.
+ *
+ * @throws {OutputEnvelopeFitError} When the minimum envelope is too large,
+ * accounting fails to stabilize, or the renderer-call ceiling is exhausted.
+ */
+export declare function fitOutputEnvelope<Row,Envelope extends Record<string,unknown>>(candidates:readonly Row[],options:FitOutputEnvelopeOptions<Row,Envelope>):OutputEnvelopeFitResult<Row,Envelope>;

package/dist/sdk/output/fit-envelope.js

@@ -0,0 +1,2 @@
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="f698608a-2f39-5972-b24b-93287af6b373")}catch{}})();import{estimatePmOutputTokens}from"../cli-contracts/agent-output-contracts.js";class OutputEnvelopeFitError extends RangeError{code;work;minimum_tokens;constructor(code,work,minimumTokens){super(code),this.name="OutputEnvelopeFitError",this.code=code,this.work=Object.freeze({...work}),this.minimum_tokens=minimumTokens}}function assertPositiveInteger(value,name){if(!Number.isSafeInteger(value)||value<1)throw new RangeError(`${name} must be a positive safe integer`)}function renderEnvelope(envelope,renderers,estimateTokens,work){return renderers.map(([name,render])=>{if(work.render_calls>=work.max_render_calls)throw new OutputEnvelopeFitError("output_envelope_work_limit",work);work.render_calls+=1;const text=render(envelope);if(typeof text!="string")throw new TypeError("Envelope renderers must return strings");const estimatedTokens=estimateTokens(text);if(!Number.isSafeInteger(estimatedTokens)||estimatedTokens<0)throw new RangeError("Envelope token estimates must be non-negative safe integers");return{name,text,bytes:Buffer.byteLength(text,"utf8"),estimated_tokens:estimatedTokens}})}function stabilizeEnvelope(rows,initial,options,work){let receipt=initial;const renderers=Object.entries(options.renderers),estimateTokens=options.estimateTokens??(text=>estimatePmOutputTokens(Buffer.byteLength(text,"utf8")));for(let pass=0;pass<(options.maxStabilizationPasses??16);pass+=1){const frozenReceipt=Object.freeze({...receipt}),envelope={...options.buildEnvelope(rows,frozenReceipt),output_fit:frozenReceipt},renderings=renderEnvelope(envelope,renderers,estimateTokens,work),bytes=Math.max(...renderings.map(rendering=>rendering.bytes)),tokens=Math.max(...renderings.map(rendering=>rendering.estimated_tokens));if(bytes===receipt.output_bytes&&tokens===receipt.estimated_tokens)return{envelope,renderings};receipt={...receipt,output_bytes:bytes,estimated_tokens:tokens}}throw new OutputEnvelopeFitError("output_envelope_unstable",work)}function fitOutputEnvelope(candidates,options){assertPositiveInteger(options.tokenBudget,"tokenBudget"),assertPositiveInteger(options.maxRenderCalls??1e4,"maxRenderCalls"),assertPositiveInteger(options.maxStabilizationPasses??16,"maxStabilizationPasses");const policy=options.policy??"prefix";if(policy!=="prefix"&&policy!=="skip")throw new TypeError("Unknown output envelope fit policy");if(Object.entries(options.renderers).length===0||Object.entries(options.renderers).some(([name,render])=>!name.trim()||typeof render!="function"))throw new TypeError("Envelope fitting requires named callable renderers");const work={evaluated_candidates:0,render_calls:0,max_render_calls:options.maxRenderCalls??1e4};let rows=[],included=[];const receiptFor=indices=>({version:1,policy,total_candidates:candidates.length,included_indices:Object.freeze([...indices]),omitted_count:candidates.length-indices.length,token_budget:options.tokenBudget,estimated_tokens:0,output_bytes:0});let fitted=stabilizeEnvelope(rows,receiptFor(included),options,work);if(fitted.envelope.output_fit.estimated_tokens>options.tokenBudget)throw new OutputEnvelopeFitError("output_envelope_infeasible",work,fitted.envelope.output_fit.estimated_tokens);for(const[index,candidate]of candidates.entries()){work.evaluated_candidates+=1;const trialRows=[...rows,candidate],trialIndices=[...included,index],trial=stabilizeEnvelope(trialRows,receiptFor(trialIndices),options,work);if(trial.envelope.output_fit.estimated_tokens<=options.tokenBudget)rows=trialRows,included=trialIndices,fitted=trial;else if(policy==="prefix")break}return{rows,...fitted,complete:rows.length===candidates.length,work:Object.freeze({...work})}}export{OutputEnvelopeFitError,fitOutputEnvelope};
+//# sourceMappingURL=fit-envelope.js.map