@unbrained/pm-cli 2026.9.6 → 2026.9.8

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

@@ -1,427 +1,3 @@
-/**
- * @module sdk/context-signal-store
- *
- * Rebuildable, cursor-stamped feature-store primitives for context relevance.
- * Snapshots are derived read artifacts: callers retain authoritative items and
- * 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]="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 = 3;
-/** Current canonical signal-vector version. */
-export const CONTEXT_SIGNAL_SET_VERSION = 2;
-const STORED_CONTEXT_SIGNAL_NAMES = [
-    "recency",
-    "activity_density",
-    "graph_proximity",
-    "priority_pressure",
-    "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: {
-        code: "context_signal_store_invalid",
-        meaning: "The persisted context-signal snapshot was unreadable or invalid and was rebuilt from authoritative items.",
-        recovery_command: "pm context",
-        recovery_effect: "Re-read context and confirm the rebuilt snapshot can be loaded without the warning.",
-    },
-    context_signal_store_stale: {
-        code: "context_signal_store_stale",
-        meaning: "The persisted context-signal snapshot did not match the authoritative cursor or item corpus and was rebuilt.",
-        recovery_command: "pm context",
-        recovery_effect: "Re-read context and confirm the rebuilt snapshot is now fresh.",
-    },
-    context_signal_store_write_failed: {
-        code: "context_signal_store_write_failed",
-        meaning: "Context signals were rebuilt in memory, but the derived snapshot could not be persisted.",
-        recovery_command: "pm context",
-        recovery_effect: "Retry the derived snapshot write and confirm the warning clears after storage access is restored.",
-    },
-};
-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);
-}
-function compactSignals(signals) {
-    const compact = {};
-    for (const name of STORED_CONTEXT_SIGNAL_NAMES) {
-        const value = signals[name];
-        if (value === undefined)
-            continue;
-        if (!isNormalizedSignal(value)) {
-            throw new TypeError(`Context relevance signal ${name} must be a finite number from 0 to 1`);
-        }
-        compact[name] = value;
-    }
-    return compact;
-}
-function normalizedCountsById(items, count) {
-    const counts = items.map((item) => [item.id, count(item)]);
-    const maximum = Math.max(0, ...counts.map(([, value]) => value));
-    return Object.fromEntries(counts.map(([id, value]) => [id, maximum === 0 ? 0 : value / maximum]));
-}
-function deriveGraphProximity(items) {
-    const degree = new Map(items.map((item) => [item.id, 0]));
-    const increment = (id) => {
-        degree.set(id, (degree.get(id) ?? 0) + 1);
-    };
-    for (const item of items) {
-        if (typeof item.parent === "string" && item.parent.trim()) {
-            increment(item.id);
-            increment(item.parent.trim());
-        }
-        for (const dependency of item.dependencies ?? []) {
-            if (typeof dependency.id !== "string" || !dependency.id.trim())
-                continue;
-            increment(item.id);
-            increment(dependency.id.trim());
-        }
-    }
-    const maximum = Math.max(0, ...degree.values());
-    return Object.fromEntries(items.map((item) => [
-        item.id,
-        maximum === 0 ? 0 : degree.get(item.id) / maximum,
-    ]));
-}
-function stableSnapshotOptions(items, options) {
-    return {
-        ...options,
-        activityDensity: options.activityDensity ??
-            normalizedCountsById(items, (item) => (item.comments?.length ?? 0) +
-                (item.notes?.length ?? 0) +
-                (item.learnings?.length ?? 0) +
-                (item.test_runs?.length ?? 0)),
-        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))
-        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 supportedSignals = new Set(STORED_CONTEXT_SIGNAL_NAMES);
-    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 validItems.sort((left, right) => left.id.localeCompare(right.id));
-}
-/** Validate an untrusted serialized snapshot without accepting partial envelopes. */
-export function parseContextSignalSnapshot(value) {
-    if (!isRecord(value) ||
-        value.format_version !== CONTEXT_SIGNAL_STORE_FORMAT_VERSION ||
-        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 = parseSnapshotItems(value.items, value.recency_evidence_fingerprint);
-    if (items === null)
-        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,
-    };
-}
-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") {
-        throw new TypeError("Context signal snapshot source must be derived_index or scan_fallback");
-    }
-}
-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;
-    /** Create an adapter for an explicit derived-state file path. */
-    constructor(filePath) {
-        if (typeof filePath !== "string" || filePath.trim().length === 0) {
-            throw new TypeError("Context signal store path must be non-empty");
-        }
-        this.filePath = path.resolve(filePath);
-    }
-    /** Read and decode the JSON snapshot, returning null when it does not exist. */
-    async read() {
-        try {
-            return JSON.parse(await fs.readFile(this.filePath, "utf8"));
-        }
-        catch (error) {
-            if (isRecord(error) && isFileAbsentError(error)) {
-                return null;
-            }
-            throw error;
-        }
-    }
-    /** Write a complete snapshot through a unique same-directory temporary file. */
-    async write(snapshot) {
-        const directory = path.dirname(this.filePath);
-        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.rename(temporaryPath, this.filePath);
-        }
-        finally {
-            try {
-                await fs.rm(temporaryPath, { force: true });
-            }
-            catch {
-                // The complete snapshot is already committed; temporary-file cleanup is best effort.
-            }
-        }
-    }
-}
-/** Cursor-aware feature store that self-heals from absent, stale, or corrupt state. */
-export class ContextSignalStore {
-    adapter;
-    /** Bind the store to a caller-selected persistence adapter. */
-    constructor(adapter) {
-        this.adapter = adapter;
-    }
-    /** Read matching signals or rebuild them from authoritative items. */
-    async readOrRebuild(items, options) {
-        validateSnapshotOptions(options);
-        const warnings = [];
-        let snapshot = null;
-        try {
-            const serialized = await this.adapter.read();
-            snapshot = parseContextSignalSnapshot(serialized);
-            if (serialized !== null && snapshot === null) {
-                warnings.push("context_signal_store_invalid");
-            }
-        }
-        catch {
-            warnings.push("context_signal_store_invalid");
-        }
-        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]);
-        let resolvedSnapshot;
-        if (fresh && snapshot !== null) {
-            resolvedSnapshot = snapshot;
-        }
-        else {
-            if (snapshot !== null) {
-                warnings.push("context_signal_store_stale");
-            }
-            resolvedSnapshot = snapshotFromCandidates(authoritativeCandidates, options, authoritativeFingerprint);
-            try {
-                await this.adapter.write(resolvedSnapshot);
-            }
-            catch {
-                warnings.push("context_signal_store_write_failed");
-            }
-        }
-        const snapshotItemsById = new Map(resolvedSnapshot.items.map((item) => [item.id, item]));
-        return {
-            snapshot: resolvedSnapshot,
-            candidates: authoritativeCandidates.map((candidate) => ({
-                ...candidate,
-                signals: {
-                    ...candidate.signals,
-                    ...snapshotItemsById.get(candidate.id)?.signals,
-                },
-                signal_provenance: snapshotItemsById.get(candidate.id).signal_provenance,
-            })),
-            cache_status: fresh ? "fresh" : "rebuilt",
-            warnings,
-            warning_details: warnings.map((warning) => CONTEXT_SIGNAL_STORE_WARNING_DETAILS[warning]),
-        };
-    }
-}
-function fallbackWorkspaceCursor(items) {
-    const hash = createHash("sha256");
-    for (const item of [...items].sort((left, right) => left.id.localeCompare(right.id))) {
-        hash.update(JSON.stringify([
-            item.id,
-            item.updated_at,
-            item.status,
-            item.parent ?? null,
-            item.priority ?? null,
-            item.risk ?? null,
-            (item.dependencies ?? []).map((dependency) => dependency.id).sort(),
-            item.comments?.length ?? 0,
-            item.notes?.length ?? 0,
-            item.learnings?.length ?? 0,
-            item.test_runs?.length ?? 0,
-        ]));
-    }
-    return `scan:${hash.digest("hex")}`;
-}
-/** Read cursor-bound workspace signals with deterministic scan fallback. */
-export async function readWorkspaceContextSignals(items, options) {
-    const hasSourceCursor = options.sourceCursor !== undefined;
-    const hasSource = options.source !== undefined;
-    if (hasSourceCursor !== hasSource) {
-        throw new TypeError("Context signal source and source cursor must be provided together");
-    }
-    if (options.storeKey !== undefined &&
-        !/^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$/u.test(options.storeKey)) {
-        throw new TypeError("Context signal store key must be a filesystem-safe identifier");
-    }
-    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")));
-    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,
-    });
-}
+!(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]="190679b7-4723-5c76-be57-2ec88b92b109")}catch(e2){}})();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";const CONTEXT_SIGNAL_STORE_FORMAT_VERSION=3;const CONTEXT_SIGNAL_SET_VERSION=2;const STORED_CONTEXT_SIGNAL_NAMES=["recency","activity_density","graph_proximity","priority_pressure","risk_pressure","knowledge_density"];const CONTEXT_RECENCY_SOURCES=new Set(["substantive_history","release_cohort","created_at"]);const CONTEXT_SIGNAL_STORE_WARNING_DETAILS={context_signal_store_invalid:{code:"context_signal_store_invalid",meaning:"The persisted context-signal snapshot was unreadable or invalid and was rebuilt from authoritative items.",recovery_command:"pm context",recovery_effect:"Re-read context and confirm the rebuilt snapshot can be loaded without the warning."},context_signal_store_stale:{code:"context_signal_store_stale",meaning:"The persisted context-signal snapshot did not match the authoritative cursor or item corpus and was rebuilt.",recovery_command:"pm context",recovery_effect:"Re-read context and confirm the rebuilt snapshot is now fresh."},context_signal_store_write_failed:{code:"context_signal_store_write_failed",meaning:"Context signals were rebuilt in memory, but the derived snapshot could not be persisted.",recovery_command:"pm context",recovery_effect:"Retry the derived snapshot write and confirm the warning clears after storage access is restored."}};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}function compactSignals(signals){const compact={};for(const name of STORED_CONTEXT_SIGNAL_NAMES){const value=signals[name];if(value===void 0)continue;if(!isNormalizedSignal(value)){throw new TypeError(`Context relevance signal ${name} must be a finite number from 0 to 1`)}compact[name]=value}return compact}function normalizedCountsById(items,count){const counts=items.map(item=>[item.id,count(item)]);const maximum=Math.max(0,...counts.map(([,value])=>value));return Object.fromEntries(counts.map(([id,value])=>[id,maximum===0?0:value/maximum]))}function deriveGraphProximity(items){const degree=new Map(items.map(item=>[item.id,0]));const increment=id=>{degree.set(id,(degree.get(id)??0)+1)};for(const item of items){if(typeof item.parent==="string"&&item.parent.trim()){increment(item.id);increment(item.parent.trim())}for(const dependency of item.dependencies??[]){if(typeof dependency.id!=="string"||!dependency.id.trim())continue;increment(item.id);increment(dependency.id.trim())}}const maximum=Math.max(0,...degree.values());return Object.fromEntries(items.map(item=>[item.id,maximum===0?0:degree.get(item.id)/maximum]))}function stableSnapshotOptions(items,options){return{...options,activityDensity:options.activityDensity??normalizedCountsById(items,item=>(item.comments?.length??0)+(item.notes?.length??0)+(item.learnings?.length??0)+(item.test_runs?.length??0)),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))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 supportedSignals=new Set(STORED_CONTEXT_SIGNAL_NAMES);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),[void 0,"substantive","maintenance"].includes(recency.event_class),recency.source==="substantive_history"?recency.event_class===void 0||recency.event_class==="substantive":recency.history_op===void 0&&recency.event_class===void 0].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 validItems.sort((left,right)=>left.id.localeCompare(right.id))}function parseContextSignalSnapshot(value){if(!isRecord(value)||value.format_version!==CONTEXT_SIGNAL_STORE_FORMAT_VERSION||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=parseSnapshotItems(value.items,value.recency_evidence_fingerprint);if(items===null)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}}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"){throw new TypeError("Context signal snapshot source must be derived_index or scan_fallback")}}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)))})}function buildContextSignalSnapshot(items,options){validateSnapshotOptions(options);return snapshotFromCandidates(buildItemContextRelevanceCandidates(items,stableSnapshotOptions(items,options)),options)}class JsonFileContextSignalStoreAdapter{filePath;constructor(filePath){if(typeof filePath!=="string"||filePath.trim().length===0){throw new TypeError("Context signal store path must be non-empty")}this.filePath=path.resolve(filePath)}async read(){try{return JSON.parse(await fs.readFile(this.filePath,"utf8"))}catch(error){if(isRecord(error)&&isFileAbsentError(error)){return null}throw error}}async write(snapshot){const directory=path.dirname(this.filePath);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)}
+`,{encoding:"utf8",flag:"wx"});await fs.rename(temporaryPath,this.filePath)}finally{try{await fs.rm(temporaryPath,{force:true})}catch{}}}}class ContextSignalStore{adapter;constructor(adapter){this.adapter=adapter}async readOrRebuild(items,options){validateSnapshotOptions(options);const warnings=[];let snapshot=null;try{const serialized=await this.adapter.read();snapshot=parseContextSignalSnapshot(serialized);if(serialized!==null&&snapshot===null){warnings.push("context_signal_store_invalid")}}catch{warnings.push("context_signal_store_invalid")}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]);let resolvedSnapshot;if(fresh&&snapshot!==null){resolvedSnapshot=snapshot}else{if(snapshot!==null){warnings.push("context_signal_store_stale")}resolvedSnapshot=snapshotFromCandidates(authoritativeCandidates,options,authoritativeFingerprint);try{await this.adapter.write(resolvedSnapshot)}catch{warnings.push("context_signal_store_write_failed")}}const snapshotItemsById=new Map(resolvedSnapshot.items.map(item=>[item.id,item]));return{snapshot:resolvedSnapshot,candidates:authoritativeCandidates.map(candidate=>({...candidate,signals:{...candidate.signals,...snapshotItemsById.get(candidate.id)?.signals},signal_provenance:snapshotItemsById.get(candidate.id).signal_provenance})),cache_status:fresh?"fresh":"rebuilt",warnings,warning_details:warnings.map(warning=>CONTEXT_SIGNAL_STORE_WARNING_DETAILS[warning])}}}function fallbackWorkspaceCursor(items){const hash=createHash("sha256");for(const item of[...items].sort((left,right)=>left.id.localeCompare(right.id))){hash.update(JSON.stringify([item.id,item.updated_at,item.status,item.parent??null,item.priority??null,item.risk??null,(item.dependencies??[]).map(dependency=>dependency.id).sort(),item.comments?.length??0,item.notes?.length??0,item.learnings?.length??0,item.test_runs?.length??0]))}return`scan:${hash.digest("hex")}`}async function readWorkspaceContextSignals(items,options){const hasSourceCursor=options.sourceCursor!==void 0;const hasSource=options.source!==void 0;if(hasSourceCursor!==hasSource){throw new TypeError("Context signal source and source cursor must be provided together")}if(options.storeKey!==void 0&&!/^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$/u.test(options.storeKey)){throw new TypeError("Context signal store key must be a filesystem-safe identifier")}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")));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})}export{CONTEXT_SIGNAL_SET_VERSION,CONTEXT_SIGNAL_STORE_FORMAT_VERSION,CONTEXT_SIGNAL_STORE_WARNING_DETAILS,ContextSignalStore,JsonFileContextSignalStoreAdapter,buildContextSignalSnapshot,parseContextSignalSnapshot,readWorkspaceContextSignals};
 //# sourceMappingURL=context-signal-store.js.map
-//# debugId=9b112b71-e0b8-5502-89f6-b4da6eb85f6b