@gmickel/gno 1.17.0 → 1.19.0

package/src/core/retrieval-trace.ts

@@ -0,0 +1,472 @@
+/** Opt-in, local-only retrieval trace recording with privacy projections. */
+
+import { z } from "zod";
+
+import type {
+  RetrievalTraceConfig,
+  RetrievalTraceRedactionMode,
+} from "../config/retrieval-traces";
+import type {
+  RetrievalTraceAppendResult,
+  RetrievalTraceEventInput,
+  RetrievalTraceFingerprints,
+  RetrievalTraceJudgmentInput,
+  RetrievalTraceRunInput,
+  RetrievalTraceTerminalStatus,
+  StorePort,
+  StoreResult,
+} from "../store/types";
+
+import {
+  parseRetrievalTraceEventInput,
+  parseRetrievalTraceJudgmentInput,
+  parseRetrievalTraceRunInput,
+} from "../store/retrieval-trace-codec";
+import { err, ok } from "../store/types";
+import { canonicalizeRetrievalTraceFilters } from "./retrieval-trace-filter-normalization";
+
+const sha256Schema = z.string().regex(/^[a-f0-9]{64}$/);
+const gnoUriSchema = z
+  .string()
+  .max(4096)
+  .refine((value) => value.startsWith("gno://"), {
+    message: "Evidence URI must use the canonical gno:// reader identity",
+  });
+const queryModeSchema = z
+  .object({
+    mode: z.enum(["term", "intent", "hyde"]),
+    text: z.string().max(8192),
+  })
+  .strict();
+export const traceFiltersSchema = z
+  .object({
+    limit: z.number().int().positive().optional(),
+    minScore: z.number().min(0).max(1).optional(),
+    collection: z.string().max(256).optional(),
+    collections: z.array(z.string().min(1).max(256)).max(1000).optional(),
+    lang: z.string().max(64).optional(),
+    full: z.boolean().optional(),
+    lineNumbers: z.boolean().optional(),
+    tagsAll: z.array(z.string().max(512)).max(1000).optional(),
+    tagsAny: z.array(z.string().max(512)).max(1000).optional(),
+    since: z.string().max(128).optional(),
+    until: z.string().max(128).optional(),
+    categories: z.array(z.string().max(512)).max(1000).optional(),
+    author: z.string().max(1024).optional(),
+    intent: z.string().max(8192).optional(),
+    exclude: z.array(z.string().max(1024)).max(1000).optional(),
+    noExpand: z.boolean().optional(),
+    noRerank: z.boolean().optional(),
+    candidateLimit: z.number().int().positive().optional(),
+    explain: z.boolean().optional(),
+    graph: z.boolean().optional(),
+    noGraph: z.boolean().optional(),
+    queryLanguageHint: z.string().max(64).optional(),
+    queryModes: z.array(queryModeSchema).max(100).optional(),
+    uriPrefix: z.string().max(4096).optional(),
+  })
+  .strict();
+const startTraceSchema = z
+  .object({
+    traceId: z.string().min(1).max(128).optional(),
+    query: z.string().min(1).max(8192),
+    goal: z.string().max(8192).optional(),
+    filters: traceFiltersSchema.default({}),
+    fingerprints: z
+      .object({
+        pipeline: sha256Schema,
+        model: sha256Schema,
+        config: sha256Schema,
+        index: sha256Schema,
+      })
+      .strict(),
+  })
+  .strict();
+
+const evidenceRefBaseSchema = z
+  .object({
+    docid: z.string().min(1).max(256).optional(),
+    sourceHash: sha256Schema.optional(),
+    mirrorHash: sha256Schema.optional(),
+    uri: gnoUriSchema.optional(),
+    seq: z.number().int().nonnegative().optional(),
+    startLine: z.number().int().positive().optional(),
+    endLine: z.number().int().positive().optional(),
+    score: z.number().finite().optional(),
+    rank: z.number().int().positive().optional(),
+    plannerRank: z.number().int().positive().optional(),
+    passageHash: sha256Schema.optional(),
+    sources: z.array(z.string().min(1).max(128)).max(16).optional(),
+    graphExpanded: z.boolean().optional(),
+  })
+  .strict();
+const refineEvidenceRef = (
+  value: z.infer<typeof evidenceRefBaseSchema>,
+  context: z.RefinementCtx
+): void => {
+  if (!(value.docid || value.sourceHash || value.mirrorHash || value.uri)) {
+    context.addIssue({
+      code: "custom",
+      message: "Evidence references require a stable document identity",
+    });
+  }
+  if ((value.startLine === undefined) !== (value.endLine === undefined)) {
+    context.addIssue({
+      code: "custom",
+      message: "Evidence line ranges require both startLine and endLine",
+    });
+  }
+  if (
+    value.startLine !== undefined &&
+    value.endLine !== undefined &&
+    value.startLine > value.endLine
+  ) {
+    context.addIssue({
+      code: "custom",
+      path: ["endLine"],
+      message: "Evidence endLine must not precede startLine",
+    });
+  }
+};
+const evidenceRefSchema = evidenceRefBaseSchema.superRefine(refineEvidenceRef);
+const evidencePayloadSchema = z
+  .object({
+    evidence: z.array(evidenceRefSchema).max(10_000),
+    latencyMs: z.number().finite().nonnegative().optional(),
+  })
+  .strict();
+const retrievalPayloadSchema = z
+  .object({
+    ranked: z.array(evidenceRefSchema).max(10_000),
+    latencyMs: z.number().finite().nonnegative().optional(),
+    capabilities: z.array(z.string().min(1).max(128)).max(100).optional(),
+    fallbackCodes: z.array(z.string().min(1).max(128)).max(100).optional(),
+  })
+  .strict();
+const contextPayloadSchema = evidencePayloadSchema.extend({
+  capsuleId: z.string().min(1).max(256),
+});
+const runPayloadSchemas = {
+  retrieval: retrievalPayloadSchema,
+  context: contextPayloadSchema,
+  get: evidencePayloadSchema,
+} as const;
+const eventPayloadSchemas = {
+  query: z.object({ filterFingerprint: sha256Schema.optional() }).strict(),
+  retrieval: retrievalPayloadSchema,
+  context: contextPayloadSchema,
+  get: evidencePayloadSchema,
+  open: evidencePayloadSchema,
+  cite: evidencePayloadSchema,
+  pin: evidencePayloadSchema,
+  capability: z
+    .object({
+      capability: z.string().min(1).max(128),
+      status: z.enum(["attempted", "used", "unavailable", "failed"]),
+      reasonCode: z.string().min(1).max(128).optional(),
+    })
+    .strict(),
+  complete: z
+    .object({
+      outcome: z.enum(["completed", "partial", "failed", "cancelled"]),
+      latencyMs: z.number().finite().nonnegative().optional(),
+    })
+    .strict(),
+} as const;
+const judgmentTargetSchema = evidenceRefBaseSchema
+  .omit({
+    score: true,
+    rank: true,
+  })
+  .superRefine(refineEvidenceRef);
+
+export interface StartRetrievalTraceInput {
+  traceId?: string;
+  query: string;
+  goal?: string;
+  filters?: z.input<typeof traceFiltersSchema>;
+  fingerprints: RetrievalTraceFingerprints;
+}
+
+export type RetrievalTraceWriteResult =
+  | {
+      recorded: false;
+      traceId: null;
+      replayCapable: false;
+      result: "disabled";
+    }
+  | {
+      recorded: true;
+      traceId: string;
+      replayCapable: boolean;
+      result: RetrievalTraceAppendResult;
+    };
+
+interface RetrievalTraceRecorderDeps {
+  clock?: () => number;
+  idFactory?: () => string;
+  /** Stable local secret loaded by the caller; required for metadata labels. */
+  redactionSecret?: string;
+}
+
+/** Query + retrieval run + retrieval event + terminal event. */
+export const MIN_RETRIEVAL_TRACE_RECORDS = 4;
+
+const normalizeText = (value: string): string =>
+  value.replace(/\r\n/g, "\n").replace(/\r/g, "\n").normalize("NFC");
+
+const textShape = (value: string | undefined) => {
+  const normalized = normalizeText(value ?? "");
+  return {
+    characters: Array.from(normalized).length,
+    terms: normalized.trim() ? normalized.trim().split(/\s+/u).length : 0,
+  };
+};
+
+const sha256 = (value: string): string =>
+  new Bun.CryptoHasher("sha256").update(value).digest("hex");
+
+const valueShape = (value: unknown): unknown => {
+  if (value === null) return { type: "null" };
+  if (Array.isArray(value)) {
+    const itemTypes = [
+      ...new Set(
+        value.map((item) =>
+          item === null ? "null" : Array.isArray(item) ? "array" : typeof item
+        )
+      ),
+    ].sort();
+    return { type: "array", count: value.length, itemTypes };
+  }
+  if (typeof value === "object") {
+    const fields: Record<string, unknown> = {};
+    for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+      fields[key] = valueShape((value as Record<string, unknown>)[key]);
+    }
+    return { type: "object", fields };
+  }
+  return { type: typeof value };
+};
+
+const projectMetadataObject = (
+  value: Record<string, unknown>
+): Record<string, unknown> => ({ shape: valueShape(value) });
+
+const projectPayload = (
+  _mode: RetrievalTraceRedactionMode,
+  value: Record<string, unknown>
+): Record<string, unknown> => value;
+
+export class RetrievalTraceRecorder {
+  private readonly clock: () => number;
+  private readonly idFactory: () => string;
+  private readonly redactionSecret: string | undefined;
+
+  constructor(
+    private readonly store: StorePort,
+    private readonly config: RetrievalTraceConfig | undefined,
+    deps: RetrievalTraceRecorderDeps = {}
+  ) {
+    this.clock = deps.clock ?? Date.now;
+    this.idFactory = deps.idFactory ?? (() => crypto.randomUUID());
+    this.redactionSecret = deps.redactionSecret;
+  }
+
+  isEnabled(): boolean {
+    return this.config?.enabled === true;
+  }
+
+  async start(
+    input: StartRetrievalTraceInput
+  ): Promise<StoreResult<RetrievalTraceWriteResult>> {
+    if (
+      !this.config?.enabled ||
+      this.config.retention.maxRecordsPerTrace < MIN_RETRIEVAL_TRACE_RECORDS
+    ) {
+      return ok({
+        recorded: false,
+        traceId: null,
+        replayCapable: false,
+        result: "disabled",
+      });
+    }
+    const parsed = startTraceSchema.safeParse(input);
+    if (!parsed.success) {
+      return err("INVALID_INPUT", parsed.error.message, parsed.error);
+    }
+    const nowMs = this.clock();
+    if (!Number.isSafeInteger(nowMs) || nowMs < 0) {
+      return err("INVALID_INPUT", "Trace clock must return epoch milliseconds");
+    }
+    const traceId = parsed.data.traceId ?? this.idFactory();
+    const query = normalizeText(parsed.data.query);
+    const goal =
+      parsed.data.goal === undefined
+        ? undefined
+        : normalizeText(parsed.data.goal);
+    const filters = canonicalizeRetrievalTraceFilters(parsed.data.filters);
+    const replay = this.config.redactionMode === "replay";
+    const create = await this.store.createRetrievalTrace({
+      traceId,
+      schemaVersion: "1.0",
+      redactionMode: this.config.redactionMode,
+      replayCapable: replay,
+      queryText: replay ? query : null,
+      queryDigest: replay ? sha256(query) : null,
+      queryShape: textShape(query),
+      goalText: replay ? (goal ?? null) : null,
+      goalDigest: replay && goal !== undefined ? sha256(goal) : null,
+      goalShape: textShape(goal),
+      filters: replay ? filters : projectMetadataObject(filters),
+      fingerprints: parsed.data.fingerprints,
+      status: "open",
+      createdAtMs: nowMs,
+      updatedAtMs: nowMs,
+      expiresAtMs: nowMs + this.config.retention.maxAgeDays * 86_400_000,
+    });
+    if (!create.ok) return create;
+    const retention = await this.store.enforceRetrievalTraceRetention(
+      this.config.retention,
+      nowMs
+    );
+    if (!retention.ok) return retention;
+    const retained = await this.store.getRetrievalTrace(traceId);
+    if (!retained.ok) return retained;
+    if (!retained.value) {
+      return err(
+        "CONSTRAINT_VIOLATION",
+        `Retrieval trace ${traceId} exceeded retention limits and was evicted`
+      );
+    }
+    return ok({
+      recorded: true,
+      traceId,
+      replayCapable: replay,
+      result: create.value,
+    });
+  }
+
+  async appendRun(
+    input: RetrievalTraceRunInput
+  ): Promise<StoreResult<RetrievalTraceAppendResult | "disabled">> {
+    if (!this.config?.enabled) return ok("disabled");
+    const payload = runPayloadSchemas[input.kind]?.safeParse(input.payload);
+    if (!payload?.success) {
+      return err(
+        "INVALID_INPUT",
+        payload?.error.message ?? `Unknown retrieval run kind: ${input.kind}`
+      );
+    }
+    try {
+      const parsed = parseRetrievalTraceRunInput({
+        ...input,
+        payload: projectPayload(this.config.redactionMode, payload.data),
+      });
+      return await this.enforceAfterWrite(
+        input.traceId,
+        await this.store.appendRetrievalTraceRun(parsed)
+      );
+    } catch (cause) {
+      return invalidTraceInput(cause, "Invalid retrieval trace run");
+    }
+  }
+
+  async appendEvent(
+    input: RetrievalTraceEventInput
+  ): Promise<StoreResult<RetrievalTraceAppendResult | "disabled">> {
+    if (!this.config?.enabled) return ok("disabled");
+    const payload = eventPayloadSchemas[input.kind]?.safeParse(input.payload);
+    if (!payload?.success) {
+      return err(
+        "INVALID_INPUT",
+        payload?.error.message ?? `Unknown retrieval event kind: ${input.kind}`
+      );
+    }
+    try {
+      const parsed = parseRetrievalTraceEventInput({
+        ...input,
+        payload: projectPayload(this.config.redactionMode, payload.data),
+      });
+      return await this.enforceAfterWrite(
+        input.traceId,
+        await this.store.appendRetrievalTraceEvent(parsed)
+      );
+    } catch (cause) {
+      return invalidTraceInput(cause, "Invalid retrieval trace event");
+    }
+  }
+
+  async appendJudgment(
+    input: RetrievalTraceJudgmentInput
+  ): Promise<StoreResult<RetrievalTraceAppendResult | "disabled">> {
+    if (!this.config?.enabled) return ok("disabled");
+    const target = judgmentTargetSchema.safeParse(input.target);
+    if (!target.success) {
+      return err("INVALID_INPUT", target.error.message, target.error);
+    }
+    const metadata = this.config.redactionMode === "metadata";
+    if (metadata && !this.redactionSecret) {
+      return err(
+        "INVALID_INPUT",
+        "Metadata judgments require a stable local redaction secret"
+      );
+    }
+    try {
+      const parsed = parseRetrievalTraceJudgmentInput({
+        ...input,
+        targetRef: metadata
+          ? `redacted:${sha256(`${this.redactionSecret}\0${input.targetRef}`)}`
+          : input.targetRef,
+        target: projectPayload(this.config.redactionMode, target.data),
+      });
+      return await this.enforceAfterWrite(
+        input.traceId,
+        await this.store.appendRetrievalTraceJudgment(parsed)
+      );
+    } catch (cause) {
+      return invalidTraceInput(cause, "Invalid retrieval trace judgment");
+    }
+  }
+
+  async finalize(
+    traceId: string,
+    status: RetrievalTraceTerminalStatus
+  ): Promise<StoreResult<RetrievalTraceAppendResult | "disabled">> {
+    if (!this.config?.enabled) return ok("disabled");
+    return await this.enforceAfterWrite(
+      traceId,
+      await this.store.finalizeRetrievalTrace(traceId, status, this.clock())
+    );
+  }
+
+  private async enforceAfterWrite(
+    traceId: string,
+    result: StoreResult<RetrievalTraceAppendResult>
+  ): Promise<StoreResult<RetrievalTraceAppendResult>> {
+    if (!result.ok || !this.config?.enabled) return result;
+    const retained = await this.store.enforceRetrievalTraceRetention(
+      this.config.retention,
+      this.clock()
+    );
+    if (!retained.ok) return retained;
+    const stored = await this.store.getRetrievalTrace(traceId);
+    if (!stored.ok) return stored;
+    if (!stored.value) {
+      return err(
+        "CONSTRAINT_VIOLATION",
+        `Retrieval trace ${traceId} exceeded retention limits and was evicted`
+      );
+    }
+    return result;
+  }
+}
+
+const invalidTraceInput = <T>(
+  cause: unknown,
+  fallback: string
+): StoreResult<T> =>
+  err(
+    "INVALID_INPUT",
+    cause instanceof Error ? cause.message : fallback,
+    cause
+  );

package/src/llm/cache.ts

@@ -46,6 +46,7 @@ const HF_PATH_PATTERN = /^([^/]+)\/([^/]+)\/(.+\.gguf)$/;
 const GGUF_MAGIC = new Uint8Array([0x47, 0x47, 0x55, 0x46]);
 
 type ModelFileOwner = "cache" | "user";
+type ResolveModelFile = typeof import("node-llama-cpp").resolveModelFile;
 
 type ValidatedCachedPath =
   | { ok: true; path: string }
@@ -268,11 +269,16 @@ const MANIFEST_VERSION = "1.0" as const;
 export class ModelCache {
   readonly dir: string;
   private readonly manifestPath: string;
+  private readonly resolveModelFileFn?: ResolveModelFile;
   private manifest: Manifest | null = null;
 
-  constructor(cacheDir?: string) {
+  constructor(
+    cacheDir?: string,
+    deps?: { resolveModelFile?: ResolveModelFile }
+  ) {
     this.dir = cacheDir ?? getModelsCachePath();
     this.manifestPath = join(this.dir, "manifest.json");
+    this.resolveModelFileFn = deps?.resolveModelFile;
   }
 
   /**
@@ -324,7 +330,8 @@ export class ModelCache {
     uri: string,
     type: ModelType,
     onProgress?: ProgressCallback,
-    force?: boolean
+    force?: boolean,
+    signal?: AbortSignal
   ): Promise<LlmResult<string>> {
     const parsed = parseModelUri(uri);
     if (!parsed.ok) {
@@ -364,7 +371,9 @@ export class ModelCache {
     }
 
     try {
-      const { resolveModelFile } = await import("node-llama-cpp");
+      const resolveModelFile =
+        this.resolveModelFileFn ??
+        (await import("node-llama-cpp")).resolveModelFile;
 
       // Convert to node-llama-cpp format (handles quantization shorthand)
       // node-llama-cpp needs hf: prefix to identify HuggingFace models
@@ -399,6 +408,7 @@ export class ModelCache {
               }
             }
           : undefined,
+        signal,
       });
 
       const validation = await validateGgufFile(resolvedPath, uri, "cache");

package/src/llm/nodeLlamaCpp/adapter.ts

@@ -27,7 +27,11 @@ import {
 } from "../registry";
 import { NodeLlamaCppEmbedding } from "./embedding";
 import { NodeLlamaCppGeneration } from "./generation";
-import { getModelManager, type ModelManager } from "./lifecycle";
+import {
+  getModelManager,
+  type ModelLease,
+  type ModelManager,
+} from "./lifecycle";
 import { NodeLlamaCppRerank } from "./rerank";
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -218,6 +222,11 @@ export class LlmAdapter {
     return this.manager;
   }
 
+  /** Acquire an idempotent request lease without transferring manager ownership. */
+  acquireModelLease(): ModelLease {
+    return this.manager.acquireLease();
+  }
+
   /**
    * Dispose all resources.
    */

package/src/llm/nodeLlamaCpp/lifecycle.ts

@@ -35,6 +35,21 @@ interface CachedModel {
   loadedAt: number;
 }
 
+export interface ModelLease {
+  release(): void;
+}
+
+export interface ModelLifecycleStats {
+  activeLeases: number;
+  leaseAcquisitions: number;
+  leaseReleases: number;
+  loadedModels: number;
+  loadAttempts: number;
+  loadSuccesses: number;
+  loadFailures: number;
+  inflightLoads: number;
+}
+
 let invalidGpuModeWarned = false;
 let invalidBuildModeWarned = false;
 let gpuFallbackWarned = false;
@@ -134,7 +149,14 @@ export class ModelManager {
     new Map();
   private readonly inflightLoads: Map<string, Promise<LlmResult<LoadedModel>>> =
     new Map();
+  private readonly leaseDrainWaiters = new Set<() => void>();
   private readonly config: ModelConfig;
+  private activeLeases = 0;
+  private leaseAcquisitions = 0;
+  private leaseReleases = 0;
+  private loadAttempts = 0;
+  private loadSuccesses = 0;
+  private loadFailures = 0;
 
   constructor(config: ModelConfig) {
     this.config = config;
@@ -263,6 +285,7 @@ export class ModelManager {
     uri: string,
     type: ModelType
   ): Promise<LlmResult<LoadedModel>> {
+    this.loadAttempts += 1;
     const timeoutMs = this.config.loadTimeout;
     let timeoutId: ReturnType<typeof setTimeout> | null = null;
     let timedOut = false;
@@ -299,6 +322,7 @@ export class ModelManager {
 
       this.models.set(uri, cachedModel);
       this.setDisposalTimer(uri);
+      this.loadSuccesses += 1;
 
       return {
         ok: true,
@@ -310,6 +334,7 @@ export class ModelManager {
         },
       };
     } catch (e) {
+      this.loadFailures += 1;
       // Clear timeout on error
       if (timeoutId) {
         clearTimeout(timeoutId);
@@ -356,6 +381,42 @@ export class ModelManager {
     return model;
   }
 
+  /** Keep warm models alive while one request owns model-backed ports. */
+  acquireLease(): ModelLease {
+    this.activeLeases += 1;
+    this.leaseAcquisitions += 1;
+    for (const timer of this.disposalTimers.values()) clearTimeout(timer);
+    this.disposalTimers.clear();
+
+    let released = false;
+    return {
+      release: () => {
+        if (released) return;
+        released = true;
+        this.activeLeases = Math.max(0, this.activeLeases - 1);
+        this.leaseReleases += 1;
+        if (this.activeLeases === 0) {
+          for (const resolve of this.leaseDrainWaiters) resolve();
+          this.leaseDrainWaiters.clear();
+          for (const uri of this.models.keys()) this.setDisposalTimer(uri);
+        }
+      },
+    };
+  }
+
+  getLifecycleStats(): ModelLifecycleStats {
+    return {
+      activeLeases: this.activeLeases,
+      leaseAcquisitions: this.leaseAcquisitions,
+      leaseReleases: this.leaseReleases,
+      loadedModels: this.models.size,
+      loadAttempts: this.loadAttempts,
+      loadSuccesses: this.loadSuccesses,
+      loadFailures: this.loadFailures,
+      inflightLoads: this.inflightLoads.size,
+    };
+  }
+
   /**
    * Check if a model is loaded.
    */
@@ -367,6 +428,10 @@ export class ModelManager {
    * Dispose a specific model.
    */
   async dispose(uri: string): Promise<void> {
+    if (this.activeLeases > 0) {
+      this.resetDisposalTimer(uri);
+      return;
+    }
     const cached = this.models.get(uri);
     if (!cached) {
       return;
@@ -393,6 +458,11 @@ export class ModelManager {
    * Dispose all loaded models.
    */
   async disposeAll(): Promise<void> {
+    if (this.activeLeases > 0) {
+      await new Promise<void>((resolve) => this.leaseDrainWaiters.add(resolve));
+    }
+    await Promise.allSettled(this.inflightLoads.values());
+
     // Clear all timers
     for (const timer of this.disposalTimers.values()) {
       clearTimeout(timer);
@@ -429,6 +499,7 @@ export class ModelManager {
   // ───────────────────────────────────────────────────────────────────────────
 
   private setDisposalTimer(uri: string): void {
+    if (this.activeLeases > 0) return;
     const timer = setTimeout(() => {
       this.dispose(uri).catch(() => {
         // Ignore disposal errors in timer callback