@gmickel/gno 1.18.0 → 1.19.0

package/src/store/types.ts

@@ -346,6 +346,8 @@ export interface FtsSearchOptions {
   limit?: number;
   /** Filter by collection */
   collection?: string;
+  /** Internal exact relative-path boundary applied before ranking and LIMIT. */
+  relPathPrefix?: string;
   /**
    * Language hint (reserved for future use).
    * Note: FTS5 snowball tokenizer is language-aware at index time,
@@ -816,6 +818,220 @@ export interface ActivationIndexSnapshot {
   documents: ActivationIndexDocument[];
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Private Retrieval Trace Receipts
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type RetrievalTraceRedactionMode = "metadata" | "replay";
+export type RetrievalTraceTerminalStatus =
+  | "completed"
+  | "partial"
+  | "failed"
+  | "cancelled";
+export type RetrievalTraceStatus = "open" | RetrievalTraceTerminalStatus;
+export type RetrievalTraceJudgmentLabel =
+  | "relevant"
+  | "irrelevant"
+  | "missing_expected";
+export type RetrievalTraceJudgmentTargetKind =
+  | "document"
+  | "chunk"
+  | "span"
+  | "query";
+export type RetrievalTraceAppendResult = "inserted" | "duplicate";
+export type RetrievalTraceRunKind = "retrieval" | "context" | "get";
+export type RetrievalTraceEventKind =
+  | "query"
+  | "retrieval"
+  | "context"
+  | "get"
+  | "open"
+  | "cite"
+  | "pin"
+  | "capability"
+  | "complete";
+export type RetrievalTraceExportFormat = "agentic-receipt" | "qrels";
+
+export interface RetrievalTraceFingerprints {
+  pipeline: string;
+  model: string;
+  config: string;
+  index: string;
+}
+
+/** Already-redacted trace header persisted by StorePort implementations. */
+export interface RetrievalTraceInput {
+  traceId: string;
+  schemaVersion: "1.0";
+  redactionMode: RetrievalTraceRedactionMode;
+  replayCapable: boolean;
+  queryText: string | null;
+  queryDigest: string | null;
+  queryShape: {
+    characters: number;
+    terms: number;
+  };
+  goalText: string | null;
+  goalDigest: string | null;
+  goalShape: {
+    characters: number;
+    terms: number;
+  };
+  filters: Record<string, unknown>;
+  fingerprints: RetrievalTraceFingerprints;
+  status: "open";
+  createdAtMs: number;
+  updatedAtMs: number;
+  expiresAtMs: number;
+}
+
+export type RetrievalTraceRow = Omit<
+  RetrievalTraceInput,
+  "status" | "updatedAtMs"
+> & {
+  status: RetrievalTraceStatus;
+  updatedAtMs: number;
+  byteSize: number;
+  /** Digest of immutable creation fields; terminal status/time are excluded. */
+  creationDigest: string;
+};
+
+export interface RetrievalTraceRunInput {
+  runId: string;
+  traceId: string;
+  idempotencyKey: string;
+  kind: RetrievalTraceRunKind;
+  payload: Record<string, unknown>;
+  createdAtMs: number;
+}
+
+export type RetrievalTraceRunRow = RetrievalTraceRunInput & {
+  payloadBytes: number;
+  canonicalDigest: string;
+};
+
+export interface RetrievalTraceEventInput {
+  eventId: string;
+  traceId: string;
+  runId: string | null;
+  idempotencyKey: string;
+  kind: RetrievalTraceEventKind;
+  payload: Record<string, unknown>;
+  createdAtMs: number;
+}
+
+export type RetrievalTraceEventRow = RetrievalTraceEventInput & {
+  payloadBytes: number;
+  canonicalDigest: string;
+};
+
+export interface RetrievalTraceJudgmentInput {
+  judgmentId: string;
+  traceId: string;
+  runId: string | null;
+  idempotencyKey: string;
+  label: RetrievalTraceJudgmentLabel;
+  targetKind: RetrievalTraceJudgmentTargetKind;
+  targetRef: string;
+  target: Record<string, unknown>;
+  createdAtMs: number;
+}
+
+export type RetrievalTraceJudgmentRow = RetrievalTraceJudgmentInput & {
+  targetBytes: number;
+  canonicalDigest: string;
+};
+
+export interface RetrievalTraceExportInput {
+  exportId: string;
+  traceId: string;
+  format: RetrievalTraceExportFormat;
+  artifactHash: string;
+  createdAtMs: number;
+}
+
+export interface RetrievalTraceExportRow extends RetrievalTraceExportInput {}
+
+export interface RetrievalTraceCursor {
+  createdAtMs: number;
+  traceId: string;
+}
+
+export interface RetrievalTraceExportManifestInput {
+  exportId: string;
+  traceIds: string[];
+  format: RetrievalTraceExportFormat;
+  artifactHash: string;
+  createdAtMs: number;
+}
+
+export interface RetrievalTraceExportManifestRow extends Omit<
+  RetrievalTraceExportManifestInput,
+  "traceIds"
+> {
+  traceIds: string[];
+}
+
+export interface RetrievalTraceBundle {
+  trace: RetrievalTraceRow;
+  runs: RetrievalTraceRunRow[];
+  events: RetrievalTraceEventRow[];
+  judgments: RetrievalTraceJudgmentRow[];
+  exports: RetrievalTraceExportRow[];
+}
+
+/** One aggregate export identity and every complete linked trace bundle. */
+export interface RetrievalTraceExportBundle {
+  manifest: RetrievalTraceExportManifestRow;
+  traces: RetrievalTraceBundle[];
+}
+
+export interface RetrievalTraceBundleTotals {
+  runs: number;
+  events: number;
+  judgments: number;
+  exports: number;
+}
+
+export interface RetrievalTraceBoundedBundle {
+  bundle: RetrievalTraceBundle;
+  totals: RetrievalTraceBundleTotals;
+}
+
+export interface RetrievalTraceRetentionPolicy {
+  maxAgeDays: number;
+  maxTraces: number;
+  maxRecordsPerTrace: number;
+  maxBytes: number;
+}
+
+export interface RetrievalTraceDeleteCounts {
+  traces: number;
+  runs: number;
+  events: number;
+  judgments: number;
+  exports: number;
+  exportLinks: number;
+}
+
+export interface RetrievalTraceRetentionResult {
+  deleted: RetrievalTraceDeleteCounts;
+  deletedTraceIds: string[];
+  remainingTraces: number;
+  remainingBytes: number;
+}
+
+export type RetrievalTracePhysicalCleanupStatus =
+  | "completed"
+  | "wal_busy"
+  | "failed";
+
+export interface RetrievalTracePurgeResult extends RetrievalTraceDeleteCounts {
+  physicalCleanup: RetrievalTracePhysicalCleanupStatus;
+  checkpointedFrames: number;
+  remainingWalFrames: number;
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Transaction Types
 // ─────────────────────────────────────────────────────────────────────────────
@@ -925,6 +1141,87 @@ export interface StorePort {
     receipt: ActivationVerificationReceipt
   ): Promise<StoreResult<void>>;
 
+  /** Persist an already-redacted, versioned retrieval trace header. */
+  createRetrievalTrace(
+    trace: RetrievalTraceInput
+  ): Promise<StoreResult<RetrievalTraceAppendResult>>;
+
+  /** Return a trace and all of its locally stored subordinate records. */
+  getRetrievalTrace(
+    traceId: string
+  ): Promise<StoreResult<RetrievalTraceBundle | null>>;
+
+  /** Read bounded subordinate detail while returning exact aggregate counts. */
+  getBoundedRetrievalTrace(
+    traceId: string,
+    detailLimit: number
+  ): Promise<StoreResult<RetrievalTraceBoundedBundle | null>>;
+
+  /** List trace headers newest-first with a bounded caller-selected limit. */
+  listRetrievalTraces(
+    limit: number,
+    cursor?: RetrievalTraceCursor
+  ): Promise<StoreResult<RetrievalTraceRow[]>>;
+
+  /** Transition an open trace to one explicit terminal outcome idempotently. */
+  finalizeRetrievalTrace(
+    traceId: string,
+    status: RetrievalTraceTerminalStatus,
+    updatedAtMs: number
+  ): Promise<StoreResult<RetrievalTraceAppendResult>>;
+
+  /** Append a run once per trace-scoped idempotency key. */
+  appendRetrievalTraceRun(
+    run: RetrievalTraceRunInput
+  ): Promise<StoreResult<RetrievalTraceAppendResult>>;
+
+  /** Append an event once per trace-scoped idempotency key. */
+  appendRetrievalTraceEvent(
+    event: RetrievalTraceEventInput
+  ): Promise<StoreResult<RetrievalTraceAppendResult>>;
+
+  /** Append an explicit judgment once per trace-scoped idempotency key. */
+  appendRetrievalTraceJudgment(
+    judgment: RetrievalTraceJudgmentInput
+  ): Promise<StoreResult<RetrievalTraceAppendResult>>;
+
+  /** Record a locally produced explicit export receipt idempotently. */
+  appendRetrievalTraceExport(
+    traceExport: RetrievalTraceExportInput
+  ): Promise<StoreResult<RetrievalTraceAppendResult>>;
+
+  /** Record one export manifest and all sorted trace memberships atomically. */
+  appendRetrievalTraceExportManifest(
+    manifest: RetrievalTraceExportManifestInput
+  ): Promise<StoreResult<RetrievalTraceAppendResult>>;
+
+  /** Read one aggregate export manifest with stable sorted membership. */
+  getRetrievalTraceExportManifest(
+    exportId: string
+  ): Promise<StoreResult<RetrievalTraceExportManifestRow | null>>;
+
+  /** Read one export and all linked traces without bounded-detail truncation. */
+  getRetrievalTraceExportBundle(
+    exportId: string
+  ): Promise<StoreResult<RetrievalTraceExportBundle | null>>;
+
+  /** Durable random index-local secret used only to redact metadata labels. */
+  getOrCreateRetrievalTraceRedactionSecret(): Promise<StoreResult<string>>;
+
+  /** Delete one trace and report exact cascade counts. */
+  deleteRetrievalTrace(
+    traceId: string
+  ): Promise<StoreResult<RetrievalTraceDeleteCounts>>;
+
+  /** Delete every trace and subordinate record in one transaction. */
+  purgeRetrievalTraces(): Promise<StoreResult<RetrievalTracePurgeResult>>;
+
+  /** Apply deterministic time, row, and byte retention limits. */
+  enforceRetrievalTraceRetention(
+    policy: RetrievalTraceRetentionPolicy,
+    nowMs: number
+  ): Promise<StoreResult<RetrievalTraceRetentionResult>>;
+
   // ─────────────────────────────────────────────────────────────────────────
   // Documents
   // ─────────────────────────────────────────────────────────────────────────

package/src/store/vector/sqlite-vec.ts

@@ -74,6 +74,16 @@ function formatUnavailableMessage(loadError?: string): string {
   return `Vector search requires sqlite-vec. Embeddings are stored, but KNN search is disabled.${reason} ${SQLITE_VEC_GUIDANCE}`;
 }
 
+const ALLOWED_HASH_BATCH_SIZE = 800;
+
+const compareVectorResults = (
+  left: VectorSearchResult,
+  right: VectorSearchResult
+): number =>
+  left.distance - right.distance ||
+  left.mirrorHash.localeCompare(right.mirrorHash) ||
+  left.seq - right.seq;
+
 /**
  * Create a VectorIndexPort for a specific model.
  * sqlite-vec is optional - storage works without it, search disabled.
@@ -243,15 +253,80 @@ export async function createVectorIndexPort(
     searchNearest(
       embedding: Float32Array,
       k: number,
-      searchOptions?: { minScore?: number }
+      searchOptions?: {
+        minScore?: number;
+        allowedMirrorHashes?: string[];
+      }
     ): Promise<StoreResult<VectorSearchResult[]>> {
       if (!(searchAvailable && searchStmt)) {
         return Promise.resolve(
           err("VEC_SEARCH_UNAVAILABLE", formatUnavailableMessage(loadError))
         );
       }
+      if (!Number.isSafeInteger(k) || k < 1) {
+        return Promise.resolve(
+          err("INVALID_INPUT", "Vector search limit must be a positive integer")
+        );
+      }
 
       try {
+        const allowed = searchOptions?.allowedMirrorHashes;
+        if (allowed) {
+          const hashes = [
+            ...new Set(allowed.filter((hash) => hash.length > 0)),
+          ].sort();
+          if (hashes.length === 0) return Promise.resolve(ok([]));
+          const distanceFunction =
+            distanceMetric === "cosine"
+              ? "vec_distance_cosine"
+              : "vec_distance_L2";
+          const scoped: VectorSearchResult[] = [];
+          for (
+            let index = 0;
+            index < hashes.length;
+            index += ALLOWED_HASH_BATCH_SIZE
+          ) {
+            const batch = hashes.slice(index, index + ALLOWED_HASH_BATCH_SIZE);
+            const placeholders = batch.map(() => "?").join(",");
+            const rows = db
+              .query<
+                {
+                  mirror_hash: string;
+                  seq: number;
+                  distance: number;
+                },
+                (Uint8Array | string | number)[]
+              >(
+                `SELECT mirror_hash, seq,
+                        ${distanceFunction}(embedding, ?) AS distance
+                 FROM content_vectors
+                 WHERE model = ?
+                   AND mirror_hash IN (${placeholders})
+                 ORDER BY distance, mirror_hash, seq
+                 LIMIT ?`
+              )
+              .all(encodeEmbedding(embedding), model, ...batch, k);
+            scoped.push(
+              ...rows.map((row) => ({
+                mirrorHash: row.mirror_hash,
+                seq: row.seq,
+                distance: row.distance,
+              }))
+            );
+          }
+          const minScore = searchOptions.minScore;
+          return Promise.resolve(
+            ok(
+              scoped
+                .sort(compareVectorResults)
+                .filter(
+                  (row) =>
+                    minScore === undefined || 1 - row.distance >= minScore
+                )
+                .slice(0, k)
+            )
+          );
+        }
         const results = searchStmt.all(encodeEmbedding(embedding), k) as {
           chunk_id: string;
           distance: number;

package/src/store/vector/types.ts

@@ -84,7 +84,7 @@ export interface VectorIndexPort {
   searchNearest(
     embedding: Float32Array,
     k: number,
-    options?: { minScore?: number }
+    options?: { minScore?: number; allowedMirrorHashes?: string[] }
   ): Promise<StoreResult<VectorSearchResult[]>>;
 
   // ─────────────────────────────────────────────────────────────────────────