@unbrained/pm-cli 2026.9.5 → 2026.9.6

package/dist/sdk/context/usage-ledger.d.ts

@@ -0,0 +1,41 @@
+import type { ContextUsageEvent, ContextUsageLedgerOptions } from "../context-usage.js";
+/** Public storage and sampling ceilings shared by every feedback producer. */
+export declare const CONTEXT_USAGE_LIMITS: {
+    readonly max_serving_rows: 256;
+    readonly max_bytes: 262144;
+    readonly max_event_bytes: 32768;
+    readonly retained_byte_fraction: 0.5;
+    readonly max_events: 2048;
+    readonly retention_days: 30;
+};
+/** Measured persistence work for one lock-protected feedback write. */
+export interface ContextUsageWriteReceipt {
+    /** Bytes written to the append or replacement file; excludes lock metadata. */
+    written_bytes: number;
+    /** Physical ledger size at the end of the protected write. */
+    ledger_bytes: number;
+    /** Whether this write replaced the ledger with a retained suffix. */
+    compacted: boolean;
+    /** Wall-clock time waiting to acquire the cross-process ledger lock. */
+    lock_wait_ms: number;
+}
+/** Named validation failure emitted by context-usage SDK inputs. */
+export declare class ContextUsageValidationError extends TypeError {
+    /** Stable code for package and CLI hosts. */
+    readonly code = "context_usage_validation_failed";
+    /** Reject invalid feedback controls without exposing ledger contents. */
+    constructor(message: string);
+}
+/** Normalize one timestamp so filtering and serialization share the same clock. */
+export declare function resolveNow(options: ContextUsageLedgerOptions): {
+    iso: string;
+    ms: number;
+};
+/** Read only a bounded file suffix, dropping a partial first JSONL row. */
+export declare function readEvents(options: ContextUsageLedgerOptions): Promise<ContextUsageEvent[]>;
+/**
+ * Append once, or compact atomically to a half-full suffix at the high-water mark.
+ * Requires trusted, stable workspace directory entries and ancestors; the lock
+ * coordinates cooperating writers and cannot constrain hostile path replacement.
+ */
+export declare function appendEvents(options: ContextUsageLedgerOptions, events: readonly ContextUsageEvent[], deliveryServeId?: string): Promise<ContextUsageWriteReceipt>;

package/dist/sdk/context/usage-ledger.js

@@ -0,0 +1,186 @@
+/**
+ * @module sdk/context/usage-ledger
+ *
+ * Bounds derived feedback reads and writes in bytes. High-water compaction
+ * retains a half-full suffix under the same lock as append, leaving headroom
+ * for subsequent serves without rewriting on every context request.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="f3af7f8f-a462-5eb4-af08-c64c3c327e62")}catch(e){}}();
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, rename, rm } from "node:fs/promises";
+import path from "node:path";
+import { isFileMissingError } from "../../core/fs/fs-utils.js";
+import { acquireLock } from "../../core/lock/lock.js";
+/** Public storage and sampling ceilings shared by every feedback producer. */
+export const CONTEXT_USAGE_LIMITS = {
+    max_serving_rows: 256,
+    max_bytes: 262_144,
+    max_event_bytes: 32_768,
+    retained_byte_fraction: 0.5,
+    max_events: 2_048,
+    retention_days: 30,
+};
+/** Named validation failure emitted by context-usage SDK inputs. */
+export class ContextUsageValidationError extends TypeError {
+    /** Stable code for package and CLI hosts. */
+    code = "context_usage_validation_failed";
+    /** Reject invalid feedback controls without exposing ledger contents. */
+    constructor(message) {
+        super(message);
+        this.name = "ContextUsageValidationError";
+    }
+}
+/** Normalize one timestamp so filtering and serialization share the same clock. */
+export function resolveNow(options) {
+    const ms = Date.parse(options.now ?? new Date().toISOString());
+    if (!Number.isFinite(ms))
+        throw new ContextUsageValidationError("Context usage now must be a valid timestamp");
+    return { iso: new Date(ms).toISOString(), ms };
+}
+/** Resolve checked byte, count and time bounds before touching storage. */
+function bounds(options) {
+    const maxBytes = options.maxBytes ?? CONTEXT_USAGE_LIMITS.max_bytes;
+    const maxEvents = options.maxEvents ?? CONTEXT_USAGE_LIMITS.max_events;
+    const retentionDays = options.retentionDays ?? CONTEXT_USAGE_LIMITS.retention_days;
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1024 || maxBytes > CONTEXT_USAGE_LIMITS.max_bytes ||
+        !Number.isSafeInteger(maxEvents) || maxEvents < 1 || !Number.isFinite(retentionDays) || retentionDays <= 0) {
+        throw new ContextUsageValidationError("Context usage retention requires positive maxEvents and retentionDays, and maxBytes from 1024 through 262144");
+    }
+    return { maxBytes, maxEvents, cutoff: resolveNow(options).ms - retentionDays * 86_400_000 };
+}
+/** Open only a private regular ledger, refusing redirected runtime directories and file links. */
+async function openLedger(target, flags) {
+    if (!(await lstat(path.dirname(target))).isDirectory()) {
+        throw new ContextUsageValidationError("Context usage runtime must be a real directory");
+    }
+    try {
+        if ((await lstat(target)).isSymbolicLink()) {
+            throw new ContextUsageValidationError("Context usage ledger must not be a symbolic link");
+        }
+    }
+    catch (error) {
+        if (!isFileMissingError(error))
+            throw error;
+    }
+    // Unsupported platform flags contribute zero to the numeric bit mask. The
+    // lstat check also rejects existing links where no-follow is unavailable.
+    const handle = await open(target, flags | constants.O_NOFOLLOW | constants.O_NONBLOCK, 0o600);
+    try {
+        const metadata = await handle.stat();
+        if (!metadata.isFile() || metadata.nlink !== 1) {
+            throw new ContextUsageValidationError("Context usage ledger must be an unshared regular file");
+        }
+        return handle;
+    }
+    catch (error) {
+        await handle.close();
+        throw error;
+    }
+}
+/** Read only a bounded file suffix, dropping a partial first JSONL row. */
+export async function readEvents(options) {
+    const policy = bounds(options);
+    try {
+        const handle = await openLedger(path.join(options.pmRoot, "runtime", "context-usage.jsonl"), constants.O_RDONLY);
+        try {
+            const size = (await handle.stat()).size;
+            const start = Math.max(0, size - policy.maxBytes);
+            const buffer = Buffer.alloc(Math.min(size, policy.maxBytes));
+            const { bytesRead } = await handle.read(buffer, 0, buffer.length, start);
+            const text = buffer.subarray(0, bytesRead).toString("utf8");
+            const lines = (start > 0 ? (text.includes("\n") ? text.slice(text.indexOf("\n") + 1) : "") : text).split("\n");
+            return lines.flatMap((line) => {
+                try {
+                    const event = JSON.parse(line);
+                    return event && Date.parse(event.at) >= policy.cutoff ? [event] : [];
+                }
+                catch {
+                    return [];
+                }
+            }).slice(-policy.maxEvents);
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch {
+        return [];
+    }
+}
+/** Retain a contiguous newest suffix within both byte and event-count bounds. */
+function retainedText(events, byteLimit, maxEvents) {
+    const lines = [];
+    let bytes = 0;
+    for (let index = events.length - 1; index >= 0 && lines.length < maxEvents; index -= 1) {
+        const line = `${JSON.stringify(events[index])}\n`;
+        bytes += Buffer.byteLength(line);
+        if (bytes > byteLimit)
+            break;
+        lines.push(line);
+    }
+    return lines.reverse().join("");
+}
+/**
+ * Append once, or compact atomically to a half-full suffix at the high-water mark.
+ * Requires trusted, stable workspace directory entries and ancestors; the lock
+ * coordinates cooperating writers and cannot constrain hostile path replacement.
+ */
+export async function appendEvents(options, events, deliveryServeId) {
+    const policy = bounds(options);
+    const target = path.join(options.pmRoot, "runtime", "context-usage.jsonl");
+    const retainedBytes = Math.floor(policy.maxBytes * CONTEXT_USAGE_LIMITS.retained_byte_fraction);
+    const eventLimit = Math.min(CONTEXT_USAGE_LIMITS.max_event_bytes, retainedBytes);
+    if (events.some((event) => Buffer.byteLength(`${JSON.stringify(event)}\n`) > eventLimit)) {
+        throw new ContextUsageValidationError("Context usage event exceeds the declared byte ceiling");
+    }
+    const current = events.filter((event) => Date.parse(event.at) >= policy.cutoff);
+    const appended = retainedText(current, retainedBytes, policy.maxEvents);
+    const lockStarted = performance.now();
+    const releaseLock = await acquireLock(options.pmRoot, "context-usage-ledger", 30, `context-usage:${process.pid}`, false, false, 3_000);
+    const lockWaitMs = performance.now() - lockStarted;
+    try {
+        await mkdir(path.dirname(target), { recursive: true });
+        let handle = await openLedger(target, constants.O_WRONLY | constants.O_CREAT | constants.O_APPEND);
+        try {
+            const size = (await handle.stat()).size;
+            const previous = deliveryServeId === undefined ? undefined : await readEvents(options);
+            if (previous?.some((event) => event.kind === "delivery" && event.serve_id === deliveryServeId)) {
+                return { written_bytes: 0, ledger_bytes: size, compacted: false, lock_wait_ms: lockWaitMs };
+            }
+            const customRetention = options.maxEvents !== undefined || options.retentionDays !== undefined;
+            if (!customRetention && size + Buffer.byteLength(appended) <= policy.maxBytes) {
+                await handle.writeFile(appended, "utf8");
+                return { written_bytes: Buffer.byteLength(appended), ledger_bytes: size + Buffer.byteLength(appended), compacted: false, lock_wait_ms: lockWaitMs };
+            }
+            const retained = retainedText([...(previous ?? await readEvents(options)), ...current], retainedBytes, policy.maxEvents);
+            const temporary = `${target}.${process.pid}.${randomUUID()}.tmp`;
+            const replacement = await open(temporary, "wx", 0o600);
+            try {
+                try {
+                    await replacement.writeFile(retained, "utf8");
+                }
+                finally {
+                    await replacement.close();
+                }
+                // Windows cannot replace the destination while our append handle is open.
+                await handle.close();
+                handle = undefined;
+                await rename(temporary, target);
+                return { written_bytes: Buffer.byteLength(retained), ledger_bytes: Buffer.byteLength(retained), compacted: true, lock_wait_ms: lockWaitMs };
+            }
+            finally {
+                await rm(temporary, { force: true });
+            }
+        }
+        finally {
+            await handle?.close();
+        }
+    }
+    finally {
+        await releaseLock();
+    }
+}
+//# sourceMappingURL=usage-ledger.js.map
+//# debugId=f3af7f8f-a462-5eb4-af08-c64c3c327e62

package/dist/sdk/context-usage.d.ts

@@ -1,3 +1,5 @@
+import { type ContextUsageWriteReceipt } from "./context/usage-ledger.js";
+export { ContextUsageValidationError, CONTEXT_USAGE_LIMITS, type ContextUsageWriteReceipt } from "./context/usage-ledger.js";
 import type { ContextRelevanceSurface } from "./context-relevance.js";
 /** One propensity row disclosed when context or next serves a candidate. */
 export interface ContextUsageServingRow {
@@ -18,6 +20,10 @@ export interface ContextUsageServingReceipt {
     surface: ContextRelevanceSurface;
     /** Propensity-complete ranked rows assembled before egress. */
     rows: readonly ContextUsageServingRow[];
+    /** Persisted sample identities; absent on legacy unsampled receipts. */
+    recorded_item_ids?: readonly string[];
+    /** Measured bounded persistence; absent on legacy receipts. */
+    storage?: ContextUsageWriteReceipt;
 }
 /** Append-only serving or subsequent-touch event. */
 export type ContextUsageEvent = {
@@ -29,6 +35,10 @@ export type ContextUsageEvent = {
     surface: ContextRelevanceSurface;
     profile: string;
     rows: ContextUsageServingRow[];
+    /** Full candidate population before deterministic prefix sampling. */
+    candidate_count?: number;
+    /** Candidate rows excluded from this bounded feedback sample. */
+    omitted_row_count?: number;
     result_omitted?: boolean;
     packed_item_ids?: string[];
     /** Legacy pre-egress field ignored by the v2 affinity fold. */
@@ -51,12 +61,18 @@ export type ContextUsageEvent = {
 };
 /** Runtime controls for the bounded derived ledger. */
 export interface ContextUsageLedgerOptions {
-    /** Tracker root containing the runtime directory. */
+    /**
+     * Tracker root containing the runtime directory. Its directory entries and
+     * ancestors must remain controlled by trusted cooperating processes during
+     * ledger operations; hostile concurrent path replacement is unsupported.
+     */
     pmRoot: string;
     /** Disable all reads and writes with zero filesystem work. */
     enabled?: boolean;
     /** Maximum retained event rows. */
     maxEvents?: number;
+    /** Physical byte ceiling; compaction retains at most half to provide headroom. */
+    maxBytes?: number;
     /** Retention horizon in days. */
     retentionDays?: number;
     /** Deterministic timestamp override. */
@@ -90,14 +106,7 @@ export declare function finalizeContextUsageDelivery(options: {
     /** Final projected response returned or rendered to the caller. */
     result: unknown;
 }): Promise<boolean>;
-/** Named validation failure emitted by context-usage SDK inputs. */
-export declare class ContextUsageValidationError extends TypeError {
-    /** Stable machine-readable error code for package and CLI hosts. */
-    readonly code = "context_usage_validation_failed";
-    /** Creates a typed validation error without exposing derived ledger contents. */
-    constructor(message: string);
-}
-/** Records a propensity-complete context/next serving event. */
+/** Records a bounded prefix of ranked context candidates with explicit sampling counts. */
 export declare function recordContextUsageServing(options: ContextUsageLedgerOptions & {
     author: string;
     surface: ContextRelevanceSurface;

package/dist/sdk/context-usage.js

@@ -4,18 +4,16 @@
  * Privacy-minimal, derived context-usage feedback primitives. The JSONL ledger
  * contains only item ids, timestamps, authors, ranks, profiles, and command
  * intents; it never enters item history and is safe to delete or rebuild.
+ * Persistence requires trusted, stable workspace directory entries and
+ * ancestors. For a workspace writable by an untrusted concurrent actor, set
+ * PM_CONTEXT_USAGE_DISABLED=1 or use an isolated copy owned by the caller.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="0c0d2e38-0964-5055-b2f5-6ba7602b2f92")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="b1b1aa19-b1de-5140-8aea-ee1994ee9ecd")}catch(e){}}();
 import { randomUUID } from "node:crypto";
-import { appendFile, mkdir, readFile, rename, stat, writeFile, } from "node:fs/promises";
-import path from "node:path";
-import { acquireLock } from "../core/lock/lock.js";
-const DEFAULT_MAX_EVENTS = 2_048;
-const DEFAULT_RETENTION_DAYS = 30;
+import { appendEvents, readEvents, resolveNow, ContextUsageValidationError, CONTEXT_USAGE_LIMITS, } from "./context/usage-ledger.js";
+export { ContextUsageValidationError, CONTEXT_USAGE_LIMITS } from "./context/usage-ledger.js";
 const DAY_MS = 86_400_000;
-const DEFAULT_COMPACTION_BYTES = 262_144;
-const CONTEXT_USAGE_LOCK_ID = "context-usage-ledger";
 const CONTEXT_USAGE_SERVING_RECEIPT = Symbol.for("@unbrained/pm-cli/context-usage-serving-receipt");
 function asObjectRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value)
@@ -162,86 +160,7 @@ export async function finalizeContextUsageDelivery(options) {
     });
     return true;
 }
-/** Named validation failure emitted by context-usage SDK inputs. */
-export class ContextUsageValidationError extends TypeError {
-    /** Stable machine-readable error code for package and CLI hosts. */
-    code = "context_usage_validation_failed";
-    /** Creates a typed validation error without exposing derived ledger contents. */
-    constructor(message) {
-        super(message);
-        this.name = "ContextUsageValidationError";
-    }
-}
-function ledgerPath(pmRoot) {
-    return path.join(pmRoot, "runtime", "context-usage.jsonl");
-}
-function resolveNow(options) {
-    const iso = options.now ?? new Date().toISOString();
-    const ms = Date.parse(iso);
-    if (!Number.isFinite(ms))
-        throw new ContextUsageValidationError("Context usage now must be a valid timestamp");
-    return { iso: new Date(ms).toISOString(), ms };
-}
-async function readEvents(options) {
-    try {
-        const text = await readFile(ledgerPath(options.pmRoot), "utf8");
-        const events = text
-            .split("\n")
-            .filter(Boolean)
-            .flatMap((line) => {
-            try {
-                return [JSON.parse(line)];
-            }
-            catch {
-                return [];
-            }
-        });
-        const maxEvents = options.maxEvents ?? DEFAULT_MAX_EVENTS;
-        const retentionDays = options.retentionDays ?? DEFAULT_RETENTION_DAYS;
-        const cutoff = resolveNow(options).ms - retentionDays * DAY_MS;
-        return events
-            .filter((entry) => Date.parse(entry.at) >= cutoff)
-            .slice(-maxEvents);
-    }
-    catch {
-        return [];
-    }
-}
-async function appendEvents(options, events, deliveryServeId) {
-    const maxEvents = options.maxEvents ?? DEFAULT_MAX_EVENTS;
-    const retentionDays = options.retentionDays ?? DEFAULT_RETENTION_DAYS;
-    if (!Number.isInteger(maxEvents) ||
-        maxEvents < 1 ||
-        !Number.isFinite(retentionDays) ||
-        retentionDays <= 0) {
-        throw new ContextUsageValidationError("Context usage retention requires positive maxEvents and retentionDays");
-    }
-    const target = ledgerPath(options.pmRoot);
-    const runtimeDirectory = path.dirname(target);
-    const releaseLock = await acquireLock(options.pmRoot, CONTEXT_USAGE_LOCK_ID, 30, `context-usage:${process.pid}`, false, false, 3_000);
-    try {
-        await mkdir(runtimeDirectory, { recursive: true });
-        if (deliveryServeId !== undefined &&
-            (await readEvents(options)).some((event) => event.kind === "delivery" && event.serve_id === deliveryServeId)) {
-            return;
-        }
-        await appendFile(target, events.map((event) => `${JSON.stringify(event)}\n`).join(""), "utf8");
-        const customBounds = options.maxEvents !== undefined || options.retentionDays !== undefined;
-        if (!customBounds && (await stat(target)).size <= DEFAULT_COMPACTION_BYTES)
-            return;
-        const retained = await readEvents(options);
-        const temporary = `${target}.${process.pid}.${randomUUID()}.tmp`;
-        await writeFile(temporary, `${retained.map((entry) => JSON.stringify(entry)).join("\n")}\n`, "utf8");
-        await rename(temporary, target);
-    }
-    finally {
-        await releaseLock();
-    }
-}
-async function appendEvent(options, event) {
-    await appendEvents(options, [event]);
-}
-/** Records a propensity-complete context/next serving event. */
+/** Records a bounded prefix of ranked context candidates with explicit sampling counts. */
 export async function recordContextUsageServing(options) {
     if ([
         process.env.PM_CONTEXT_USAGE_DISABLED === "1",
@@ -253,32 +172,37 @@ export async function recordContextUsageServing(options) {
         throw new ContextUsageValidationError("Context usage serving requires an author and valid ranked rows");
     }
     const normalizedRows = options.rows.map((row) => ({
-        ...row,
         id: row.id.trim(),
+        rank: row.rank,
+        included: row.included,
     }));
     if (new Set(normalizedRows.map((row) => row.id)).size !== normalizedRows.length) {
         throw new ContextUsageValidationError("Context usage serving requires unique normalized row ids");
     }
+    const recordedRows = normalizedRows.slice(0, CONTEXT_USAGE_LIMITS.max_serving_rows);
     const receipt = {
         serve_id: randomUUID(),
         author: options.author.trim(),
         surface: options.surface,
         rows: normalizedRows,
+        recorded_item_ids: recordedRows.map((row) => row.id),
     };
-    await appendEvent(options, {
-        kind: "serve",
-        schema_version: 2,
-        serve_id: receipt.serve_id,
-        at: resolveNow(options).iso,
-        author: options.author.trim(),
-        surface: options.surface,
-        profile: options.profile.trim() || "balanced",
-        rows: receipt.rows.map((row) => ({ ...row })),
-        result_omitted: false,
-        packed_item_ids: receipt.rows
-            .filter((row) => row.included)
-            .map((row) => row.id),
-    });
+    receipt.storage = await appendEvents(options, [{
+            kind: "serve",
+            schema_version: 2,
+            serve_id: receipt.serve_id,
+            at: resolveNow(options).iso,
+            author: options.author.trim(),
+            surface: options.surface,
+            profile: options.profile.trim() || "balanced",
+            rows: recordedRows,
+            candidate_count: normalizedRows.length,
+            omitted_row_count: normalizedRows.length - recordedRows.length,
+            result_omitted: false,
+            packed_item_ids: recordedRows
+                .filter((row) => row.included)
+                .map((row) => row.id),
+        }]);
     return receipt;
 }
 /** Append the exact post-egress delivery decision for one serving receipt. */
@@ -296,6 +220,7 @@ export async function recordContextUsageDelivery(options) {
         (options.resultOmitted && deliveredItemIds.length > 0)) {
         throw new ContextUsageValidationError("Context usage delivery requires emitted ranked ids and zero ids for an omitted result");
     }
+    const recordedIds = new Set(options.receipt.recorded_item_ids ?? options.receipt.rows.map((row) => row.id));
     const delivery = {
         kind: "delivery",
         schema_version: 2,
@@ -304,7 +229,7 @@ export async function recordContextUsageDelivery(options) {
         author: options.receipt.author,
         surface: options.receipt.surface,
         result_omitted: options.resultOmitted,
-        delivered_item_ids: deliveredItemIds,
+        delivered_item_ids: deliveredItemIds.filter((id) => recordedIds.has(id)),
     };
     await appendEvents(options, [delivery], delivery.serve_id);
 }
@@ -318,13 +243,13 @@ export async function recordContextUsageTouch(options) {
         !options.intent.trim()) {
         throw new ContextUsageValidationError("Context usage touch requires author, itemId, and intent");
     }
-    await appendEvent(options, {
-        kind: "touch",
-        at: resolveNow(options).iso,
-        author: options.author.trim(),
-        item_id: options.itemId.trim(),
-        intent: options.intent.trim(),
-    });
+    await appendEvents(options, [{
+            kind: "touch",
+            at: resolveNow(options).iso,
+            author: options.author.trim(),
+            item_id: options.itemId.trim(),
+            intent: options.intent.trim(),
+        }]);
 }
 /**
  * Records mutation outcomes as one append and one optional compaction pass.
@@ -440,4 +365,4 @@ export async function readContextUsageAffinity(options) {
     };
 }
 //# sourceMappingURL=context-usage.js.map
-//# debugId=0c0d2e38-0964-5055-b2f5-6ba7602b2f92
+//# debugId=b1b1aa19-b1de-5140-8aea-ee1994ee9ecd

package/dist/sdk/dependency-provenance.d.ts

@@ -61,3 +61,10 @@ export declare function normalizeDependencySourceKind(sourceKind: string | undef
  * global seeds preserve the caller-provided id verbatim (apart from trimming).
  */
 export declare function normalizeDependencySeedId(id: string, prefix: string, sourceKind: string | undefined): string;
+/**
+ * Canonicalize a local relationship target using the workspace prefix. Explicit
+ * provider locators and externally sourced identities retain case and spelling;
+ * only surrounding whitespace is removed. Resolution and parent policy remain
+ * the caller's responsibility, so dangling local ids are never guessed remote.
+ */
+export declare function normalizeItemReference(reference: string, prefix: string, sourceKind?: string): string;

package/dist/sdk/dependency-provenance.js

@@ -5,7 +5,7 @@
  * items outside the current workspace.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="f3f3beb2-1d60-52fe-88ce-1ab3cb9dba0d")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="ee17fdea-aeac-55b0-8302-a8740ba8428e")}catch(e){}}();
 import { normalizeItemId } from "../core/item/id.js";
 import { isExternalDependencyReference, isExternalDependencySourceKind, } from "../core/item/dependency-reference.js";
 export { isExternalDependencyReference, isExternalDependencySourceKind, } from "../core/item/dependency-reference.js";
@@ -117,10 +117,20 @@ export function normalizeDependencySourceKind(sourceKind) {
  * global seeds preserve the caller-provided id verbatim (apart from trimming).
  */
 export function normalizeDependencySeedId(id, prefix, sourceKind) {
-    const trimmed = id.trim();
-    return isExternalDependencySourceKind(sourceKind)
+    return normalizeItemReference(id, prefix, sourceKind);
+}
+/**
+ * Canonicalize a local relationship target using the workspace prefix. Explicit
+ * provider locators and externally sourced identities retain case and spelling;
+ * only surrounding whitespace is removed. Resolution and parent policy remain
+ * the caller's responsibility, so dangling local ids are never guessed remote.
+ */
+export function normalizeItemReference(reference, prefix, sourceKind) {
+    const trimmed = reference.trim();
+    return isExternalDependencySourceKind(sourceKind) ||
+        isExternalDependencyReference(trimmed)
         ? trimmed
         : normalizeItemId(trimmed, prefix);
 }
 //# sourceMappingURL=dependency-provenance.js.map
-//# debugId=f3f3beb2-1d60-52fe-88ce-1ab3cb9dba0d
+//# debugId=ee17fdea-aeac-55b0-8302-a8740ba8428e

package/dist/sdk/duplicates.d.ts

@@ -8,6 +8,8 @@ import type { GlobalOptions } from "../core/shared/command-types.js";
 import { type DuplicateCluster, type DuplicateClustersResult } from "./similarity.js";
 /** Options shared by the `pm duplicates` command and SDK action. */
 export interface DuplicatesCommandOptions {
+    /** Compare all pairs instead of using lossless prefix filtering. */
+    exhaustive?: boolean;
     /** Lifecycle statuses to include; omitted means every status. */
     status?: readonly string[];
     /** Inclusive creation timestamp lower bound. */

package/dist/sdk/duplicates.js

@@ -1,11 +1,12 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="6152efa9-8338-57f0-b3de-5707befed019")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="51a84d98-6b3c-55ad-81f8-81928aa6e537")}catch(e){}}();
 import { resolvePmRoot } from "../core/store/paths.js";
 import { findDuplicateClusters, } from "./similarity.js";
 /** Discover existing duplicate clusters without creating or mutating an item. */
 export async function runDuplicates(global, options = {}) {
     const result = await findDuplicateClusters({
         pmRoot: resolvePmRoot(process.cwd(), global.path),
+        exhaustive: options.exhaustive,
         ...(options.status === undefined
             ? {}
             : {
@@ -37,4 +38,4 @@ export async function runDuplicates(global, options = {}) {
     };
 }
 //# sourceMappingURL=duplicates.js.map
-//# debugId=6152efa9-8338-57f0-b3de-5707befed019
+//# debugId=51a84d98-6b3c-55ad-81f8-81928aa6e537

package/dist/sdk/environment/host-environment-errors.d.ts

@@ -1,27 +1,5 @@
-import { PmCliError } from "../../core/shared/errors.js";
-/** Optional stable codes used by an existing SDK surface for each fault class. */
-export interface HostEnvironmentFaultCodeOverrides {
-    /** Code used for quota and storage exhaustion. */
-    capacity?: string;
-    /** Code used for access policy and read-only filesystems. */
-    permission?: string;
-    /** Code used for file-descriptor and memory exhaustion. */
-    resource?: string;
-}
-/** Context and compatibility controls for a host-environment boundary. */
-export interface HostEnvironmentBoundaryOptions {
-    /** Existing surface-specific codes that must remain compatible. */
-    codes?: HostEnvironmentFaultCodeOverrides;
-    /** Human explanation of why the operation needs host resources. */
-    why?: string;
-    /** Additional ordered recovery guidance. */
-    nextSteps?: readonly string[];
-    /** Copyable retry command when one is safe. */
-    suggestedRetry?: string;
-}
-/** Return a declared host errno only when it represents recoverable environment state. */
-export declare function classifyHostEnvironmentFault(error: unknown): string | null;
-/** Translate one known host fault into a stable path-redacted SDK refusal. */
-export declare function translateHostEnvironmentFault(error: unknown, operation: string, options?: HostEnvironmentBoundaryOptions): PmCliError | null;
-/** Run one SDK filesystem stage and translate only declared host faults. */
-export declare function withHostEnvironmentBoundary<T>(operation: string, run: () => Promise<T>, options?: HostEnvironmentBoundaryOptions): Promise<T>;
+/**
+ * @module sdk/host-environment-errors
+ * Public SDK compatibility surface for path-redacted host filesystem refusals.
+ */
+export { classifyHostEnvironmentFault, translateHostEnvironmentFault, withHostEnvironmentBoundary, type HostEnvironmentBoundaryOptions, type HostEnvironmentFaultCodeOverrides, } from "../../core/fs/host-environment-errors.js";