@unbrained/pm-cli 2026.10.9 → 2026.10.11

package/dist/sdk/structured-mutations.d.ts

@@ -1,4 +1,5 @@
 import type { BulkItemMutation } from "./item-transaction.js";
+import { type RuntimeFieldDefinitionResolved } from "../core/schema/runtime-schema.js";
 /** Controls for resolving one versioned mutation document. */
 export interface ResolveItemMutationDocumentOptions {
     /** Stable transaction identity used to derive replay-safe create ids. */
@@ -38,7 +39,10 @@ export declare function resolveItemMutationDocument(input: string, options: Reso
 /**
  * Convert a direct item JSON document or `pm get --json` envelope into the
  * create/update option shape. Explicit CLI flags override document values.
+ * Supply the workspace's resolved schema fields to route metadata keys through
+ * declared option names and aliases. Extension assignments retain raw strings
+ * and JSON containers, with explicit assignments applied after document values.
  */
-export declare function itemDocumentToMutationOptions(input: string, mode: "create" | "update", explicitOptions?: Record<string, unknown>): Record<string, unknown>;
+export declare function itemDocumentToMutationOptions(input: string, mode: "create" | "update", explicitOptions?: Record<string, unknown>, runtimeFields?: readonly RuntimeFieldDefinitionResolved[]): Record<string, unknown>;
 /** Validate an already-decoded MCP mutation array through the same strict parser as CLI stdin. */
 export declare function validateItemMutationRows(value: unknown): BulkItemMutation[];

package/dist/sdk/structured-mutations.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]="62e0ef49-30c8-56e0-985e-49c83d14695e")}catch{}})();import crypto from"node:crypto";import{normalizeItemId,normalizePrefix}from"../core/item/id.js";import{preserveMutationStdinTokenLiterals}from"../core/item/parse.js";import{EXIT_CODE,ITEM_PROJECT_CONTEXT_KEYS}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";import{levenshteinDistanceWithinLimit}from"../core/shared/levenshtein.js";import{CLOSE_FLAG_CONTRACTS,RELEASE_FLAG_CONTRACTS}from"./cli-contracts/flag-contracts.js";import{CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS,UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS}from"./cli-contracts/commander-mutation-options.js";const MUTATION_ROW_KEYS=["op","id","reason","options"],REFERENCED_MUTATION_ROW_KEYS=[...MUTATION_ROW_KEYS,"ref"],MUTATION_DOCUMENT_KEYS=["schema_version","mutations"],MUTATION_REFERENCE_SOURCE="[a-z][a-z0-9._-]{0,63}",MUTATION_REFERENCE_PATTERN=new RegExp(`^${MUTATION_REFERENCE_SOURCE}$`,"u"),MUTATION_DEPENDENCY_REFERENCE_PATTERN=new RegExp(`(^|,)id=@(${MUTATION_REFERENCE_SOURCE})(?=,|$)`,"gu"),flagToOptionKey=flag=>flag.slice(2).replaceAll(/-([a-z])/gu,(_match,letter)=>letter.toUpperCase()),ITEM_ENVELOPE_KEYS=["item","linked","schedule","claim_state","children","omission_receipt","row_contract","context_intent"],READ_ONLY_ITEM_KEYS=new Set(["created_at","updated_at","closed_at","version","format_version","path","author","collection_counts","notes_count","tests_count"]),UPDATE_READ_ONLY_ITEM_KEYS=new Set([...READ_ONLY_ITEM_KEYS,"completed_at","id"]),ITEM_FIELD_KEYS=new Set(["id","title","description","type","status","priority","tags","body","deadline","estimated_minutes","acceptance_criteria","definition_of_ready","order","rank","assignee",...ITEM_PROJECT_CONTEXT_KEYS,"affected_version","fixed_version","component","regression","customer_impact","close_reason","completed_at","dependencies","comments","notes","learnings","files","tests","docs","reminders","events","type_options"]),MUTATION_OPTION_KEYS={create:CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS.map(contract=>contract.target),update:UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS.map(contract=>contract.target),close:CLOSE_FLAG_CONTRACTS.map(contract=>flagToOptionKey(contract.flag)).filter(key=>key!=="reason"),release:RELEASE_FLAG_CONTRACTS.map(contract=>flagToOptionKey(contract.flag))};function parseAtomicMutationControls(value){const controls={},compensation=value.createCompensation;if(compensation!==void 0){if(compensation!=="close"&&compensation!=="delete")throw new PmCliError("createCompensation must be close or delete.",EXIT_CODE.USAGE);controls.createCompensation=compensation}for(const key of["lockTtlSeconds","lockWaitMs"]){const raw=value[key];if(raw===void 0)continue;const parsed=typeof raw=="number"||typeof raw=="string"&&raw.trim().length>0?Number(raw):Number.NaN;if(!Number.isSafeInteger(parsed)||parsed<=0)throw new PmCliError(`${key} must be a positive safe integer.`,EXIT_CODE.USAGE);controls[key]=parsed}return controls}function isPlainObject(value){if(typeof value!="object"||value===null||Array.isArray(value))return!1;const prototype=Object.getPrototypeOf(value);return prototype===Object.prototype||prototype===null}function nearestKey(key,candidates){const limit=Math.max(1,Math.min(3,Math.floor(key.length/4)+1));let best;for(const candidate of candidates){const distance=levenshteinDistanceWithinLimit(key,candidate,limit);distance!==null&&(best===void 0||distance<best.distance)&&(best={key:candidate,distance})}return best?.key}function unknownKeyError(scope,key,candidates){const suggestion=nearestKey(key,candidates);return new PmCliError(suggestion===void 0?`${scope} does not recognize key "${key}". Allowed keys: ${candidates.join(", ")}.`:`${scope} does not recognize key "${key}". Did you mean "${suggestion}"?`,EXIT_CODE.USAGE,{code:"stdin_json_unknown_key",required:`Use documented ${scope} keys only.`,why:"Strict structured input prevents silent typos from creating incomplete or unintended mutations.",nextSteps:[suggestion===void 0?`Remove or correct "${key}".`:`Replace "${key}" with "${suggestion}".`]})}function parseJsonValue(input,label){try{return JSON.parse(input)}catch(error){const detail=error instanceof Error?error.message:String(error);throw new PmCliError(`${label} must be valid JSON: ${detail}`,EXIT_CODE.USAGE,{code:"stdin_json_invalid",required:`Pipe one valid JSON ${label.toLowerCase()} into stdin.`,why:"Structured mutation input must parse deterministically before any tracker write begins."})}}function validateMutationObject(value,index){if(!isPlainObject(value))throw new PmCliError(`Mutation ${index+1} must be an object.`,EXIT_CODE.USAGE);for(const key of Object.keys(value))if(!MUTATION_ROW_KEYS.includes(key))throw unknownKeyError(`mutation ${index+1}`,key,MUTATION_ROW_KEYS);return value}function validateMutationOptions(options,op,index){if(options!==void 0){if(!isPlainObject(options))throw new PmCliError(`Mutation ${index+1} options must be an object.`,EXIT_CODE.USAGE);for(const key of Object.keys(options))if(!MUTATION_OPTION_KEYS[op].includes(key))throw unknownKeyError(`mutation ${index+1} ${op} options`,key,MUTATION_OPTION_KEYS[op]);return options}}function validateMutationRow(value,index){const mutation=validateMutationObject(value,index),{op,id,reason}=mutation;if(op!=="create"&&op!=="update"&&op!=="close"&&op!=="release")throw new PmCliError(`Mutation ${index+1} op must be create, update, close, or release.`,EXIT_CODE.USAGE);const options=validateMutationOptions(mutation.options,op,index);if(typeof id!="string"||id.trim().length===0)throw new PmCliError(`Mutation ${index+1} requires a non-empty id.`,EXIT_CODE.USAGE);const normalizedId=id.trim();if(op==="close"){if(typeof reason!="string"||reason.trim().length===0)throw new PmCliError(`Mutation ${index+1} close requires a non-empty reason.`,EXIT_CODE.USAGE);return{op,id:normalizedId,reason:reason.trim(),...options===void 0?{}:{options}}}if(op==="release")return{op,id:normalizedId,...options===void 0?{}:{options}};if(!isPlainObject(options))throw new PmCliError(`Mutation ${index+1} ${op} requires an options object.`,EXIT_CODE.USAGE);return{op,id:normalizedId,options}}function parseItemMutationBatch(input){const parsed=parseJsonValue(input,"Mutation batch"),rows=Array.isArray(parsed)?parsed:isPlainObject(parsed)&&Array.isArray(parsed.mutations)?parsed.mutations:void 0;if(rows===void 0||rows.length===0)throw new PmCliError("Mutation batch must be a non-empty JSON array or an object with a non-empty mutations array.",EXIT_CODE.USAGE);return rows.map((row,index)=>{const mutation=validateMutationRow(row,index);return mutation.options!==void 0&&preserveMutationStdinTokenLiterals(mutation.options),mutation})}function deriveReferencedItemId(transactionId,reference,idPrefix){const digest=crypto.createHash("sha256").update(transactionId).update("\0").update(reference).digest("hex"),token=BigInt(`0x${digest.slice(0,16)}`).toString(36).padStart(13,"0").slice(-12);return`${normalizePrefix(idPrefix)}${token}`}function replaceExactMutationReference(value,references){if(typeof value!="string"||!value.startsWith("@"))return value;const reference=value.slice(1),resolved=references[reference];if(resolved===void 0)throw new PmCliError(`Unknown mutation reference "${value}".`,EXIT_CODE.USAGE);return resolved}function replaceDependencyReference(value,references){if(typeof value!="string")return value;const resolvedValue=value.replace(MUTATION_DEPENDENCY_REFERENCE_PATTERN,(_match,prefix,reference)=>{const resolved=references[reference];if(resolved===void 0)throw new PmCliError(`Unknown mutation reference "@${reference}".`,EXIT_CODE.USAGE);return`${prefix}id=${resolved}`});if(/(^|,)id=@/u.test(resolvedValue))throw new PmCliError(`Malformed mutation reference in dependency "${value}".`,EXIT_CODE.USAGE);return resolvedValue}function referencedAliases(value){return typeof value!="string"?[]:value.startsWith("@")?[value.slice(1)]:[...value.matchAll(MUTATION_DEPENDENCY_REFERENCE_PATTERN)].map(match=>match[1]).filter(reference=>reference!==void 0)}function assertAcyclicCreateReferences(rows){const graph=new Map;for(const row of rows){if(row.op!=="create"||typeof row.ref!="string")continue;const mutationOptions=isPlainObject(row.options)?row.options:{},dependencies=Array.isArray(mutationOptions.dep)?mutationOptions.dep:mutationOptions.dep===void 0?[]:[mutationOptions.dep];graph.set(row.ref,[mutationOptions.parent,mutationOptions.blockedBy,...dependencies].flatMap(referencedAliases))}const visiting=new Set,visited=new Set,visit=reference=>{if(visiting.has(reference))throw new PmCliError(`Mutation reference cycle includes "@${reference}".`,EXIT_CODE.USAGE);if(!visited.has(reference)){visiting.add(reference);for(const dependency of graph.get(reference))graph.has(dependency)&&visit(dependency);visiting.delete(reference),visited.add(reference)}};for(const reference of graph.keys())visit(reference)}function parseMutationDocumentRows(input){const parsed=parseJsonValue(input,"Mutation document"),envelope=Array.isArray(parsed)?{schema_version:1,mutations:parsed}:parsed;if(!isPlainObject(envelope))throw new PmCliError("Mutation document must be a JSON array or object.",EXIT_CODE.USAGE);for(const key of Object.keys(envelope))if(!MUTATION_DOCUMENT_KEYS.includes(key))throw unknownKeyError("mutation document",key,MUTATION_DOCUMENT_KEYS);if(envelope.schema_version!==void 0&&envelope.schema_version!==1)throw new PmCliError("Mutation document schema_version must be 1.",EXIT_CODE.USAGE);if(!Array.isArray(envelope.mutations)||envelope.mutations.length===0)throw new PmCliError("Mutation document requires a non-empty mutations array.",EXIT_CODE.USAGE);return envelope.mutations.map((row,index)=>{if(!isPlainObject(row))throw new PmCliError(`Mutation ${index+1} must be an object.`,EXIT_CODE.USAGE);for(const key of Object.keys(row))if(!REFERENCED_MUTATION_ROW_KEYS.includes(key))throw unknownKeyError(`mutation ${index+1}`,key,REFERENCED_MUTATION_ROW_KEYS);return{...row}})}function collectMutationReferences(rows,options){const references=Object.create(null);for(const[index,row]of rows.entries())if(row.ref!==void 0){if(row.op!=="create")throw new PmCliError(`Mutation ${index+1} ref is only valid for create operations.`,EXIT_CODE.USAGE);if(typeof row.ref!="string"||!MUTATION_REFERENCE_PATTERN.test(row.ref))throw new PmCliError(`Mutation ${index+1} ref must match ${MUTATION_REFERENCE_PATTERN.source}.`,EXIT_CODE.USAGE);if(references[row.ref]!==void 0)throw new PmCliError(`Duplicate mutation ref "${row.ref}".`,EXIT_CODE.USAGE);references[row.ref]=typeof row.id=="string"&&row.id.trim().length>0?normalizeItemId(row.id,options.idPrefix):deriveReferencedItemId(options.transactionId,row.ref,options.idPrefix)}return references}function resolveItemMutationDocument(input,options){const rows=parseMutationDocumentRows(input),references=collectMutationReferences(rows,options);assertAcyclicCreateReferences(rows);const resolvedRows=rows.map(row=>{const resolved={...row},reference=typeof resolved.ref=="string"?resolved.ref:void 0;if(delete resolved.ref,reference!==void 0?resolved.id=references[reference]:resolved.id=replaceExactMutationReference(resolved.id,references),isPlainObject(resolved.options)){const mutationOptions={...resolved.options};for(const key of["parent","blockedBy"])mutationOptions[key]!==void 0&&(mutationOptions[key]=replaceExactMutationReference(mutationOptions[key],references));Array.isArray(mutationOptions.dep)?mutationOptions.dep=mutationOptions.dep.map(entry=>replaceDependencyReference(entry,references)):mutationOptions.dep!==void 0&&(mutationOptions.dep=replaceDependencyReference(mutationOptions.dep,references)),resolved.options=mutationOptions}return resolved}),mutations=parseItemMutationBatch(JSON.stringify(resolvedRows)),createIds=mutations.filter(mutation=>mutation.op==="create").map(mutation=>mutation.id);if(new Set(createIds).size!==createIds.length)throw new PmCliError("Duplicate resolved create id in mutation document.",EXIT_CODE.USAGE);return{schema_version:1,mutations,references}}function serializePairs(value,keys){return keys.filter(key=>value[key]!==void 0&&value[key]!==null).map(key=>{const rendered=String(value[key]);return`${key}=${/[",\n\r\\]/u.test(rendered)?JSON.stringify(rendered):rendered}`}).join(",")}function serializeObjectArray(value,keys,label){if(value!==void 0){if(!Array.isArray(value)||!value.every(isPlainObject))throw new PmCliError(`${label} must be an array of objects.`,EXIT_CODE.USAGE);return value.map(entry=>serializePairs(entry,keys))}}function scalarItemOption(key,value){return key==="tags"&&Array.isArray(value)&&value.every(entry=>typeof entry=="string")?JSON.stringify(value):typeof value=="number"||typeof value=="boolean"?String(value):value}function appendFacetOptions(target,source,skipPersistedAnnotations=!1){const mappings=[["dependencies","dep",["id","kind","created_at","author","source_kind"]],["comments","comment",["text","created_at","author"]],["notes","note",["text","created_at","author"]],["learnings","learning",["text","created_at","author"]],["files","file",["path","scope","note"]],["tests","test",["command","scope","timeout_seconds"]],["docs","doc",["path","scope","note"]],["reminders","reminder",["at","text","created_at"]],["events","event",["start_at","end_at","title","location"]],["type_options","typeOption",["key","value"]]];for(const[sourceKey,targetKey,keys]of mappings){const sourceValue=source[sourceKey],serialized=serializeObjectArray(skipPersistedAnnotations&&["comments","notes","learnings"].includes(sourceKey)&&Array.isArray(sourceValue)?sourceValue.filter(entry=>!isPlainObject(entry)||entry.created_at===void 0):sourceValue,keys,sourceKey);serialized!==void 0&&serialized.length>0&&(target[targetKey]=serialized)}}function validateItemDocumentKeys(parsed,envelope){for(const key of Object.keys(parsed)){if(envelope){if(!ITEM_ENVELOPE_KEYS.includes(key))throw unknownKeyError("item envelope",key,ITEM_ENVELOPE_KEYS);continue}if(!ITEM_FIELD_KEYS.has(key)&&nearestKey(key,[...ITEM_FIELD_KEYS])===void 0&&nearestKey(key,ITEM_ENVELOPE_KEYS)==="item")throw unknownKeyError("item envelope",key,ITEM_ENVELOPE_KEYS)}}function resolveItemDocument(parsed){const envelope=Object.hasOwn(parsed,"item");validateItemDocumentKeys(parsed,envelope);const item=envelope?parsed.item:parsed;if(!isPlainObject(item))throw new PmCliError("Item document item must be an object.",EXIT_CODE.USAGE);return{item,...envelope&&isPlainObject(parsed.linked)?{linked:parsed.linked}:{}}}function appendItemDocumentEntry(documentOptions,key,value,mode){if(!(mode==="update"?UPDATE_READ_ONLY_ITEM_KEYS:READ_ONLY_ITEM_KEYS).has(key)){if(!ITEM_FIELD_KEYS.has(key)){if(nearestKey(key,[...ITEM_FIELD_KEYS])!==void 0)throw unknownKeyError("item document",key,[...ITEM_FIELD_KEYS]);const fields=Array.isArray(documentOptions.field)?documentOptions.field:[];fields.push(serializePairs({key,value:typeof value=="string"?value:JSON.stringify(value)},["key","value"])),documentOptions.field=fields;return}["dependencies","comments","notes","learnings","files","tests","docs","reminders","events","type_options"].includes(key)||(documentOptions[key.replaceAll(/_([a-z])/gu,(_match,letter)=>letter.toUpperCase())]=scalarItemOption(key,value))}}function itemDocumentToMutationOptions(input,mode,explicitOptions={}){const parsed=parseJsonValue(input,"Item document");if(!isPlainObject(parsed))throw new PmCliError("Item document must be a JSON object.",EXIT_CODE.USAGE);const{item,linked}=resolveItemDocument(parsed),documentOptions={};for(const[key,value]of Object.entries(item))appendItemDocumentEntry(documentOptions,key,value,mode);if(appendFacetOptions(documentOptions,item,mode==="update"),linked!==void 0&&appendFacetOptions(documentOptions,linked),mode==="update"){const annotations=Object.fromEntries(["comments","notes","learnings"].filter(key=>Object.hasOwn(item,key)).map(key=>[key,item[key].filter(entry=>isPlainObject(entry)&&entry.created_at!==void 0)]));Object.keys(annotations).length>0&&(documentOptions.documentAnnotationSnapshot=annotations)}return{...documentOptions,...Object.fromEntries(Object.entries(explicitOptions).filter(([,value])=>value!==void 0)),stdinJson:void 0}}function validateItemMutationRows(value){return parseItemMutationBatch(JSON.stringify(value))}export{itemDocumentToMutationOptions,parseAtomicMutationControls,parseItemMutationBatch,resolveItemMutationDocument,validateItemMutationRows};
+(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]="ccd80f77-f619-5cd8-a792-cc5d9c733ebf")}catch{}})();import crypto from"node:crypto";import{normalizeItemId,normalizePrefix}from"../core/item/id.js";import{preserveMutationStdinTokenLiterals}from"../core/item/parse.js";import{EXIT_CODE,ITEM_PROJECT_CONTEXT_KEYS}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";import{levenshteinDistanceWithinLimit}from"../core/shared/levenshtein.js";import{CLOSE_FLAG_CONTRACTS,RELEASE_FLAG_CONTRACTS}from"./cli-contracts/flag-contracts.js";import{CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS,UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS}from"./cli-contracts/commander-mutation-options.js";import{runtimeFieldOptionTarget}from"../core/schema/runtime-schema.js";import{readRuntimeFieldOptionValue}from"../core/schema/runtime-field-values.js";const MUTATION_ROW_KEYS=["op","id","reason","options"],REFERENCED_MUTATION_ROW_KEYS=[...MUTATION_ROW_KEYS,"ref"],MUTATION_DOCUMENT_KEYS=["schema_version","mutations"],MUTATION_REFERENCE_SOURCE="[a-z][a-z0-9._-]{0,63}",MUTATION_REFERENCE_PATTERN=new RegExp(`^${MUTATION_REFERENCE_SOURCE}$`,"u"),MUTATION_DEPENDENCY_REFERENCE_PATTERN=new RegExp(`(^|,)id=@(${MUTATION_REFERENCE_SOURCE})(?=,|$)`,"gu"),flagToOptionKey=flag=>flag.slice(2).replaceAll(/-([a-z])/gu,(_match,letter)=>letter.toUpperCase()),ITEM_ENVELOPE_KEYS=["item","linked","schedule","claim_state","children","omission_receipt","row_contract","context_intent"],READ_ONLY_ITEM_KEYS=new Set(["created_at","updated_at","closed_at","version","format_version","path","author","collection_counts","notes_count","tests_count"]),UPDATE_READ_ONLY_ITEM_KEYS=new Set([...READ_ONLY_ITEM_KEYS,"completed_at","id"]),ITEM_FIELD_KEYS=new Set(["id","title","description","type","status","priority","tags","body","deadline","estimated_minutes","acceptance_criteria","definition_of_ready","order","rank","assignee",...ITEM_PROJECT_CONTEXT_KEYS,"affected_version","fixed_version","component","regression","customer_impact","close_reason","completed_at","dependencies","comments","notes","learnings","files","tests","docs","reminders","events","type_options"]),MUTATION_OPTION_KEYS={create:CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS.map(contract=>contract.target),update:UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS.map(contract=>contract.target),close:CLOSE_FLAG_CONTRACTS.map(contract=>flagToOptionKey(contract.flag)).filter(key=>key!=="reason"),release:RELEASE_FLAG_CONTRACTS.map(contract=>flagToOptionKey(contract.flag))};function parseAtomicMutationControls(value){const controls={},compensation=value.createCompensation;if(compensation!==void 0){if(compensation!=="close"&&compensation!=="delete")throw new PmCliError("createCompensation must be close or delete.",EXIT_CODE.USAGE);controls.createCompensation=compensation}for(const key of["lockTtlSeconds","lockWaitMs"]){const raw=value[key];if(raw===void 0)continue;const parsed=typeof raw=="number"||typeof raw=="string"&&raw.trim().length>0?Number(raw):Number.NaN;if(!Number.isSafeInteger(parsed)||parsed<=0)throw new PmCliError(`${key} must be a positive safe integer.`,EXIT_CODE.USAGE);controls[key]=parsed}return controls}function isPlainObject(value){if(typeof value!="object"||value===null||Array.isArray(value))return!1;const prototype=Object.getPrototypeOf(value);return prototype===Object.prototype||prototype===null}function nearestKey(key,candidates){const limit=Math.max(1,Math.min(3,Math.floor(key.length/4)+1));let best;for(const candidate of candidates){const distance=levenshteinDistanceWithinLimit(key,candidate,limit);distance!==null&&(best===void 0||distance<best.distance)&&(best={key:candidate,distance})}return best?.key}function unknownKeyError(scope,key,candidates){const suggestion=nearestKey(key,candidates);return new PmCliError(suggestion===void 0?`${scope} does not recognize key "${key}". Allowed keys: ${candidates.join(", ")}.`:`${scope} does not recognize key "${key}". Did you mean "${suggestion}"?`,EXIT_CODE.USAGE,{code:"stdin_json_unknown_key",required:`Use documented ${scope} keys only.`,why:"Strict structured input prevents silent typos from creating incomplete or unintended mutations.",nextSteps:[suggestion===void 0?`Remove or correct "${key}".`:`Replace "${key}" with "${suggestion}".`]})}function parseJsonValue(input,label){try{return JSON.parse(input)}catch(error){const detail=error instanceof Error?error.message:String(error);throw new PmCliError(`${label} must be valid JSON: ${detail}`,EXIT_CODE.USAGE,{code:"stdin_json_invalid",required:`Pipe one valid JSON ${label.toLowerCase()} into stdin.`,why:"Structured mutation input must parse deterministically before any tracker write begins."})}}function validateMutationObject(value,index){if(!isPlainObject(value))throw new PmCliError(`Mutation ${index+1} must be an object.`,EXIT_CODE.USAGE);for(const key of Object.keys(value))if(!MUTATION_ROW_KEYS.includes(key))throw unknownKeyError(`mutation ${index+1}`,key,MUTATION_ROW_KEYS);return value}function validateMutationOptions(options,op,index){if(options!==void 0){if(!isPlainObject(options))throw new PmCliError(`Mutation ${index+1} options must be an object.`,EXIT_CODE.USAGE);for(const key of Object.keys(options))if(!MUTATION_OPTION_KEYS[op].includes(key))throw unknownKeyError(`mutation ${index+1} ${op} options`,key,MUTATION_OPTION_KEYS[op]);return options}}function validateMutationRow(value,index){const mutation=validateMutationObject(value,index),{op,id,reason}=mutation;if(op!=="create"&&op!=="update"&&op!=="close"&&op!=="release")throw new PmCliError(`Mutation ${index+1} op must be create, update, close, or release.`,EXIT_CODE.USAGE);const options=validateMutationOptions(mutation.options,op,index);if(typeof id!="string"||id.trim().length===0)throw new PmCliError(`Mutation ${index+1} requires a non-empty id.`,EXIT_CODE.USAGE);const normalizedId=id.trim();if(op==="close"){if(typeof reason!="string"||reason.trim().length===0)throw new PmCliError(`Mutation ${index+1} close requires a non-empty reason.`,EXIT_CODE.USAGE);return{op,id:normalizedId,reason:reason.trim(),...options===void 0?{}:{options}}}if(op==="release")return{op,id:normalizedId,...options===void 0?{}:{options}};if(!isPlainObject(options))throw new PmCliError(`Mutation ${index+1} ${op} requires an options object.`,EXIT_CODE.USAGE);return{op,id:normalizedId,options}}function parseItemMutationBatch(input){const parsed=parseJsonValue(input,"Mutation batch"),rows=Array.isArray(parsed)?parsed:isPlainObject(parsed)&&Array.isArray(parsed.mutations)?parsed.mutations:void 0;if(rows===void 0||rows.length===0)throw new PmCliError("Mutation batch must be a non-empty JSON array or an object with a non-empty mutations array.",EXIT_CODE.USAGE);return rows.map((row,index)=>{const mutation=validateMutationRow(row,index);return mutation.options!==void 0&&preserveMutationStdinTokenLiterals(mutation.options),mutation})}function deriveReferencedItemId(transactionId,reference,idPrefix){const digest=crypto.createHash("sha256").update(transactionId).update("\0").update(reference).digest("hex"),token=BigInt(`0x${digest.slice(0,16)}`).toString(36).padStart(13,"0").slice(-12);return`${normalizePrefix(idPrefix)}${token}`}function replaceExactMutationReference(value,references){if(typeof value!="string"||!value.startsWith("@"))return value;const reference=value.slice(1),resolved=references[reference];if(resolved===void 0)throw new PmCliError(`Unknown mutation reference "${value}".`,EXIT_CODE.USAGE);return resolved}function replaceDependencyReference(value,references){if(typeof value!="string")return value;const resolvedValue=value.replace(MUTATION_DEPENDENCY_REFERENCE_PATTERN,(_match,prefix,reference)=>{const resolved=references[reference];if(resolved===void 0)throw new PmCliError(`Unknown mutation reference "@${reference}".`,EXIT_CODE.USAGE);return`${prefix}id=${resolved}`});if(/(^|,)id=@/u.test(resolvedValue))throw new PmCliError(`Malformed mutation reference in dependency "${value}".`,EXIT_CODE.USAGE);return resolvedValue}function referencedAliases(value){return typeof value!="string"?[]:value.startsWith("@")?[value.slice(1)]:[...value.matchAll(MUTATION_DEPENDENCY_REFERENCE_PATTERN)].map(match=>match[1]).filter(reference=>reference!==void 0)}function assertAcyclicCreateReferences(rows){const graph=new Map;for(const row of rows){if(row.op!=="create"||typeof row.ref!="string")continue;const mutationOptions=isPlainObject(row.options)?row.options:{},dependencies=Array.isArray(mutationOptions.dep)?mutationOptions.dep:mutationOptions.dep===void 0?[]:[mutationOptions.dep];graph.set(row.ref,[mutationOptions.parent,mutationOptions.blockedBy,...dependencies].flatMap(referencedAliases))}const visiting=new Set,visited=new Set,visit=reference=>{if(visiting.has(reference))throw new PmCliError(`Mutation reference cycle includes "@${reference}".`,EXIT_CODE.USAGE);if(!visited.has(reference)){visiting.add(reference);for(const dependency of graph.get(reference))graph.has(dependency)&&visit(dependency);visiting.delete(reference),visited.add(reference)}};for(const reference of graph.keys())visit(reference)}function parseMutationDocumentRows(input){const parsed=parseJsonValue(input,"Mutation document"),envelope=Array.isArray(parsed)?{schema_version:1,mutations:parsed}:parsed;if(!isPlainObject(envelope))throw new PmCliError("Mutation document must be a JSON array or object.",EXIT_CODE.USAGE);for(const key of Object.keys(envelope))if(!MUTATION_DOCUMENT_KEYS.includes(key))throw unknownKeyError("mutation document",key,MUTATION_DOCUMENT_KEYS);if(envelope.schema_version!==void 0&&envelope.schema_version!==1)throw new PmCliError("Mutation document schema_version must be 1.",EXIT_CODE.USAGE);if(!Array.isArray(envelope.mutations)||envelope.mutations.length===0)throw new PmCliError("Mutation document requires a non-empty mutations array.",EXIT_CODE.USAGE);return envelope.mutations.map((row,index)=>{if(!isPlainObject(row))throw new PmCliError(`Mutation ${index+1} must be an object.`,EXIT_CODE.USAGE);for(const key of Object.keys(row))if(!REFERENCED_MUTATION_ROW_KEYS.includes(key))throw unknownKeyError(`mutation ${index+1}`,key,REFERENCED_MUTATION_ROW_KEYS);return{...row}})}function collectMutationReferences(rows,options){const references=Object.create(null);for(const[index,row]of rows.entries())if(row.ref!==void 0){if(row.op!=="create")throw new PmCliError(`Mutation ${index+1} ref is only valid for create operations.`,EXIT_CODE.USAGE);if(typeof row.ref!="string"||!MUTATION_REFERENCE_PATTERN.test(row.ref))throw new PmCliError(`Mutation ${index+1} ref must match ${MUTATION_REFERENCE_PATTERN.source}.`,EXIT_CODE.USAGE);if(references[row.ref]!==void 0)throw new PmCliError(`Duplicate mutation ref "${row.ref}".`,EXIT_CODE.USAGE);references[row.ref]=typeof row.id=="string"&&row.id.trim().length>0?normalizeItemId(row.id,options.idPrefix):deriveReferencedItemId(options.transactionId,row.ref,options.idPrefix)}return references}function resolveItemMutationDocument(input,options){const rows=parseMutationDocumentRows(input),references=collectMutationReferences(rows,options);assertAcyclicCreateReferences(rows);const resolvedRows=rows.map(row=>{const resolved={...row},reference=typeof resolved.ref=="string"?resolved.ref:void 0;if(delete resolved.ref,reference!==void 0?resolved.id=references[reference]:resolved.id=replaceExactMutationReference(resolved.id,references),isPlainObject(resolved.options)){const mutationOptions={...resolved.options};for(const key of["parent","blockedBy"])mutationOptions[key]!==void 0&&(mutationOptions[key]=replaceExactMutationReference(mutationOptions[key],references));Array.isArray(mutationOptions.dep)?mutationOptions.dep=mutationOptions.dep.map(entry=>replaceDependencyReference(entry,references)):mutationOptions.dep!==void 0&&(mutationOptions.dep=replaceDependencyReference(mutationOptions.dep,references)),resolved.options=mutationOptions}return resolved}),mutations=parseItemMutationBatch(JSON.stringify(resolvedRows)),createIds=mutations.filter(mutation=>mutation.op==="create").map(mutation=>mutation.id);if(new Set(createIds).size!==createIds.length)throw new PmCliError("Duplicate resolved create id in mutation document.",EXIT_CODE.USAGE);return{schema_version:1,mutations,references}}function serializePairs(value,keys){return keys.filter(key=>value[key]!==void 0&&value[key]!==null).map(key=>{const rendered=String(value[key]);return`${key}=${/[",\n\r\\]/u.test(rendered)?JSON.stringify(rendered):rendered}`}).join(",")}function serializeObjectArray(value,keys,label){if(value!==void 0){if(!Array.isArray(value)||!value.every(isPlainObject))throw new PmCliError(`${label} must be an array of objects.`,EXIT_CODE.USAGE);return value.map(entry=>serializePairs(entry,keys))}}function scalarItemOption(key,value){return key==="tags"&&Array.isArray(value)&&value.every(entry=>typeof entry=="string")?JSON.stringify(value):typeof value=="number"||typeof value=="boolean"?String(value):value}function appendFacetOptions(target,source,skipPersistedAnnotations=!1){const mappings=[["dependencies","dep",["id","kind","created_at","author","source_kind"]],["comments","comment",["text","created_at","author"]],["notes","note",["text","created_at","author"]],["learnings","learning",["text","created_at","author"]],["files","file",["path","scope","note"]],["tests","test",["command","scope","timeout_seconds"]],["docs","doc",["path","scope","note"]],["reminders","reminder",["at","text","created_at"]],["events","event",["start_at","end_at","title","location"]],["type_options","typeOption",["key","value"]]];for(const[sourceKey,targetKey,keys]of mappings){const sourceValue=source[sourceKey],serialized=serializeObjectArray(skipPersistedAnnotations&&["comments","notes","learnings"].includes(sourceKey)&&Array.isArray(sourceValue)?sourceValue.filter(entry=>!isPlainObject(entry)||entry.created_at===void 0):sourceValue,keys,sourceKey);serialized!==void 0&&serialized.length>0&&(target[targetKey]=serialized)}}function validateItemDocumentKeys(parsed,envelope){for(const key of Object.keys(parsed)){if(envelope){if(!ITEM_ENVELOPE_KEYS.includes(key))throw unknownKeyError("item envelope",key,ITEM_ENVELOPE_KEYS);continue}if(!ITEM_FIELD_KEYS.has(key)&&nearestKey(key,[...ITEM_FIELD_KEYS])===void 0&&nearestKey(key,ITEM_ENVELOPE_KEYS)==="item")throw unknownKeyError("item envelope",key,ITEM_ENVELOPE_KEYS)}}function resolveItemDocument(parsed){const envelope=Object.hasOwn(parsed,"item");validateItemDocumentKeys(parsed,envelope);const item=envelope?parsed.item:parsed;if(!isPlainObject(item))throw new PmCliError("Item document item must be an object.",EXIT_CODE.USAGE);return{item,...envelope&&isPlainObject(parsed.linked)?{linked:parsed.linked}:{}}}function appendItemDocumentEntry(documentOptions,key,value,mode,runtimeFields,explicitOptions){if((mode==="update"?UPDATE_READ_ONLY_ITEM_KEYS:READ_ONLY_ITEM_KEYS).has(key))return;const definition=runtimeFields.find(field=>field.metadata_key===key&&field.commands.includes(mode));if(definition!==void 0){const explicitValue=readRuntimeFieldOptionValue(explicitOptions,definition);documentOptions[runtimeFieldOptionTarget(definition)]=explicitValue!==void 0?explicitValue:definition.type==="array"||definition.type==="object"?JSON.stringify(value):value;return}if(!ITEM_FIELD_KEYS.has(key)){if(nearestKey(key,[...ITEM_FIELD_KEYS])!==void 0)throw unknownKeyError("item document",key,[...ITEM_FIELD_KEYS]);const fields=Array.isArray(documentOptions.field)?documentOptions.field:[];fields.push(`${key}=${typeof value=="string"?value:JSON.stringify(value)}`),documentOptions.field=fields;return}["dependencies","comments","notes","learnings","files","tests","docs","reminders","events","type_options"].includes(key)||(documentOptions[key.replaceAll(/_([a-z])/gu,(_match,letter)=>letter.toUpperCase())]=scalarItemOption(key,value))}function itemDocumentToMutationOptions(input,mode,explicitOptions={},runtimeFields=[]){const parsed=parseJsonValue(input,"Item document");if(!isPlainObject(parsed))throw new PmCliError("Item document must be a JSON object.",EXIT_CODE.USAGE);const{item,linked}=resolveItemDocument(parsed),documentOptions={};for(const[key,value]of Object.entries(item))appendItemDocumentEntry(documentOptions,key,value,mode,runtimeFields,explicitOptions);if(appendFacetOptions(documentOptions,item,mode==="update"),linked!==void 0&&appendFacetOptions(documentOptions,linked),mode==="update"){const annotations=Object.fromEntries(["comments","notes","learnings"].filter(key=>Object.hasOwn(item,key)).map(key=>[key,item[key].filter(entry=>isPlainObject(entry)&&entry.created_at!==void 0)]));Object.keys(annotations).length>0&&(documentOptions.documentAnnotationSnapshot=annotations)}return{...documentOptions,...Object.fromEntries(Object.entries(explicitOptions).filter(([,value])=>value!==void 0)),...Array.isArray(documentOptions.field)&&Array.isArray(explicitOptions.field)?{field:[...documentOptions.field,...explicitOptions.field]}:{},stdinJson:void 0}}function validateItemMutationRows(value){return parseItemMutationBatch(JSON.stringify(value))}export{itemDocumentToMutationOptions,parseAtomicMutationControls,parseItemMutationBatch,resolveItemMutationDocument,validateItemMutationRows};
 //# sourceMappingURL=structured-mutations.js.map

package/docs/QUALITY_EVIDENCE.md

@@ -1,7 +1,58 @@
 # Test strength and documentation content
 
 Tracked by [pm-zclzll](../.agents/pm/tasks/pm-zclzll.toon) and
-[pm-dvwm](../.agents/pm/chores/pm-dvwm.toon).
+[pm-dvwm](../.agents/pm/chores/pm-dvwm.toon). Release acceptance and token
+comparison contracts: [pm-gh1428](../.agents/pm/issues/pm-gh1428.toon),
+[pm-gh1429](../.agents/pm/issues/pm-gh1429.toon), and
+[pm-agent-token-path](../.agents/pm/issues/pm-agent-token-path.toon).
+
+## Installed context and immutable release recovery
+
+The installed-agent journey requests `context --for orient --limit 1` with an
+explicit 512-token output budget. A complete successful result must report the
+actual population: zero items before creation and one closed item after the
+lifecycle. An omitted result cannot establish either fact. When the installed
+version refuses an infeasible budget, the verifier checks exit 2, the omission
+and budget receipts, and the exact advertised `outputBudget: "unbounded"`
+recovery. It then repeats the same intent and amount with that recovery. Older
+control releases may return complete bounded context immediately. Every step
+keeps its existing character ceiling and process deadline; reports retain the
+observed exit status and all refusal/recovery output costs.
+
+Unexpected process failures retain classified status, signal, spawn error and
+both output streams, with credential redaction before 512-character excerpts.
+Unit tests own malformed receipts and failure diagnostics. Real npm/Bun
+installations and the hosted candidate/control platform matrix own compatibility
+with the actual SDK-backed CLI. A stubbed empty context object cannot satisfy
+the population assertions.
+
+Exact-tag recovery preserves reviewed artifact controls before selecting tagged
+source. The preserved directory retains `scripts/release` and its parent script
+dependencies, including temporary lifecycle and cleanup modules. The executable
+workflow regression copies those real controls, packs a foreign workspace with
+real npm, and checks the committed artifact budget. Removing a transitive import
+must fail with its original module error. Preserved controls stay outside the
+source checkout; published immutable versions are verified without republishing.
+
+## Portable agent-task token comparisons
+
+Version 5 of the agent-task baseline declares
+`comparison_scope: "plan_recovery_tracker_root_canonicalized"`. Each replay
+continues to report exact `emitted_bytes`, `estimated_tokens`, and accounting
+receipt bytes for the actual transport. Its `comparison_emitted_bytes` and
+`comparison_estimated_tokens` replace only the validated tracker suffixes in
+Plan inspection, next-action and plan-detail recovery commands with the fixed
+`/replay/.agents/pm` comparison root. The actual payload retains executable
+commands targeting its real fixture. Other facts, paths and commands remain
+part of the cost.
+
+Step, completed-task and composite ceilings use those comparison measurements.
+The orientation selector uses the same cost basis. Missing, negative,
+non-integer or non-finite measurements and mismatched comparison scopes fail
+closed. Short and long temporary roots must produce the same verdict while
+their real emitted-byte counts may differ. Output growth still fails the
+unchanged ceilings; normalization does not waive accounting, payload parity,
+required-field or executable-recovery checks.
 
 ## SDK mutation testing
 

package/docs/RELEASE_LEDGER_RECONCILIATION.md

@@ -0,0 +1,148 @@
+# Full-history release reconciliation
+
+Owner: [pm-q91qyd](../.agents/pm/issues/pm-q91qyd.toon).
+Upstream trigger evidence: [pm-prrlce](../.agents/pm/issues/pm-prrlce.toon).
+
+The Release Reliability workflow compares every dated section in the
+package-generated changelog, every release tag advertised by `origin`, and
+every version in anonymous public npm metadata. It runs on the existing daily
+schedule and completion triggers, even when a rolling reliability report fails.
+Its separate `release-ledgers-<run>-<attempt>` artifact contains the complete
+input inventories, counts, findings and exception dispositions for offline replay.
+
+Missing public registry versions are declared-but-undelivered releases. Missing
+changelog sections are delivered-but-undocumented releases. A tag missing its
+section is tagged-but-unsectioned; an identity can belong to several classes.
+Every missing ledger appears explicitly in the report, without counting one
+identity several times or dropping overlapping classes.
+The `classes` object names these three populations separately; `findings`
+retains one row per discrepant identity.
+
+The first complete census on 2026-10-10 found 14 discrepant identities among
+143 sections, 151 tags and 143 public versions. The exact historical signatures
+and their individual dispositions are recorded in
+[the reviewed exception policy](../config/release-ledger-exceptions.json).
+Unpublished historical preparations are retained as abandoned publications;
+historical documentation gaps remain visible without inventing shipped content.
+These are explicit exceptions, not claims that the three historical sets agree.
+No tag is deleted and no old artifact is published by this reporting path.
+
+An exception matches one identity and one exact missing-ledger signature.
+Additional missing evidence invalidates it. Correcting a historical gap makes
+its exception stale and requires removing or revising that policy entry in a
+reviewed change. A new discrepancy or stale exception fails the report.
+Empty total inventories, incomplete populations, duplicate identities, malformed
+remote output, registry failures and missing exception evidence refuse evaluation.
+
+The registry request uses the same public npm metadata surface as release
+acceptance, with explicit public registry selection, empty user/global
+configuration and a fresh temporary cache. It runs outside the checkout and
+removes inherited npm authentication/configuration. The report never archives
+credentials, command output or environment values.
+On Windows the collector invokes `cmd.exe` explicitly for npm's `.cmd` launcher.
+The package name must satisfy the restricted registry identity grammar before
+any child starts; the remaining arguments are fixed. Required Windows acceptance
+executes real Git and public npm requests from paths containing spaces and `&`,
+first proves that direct `npm.cmd` execution fails, then verifies the complete
+inventory and temporary-directory cleanup through the repaired launcher.
+No `shell: true` argument-array fallback or resource ceiling increase is used.
+The parser supports npm 11's object and npm 12's single-result array, with
+[captured public npm 12 metadata](../tests/fixtures/release-ledgers/npm-view-12.json)
+as its format regression. Multiple package results refuse evaluation.
+
+To run the actual collector after building:
+
+```bash
+RELEASE_LEDGERS_OUTPUT=/absolute/report.json node --input-type=module -e '
+  import { main } from "./scripts/release/collect-release-ledgers.mjs";
+  const report = main();
+  console.log(JSON.stringify({ok:report.ok,counts:report.counts,findings:report.findings}));
+  process.exitCode = report.ok ? 0 : 1;
+'
+```
+
+Packages and non-release projects can use the same pure SDK primitive with
+their own named artifact inventories and decision references:
+
+```ts
+import { reconcileArtifactLedgers } from "@unbrained/pm-cli/sdk/governance";
+
+const report = reconcileArtifactLedgers([
+  { name: "declared", complete: true, identities: ["artifact-1"] },
+  { name: "delivered", complete: true, identities: ["artifact-1"] },
+]);
+```
+
+`ArtifactLedgerSnapshot`, `ArtifactLedgerException`, `ArtifactLedgerFinding`
+and `ArtifactLedgerReport` describe this harness-independent contract.
+The evaluator performs no filesystem, clock or network operations and preserves
+caller inputs. For offline replay, feed the saved `snapshots` and `exceptions`
+back into `reconcileArtifactLedgers`.
+
+## Tag-carried trigger declarations
+
+New preparations create annotated tags whose bounded JSON message binds the
+declared upstream event/origin, repository, run/attempt, reviewed source commit
+and prepared target commit. Before publication, the Release workflow checks
+the tag's peeled commit and source ancestry and compares the source declaration
+with the exact GitHub run attempt, including repository, event, source SHA,
+the producer workflow path and declared Auto Release run name. It independently
+fetches the repository's default branch and requires the source run's branch to
+match it. Auto Release uploads an immutable producer binding before pushing;
+publication independently downloads that run attempt's artifact and compares
+the exact tag name, target commit, tag object and canonical declaration. Missing,
+expired, ambiguous or mismatched evidence stops publication; the artifact is
+retained for 90 days. The verifier never assumes the default branch is named
+`main`.
+
+The separate `release-publication-origin-<run>-<attempt>` artifact retains the
+tag-object SHA, upstream declaration, independent verification result and the
+current publication/recovery trigger. An operator recovering a dispatcher
+release therefore retains both origins. A rejected atomic push after sealing
+refuses to rebase into a different target; a new preparation must establish a
+new independent binding. Local preparation remains supported without pushing;
+local `--push` refuses before Git inspection or release-asset mutation.
+
+Historical lightweight tags and unrelated legacy annotations stay explicitly
+unattributed only when publication matches the repository, tag name and exact
+content-addressed object in the
+[frozen pre-rollout inventory](../config/release-tag-legacy.json). That reviewed
+inventory identifies all 152 origin tag objects observed before this rollout;
+it is not extended automatically. Unknown lightweight tags, unrelated new
+annotations and rewritten historical objects stop before publication, including
+operator recovery. A missing or unreadable inventory fails closed. No origin is
+inferred from a tag-push event or actor. Local preparation records an operator
+declaration but hosted publication refuses it without a hosted producer.
+Tag objects are content-addressed evidence; this does not assert that GitHub
+release/tag immutability policy has been enabled.
+
+The downstream tag-push workflow's run name still names `tag_push`; its verified
+upstream origin lives in the summary and artifact. The remaining run-name and
+operator-only manual follow-up contracts retain their existing owners
+[pm-prrlce](../.agents/pm/issues/pm-prrlce.toon) and
+[pm-uenmu9](../.agents/pm/issues/pm-uenmu9.toon). The one-automatic-release-per-UTC-day
+guard and exact-tag recovery semantics are unchanged.
+
+## Installed acceptance path cost
+
+Owner: [pm-release-acceptance-path-cost](../.agents/pm/issues/pm-release-acceptance-path-cost.toon).
+
+The disposable installed-consumer layout uses concise directory names because
+`init` repeats its workspace path throughout its complete JSON guidance. Long
+macOS temporary ancestry previously made an otherwise valid public artifact
+exceed the raw 12,000-character init ceiling. Shorter private paths retain every
+output field, lifecycle assertion, deadline and ceiling. The
+[captured public output regression](../tests/fixtures/release-acceptance/README.md)
+checks the raw cost for independent control/candidate local npm, global npm and
+Bun layouts; actual installed sessions remain separate acceptance evidence.
+
+## Publication metadata weight
+
+Owner: [pm-998juj](../.agents/pm/tasks/pm-998juj.toon).
+
+The publication stage compacts first-party JSON while leaving checkout files
+readable and third-party runtime files unchanged. Every parsed value must survive
+serialization exactly; invalid JSON and lossy representations, including negative
+zero or overflowing numbers, stop packing. Real tarball regressions verify nested
+extension data, Unicode, escaped text and the runtime ledger. Both committed size
+profiles, required files and source-map exclusions remain enforced.

package/docs/RELEASE_RELIABILITY.md

@@ -7,7 +7,7 @@ installed-package diagnostics are tracked by
 [pm-q7c36n](../.agents/pm/issues/pm-q7c36n.toon).
 
 The **Release Reliability** workflow evaluates the preceding 30 days after a
-scheduled Auto Release completes, daily at nominal 04:35 UTC, and on manual
+default-branch Auto Release or Nightly Validation completes, daily at nominal 04:35 UTC, and on manual
 dispatch. It saves a JSON report and fails its own check when policy is breached.
 The report is independent of candidate correctness: historical failures must
 remain visible while a reviewed repair can still pass publication gates.
@@ -34,6 +34,10 @@ by release preparation, not the inferred cron occurrence. A delayed run cannot
 backdate a tag. Reporting never creates, retargets, retries, or publishes a tag.
 The unchanged [release recovery rules](RELEASING.md#failure-handling) apply.
 
+The independent [full-history ledger report](RELEASE_LEDGER_RECONCILIATION.md)
+also reconciles public registry versions, release tags and generated sections.
+It preserves every historical exception and fails on new or changed drift.
+
 ## Evidence and denominator
 
 The collector paginates Auto Release runs over an explicit half-open UTC window
@@ -48,6 +52,11 @@ be uploaded, the collector reads the declared run name. Historical dispatches
 without either declaration appear in `pre_attribution_gap`; the failed
 2026-09-28 morning dispatch cannot be attributed from its old run record.
 Dispatcher rows retain creation time, queue delay, outcome, and failure stage.
+The `origins` map also retains independent `native_schedule`, `operator`, and
+`blocker_retry` series, each with original counts, failure stages and outcome
+evidence completeness. Undeclared historical runs remain explicit attribution
+gaps; event or actor never supplies an invented origin. These diagnostic series
+do not alter the native scheduled policy denominator.
 They omit nominal occurrence and dispatch delay because the native 02:35 UTC
 cron is not the dispatcher's clock; the scheduled timing policy does not apply
 to those rows.
@@ -85,8 +94,54 @@ hosted acceptance job limit.
 
 The report is a rolling observation, not a permanent archive of all releases.
 Retain exported receipts externally if a longer historical window is needed.
-It does not implement the separate nightly per-leg reliability programme or
-change the manual same-day version policy.
+It does not change the manual same-day version policy or propagate upstream
+origin through historical lightweight tags. Those remaining outcomes retain
+their existing PM owners.
+
+## Nightly recurrence and public SDK
+
+[pm-2zjs0g](../.agents/pm/issues/pm-2zjs0g.toon) owns the nightly recurrence meter.
+The same reporting workflow builds trusted default-branch code and writes a
+separate `nightly-reliability-<run>-<attempt>` artifact, including when release
+reporting is already red. Its [versioned policy](../config/nightly-reliability-policy.json)
+requires seven completed original attempts per family and at most 10% failures
+over 30 days. Breaches fail the operational report and appear in the workflow
+summary; they remain distinct from checks evaluating a candidate repair.
+
+The collector derives current leg identities from `nightly.yml` and each run's
+applicable population from the workflow at its original head SHA. Immutable
+definitions are cached within one census; legacy OS/Node matrices and today's
+labelled shards both retain their actual generations. Newly introduced families
+never gain synthetic pending attempts in older runs. It retains historical
+observed legs, retrieves attempt 1 after reruns, and reads both open
+and closed alert issues plus their complete comment pages. Original failures,
+distinct affected UTC days and observed closure durations survive alert repair.
+Every new alert carries the stable PM recurrence owner and a platform/Node family
+identity. Counts do not depend on a maintained list of occurrence IDs. An absent
+job is pending evidence; an empty family has a null rate and fails coverage.
+
+Alert closure is the recorded latency endpoint, not proof of a product fix.
+When one alert episode links several failed runs, its shared closure is the
+endpoint for each recorded occurrence's alert-closure latency. This does not
+assert that an independent per-attempt product repair was verified.
+Product versus infrastructure cause stays `unknown` until independent evidence
+classifies it. Repairs at or beyond the report cutoff remain unresolved in that
+historical window. API errors, incomplete search results, missing pages,
+duplicate identities and ambiguous jobs refuse a complete-census claim.
+
+Packages can reuse the harness-independent evaluator through
+`evaluateReliabilityWindow` from `@unbrained/pm-cli/sdk/governance`. Supply
+`ReliabilityAttempt` records with unique `id`, stable `family`, `started_at`,
+original `outcome` and optional `repaired_at`/`cause`, plus an explicit
+`ReliabilityWindowPolicy` population, half-open window, maximum failure fraction
+and minimum completed count. The typed result preserves per-family findings,
+unknown causes and repair observations. No GitHub dependency, filesystem tracker,
+clock read or network call is required by this SDK primitive.
+
+For reproducible offline evaluation, retain the report's `attempts` and `policy`
+with its exact window; rerun the SDK evaluator against those records. The GitHub
+adapter accepts a caller-chosen clock and a 1–90 day policy window, allowing
+historical family reconstruction while keeping the production 30-day policy fixed.
 
 Provider contracts: [workflow run attempts](https://docs.github.com/en/rest/actions/workflow-runs#get-a-workflow-run-attempt)
 and [completion-triggered workflows](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#workflow_run).

package/docs/RELEASING.md

@@ -172,6 +172,17 @@ Pipeline entrypoint:
 node scripts/release/run-release-pipeline.mjs
 ```
 
+Tracked by [pm-prrlce](../.agents/pm/issues/pm-prrlce.toon): hosted preparation
+uses `--push --defer-push` to write an exact producer binding. Auto Release uploads
+`release-producer-binding-<attempt>` before verifying and atomically pushing its
+prepared refs. Publication independently fetches the verified run's artifact and
+compares the tag name, target commit, tag object and declaration. Missing, expired,
+ambiguous or mismatched evidence fails closed; artifact retention is 90 days.
+A branch advance after sealing refuses publication rather than rebasing into a
+different target. Local `--push` refuses before Git inspection or asset mutation;
+local preparation without pushing remains supported. Historical admission remains
+limited to the reviewed exact-object inventory.
+
 The pipeline performs:
 
 1. change detection + one-release-per-day guard
@@ -421,14 +432,28 @@ maintainer supplies
 pair that acknowledgement with migration guidance, compatible extension
 version bounds where applicable, and the next eligible date-based release.
 
-5. Push branch and tag after local green.
+5. Land the implementation through a reviewed pull request, then use hosted
+   preparation for publication.
+
+Local preparation without `--push` is a diagnostic preview. Its local producer
+declaration cannot authorize publication. Once the reviewed implementation is on
+`main`, dispatch the existing Auto Release workflow from that default branch:
 
 ```bash
-git push origin main
-git tag v<version>
-git push origin v<version>
+gh workflow run auto-release.yml --ref main \
+  -f push=true -f dry_run=false -f telemetry_mode=off -f trigger_origin=operator
 ```
 
+Hosted preparation runs the mandatory gates, creates the version commit and
+annotated tag, and seals their exact producer binding in an immutable artifact
+before verifying and atomically pushing either ref. It waits for the single
+tag-driven Release workflow to publish and accept that exact package. Do not push
+locally prepared tags or invoke `npm publish` separately.
+
+If today's immutable tag already exists, use the exact-tag recovery procedure
+below. A local diagnostic tag does not prove hosted preparation or publication;
+never move a published tag or mint a second automatic version for the same UTC day.
+
 ## GitHub Workflow
 
 `.github/workflows/release.yml` runs on `v*.*.*` tags and handles:
@@ -454,7 +479,11 @@ git push origin v<version>
 - a base npm pack dry run, optional Sentry debug-ID injection, a second
   `sentry-injected` packlist budget over the exact publishable bytes, and only
   then optional Sentry release metadata/upload/finalization and the npx tarball
-  smoke test
+  smoke test. Sentry release metadata and sourcemaps are uploaded only from
+  tag sources. Recovery of an already-published version from reviewed `main`
+  preserves that version's existing Sentry commits and sourcemaps; local debug-ID
+  injection still validates the candidate artifact budget without changing the
+  published release's symbolication data.
 - generated release notes from changelog plus sanitized tracker metadata. The
   tracker read projects only release-relevant fields and explicitly removes row
   and token limits. The generator validates the completeness receipt before

package/docs/SDK.md

@@ -1552,8 +1552,22 @@ accepts either a direct `ItemDocument` or the envelope returned by
 `pm get <id> --json`, strips read-only metadata, maps canonical snake-case item
 fields to typed mutation options, and serializes linked facets through the same
 repeatable option forms as create/update. Explicit options win over document
-values. Unknown near-miss keys fail; application-defined fields are routed
-through the public `field` escape hatch.
+values. Pass `resolveRuntimeFieldRegistry(settings.schema).definitions` as the
+fourth argument to route workspace metadata keys through their declared SDK
+option names. CLI stdin automatically resolves the selected workspace schema.
+Schema aliases override document values through the same field registry.
+Declared extension fields use raw `name=value` assignments; explicit `field`
+entries override only matching names, preserving other document fields. Strings
+retain commas, equals signs, quotes, Unicode, and newlines; numbers, booleans,
+objects, and arrays retain their types. Unknown fields and near-miss built-in
+keys refuse before item or history writes.
+
+Tracked by [pm-stdin-schema-fields](../.agents/pm/issues/pm-stdin-schema-fields.toon).
+Stored schema containers retain their decoded shape; repeated CLI container
+flags still select the final supplied value. Normal SDK item operations refuse
+ahead-of-runtime storage markers before schema or body validation and retain
+item identity/path in the structured error. Integrity diagnostics preserve
+future markers for inspection.
 
 The built-in adapters stay deliberately thin:
 

package/docs/TESTING.md

@@ -142,6 +142,42 @@ failed, skipped, stale, ambiguous, and different-tree results all fail.
 `pnpm release:gates` includes the same non-skippable verification, so run it
 only after the pushed reviewed head's hosted analyzers are terminal.
 
+## Published Workspace Compatibility
+
+Tracked by [pm-pae3wo](../.agents/pm/tasks/pm-pae3wo.toon).
+Run `node scripts/release/workspace-compatibility.mjs --json` after building.
+The policy in `scripts/release/workspace-compatibility-policy.json` requires
+the two immediately preceding stable calendar releases. Each installed release
+writes a disposable workspace read by the current runtime, and the current
+runtime writes one read by that release. Exact scalar and container values must
+survive CLI and public SDK reads, ordinary writes with their registration
+disabled, history restoration, native Git merges, reconciliation, and history
+verification. Missing releases, metadata loss, or invalid merged histories fail
+the gate. CI, nightly quality, release publication, and local preflight require
+this matrix alongside the independent legacy Markdown migration check.
+
+Metadata probes and installs explicitly use the public npm registry with
+separate empty user/global configurations and a fresh temporary cache. Inherited
+npm settings and registry-auth environment variables are removed, so host
+configuration cannot change the artifacts selected by the declared window.
+
+The current item-operation boundary refuses a stored `pm_format_version`
+ahead of its supported version with `item_format_version_unsupported` and
+upgrade guidance. Reads, updates, deletion, and restoration preserve the
+original item/history on refusal, including documents whose metadata/body
+shapes are invalid for the current runtime. Admission precedes schema validation
+so restore cannot misclassify newer data as ordinary corruption. Static fixture
+modules read separate JSON data; published SDK probes use the public package
+entrypoint from their own consumer directory. Raw parsers still preserve future version
+markers for integrity inspection; inventory diagnostics are not permission to
+rewrite an unsupported item.
+
+Run the matrix from the built workspace root. Exact-tag release recovery retains
+the reviewed matrix controls, policy and static fixtures outside the checkout,
+then tests the selected tagged runtime through its manifest and public SDK. A
+historical tag need not contain newly added gate scripts; recovery still runs
+the mandatory matrix without rewriting the tagged source or skipping policy.
+
 ## Focused Test Runs
 
 ```bash