@codemem/core 0.40.0-alpha.1 → 0.40.0

package/dist/retrieval-ledger.d.ts

@@ -0,0 +1,216 @@
+import type { Database } from "./db.js";
+import type { MemoryFilters, PackTraceCandidateScores, PackTraceSection } from "./types.js";
+export declare const RETRIEVAL_LEDGER_CONTRACT_VERSION: 1;
+export declare const DEFAULT_RETRIEVAL_LEDGER_RETENTION_DAYS = 90;
+export declare const MAX_RETRIEVAL_SELECTED_EXPOSURES = 50;
+export declare const MAX_RETRIEVAL_DIAGNOSTIC_EXPOSURES = 20;
+export declare const MAX_RETRIEVAL_JSON_BYTES: number;
+export declare const DEFAULT_RETRIEVAL_QUERY_LIMIT = 50;
+export declare const MAX_RETRIEVAL_QUERY_LIMIT = 100;
+export type RetrievalSurface = "prompt_pack" | "file_context" | "mcp_search" | "mcp_search_index" | "mcp_pack" | "mcp_get" | "mcp_get_observations" | "mcp_recent" | "mcp_timeline" | "mcp_expand" | "mcp_explain" | "evaluation_replay";
+export type RetrievalTrigger = "automatic" | "explicit" | "evaluation";
+export type RetrievalStatus = "succeeded" | "no_results" | "skipped" | "failed" | "unknown";
+export type RetrievalDeliveryStatus = "not_attempted" | "handed_off" | "failed" | "unknown";
+export type RetrievalDisposition = "selected" | "dropped" | "deduped" | "trimmed" | "compressed";
+export type RetrievalFilterSummary = Omit<MemoryFilters, "working_set_paths">;
+export type RetrievalScoreSummary = Partial<PackTraceCandidateScores>;
+export interface RetrievalExposureInput {
+    memoryId?: number | null;
+    memoryImportKey?: string | null;
+    originDeviceId?: string | null;
+    rank: number;
+    disposition: RetrievalDisposition;
+    section?: PackTraceSection | null;
+    handoffStatus: RetrievalDeliveryStatus;
+    memoryRev?: number | null;
+    memoryUpdatedAt?: string | null;
+    memoryScopeId?: string | null;
+    memoryKind?: string | null;
+    memoryActive?: boolean | null;
+    memoryDeletedAt?: string | null;
+    scoreSummary?: RetrievalScoreSummary | null;
+    reasonCodes?: string[] | null;
+}
+export interface RecordRetrievalAttemptInput {
+    attemptId: string;
+    surface: RetrievalSurface;
+    trigger: RetrievalTrigger;
+    startedAt: string;
+    completedAt?: string | null;
+    retrievalStatus: RetrievalStatus;
+    deliveryStatus: RetrievalDeliveryStatus;
+    candidateCount: number;
+    selectedCount: number;
+    recorderVersion: string;
+    sessionId?: number | null;
+    source?: string | null;
+    streamId?: string | null;
+    sourceSessionId?: string | null;
+    promptNumber?: number | null;
+    requestId?: string | null;
+    rawEventStartSeq?: number | null;
+    rawEventEndSeq?: number | null;
+    experimentId?: string | null;
+    experimentCellId?: string | null;
+    evaluationCheckoutId?: string | null;
+    evaluationFixtureId?: string | null;
+    evaluationSeed?: number | null;
+    latencyMs?: number | null;
+    project?: string | null;
+    scopeId?: string | null;
+    mode?: string | null;
+    limitRequested?: number | null;
+    tokenBudget?: number | null;
+    outputTokens?: number | null;
+    workingSetFileCount?: number | null;
+    workingSetFiles?: string[] | null;
+    queryHashSha256?: string | null;
+    queryCharCount?: number | null;
+    queryTokenEstimate?: number | null;
+    filterSummary?: RetrievalFilterSummary | null;
+    failureCode?: string | null;
+    failureStage?: string | null;
+    traceVersion?: number | null;
+    retentionDays?: number;
+    retentionPinned?: boolean;
+    exposures: RetrievalExposureInput[];
+}
+export interface RetrievalAttemptRecord {
+    attemptId: string;
+    contractVersion: typeof RETRIEVAL_LEDGER_CONTRACT_VERSION;
+    surface: RetrievalSurface;
+    trigger: RetrievalTrigger;
+    startedAt: string;
+    completedAt: string | null;
+    retrievalStatus: RetrievalStatus;
+    deliveryStatus: RetrievalDeliveryStatus;
+    candidateCount: number;
+    selectedCount: number;
+    persistedCandidateCount: number;
+    recorderVersion: string;
+    sessionId: number | null;
+    source: string | null;
+    streamId: string | null;
+    sourceSessionId: string | null;
+    promptNumber: number | null;
+    requestId: string | null;
+    rawEventStartSeq: number | null;
+    rawEventEndSeq: number | null;
+    experimentId: string | null;
+    experimentCellId: string | null;
+    evaluationCheckoutId: string | null;
+    evaluationFixtureId: string | null;
+    evaluationSeed: number | null;
+    latencyMs: number | null;
+    project: string | null;
+    scopeId: string | null;
+    mode: string | null;
+    limitRequested: number | null;
+    tokenBudget: number | null;
+    outputTokens: number | null;
+    workingSetFileCount: number | null;
+    workingSetFiles: string[] | null;
+    queryHashSha256: string | null;
+    queryCharCount: number | null;
+    queryTokenEstimate: number | null;
+    filterSummary: RetrievalFilterSummary | null;
+    failureCode: string | null;
+    failureStage: string | null;
+    traceVersion: number | null;
+    retentionUntil: string | null;
+    retentionPinned: boolean;
+    retentionFinalizedAt: string | null;
+    exposures: RetrievalExposureRecord[];
+}
+export interface RetrievalExposureRecord extends RetrievalExposureInput {
+    exposureId: number;
+    attemptId: string;
+}
+export interface RetrievalWriteResult {
+    attempt: RetrievalAttemptRecord;
+    inserted: boolean;
+}
+export interface QueryRetrievalAttemptsInput {
+    sessionId?: number;
+    source?: string;
+    streamId?: string;
+    surface?: RetrievalSurface;
+    startedAtOrAfter?: string;
+    startedAtOrBefore?: string;
+    limit?: number;
+}
+export interface FinalizeRetrievalAttemptRetentionInput {
+    finalizedAt: string;
+    retentionDays?: number;
+}
+export type RetrievalLedgerWriteOutcome = {
+    ok: true;
+    value: RetrievalWriteResult;
+} | {
+    ok: false;
+    errorCode: "retrieval_ledger_write_failed";
+    reason: RetrievalLedgerFailureReason;
+};
+export type RetrievalLedgerDeliveryOutcome = {
+    ok: true;
+    value: {
+        changed: boolean;
+        attempt: RetrievalAttemptRecord;
+    };
+} | {
+    ok: false;
+    errorCode: "retrieval_ledger_delivery_write_failed";
+    reason: RetrievalLedgerFailureReason;
+};
+export type RetrievalLedgerRetentionOutcome = {
+    ok: true;
+    value: {
+        changed: boolean;
+        attempt: RetrievalAttemptRecord;
+    };
+} | {
+    ok: false;
+    errorCode: "retrieval_ledger_retention_write_failed";
+    reason: RetrievalLedgerFailureReason;
+};
+export type RetrievalLedgerFailureReason = "invalid_input" | "idempotency_conflict" | "attempt_not_found" | "storage_unavailable";
+export declare function isValidRetrievalFilterSummaryEntry(key: string, entry: unknown): boolean;
+export declare function hashRetrievalQuery(query: string): {
+    queryHashSha256: string;
+    queryCharCount: number;
+};
+export declare function getRetrievalAttempt(db: Database, attemptId: string): RetrievalAttemptRecord | null;
+export declare function queryRetrievalAttempts(db: Database, input?: QueryRetrievalAttemptsInput): RetrievalAttemptRecord[];
+export declare function recordRetrievalAttempt(db: Database, input: RecordRetrievalAttemptInput): RetrievalWriteResult;
+export declare function tryRecordRetrievalAttempt(db: Database, input: RecordRetrievalAttemptInput): RetrievalLedgerWriteOutcome;
+export declare function reconcileFailedRetrievalAttempt(db: Database, input: RecordRetrievalAttemptInput): RetrievalWriteResult;
+export declare function tryReconcileFailedRetrievalAttempt(db: Database, input: RecordRetrievalAttemptInput): RetrievalLedgerWriteOutcome;
+export declare function updateRetrievalDelivery(db: Database, attemptId: string, deliveryStatus: Exclude<RetrievalDeliveryStatus, "not_attempted">): {
+    changed: boolean;
+    attempt: RetrievalAttemptRecord;
+};
+export declare function tryUpdateRetrievalDelivery(db: Database, attemptId: string, deliveryStatus: Exclude<RetrievalDeliveryStatus, "not_attempted">): RetrievalLedgerDeliveryOutcome;
+export declare function finalizeRetrievalAttemptRetention(db: Database, attemptId: string, input: FinalizeRetrievalAttemptRetentionInput): {
+    changed: boolean;
+    attempt: RetrievalAttemptRecord;
+};
+export declare function tryFinalizeRetrievalAttemptRetention(db: Database, attemptId: string, input: FinalizeRetrievalAttemptRetentionInput): RetrievalLedgerRetentionOutcome;
+export declare function purgeExpiredRetrievalAttempts(db: Database, now?: string): number;
+export type RetrievalPrivacyPurgeSelector = {
+    sessionId: number;
+    source?: never;
+    streamId?: never;
+    surface?: never;
+} | {
+    sessionId?: never;
+    source: string;
+    streamId: string;
+    surface?: never;
+} | {
+    sessionId?: never;
+    source: string;
+    streamId?: never;
+    surface: RetrievalSurface;
+};
+export declare function purgeRetrievalAttemptsForPrivacy(db: Database, selector: RetrievalPrivacyPurgeSelector): number;
+//# sourceMappingURL=retrieval-ledger.d.ts.map

package/dist/retrieval-ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrieval-ledger.d.ts","sourceRoot":"","sources":["../src/retrieval-ledger.ts"],"names":[],"mappings":"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"}

package/dist/retrieval-surface-ledger.d.ts

@@ -0,0 +1,17 @@
+import type { Database } from "./db.js";
+import { type RecordRetrievalAttemptInput, type RetrievalFilterSummary, type RetrievalLedgerWriteOutcome } from "./retrieval-ledger.js";
+import type { MemoryFilters } from "./types.js";
+export interface RetrievalSurfaceRecordInput extends Omit<RecordRetrievalAttemptInput, "candidateCount" | "selectedCount" | "exposures" | "filterSummary" | "queryHashSha256" | "queryCharCount" | "queryTokenEstimate" | "workingSetFiles" | "workingSetFileCount"> {
+    candidateIds?: number[];
+    selectedIds?: number[];
+    candidateCount?: number;
+    filters?: MemoryFilters;
+    query?: string | null;
+    repositoryPaths?: string[];
+}
+export declare function sanitizeRepositoryPaths(paths: string[] | undefined): string[] | null;
+export declare function sanitizeRetrievalFilters(filters: MemoryFilters | undefined): RetrievalFilterSummary | null;
+export declare function resolveRetrievalSession(db: Database, source: string, sourceSessionId: string | null | undefined): number | null;
+export declare function recordRetrievalSurface(db: Database, input: RetrievalSurfaceRecordInput): RetrievalLedgerWriteOutcome;
+export declare function reconcileFailedRetrievalSurface(db: Database, input: RetrievalSurfaceRecordInput): RetrievalLedgerWriteOutcome;
+//# sourceMappingURL=retrieval-surface-ledger.d.ts.map

package/dist/retrieval-surface-ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrieval-surface-ledger.d.ts","sourceRoot":"","sources":["../src/retrieval-surface-ledger.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAGxC,OAAO,EAMN,KAAK,2BAA2B,EAEhC,KAAK,sBAAsB,EAC3B,KAAK,2BAA2B,EAGhC,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AA6ChD,MAAM,WAAW,2BAChB,SAAQ,IAAI,CACX,2BAA2B,EACzB,gBAAgB,GAChB,eAAe,GACf,WAAW,GACX,eAAe,GACf,iBAAiB,GACjB,gBAAgB,GAChB,oBAAoB,GACpB,iBAAiB,GACjB,qBAAqB,CACvB;IACD,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAQD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,SAAS,GAAG,MAAM,EAAE,GAAG,IAAI,CAgBpF;AAED,wBAAgB,wBAAwB,CACvC,OAAO,EAAE,aAAa,GAAG,SAAS,GAChC,sBAAsB,GAAG,IAAI,CA+C/B;AA0DD,wBAAgB,uBAAuB,CACtC,EAAE,EAAE,QAAQ,EACZ,MAAM,EAAE,MAAM,EACd,eAAe,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACxC,MAAM,GAAG,IAAI,CAcf;AAwCD,wBAAgB,sBAAsB,CACrC,EAAE,EAAE,QAAQ,EACZ,KAAK,EAAE,2BAA2B,GAChC,2BAA2B,CAU7B;AAED,wBAAgB,+BAA+B,CAC9C,EAAE,EAAE,QAAQ,EACZ,KAAK,EAAE,2BAA2B,GAChC,2BAA2B,CAU7B"}

package/dist/schema-bootstrap.d.ts

@@ -11,6 +11,8 @@ import type { Database } from "./db.js";
  */
 export declare function ensureVectorSchema(db: Database): void;
 export declare function bootstrapSchema(db: Database): void;
+/** Add the local-only retrieval ledger to an already initialized database. */
+export declare function ensureRetrievalLedgerSchema(db: Database): void;
 /**
  * Run `bootstrapSchema` on a database only if it's still at the unbootstrapped
  * state (`user_version === 0`). `connect()` now calls this by default for

package/dist/schema-bootstrap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema-bootstrap.d.ts","sourceRoot":"","sources":["../src/schema-bootstrap.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAgSxC;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,CAUrD;AAWD,wBAAgB,eAAe,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,CAYlD;AA2BD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,CAI3D;AAED,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,QAAQ,GAAG,OAAO,CAE5D"}
+{"version":3,"file":"schema-bootstrap.d.ts","sourceRoot":"","sources":["../src/schema-bootstrap.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AA4mBxC;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,CAUrD;AAWD,wBAAgB,eAAe,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,CAclD;AAED,8EAA8E;AAC9E,wBAAgB,2BAA2B,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,CAuB9D;AA4GD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,CAI3D;AAED,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,QAAQ,GAAG,OAAO,CAE5D"}