@unbrained/pm-cli 2026.10.12 → 2026.10.14

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

@@ -8,99 +8,99 @@ export declare const CONTEXT_SIGNAL_SET_VERSION = 2;
 export type ContextSignalSnapshotSource = "derived_index" | "scan_fallback";
 /** One immutable item signal row. */
 export interface ContextSignalSnapshotItem {
-    /** Stable item identifier. */
-    id: string;
-    /** Canonical normalized signal vector. */
-    signals: ContextRelevanceSignals;
-    /** Authoritative temporal source retained for explained ranking. */
-    signal_provenance: ContextSignalProvenance;
+/** Stable item identifier. */
+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 {
-    /** Serialized envelope version. */
-    format_version: number;
-    /** Signal algorithm version. */
-    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. */
-    source: ContextSignalSnapshotSource;
-    /** Item rows sorted by canonical id. */
-    items: readonly ContextSignalSnapshotItem[];
+/** Serialized envelope version. */
+format_version: number;
+/** Signal algorithm version. */
+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. */
+source: ContextSignalSnapshotSource;
+/** Item rows sorted by canonical id. */
+items: readonly ContextSignalSnapshotItem[];
 }
 /** Pluggable persistence boundary for context-signal snapshots. */
 export interface ContextSignalStoreAdapter {
-    /** Read the serialized snapshot, or null when none exists. */
-    read(): Promise<unknown | null>;
-    /** Atomically replace the serialized snapshot. */
-    write(snapshot: ContextSignalSnapshot): Promise<void>;
+/** Read the serialized snapshot, or null when none exists. */
+read(): Promise<unknown | null>;
+/** Atomically replace the serialized snapshot. */
+write(snapshot: ContextSignalSnapshot): Promise<void>;
 }
 /** Options required to fold authoritative items into a snapshot. */
 export interface BuildContextSignalSnapshotOptions extends BuildItemContextRelevanceCandidatesOptions {
-    /** Authoritative history or derived-index cursor. */
-    sourceCursor: string;
-    /** Substrate used to load the authoritative items. */
-    source: ContextSignalSnapshotSource;
+/** Authoritative history or derived-index cursor. */
+sourceCursor: string;
+/** Substrate used to load the authoritative items. */
+source: ContextSignalSnapshotSource;
 }
 /** Result of a feature-store read with explicit degradation metadata. */
 export interface ContextSignalStoreReadResult {
-    /** Valid snapshot used for candidate assembly. */
-    snapshot: ContextSignalSnapshot;
-    /** Candidates joined to the caller's authoritative item objects. */
-    candidates: ContextRelevanceCandidate<ItemMetadata>[];
-    /** Whether the persisted snapshot was reused or rebuilt. */
-    cache_status: "fresh" | "rebuilt";
-    /** Non-fatal recovery diagnostics. */
-    warnings: readonly string[];
-    /** Actionable meanings and executable recovery commands for every warning. */
-    warning_details?: readonly ContextSignalStoreWarningDetail[];
+/** Valid snapshot used for candidate assembly. */
+snapshot: ContextSignalSnapshot;
+/** Candidates joined to the caller's authoritative item objects. */
+candidates: ContextRelevanceCandidate<ItemMetadata>[];
+/** Whether the persisted snapshot was reused or rebuilt. */
+cache_status: "fresh" | "rebuilt";
+/** Non-fatal recovery diagnostics. */
+warnings: readonly string[];
+/** Actionable meanings and executable recovery commands for every warning. */
+warning_details?: readonly ContextSignalStoreWarningDetail[];
 }
 /** Stable recovery contract for one context signal-store warning. */
 export interface ContextSignalStoreWarningDetail {
-    /** Machine-readable warning code also present in `warnings`. */
-    code: "context_signal_store_invalid" | "context_signal_store_stale" | "context_signal_store_write_failed";
-    /** Bounded explanation of the observed derived-state condition. */
-    meaning: string;
-    /** Safe executable command that retries or confirms recovery. */
-    recovery_command: "pm context";
-    /** Expected observable effect of the recovery command. */
-    recovery_effect: string;
+/** Machine-readable warning code also present in `warnings`. */
+code: "context_signal_store_invalid" | "context_signal_store_stale" | "context_signal_store_write_failed";
+/** Bounded explanation of the observed derived-state condition. */
+meaning: string;
+/** Safe executable command that retries or confirms recovery. */
+recovery_command: "pm context";
+/** Expected observable effect of the recovery command. */
+recovery_effect: string;
 }
 /** Canonical actionable contracts shared by CLI, SDK, MCP, and package hosts. */
 export declare const CONTEXT_SIGNAL_STORE_WARNING_DETAILS: {
-    readonly context_signal_store_invalid: {
-        readonly code: "context_signal_store_invalid";
-        readonly meaning: "The persisted context-signal snapshot was unreadable or invalid and was rebuilt from authoritative items.";
-        readonly recovery_command: "pm context";
-        readonly recovery_effect: "Re-read context and confirm the rebuilt snapshot can be loaded without the warning.";
-    };
-    readonly context_signal_store_stale: {
-        readonly code: "context_signal_store_stale";
-        readonly meaning: "The persisted context-signal snapshot did not match the authoritative cursor or item corpus and was rebuilt.";
-        readonly recovery_command: "pm context";
-        readonly recovery_effect: "Re-read context and confirm the rebuilt snapshot is now fresh.";
-    };
-    readonly context_signal_store_write_failed: {
-        readonly code: "context_signal_store_write_failed";
-        readonly meaning: "Context signals were rebuilt in memory, but the derived snapshot could not be persisted.";
-        readonly recovery_command: "pm context";
-        readonly recovery_effect: "Retry the derived snapshot write and confirm the warning clears after storage access is restored.";
-    };
+readonly context_signal_store_invalid: {
+readonly code: "context_signal_store_invalid";
+readonly meaning: "The persisted context-signal snapshot was unreadable or invalid and was rebuilt from authoritative items.";
+readonly recovery_command: "pm context";
+readonly recovery_effect: "Re-read context and confirm the rebuilt snapshot can be loaded without the warning.";
+};
+readonly context_signal_store_stale: {
+readonly code: "context_signal_store_stale";
+readonly meaning: "The persisted context-signal snapshot did not match the authoritative cursor or item corpus and was rebuilt.";
+readonly recovery_command: "pm context";
+readonly recovery_effect: "Re-read context and confirm the rebuilt snapshot is now fresh.";
+};
+readonly context_signal_store_write_failed: {
+readonly code: "context_signal_store_write_failed";
+readonly meaning: "Context signals were rebuilt in memory, but the derived snapshot could not be persisted.";
+readonly recovery_command: "pm context";
+readonly recovery_effect: "Retry the derived snapshot write and confirm the warning clears after storage access is restored.";
+};
 };
 /** Workspace-bound feature-store options used by CLI, MCP, and SDK readers. */
 export interface ReadWorkspaceContextSignalsOptions extends BuildItemContextRelevanceCandidatesOptions {
-    /** Tracker root containing rebuildable runtime state. */
-    pmRoot: string;
-    /** Explicit cursor for custom SDK hosts; the stock host reads the metadata index. */
-    sourceCursor?: string;
-    /** Explicit source classification paired with sourceCursor. */
-    source?: ContextSignalSnapshotSource;
-    /** Stable projection namespace when one workspace serves distinct candidate corpora. */
-    storeKey?: string;
+/** Tracker root containing rebuildable runtime state. */
+pmRoot: string;
+/** Explicit cursor for custom SDK hosts; the stock host reads the metadata index. */
+sourceCursor?: string;
+/** Explicit source classification paired with sourceCursor. */
+source?: ContextSignalSnapshotSource;
+/** Stable projection namespace when one workspace serves distinct candidate corpora. */
+storeKey?: string;
 }
 /** Validate an untrusted serialized snapshot without accepting partial envelopes. */
 export declare function parseContextSignalSnapshot(value: unknown): ContextSignalSnapshot | null;
@@ -108,21 +108,21 @@ export declare function parseContextSignalSnapshot(value: unknown): ContextSigna
 export declare function buildContextSignalSnapshot(items: readonly ItemMetadata[], options: BuildContextSignalSnapshotOptions): ContextSignalSnapshot;
 /** Filesystem adapter using same-directory atomic replacement. */
 export declare class JsonFileContextSignalStoreAdapter implements ContextSignalStoreAdapter {
-    private readonly filePath;
-    /** Create an adapter for an explicit derived-state file path. */
-    constructor(filePath: string);
-    /** Read and decode the JSON snapshot, returning null when it does not exist. */
-    read(): Promise<unknown | null>;
-    /** Write a complete snapshot through a unique same-directory temporary file. */
-    write(snapshot: ContextSignalSnapshot): Promise<void>;
+private readonly filePath;
+/** Create an adapter for an explicit derived-state file path. */
+constructor(filePath: string);
+/** Read and decode the JSON snapshot, returning null when it does not exist. */
+read(): Promise<unknown | null>;
+/** Write a complete snapshot through a unique same-directory temporary file. */
+write(snapshot: ContextSignalSnapshot): Promise<void>;
 }
 /** Cursor-aware feature store that self-heals from absent, stale, or corrupt state. */
 export declare class ContextSignalStore {
-    private readonly adapter;
-    /** Bind the store to a caller-selected persistence adapter. */
-    constructor(adapter: ContextSignalStoreAdapter);
-    /** Read matching signals or rebuild them from authoritative items. */
-    readOrRebuild(items: readonly ItemMetadata[], options: BuildContextSignalSnapshotOptions): Promise<ContextSignalStoreReadResult>;
+private readonly adapter;
+/** Bind the store to a caller-selected persistence adapter. */
+constructor(adapter: ContextSignalStoreAdapter);
+/** Read matching signals or rebuild them from authoritative items. */
+readOrRebuild(items: readonly ItemMetadata[], options: BuildContextSignalSnapshotOptions): Promise<ContextSignalStoreReadResult>;
 }
 /** Read cursor-bound workspace signals with deterministic scan fallback. */
 export declare function readWorkspaceContextSignals(items: readonly ItemMetadata[], options: ReadWorkspaceContextSignalsOptions): Promise<ContextSignalStoreReadResult>;

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

@@ -3,91 +3,91 @@ export { ContextUsageValidationError, CONTEXT_USAGE_LIMITS, type ContextUsageWri
 import type { ContextRelevanceSurface } from "./context-relevance.js";
 /** One propensity row disclosed when context or next serves a candidate. */
 export interface ContextUsageServingRow {
-    /** Served item identifier. */
-    id: string;
-    /** One-based scorer rank. */
-    rank: number;
-    /** Whether the packer included the item. */
-    included: boolean;
+/** Served item identifier. */
+id: string;
+/** One-based scorer rank. */
+rank: number;
+/** 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[];
-    /** Persisted sample identities; absent on legacy unsampled receipts. */
-    recorded_item_ids?: readonly string[];
-    /** Measured bounded persistence; absent on legacy receipts. */
-    storage?: ContextUsageWriteReceipt;
+/** 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[];
+/** Persisted sample identities; absent on legacy unsampled receipts. */
+recorded_item_ids?: readonly string[];
+/** Measured bounded persistence; absent on legacy receipts. */
+storage?: ContextUsageWriteReceipt;
 }
 /** 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[];
-    /** Full candidate population before deterministic prefix sampling. */
-    candidate_count?: number;
-    /** Candidate rows excluded from this bounded feedback sample. */
-    omitted_row_count?: number;
-    result_omitted?: boolean;
-    packed_item_ids?: string[];
-    /** Legacy pre-egress field ignored by the v2 affinity fold. */
-    delivered_item_ids?: string[];
+kind: "serve";
+schema_version?: 2;
+serve_id?: string;
+at: string;
+author: string;
+surface: ContextRelevanceSurface;
+profile: string;
+rows: ContextUsageServingRow[];
+/** Full candidate population before deterministic prefix sampling. */
+candidate_count?: number;
+/** Candidate rows excluded from this bounded feedback sample. */
+omitted_row_count?: number;
+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: "delivery";
+schema_version: 2;
+serve_id: string;
+at: string;
+author: string;
+surface: ContextRelevanceSurface;
+result_omitted: boolean;
+delivered_item_ids: string[];
 } | {
-    kind: "touch";
-    at: string;
-    author: string;
-    item_id: string;
-    intent: string;
+kind: "touch";
+at: string;
+author: string;
+item_id: string;
+intent: string;
 };
 /** Runtime controls for the bounded derived ledger. */
 export interface ContextUsageLedgerOptions {
-    /**
+/**
      * Tracker root containing the runtime directory. Its directory entries and
      * ancestors must remain controlled by trusted cooperating processes during
      * ledger operations; hostile concurrent path replacement is unsupported.
      */
-    pmRoot: string;
-    /** Disable all reads and writes with zero filesystem work. */
-    enabled?: boolean;
-    /** Maximum retained event rows. */
-    maxEvents?: number;
-    /** Physical byte ceiling; compaction retains at most half to provide headroom. */
-    maxBytes?: number;
-    /** Retention horizon in days. */
-    retentionDays?: number;
-    /** Deterministic timestamp override. */
-    now?: string;
+pmRoot: string;
+/** Disable all reads and writes with zero filesystem work. */
+enabled?: boolean;
+/** Maximum retained event rows. */
+maxEvents?: number;
+/** Physical byte ceiling; compaction retains at most half to provide headroom. */
+maxBytes?: number;
+/** Retention horizon in days. */
+retentionDays?: number;
+/** Deterministic timestamp override. */
+now?: string;
 }
 /** Decayed per-item affinity derived for one author. */
 export interface ContextUsageAffinity {
-    /** Normalized affinity by item id. */
-    affinity: Record<string, number>;
-    /** Number of eligible served-then-touched judgments. */
-    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;
+/** Normalized affinity by item id. */
+affinity: Record<string, number>;
+/** Number of eligible served-then-touched judgments. */
+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;
@@ -101,49 +101,49 @@ export declare function propagateContextUsageServingReceipt(source: unknown, tar
 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;
+/** Tracker root owning the derived ledger. */
+pmRoot: string;
+/** Final projected response returned or rendered to the caller. */
+result: unknown;
 }): Promise<boolean>;
 /** Records a bounded prefix of ranked context candidates with explicit sampling counts. */
 export declare function recordContextUsageServing(options: ContextUsageLedgerOptions & {
-    author: string;
-    surface: ContextRelevanceSurface;
-    profile: string;
-    rows: ContextUsageServingRow[];
+author: string;
+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;
+/** 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 & {
-    author: string;
-    itemId: string;
-    intent: string;
+author: string;
+itemId: string;
+intent: string;
 }): Promise<void>;
 /**
  * Records mutation outcomes as one append and one optional compaction pass.
  */
 export declare function recordContextUsageTouches(options: ContextUsageLedgerOptions & {
-    /** Stable caller identity used to isolate affinity. */
-    author: string;
-    /** Item identifiers affected by the completed command. */
-    itemIds: readonly string[];
-    /** Command or workflow intent associated with the touches. */
-    intent: string;
+/** Stable caller identity used to isolate affinity. */
+author: string;
+/** Item identifiers affected by the completed command. */
+itemIds: readonly string[];
+/** Command or workflow intent associated with the touches. */
+intent: string;
 }): Promise<void>;
 /**
  * Derives decayed served-then-touched affinity. A small exploration floor keeps
  * ignored and unseen items eligible, preventing a popularity feedback lock-in.
  */
 export declare function readContextUsageAffinity(options: ContextUsageLedgerOptions & {
-    author: string;
-    horizonHours?: number;
+author: string;
+horizonHours?: number;
 }): Promise<ContextUsageAffinity>;