@unbrained/pm-cli 2026.9.2 → 2026.9.3

package/dist/core/store/item-metadata-query-index.js

@@ -4,7 +4,7 @@
  * Maintains a rebuildable SQLite projection for bounded metadata queries.
  */
 
-!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]="e94075b0-810d-506c-b6a2-ae322526c078")}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]="97cfeab2-8e3f-5b70-9f64-10494158d141")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
@@ -185,13 +185,13 @@ function readIndexMetadata(database) {
  * callers can remove and lazily rebuild this optional projection.
  */
 export async function updateItemMetadataQueryIndex(options) {
+    const Database = resolveDatabaseSync();
+    if (!Database)
+        return false;
     const indexPath = queryIndexPath(options.pmRoot);
     let database;
     try {
         await fs.access(indexPath);
-        const Database = resolveDatabaseSync();
-        if (!Database)
-            return false;
         database = new Database(indexPath);
         database.exec("PRAGMA foreign_keys = ON");
         const metadata = readIndexMetadata(database);
@@ -470,4 +470,4 @@ export const _testOnly = {
     },
 };
 //# sourceMappingURL=item-metadata-query-index.js.map
-//# debugId=e94075b0-810d-506c-b6a2-ae322526c078
+//# debugId=97cfeab2-8e3f-5b70-9f64-10494158d141

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

@@ -0,0 +1,9 @@
+/** Deterministic oldest coordinate used when legacy creation metadata is invalid. */
+export declare const CONTEXT_RECENCY_EPOCH = "1970-01-01T00:00:00.000Z";
+/**
+ * Canonicalize a calendar-valid RFC 3339 instant or dashed legacy date-only
+ * value. Compact dates, sub-millisecond instants, and host-local date-times are
+ * rejected because they cannot round-trip through the strict timestamp contract
+ * losslessly and deterministically.
+ */
+export declare function canonicalizeContextRecencyCoordinate(value: unknown): string | null;

package/dist/sdk/context/recency.js

@@ -0,0 +1,34 @@
+/**
+ * @module sdk/context/recency
+ *
+ * Canonicalizes the absolute timestamps used as durable context-recency
+ * coordinates without accepting relative or host-local date-time values.
+ */
+
+!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]="377499d7-13b3-55f0-9d44-425bfcaf7964")}catch(e){}}();
+import { isMillisecondPrecisionRfc3339DateTime, resolveIsoOrRelative, } from "../../core/shared/time.js";
+/** Deterministic oldest coordinate used when legacy creation metadata is invalid. */
+export const CONTEXT_RECENCY_EPOCH = "1970-01-01T00:00:00.000Z";
+/**
+ * Canonicalize a calendar-valid RFC 3339 instant or dashed legacy date-only
+ * value. Compact dates, sub-millisecond instants, and host-local date-times are
+ * rejected because they cannot round-trip through the strict timestamp contract
+ * losslessly and deterministically.
+ */
+export function canonicalizeContextRecencyCoordinate(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    if (!isMillisecondPrecisionRfc3339DateTime(trimmed) &&
+        !/^\d{4}-\d{2}-\d{2}$/u.test(trimmed)) {
+        return null;
+    }
+    try {
+        return resolveIsoOrRelative(trimmed, new Date(Number.NaN), "context signal recency coordinate");
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=recency.js.map
+//# debugId=377499d7-13b3-55f0-9d44-425bfcaf7964

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

@@ -0,0 +1,9 @@
+/**
+ * @module sdk/context/usage-egress
+ *
+ * Keeps post-projection context feedback best-effort without weakening the
+ * response contract returned by embedded SDK and MCP hosts.
+ */
+import { finalizeContextUsageDelivery } from "../context-usage.js";
+/** Finalize derived usage feedback and attach a stable warning on failure. */
+export declare function finalizeContextUsageEgress(pmRoot: string, projected: unknown, finalize?: typeof finalizeContextUsageDelivery): Promise<void>;

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

@@ -0,0 +1,30 @@
+/**
+ * @module sdk/context/usage-egress
+ *
+ * Keeps post-projection context feedback best-effort without weakening the
+ * response contract returned by embedded SDK and MCP hosts.
+ */
+
+!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]="c5a14f99-ce5b-5da7-8b17-6b6a56f0644a")}catch(e){}}();
+import { finalizeContextUsageDelivery } from "../context-usage.js";
+/** Finalize derived usage feedback and attach a stable warning on failure. */
+export async function finalizeContextUsageEgress(pmRoot, projected, finalize = finalizeContextUsageDelivery) {
+    try {
+        await finalize({ pmRoot, result: projected });
+    }
+    catch {
+        if (typeof projected === "object" &&
+            projected !== null &&
+            !Array.isArray(projected)) {
+            const record = projected;
+            const warnings = Array.isArray(record.warnings)
+                ? record.warnings.filter((warning) => typeof warning === "string")
+                : [];
+            record.warnings = [
+                ...new Set([...warnings, "context_usage_feedback_write_failed"]),
+            ].sort();
+        }
+    }
+}
+//# sourceMappingURL=usage-egress.js.map
+//# debugId=c5a14f99-ce5b-5da7-8b17-6b6a56f0644a

package/dist/sdk/context-intent-contracts.js

@@ -5,12 +5,13 @@
  * workspace configuration, and packages.
  */
 
-!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]="da15ca02-02cc-5886-8c82-610939b8581c")}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]="5dc9c6e4-6db8-560f-a87f-368132e2ffb3")}catch(e){}}();
 import { AsyncLocalStorage } from "node:async_hooks";
 import { renderPmCommand } from "./command-line.js";
 import { attachOutputOmissionReceipt } from "./output-projection.js";
 import { encodeQueryCursor } from "./pagination.js";
 import { applyReadOutputDimensions, stabilizeReadOutputReceiptEstimates, } from "./read-output-contracts.js";
+import { propagateContextUsageServingReceipt } from "./context-usage.js";
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 /** Built-in intent projections shared by CLI, SDK, MCP, and package authors. */
@@ -692,6 +693,7 @@ export function attachReadOutputContracts(command, options, result) {
         !Array.isArray(disclosedResult)
         ? applyReadOutputDimensions(command ?? "", options, collapseContinuationMetadata(options, attachContextIntentReceipt(command ?? "", options, disclosedResult)))
         : disclosedResult;
+    propagateContextUsageServingReceipt(result, projected);
     if (options.outputRowContract === true ||
         options.output_row_contract === true ||
         typeof projected !== "object" ||
@@ -700,7 +702,9 @@ export function attachReadOutputContracts(command, options, result) {
         !Object.hasOwn(projected, "row_contract")) {
         return projected;
     }
-    return stabilizeSuppressedRowContractReceipts(Object.fromEntries(Object.entries(projected).filter(([key]) => key !== "row_contract")), options);
+    const suppressed = stabilizeSuppressedRowContractReceipts(Object.fromEntries(Object.entries(projected).filter(([key]) => key !== "row_contract")), options);
+    propagateContextUsageServingReceipt(projected, suppressed);
+    return suppressed;
 }
 //# sourceMappingURL=context-intent-contracts.js.map
-//# debugId=da15ca02-02cc-5886-8c82-610939b8581c
+//# debugId=5dc9c6e4-6db8-560f-a87f-368132e2ffb3

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

@@ -1,11 +1,28 @@
 import type { RuntimeStatusRegistry } from "../core/schema/runtime-schema.js";
 import type { ItemMetadata } from "../types/index.js";
+import type { HistoryEventClass } from "../core/history/event-classification.js";
 /** Canonical signal keys understood by the built-in relevance model. */
 export declare const CONTEXT_RELEVANCE_SIGNAL_NAMES: readonly ["structural", "recency", "activity_density", "graph_proximity", "claim_focus", "priority_pressure", "risk_pressure", "deadline_pressure", "knowledge_density", "author_affinity", "usage_affinity", "semantic_similarity"];
 /** A normalized signal consumed by the built-in context relevance scorer. */
 export type ContextRelevanceSignalName = (typeof CONTEXT_RELEVANCE_SIGNAL_NAMES)[number];
 /** Normalized candidate features; omitted signals are excluded from weighting. */
 export type ContextRelevanceSignals = Partial<Record<Exclude<ContextRelevanceSignalName, "structural">, number>>;
+/** Authoritative coordinate and fallback that produced an item's recency. */
+export interface ContextRecencyEvidence {
+    /** Source selected by the canonical fallback ladder. */
+    source: "substantive_history" | "release_cohort" | "created_at";
+    /** ISO coordinate used for deterministic recency ordering. */
+    coordinate: string;
+    /** Immutable operation selected from history when source is substantive_history. */
+    history_op?: string;
+    /** Declared class selected from history when source is substantive_history. */
+    event_class?: HistoryEventClass;
+}
+/** Per-signal provenance exposed by explained relevance results. */
+export interface ContextSignalProvenance {
+    /** Evidence for the canonical temporal component. */
+    recency: ContextRecencyEvidence;
+}
 /** A project-management object and its derived relevance signals. */
 export interface ContextRelevanceCandidate<TItem> {
     /** Stable identifier used to reference this record across commands and storage. */
@@ -14,11 +31,15 @@ export interface ContextRelevanceCandidate<TItem> {
     item: TItem;
     /** Value that configures or reports signals for this contract. */
     signals?: ContextRelevanceSignals;
+    /** Authoritative source details for explainable derived signals. */
+    signal_provenance?: ContextSignalProvenance;
 }
 /** Item candidate whose built-in metadata derivation always supplies signals. */
 export interface ItemContextRelevanceCandidate extends ContextRelevanceCandidate<ItemMetadata> {
     /** Complete built-in derivation result, with unavailable signals omitted by value. */
     signals: ContextRelevanceSignals;
+    /** Built-in recency derivation always discloses its source. */
+    signal_provenance: ContextSignalProvenance;
 }
 /** Inputs that make item-signal derivation deterministic and host-configurable. */
 export interface BuildItemContextRelevanceCandidatesOptions {
@@ -42,6 +63,8 @@ export interface BuildItemContextRelevanceCandidatesOptions {
     knowledgeDensity?: Readonly<Record<string, number>>;
     /** Optional history-derived author affinity by item id. */
     authorAffinity?: Readonly<Record<string, number>>;
+    /** Latest substantive history evidence keyed by item id. */
+    recencyEvidence?: Readonly<Record<string, ContextRecencyEvidence>>;
 }
 /**
  * Derive the canonical metadata signals consumed by `pm context` and `pm next`.

package/dist/sdk/context-relevance.js

@@ -6,10 +6,11 @@
  * with core, extension, or project-specific feature stores.
  */
 
-!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]="7eefe5f0-364d-559a-b365-0e7d539ee19e")}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]="80a03884-711e-5170-a3c1-f05ccb065702")}catch(e){}}();
 import { runActiveServiceOverride } from "../core/extensions/index.js";
 import { normalizeStatusForRegistry, normalizeStatusInput, } from "../core/item/status.js";
-import { compareTimestampStrings, resolveIsoOrRelative } from "../core/shared/time.js";
+import { compareTimestampStrings } from "../core/shared/time.js";
+import { canonicalizeContextRecencyCoordinate, CONTEXT_RECENCY_EPOCH, } from "./context/recency.js";
 /** Canonical signal keys understood by the built-in relevance model. */
 export const CONTEXT_RELEVANCE_SIGNAL_NAMES = [
     "structural",
@@ -33,12 +34,67 @@ function normalizeContextActor(value, missingValue) {
     const normalized = value.trim().toLowerCase();
     return normalized.length > 0 ? normalized : missingValue;
 }
+function releaseCohortCoordinate(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const match = /^v?(\d{4})\.(\d{1,2})\.(\d{1,2})(?:$|[-+])/u.exec(value.trim());
+    if (!match)
+        return undefined;
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    const date = new Date(Date.UTC(year, month - 1, day));
+    return date.getUTCFullYear() === year &&
+        date.getUTCMonth() === month - 1 &&
+        date.getUTCDate() === day
+        ? date.toISOString()
+        : undefined;
+}
+function fallbackRecencyEvidence(item) {
+    const releaseCoordinate = releaseCohortCoordinate(item.release);
+    if (releaseCoordinate !== undefined) {
+        return { source: "release_cohort", coordinate: releaseCoordinate };
+    }
+    return {
+        source: "created_at",
+        coordinate: canonicalizeContextRecencyCoordinate(item.created_at) ??
+            CONTEXT_RECENCY_EPOCH,
+    };
+}
+function canonicalizeRecencyEvidence(evidence) {
+    if (!["substantive_history", "release_cohort", "created_at"].includes(evidence.source) ||
+        (evidence.source === "substantive_history"
+            ? (evidence.history_op !== undefined &&
+                typeof evidence.history_op !== "string") ||
+                (evidence.event_class !== undefined &&
+                    evidence.event_class !== "substantive")
+            : evidence.history_op !== undefined || evidence.event_class !== undefined)) {
+        throw new TypeError("Context signal recency provenance must match its source");
+    }
+    const coordinate = canonicalizeContextRecencyCoordinate(evidence.coordinate);
+    if (coordinate === null) {
+        throw new TypeError("Context signal recency coordinate must be a valid absolute timestamp with millisecond precision");
+    }
+    return { ...evidence, coordinate };
+}
 function normalizedPressure(value, maximum) {
-    const parsed = typeof value === "number" ? value : typeof value === "string" ? Number.parseFloat(value) : Number.NaN;
-    return Number.isFinite(parsed) ? 1 - Math.min(Math.max(parsed, 0), maximum) / maximum : 0;
+    const parsed = typeof value === "number"
+        ? value
+        : typeof value === "string"
+            ? Number.parseFloat(value)
+            : Number.NaN;
+    return Number.isFinite(parsed)
+        ? 1 - Math.min(Math.max(parsed, 0), maximum) / maximum
+        : 0;
 }
 function deadlinePressure(deadline, nowMs) {
-    const deadlineMs = typeof deadline === "string" ? Date.parse(deadline) : deadline instanceof Date ? deadline.getTime() : typeof deadline === "number" ? deadline : Number.NaN;
+    const deadlineMs = typeof deadline === "string"
+        ? Date.parse(deadline)
+        : deadline instanceof Date
+            ? deadline.getTime()
+            : typeof deadline === "number"
+                ? deadline
+                : Number.NaN;
     if (!Number.isFinite(deadlineMs) || !Number.isFinite(nowMs))
         return 0;
     const days = (deadlineMs - nowMs) / 86_400_000;
@@ -61,20 +117,22 @@ function derivedSignalOrFallback(values, id, fallback) {
  * to reproduce built-in ranking without private imports or subprocesses.
  */
 export function buildItemContextRelevanceCandidates(items, options) {
-    const sortableTimestamp = (value) => {
-        if (typeof value !== "string")
-            return "";
-        try {
-            return resolveIsoOrRelative(value, new Date(Number.NaN), "updated_at");
-        }
-        catch {
-            return "";
-        }
-    };
+    const recencyEvidence = new Map(items.map((item) => {
+        const suppliedEvidence = options.recencyEvidence?.[item.id];
+        return [
+            item.id,
+            suppliedEvidence === undefined
+                ? fallbackRecencyEvidence(item)
+                : canonicalizeRecencyEvidence(suppliedEvidence),
+        ];
+    }));
     const recencyOrder = [...items].sort((left, right) => {
-        const leftTime = sortableTimestamp(left.updated_at);
-        const rightTime = sortableTimestamp(right.updated_at);
-        return compareTimestampStrings(rightTime, leftTime) || left.id.localeCompare(right.id);
+        const leftTime = recencyEvidence.get(left.id)
+            .coordinate;
+        const rightTime = recencyEvidence.get(right.id)
+            .coordinate;
+        return (compareTimestampStrings(rightTime, leftTime) ||
+            left.id.localeCompare(right.id));
     });
     const recencyRank = new Map(recencyOrder.map((item, index) => [item.id, index]));
     const denominator = Math.max(items.length - 1, 1);
@@ -82,16 +140,29 @@ export function buildItemContextRelevanceCandidates(items, options) {
     const inProgressStatus = normalizeStatusInput("in_progress", options.statusRegistry);
     const nowMs = Date.parse(options.now);
     return items.map((item) => {
-        const assigned = normalizeContextActor(item.assignee, NO_ITEM_ASSIGNEE) === normalizedAuthor;
-        const knowledgeEntries = (item.comments?.length ?? 0) + (item.notes?.length ?? 0) + (item.learnings?.length ?? 0);
+        const assigned = normalizeContextActor(item.assignee, NO_ITEM_ASSIGNEE) ===
+            normalizedAuthor;
+        const knowledgeEntries = (item.comments?.length ?? 0) +
+            (item.notes?.length ?? 0) +
+            (item.learnings?.length ?? 0);
         return {
             id: item.id,
             item,
+            signal_provenance: {
+                recency: recencyEvidence.get(item.id),
+            },
             signals: {
-                recency: items.length === 1 ? 1 : 1 - recencyRank.get(item.id) / denominator,
+                recency: items.length === 1
+                    ? 1
+                    : 1 - recencyRank.get(item.id) / denominator,
                 activity_density: options.activityDensity?.[item.id],
                 graph_proximity: derivedSignalOrFallback(options.graphProximity, item.id, item.parent ? 0.3 : 0),
-                claim_focus: derivedSignalOrFallback(options.claimFocus, item.id, normalizeStatusForRegistry(item.status, options.statusRegistry) === inProgressStatus ? 1 : assigned ? 0.75 : 0),
+                claim_focus: derivedSignalOrFallback(options.claimFocus, item.id, normalizeStatusForRegistry(item.status, options.statusRegistry) ===
+                    inProgressStatus
+                    ? 1
+                    : assigned
+                        ? 0.75
+                        : 0),
                 priority_pressure: normalizedPressure(item.priority, 4),
                 risk_pressure: riskPressure(item.risk),
                 deadline_pressure: deadlinePressure(item.deadline, nowMs),
@@ -430,4 +501,4 @@ export async function runContextEvaluationCorpus(scenarios, reader, thresholds)
     return summarizeContextEvaluationReports(reports, thresholds);
 }
 //# sourceMappingURL=context-relevance.js.map
-//# debugId=7eefe5f0-364d-559a-b365-0e7d539ee19e
+//# debugId=80a03884-711e-5170-a3c1-f05ccb065702

package/dist/sdk/context-signal-store.d.ts

@@ -1,9 +1,9 @@
-import { type BuildItemContextRelevanceCandidatesOptions, type ContextRelevanceCandidate, type ContextRelevanceSignals } from "./context-relevance.js";
+import { type BuildItemContextRelevanceCandidatesOptions, type ContextRelevanceCandidate, type ContextRelevanceSignals, type ContextSignalProvenance } from "./context-relevance.js";
 import type { ItemMetadata } from "../types/index.js";
 /** Current serialized feature-store envelope version. */
-export declare const CONTEXT_SIGNAL_STORE_FORMAT_VERSION = 1;
+export declare const CONTEXT_SIGNAL_STORE_FORMAT_VERSION = 3;
 /** Current canonical signal-vector version. */
-export declare const CONTEXT_SIGNAL_SET_VERSION = 1;
+export declare const CONTEXT_SIGNAL_SET_VERSION = 2;
 /** Authoritative substrate used to derive one snapshot. */
 export type ContextSignalSnapshotSource = "derived_index" | "scan_fallback";
 /** One immutable item signal row. */
@@ -12,6 +12,8 @@ export interface ContextSignalSnapshotItem {
     id: string;
     /** Canonical normalized signal vector. */
     signals: ContextRelevanceSignals;
+    /** Authoritative temporal source retained for explained ranking. */
+    signal_provenance: ContextSignalProvenance;
 }
 /** Rebuildable, deterministic context-signal snapshot. */
 export interface ContextSignalSnapshot {
@@ -21,6 +23,8 @@ export interface ContextSignalSnapshot {
     signal_set_version: number;
     /** Authoritative history or derived-index cursor folded into this snapshot. */
     source_cursor: string;
+    /** Deterministic digest of substantive recency provenance used by the fold. */
+    recency_evidence_fingerprint: string;
     /** Stable clock supplied by the caller. */
     generated_at: string;
     /** Read substrate used for the fold. */