@unbrained/pm-cli 2026.8.14 → 2026.8.16

package/dist/sdk/governance.d.ts

@@ -5,6 +5,12 @@
  */
 export * from "./governance/gc.js";
 export * from "./governance/health.js";
+export * from "./governance/extension-host-version.js";
+export * from "./governance/assurance.js";
+export * from "./governance/assurance-action.js";
+export * from "./governance/assurance-mutation-error.js";
+export * from "./governance/assurance-presets.js";
+export * from "./governance/assurance-runtime.js";
 export { runReindex, type ReindexOptions, type ReindexResult, } from "./governance/reindex.js";
 export * from "./governance/stale-work.js";
 export * from "./governance/storage-integrity.js";

package/dist/sdk/governance.js

@@ -4,9 +4,15 @@
  * Provides validation, health, integrity, and mutation-policy primitives.
  */
 
-!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]="8e8c2de1-7bff-57c6-8e71-9c27e9e76eaa")}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]="0baaaf38-2a32-5d6e-92bc-9919d2393f86")}catch(e){}}();
 export * from "./governance/gc.js";
 export * from "./governance/health.js";
+export * from "./governance/extension-host-version.js";
+export * from "./governance/assurance.js";
+export * from "./governance/assurance-action.js";
+export * from "./governance/assurance-mutation-error.js";
+export * from "./governance/assurance-presets.js";
+export * from "./governance/assurance-runtime.js";
 export { runReindex, } from "./governance/reindex.js";
 export * from "./governance/stale-work.js";
 export * from "./governance/storage-integrity.js";
@@ -17,4 +23,4 @@ export * from "./mutation-guard.js";
 export * from "./governance/provenance-health.js";
 export * from "./similarity.js";
 //# sourceMappingURL=governance.js.map
-//# debugId=8e8c2de1-7bff-57c6-8e71-9c27e9e76eaa
+//# debugId=0baaaf38-2a32-5d6e-92bc-9919d2393f86

package/dist/sdk/history-repair.d.ts

@@ -1,6 +1,7 @@
 import { type ReplayDocument } from "../core/history/replay.js";
 import type { GlobalOptions } from "../core/shared/command-types.js";
 import type { HistoryEntry } from "../types/index.js";
+import { type ProvenanceNormalizationReceipt } from "./governance/provenance-health.js";
 /** Documents the history repair command options payload exchanged by command, SDK, and package integrations. */
 export interface HistoryRepairCommandOptions {
     /** Value that configures or reports dry run for this contract. */
@@ -19,6 +20,8 @@ export interface HistoryRepairCommandOptions {
     auditContextById?: Record<string, Record<string, unknown>>;
     /** Add an audit event even when replay and the current item already match. */
     forceAuditEntry?: boolean;
+    /** Remove bounded-domain-invalid provenance observations and record an aggregate privacy-safe audit receipt. */
+    normalizeProvenance?: boolean;
 }
 /** Documents the history repair result payload exchanged by command, SDK, and package integrations. */
 export interface HistoryRepairResult {
@@ -41,6 +44,9 @@ export interface HistoryRepairResult {
         audit_entry_added: boolean;
         verify_ok: boolean;
         verify_errors: string[];
+        item_hash_version_before: number | null;
+        item_hash_version_after: number;
+        version_disposition: "preserved" | "selected_for_ambiguous_stream";
     };
     /** Value that configures or reports item for this contract. */
     item: {
@@ -48,6 +54,10 @@ export interface HistoryRepairResult {
         path: string | null;
         matched_chain_before: boolean | null;
     };
+    /** Privacy-safe receipt for the explicitly requested provenance normalization mode. */
+    provenance_normalization: ProvenanceNormalizationReceipt & {
+        requested: boolean;
+    };
     /** Present when reconciling the chain with the on-disk item discards the replayed effect of earlier history events (GH-603): names the reverted fields and the authors whose mutations the reconciliation overwrites, so cross-author data loss after a lossy merge is loud instead of silent. */
     reconciliation?: HistoryRepairReconciliationReport;
     /** Value that configures or reports warnings for this contract. */
@@ -126,7 +136,9 @@ export interface HistoryRepairAllResult {
     scanned_streams: number;
     /** Value that configures or reports drifted streams for this contract. */
     drifted_streams: number;
-    /** One compact row per drifted stream (clean streams are summarized by the counts only). */
+    /** Streams selected only because invalid provenance required normalization. */
+    provenance_invalid_streams: number;
+    /** One compact row per drifted or provenance-normalization target. */
     streams: HistoryRepairAllStreamResult[];
     /** Value that configures or reports totals for this contract. */
     totals: {

package/dist/sdk/history-repair.js

@@ -4,12 +4,12 @@
  * Implements the pm history repair command surface and its agent-facing runtime behavior.
  */
 
-!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]="dd5ab9c3-bc6f-59f1-be89-ad0ab2abe7b5")}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]="de9b7f82-0f51-599d-b1fa-2d54e3acbdbc")}catch(e){}}();
 import jsonPatch from "fast-json-patch";
 import { patchPathToChangedField } from "../core/history/history-diff.js";
 import { pathExists, readFileIfExists } from "../core/fs/fs-utils.js";
 import { executeHistoryRewrite, writeHistoryRawWithRollback, } from "../core/history/history-rewrite.js";
-import { historyEntriesToRaw, normalizeReplayPatchOps, reanchorHistoryEntries, replayHash, toReplayDocument, verifyHistoryChain, } from "../core/history/replay.js";
+import { historyEntriesToRaw, normalizeReplayPatchOps, reanchorHistoryEntries, replayHash, resolveHistoryRepairItemHashVersion, toReplayDocument, verifyHistoryChain, verifyHistoryChainWithVersion, } from "../core/history/replay.js";
 import { scanHistoryDrift } from "../core/history/drift-scan.js";
 import { invalidateHistoryDriftCache } from "../core/history/drift-cache.js";
 import { readHistoryEntries } from "../core/history/read.js";
@@ -23,6 +23,7 @@ import { listAllItemMetadataWithBody, readLocatedItem, } from "../core/store/ite
 import { getSettingsPath, resolvePmRoot } from "../core/store/paths.js";
 import { readSettings } from "../core/store/settings.js";
 import { resolveHistorySubject } from "./history-redact.js";
+import { listInvalidProvenanceHistoryStreamIds, normalizeInvalidHistoryProvenance, } from "./governance/provenance-health.js";
 function replayFieldValue(document, field) {
     return field === "body"
         ? document.body
@@ -133,7 +134,7 @@ export function analyzeReconciliationDiscard(entries, finalReplay, currentItemRe
             : null,
     };
 }
-async function loadHistoryRepairItemReplay(subject, settings, historyEntries) {
+async function loadHistoryRepairItemReplay(subject, settings, historyEntries, itemHashVersion) {
     const currentItemPath = subject.located?.itemPath ?? null;
     const loadedItem = subject.located
         ? await readLocatedItem(subject.located, { schema: settings.schema })
@@ -152,7 +153,7 @@ async function loadHistoryRepairItemReplay(subject, settings, historyEntries) {
     return {
         currentItemReplay,
         currentItemPath,
-        matchedChainBefore: replayHash(currentItemReplay) === lastOriginalAfterHash,
+        matchedChainBefore: replayHash(currentItemReplay, itemHashVersion) === lastOriginalAfterHash,
         currentItemRawBeforeLock: loadedItem.raw,
         loadedItem,
     };
@@ -180,16 +181,19 @@ function buildHistoryRepairEntries(params) {
         patch: params.reconcileNeeded && params.currentItemReplay
             ? jsonPatch.compare(params.finalReplay, params.currentItemReplay)
             : [],
-        before_hash: replayHash(params.finalReplay),
-        after_hash: replayHash(afterReplay),
+        before_hash: replayHash(params.finalReplay, params.itemHashVersion),
+        after_hash: replayHash(afterReplay, params.itemHashVersion),
         message: params.message,
+        ...(params.explicitItemHashVersion
+            ? { item_hash_version: params.itemHashVersion }
+            : {}),
         ...(params.auditContext === undefined
             ? {}
             : { context: params.auditContext }),
     });
     return { rewrittenEntries, auditEntryAdded: true };
 }
-function collectHistoryRepairWarnings(changed, skippedOps) {
+function collectHistoryRepairWarnings(changed, skippedOps, reconciliation) {
     const warnings = [];
     if (!changed) {
         warnings.push("history_repair_no_changes");
@@ -197,6 +201,9 @@ function collectHistoryRepairWarnings(changed, skippedOps) {
     if (skippedOps > 0) {
         warnings.push(`history_repair_skipped_unresolvable_ops:${skippedOps}`);
     }
+    if (reconciliation && reconciliation.discarded_events.length > 0) {
+        warnings.push(`history_repair_reconcile_discards_events:${reconciliation.discarded_events.length}`, `history_repair_discarded_authors:${reconciliation.discarded_authors.join(",")}`);
+    }
     return warnings;
 }
 async function applyHistoryRepairRewrite(params) {
@@ -241,11 +248,28 @@ export async function runHistoryRepair(id, options, global) {
         throw new PmCliError(`No history entries exist for ${subject.id}; nothing to repair.`, EXIT_CODE.USAGE);
     }
     const chainBefore = verifyHistoryChain(historyEntries);
-    const reanchor = reanchorHistoryEntries(historyEntries);
-    const itemReplayContext = await loadHistoryRepairItemReplay(subject, settings, historyEntries);
+    const chainVersionBefore = verifyHistoryChainWithVersion(historyEntries);
+    const provenanceNormalization = options.normalizeProvenance
+        ? normalizeInvalidHistoryProvenance(historyEntries)
+        : {
+            entries: historyEntries,
+            receipt: {
+                changed: false,
+                events_changed: 0,
+                observations_removed: 0,
+                invalid_values: [],
+            },
+        };
+    const itemHashVersion = resolveHistoryRepairItemHashVersion(provenanceNormalization.entries);
+    const explicitVersionsBefore = new Set(provenanceNormalization.entries
+        .map((entry) => entry.item_hash_version)
+        .filter((version) => version !== undefined));
+    const reanchor = reanchorHistoryEntries(provenanceNormalization.entries, itemHashVersion);
+    const itemReplayContext = await loadHistoryRepairItemReplay(subject, settings, historyEntries, itemHashVersion);
     const finalReplay = reanchor.finalDocument;
     const reconcileNeeded = itemReplayContext.currentItemReplay !== null &&
-        replayHash(finalReplay) !== replayHash(itemReplayContext.currentItemReplay);
+        replayHash(finalReplay, itemHashVersion) !==
+            replayHash(itemReplayContext.currentItemReplay, itemHashVersion);
     // GH-603: reconciling toward the on-disk item can silently overwrite the
     // replayed effect of other authors' events (classic after a lossy merge).
     // Surface exactly what is being discarded before any write happens.
@@ -257,6 +281,7 @@ export async function runHistoryRepair(id, options, global) {
         reanchor.entriesPatchRepaired > 0,
         reconcileNeeded,
         options.forceAuditEntry === true,
+        provenanceNormalization.receipt.changed,
     ].some(Boolean);
     const author = resolveAuthor(options.author, settings.author_default);
     const dryRun = Boolean(options.dryRun);
@@ -275,17 +300,20 @@ export async function runHistoryRepair(id, options, global) {
         author,
         message: repairMessage,
         auditOperation: options.auditOperation ?? "history_repair",
-        auditContext: options.auditContext,
+        auditContext: provenanceNormalization.receipt.changed
+            ? {
+                ...options.auditContext,
+                provenance_normalization: provenanceNormalization.receipt,
+            }
+            : options.auditContext,
+        itemHashVersion,
+        explicitItemHashVersion: reanchor.explicitItemHashVersion,
     });
     const historyVerify = verifyHistoryChain(rewrittenEntries);
     if (!historyVerify.ok) {
         throw new PmCliError(`history-repair produced an invalid rewritten chain (${historyVerify.errors.join(", ")}).`, EXIT_CODE.GENERIC_FAILURE);
     }
-    const warnings = collectHistoryRepairWarnings(changed, reanchor.skippedOps);
-    if (reconciliation && reconciliation.discarded_events.length > 0) {
-        warnings.push(`history_repair_reconcile_discards_events:${reconciliation.discarded_events.length}`);
-        warnings.push(`history_repair_discarded_authors:${reconciliation.discarded_authors.join(",")}`);
-    }
+    const warnings = collectHistoryRepairWarnings(changed, reanchor.skippedOps, reconciliation);
     if (changed && !dryRun) {
         warnings.push(...(await applyHistoryRepairRewrite({
             pmRoot,
@@ -317,12 +345,21 @@ export async function runHistoryRepair(id, options, global) {
             audit_entry_added: auditEntryAdded,
             verify_ok: historyVerify.ok,
             verify_errors: historyVerify.errors,
+            item_hash_version_before: chainVersionBefore.item_hash_version ?? null,
+            item_hash_version_after: itemHashVersion,
+            version_disposition: explicitVersionsBefore.size > 1
+                ? "selected_for_ambiguous_stream"
+                : "preserved",
         },
         item: {
             exists: itemReplayContext.currentItemPath !== null,
             path: itemReplayContext.currentItemPath,
             matched_chain_before: itemReplayContext.matchedChainBefore,
         },
+        provenance_normalization: {
+            requested: options.normalizeProvenance === true,
+            ...provenanceNormalization.receipt,
+        },
         ...(reconciliation ? { reconciliation } : {}),
         warnings: [...new Set(warnings)].sort((left, right) => left.localeCompare(right)),
         generated_at: nowIso(),
@@ -348,10 +385,16 @@ export async function runHistoryRepairAll(options, global) {
     const itemReadWarnings = [];
     const items = await listAllItemMetadataWithBody(pmRoot, settings.item_format, typeRegistry.type_to_folder, itemReadWarnings, settings.schema, { forceSourceScan: true });
     const drift = await scanHistoryDrift(pmRoot, items);
+    const invalidProvenanceIds = options.normalizeProvenance
+        ? await listInvalidProvenanceHistoryStreamIds(pmRoot)
+        : [];
+    const targetedIds = [
+        ...new Set([...drift.driftedItems, ...invalidProvenanceIds]),
+    ].sort((left, right) => left.localeCompare(right));
     const streams = [];
     const repairWarnings = [];
     const totals = { repaired: 0, skipped_clean: 0, failed: 0 };
-    for (const driftedId of drift.driftedItems) {
+    for (const driftedId of targetedIds) {
         try {
             const result = await runHistoryRepair(driftedId, {
                 ...options,
@@ -392,6 +435,7 @@ export async function runHistoryRepairAll(options, global) {
         dry_run: Boolean(options.dryRun),
         scanned_streams: items.length,
         drifted_streams: drift.driftedItems.length,
+        provenance_invalid_streams: invalidProvenanceIds.length,
         streams,
         totals,
         warnings: [...new Set([...itemReadWarnings, ...repairWarnings])].sort((left, right) => left.localeCompare(right)),
@@ -399,4 +443,4 @@ export async function runHistoryRepairAll(options, global) {
     };
 }
 //# sourceMappingURL=history-repair.js.map
-//# debugId=dd5ab9c3-bc6f-59f1-be89-ad0ab2abe7b5
+//# debugId=de9b7f82-0f51-599d-b1fa-2d54e3acbdbc

package/dist/sdk/index.d.ts

@@ -7,7 +7,7 @@ export { PM_COMMAND_VISIBILITY_CONTRACTS, PM_MCP_PROMPT_CONTRACTS, PM_MCP_RESOUR
 export * from "./agent-session-context.js";
 export type { PmCommandVisibilityContract, PmCommandVisibilityTier, PmMcpPromptArgumentContract, PmMcpPromptContract, PmMcpResourceContract, PmMcpToolProfile, } from "./agent-capability-contracts.js";
 export { isErrnoError, limitAnnotationEntries, parseAnnotationTextInput, readAnnotationEntries, normalizeAnnotationTransportOptions, resolveAnnotationInput, resolveAnnotationIndex, runAnnotationCommand, wrapOwnershipConflict, type AnnotationCommandConfig, type AnnotationCommandOptions, type AnnotationCommandResult, type AnnotationEntry, type AnnotationInput, type AnnotationHistoryRestoration, type AnnotationMutationReceipt, type AnnotationOmissionReceipt, type AnnotationSourceOptions, type OwnershipConflictGuidance, } from "./annotations.js";
-export { acknowledgeUnknownAuthorHistoryEvents, acknowledgeUnknownAuthorHistoryEventsFromTransport, inspectHistoryAuthorStream, parseUnknownAuthorHistoryEventCoordinates, resolveUnknownAuthorAcknowledgmentSelector, scanHistoryAuthorAttribution, type AcknowledgeUnknownAuthorEventsOptions, type HistoryAuthorAttributionScan, type UnknownAuthorHistoryEvent, } from "./author-attribution.js";
+export { acknowledgeUnknownAuthorHistoryEvents, acknowledgeUnknownAuthorHistoryEventsFromTransport, inspectHistoryAuthorStream, parseUnknownAuthorHistoryEventCoordinates, planUnknownAuthorHistoryAcknowledgment, resolveUnknownAuthorAcknowledgmentSelector, scanHistoryAuthorAttribution, type AcknowledgeUnknownAuthorEventsOptions, type HistoryAuthorAttributionScan, type UnknownAuthorAcknowledgmentPlan, type UnknownAuthorAcknowledgmentPlanCoordinate, type UnknownAuthorAcknowledgmentResult, type UnknownAuthorHistoryEvent, } from "./author-attribution.js";
 export { BUILTIN_CORPUS_SHAPES, PM_CORPUS_SHAPE_SCHEMA, buildCorpusShapeItemPlan, createCorpusShapeMeasurement, defineCorpusShape, listBuiltinCorpusShapes, measureCorpusShapePlan, resolveBuiltinCorpusShape, type BuiltinCorpusShapeName, type CorpusShape, type CorpusShapeEdgeWeight, type CorpusShapeItemPlan, type CorpusShapeMeasurement, type CorpusShapeProfile, } from "./corpus-shape.js";
 export * from "./core-governance.js";
 export { createPmCliProgram } from "./cli-program.js";
@@ -22,6 +22,7 @@ export * from "./agent/command-suggestions.js";
 export * from "./agent/item-addressing.js";
 export * from "./agent/create-option-policy.js";
 export { runGc, type GcCheckpointsSummary, type GcLocksSummary, } from "./governance/gc.js";
+export { PM_EXACT_COVERAGE_METRICS, findCoverageDeficits, type PmCoverageDeficit, type PmExactCoverageMetric, } from "./governance/coverage-assurance.js";
 export { _testOnlyHealthCommand, runHealth, type HealthCheck, } from "./governance/health.js";
 export { _testOnlyValidateCommand, projectValidateCounts, runValidate, type ValidateCheck, type ValidateCountsFixesSummary, type ValidateCountsResult, type ValidateFixesSummary, type ValidateMutationServices, } from "./governance/validate.js";
 export { runExtension, type ExtensionCommandAction } from "./extension.js";

package/dist/sdk/index.js

@@ -4,11 +4,11 @@
  * Defines public SDK APIs and package-author helpers for Index.
  */
 
-!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]="a05170b2-a48d-5275-ac04-aafc9f8315b2")}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]="9ec91496-fc1e-5be5-a8e8-145d884b0ef7")}catch(e){}}();
 export { PM_COMMAND_VISIBILITY_CONTRACTS, PM_MCP_PROMPT_CONTRACTS, PM_MCP_RESOURCE_CONTRACTS, PM_MCP_TOOL_COMMAND_CONTRACTS, listPmCommandsForTier, listPmMcpToolsForProfile, renderPmCommandVisibilityMarkdown, resolvePmCommandVisibilityTier, } from "./agent-capability-contracts.js";
 export * from "./agent-session-context.js";
 export { isErrnoError, limitAnnotationEntries, parseAnnotationTextInput, readAnnotationEntries, normalizeAnnotationTransportOptions, resolveAnnotationInput, resolveAnnotationIndex, runAnnotationCommand, wrapOwnershipConflict, } from "./annotations.js";
-export { acknowledgeUnknownAuthorHistoryEvents, acknowledgeUnknownAuthorHistoryEventsFromTransport, inspectHistoryAuthorStream, parseUnknownAuthorHistoryEventCoordinates, resolveUnknownAuthorAcknowledgmentSelector, scanHistoryAuthorAttribution, } from "./author-attribution.js";
+export { acknowledgeUnknownAuthorHistoryEvents, acknowledgeUnknownAuthorHistoryEventsFromTransport, inspectHistoryAuthorStream, parseUnknownAuthorHistoryEventCoordinates, planUnknownAuthorHistoryAcknowledgment, resolveUnknownAuthorAcknowledgmentSelector, scanHistoryAuthorAttribution, } from "./author-attribution.js";
 export { BUILTIN_CORPUS_SHAPES, PM_CORPUS_SHAPE_SCHEMA, buildCorpusShapeItemPlan, createCorpusShapeMeasurement, defineCorpusShape, listBuiltinCorpusShapes, measureCorpusShapePlan, resolveBuiltinCorpusShape, } from "./corpus-shape.js";
 export * from "./core-governance.js";
 export { createPmCliProgram } from "./cli-program.js";
@@ -23,6 +23,7 @@ export * from "./agent/command-suggestions.js";
 export * from "./agent/item-addressing.js";
 export * from "./agent/create-option-policy.js";
 export { runGc, } from "./governance/gc.js";
+export { PM_EXACT_COVERAGE_METRICS, findCoverageDeficits, } from "./governance/coverage-assurance.js";
 export { _testOnlyHealthCommand, runHealth, } from "./governance/health.js";
 export { _testOnlyValidateCommand, projectValidateCounts, runValidate, } from "./governance/validate.js";
 export { runExtension } from "./extension.js";
@@ -151,4 +152,4 @@ export * from "./governance.js";
 export * from "./query.js";
 export * from "./testing.js";
 //# sourceMappingURL=index.js.map
-//# debugId=a05170b2-a48d-5275-ac04-aafc9f8315b2
+//# debugId=9ec91496-fc1e-5be5-a8e8-145d884b0ef7

package/dist/sdk/linked-artifacts.js

@@ -4,7 +4,7 @@
  * Implements the pm linked artifacts command surface and its agent-facing runtime behavior.
  */
 
-!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]="585364aa-e5ff-56b6-8276-8f741fbd6be4")}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]="256b39b7-882e-553c-9dea-813bfd363dd7")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import fg from "fast-glob";
@@ -57,9 +57,20 @@ export function looksLikeStructuredPathEntry(raw) {
     if (/^(?:[-*+]\s+)?(?:path|scope|note)\s*[:=]/i.test(raw)) {
         return true;
     }
-    // A first-key typo (e.g. `lable=main,path=…`) must still be parsed so the
-    // unknown key is rejected rather than swallowed as a bare path (GH-258).
-    return looksLikeGenericKeyValueEntry(raw);
+    // An equals sign is valid inside filesystem paths and URL query strings.
+    // Preserve unmistakable whitespace-free path/URL shapes while routing
+    // leading assignment syntax through the structured-key allowlist so typos
+    // and malformed URL-plus-note input remain atomic failures (GH-258,
+    // GH-1000).
+    const equalsIndex = raw.indexOf("=");
+    if (equalsIndex >= 0 &&
+        !/\s/u.test(raw) &&
+        (/^[A-Za-z][A-Za-z0-9+.-]*:\/\//u.test(raw) ||
+            /^(?:[A-Za-z]:[\\/]|[\\/]{1,2}|\.\.?(?:[\\/]))/u.test(raw) ||
+            [raw.indexOf("/"), raw.indexOf("\\")].some((separatorIndex) => separatorIndex >= 0 && separatorIndex < equalsIndex))) {
+        return false;
+    }
+    return raw.includes("=") || looksLikeGenericKeyValueEntry(raw);
 }
 function expandBareCommaSeparatedAddEntries(raw) {
     return raw.flatMap((entry) => {
@@ -479,4 +490,4 @@ export function renameArtifactsResultKey(result, key) {
     return out;
 }
 //# sourceMappingURL=linked-artifacts.js.map
-//# debugId=585364aa-e5ff-56b6-8276-8f741fbd6be4
+//# debugId=256b39b7-882e-553c-9dea-813bfd363dd7

package/dist/sdk/pagination.d.ts

@@ -1,4 +1,17 @@
 import type { CliFlagContract } from "./cli-contracts/flag-contracts.js";
+/** Validated transport envelope carried by an opaque query cursor. */
+export interface QueryCursorEnvelope {
+    /** Serialized cursor contract version. */
+    version: number;
+    /** Stable fingerprint of the query semantics that produced the cursor. */
+    fingerprint: string;
+    /** Stable id of the last row emitted by the producer. */
+    after_id: string;
+    /** Zero-based position of the last emitted row when available. */
+    after_index?: number;
+    /** Opaque producer-defined snapshot token for stable continuation. */
+    snapshot?: string;
+}
 /** Decoded cursor state for advanced package and retrieval-window integrations. */
 export interface QueryCursorState {
     /** Stable id of the last row emitted by the previous page. */
@@ -27,6 +40,8 @@ export declare function selectCursorSemanticOptions(options: Readonly<Record<str
 export declare function createQueryFingerprint(command: string, contract: unknown): string;
 /** Encode the last emitted item id into a versioned opaque base64url cursor. */
 export declare function encodeQueryCursor(fingerprint: string, afterId: string, afterIndex?: number, snapshot?: string): string;
+/** Decode and validate an opaque cursor without imposing caller query identity. */
+export declare function decodeQueryCursorEnvelope(cursor: unknown): QueryCursorEnvelope;
 /** Decode and validate complete cursor state against a query fingerprint. */
 export declare function decodeQueryCursorState(cursor: unknown, expectedFingerprint: string): QueryCursorState;
 /** Decode and validate a cursor against the normalized query fingerprint. */

package/dist/sdk/pagination.js

@@ -5,7 +5,7 @@
  * package-authored query surfaces.
  */
 
-!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]="83fe180b-9d95-5d19-9d3b-ba3821700e61")}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]="d3329fac-693d-566c-a30a-43f8fb37938f")}catch(e){}}();
 import { createHash } from "node:crypto";
 import { PmCliError } from "../core/shared/errors.js";
 import { EXIT_CODE } from "../core/shared/constants.js";
@@ -78,8 +78,8 @@ function isQueryCursorEnvelope(value) {
         (envelope.snapshot === undefined ||
             (typeof envelope.snapshot === "string" && envelope.snapshot.length > 0)));
 }
-/** Decode and validate complete cursor state against a query fingerprint. */
-export function decodeQueryCursorState(cursor, expectedFingerprint) {
+/** Decode and validate an opaque cursor without imposing caller query identity. */
+export function decodeQueryCursorEnvelope(cursor) {
     if (typeof cursor !== "string") {
         throw invalidCursor("Query cursor is malformed.");
     }
@@ -99,7 +99,11 @@ export function decodeQueryCursorState(cursor, expectedFingerprint) {
     if (!isQueryCursorEnvelope(parsed)) {
         throw invalidCursor("Query cursor version or payload is unsupported.");
     }
-    const envelope = parsed;
+    return parsed;
+}
+/** Decode and validate complete cursor state against a query fingerprint. */
+export function decodeQueryCursorState(cursor, expectedFingerprint) {
+    const envelope = decodeQueryCursorEnvelope(cursor);
     if (envelope.fingerprint !== expectedFingerprint) {
         throw invalidCursor(`Query cursor does not match the current filters, sort, or query (${envelope.fingerprint} != ${expectedFingerprint}).`);
     }
@@ -156,4 +160,4 @@ export const QUERY_CURSOR_CONTRACT = Object.freeze({
     max_length: MAX_CURSOR_LENGTH,
 });
 //# sourceMappingURL=pagination.js.map
-//# debugId=83fe180b-9d95-5d19-9d3b-ba3821700e61
+//# debugId=d3329fac-693d-566c-a30a-43f8fb37938f

package/dist/sdk/query/context.d.ts

@@ -399,6 +399,10 @@ export interface ContextRankingSummary {
         score: number;
         contributions: ContextRelevanceContributions;
     }>;
+    /** Number of candidates considered before answer-sized projection. */
+    candidate_count: number;
+    /** Number of candidate explanations omitted because their rows were not served. */
+    omitted_count: number;
     /** Rebuildable feature-store freshness and provenance. */
     feature_store?: {
         source: "derived_index" | "scan_fallback";
@@ -462,7 +466,7 @@ export declare function packRankedContextItems(report: ContextRelevanceReport<It
 /** Projects the SDK packer report onto the stable low-token command envelope. */
 export declare function toContextPackingSummary(report: ContextPackingReport<ItemMetadata>): ContextPackingSummary;
 /** Project a full scorer report onto the low-token command explanation shape. */
-export declare function toContextRankingSummary<TItem>(report: ContextRelevanceReport<TItem>, featureStore?: ContextSignalStoreReadResult): ContextRankingSummary;
+export declare function toContextRankingSummary<TItem>(report: ContextRelevanceReport<TItem>, featureStore?: ContextSignalStoreReadResult, servedItemIds?: ReadonlySet<string>): ContextRankingSummary;
 declare function completionPct(closed: number, total: number): number;
 /** Indexes items by their parent id, yielding a parent→direct-children map used by the hierarchy/progress rollups and by focus-row child completion. Items without a parent are skipped. Exported so sibling read commands reuse the same index. */
 export declare function buildChildrenByParent(allItems: ItemMetadata[]): Map<string, ItemMetadata[]>;

package/dist/sdk/query/context.js

@@ -4,7 +4,7 @@
  * Implements the pm context command surface and its agent-facing runtime behavior.
  */
 
-!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]="757a0349-9fb6-579d-ab29-fabaad790ce4")}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]="ee5279f2-7489-59fb-8f96-f2e035434cce")}catch(e){}}();
 import { SETTINGS_DEFAULTS, EXIT_CODE, PmCliError, compareTimestampStrings, nowIso, isTerminalStatus, normalizeStatusForRegistry, normalizeStatusInput, resolveRuntimeStatusRegistry, resolvePmRoot, readSettings, resolveAuthor, discoverExtensions, } from "../runtime-primitives.js";
 import { collectDependencyBlockedIds, resolveItemBlockers, } from "../actionability.js";
 import { CONTEXT_DEPTH_VALUES, CONTEXT_SECTION_VALUES, } from "../../types/index.js";
@@ -455,17 +455,22 @@ export function toContextPackingSummary(report) {
     };
 }
 /** Project a full scorer report onto the low-token command explanation shape. */
-export function toContextRankingSummary(report, featureStore) {
+export function toContextRankingSummary(report, featureStore, servedItemIds) {
+    const ranked = servedItemIds === undefined
+        ? report.ranked
+        : report.ranked.filter((entry) => servedItemIds.has(entry.id));
     return {
         model: report.model,
         available_signals: report.available_signals,
-        items: report.ranked.map((entry) => ({
+        items: ranked.map((entry) => ({
             id: entry.id,
             rank: entry.rank,
             baseline_rank: entry.baseline_rank,
             score: entry.score,
             contributions: entry.contributions,
         })),
+        candidate_count: report.ranked.length,
+        omitted_count: report.ranked.length - ranked.length,
         ...(featureStore
             ? {
                 feature_store: {
@@ -1659,7 +1664,11 @@ export async function runContext(options, global) {
     attachOptionalContextSections(result, sections, focusGroups.featureStore.warning_details);
     applyContextTagProjection(result, options.noTags === true);
     if (options.explainRanking === true) {
-        result.ranking = toContextRankingSummary(focusGroups.ranking, focusGroups.featureStore);
+        result.ranking = toContextRankingSummary(focusGroups.ranking, focusGroups.featureStore, new Set([
+            ...focusGroups.highLevel,
+            ...focusGroups.lowLevel,
+            ...focusGroups.blockedFallback,
+        ].map((entry) => entry.id)));
         result.packing = toContextPackingSummary(focusGroups.packing);
     }
     applyContextFocusProjection(result, runtime.focusFields);
@@ -1670,4 +1679,4 @@ export async function runContext(options, global) {
     return result;
 }
 //# sourceMappingURL=context.js.map
-//# debugId=757a0349-9fb6-579d-ab29-fabaad790ce4
+//# debugId=ee5279f2-7489-59fb-8f96-f2e035434cce

package/dist/sdk/read-output/continuation.d.ts

@@ -0,0 +1,11 @@
+import type { PmReadOutputCursorEnvelope, PmReadOutputSurface } from "../read-output-contracts.js";
+/** Fingerprint stable row identities without including volatile observation fields. */
+export declare function readOutputCollectionFingerprint(path: string, value: unknown[] | Record<string, unknown>): string;
+/** Encode one stable declared-row continuation for CLI, SDK, and MCP callers. */
+export declare function encodeReadOutputContinuationCursor(cursor: Omit<PmReadOutputCursorEnvelope, "version">): string;
+/** Decode and validate one universal declared-row continuation cursor. */
+export declare function decodeReadOutputContinuationCursor(raw: string): PmReadOutputCursorEnvelope;
+/** Place every non-passing assurance assertion before passing evidence. */
+export declare function prioritizeAssuranceAssertions(result: Record<string, unknown>): Record<string, unknown>;
+/** Validate and apply a continuation suffix to its declared row collection. */
+export declare function applyReadOutputContinuation(result: Record<string, unknown>, command: PmReadOutputSurface, cursor: PmReadOutputCursorEnvelope | undefined): Record<string, unknown>;