@unbrained/pm-cli 2026.10.14 → 2026.10.17

package/dist/sdk/search-refresh-worker.d.ts

@@ -1,2 +1,2 @@
 /** Drain the active workspace's pending semantic-refresh queue. */
-export declare function runSearchRefreshWorkerEntrypoint(): Promise<void>;
+export declare function runSearchRefreshWorkerEntrypoint():Promise<void>;

package/dist/sdk/similarity-scoring.d.ts

@@ -2,26 +2,26 @@ export { jaccardSimilarity } from "../core/shared/text-normalization.js";
 /** Precomputed title signals reused by bounded batch similarity operations. */
 export interface PreparedSimilarityText {
 /** Canonical title used for exact comparison. */
-normalized: string;
+normalized:string;
 /** Unique normalized word tokens. */
-tokens: string[];
+tokens:string[];
 /** Unique issue identifiers embedded in the title. */
-issueCodes: string[];
+issueCodes:string[];
 }
 /** Stable score and strongest signal returned by title comparison. */
 export interface ItemSimilarityScore {
 /** Similarity on the zero-to-one scale. */
-score: number;
+score:number;
 /** Strongest deterministic match signal. */
-reason: "exact_title" | "issue_code" | "title_token_jaccard";
+reason:"exact_title" | "issue_code" | "title_token_jaccard";
 }
 /** Normalize title text for exact comparisons and tokenization. */
-export declare function normalizeSimilarityText(value: string): string;
+export declare function normalizeSimilarityText(value:string):string;
 /** Split normalized text into unique Unicode letter/number tokens. */
-export declare function tokenizeSimilarityText(value: string): string[];
+export declare function tokenizeSimilarityText(value:string):string[];
 /** Precompute every deterministic title signal exactly once for repeated comparisons. */
-export declare function prepareSimilarityText(value: string): PreparedSimilarityText;
+export declare function prepareSimilarityText(value:string):PreparedSimilarityText;
 /** Score two titles through the canonical exact, issue-code, and token signals. */
-export declare function scoreItemSimilarity(leftTitle: string, rightTitle: string): ItemSimilarityScore;
+export declare function scoreItemSimilarity(leftTitle:string,rightTitle:string):ItemSimilarityScore;
 /** Score two precomputed title representations without repeating normalization or tokenization. */
-export declare function scorePreparedItemSimilarity(left: PreparedSimilarityText, right: PreparedSimilarityText): ItemSimilarityScore;
+export declare function scorePreparedItemSimilarity(left:PreparedSimilarityText,right:PreparedSimilarityText):ItemSimilarityScore;

package/dist/sdk/similarity.d.ts

@@ -1,175 +1,175 @@
 import { collectDuplicateCandidatePairs } from "./query/duplicate-candidates.js";
 import type { ItemMetadata } from "../types/index.js";
 import { type PreparedSimilarityText } from "./similarity-scoring.js";
-export { jaccardSimilarity, normalizeSimilarityText, prepareSimilarityText, scoreItemSimilarity, scorePreparedItemSimilarity, tokenizeSimilarityText, type ItemSimilarityScore, type PreparedSimilarityText, } from "./similarity-scoring.js";
+export { jaccardSimilarity,normalizeSimilarityText,prepareSimilarityText,scoreItemSimilarity,scorePreparedItemSimilarity,tokenizeSimilarityText,type ItemSimilarityScore,type PreparedSimilarityText,} from "./similarity-scoring.js";
 /** Candidate content accepted by the similarity primitive. */
 export interface SimilarItemCandidate {
 /** Proposed title. */
-title: string;
+title:string;
 /** Optional description used by future semantic providers. */
-description?: string;
+description?:string;
 /** Optional body used by future semantic providers. */
-body?: string;
+body?:string;
 /** Existing ids to omit, such as a copy source or current item. */
-excludeIds?: readonly string[];
+excludeIds?:readonly string[];
 }
 /** Query controls for {@link findSimilarItems}. */
 export interface FindSimilarItemsOptions {
 /** Explicit tracker root. */
-pmRoot?: string;
+pmRoot?:string;
 /** Workspace used for nearest-tracker discovery. */
-cwd?: string;
+cwd?:string;
 /** Maximum returned matches, from zero through twenty. */
-limit?: number;
+limit?:number;
 /** Inclusive score threshold on the zero-to-one scale. */
-threshold?: number;
+threshold?:number;
 }
 /** One likely existing duplicate. */
 export interface SimilarItemMatch {
 /** Existing item id. */
-id: string;
+id:string;
 /** Existing item title. */
-title: string;
+title:string;
 /** Existing lifecycle status. */
-status: string;
+status:string;
 /** Existing item type. */
-type: string;
+type:string;
 /** Stable similarity score on the zero-to-one scale. */
-score: number;
+score:number;
 /** Strongest deterministic match signal. */
-reason: "exact_title" | "issue_code" | "title_token_jaccard";
+reason:"exact_title" | "issue_code" | "title_token_jaccard";
 }
 /** Bounded similarity query result. */
 export interface SimilarItemsResult {
 /** Ranked likely duplicates. */
-items: SimilarItemMatch[];
+items:SimilarItemMatch[];
 /** Number of returned matches. */
-count: number;
+count:number;
 /** Effective threshold. */
-threshold: number;
+threshold:number;
 /** Retrieval path used before shared scoring. */
-source: "persistent_index" | "metadata_fallback";
+source:"persistent_index" | "metadata_fallback";
 }
 /** Query controls for one all-status duplicate-cluster sweep. */
 export interface FindDuplicateClustersOptions extends FindSimilarItemsOptions {
 /** Compare every pair as an exact oracle; retains the declared safety bound. */
-exhaustive?: boolean;
+exhaustive?:boolean;
 /** Lifecycle statuses to include; omit to inspect every status. */
-statuses?: readonly string[];
+statuses?:readonly string[];
 /** Inclusive ISO timestamp lower bound on item creation. */
-since?: string;
+since?:string;
 }
 /** One deterministic pair that caused items to join a duplicate cluster. */
 export interface DuplicateClusterMatch {
 /** First item id in lexical order. */
-left_id: string;
+left_id:string;
 /** Second item id in lexical order. */
-right_id: string;
+right_id:string;
 /** Canonical deterministic score. */
-score: number;
+score:number;
 /** Strongest deterministic signal. */
-reason: SimilarItemMatch["reason"];
+reason:SimilarItemMatch["reason"];
 }
 /** One connected component of likely duplicate items. */
 export interface DuplicateCluster {
 /** Stable cluster key derived from the lexically first item id. */
-id: string;
+id:string;
 /** Item summaries ordered by id. */
-items: Omit<SimilarItemMatch, "score" | "reason">[];
+items:Omit<SimilarItemMatch,"score" | "reason">[];
 /** Qualifying pair evidence ordered by score then ids. */
-matches: DuplicateClusterMatch[];
+matches:DuplicateClusterMatch[];
 /** Strongest pair score in this component. */
-max_score: number;
+max_score:number;
 }
 /** Bounded batch duplicate analysis result with explicit cost disclosure. */
 export interface DuplicateClustersResult {
 /** Connected duplicate components. */
-clusters: DuplicateCluster[];
+clusters:DuplicateCluster[];
 /** Number of returned components. */
-count: number;
+count:number;
 /** Effective threshold. */
-threshold: number;
+threshold:number;
 /** Retrieval path used for this whole-workspace sweep. */
-source: "metadata_scan";
+source:"metadata_scan";
 /** Effective lifecycle filter; null means the complete all-status corpus. */
-filters: {
-statuses: string[] | null;
-since: string | null;
+filters:{
+statuses:string[] | null;
+since:string | null;
 };
 /** Work performed after the single metadata read. */
-cost: {
+cost:{
 /** Items retained after filters. */
-item_count: number;
+item_count:number;
 /** Algorithm used to generate candidates before canonical scoring. */
-algorithm: "prefix_exact" | "exhaustive";
+algorithm:"prefix_exact" | "exhaustive";
 /** Pairs in the exhaustive population, including pairs pruned without scoring. */
-possible_pairs: number;
+possible_pairs:number;
 /** Safety ceiling, exceeded only by an explicit refusal. */
-pair_limit: number;
+pair_limit:number;
 /** Every qualifying pair is retained by candidate generation. */
-recall_guarantee: "exact";
+recall_guarantee:"exact";
 /** Candidate pairs sharing at least one deterministic signal. */
-candidate_pairs: number;
+candidate_pairs:number;
 /** Candidate pairs scored. */
-scored_pairs: number;
+scored_pairs:number;
 };
 }
 interface PreparedDuplicateItem {
-item: Pick<ItemMetadata, "id" | "title" | "status" | "type">;
-prepared: PreparedSimilarityText;
+item:Pick<ItemMetadata,"id" | "title" | "status" | "type">;
+prepared:PreparedSimilarityText;
 }
 /** Create/copy governance envelope attached when likely duplicates exist. */
 export interface SimilarityAdvisory {
 /** Effective governance mode. */
-mode: "advisory" | "strict";
+mode:"advisory" | "strict";
 /** Whether strict enforcement was explicitly bypassed. */
-bypassed: boolean;
+bypassed:boolean;
 /** Shared similarity query result. */
-result: SimilarItemsResult;
+result:SimilarItemsResult;
 /** Executable next action selected from the strongest matching item's lifecycle state. */
-recovery: SimilarityRecovery;
+recovery:SimilarityRecovery;
 }
 /** Executable duplicate-intake recovery selected from the strongest match. */
 export interface SimilarityRecovery {
 /** Whether to continue existing active work or reopen terminal work as a recurrence. */
-action: "reuse" | "reopen";
+action:"reuse" | "reopen";
 /** Strongest matching canonical item. */
-item_id: string;
+item_id:string;
 /** Shell-form recovery command. */
-command: string;
+command:string;
 /** Tokenized recovery command for direct execution. */
-args: string[];
+args:string[];
 }
 /** Render compact warning tokens shared by create and copy results. */
-export declare function similarityAdvisoryWarnings(advisory: SimilarityAdvisory | undefined): string[];
+export declare function similarityAdvisoryWarnings(advisory:SimilarityAdvisory | undefined):string[];
 /** Internal deterministic seams used to prove bounded batch behavior without building a million-pair fixture. */
-export declare const _testOnlySimilarity: {
-buildDuplicateClusters: typeof buildDuplicateClusters;
-collectDuplicateCandidatePairs: typeof collectDuplicateCandidatePairs;
-createDuplicateUnionFind: typeof createDuplicateUnionFind;
+export declare const _testOnlySimilarity:{
+buildDuplicateClusters:typeof buildDuplicateClusters;
+collectDuplicateCandidatePairs:typeof collectDuplicateCandidatePairs;
+createDuplicateUnionFind:typeof createDuplicateUnionFind;
 };
-declare function createDuplicateUnionFind(size: number): {
-parent: number[];
-findRoot: (index: number) => number;
+declare function createDuplicateUnionFind(size:number):{
+parent:number[];
+findRoot:(index:number) => number;
 };
 /** Group unioned endpoints and their scored evidence once, then deterministically rank and limit complete components. */
-declare function buildDuplicateClusters(items: PreparedDuplicateItem[], matches: DuplicateClusterMatch[], union: ReturnType<typeof createDuplicateUnionFind>, limit: number): DuplicateCluster[];
+declare function buildDuplicateClusters(items:PreparedDuplicateItem[],matches:DuplicateClusterMatch[],union:ReturnType<typeof createDuplicateUnionFind>,limit:number):DuplicateCluster[];
 /** Find likely existing duplicates through an index-first bounded read. */
-export declare function findSimilarItems(candidate: SimilarItemCandidate, options?: FindSimilarItemsOptions): Promise<SimilarItemsResult>;
+export declare function findSimilarItems(candidate:SimilarItemCandidate,options?:FindSimilarItemsOptions):Promise<SimilarItemsResult>;
 /** Minimal metadata accepted from package-owned or remote project stores. */
-export type DuplicateItemInput = Pick<ItemMetadata, "id" | "title" | "status" | "type">;
+export type DuplicateItemInput = Pick<ItemMetadata,"id" | "title" | "status" | "type">;
 /** Exact in-memory duplicate analysis, independent of a filesystem workspace. */
-export type DuplicateItemsAnalysis = Omit<DuplicateClustersResult, "source" | "filters">;
+export type DuplicateItemsAnalysis = Omit<DuplicateClustersResult,"source" | "filters">;
 /**
  * Cluster caller-owned metadata using the same scorer and safety bounds as the CLI.
  * Candidate filtering is lossless; exhaustive mode provides an independent pair
  * population for recall checks. Inputs are copied, sorted and never mutated.
  */
-export declare function analyzeDuplicateItems(input: readonly DuplicateItemInput[], options?: Pick<FindDuplicateClustersOptions, "threshold" | "limit" | "exhaustive">): DuplicateItemsAnalysis;
+export declare function analyzeDuplicateItems(input:readonly DuplicateItemInput[],options?:Pick<FindDuplicateClustersOptions,"threshold" | "limit" | "exhaustive">):DuplicateItemsAnalysis;
 /** Find connected duplicate clusters with one metadata read and shared package analysis. */
-export declare function findDuplicateClusters(options?: FindDuplicateClustersOptions): Promise<DuplicateClustersResult>;
+export declare function findDuplicateClusters(options?:FindDuplicateClustersOptions):Promise<DuplicateClustersResult>;
 /** Apply off/advisory/strict mutation governance through the shared query. */
-export declare function evaluateSimilarityGovernance(candidate: SimilarItemCandidate, options: FindSimilarItemsOptions & {
-mode: "off" | "advisory" | "strict";
-allowDuplicate?: boolean;
-}): Promise<SimilarityAdvisory | undefined>;
+export declare function evaluateSimilarityGovernance(candidate:SimilarItemCandidate,options:FindSimilarItemsOptions & {
+mode:"off" | "advisory" | "strict";
+allowDuplicate?:boolean;
+}):Promise<SimilarityAdvisory | undefined>;

package/dist/sdk/start-task-status.d.ts

@@ -5,4 +5,4 @@
  */
 import { type RuntimeStatusRegistry } from "../core/schema/runtime-schema.js";
 /** Resolve the status the `start-task` lifecycle alias should move an item to. Resolves `in_progress` strictly through the workspace registry so a custom workflow that omits in_progress falls back to its open status instead of setting a status the workflow does not define. */
-export declare function resolveStartTaskInProgressStatus(statusRegistry: RuntimeStatusRegistry): string;
+export declare function resolveStartTaskInProgressStatus(statusRegistry:RuntimeStatusRegistry):string;

package/dist/sdk/stats.d.ts

@@ -1,139 +1,139 @@
 import { type ContentFieldUtilizationReport } from "../core/governance/content-fields.js";
-import { type CoverageItem, type GroupedBreakdown, type LifecycleClassifier, type MetadataCoverageReport } from "../core/governance/metadata-coverage.js";
+import { type CoverageItem,type GroupedBreakdown,type LifecycleClassifier,type MetadataCoverageReport } from "../core/governance/metadata-coverage.js";
 import { type HistoryStorageStats } from "../core/history/history-storage-stats.js";
 import type { GlobalOptions } from "../core/shared/command-types.js";
-import type { ItemStatus, ItemType } from "../types/index.js";
-import { type ImprovementDirection, type ImprovementLedgerResult, type RecordImprovementObservationResult } from "./improvement-ledger.js";
-import { type FleetAttributionAnalytics, type ProvenanceCoverageAnalytics } from "./history-analytics.js";
+import type { ItemStatus,ItemType } from "../types/index.js";
+import { type ImprovementDirection,type ImprovementLedgerResult,type RecordImprovementObservationResult } from "./improvement-ledger.js";
+import { type FleetAttributionAnalytics,type ProvenanceCoverageAnalytics } from "./history-analytics.js";
 /** Documents the stats command options payload exchanged by command, SDK, and package integrations. */
 export interface StatsCommandOptions {
 /** Restore zero-count item-type and status buckets for schema-governance dashboards. */
-includeEmpty?: boolean;
+includeEmpty?:boolean;
 /** Include aggregate per-stream history storage metrics (sizes, depth, oldest/newest). */
-storage?: boolean;
+storage?:boolean;
 /** Include metadata coverage percentages (AC, estimates, resolution, tags, parent) overall and by type. */
-metadataCoverage?: boolean;
+metadataCoverage?:boolean;
 /** Include a lifecycle-bucketed breakdown grouped by assignee. */
-byAssignee?: boolean;
+byAssignee?:boolean;
 /** Include a lifecycle-bucketed breakdown grouped by tag (optionally filtered by --tag-prefix). */
-byTag?: boolean;
+byTag?:boolean;
 /** Include a lifecycle-bucketed breakdown grouped by priority. */
-byPriority?: boolean;
+byPriority?:boolean;
 /** With --by-tag: only consider tags starting with this prefix (e.g. "domain:"). */
-tagPrefix?: string;
+tagPrefix?:string;
 /** Include a content-field utilization breakdown (notes/learnings/files/docs/tests/comments/deps/body usage rates). */
-fieldUtilization?: boolean;
+fieldUtilization?:boolean;
 /** Include the audited improvement observation ledger and derived trends. */
-measurements?: boolean;
+measurements?:boolean;
 /** Exact improvement metric filter used with --measurements. */
-metric?: string;
+metric?:string;
 /** Maximum newest improvement observations returned. */
-measurementLimit?: number;
+measurementLimit?:number;
 /** Repeatable name=value[,unit=...][,threshold=...] observations to append. */
-observe?: string[];
+observe?:string[];
 /** Improvement direction applied to newly recorded observations. */
-direction?: ImprovementDirection;
+direction?:ImprovementDirection;
 /** Producing gate or instrument associated with new observations. */
-measurementSource?: string;
+measurementSource?:string;
 /** Tracked owner associated with new observations. */
-measurementItem?: string;
+measurementItem?:string;
 /** Explicit source revision for new observations. */
-measurementRevision?: string;
+measurementRevision?:string;
 /** Intentional mutation author override. */
-author?: string;
+author?:string;
 /** Human-readable observation audit rationale. */
-message?: string;
+message?:string;
 /** Include live declared-versus-observed provenance coverage. */
-provenanceCoverage?: boolean;
+provenanceCoverage?:boolean;
 /** Include immutable-history fleet outcome attribution. */
-fleetAttribution?: boolean;
+fleetAttribution?:boolean;
 /** Inclusive history analytics lower bound or negative duration. */
-since?: string;
+since?:string;
 /** Maximum immutable events consumed by each analytics projection. */
-eventLimit?: number;
+eventLimit?:number;
 /** Minimum close or explicit-value denominator required for rates. */
-minimumSample?: number;
+minimumSample?:number;
 }
 /** Compact, tabular lifecycle row used by the default stats type distribution. */
 export interface StatsTypeLifecycleRow {
 /** Item type represented by this row. */
-type: string;
+type:string;
 /** Total items of this type across every lifecycle bucket. */
-total: number;
+total:number;
 /** Items in the default open lifecycle bucket. */
-open: number;
+open:number;
 /** Items in active non-default lifecycle states. */
-in_progress: number;
+in_progress:number;
 /** Items in blocked lifecycle states. */
-blocked: number;
+blocked:number;
 /** Items in draft lifecycle states. */
-draft: number;
+draft:number;
 /** Items in completed lifecycle states. */
-closed: number;
+closed:number;
 /** Items in canceled lifecycle states. */
-canceled: number;
+canceled:number;
 /** Items whose custom status is outside the recognized lifecycle buckets. */
-other: number;
+other:number;
 }
 /** Screen-sized type distribution rendered as one canonical TOON table. */
 export type StatsTypeBreakdown = StatsTypeLifecycleRow[];
 /** Documents the stats result payload exchanged by command, SDK, and package integrations. */
 export interface StatsResult {
 /** Value that configures or reports totals for this contract. */
-totals: {
-items: number;
-history_streams: number;
-history_entries: number;
+totals:{
+items:number;
+history_streams:number;
+history_entries:number;
 };
 /** Schema type that determines the shape and validation rules for this value. */
-by_type: StatsTypeBreakdown;
+by_type:StatsTypeBreakdown;
 /** Item counts grouped by lifecycle status. */
-by_status: Partial<Record<ItemStatus, number>>;
+by_status:Partial<Record<ItemStatus,number>>;
 /** Total zero-count type and status buckets omitted from the default projection. */
-omitted_zero_buckets: number;
+omitted_zero_buckets:number;
 /** Present only with --metadata-coverage: per-field coverage overall and by type. */
-metadata_coverage?: MetadataCoverageReport;
+metadata_coverage?:MetadataCoverageReport;
 /** Present only with --by-assignee/--by-tag/--by-priority: lifecycle-bucketed group breakdowns. */
-breakdowns?: {
-assignee?: GroupedBreakdown;
-tag?: GroupedBreakdown;
-priority?: GroupedBreakdown;
+breakdowns?:{
+assignee?:GroupedBreakdown;
+tag?:GroupedBreakdown;
+priority?:GroupedBreakdown;
 };
 /** Present only with --storage: aggregate history-stream metrics for compaction/planning. */
-storage?: HistoryStorageStats;
+storage?:HistoryStorageStats;
 /** Present only with --field-utilization: content-field utilization rates across all items. */
-field_utilization?: ContentFieldUtilizationReport;
+field_utilization?:ContentFieldUtilizationReport;
 /** Audited improvement observations and baseline-to-latest trends. */
-improvement_ledger?: ImprovementLedgerResult;
+improvement_ledger?:ImprovementLedgerResult;
 /** Receipts for observations appended by this invocation. */
-recorded_observations?: RecordImprovementObservationResult[];
+recorded_observations?:RecordImprovementObservationResult[];
 /** Live provenance coverage over a bounded immutable-history window. */
-provenance_coverage?: ProvenanceCoverageAnalytics;
+provenance_coverage?:ProvenanceCoverageAnalytics;
 /** Bounded fleet attribution derived from immutable history. */
-fleet_attribution?: FleetAttributionAnalytics;
+fleet_attribution?:FleetAttributionAnalytics;
 /** ISO 8601 timestamp recording when generated occurred. */
-generated_at: string;
+generated_at:string;
 }
-declare function zeroByType(itemTypes: string[]): Record<ItemType, number>;
-declare function zeroByStatus(statuses: string[]): Record<ItemStatus, number>;
-declare function projectStatsDistributions(items: readonly CoverageItem[], itemTypes: readonly string[], statuses: readonly string[], classifier: LifecycleClassifier, includeEmpty: boolean): {
-byType: StatsTypeBreakdown;
-byStatus: Partial<Record<ItemStatus, number>>;
-omitted: number;
+declare function zeroByType(itemTypes:string[]):Record<ItemType,number>;
+declare function zeroByStatus(statuses:string[]):Record<ItemStatus,number>;
+declare function projectStatsDistributions(items:readonly CoverageItem[],itemTypes:readonly string[],statuses:readonly string[],classifier:LifecycleClassifier,includeEmpty:boolean):{
+byType:StatsTypeBreakdown;
+byStatus:Partial<Record<ItemStatus,number>>;
+omitted:number;
 };
-declare function countNonEmptyLines(raw: string): number;
-declare function readHistoryStreamContents(pmRoot: string): Promise<Array<{
-id: string;
-raw: string;
+declare function countNonEmptyLines(raw:string):number;
+declare function readHistoryStreamContents(pmRoot:string):Promise<Array<{
+id:string;
+raw:string;
 }>>;
 /** Public contract for test only, shared by SDK and presentation-layer consumers. */
-export declare const _testOnly: {
-zeroByType: typeof zeroByType;
-zeroByStatus: typeof zeroByStatus;
-countNonEmptyLines: typeof countNonEmptyLines;
-readHistoryStreamContents: typeof readHistoryStreamContents;
-projectStatsDistributions: typeof projectStatsDistributions;
+export declare const _testOnly:{
+zeroByType:typeof zeroByType;
+zeroByStatus:typeof zeroByStatus;
+countNonEmptyLines:typeof countNonEmptyLines;
+readHistoryStreamContents:typeof readHistoryStreamContents;
+projectStatsDistributions:typeof projectStatsDistributions;
 };
 /** Implements run stats for the public runtime surface of this module. */
-export declare function runStats(global: GlobalOptions, options?: StatsCommandOptions): Promise<StatsResult>;
+export declare function runStats(global:GlobalOptions,options?:StatsCommandOptions):Promise<StatsResult>;
 export {};

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

@@ -1,41 +1,92 @@
 import type { BulkItemMutation } from "./item-transaction.js";
 import { type RuntimeFieldDefinitionResolved } from "../core/schema/runtime-schema.js";
+/** One existing workspace item considered by keyed upsert resolution. */
+export interface ItemMutationUpsertCandidate {
+/** Canonical id of the existing item. */
+id:string;
+/** Current value of the upsert key field on that item. */
+value:unknown;
+}
+/** Keyed-upsert policy applied to create rows of one mutation document. */
+export interface ItemMutationUpsertOptions {
+/** Item field (core or declared custom metadata key) whose value identifies an existing item. */
+key:string;
+/**
+     * Existing items that carry a value for the key, read before the writer
+     * lock. Items this very document would create (its deterministic create
+     * ids) are never candidates, so a replay of a committed import keeps its
+     * original create plan instead of mutating into updates.
+     */
+existing:readonly ItemMutationUpsertCandidate[];
+}
 /** Controls for resolving one versioned mutation document. */
 export interface ResolveItemMutationDocumentOptions {
 /** Stable transaction identity used to derive replay-safe create ids. */
-transactionId: string;
+transactionId:string;
 /** Workspace item-id prefix. */
-idPrefix: string;
+idPrefix:string;
+/** Resolved schema fields that route document keys through declared option names. */
+runtimeFields?:readonly RuntimeFieldDefinitionResolved[];
+/** Optional keyed upsert: create rows matching one existing item become updates. */
+upsert?:ItemMutationUpsertOptions;
+}
+/** Input-ordered receipt row mapping one source record to its resolved mutation. */
+export interface ResolvedItemMutationRow {
+/** Zero-based position of the source record in the document. */
+index:number;
+/** Batch-local alias when the row declared or received one. */
+ref?:string;
+/** Concrete item id the mutation targets. */
+id:string;
+/** Operation applied for this row after upsert resolution. */
+op:BulkItemMutation["op"];
+/** Whether keyed upsert turned a create row into an update of an existing item. */
+upserted?:true;
 }
 /** Fully validated mutation document ready for preview or commit. */
 export interface ResolvedItemMutationDocument {
 /** Versioned structured-input contract. */
-schema_version: 1;
+schema_version:1;
 /** Atomic mutations with every local reference replaced by a concrete id. */
-mutations: BulkItemMutation[];
+mutations:BulkItemMutation[];
 /** Batch-local alias to concrete-id receipt. */
-references: Record<string, string>;
+references:Record<string,string>;
+/** Input-ordered receipt mapping each source record to its resolved id and operation. */
+rows:ResolvedItemMutationRow[];
 }
+/**
+ * Derive a stable transaction id from the exact document bytes so that
+ * re-running an identical import resumes or replays the same journal instead
+ * of duplicating items. Any change to the document yields a new id.
+ */
+export declare function deriveMutationTransactionId(input:string):string;
 /** Validated transaction controls shared by atomic CLI and MCP adapters. */
 export interface AtomicMutationControls {
 /** Compensation policy applied to created items when a later step fails. */
-createCompensation?: "close" | "delete";
+createCompensation?:"close" | "delete";
 /** Workspace transaction lock lifetime in seconds. */
-lockTtlSeconds?: number;
+lockTtlSeconds?:number;
 /** Maximum time to wait for the workspace transaction lock. */
-lockWaitMs?: number;
+lockWaitMs?:number;
 }
 /** Validate and normalize atomic transaction controls at every transport boundary. */
-export declare function parseAtomicMutationControls(value: Record<string, unknown>): AtomicMutationControls;
+export declare function parseAtomicMutationControls(value:Record<string,unknown>):AtomicMutationControls;
+/** Workspace schema context that widens the option keys a batch row may carry. */
+export interface ParseItemMutationBatchOptions {
+/** Declared schema fields whose option targets create/update rows may set. */
+runtimeFields?:readonly RuntimeFieldDefinitionResolved[];
+}
 /** Parse a JSON array, or an object containing `mutations`, into an atomic mutation batch. */
-export declare function parseItemMutationBatch(input: string): BulkItemMutation[];
+export declare function parseItemMutationBatch(input:string,parseOptions?:ParseItemMutationBatchOptions):BulkItemMutation[];
+/** Canonical comparison form of an upsert key value: trimmed strings, otherwise key-sorted JSON. Shared by the planner and the lock-held commit guard. */
+export declare function stableUpsertValue(value:unknown):string;
 /**
  * Resolve a versioned heterogeneous mutation document. Create rows may declare
  * a unique `ref`; omitted ids are derived deterministically from the stable
  * transaction id, and `@ref` forward references are supported in target ids,
  * parent/blocked-by options, and dependency entries.
  */
-export declare function resolveItemMutationDocument(input: string, options: ResolveItemMutationDocumentOptions): ResolvedItemMutationDocument;
+export declare function resolveItemMutationDocument(input:string,options:ResolveItemMutationDocumentOptions):ResolvedItemMutationDocument;
 /**
  * Convert a direct item JSON document or `pm get --json` envelope into the
  * create/update option shape. Explicit CLI flags override document values.
@@ -43,6 +94,6 @@ export declare function resolveItemMutationDocument(input: string, options: Reso
  * 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>, runtimeFields?: readonly RuntimeFieldDefinitionResolved[]): 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[];
+export declare function validateItemMutationRows(value:unknown):BulkItemMutation[];