@unbrained/pm-cli 2026.9.2 → 2026.9.3

package/dist/sdk/context-signal-store.js

@@ -6,17 +6,19 @@
  * history, while stale, absent, or corrupt snapshots rebuild transparently.
  */
 
-!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]="3d0a558b-6a01-5bca-a2f7-21766be6d67c")}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]="9b112b71-e0b8-5502-89f6-b4da6eb85f6b")}catch(e){}}();
 import { isFileAbsentError } from "../core/fs/fs-utils.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { createHash, randomUUID } from "node:crypto";
 import { buildItemContextRelevanceCandidates, } from "./context-relevance.js";
 import { readItemMetadataDerivedIndexState } from "./item-metadata-index.js";
+import { readLatestSubstantiveHistoryEvents } from "../core/history/event-index.js";
+import { canonicalizeContextRecencyCoordinate } from "./context/recency.js";
 /** Current serialized feature-store envelope version. */
-export const CONTEXT_SIGNAL_STORE_FORMAT_VERSION = 1;
+export const CONTEXT_SIGNAL_STORE_FORMAT_VERSION = 3;
 /** Current canonical signal-vector version. */
-export const CONTEXT_SIGNAL_SET_VERSION = 1;
+export const CONTEXT_SIGNAL_SET_VERSION = 2;
 const STORED_CONTEXT_SIGNAL_NAMES = [
     "recency",
     "activity_density",
@@ -25,6 +27,11 @@ const STORED_CONTEXT_SIGNAL_NAMES = [
     "risk_pressure",
     "knowledge_density",
 ];
+const CONTEXT_RECENCY_SOURCES = new Set([
+    "substantive_history",
+    "release_cohort",
+    "created_at",
+]);
 /** Canonical actionable contracts shared by CLI, SDK, MCP, and package hosts. */
 export const CONTEXT_SIGNAL_STORE_WARNING_DETAILS = {
     context_signal_store_invalid: {
@@ -50,7 +57,10 @@ function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function isNormalizedSignal(value) {
-    return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1;
+    return (typeof value === "number" &&
+        Number.isFinite(value) &&
+        value >= 0 &&
+        value <= 1);
 }
 function compactSignals(signals) {
     const compact = {};
@@ -88,7 +98,10 @@ function deriveGraphProximity(items) {
         }
     }
     const maximum = Math.max(0, ...degree.values());
-    return Object.fromEntries(items.map((item) => [item.id, maximum === 0 ? 0 : degree.get(item.id) / maximum]));
+    return Object.fromEntries(items.map((item) => [
+        item.id,
+        maximum === 0 ? 0 : degree.get(item.id) / maximum,
+    ]));
 }
 function stableSnapshotOptions(items, options) {
     return {
@@ -101,19 +114,77 @@ function stableSnapshotOptions(items, options) {
         graphProximity: options.graphProximity ?? deriveGraphProximity(items),
     };
 }
+function recencyEvidenceFingerprint(candidates) {
+    const hash = createHash("sha256");
+    for (const { id, signal_provenance: { recency: evidence }, } of [...candidates].sort((left, right) => left.id.localeCompare(right.id))) {
+        hash.update(JSON.stringify([
+            id,
+            evidence.source,
+            evidence.coordinate,
+            evidence.history_op ?? null,
+            evidence.event_class ?? null,
+        ]));
+    }
+    return `sha256:${hash.digest("hex")}`;
+}
 function parseSnapshotItem(value) {
-    if (!isRecord(value) || typeof value.id !== "string" || !isRecord(value.signals)) {
+    if (!isRecord(value))
+        return null;
+    const signalProvenance = value.signal_provenance;
+    if (![
+        typeof value.id === "string",
+        isRecord(value.signals),
+        isRecord(signalProvenance),
+    ].every(Boolean))
+        return null;
+    const recency = signalProvenance.recency;
+    if (!isRecord(recency))
+        return null;
+    const coordinate = canonicalizeContextRecencyCoordinate(recency.coordinate);
+    if (coordinate === null)
         return null;
-    }
-    const signals = {};
     const supportedSignals = new Set(STORED_CONTEXT_SIGNAL_NAMES);
-    for (const [name, signal] of Object.entries(value.signals)) {
-        if (!supportedSignals.has(name) || !isNormalizedSignal(signal)) {
-            return null;
-        }
-        signals[name] = signal;
+    const signalEntries = Object.entries(value.signals);
+    if (!signalEntries.every(([name, signal]) => supportedSignals.has(name) && isNormalizedSignal(signal))) {
+        return null;
+    }
+    if (![
+        typeof recency.source === "string" &&
+            CONTEXT_RECENCY_SOURCES.has(recency.source),
+        ["undefined", "string"].includes(typeof recency.history_op),
+        [undefined, "substantive", "maintenance"].includes(recency.event_class),
+        recency.source === "substantive_history"
+            ? recency.event_class === undefined ||
+                recency.event_class === "substantive"
+            : recency.history_op === undefined && recency.event_class === undefined,
+    ].every(Boolean)) {
+        return null;
+    }
+    return {
+        id: value.id,
+        signals: Object.fromEntries(signalEntries),
+        signal_provenance: {
+            recency: {
+                source: recency.source,
+                coordinate,
+                history_op: recency.history_op,
+                event_class: recency.event_class,
+            },
+        },
+    };
+}
+function parseSnapshotItems(values, expectedRecencyEvidenceFingerprint) {
+    const items = Array.from(values, parseSnapshotItem);
+    if (items.some((item) => item === null))
+        return null;
+    const validItems = items;
+    if (new Set(validItems.map((item) => item.id)).size !== validItems.length ||
+        validItems.some((item) => item.id.trim().length === 0) ||
+        expectedRecencyEvidenceFingerprint !==
+            recencyEvidenceFingerprint(validItems)) {
+        return null;
     }
-    return { id: value.id, signals: signals };
+    return validItems.sort((left, right) => left.id.localeCompare(right.id));
 }
 /** Validate an untrusted serialized snapshot without accepting partial envelopes. */
 export function parseContextSignalSnapshot(value) {
@@ -122,56 +193,68 @@ export function parseContextSignalSnapshot(value) {
         value.signal_set_version !== CONTEXT_SIGNAL_SET_VERSION ||
         typeof value.source_cursor !== "string" ||
         value.source_cursor.trim().length === 0 ||
+        typeof value.recency_evidence_fingerprint !== "string" ||
+        !/^sha256:[a-f0-9]{64}$/u.test(value.recency_evidence_fingerprint) ||
         typeof value.generated_at !== "string" ||
         !Number.isFinite(Date.parse(value.generated_at)) ||
         (value.source !== "derived_index" && value.source !== "scan_fallback") ||
         !Array.isArray(value.items)) {
         return null;
     }
-    const items = value.items.map(parseSnapshotItem);
-    if (items.some((item) => item === null)) {
+    const items = parseSnapshotItems(value.items, value.recency_evidence_fingerprint);
+    if (items === null)
         return null;
-    }
-    const validItems = items;
-    if (new Set(validItems.map((item) => item.id)).size !== validItems.length ||
-        validItems.some((item) => item.id.trim().length === 0)) {
-        return null;
-    }
     return {
         format_version: CONTEXT_SIGNAL_STORE_FORMAT_VERSION,
         signal_set_version: CONTEXT_SIGNAL_SET_VERSION,
         source_cursor: value.source_cursor,
+        recency_evidence_fingerprint: value.recency_evidence_fingerprint,
         generated_at: value.generated_at,
         source: value.source,
-        items: validItems.sort((left, right) => left.id.localeCompare(right.id)),
+        items,
     };
 }
-/** Fold authoritative items into a deterministic, immutable signal snapshot. */
-export function buildContextSignalSnapshot(items, options) {
-    if (typeof options.sourceCursor !== "string" || options.sourceCursor.trim().length === 0) {
+function validateSnapshotOptions(options) {
+    if (typeof options.sourceCursor !== "string" ||
+        options.sourceCursor.trim().length === 0) {
         throw new TypeError("Context signal source cursor must be non-empty");
     }
     if (!Number.isFinite(Date.parse(options.now))) {
         throw new TypeError("Context signal snapshot clock must be a valid timestamp");
     }
-    if (options.source !== "derived_index" && options.source !== "scan_fallback") {
+    if (options.source !== "derived_index" &&
+        options.source !== "scan_fallback") {
         throw new TypeError("Context signal snapshot source must be derived_index or scan_fallback");
     }
-    const rows = buildItemContextRelevanceCandidates(items, stableSnapshotOptions(items, options))
-        .map(({ id, signals }) => ({
+}
+function snapshotFromCandidates(candidates, options, fingerprint = recencyEvidenceFingerprint(candidates)) {
+    const candidateIds = candidates.map(({ id }) => id);
+    if (new Set(candidateIds).size !== candidateIds.length ||
+        candidateIds.some((id) => id.trim().length === 0)) {
+        throw new TypeError("Context signal snapshot item IDs must be unique and non-empty");
+    }
+    const rows = candidates
+        .map(({ id, signals, signal_provenance }) => ({
         id,
         signals: compactSignals(signals),
+        signal_provenance,
     }))
         .sort((left, right) => left.id.localeCompare(right.id));
     return Object.freeze({
         format_version: CONTEXT_SIGNAL_STORE_FORMAT_VERSION,
         signal_set_version: CONTEXT_SIGNAL_SET_VERSION,
         source_cursor: options.sourceCursor,
+        recency_evidence_fingerprint: fingerprint,
         generated_at: options.now,
         source: options.source,
         items: Object.freeze(rows.map((row) => Object.freeze(row))),
     });
 }
+/** Fold authoritative items into a deterministic, immutable signal snapshot. */
+export function buildContextSignalSnapshot(items, options) {
+    validateSnapshotOptions(options);
+    return snapshotFromCandidates(buildItemContextRelevanceCandidates(items, stableSnapshotOptions(items, options)), options);
+}
 /** Filesystem adapter using same-directory atomic replacement. */
 export class JsonFileContextSignalStoreAdapter {
     filePath;
@@ -200,7 +283,10 @@ export class JsonFileContextSignalStoreAdapter {
         await fs.mkdir(directory, { recursive: true });
         const temporaryPath = path.join(directory, `.${path.basename(this.filePath)}.${randomUUID()}.tmp`);
         try {
-            await fs.writeFile(temporaryPath, `${JSON.stringify(snapshot)}\n`, { encoding: "utf8", flag: "wx" });
+            await fs.writeFile(temporaryPath, `${JSON.stringify(snapshot)}\n`, {
+                encoding: "utf8",
+                flag: "wx",
+            });
             await fs.rename(temporaryPath, this.filePath);
         }
         finally {
@@ -222,6 +308,7 @@ export class ContextSignalStore {
     }
     /** Read matching signals or rebuild them from authoritative items. */
     async readOrRebuild(items, options) {
+        validateSnapshotOptions(options);
         const warnings = [];
         let snapshot = null;
         try {
@@ -234,10 +321,15 @@ export class ContextSignalStore {
         catch {
             warnings.push("context_signal_store_invalid");
         }
-        const authoritativeIds = items.map((item) => item.id).sort((left, right) => left.localeCompare(right));
+        const authoritativeIds = items
+            .map((item) => item.id)
+            .sort((left, right) => left.localeCompare(right));
         const snapshotIds = snapshot?.items.map((item) => item.id) ?? [];
+        const authoritativeCandidates = buildItemContextRelevanceCandidates(items, stableSnapshotOptions(items, options));
+        const authoritativeFingerprint = recencyEvidenceFingerprint(authoritativeCandidates);
         const fresh = snapshot !== null &&
             snapshot.source_cursor === options.sourceCursor &&
+            snapshot.recency_evidence_fingerprint === authoritativeFingerprint &&
             snapshot.source === options.source &&
             snapshotIds.length === authoritativeIds.length &&
             snapshotIds.every((id, index) => id === authoritativeIds[index]);
@@ -249,7 +341,7 @@ export class ContextSignalStore {
             if (snapshot !== null) {
                 warnings.push("context_signal_store_stale");
             }
-            resolvedSnapshot = buildContextSignalSnapshot(items, options);
+            resolvedSnapshot = snapshotFromCandidates(authoritativeCandidates, options, authoritativeFingerprint);
             try {
                 await this.adapter.write(resolvedSnapshot);
             }
@@ -257,13 +349,16 @@ export class ContextSignalStore {
                 warnings.push("context_signal_store_write_failed");
             }
         }
-        const signalsById = new Map(resolvedSnapshot.items.map((item) => [item.id, item.signals]));
-        const dynamicCandidates = buildItemContextRelevanceCandidates(items, options);
+        const snapshotItemsById = new Map(resolvedSnapshot.items.map((item) => [item.id, item]));
         return {
             snapshot: resolvedSnapshot,
-            candidates: dynamicCandidates.map((candidate) => ({
+            candidates: authoritativeCandidates.map((candidate) => ({
                 ...candidate,
-                signals: { ...candidate.signals, ...signalsById.get(candidate.id) },
+                signals: {
+                    ...candidate.signals,
+                    ...snapshotItemsById.get(candidate.id)?.signals,
+                },
+                signal_provenance: snapshotItemsById.get(candidate.id).signal_provenance,
             })),
             cache_status: fresh ? "fresh" : "rebuilt",
             warnings,
@@ -304,11 +399,29 @@ export async function readWorkspaceContextSignals(items, options) {
     const indexState = hasSourceCursor
         ? null
         : await readItemMetadataDerivedIndexState(options.pmRoot);
-    const sourceCursor = options.sourceCursor ?? indexState?.source_cursor ?? fallbackWorkspaceCursor(items);
-    const source = options.source ??
-        (indexState === null ? "scan_fallback" : "derived_index");
-    const store = new ContextSignalStore(new JsonFileContextSignalStoreAdapter(path.join(options.pmRoot, "runtime", options.storeKey ? `context-signals-${options.storeKey}.json` : "context-signals.json")));
-    return store.readOrRebuild(items, { ...options, sourceCursor, source });
+    const sourceCursor = options.sourceCursor ??
+        indexState?.source_cursor ??
+        fallbackWorkspaceCursor(items);
+    const source = options.source ?? (indexState === null ? "scan_fallback" : "derived_index");
+    const store = new ContextSignalStore(new JsonFileContextSignalStoreAdapter(path.join(options.pmRoot, "runtime", options.storeKey
+        ? `context-signals-${options.storeKey}.json`
+        : "context-signals.json")));
+    const recencyEvidence = options.recencyEvidence ??
+        Object.fromEntries(Object.entries(await readLatestSubstantiveHistoryEvents(options.pmRoot, items.map((item) => item.id))).map(([id, event]) => [
+            id,
+            {
+                source: "substantive_history",
+                coordinate: event.entry.ts,
+                history_op: event.entry.op,
+                event_class: "substantive",
+            },
+        ]));
+    return store.readOrRebuild(items, {
+        ...options,
+        recencyEvidence,
+        sourceCursor,
+        source,
+    });
 }
 //# sourceMappingURL=context-signal-store.js.map
-//# debugId=3d0a558b-6a01-5bca-a2f7-21766be6d67c
+//# debugId=9b112b71-e0b8-5502-89f6-b4da6eb85f6b

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

@@ -8,14 +8,40 @@ export interface ContextUsageServingRow {
     /** Whether the packer included the item. */
     included: boolean;
 }
+/** Correlation receipt joining a pre-egress serve to its final delivery. */
+export interface ContextUsageServingReceipt {
+    /** Versioned immutable serve identifier. */
+    serve_id: string;
+    /** Caller whose feedback model owns the event. */
+    author: string;
+    /** Read surface that assembled the candidates. */
+    surface: ContextRelevanceSurface;
+    /** Propensity-complete ranked rows assembled before egress. */
+    rows: readonly ContextUsageServingRow[];
+}
 /** Append-only serving or subsequent-touch event. */
 export type ContextUsageEvent = {
     kind: "serve";
+    schema_version?: 2;
+    serve_id?: string;
     at: string;
     author: string;
     surface: ContextRelevanceSurface;
     profile: string;
     rows: ContextUsageServingRow[];
+    result_omitted?: boolean;
+    packed_item_ids?: string[];
+    /** Legacy pre-egress field ignored by the v2 affinity fold. */
+    delivered_item_ids?: string[];
+} | {
+    kind: "delivery";
+    schema_version: 2;
+    serve_id: string;
+    at: string;
+    author: string;
+    surface: ContextRelevanceSurface;
+    result_omitted: boolean;
+    delivered_item_ids: string[];
 } | {
     kind: "touch";
     at: string;
@@ -44,7 +70,26 @@ export interface ContextUsageAffinity {
     positive_judgments: number;
     /** Number of retained serving events inspected. */
     serving_events: number;
+    /** Legacy serving events ignored because their inclusion cannot be trusted. */
+    untrusted_serving_events: number;
 }
+/** Attach a JSON-invisible serving receipt to a result for later egress. */
+export declare function attachContextUsageServingReceipt(result: unknown, receipt: ContextUsageServingReceipt | null): void;
+/** Copy an attached serving receipt across a result projection boundary. */
+export declare function propagateContextUsageServingReceipt(source: unknown, target: unknown): void;
+/**
+ * Collect every item identifier visible in a final context or next result.
+ * The traversal is shape-aware so summary counters and unrelated identifier
+ * fields cannot enter the privacy-minimal usage ledger.
+ */
+export declare function collectContextUsageDeliveredItemIds(result: unknown, surface: ContextRelevanceSurface): string[];
+/** Resolve and append one post-egress decision carried by a context result. */
+export declare function finalizeContextUsageDelivery(options: {
+    /** Tracker root owning the derived ledger. */
+    pmRoot: string;
+    /** Final projected response returned or rendered to the caller. */
+    result: unknown;
+}): Promise<boolean>;
 /** Named validation failure emitted by context-usage SDK inputs. */
 export declare class ContextUsageValidationError extends TypeError {
     /** Stable machine-readable error code for package and CLI hosts. */
@@ -58,6 +103,15 @@ export declare function recordContextUsageServing(options: ContextUsageLedgerOpt
     surface: ContextRelevanceSurface;
     profile: string;
     rows: ContextUsageServingRow[];
+}): Promise<ContextUsageServingReceipt | null>;
+/** Append the exact post-egress delivery decision for one serving receipt. */
+export declare function recordContextUsageDelivery(options: ContextUsageLedgerOptions & {
+    /** Correlation receipt returned by {@link recordContextUsageServing}. */
+    receipt: ContextUsageServingReceipt | null;
+    /** Item ids present in the final response payload. */
+    deliveredItemIds: readonly string[];
+    /** Whether the result was suppressed by the final output budget. */
+    resultOmitted: boolean;
 }): Promise<void>;
 /** Records one subsequent item read or mutation outcome. */
 export declare function recordContextUsageTouch(options: ContextUsageLedgerOptions & {