@unbrained/pm-cli 2026.8.14 → 2026.8.15

package/dist/sdk/governance/provenance-health.d.ts

@@ -1,3 +1,4 @@
+import type { HistoryEntry } from "../../types/index.js";
 /** Aggregated resolver attempts for one harness provenance dimension. */
 export interface ProvenanceResolverHealthOutcome {
     /** Detected harness namespace. */
@@ -35,5 +36,31 @@ export interface ProvenanceResolverHealthScan {
     /** Whether an event or byte ceiling omitted history input. */
     truncated: boolean;
 }
+/** Privacy-safe receipt for an explicit provenance normalization pass. */
+export interface ProvenanceNormalizationReceipt {
+    /** Whether at least one immutable event required normalization. */
+    changed: boolean;
+    /** Immutable events whose invalid provenance observations were removed. */
+    events_changed: number;
+    /** Total invalid observations removed without retaining their values. */
+    observations_removed: number;
+    /** Aggregate invalid-value classes removed by the pass. */
+    invalid_values: ProvenanceValueHealthFinding[];
+}
+/** Normalized entries plus the privacy-safe mutation receipt. */
+export interface ProvenanceNormalizationResult {
+    /** History entries with invalid bounded observations removed. */
+    entries: HistoryEntry[];
+    /** Aggregate mutation receipt; never includes an observed value. */
+    receipt: ProvenanceNormalizationReceipt;
+}
+/**
+ * Remove only provenance observations whose values violate the bounded domain.
+ * History operations, patches, timestamps, authors, and hashes are retained;
+ * the receipt exposes aggregate classes and counts but never the removed value.
+ */
+export declare function normalizeInvalidHistoryProvenance(entries: HistoryEntry[]): ProvenanceNormalizationResult;
+/** Find every history stream requiring provenance normalization without returning raw values. */
+export declare function listInvalidProvenanceHistoryStreamIds(pmRoot: string): Promise<string[]>;
 /** Scan immutable history without failing over malformed streams owned by integrity checks. */
 export declare function scanProvenanceResolverHealth(pmRoot: string, eventLimit?: number): Promise<ProvenanceResolverHealthScan>;

package/dist/sdk/governance/provenance-health.js

@@ -4,7 +4,7 @@
  * Reads bounded, privacy-safe provenance resolver outcomes for health checks.
  */
 
-!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]="60154e1b-8348-5b6b-badf-e76bba43bef8")}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]="6efed404-acd2-5c3a-a008-856df67c8b77")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 const DEFAULT_PROVENANCE_HISTORY_BYTE_LIMIT = 8_388_608;
@@ -27,6 +27,98 @@ const INVALID_PROVENANCE_VALUE_CLASSIFIERS = [
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function invalidProvenanceValueKind(value) {
+    return INVALID_PROVENANCE_VALUE_CLASSIFIERS.find((classifier) => classifier.matches(value))?.kind;
+}
+/**
+ * Remove only provenance observations whose values violate the bounded domain.
+ * History operations, patches, timestamps, authors, and hashes are retained;
+ * the receipt exposes aggregate classes and counts but never the removed value.
+ */
+export function normalizeInvalidHistoryProvenance(entries) {
+    const invalidValues = new Map();
+    let eventsChanged = 0;
+    let observationsRemoved = 0;
+    const normalized = entries.map((entry) => {
+        const provenance = isRecord(entry.agent_provenance)
+            ? entry.agent_provenance
+            : undefined;
+        if (provenance === undefined)
+            return entry;
+        const retained = {};
+        let eventChanged = false;
+        for (const [dimension, observation] of Object.entries(provenance)) {
+            const kind = isRecord(observation)
+                ? invalidProvenanceValueKind(observation.value)
+                : undefined;
+            if (kind === undefined) {
+                retained[dimension] = observation;
+                continue;
+            }
+            eventChanged = true;
+            observationsRemoved += 1;
+            const harness = entry.agent_harness ?? "unknown";
+            const key = `${harness}\0${dimension}\0${kind}`;
+            const aggregate = invalidValues.get(key) ?? {
+                harness,
+                dimension,
+                kind,
+                count: 0,
+            };
+            aggregate.count += 1;
+            invalidValues.set(key, aggregate);
+        }
+        if (!eventChanged)
+            return entry;
+        eventsChanged += 1;
+        const next = { ...entry };
+        if (Object.keys(retained).length === 0) {
+            delete next.agent_provenance;
+        }
+        else {
+            next.agent_provenance = retained;
+        }
+        return next;
+    });
+    return {
+        entries: normalized,
+        receipt: {
+            changed: eventsChanged > 0,
+            events_changed: eventsChanged,
+            observations_removed: observationsRemoved,
+            invalid_values: [...invalidValues.values()].sort((left, right) => left.harness.localeCompare(right.harness) ||
+                left.dimension.localeCompare(right.dimension) ||
+                left.kind.localeCompare(right.kind)),
+        },
+    };
+}
+/** Find every history stream requiring provenance normalization without returning raw values. */
+export async function listInvalidProvenanceHistoryStreamIds(pmRoot) {
+    const ids = [];
+    for (const file of await listHistoryFiles(pmRoot)) {
+        try {
+            const content = await fs.readFile(path.join(pmRoot, "history", file), "utf8");
+            for (const line of content.split("\n")) {
+                if (line.trim().length === 0)
+                    continue;
+                const entry = parseHistoryEntry(line);
+                if (entry === null || !isRecord(entry.agent_provenance))
+                    continue;
+                const invalid = Object.values(entry.agent_provenance).some((observation) => isRecord(observation) &&
+                    invalidProvenanceValueKind(observation.value) !== undefined);
+                if (invalid) {
+                    ids.push(file.slice(0, -".jsonl".length));
+                    break;
+                }
+            }
+        }
+        catch {
+            // Integrity diagnostics own unreadable or malformed streams. This census
+            // only selects safely parseable streams for the explicit normalizer.
+        }
+    }
+    return ids;
+}
 async function listHistoryFiles(pmRoot) {
     try {
         return (await fs.readdir(path.join(pmRoot, "history")))
@@ -84,7 +176,7 @@ function collectResolverOutcomes(entry, aggregates, invalidValues) {
     Object.entries(provenance).forEach(([dimension, observation]) => {
         if (!isRecord(observation))
             return;
-        const kind = INVALID_PROVENANCE_VALUE_CLASSIFIERS.find((classifier) => classifier.matches(observation.value))?.kind;
+        const kind = invalidProvenanceValueKind(observation.value);
         if (!kind)
             return;
         const key = `${harness}\0${dimension}\0${kind}`;
@@ -182,4 +274,4 @@ export async function scanProvenanceResolverHealth(pmRoot, eventLimit = 10_000)
     };
 }
 //# sourceMappingURL=provenance-health.js.map
-//# debugId=60154e1b-8348-5b6b-badf-e76bba43bef8
+//# debugId=6efed404-acd2-5c3a-a008-856df67c8b77

package/dist/sdk/governance/validate.js

@@ -4,7 +4,7 @@
  * Implements the pm validate 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]="7b47a375-e72c-5108-bd93-75dd8cf93218")}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]="b8c4707f-5445-5079-96e5-dc0dbd649b34")}catch(e){}}();
 import fs from "node:fs/promises";
 import { realpathSync } from "node:fs";
 import { execFile } from "node:child_process";
@@ -778,9 +778,7 @@ function buildMetadataCounts(metadataPolicy, missingByField) {
         const missing = missingByField[field];
         const value = missing ? missing.length : 0;
         const countKey = METADATA_COUNT_KEY_BY_FIELD[field];
-        if (value > 0 && countKey) {
-            counts[countKey] = value;
-        }
+        counts[countKey] = value;
     }
     return counts;
 }
@@ -858,9 +856,10 @@ function buildMetadataCheck(items, metadataPolicy, statusRegistry, verboseDiagno
     const duplicateIssueCodes = findDuplicateIssueCodes(items);
     const duplicateIssueCodeSummary = summarizeDuplicateIssueCodes(duplicateIssueCodes, verboseDiagnostics);
     const warningTokens = buildMetadataWarningTokens(metadataPolicy, missingByField, duplicateIssueCodeSummary.warnings);
-    // Zero-suppress counts to reduce agent token cost (telemetry pm-tylj).
-    // Only emit counts for the ACTIVE required fields of the resolved profile so a
-    // looser profile (e.g. core) never reports missing reviewer/risk/sprint/etc.
+    // Emit an explicit numeric predicate for every ACTIVE required field. Stable
+    // zeroes let assurance consumers distinguish a passing metric from an absent
+    // contract key without exposing any per-item diagnostic rows.
+    // A looser profile (e.g. core) still never reports reviewer/risk/sprint/etc.
     // Defensive guards (Gemini high #1, PR #78 follow-up): a future settings
     // shape could include an unsupported field in required_fields — fall back
     // to 0 instead of throwing TypeError, and skip writing when the count-key
@@ -2314,4 +2313,4 @@ export async function runValidate(options, global, services = {}) {
 }
 /* c8 ignore stop */
 //# sourceMappingURL=validate.js.map
-//# debugId=7b47a375-e72c-5108-bd93-75dd8cf93218
+//# debugId=b8c4707f-5445-5079-96e5-dc0dbd649b34

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/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[]>;