@unbrained/pm-cli 2026.10.14 → 2026.10.17

package/dist/core/shared/serial-queue.d.ts

@@ -6,18 +6,18 @@
 /** Defines the FIFO queue contract used to serialize asynchronous mutation-sensitive work. */
 export interface SerialQueue {
 /** Schedule `task` to run after every previously-enqueued task has settled. Returns a promise for this task's result (or rejection) so callers can await individual outcomes. A rejected task never wedges the queue: later tasks still run in order. */
-enqueue<T>(task: () => Promise<T> | T): Promise<T>;
+enqueue<T>(task:() => Promise<T> | T):Promise<T>;
 /** Resolves once the queue has fully drained (no pending tasks remain). */
-idle(): Promise<void>;
+idle():Promise<void>;
 }
 /** Coordinates concurrent readers with FIFO-exclusive writers without serializing independent read work. */
 export interface AsyncReadWriteGate {
 /** Run work concurrently after every writer scheduled before this call has settled. */
-read<T>(task: () => Promise<T> | T): Promise<T>;
+read<T>(task:() => Promise<T> | T):Promise<T>;
 /** Run work exclusively after all readers and writers scheduled before this call have settled. */
-write<T>(task: () => Promise<T> | T): Promise<T>;
+write<T>(task:() => Promise<T> | T):Promise<T>;
 }
 /** Create an arrival-ordered asynchronous read/write gate. Readers may overlap, while writers exclude both modes and never starve behind later readers. */
-export declare function createAsyncReadWriteGate(): AsyncReadWriteGate;
+export declare function createAsyncReadWriteGate():AsyncReadWriteGate;
 /** Implements create serial queue for the public runtime surface of this module. */
-export declare function createSerialQueue(): SerialQueue;
+export declare function createSerialQueue():SerialQueue;

package/dist/core/shared/serialization.d.ts

@@ -1,8 +1,8 @@
 /** Implements stable stringify for the public runtime surface of this module. */
-export declare function stableStringify(value: unknown): string;
+export declare function stableStringify(value:unknown):string;
 /** Implements stable value equals for the public runtime surface of this module. */
-export declare function stableValueEquals(left: unknown, right: unknown): boolean;
+export declare function stableValueEquals(left:unknown,right:unknown):boolean;
 /** Implements sha256 hex for the public runtime surface of this module. */
-export declare function sha256Hex(value: string): string;
+export declare function sha256Hex(value:string):string;
 /** Implements order object for the public runtime surface of this module. */
-export declare function orderObject<T extends Record<string, unknown>>(value: T, keyOrder: ReadonlyArray<string>): Record<string, unknown>;
+export declare function orderObject<T extends Record<string,unknown>>(value:T,keyOrder:ReadonlyArray<string>):Record<string,unknown>;

package/dist/core/shared/split-comma-list.d.ts

@@ -6,11 +6,11 @@
 /** Configures comma-list parsing for command flags that support escaped separators. */
 export interface SplitCommaListOptions {
 /** Separator pattern. Defaults to `/,/`. */
-separators?: RegExp | string;
+separators?:RegExp | string;
 /** De-duplicate entries while preserving first-seen order. Defaults to `true`. */
-unique?: boolean;
+unique?:boolean;
 /** Sort entries lexicographically (default JS string sort). Defaults to `false`. */
-sort?: boolean;
+sort?:boolean;
 }
 /**
  * Split a comma-separated (or custom-separator) string into trimmed, non-empty entries.
@@ -23,4 +23,4 @@ sort?: boolean;
  *
  * Returns `[]` for `undefined`/`null` input. Pure, dependency-free.
  */
-export declare function splitCommaList(raw: string | undefined | null, options?: SplitCommaListOptions): string[];
+export declare function splitCommaList(raw:string | undefined | null,options?:SplitCommaListOptions):string[];

package/dist/core/shared/text-normalization.d.ts

@@ -4,8 +4,10 @@
  * Provides shared primitives and utilities for Text Normalization.
  */
 /** Normalizes text to lowercase whitespace-collapsed form for stable matching and comparison. */
-export declare function normalizeLowercaseWhitespace(value: string): string;
+export declare function normalizeLowercaseWhitespace(value:string):string;
+/** Return a UTF-16 prefix without splitting a valid surrogate pair at its boundary. */
+export declare function unicodeSafePrefix(value:string,end:number):string;
 /** Implements tokenize alpha numeric for the public runtime surface of this module. */
-export declare function tokenizeAlphaNumeric(value: string): string[];
+export declare function tokenizeAlphaNumeric(value:string):string[];
 /** Implements jaccard similarity for the public runtime surface of this module. */
-export declare function jaccardSimilarity(leftTokens: readonly string[], rightTokens: readonly string[]): number;
+export declare function jaccardSimilarity(leftTokens:readonly string[],rightTokens:readonly string[]):number;

package/dist/core/shared/text-normalization.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]="6c555c2c-9db2-5c9f-9d69-3456fe8bffaa")}catch{}})();function normalizeLowercaseWhitespace(value){return value.trim().toLowerCase().replace(/\s+/g," ")}function tokenizeAlphaNumeric(value){return normalizeLowercaseWhitespace(value).split(/[^a-z0-9]+/).filter(token=>token.length>0)}function jaccardSimilarity(leftTokens,rightTokens){if(leftTokens.length===0&&rightTokens.length===0)return 1;if(leftTokens.length===0||rightTokens.length===0)return 0;const leftSet=new Set(leftTokens),rightSet=new Set(rightTokens);let intersection=0;for(const token of leftSet)rightSet.has(token)&&(intersection+=1);const union=new Set([...leftSet,...rightSet]).size;return intersection/union}export{jaccardSimilarity,normalizeLowercaseWhitespace,tokenizeAlphaNumeric};
+(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]="4a7b042c-7fb8-57a5-8f94-de44f82d7589")}catch{}})();function normalizeLowercaseWhitespace(value){return value.trim().toLowerCase().replace(/\s+/g," ")}function unicodeSafePrefix(value,end){const prefix=value.slice(0,end),last=prefix.charCodeAt(prefix.length-1),next=value.charCodeAt(prefix.length);return last>=55296&&last<=56319&&next>=56320&&next<=57343?prefix.slice(0,-1):prefix}function tokenizeAlphaNumeric(value){return normalizeLowercaseWhitespace(value).split(/[^a-z0-9]+/).filter(token=>token.length>0)}function jaccardSimilarity(leftTokens,rightTokens){if(leftTokens.length===0&&rightTokens.length===0)return 1;if(leftTokens.length===0||rightTokens.length===0)return 0;const leftSet=new Set(leftTokens),rightSet=new Set(rightTokens);let intersection=0;for(const token of leftSet)rightSet.has(token)&&(intersection+=1);const union=new Set([...leftSet,...rightSet]).size;return intersection/union}export{jaccardSimilarity,normalizeLowercaseWhitespace,tokenizeAlphaNumeric,unicodeSafePrefix};
 //# sourceMappingURL=text-normalization.js.map

package/dist/core/shared/time.d.ts

@@ -1,52 +1,52 @@
 /** Implements now iso for the public runtime surface of this module. */
-export declare function nowIso(): string;
+export declare function nowIso():string;
 /** Implements check whether timestamp literal for the public runtime surface of this module. */
-export declare function isTimestampLiteral(input: string): boolean;
+export declare function isTimestampLiteral(input:string):boolean;
 /** Return whether a string is a calendar-valid RFC 3339 date-time. */
-export declare function isRfc3339DateTime(input: string): boolean;
+export declare function isRfc3339DateTime(input:string):boolean;
 /** Return whether a value is a calendar-valid RFC 3339 date-time whose fractional seconds carry no sub-millisecond information. */
-export declare function isMillisecondPrecisionRfc3339DateTime(input: string): boolean;
+export declare function isMillisecondPrecisionRfc3339DateTime(input:string):boolean;
 /** Implements compare timestamp strings for the public runtime surface of this module. */
-export declare function compareTimestampStrings(left: string, right: string): number;
+export declare function compareTimestampStrings(left:string,right:string):number;
 /** Timestamp-bearing record accepted by shared inclusive bound filtering. */
 export interface TimestampedRecord {
 /** Optional deadline timestamp. */
-deadline?: string;
+deadline?:string;
 /** Last-update timestamp. */
-updated_at: string;
+updated_at:string;
 /** Creation timestamp. */
-created_at: string;
+created_at:string;
 }
 /** Inclusive timestamp bounds shared by list and search filtering. */
 export interface TimestampFilterBounds {
 /** Inclusive upper deadline bound. */
-deadlineBefore?: string;
+deadlineBefore?:string;
 /** Inclusive lower deadline bound. */
-deadlineAfter?: string;
+deadlineAfter?:string;
 /** Inclusive lower update-time bound. */
-updatedAfter?: string;
+updatedAfter?:string;
 /** Inclusive upper update-time bound. */
-updatedBefore?: string;
+updatedBefore?:string;
 /** Inclusive lower creation-time bound. */
-createdAfter?: string;
+createdAfter?:string;
 /** Inclusive upper creation-time bound. */
-createdBefore?: string;
+createdBefore?:string;
 }
 /** Return whether a timestamp-bearing record satisfies every configured bound. */
-export declare function matchesTimestampFilters(item: TimestampedRecord, filters: TimestampFilterBounds): boolean;
-declare function normalizeOffset(raw: string | undefined): string;
-declare function pushTimestampCandidate(candidates: string[], input: string, value: string | undefined): void;
-declare function normalizeTimestampCandidates(input: string): string[];
-declare function parseTimestampWithFallbacks(input: string): number;
-declare function isWhitespaceCharacter(character: string | undefined): boolean;
+export declare function matchesTimestampFilters(item:TimestampedRecord,filters:TimestampFilterBounds):boolean;
+declare function normalizeOffset(raw:string | undefined):string;
+declare function pushTimestampCandidate(candidates:string[],input:string,value:string | undefined):void;
+declare function normalizeTimestampCandidates(input:string):string[];
+declare function parseTimestampWithFallbacks(input:string):number;
+declare function isWhitespaceCharacter(character:string | undefined):boolean;
 /** Implements resolve iso or relative for the public runtime surface of this module. */
-export declare function resolveIsoOrRelative(input: string, now?: Date, fieldLabel?: string): string;
+export declare function resolveIsoOrRelative(input:string,now?:Date,fieldLabel?:string):string;
 /** Public contract for test only, shared by SDK and presentation-layer consumers. */
-export declare const _testOnly: {
-normalizeOffset: typeof normalizeOffset;
-pushTimestampCandidate: typeof pushTimestampCandidate;
-normalizeTimestampCandidates: typeof normalizeTimestampCandidates;
-parseTimestampWithFallbacks: typeof parseTimestampWithFallbacks;
-isWhitespaceCharacter: typeof isWhitespaceCharacter;
+export declare const _testOnly:{
+normalizeOffset:typeof normalizeOffset;
+pushTimestampCandidate:typeof pushTimestampCandidate;
+normalizeTimestampCandidates:typeof normalizeTimestampCandidates;
+parseTimestampWithFallbacks:typeof parseTimestampWithFallbacks;
+isWhitespaceCharacter:typeof isWhitespaceCharacter;
 };
 export {};

package/dist/core/store/item-format-migration.d.ts

@@ -1,16 +1,16 @@
-import type { ItemFormat, RuntimeSchemaSettings } from "../../types/index.js";
+import type { ItemFormat,RuntimeSchemaSettings } from "../../types/index.js";
 /** Documents the item format migration result payload exchanged by command, SDK, and package integrations. */
 export interface ItemFormatMigrationResult {
 /** Value that configures or reports target format for this contract. */
-target_format: ItemFormat;
+target_format:ItemFormat;
 /** Value that configures or reports scanned for this contract. */
-scanned: number;
+scanned:number;
 /** Value that configures or reports migrated for this contract. */
-migrated: string[];
+migrated:string[];
 /** Value that configures or reports removed for this contract. */
-removed: string[];
+removed:string[];
 /** Value that configures or reports warnings for this contract. */
-warnings: string[];
+warnings:string[];
 }
 /** Implements migrate item files to format for the public runtime surface of this module. */
-export declare function migrateItemFilesToFormat(pmRoot: string, targetFormat: ItemFormat, op?: string, typeToFolder?: Record<string, string>, schema?: RuntimeSchemaSettings): Promise<ItemFormatMigrationResult>;
+export declare function migrateItemFilesToFormat(pmRoot:string,targetFormat:ItemFormat,op?:string,typeToFolder?:Record<string,string>,schema?:RuntimeSchemaSettings):Promise<ItemFormatMigrationResult>;

package/dist/core/store/item-metadata-cache.d.ts

@@ -1,29 +1,29 @@
-import type { ItemDocument, ItemFormat, ItemMetadata, RuntimeSchemaSettings } from "../../types/index.js";
+import type { ItemDocument,ItemFormat,ItemMetadata,RuntimeSchemaSettings } from "../../types/index.js";
 /** Minimum item count at which derived-index mutations use cross-process locking. */
 export declare const DEFAULT_DERIVED_INDEX_MINIMUM_ITEMS = 500;
 /** Heavy "collection" item-metadata fields. These arrays dominate the on-disk cache (e.g. a single item's comment thread can be hundreds of KB) yet the hot list path (`pm list`, stats, deps, activity, calendar, close) never reads them. They are stored in a separate collections cache that is parsed only when a caller opts in (`includeCollections`), keeping the always-loaded light cache an order of magnitude smaller and its JSON.parse correspondingly cheaper. */
-export declare const HEAVY_METADATA_KEYS: readonly ["comments", "notes", "learnings", "files", "tests", "test_runs", "docs"];
+export declare const HEAVY_METADATA_KEYS:readonly ["comments","notes","learnings","files","tests","test_runs","docs"];
 /** Controls whether derived-index writers may skip the cross-process lock below the scale threshold. */
 export interface ItemMetadataDerivedIndexLockOptions {
 /** Require serialization even when the derived index is absent or contains fewer than the normal locking threshold. */
-required?: boolean;
+required?:boolean;
 }
 /** Documents the cached document candidate payload exchanged by command, SDK, and package integrations. */
 export interface CachedDocumentCandidate {
 /** Value that configures or reports metadata for this contract. */
-metadata: ItemMetadata;
+metadata:ItemMetadata;
 /** Value that configures or reports body for this contract. */
-body?: string;
+body?:string;
 /** Value that configures or reports item format for this contract. */
-item_format: ItemFormat;
+item_format:ItemFormat;
 /** Filesystem path used for item resolution. */
-item_path: string;
+item_path:string;
 }
 /**
  * Drop memoized envelopes. Exposed for tests; production invalidation is stat-driven
  * plus the explicit delete in {@link persistCache} after a rewrite.
  */
-export declare function clearItemMetadataEnvelopeMemo(): void;
+export declare function clearItemMetadataEnvelopeMemo():void;
 /**
  * Decide whether a freshly parsed document candidate should replace the one
  * already recorded for the same item id when both an explicit-format file and a
@@ -36,37 +36,37 @@ export declare function clearItemMetadataEnvelopeMemo(): void;
  * branch taken (and thus its coverage) would race. Keep this exported and
  * unit-tested across every format combination.
  */
-export declare function shouldReplaceCachedDocumentCandidate(existingFormat: ItemFormat, candidateFormat: ItemFormat, preferredFormat: ItemFormat | undefined): boolean;
+export declare function shouldReplaceCachedDocumentCandidate(existingFormat:ItemFormat,candidateFormat:ItemFormat,preferredFormat:ItemFormat | undefined):boolean;
 /** Decide whether a scanned candidate should be recorded for its item id. An unseen id is always recorded; duplicate ids delegate to the deterministic cross-format preference rule. Keeping the short-circuit in this pure helper makes both outcomes testable without relying on filesystem enumeration or concurrent read completion order. */
-export declare function shouldRecordCachedDocumentCandidate(existingFormat: ItemFormat | undefined, candidateFormat: ItemFormat, preferredFormat: ItemFormat | undefined): boolean;
+export declare function shouldRecordCachedDocumentCandidate(existingFormat:ItemFormat | undefined,candidateFormat:ItemFormat,preferredFormat:ItemFormat | undefined):boolean;
 /** Acquire the cross-process derived-index writer lock when an index exists. */
-export declare function acquireItemMetadataDerivedIndexLock(pmRoot: string, author: string, options?: ItemMetadataDerivedIndexLockOptions): Promise<() => Promise<void>>;
+export declare function acquireItemMetadataDerivedIndexLock(pmRoot:string,author:string,options?:ItemMetadataDerivedIndexLockOptions):Promise<() => Promise<void>>;
 /** One authoritative item commit projected into the rebuildable index. */
 export interface ItemMetadataDerivedIndexMutation {
 /** Tracker root containing the derived cache. */
-pmRoot: string;
+pmRoot:string;
 /** Preferred item format folded into the cache schema fingerprint. */
-preferredFormat: ItemFormat | undefined;
+preferredFormat:ItemFormat | undefined;
 /** Runtime item-type folder mapping. */
-typeToFolder: Record<string, string>;
+typeToFolder:Record<string,string>;
 /** Runtime schema folded into the cache schema fingerprint. */
-schema: RuntimeSchemaSettings | undefined;
+schema:RuntimeSchemaSettings | undefined;
 /** Committed item path, or deleted item path when document is null. */
-itemPath: string;
+itemPath:string;
 /** Previous path removed by a format or type migration. */
-previousItemPath?: string;
+previousItemPath?:string;
 /** Committed document, or null for deletion. */
-document: ItemDocument | null;
+document:ItemDocument | null;
 }
 /** Read-only identity of the effective rebuildable metadata projection. */
 export interface ItemMetadataDerivedIndexState {
 /** Cursor shared by the base manifest and its collapsed mutation delta. */
-source_cursor: string;
+source_cursor:string;
 /** Number of authoritative rows recorded when the base manifest was built. */
-entry_count: number;
+entry_count:number;
 }
 /** Read the effective derived-index cursor without exposing cache file layout. */
-export declare function readItemMetadataDerivedIndexState(pmRoot: string, folders?: readonly string[]): Promise<ItemMetadataDerivedIndexState | null>;
+export declare function readItemMetadataDerivedIndexState(pmRoot:string,folders?:readonly string[]):Promise<ItemMetadataDerivedIndexState | null>;
 /**
  * Project one already-committed authoritative item write into every compatible
  * derived-index tier. Callers hold {@link acquireItemMetadataDerivedIndexLock}
@@ -76,19 +76,19 @@ export declare function readItemMetadataDerivedIndexState(pmRoot: string, folder
  * mutation cost is bounded by changed items instead of total workspace size.
  * Any refresh failure deletes the rebuildable cache so the next read scans.
  */
-export declare function refreshItemMetadataDerivedIndex(mutation: ItemMetadataDerivedIndexMutation): Promise<string[]>;
+export declare function refreshItemMetadataDerivedIndex(mutation:ItemMetadataDerivedIndexMutation):Promise<string[]>;
 /** Documents the list cache options payload exchanged by command, SDK, and package integrations. */
 export interface ListCacheOptions {
 /** When false, item bodies are neither loaded from nor written to the separate body cache. Metadata-only callers (`pm list`, stats, deps, activity, …) skip the large body cache entirely; only body consumers (search/reindex) pay for it. */
-includeBody?: boolean;
+includeBody?:boolean;
 /** When false, heavy collection fields (comments/notes/learnings/files/tests/ test_runs/docs) are neither loaded from nor written to the separate collections cache, and are absent from the returned metadata. Light-only callers (`pm list` compact, stats, deps, activity, calendar, close) skip the large collections cache entirely. Defaults to true so any caller that does read those fields stays correct. */
-includeCollections?: boolean;
+includeCollections?:boolean;
 /** Force canonical item enumeration and authoritative file reads even when stat-matched cache tiers or a fresh derived index are available. Validation, repair, migration, and equivalence tests use this correctness path. */
-forceSourceScan?: boolean;
+forceSourceScan?:boolean;
 /** Minimum item count required before the directory-signature derived-index fast path is used. Defaults to 500 so small workspaces preserve per-file external-edit detection; tests and specialized SDK hosts may lower it explicitly. */
-derivedIndexMinimumItems?: number;
+derivedIndexMinimumItems?:number;
 /** Optional cache-rebuild diagnostics kept separate from item-read warnings. */
-cacheDiagnostics?: string[];
+cacheDiagnostics?:string[];
 }
 /**
  * List all item documents using a persistent on-disk metadata cache.
@@ -100,13 +100,13 @@ cacheDiagnostics?: string[];
  * registers one. Only files whose mtime/ctime/size changed since the last run are
  * re-parsed.
  */
-export declare function listAllDocumentCandidatesCached(pmRoot: string, preferredFormat: ItemFormat | undefined, typeToFolder: Record<string, string>, warnings: string[] | undefined, schema: RuntimeSchemaSettings | undefined, options?: ListCacheOptions): Promise<CachedDocumentCandidate[]>;
+export declare function listAllDocumentCandidatesCached(pmRoot:string,preferredFormat:ItemFormat | undefined,typeToFolder:Record<string,string>,warnings:string[] | undefined,schema:RuntimeSchemaSettings | undefined,options?:ListCacheOptions):Promise<CachedDocumentCandidate[]>;
 /** Implements list all documents cached for the public runtime surface of this module. */
-export declare function listAllDocumentsCached(pmRoot: string, preferredFormat: ItemFormat | undefined, typeToFolder: Record<string, string>, warnings: string[] | undefined, schema: RuntimeSchemaSettings | undefined): Promise<ItemDocument[]>;
+export declare function listAllDocumentsCached(pmRoot:string,preferredFormat:ItemFormat | undefined,typeToFolder:Record<string,string>,warnings:string[] | undefined,schema:RuntimeSchemaSettings | undefined):Promise<ItemDocument[]>;
 /**
  * Light variant of {@link listAllDocumentsCached}: returns metadata WITHOUT the heavy
  * collection fields (comments/notes/learnings/files/tests/test_runs/docs), skipping the
  * large collections cache entirely. Only safe for callers that read just the light
  * scalar/small fields (id/title/status/type/priority/parent/tags/dates/dependencies/…).
  */
-export declare function listAllDocumentsCachedLight(pmRoot: string, preferredFormat: ItemFormat | undefined, typeToFolder: Record<string, string>, warnings: string[] | undefined, schema: RuntimeSchemaSettings | undefined): Promise<ItemDocument[]>;
+export declare function listAllDocumentsCachedLight(pmRoot:string,preferredFormat:ItemFormat | undefined,typeToFolder:Record<string,string>,warnings:string[] | undefined,schema:RuntimeSchemaSettings | undefined):Promise<ItemDocument[]>;

package/dist/core/store/item-metadata-query-index.d.ts

@@ -1,137 +1,137 @@
 import type { DatabaseSync } from "node:sqlite";
-import type { ItemMetadata, LinkedFile, LinkScope } from "../../types/index.js";
-import { loadDatabaseSync, loadStableDatabaseSync } from "./sqlite-runtime.js";
+import type { ItemMetadata,LinkedFile,LinkScope } from "../../types/index.js";
+import { loadDatabaseSync,loadStableDatabaseSync } from "./sqlite-runtime.js";
 type DatabaseSyncConstructor = typeof DatabaseSync;
 /** One light-metadata row projected into the persistent query index. */
 export interface ItemMetadataQueryIndexRow {
 /** Tracker-relative authoritative item path. */
-relativePath: string;
+relativePath:string;
 /** Light item metadata serialized into the row store. */
-metadata: ItemMetadata;
+metadata:ItemMetadata;
 /** Heavy linked-file records projected separately for reverse traceability. */
-linkedFiles?: readonly LinkedFile[];
+linkedFiles?:readonly LinkedFile[];
 }
 /** Selection supported directly by the persistent metadata query index. */
 export interface ItemMetadataIndexQuery {
 /** Include only these lifecycle statuses. */
-statuses?: readonly string[];
+statuses?:readonly string[];
 /** Exclude these lifecycle statuses. */
-excludeStatuses?: readonly string[];
+excludeStatuses?:readonly string[];
 /** Statuses sorted after active rows by the default list ordering contract. */
-terminalStatuses?: readonly string[];
+terminalStatuses?:readonly string[];
 /** Include only these item types. */
-types?: readonly string[];
+types?:readonly string[];
 /** Include only these exact item identifiers. */
-ids?: readonly string[];
+ids?:readonly string[];
 /** Include only rows that define every requested metadata key. */
-metadataKeys?: readonly string[];
+metadataKeys?:readonly string[];
 /** Include only direct children of this item. */
-parent?: string;
+parent?:string;
 /** Include only this assignee value. */
-assignee?: string;
+assignee?:string;
 /** Include only this sprint value. */
-sprint?: string;
+sprint?:string;
 /** Include only this release value. */
-release?: string;
+release?:string;
 /** Include only this numeric priority. */
-priority?: number;
+priority?:number;
 /** Maximum rows returned after deterministic default ordering. */
-limit?: number;
+limit?:number;
 /** Number of ordered rows skipped before returning results. */
-offset?: number;
+offset?:number;
 }
 /** Bounded query result carrying total match count and index provenance. */
 export interface ItemMetadataIndexQueryResult {
 /** Effective index source cursor. */
-source_cursor: string;
+source_cursor:string;
 /** Total matching rows before offset and limit. */
-total: number;
+total:number;
 /** Ordered light metadata rows in the requested window. */
-items: ItemMetadata[];
+items:ItemMetadata[];
 }
 /** Bounded lexical candidate result from the persistent metadata projection. */
 export interface SimilarItemMetadataIndexResult {
 /** Effective index source cursor. */
-source_cursor: string;
+source_cursor:string;
 /** FTS-ranked light metadata candidates. */
-items: ItemMetadata[];
+items:ItemMetadata[];
 }
 /** One indexed item and the requested linked-file records that reference it. */
 export interface IndexedLinkedFileMatch {
 /** Light metadata for the referencing item. */
-item: ItemMetadata;
+item:ItemMetadata;
 /** Exact linked-file records matching the requested paths and optional scope. */
-files: LinkedFile[];
+files:LinkedFile[];
 }
 /** Bounded reverse linked-file query result from the persistent projection. */
 export interface LinkedFileMetadataIndexResult {
 /** Effective index source cursor. */
-source_cursor: string;
+source_cursor:string;
 /** Total matching items before offset and limit. */
-total: number;
+total:number;
 /** Deterministically ordered referencing items in the requested window. */
-matches: IndexedLinkedFileMatch[];
+matches:IndexedLinkedFileMatch[];
 }
 /** Atomically rebuild the complete query projection from authoritative cache rows. */
-export declare function rebuildItemMetadataQueryIndex(options: {
-pmRoot: string;
-contextFingerprint: string;
-sourceCursor: string;
-rows: readonly ItemMetadataQueryIndexRow[];
-}): Promise<void>;
+export declare function rebuildItemMetadataQueryIndex(options:{
+pmRoot:string;
+contextFingerprint:string;
+sourceCursor:string;
+rows:readonly ItemMetadataQueryIndexRow[];
+}):Promise<void>;
 /**
  * Apply one authoritative metadata mutation in the same writer critical
  * section as the JSON derived-index delta. A cursor mismatch fails closed so
  * callers can remove and lazily rebuild this optional projection.
  */
-export declare function updateItemMetadataQueryIndex(options: {
-pmRoot: string;
-contextFingerprint: string;
-expectedSourceCursor: string;
-sourceCursor: string;
-row: ItemMetadataQueryIndexRow | null;
-deletedRelativePaths?: readonly string[];
-}): Promise<boolean>;
+export declare function updateItemMetadataQueryIndex(options:{
+pmRoot:string;
+contextFingerprint:string;
+expectedSourceCursor:string;
+sourceCursor:string;
+row:ItemMetadataQueryIndexRow | null;
+deletedRelativePaths?:readonly string[];
+}):Promise<boolean>;
 /**
  * Query the persistent projection without materializing the full metadata
  * cache. Returns null when the database is absent, stale, corrupt, or active
  * extension read hooks require canonical per-document dispatch.
  */
-export declare function queryItemMetadataIndex(options: {
-pmRoot: string;
-expectedSourceCursor: string;
-query?: ItemMetadataIndexQuery;
-}): Promise<ItemMetadataIndexQueryResult | null>;
+export declare function queryItemMetadataIndex(options:{
+pmRoot:string;
+expectedSourceCursor:string;
+query?:ItemMetadataIndexQuery;
+}):Promise<ItemMetadataIndexQueryResult | null>;
 /**
  * Resolve items that link any requested project-relative path without loading
  * heavy item collections. Returns null when the optional projection is absent,
  * stale, or corrupt so callers can fall back to authoritative item reads.
  */
-export declare function queryLinkedFileMetadataIndex(options: {
-pmRoot: string;
-expectedSourceCursor: string;
-paths: readonly string[];
-scope?: LinkScope;
-limit?: number;
-offset?: number;
-}): Promise<LinkedFileMetadataIndexResult | null>;
+export declare function queryLinkedFileMetadataIndex(options:{
+pmRoot:string;
+expectedSourceCursor:string;
+paths:readonly string[];
+scope?:LinkScope;
+limit?:number;
+offset?:number;
+}):Promise<LinkedFileMetadataIndexResult | null>;
 /**
  * Query FTS-ranked item candidates without materializing the workspace. The
  * caller owns final similarity scoring and threshold semantics.
  */
-export declare function querySimilarItemMetadataIndex(options: {
-pmRoot: string;
-expectedSourceCursor: string;
-query: string;
-limit: number;
-}): Promise<SimilarItemMetadataIndexResult | null>;
+export declare function querySimilarItemMetadataIndex(options:{
+pmRoot:string;
+expectedSourceCursor:string;
+query:string;
+limit:number;
+}):Promise<SimilarItemMetadataIndexResult | null>;
 /** Remove only the optional SQLite query projection. */
-export declare function removeItemMetadataQueryIndex(pmRoot: string): Promise<void>;
+export declare function removeItemMetadataQueryIndex(pmRoot:string):Promise<void>;
 /** Test-only dependency seam for runtimes that do not implement node:sqlite. */
-export declare const _testOnly: {
-loadDatabaseSync: typeof loadDatabaseSync;
-loadStableDatabaseSync: typeof loadStableDatabaseSync;
+export declare const _testOnly:{
+loadDatabaseSync:typeof loadDatabaseSync;
+loadStableDatabaseSync:typeof loadStableDatabaseSync;
 /** Replace the optional constructor and return a restoration callback. */
-setDatabaseSync(databaseSync: DatabaseSyncConstructor | null): () => void;
+setDatabaseSync(databaseSync:DatabaseSyncConstructor | null):() => void;
 };
 export {};

package/dist/core/store/item-metadata-read-work.d.ts

@@ -1,19 +1,19 @@
 /** Logical metadata work, independent of output projection and cache hit rate. */
 export interface ItemMetadataReadWork {
 /** Completed full, light, or body-bearing item-store enumeration calls. */
-enumeration_calls: number;
+enumeration_calls:number;
 /** Metadata rows returned by those calls, counting repeated enumeration. */
-metadata_rows: number;
+metadata_rows:number;
 }
 /** Record completed enumeration in each enclosing measurement, without retaining item data. */
-export declare function recordItemMetadataEnumeration(rowCount: number): void;
+export declare function recordItemMetadataEnumeration(rowCount:number):void;
 /**
  * Measure an awaited operation without changing its result or failure semantics.
  * Concurrent roots remain isolated; nested measurements also contribute to their
  * parents. The returned snapshot excludes work completed after the operation.
  * Counters cover filesystem item-store enumeration APIs, not arbitrary host I/O.
  */
-export declare function measureItemMetadataReadWork<T>(operation: () => T | Promise<T>): Promise<{
-result: T;
-work: Readonly<ItemMetadataReadWork>;
+export declare function measureItemMetadataReadWork<T>(operation:() => T | Promise<T>):Promise<{
+result:T;
+work:Readonly<ItemMetadataReadWork>;
 }>;

package/dist/core/store/item-mutation-precondition.d.ts

@@ -0,0 +1,11 @@
+import type { ItemDocument } from "../../types/index.js";
+interface ItemMutationPrecondition {
+pmRoot:string;
+id:string;
+validate:(document:ItemDocument) => void;
+}
+/** Scope a target-specific precondition to an awaited mutation without affecting concurrent callers. */
+export declare function runWithItemMutationPrecondition<T>(condition:ItemMutationPrecondition,operation:() => Promise<T>):Promise<T>;
+/** Evaluate matching preconditions only after the item lock has been acquired and its document read. */
+export declare function assertItemMutationPreconditions(pmRoot:string,document:ItemDocument):void;
+export {};

package/dist/core/store/item-mutation-precondition.js

@@ -0,0 +1,2 @@
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="53df109f-bd64-5879-96a6-39f70334910e")}catch{}})();import{AsyncLocalStorage}from"node:async_hooks";import path from"node:path";const preconditions=new AsyncLocalStorage;function runWithItemMutationPrecondition(condition,operation){return preconditions.run([...preconditions.getStore()??[],{...condition,pmRoot:path.resolve(condition.pmRoot)}],operation)}function assertItemMutationPreconditions(pmRoot,document){for(const condition of preconditions.getStore()??[])condition.pmRoot===path.resolve(pmRoot)&&condition.id===document.metadata.id&&condition.validate(document)}export{assertItemMutationPreconditions,runWithItemMutationPrecondition};
+//# sourceMappingURL=item-mutation-precondition.js.map