@unbrained/pm-cli 2026.10.11 → 2026.10.13

package/dist/sdk/merge/three-way.d.ts

@@ -7,7 +7,7 @@ export type ItemScalarConflictResolution = "preferred_side" | "stable_value_orde
 export type ItemScalarResolutionBasis = "requested_preference" | "document_updated_at" | "stable_value_tiebreak";
 /** JSON-stable marker used when a conflict decision refers to an absent scalar. */
 export declare const ITEM_SCALAR_MISSING_VALUE: Readonly<{
-    readonly pm_item_scalar_missing: true;
+readonly pm_item_scalar_missing: true;
 }>;
 /** Return whether receipt evidence represents an absent item scalar. */
 export declare function isItemScalarMissingValue(value: unknown): value is typeof ITEM_SCALAR_MISSING_VALUE;
@@ -19,26 +19,27 @@ export declare function hashItemScalarDecisionValue(value: unknown): string;
 export type HistoryMergeStrategy = "identical" | "fast_forward_ours" | "fast_forward_theirs" | "union_reanchor";
 /** Documents the history stream merge result payload exchanged by command, SDK, and package integrations. */
 export interface HistoryMergeResult {
-    /** Merged JSONL content ready to be written as the resolved history stream. */
-    merged: string;
-    /** Strategy the merge used: identical inputs, one-sided fast-forward, or a deterministic union with a re-anchored hash chain. */
-    strategy: HistoryMergeStrategy;
-    /** Number of entries shared by both sides before their streams diverged. */
-    common_entries: number;
-    /** Number of divergent entries contributed by the ours side. */
-    entries_from_ours: number;
-    /** Number of divergent entries contributed by the theirs side. */
-    entries_from_theirs: number;
-    /** Total entries in the merged stream. */
-    entries_total: number;
-    /** Whether the merged chain required hash re-anchoring (true for every union merge). */
-    reanchored: boolean;
+/** Merged JSONL content ready to be written as the resolved history stream. */
+merged: string;
+/** Strategy the merge used: identical inputs, one-sided fast-forward, or a deterministic union with a re-anchored hash chain. */
+strategy: HistoryMergeStrategy;
+/** Number of entries shared by both sides before their streams diverged. */
+common_entries: number;
+/** Number of divergent entries contributed by the ours side. */
+entries_from_ours: number;
+/** Number of divergent entries contributed by the theirs side. */
+entries_from_theirs: number;
+/** Total entries in the merged stream. */
+entries_total: number;
+/** Whether the merged chain required hash re-anchoring (true for every union merge). */
+reanchored: boolean;
 }
 /**
  * Deterministically merge two diverged versions of one append-only history
  * JSONL stream. Identical streams and one-sided fast-forwards keep the winning
  * side byte-for-byte; genuinely diverged streams are merged as the shared
- * prefix plus both suffixes ordered by timestamp (ours-first on ties), then
+ * prefix plus both suffixes ordered by original branch dependencies, choosing
+ * by timestamp among available events (ours-first on ties), then
  * hash re-anchored so the resulting chain verifies again. No side's events are
  * ever discarded: content divergence is preserved for the post-merge
  * reconciliation pass (`pm validate` + `pm history-repair`) instead of being
@@ -49,20 +50,20 @@ export interface HistoryMergeResult {
 export declare function mergeHistoryStreams(baseRaw: string, oursRaw: string, theirsRaw: string): HistoryMergeResult;
 /** Documents the relationship event stream merge result payload exchanged by command, SDK, and package integrations. */
 export interface RelationshipStreamMergeResult {
-    /** Merged JSONL content with consecutively renumbered `sequence` values, ready to be written as the resolved event store. */
-    merged: string;
-    /** Strategy the merge used: identical inputs, one-sided fast-forward, or a deterministic union with renumbered sequences. */
-    strategy: HistoryMergeStrategy;
-    /** Number of events shared by both sides before their streams diverged. */
-    common_entries: number;
-    /** Number of divergent events contributed by the ours side. */
-    entries_from_ours: number;
-    /** Number of divergent events contributed by the theirs side. */
-    entries_from_theirs: number;
-    /** Total events in the merged stream. */
-    entries_total: number;
-    /** Whether merged events required sequence renumbering (true for every union merge). */
-    reanchored: boolean;
+/** Merged JSONL content with consecutively renumbered `sequence` values, ready to be written as the resolved event store. */
+merged: string;
+/** Strategy the merge used: identical inputs, one-sided fast-forward, or a deterministic union with renumbered sequences. */
+strategy: HistoryMergeStrategy;
+/** Number of events shared by both sides before their streams diverged. */
+common_entries: number;
+/** Number of divergent events contributed by the ours side. */
+entries_from_ours: number;
+/** Number of divergent events contributed by the theirs side. */
+entries_from_theirs: number;
+/** Total events in the merged stream. */
+entries_total: number;
+/** Whether merged events required sequence renumbering (true for every union merge). */
+reanchored: boolean;
 }
 /**
  * Deterministically merge two diverged versions of one append-only
@@ -89,41 +90,41 @@ export declare const ITEM_UNION_COLLECTION_FIELDS: readonly ["tags", "dependenci
 export declare const ITEM_LATEST_TIMESTAMP_FIELDS: readonly ["updated_at"];
 /** Documents one recoverable scalar decision made during an item merge. */
 export interface ItemMergeConflictDecision {
-    /** Metadata field name, or `body`. */
-    field: string;
-    /** Common-ancestor value. */
-    base: unknown;
-    /** Current-branch value. */
-    ours: unknown;
-    /** Other-branch value. */
-    theirs: unknown;
-    /** Value retained in the merged item. */
-    retained: unknown;
-    /** Value not retained in the merged item. */
-    discarded: unknown;
-    /** Branch coordinate whose value was retained. */
-    retained_side?: MergePreferredSide;
-    /** Evidence class that selected the retained value. */
-    resolution_basis?: ItemScalarResolutionBasis;
+/** Metadata field name, or `body`. */
+field: string;
+/** Common-ancestor value. */
+base: unknown;
+/** Current-branch value. */
+ours: unknown;
+/** Other-branch value. */
+theirs: unknown;
+/** Value retained in the merged item. */
+retained: unknown;
+/** Value not retained in the merged item. */
+discarded: unknown;
+/** Branch coordinate whose value was retained. */
+retained_side?: MergePreferredSide;
+/** Evidence class that selected the retained value. */
+resolution_basis?: ItemScalarResolutionBasis;
 }
 /** Documents the item document merge result payload exchanged by command, SDK, and package integrations. */
 export interface ItemDocumentMergeResult {
-    /** Serialized merged item document (always parseable; count headers recomputed by canonical serialization). */
-    merged: string;
-    /** Metadata fields (plus `body`) where both sides changed to different values; resolved toward the preferred side. */
-    conflict_fields: string[];
-    /** Fields taken from the theirs side by clean three-way resolution. */
-    fields_from_theirs: string[];
-    /** Collection fields that merged by element-identity union. */
-    union_fields: string[];
-    /** Scalar conflict decisions; callers choose a privacy-appropriate persistence boundary. */
-    conflict_decisions: ItemMergeConflictDecision[];
-    /** Side requested by the caller; stable-value decisions can retain either side. */
-    requested_preference: MergePreferredSide;
-    /** Whether the requested side participates in item scalar selection under the declared policy. */
-    requested_preference_applied: boolean;
-    /** Scalar-conflict selection contract used for this merge. */
-    conflict_resolution: ItemScalarConflictResolution;
+/** Serialized merged item document (always parseable; count headers recomputed by canonical serialization). */
+merged: string;
+/** Metadata fields (plus `body`) where both sides changed to different values; resolved toward the preferred side. */
+conflict_fields: string[];
+/** Fields taken from the theirs side by clean three-way resolution. */
+fields_from_theirs: string[];
+/** Collection fields that merged by element-identity union. */
+union_fields: string[];
+/** Scalar conflict decisions; callers choose a privacy-appropriate persistence boundary. */
+conflict_decisions: ItemMergeConflictDecision[];
+/** Side requested by the caller; stable-value decisions can retain either side. */
+requested_preference: MergePreferredSide;
+/** Whether the requested side participates in item scalar selection under the declared policy. */
+requested_preference_applied: boolean;
+/** Scalar-conflict selection contract used for this merge. */
+conflict_resolution: ItemScalarConflictResolution;
 }
 /**
  * Field-aware three-way merge of one tracker item document. Commutative
@@ -138,21 +139,21 @@ export interface ItemDocumentMergeResult {
  * headers) cannot be produced by this merge.
  */
 export declare function mergeItemDocuments(baseRaw: string, oursRaw: string, theirsRaw: string, options?: ItemDocumentFormatOptions & {
-    /** Side that wins unresolvable conflicts (default "ours"). */
-    preferred?: MergePreferredSide;
-    /** Direction-independent scalar selection used by the Git driver. */
-    conflictResolution?: ItemScalarConflictResolution;
+/** Side that wins unresolvable conflicts (default "ours"). */
+preferred?: MergePreferredSide;
+/** Direction-independent scalar selection used by the Git driver. */
+conflictResolution?: ItemScalarConflictResolution;
 }): ItemDocumentMergeResult;
 /** Documents the JSON document merge result payload exchanged by command, SDK, and package integrations. */
 export interface JsonDocumentMergeResult {
-    /** Serialized merged JSON document (two-space indent, trailing newline — the tracker's canonical config style). */
-    merged: string;
-    /** Dotted key paths where both sides changed to different values; resolved toward the preferred side. */
-    conflict_paths: string[];
-    /** Dotted key paths taken from the theirs side by clean three-way resolution. */
-    paths_from_theirs: string[];
-    /** Which side unresolvable conflicts were resolved toward. */
-    preferred: MergePreferredSide;
+/** Serialized merged JSON document (two-space indent, trailing newline — the tracker's canonical config style). */
+merged: string;
+/** Dotted key paths where both sides changed to different values; resolved toward the preferred side. */
+conflict_paths: string[];
+/** Dotted key paths taken from the theirs side by clean three-way resolution. */
+paths_from_theirs: string[];
+/** Which side unresolvable conflicts were resolved toward. */
+preferred: MergePreferredSide;
 }
 /**
  * Key-level three-way merge for the tracker's JSON configuration artifacts.
@@ -163,6 +164,6 @@ export interface JsonDocumentMergeResult {
  * silent-defaults fallback that raw conflict markers cause.
  */
 export declare function mergeJsonDocuments(baseRaw: string, oursRaw: string, theirsRaw: string, options?: {
-    /** Side that wins unresolvable conflicts (default "ours"). */
-    preferred?: MergePreferredSide;
+/** Side that wins unresolvable conflicts (default "ours"). */
+preferred?: MergePreferredSide;
 }): JsonDocumentMergeResult;

package/dist/sdk/merge/three-way.js

@@ -1,4 +1,4 @@
-(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]="5134bd12-d808-588f-af5d-fc71e5153e95")}catch{}})();import{historyEntriesToRaw,reanchorHistoryEntries}from"../../core/history/replay.js";import{canonicalDocument,parseItemDocument,serializeItemDocument}from"../../core/item/item-format.js";import{splitAcceptanceCriteria}from"../../core/item/parse.js";import{EXIT_CODE}from"../../core/shared/constants.js";import{findFirstMergeConflictMarker}from"../../core/shared/conflict-markers.js";import{PmCliError}from"../../core/shared/errors.js";import{sha256Hex,stableStringify}from"../../core/shared/serialization.js";import{compareTimestampStrings}from"../../core/shared/time.js";const ITEM_SCALAR_MISSING_VALUE=Object.freeze({pm_item_scalar_missing:!0});function isItemScalarMissingValue(value){return typeof value=="object"&&value!==null&&!Array.isArray(value)&&Object.keys(value).length===1&&value.pm_item_scalar_missing===!0}function encodeItemScalarDecisionValue(value){return value===void 0?ITEM_SCALAR_MISSING_VALUE:value}function hashItemScalarDecisionValue(value){return sha256Hex(stableStringify(value===void 0?{pm_item_scalar_presence:"missing"}:{pm_item_scalar_presence:"present",value}))}function parseHistoryJsonl(raw,label){const conflictMarker=findFirstMergeConflictMarker(raw);if(conflictMarker)throw new PmCliError(`History merge input (${label}) contains unresolved conflict markers at line ${conflictMarker.line}. Merge drivers must receive clean per-side versions.`,EXIT_CODE.GENERIC_FAILURE);const entries=[];for(const[index,rawLine]of raw.split(/\r?\n/).entries()){const line=rawLine.trim();if(line)try{const parsed=JSON.parse(line);if(typeof parsed!="object"||parsed===null||Array.isArray(parsed))throw new TypeError("history entry must be an object");entries.push(parsed)}catch{throw new PmCliError(`History merge input (${label}) contains invalid JSON at line ${index+1}.`,EXIT_CODE.GENERIC_FAILURE)}}return entries}function historyEntryIdentity(entry){return stableStringify({ts:entry.ts,author:entry.author,op:entry.op,patch:entry.patch,message:entry.message??null})}function commonHistoryPrefixLength(ours,theirs){const limit=Math.min(ours.length,theirs.length);let shared=0;for(;shared<limit&&historyEntryIdentity(ours[shared])===historyEntryIdentity(theirs[shared]);)shared+=1;return shared}function mergeHistoryStreams(baseRaw,oursRaw,theirsRaw){const base=parseHistoryJsonl(baseRaw,"base"),ours=parseHistoryJsonl(oursRaw,"ours"),theirs=parseHistoryJsonl(theirsRaw,"theirs"),creates=[base,ours,theirs].map(entries=>entries.filter(entry=>entry.op==="create"));if(creates[0].length===0&&creates.slice(1).every(entries=>entries.length>0)||creates.some(entries=>entries.length>1)||new Set(creates.flat().map(historyEntryIdentity)).size>1)throw new PmCliError("Duplicate item identity: history contains independent or unproven create events. Preserve both branches and assign distinct item ids before merging.",EXIT_CODE.CONFLICT,{code:"item_identity_conflict"});const shared=commonHistoryPrefixLength(ours,theirs);if(shared===ours.length&&shared===theirs.length)return{merged:historyEntriesToRaw(ours),strategy:"identical",common_entries:shared,entries_from_ours:0,entries_from_theirs:0,entries_total:ours.length,reanchored:!1};if(shared===theirs.length)return{merged:historyEntriesToRaw(ours),strategy:"fast_forward_ours",common_entries:shared,entries_from_ours:ours.length-shared,entries_from_theirs:0,entries_total:ours.length,reanchored:!1};if(shared===ours.length)return{merged:historyEntriesToRaw(theirs),strategy:"fast_forward_theirs",common_entries:shared,entries_from_ours:0,entries_from_theirs:theirs.length-shared,entries_total:theirs.length,reanchored:!1};const oursSuffix=ours.slice(shared),seenIdentities=new Set(oursSuffix.map(historyEntryIdentity)),theirsSuffix=theirs.slice(shared).filter(entry=>!seenIdentities.has(historyEntryIdentity(entry))),mergedSuffix=[...oursSuffix,...theirsSuffix].sort((left,right)=>{const byTs=compareTimestampStrings(left.ts,right.ts);if(byTs!==0)return byTs;const leftFromOurs=seenIdentities.has(historyEntryIdentity(left)),rightFromOurs=seenIdentities.has(historyEntryIdentity(right));return leftFromOurs!==rightFromOurs?Number(rightFromOurs)-Number(leftFromOurs):historyEntryIdentity(left).localeCompare(historyEntryIdentity(right))}),reanchored=reanchorHistoryEntries([...ours.slice(0,shared),...mergedSuffix],void 0,{continuousHashSurface:!0});if(reanchored.skippedOps>0)throw new PmCliError(`History union cannot preserve ${reanchored.skippedOps} patch operation(s) after deterministic suffix ordering; leave the file unresolved for manual recovery.`,EXIT_CODE.GENERIC_FAILURE);return{merged:historyEntriesToRaw(reanchored.entries),strategy:"union_reanchor",common_entries:shared,entries_from_ours:oursSuffix.length,entries_from_theirs:theirsSuffix.length,entries_total:reanchored.entries.length,reanchored:!0}}function parseRelationshipJsonl(raw,label){const conflictMarker=findFirstMergeConflictMarker(raw);if(conflictMarker)throw new PmCliError(`Relationship merge input (${label}) contains unresolved conflict markers at line ${conflictMarker.line}. Merge drivers must receive clean per-side versions.`,EXIT_CODE.GENERIC_FAILURE);const events=[];for(const[index,rawLine]of raw.split(/\r?\n/).entries()){const line=rawLine.trim();if(!line)continue;let parsed;try{parsed=JSON.parse(line)}catch{throw new PmCliError(`Relationship merge input (${label}) contains invalid JSON at line ${index+1}.`,EXIT_CODE.GENERIC_FAILURE)}if(typeof parsed!="object"||parsed===null||Array.isArray(parsed)||typeof parsed.eventId!="string"||typeof parsed.sequence!="number")throw new PmCliError(`Relationship merge input (${label}) line ${index+1} is not a relationship event (eventId + sequence required).`,EXIT_CODE.GENERIC_FAILURE);events.push(parsed)}return events}function relationshipEventsToRaw(events){return events.length===0?"":`${events.map(event=>JSON.stringify(event)).join(`
+(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]="c7589997-de92-502d-8e61-ac61b67fe6cd")}catch{}})();import{cloneEmptyReplayDocument,historyEntriesToRaw,normalizeReplayPatchOps,reanchorHistoryEntries,toReplayDocument,tryApplyReplayPatch}from"../../core/history/replay.js";import jsonPatch from"fast-json-patch";import{canonicalDocument,parseItemDocument,serializeItemDocument}from"../../core/item/item-format.js";import{splitAcceptanceCriteria}from"../../core/item/parse.js";import{EXIT_CODE}from"../../core/shared/constants.js";import{findFirstMergeConflictMarker}from"../../core/shared/conflict-markers.js";import{PmCliError}from"../../core/shared/errors.js";import{sha256Hex,stableStringify}from"../../core/shared/serialization.js";import{compareTimestampStrings}from"../../core/shared/time.js";const ITEM_SCALAR_MISSING_VALUE=Object.freeze({pm_item_scalar_missing:!0});function isItemScalarMissingValue(value){return typeof value=="object"&&value!==null&&!Array.isArray(value)&&Object.keys(value).length===1&&value.pm_item_scalar_missing===!0}function encodeItemScalarDecisionValue(value){return value===void 0?ITEM_SCALAR_MISSING_VALUE:value}function hashItemScalarDecisionValue(value){return sha256Hex(stableStringify(value===void 0?{pm_item_scalar_presence:"missing"}:{pm_item_scalar_presence:"present",value}))}function parseHistoryJsonl(raw,label){const conflictMarker=findFirstMergeConflictMarker(raw);if(conflictMarker)throw new PmCliError(`History merge input (${label}) contains unresolved conflict markers at line ${conflictMarker.line}. Merge drivers must receive clean per-side versions.`,EXIT_CODE.GENERIC_FAILURE);const entries=[];for(const[index,rawLine]of raw.split(/\r?\n/).entries()){const line=rawLine.trim();if(line)try{const parsed=JSON.parse(line);if(typeof parsed!="object"||parsed===null||Array.isArray(parsed))throw new TypeError("history entry must be an object");entries.push(parsed)}catch{throw new PmCliError(`History merge input (${label}) contains invalid JSON at line ${index+1}.`,EXIT_CODE.GENERIC_FAILURE)}}return entries}function historyEntryIdentity(entry){return stableStringify({ts:entry.ts,author:entry.author,op:entry.op,patch:entry.patch,message:entry.message??null})}function commonHistoryPrefixLength(ours,theirs){const limit=Math.min(ours.length,theirs.length);let shared=0;for(;shared<limit&&historyEntryIdentity(ours[shared])===historyEntryIdentity(theirs[shared]);)shared+=1;return shared}function orderHistoryUnionSuffix(ours,theirs,incoming,oursIdentities){const entries=[...ours,...incoming],positions=new Map(entries.map((entry,index)=>[entry,index])),aliases=new Map(entries.map((entry,index)=>[historyEntryIdentity(entry),index])),successors=entries.map(()=>new Set);for(const branch of[ours,theirs]){const coordinates=branch.map(entry=>positions.get(entry)??aliases.get(historyEntryIdentity(entry)));for(let index=1;index<coordinates.length;index+=1)coordinates[index-1]!==coordinates[index]&&successors[coordinates[index-1]].add(coordinates[index])}const predecessors=entries.map(()=>0);for(const targets of successors)for(const target of targets)predecessors[target]+=1;const ready=entries.map((_,index)=>index).filter(index=>predecessors[index]===0),result=[];for(;ready.length>0;){ready.sort((leftIndex,rightIndex)=>{const left=entries[leftIndex],right=entries[rightIndex],byTs=compareTimestampStrings(left.ts,right.ts),leftIdentity=historyEntryIdentity(left),rightIdentity=historyEntryIdentity(right);return byTs||Number(oursIdentities.has(rightIdentity))-Number(oursIdentities.has(leftIdentity))});const index=ready.shift();result.push(entries[index]);for(const target of successors[index])predecessors[target]-=1,predecessors[target]===0&&ready.push(target)}if(result.length!==entries.length)throw new PmCliError("History union cannot preserve contradictory original branch event orders; leave the file unresolved for manual recovery.",EXIT_CODE.GENERIC_FAILURE);return result}function createHistoryBranchProjection(entries){return{entries,positions:new Map(entries.map((entry,index)=>[historyEntryIdentity(entry),index])),index:-1,document:cloneEmptyReplayDocument()}}function advanceHistoryBranch(state,target){const end=target??state.index;for(;state.index<end;){const applied=tryApplyReplayPatch(state.document,state.entries[state.index+1].patch);if(!applied.ok)throw new PmCliError("History union cannot preserve a patch that does not apply in its original branch.",EXIT_CODE.GENERIC_FAILURE);state.document=applied.document,state.index+=1}return state.document}function advanceOrderedHistoryBranch(state,target){if(target!==void 0&&target>state.index+1)throw new PmCliError("History union cannot attribute multiple original branch events to one semantic identity; preserve the source histories for manual recovery.",EXIT_CODE.GENERIC_FAILURE);return advanceHistoryBranch(state,target)}function historyUnionPatchProjection(ours,theirs,shared){if(shared===0)return;const oursBranch=createHistoryBranchProjection(ours),theirsBranch=createHistoryBranchProjection(theirs),prefix=advanceHistoryBranch(oursBranch,shared-1);advanceHistoryBranch(theirsBranch,shared-1);let position=0;const unionFields=new Set([...ITEM_UNION_COLLECTION_FIELDS,...ITEM_UNION_DELIMITED_FIELDS]);return(entry,current)=>{if(position++<shared)return entry.patch;const identity=historyEntryIdentity(entry),oursState=advanceOrderedHistoryBranch(oursBranch,oursBranch.positions.get(identity)),theirsState=advanceOrderedHistoryBranch(theirsBranch,theirsBranch.positions.get(identity)),scalarPatch=normalizeReplayPatchOps(entry.patch).filter(operation=>{const[root,field]=operation.path.slice(1).split("/");return root!=="metadata"||!unionFields.has(field)}),scalar=tryApplyReplayPatch(current,scalarPatch);if(!scalar.ok)throw new PmCliError("History union cannot rebase a scalar patch onto the merged replay position; leave the file unresolved for manual recovery.",EXIT_CODE.GENERIC_FAILURE);const merged=mergeItemMetadataRecords(prefix.metadata,oursState.metadata,theirsState.metadata,"ours","latest_document_update",String(oursState.metadata.updated_at),String(theirsState.metadata.updated_at)),next=scalar.document;for(const field of unionFields)Object.hasOwn(merged.merged,field)?next.metadata[field]=merged.merged[field]:delete next.metadata[field];const canonical=toReplayDocument({metadata:next.metadata,body:next.body});return jsonPatch.compare(current,canonical)}}function mergeHistoryStreams(baseRaw,oursRaw,theirsRaw){const base=parseHistoryJsonl(baseRaw,"base"),ours=parseHistoryJsonl(oursRaw,"ours"),theirs=parseHistoryJsonl(theirsRaw,"theirs"),creates=[base,ours,theirs].map(entries=>entries.filter(entry=>entry.op==="create"));if(creates[0].length===0&&creates.slice(1).every(entries=>entries.length>0)||creates.some(entries=>entries.length>1)||new Set(creates.flat().map(historyEntryIdentity)).size>1)throw new PmCliError("Duplicate item identity: history contains independent or unproven create events. Preserve both branches and assign distinct item ids before merging.",EXIT_CODE.CONFLICT,{code:"item_identity_conflict"});const shared=commonHistoryPrefixLength(ours,theirs);if(shared===ours.length&&shared===theirs.length)return{merged:historyEntriesToRaw(ours),strategy:"identical",common_entries:shared,entries_from_ours:0,entries_from_theirs:0,entries_total:ours.length,reanchored:!1};if(shared===theirs.length)return{merged:historyEntriesToRaw(ours),strategy:"fast_forward_ours",common_entries:shared,entries_from_ours:ours.length-shared,entries_from_theirs:0,entries_total:ours.length,reanchored:!1};if(shared===ours.length)return{merged:historyEntriesToRaw(theirs),strategy:"fast_forward_theirs",common_entries:shared,entries_from_ours:0,entries_from_theirs:theirs.length-shared,entries_total:theirs.length,reanchored:!1};const oursSuffix=ours.slice(shared),seenIdentities=new Set(oursSuffix.map(historyEntryIdentity)),theirsSuffix=theirs.slice(shared).filter(entry=>!seenIdentities.has(historyEntryIdentity(entry))),mergedSuffix=orderHistoryUnionSuffix(oursSuffix,theirs.slice(shared),theirsSuffix,seenIdentities),reanchored=reanchorHistoryEntries([...ours.slice(0,shared),...mergedSuffix],void 0,{continuousHashSurface:!0,projectPatch:historyUnionPatchProjection(ours,theirs,shared)});if(reanchored.skippedOps>0)throw new PmCliError(`History union cannot preserve ${reanchored.skippedOps} patch operation(s) after deterministic suffix ordering; leave the file unresolved for manual recovery.`,EXIT_CODE.GENERIC_FAILURE);return{merged:historyEntriesToRaw(reanchored.entries),strategy:"union_reanchor",common_entries:shared,entries_from_ours:oursSuffix.length,entries_from_theirs:theirsSuffix.length,entries_total:reanchored.entries.length,reanchored:!0}}function parseRelationshipJsonl(raw,label){const conflictMarker=findFirstMergeConflictMarker(raw);if(conflictMarker)throw new PmCliError(`Relationship merge input (${label}) contains unresolved conflict markers at line ${conflictMarker.line}. Merge drivers must receive clean per-side versions.`,EXIT_CODE.GENERIC_FAILURE);const events=[];for(const[index,rawLine]of raw.split(/\r?\n/).entries()){const line=rawLine.trim();if(!line)continue;let parsed;try{parsed=JSON.parse(line)}catch{throw new PmCliError(`Relationship merge input (${label}) contains invalid JSON at line ${index+1}.`,EXIT_CODE.GENERIC_FAILURE)}if(typeof parsed!="object"||parsed===null||Array.isArray(parsed)||typeof parsed.eventId!="string"||typeof parsed.sequence!="number")throw new PmCliError(`Relationship merge input (${label}) line ${index+1} is not a relationship event (eventId + sequence required).`,EXIT_CODE.GENERIC_FAILURE);events.push(parsed)}return events}function relationshipEventsToRaw(events){return events.length===0?"":`${events.map(event=>JSON.stringify(event)).join(`
 `)}
 `}function renumberRelationshipEvents(events){return events.map((event,index)=>({...event,sequence:index+1}))}function mergeRelationshipEventStreams(baseRaw,oursRaw,theirsRaw){parseRelationshipJsonl(baseRaw,"base");const ours=parseRelationshipJsonl(oursRaw,"ours"),theirs=parseRelationshipJsonl(theirsRaw,"theirs"),limit=Math.min(ours.length,theirs.length);let shared=0;for(;shared<limit&&ours[shared].eventId===theirs[shared].eventId;)shared+=1;if(shared===ours.length&&shared===theirs.length)return{merged:relationshipEventsToRaw(ours),strategy:"identical",common_entries:shared,entries_from_ours:0,entries_from_theirs:0,entries_total:ours.length,reanchored:!1};if(shared===theirs.length)return{merged:relationshipEventsToRaw(ours),strategy:"fast_forward_ours",common_entries:shared,entries_from_ours:ours.length-shared,entries_from_theirs:0,entries_total:ours.length,reanchored:!1};if(shared===ours.length)return{merged:relationshipEventsToRaw(theirs),strategy:"fast_forward_theirs",common_entries:shared,entries_from_ours:0,entries_from_theirs:theirs.length-shared,entries_total:theirs.length,reanchored:!1};const oursSuffix=ours.slice(shared),oursEventIds=new Set(oursSuffix.map(event=>event.eventId)),theirsSuffix=theirs.slice(shared).filter(event=>!oursEventIds.has(event.eventId)),mergedSuffix=[...oursSuffix,...theirsSuffix].sort((left,right)=>{if(left.timestamp!==void 0&&right.timestamp!==void 0){const byTs=compareTimestampStrings(left.timestamp,right.timestamp);if(byTs!==0)return byTs}else{if(left.timestamp===void 0&&right.timestamp!==void 0)return 1;if(left.timestamp!==void 0)return-1}const leftFromOurs=oursEventIds.has(left.eventId),rightFromOurs=oursEventIds.has(right.eventId);return leftFromOurs!==rightFromOurs?Number(rightFromOurs)-Number(leftFromOurs):0}),merged=renumberRelationshipEvents([...ours.slice(0,shared),...mergedSuffix]);return{merged:relationshipEventsToRaw(merged),strategy:"union_reanchor",common_entries:shared,entries_from_ours:oursSuffix.length,entries_from_theirs:theirsSuffix.length,entries_total:merged.length,reanchored:!0}}const ITEM_UNION_COLLECTION_FIELDS=["tags","dependencies","comments","notes","learnings","files","tests","test_runs","docs","reminders","events"],ITEM_UNION_DELIMITED_FIELDS=["acceptance_criteria"],ITEM_LATEST_TIMESTAMP_FIELDS=["updated_at"];function jsonEquals(left,right){return left===void 0||right===void 0?left===void 0&&right===void 0:stableStringify(left)===stableStringify(right)}function unionCollection(base,ours,theirs){const toEntries=value=>Array.isArray(value)?value:[],baseIds=new Set(toEntries(base).map(entry=>stableStringify(entry))),oursEntries=toEntries(ours),oursIds=new Set(oursEntries.map(entry=>stableStringify(entry))),theirsEntries=toEntries(theirs),theirsIds=new Set(theirsEntries.map(entry=>stableStringify(entry))),merged=oursEntries.filter(entry=>{const identity=stableStringify(entry);return!baseIds.has(identity)||theirsIds.has(identity)});for(const entry of theirsEntries){const identity=stableStringify(entry);!oursIds.has(identity)&&!baseIds.has(identity)&&merged.push(entry)}return merged}function linkedTestDefinitionIdentity(value){if(typeof value!="object"||value===null||Array.isArray(value))return stableStringify(value);const{provenance:_provenance,...definition}=value;return stableStringify(definition)}function markMergedLinkedTest(value){if(typeof value!="object"||value===null||Array.isArray(value))return value;const test=value;return test.provenance?{...test,provenance:{...test.provenance,source_kind:"merge_union"}}:{...test,provenance:{source_kind:"merge_union"}}}function unionLinkedTests(base,ours,theirs){const toEntries=value=>Array.isArray(value)?value:[],baseIds=new Set(toEntries(base).map(linkedTestDefinitionIdentity)),oursEntries=toEntries(ours),oursIds=new Set(oursEntries.map(linkedTestDefinitionIdentity)),theirsEntries=toEntries(theirs),theirsIds=new Set(theirsEntries.map(linkedTestDefinitionIdentity)),merged=oursEntries.filter(entry=>{const identity=linkedTestDefinitionIdentity(entry);return!baseIds.has(identity)||theirsIds.has(identity)});for(const entry of theirsEntries){const identity=linkedTestDefinitionIdentity(entry);!oursIds.has(identity)&&!baseIds.has(identity)&&merged.push(markMergedLinkedTest(entry))}return merged}function latestTimestamp(ours,theirs){return compareTimestampStrings(String(ours),String(theirs))>=0?ours:theirs}function mergeScalarThreeWay(base,ours,theirs,preferred){return jsonEquals(ours,theirs)?{value:ours,from_theirs:!1,conflict:!1}:jsonEquals(base,ours)?{value:theirs,from_theirs:!0,conflict:!1}:jsonEquals(base,theirs)?{value:ours,from_theirs:!1,conflict:!1}:{value:preferred==="theirs"?theirs:ours,from_theirs:preferred==="theirs",conflict:!0}}function mergeItemScalarThreeWay(base,ours,theirs,preferred,conflictResolution,oursUpdatedAt,theirsUpdatedAt){const outcome=mergeScalarThreeWay(base,ours,theirs,preferred);if(!outcome.conflict)return{...outcome,conflict:!1};if(conflictResolution==="preferred_side")return{...outcome,resolution_basis:"requested_preference",retained_side:outcome.from_theirs?"theirs":"ours"};const timestampOrder=compareTimestampStrings(oursUpdatedAt,theirsUpdatedAt);if(conflictResolution==="latest_document_update"&&timestampOrder!==0){const retainTheirs2=timestampOrder<0;return{value:retainTheirs2?theirs:ours,from_theirs:retainTheirs2,conflict:!0,resolution_basis:"document_updated_at",retained_side:retainTheirs2?"theirs":"ours"}}const retainTheirs=stableStringify(encodeItemScalarDecisionValue(theirs)).localeCompare(stableStringify(encodeItemScalarDecisionValue(ours)))<0;return{value:retainTheirs?theirs:ours,from_theirs:retainTheirs,conflict:!0,resolution_basis:"stable_value_tiebreak",retained_side:retainTheirs?"theirs":"ours"}}function toMetadataRecord(document){return{...document.metadata}}function parseItemMergeSide(raw,label,options){try{const document=canonicalDocument(parseItemDocument(raw,options),options),reservedField=Object.entries(document.metadata).find(([,value])=>isItemScalarMissingValue(value))?.[0];if(reservedField!==void 0)throw new TypeError(`metadata field ${reservedField} uses the reserved missing-scalar evidence marker`);return document}catch(error){throw new PmCliError(`Item merge input (${label}) is not a readable item document: ${String(error)}`,EXIT_CODE.GENERIC_FAILURE)}}function mergeItemUnionField(params){if(!params.unionFieldSet.has(params.field))return!1;const union=params.field==="tests"?unionLinkedTests(params.baseValue,params.oursValue,params.theirsValue):params.field==="acceptance_criteria"?unionCollection(splitAcceptanceCriteria(params.baseValue),splitAcceptanceCriteria(params.oursValue),splitAcceptanceCriteria(params.theirsValue)).join("; "):unionCollection(params.baseValue,params.oursValue,params.theirsValue);return params.accumulator.merged[params.field]=union,jsonEquals(union,params.oursValue)||params.accumulator.unionFields.push(params.field),!0}function mergeItemScalarField(params){const outcome=mergeItemScalarThreeWay(params.baseValue,params.oursValue,params.theirsValue,params.preferred,params.conflictResolution,params.oursUpdatedAt,params.theirsUpdatedAt);outcome.value!==void 0&&(params.accumulator.merged[params.field]=outcome.value),outcome.conflict?(params.accumulator.conflictFields.push(params.field),params.accumulator.conflictDecisions.push({field:params.field,base:encodeItemScalarDecisionValue(params.baseValue),ours:encodeItemScalarDecisionValue(params.oursValue),theirs:encodeItemScalarDecisionValue(params.theirsValue),retained:encodeItemScalarDecisionValue(outcome.value),discarded:encodeItemScalarDecisionValue(outcome.from_theirs?params.oursValue:params.theirsValue),retained_side:outcome.retained_side,resolution_basis:outcome.resolution_basis})):outcome.from_theirs&&params.accumulator.fieldsFromTheirs.push(params.field)}function mergeItemMetadataRecords(baseRecord,oursRecord,theirsRecord,preferred,conflictResolution,oursUpdatedAt,theirsUpdatedAt){const unionFieldSet=new Set([...ITEM_UNION_COLLECTION_FIELDS,...ITEM_UNION_DELIMITED_FIELDS]),latestFieldSet=new Set(ITEM_LATEST_TIMESTAMP_FIELDS),fieldNames=[...new Set([...Object.keys(oursRecord),...Object.keys(theirsRecord)])].sort((left,right)=>left.localeCompare(right)),accumulator={merged:{},conflictFields:[],fieldsFromTheirs:[],unionFields:[],conflictDecisions:[]};for(const field of fieldNames){const baseValue=baseRecord[field],oursValue=oursRecord[field],theirsValue=theirsRecord[field];if(!mergeItemUnionField({field,baseValue,oursValue,theirsValue,unionFieldSet,accumulator})){if(latestFieldSet.has(field)){accumulator.merged[field]=latestTimestamp(oursValue,theirsValue);continue}mergeItemScalarField({field,baseValue,oursValue,theirsValue,preferred,conflictResolution,oursUpdatedAt,theirsUpdatedAt,accumulator})}}return accumulator}function mergeItemDocuments(baseRaw,oursRaw,theirsRaw,options={}){const preferred=options.preferred??"ours",conflictResolution=options.conflictResolution??"preferred_side",ours=parseItemMergeSide(oursRaw,"ours",options),theirs=parseItemMergeSide(theirsRaw,"theirs",options);if(baseRaw.trim().length===0)throw new PmCliError("Duplicate item identity: add/add item documents have no common ancestor. Preserve both branches and assign distinct item ids before merging.",EXIT_CODE.CONFLICT,{code:"item_identity_conflict",item_id:ours.metadata.id});const base=parseItemMergeSide(baseRaw,"base",options);if(base.metadata.id!==ours.metadata.id||base.metadata.id!==theirs.metadata.id)throw new PmCliError("Duplicate or mismatched item identity: all merge sides must address the common ancestor's item id.",EXIT_CODE.CONFLICT,{code:"item_identity_conflict",item_id:base.metadata.id});const baseRecord=toMetadataRecord(base),oursRecord=toMetadataRecord(ours),theirsRecord=toMetadataRecord(theirs),{merged,conflictFields,fieldsFromTheirs,unionFields,conflictDecisions}=mergeItemMetadataRecords(baseRecord,oursRecord,theirsRecord,preferred,conflictResolution,ours.metadata.updated_at,theirs.metadata.updated_at),bodyOutcome=mergeItemScalarThreeWay(base.body,ours.body,theirs.body,preferred,conflictResolution,ours.metadata.updated_at,theirs.metadata.updated_at);return bodyOutcome.conflict?(conflictFields.push("body"),conflictDecisions.push({field:"body",base:encodeItemScalarDecisionValue(base.body),ours:encodeItemScalarDecisionValue(ours.body),theirs:encodeItemScalarDecisionValue(theirs.body),retained:encodeItemScalarDecisionValue(bodyOutcome.value),discarded:encodeItemScalarDecisionValue(bodyOutcome.from_theirs?ours.body:theirs.body),retained_side:bodyOutcome.retained_side,resolution_basis:bodyOutcome.resolution_basis})):bodyOutcome.from_theirs&&fieldsFromTheirs.push("body"),{merged:serializeItemDocument({metadata:merged,body:bodyOutcome.value},options),conflict_fields:conflictFields,fields_from_theirs:fieldsFromTheirs,union_fields:unionFields,conflict_decisions:conflictDecisions,requested_preference:preferred,requested_preference_applied:conflictResolution==="preferred_side",conflict_resolution:conflictResolution}}function isPlainObject(value){return typeof value=="object"&&value!==null&&!Array.isArray(value)}function parseJsonSide(raw,label){const conflictMarker=findFirstMergeConflictMarker(raw);if(conflictMarker)throw new PmCliError(`JSON merge input (${label}) contains unresolved conflict markers at line ${conflictMarker.line}.`,EXIT_CODE.GENERIC_FAILURE);if(raw.trim().length!==0)try{return JSON.parse(raw)}catch{throw new PmCliError(`JSON merge input (${label}) is not valid JSON.`,EXIT_CODE.GENERIC_FAILURE)}}function mergeAdditiveJsonArrays(base,ours,theirs){if(!Array.isArray(base)||!Array.isArray(ours)||!Array.isArray(theirs))return null;const countEntries=entries=>{const counts=new Map;for(const entry of entries){const identity=stableStringify(entry);counts.set(identity,(counts.get(identity)??0)+1)}return counts},baseCounts=countEntries(base),oursCounts=countEntries(ours),theirsCounts=countEntries(theirs);for(const[identity,baseCount]of baseCounts)if((oursCounts.get(identity)??0)<baseCount||(theirsCounts.get(identity)??0)<baseCount)return null;const unmatchedOursCounts=new Map(oursCounts),additionsFromTheirs=[];for(const entry of theirs){const identity=stableStringify(entry),unmatchedOursCount=unmatchedOursCounts.get(identity)??0;unmatchedOursCount>0?unmatchedOursCounts.set(identity,unmatchedOursCount-1):additionsFromTheirs.push(entry)}return{merged:[...ours,...additionsFromTheirs],acceptedTheirs:additionsFromTheirs.length>0}}function mergeJsonObjects(base,ours,theirs,preferred,pathPrefix,conflictPaths,pathsFromTheirs){if(!isPlainObject(ours)||!isPlainObject(theirs))return null;const baseObject=isPlainObject(base)?base:{},merged={},keys=[...new Set([...Object.keys(ours),...Object.keys(theirs)])].sort((left,right)=>left.localeCompare(right));for(const key of keys){const childPath=pathPrefix.length>0?`${pathPrefix}.${key}`:key,child=mergeJsonKey(baseObject,ours,theirs,key,preferred,childPath,conflictPaths,pathsFromTheirs);child!==void 0&&(merged[key]=child)}return merged}function mergeJsonValue(base,ours,theirs,preferred,pathPrefix,conflictPaths,pathsFromTheirs){if(jsonEquals(ours,theirs))return ours;const additiveArrayMerge=mergeAdditiveJsonArrays(base,ours,theirs);if(additiveArrayMerge!==null)return additiveArrayMerge.acceptedTheirs&&pathsFromTheirs.push(pathPrefix),additiveArrayMerge.merged;const mergedObject=mergeJsonObjects(base,ours,theirs,preferred,pathPrefix,conflictPaths,pathsFromTheirs);if(mergedObject!==null)return mergedObject;const outcome=mergeScalarThreeWay(base,ours,theirs,preferred);return outcome.conflict?conflictPaths.push(pathPrefix):outcome.from_theirs&&pathsFromTheirs.push(pathPrefix),outcome.value}function mergeJsonKey(base,ours,theirs,key,preferred,childPath,conflictPaths,pathsFromTheirs){const inOurs=Object.prototype.hasOwnProperty.call(ours,key),inTheirs=Object.prototype.hasOwnProperty.call(theirs,key),inBase=Object.prototype.hasOwnProperty.call(base,key);if(inOurs&&inTheirs)return mergeJsonValue(base[key],ours[key],theirs[key],preferred,childPath,conflictPaths,pathsFromTheirs);if(inOurs){if(inBase&&jsonEquals(base[key],ours[key])){pathsFromTheirs.push(childPath);return}return inBase?(conflictPaths.push(childPath),preferred==="theirs"?void 0:ours[key]):ours[key]}if(!(inBase&&jsonEquals(base[key],theirs[key])))return inBase?(conflictPaths.push(childPath),preferred==="theirs"?theirs[key]:void 0):(pathsFromTheirs.push(childPath),theirs[key])}function mergeJsonDocuments(baseRaw,oursRaw,theirsRaw,options={}){const preferred=options.preferred??"ours",base=parseJsonSide(baseRaw,"base"),ours=parseJsonSide(oursRaw,"ours"),theirs=parseJsonSide(theirsRaw,"theirs"),conflictPaths=[],pathsFromTheirs=[],merged=mergeJsonValue(base,ours,theirs,preferred,"",conflictPaths,pathsFromTheirs);return{merged:`${JSON.stringify(merged??null,null,2)}
 `,conflict_paths:conflictPaths,paths_from_theirs:pathsFromTheirs,preferred}}export{ITEM_LATEST_TIMESTAMP_FIELDS,ITEM_SCALAR_MISSING_VALUE,ITEM_UNION_COLLECTION_FIELDS,encodeItemScalarDecisionValue,hashItemScalarDecisionValue,isItemScalarMissingValue,mergeHistoryStreams,mergeItemDocuments,mergeJsonDocuments,mergeRelationshipEventStreams};

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

@@ -3,95 +3,95 @@ import type { HistoryEntry } from "../types/index.js";
 import { type HistoryProvenanceRow, type HistoryProvenanceSummary } from "./history-provenance.js";
 /** Regression budgets for the canonical 200-event wire-cost fixture. */
 export declare const MUTATION_EVENT_WIRE_BUDGET: Readonly<{
-    /** Maximum default batch bytes divided by legacy row-cursor bytes. */
-    batch_to_row_ratio: 0.6;
-    /** Fixture size used to keep the ratio representative of fleet catch-up. */
-    fixture_events: 200;
+/** Maximum default batch bytes divided by legacy row-cursor bytes. */
+batch_to_row_ratio: 0.6;
+/** Fixture size used to keep the ratio representative of fleet catch-up. */
+fixture_events: 200;
 }>;
 interface MutationEventCursorEnvelope {
-    version: number;
-    fingerprint: string;
-    ts: string;
-    stream_id: string;
-    stream_offset: number;
+version: number;
+fingerprint: string;
+ts: string;
+stream_id: string;
+stream_offset: number;
 }
 /** Workspace and filtering controls for mutation-event reads. */
 export interface ListMutationEventsOptions {
-    /** Explicit tracker root, equivalent to global `--pm-path`. */
-    pmRoot?: string;
-    /** Working directory used to discover the nearest tracker. */
-    cwd?: string;
-    /** Opaque cursor or inclusive ISO timestamp lower bound. */
-    since?: string;
-    /** Operation name filter, repeatable through arrays. */
-    type?: string | readonly string[];
-    /** Author filter, repeatable through arrays. */
-    author?: string | readonly string[];
-    /** Item/workspace stream filter, repeatable through arrays. */
-    item?: string | readonly string[];
-    /** Maximum events returned, capped at 1,000. */
-    limit?: number;
-    /** Include the complete history entry instead of the compact projection. */
-    full?: boolean;
-    /** Return patch-free provenance instead of the compact event projection. */
-    provenance?: boolean;
-    /** Include bounded provenance completeness counts for the returned page. */
-    provenanceSummary?: boolean;
-    /** Filter by canonical recorded or vocabulary-resolved harness. */
-    harness?: string | readonly string[];
-    /** Filter by privacy-safe invocation fingerprint. */
-    agentInstance?: string | readonly string[];
-    /** Exact provenance dimension predicates (`dimension=value`). */
-    provenanceFilter?: string | readonly string[];
-    /** Cursor framing mode; batch is the token-efficient default. */
-    cursorMode?: "batch" | "row";
+/** Explicit tracker root, equivalent to global `--pm-path`. */
+pmRoot?: string;
+/** Working directory used to discover the nearest tracker. */
+cwd?: string;
+/** Opaque cursor or inclusive ISO timestamp lower bound. */
+since?: string;
+/** Operation name filter, repeatable through arrays. */
+type?: string | readonly string[];
+/** Author filter, repeatable through arrays. */
+author?: string | readonly string[];
+/** Item/workspace stream filter, repeatable through arrays. */
+item?: string | readonly string[];
+/** Maximum events returned, capped at 1,000. */
+limit?: number;
+/** Include the complete history entry instead of the compact projection. */
+full?: boolean;
+/** Return patch-free provenance instead of the compact event projection. */
+provenance?: boolean;
+/** Include bounded provenance completeness counts for the returned page. */
+provenanceSummary?: boolean;
+/** Filter by canonical recorded or vocabulary-resolved harness. */
+harness?: string | readonly string[];
+/** Filter by privacy-safe invocation fingerprint. */
+agentInstance?: string | readonly string[];
+/** Exact provenance dimension predicates (`dimension=value`). */
+provenanceFilter?: string | readonly string[];
+/** Cursor framing mode; batch is the token-efficient default. */
+cursorMode?: "batch" | "row";
 }
 /** One ordered cross-item mutation event. */
 export interface MutationEvent {
-    /** Cursor that resumes strictly after this event. */
-    cursor?: string;
-    /** Item id or `_workspace` stream subject. */
-    item_id: string;
-    /** One-based version within the subject's stream. */
-    version: number;
-    /** Mutation timestamp. */
-    ts: string;
-    /** Attributed mutation author. */
-    author: string;
-    /** Stable mutation operation. */
-    type: string;
-    /** Optional mutation message. */
-    message?: string;
-    /** Number of JSON Patch operations in the history entry. */
-    patch_count: number;
-    /** Complete authoritative history entry when `full` is requested. */
-    entry?: HistoryEntry;
-    /** Patch-free provenance row when requested. */
-    provenance?: HistoryProvenanceRow;
+/** Cursor that resumes strictly after this event. */
+cursor?: string;
+/** Item id or `_workspace` stream subject. */
+item_id: string;
+/** One-based version within the subject's stream. */
+version: number;
+/** Mutation timestamp. */
+ts: string;
+/** Attributed mutation author. */
+author: string;
+/** Stable mutation operation. */
+type: string;
+/** Optional mutation message. */
+message?: string;
+/** Number of JSON Patch operations in the history entry. */
+patch_count: number;
+/** Complete authoritative history entry when `full` is requested. */
+entry?: HistoryEntry;
+/** Patch-free provenance row when requested. */
+provenance?: HistoryProvenanceRow;
 }
 /** Bounded event page returned by {@link listMutationEvents}. */
 export interface MutationEventPage {
-    /** Ordered mutation events. */
-    events: MutationEvent[];
-    /** Number of events in this page. */
-    count: number;
-    /** Whether another matching event is immediately available. */
-    has_more: boolean;
-    /** Cursor framing used by this page. */
-    cursor_mode: "batch" | "row";
-    /** Cursor that resumes after the final returned event. */
-    next_cursor?: string;
-    /** Persistent derived projection used for the read. */
-    source: "derived_index" | "authoritative_history";
-    /** Constant-size provenance completeness metrics for the returned page. */
-    provenance_summary?: HistoryProvenanceSummary;
+/** Ordered mutation events. */
+events: MutationEvent[];
+/** Number of events in this page. */
+count: number;
+/** Whether another matching event is immediately available. */
+has_more: boolean;
+/** Cursor framing used by this page. */
+cursor_mode: "batch" | "row";
+/** Cursor that resumes after the final returned event. */
+next_cursor?: string;
+/** Persistent derived projection used for the read. */
+source: "derived_index" | "authoritative_history";
+/** Constant-size provenance completeness metrics for the returned page. */
+provenance_summary?: HistoryProvenanceSummary;
 }
 /** Follow controls accepted by {@link subscribeMutationEvents}. */
 export interface SubscribeMutationEventsOptions extends ListMutationEventsOptions {
-    /** Delay between empty catch-up reads. */
-    intervalMs?: number;
-    /** Cancellation signal for a long-lived subscription. */
-    signal?: AbortSignal;
+/** Delay between empty catch-up reads. */
+intervalMs?: number;
+/** Cancellation signal for a long-lived subscription. */
+signal?: AbortSignal;
 }
 declare function eventQueryFingerprint(options: ListMutationEventsOptions): string;
 declare function encodeMutationEventCursor(event: IndexedHistoryEvent, fingerprint: string): string;
@@ -100,8 +100,8 @@ declare function decodeMutationEventCursor(cursor: string, fingerprint: string):
 declare function parseMutationEventLimit(value: number | undefined): number;
 declare function isAbortError(error: unknown): boolean;
 declare function resolveMutationEventStart(sinceValue: string | undefined, fingerprint: string): {
-    cursor?: MutationEventCursorEnvelope;
-    sinceTimestamp?: string;
+cursor?: MutationEventCursorEnvelope;
+sinceTimestamp?: string;
 };
 /** Read one bounded page of mutation events from the persistent projection. */
 export declare function listMutationEvents(options?: ListMutationEventsOptions): Promise<MutationEventPage>;
@@ -117,12 +117,12 @@ export declare function subscribeMutationEventBatches(options?: SubscribeMutatio
 export declare function subscribeMutationEvents(options?: SubscribeMutationEventsOptions): AsyncGenerator<MutationEvent, void, void>;
 /** Public test seams for cursor contract verification. */
 export declare const _testOnlyMutationEvents: {
-    decodeMutationEventCursor: typeof decodeMutationEventCursor;
-    encodeMutationEventCursor: typeof encodeMutationEventCursor;
-    eventQueryFingerprint: typeof eventQueryFingerprint;
-    isAbortError: typeof isAbortError;
-    isMutationEventCursorEnvelope: typeof isMutationEventCursorEnvelope;
-    parseMutationEventLimit: typeof parseMutationEventLimit;
-    resolveMutationEventStart: typeof resolveMutationEventStart;
+decodeMutationEventCursor: typeof decodeMutationEventCursor;
+encodeMutationEventCursor: typeof encodeMutationEventCursor;
+eventQueryFingerprint: typeof eventQueryFingerprint;
+isAbortError: typeof isAbortError;
+isMutationEventCursorEnvelope: typeof isMutationEventCursorEnvelope;
+parseMutationEventLimit: typeof parseMutationEventLimit;
+resolveMutationEventStart: typeof resolveMutationEventStart;
 };
 export {};