@gmickel/gno 1.18.0 → 1.20.0

package/src/core/retrieval-trace-export.ts

@@ -0,0 +1,113 @@
+/** Aggregate retrieval trace export with manifest-bound verification. */
+
+import type {
+  RetrievalTraceBundle,
+  RetrievalTraceExportFormat,
+  StorePort,
+  StoreResult,
+} from "../store/types";
+import type {
+  ExportRetrievalTracesInput,
+  ExportRetrievalTracesResult,
+  RetrievalTraceArtifact,
+} from "./retrieval-trace-management-types";
+
+import { hashTraceCanonical } from "../store/retrieval-trace-codec";
+import { err, ok } from "../store/types";
+import { buildRetrievalQrelsArtifact } from "./retrieval-qrels";
+
+const validateTraceIds = (traceIds: unknown): StoreResult<string[]> => {
+  if (
+    !Array.isArray(traceIds) ||
+    traceIds.some(
+      (traceId) => typeof traceId !== "string" || traceId.length < 1
+    )
+  ) {
+    return err("INVALID_INPUT", "Export trace IDs must be a string array");
+  }
+  const normalized = [...new Set(traceIds)].sort((left, right) =>
+    left.localeCompare(right)
+  );
+  return normalized.length < 1 || normalized.length > 10_000
+    ? err("INVALID_INPUT", "Export requires from 1 to 10000 trace IDs")
+    : ok(normalized);
+};
+
+const agenticArtifact = (
+  bundles: RetrievalTraceBundle[]
+): RetrievalTraceArtifact => ({
+  schemaVersion: "1.0",
+  format: "agentic-receipt",
+  traces: bundles.map(({ exports: _exports, ...trace }) => trace),
+});
+
+const buildArtifact = (
+  format: "agentic-receipt" | "qrels",
+  bundles: RetrievalTraceBundle[]
+): StoreResult<RetrievalTraceArtifact> => {
+  if (format === "agentic-receipt") return ok(agenticArtifact(bundles));
+  return buildRetrievalQrelsArtifact(bundles);
+};
+
+export const exportRetrievalTraces = async <
+  Format extends RetrievalTraceExportFormat,
+>(
+  store: StorePort,
+  clock: () => number,
+  input: ExportRetrievalTracesInput<Format>
+): Promise<StoreResult<ExportRetrievalTracesResult<Format>>> => {
+  const format = input.format ?? "agentic-receipt";
+  if (!["agentic-receipt", "qrels"].includes(format)) {
+    return err("INVALID_INPUT", "Invalid retrieval trace export format");
+  }
+  const traceIds = validateTraceIds(input.traceIds);
+  if (!traceIds.ok) return traceIds;
+  const bundles: RetrievalTraceBundle[] = [];
+  for (const traceId of traceIds.value) {
+    const stored = await store.getRetrievalTrace(traceId);
+    if (!stored.ok) return stored;
+    if (!stored.value) return err("NOT_FOUND", "Retrieval trace not found");
+    if (stored.value.trace.status === "open") {
+      return err(
+        "CONSTRAINT_VIOLATION",
+        "Open retrieval traces cannot be exported"
+      );
+    }
+    bundles.push(stored.value);
+  }
+  const built = buildArtifact(format, bundles);
+  if (!built.ok) return built;
+  const artifactHash = hashTraceCanonical(built.value);
+  const exportId = `trace-export-${artifactHash.slice(0, 40)}`;
+  const appended = await store.appendRetrievalTraceExportManifest({
+    exportId,
+    traceIds: traceIds.value,
+    format,
+    artifactHash,
+    createdAtMs: clock(),
+  });
+  if (!appended.ok) return appended;
+  const complete = await store.getRetrievalTraceExportBundle(exportId);
+  if (!complete.ok) return complete;
+  if (!complete.value) {
+    return err("QUERY_FAILED", "Stored retrieval trace export is unavailable");
+  }
+  const reconstructed = buildArtifact(format, complete.value.traces);
+  if (!reconstructed.ok) return reconstructed;
+  if (
+    complete.value.manifest.traceIds.join("\0") !== traceIds.value.join("\0") ||
+    hashTraceCanonical(reconstructed.value) !==
+      complete.value.manifest.artifactHash
+  ) {
+    return err(
+      "CONSTRAINT_VIOLATION",
+      "manifest_hash_mismatch: stored retrieval trace export changed"
+    );
+  }
+  return ok({
+    schemaVersion: "1.0",
+    result: appended.value,
+    manifest: complete.value.manifest,
+    artifact: reconstructed.value,
+  } as ExportRetrievalTracesResult<Format>);
+};

package/src/core/retrieval-trace-filter-normalization.ts

@@ -0,0 +1,27 @@
+/** Deterministic set-like retrieval-filter normalization before persistence. */
+
+const SET_ARRAY_KEYS = [
+  "categories",
+  "collections",
+  "exclude",
+  "tagsAll",
+  "tagsAny",
+] as const;
+
+const compareCodeUnits = (left: string, right: string): number =>
+  left < right ? -1 : left > right ? 1 : 0;
+
+export const canonicalizeRetrievalTraceFilters = <
+  Filters extends Record<string, unknown>,
+>(
+  filters: Filters
+): Filters => {
+  const normalized: Record<string, unknown> = { ...filters };
+  for (const key of SET_ARRAY_KEYS) {
+    const values = filters[key];
+    if (Array.isArray(values)) {
+      normalized[key] = [...new Set(values)].sort(compareCodeUnits);
+    }
+  }
+  return normalized as Filters;
+};

package/src/core/retrieval-trace-filters.ts

@@ -0,0 +1,19 @@
+/** Canonical replay-filter parsing shared by qrels export and replay. */
+
+import type { StoreResult } from "../store/types";
+
+import { err, ok } from "../store/types";
+import { traceFiltersSchema } from "./retrieval-trace";
+import { canonicalizeRetrievalTraceFilters } from "./retrieval-trace-filter-normalization";
+
+export type RetrievalTraceFilters = Record<string, unknown>;
+
+export const parseRetrievalTraceFilters = (
+  value: unknown
+): StoreResult<RetrievalTraceFilters> => {
+  const parsed = traceFiltersSchema.safeParse(value);
+  if (!parsed.success) {
+    return err("INVALID_INPUT", `filters_incomplete: ${parsed.error.message}`);
+  }
+  return ok(canonicalizeRetrievalTraceFilters(parsed.data));
+};

package/src/core/retrieval-trace-management-helpers.ts

@@ -0,0 +1,247 @@
+import type {
+  RetrievalTraceBundle,
+  RetrievalTraceCursor,
+  RetrievalTraceJudgmentRow,
+  StoreResult,
+} from "../store/types";
+import type {
+  LabelRetrievalTraceInput,
+  RetrievalTraceSummary,
+} from "./retrieval-trace-management-types";
+
+import { hashTraceCanonical } from "../store/retrieval-trace-codec";
+import { err, ok } from "../store/types";
+
+export type EvidenceTarget = {
+  docid?: string;
+  sourceHash?: string;
+  mirrorHash?: string;
+  uri?: string;
+  seq?: number;
+  startLine?: number;
+  endLine?: number;
+  passageHash?: string;
+};
+
+export interface EvidenceMatch {
+  target: EvidenceTarget;
+  runId: string | null;
+}
+
+export const compactTarget = (target: EvidenceTarget): EvidenceTarget =>
+  Object.fromEntries(
+    Object.entries(target).filter(([, value]) => value !== undefined)
+  ) as EvidenceTarget;
+
+export const summaryOf = (
+  trace: RetrievalTraceBundle["trace"]
+): RetrievalTraceSummary => ({
+  traceId: trace.traceId,
+  schemaVersion: trace.schemaVersion,
+  redactionMode: trace.redactionMode,
+  replayCapable: trace.replayCapable,
+  status: trace.status,
+  queryShape: trace.queryShape,
+  goalShape: trace.goalShape,
+  fingerprints: trace.fingerprints,
+  createdAtMs: trace.createdAtMs,
+  updatedAtMs: trace.updatedAtMs,
+  expiresAtMs: trace.expiresAtMs,
+  byteSize: trace.byteSize,
+  creationDigest: trace.creationDigest,
+});
+
+const TRACE_CURSOR_PREFIX = "gno-trace-v1.";
+const TRACE_CURSOR_KEYS = ["createdAtMs", "traceId"] as const;
+
+export const encodeCursor = (cursor: RetrievalTraceCursor): string => {
+  const payload = new TextEncoder().encode(
+    JSON.stringify({
+      createdAtMs: cursor.createdAtMs,
+      traceId: cursor.traceId,
+    })
+  );
+  return `${TRACE_CURSOR_PREFIX}${payload.toBase64({
+    alphabet: "base64url",
+    omitPadding: true,
+  })}`;
+};
+
+export const decodeCursor = (
+  value: string | undefined
+): StoreResult<RetrievalTraceCursor | undefined> => {
+  if (value === undefined) return ok(undefined);
+  if (!value.startsWith(TRACE_CURSOR_PREFIX)) {
+    return err("INVALID_INPUT", "Invalid trace cursor");
+  }
+  let decoded: unknown;
+  try {
+    const bytes = Uint8Array.fromBase64(
+      value.slice(TRACE_CURSOR_PREFIX.length),
+      {
+        alphabet: "base64url",
+      }
+    );
+    decoded = JSON.parse(
+      new TextDecoder("utf-8", { fatal: true }).decode(bytes)
+    );
+  } catch {
+    return err("INVALID_INPUT", "Invalid trace cursor");
+  }
+  if (!decoded || typeof decoded !== "object" || Array.isArray(decoded)) {
+    return err("INVALID_INPUT", "Invalid trace cursor");
+  }
+  const record = decoded as Record<string, unknown>;
+  if (
+    Object.keys(record).length !== TRACE_CURSOR_KEYS.length ||
+    TRACE_CURSOR_KEYS.some((key) => !(key in record))
+  ) {
+    return err("INVALID_INPUT", "Invalid trace cursor");
+  }
+  const { createdAtMs, traceId } = record;
+  if (
+    !Number.isSafeInteger(createdAtMs) ||
+    (createdAtMs as number) < 0 ||
+    typeof traceId !== "string" ||
+    traceId.length < 1 ||
+    traceId.length > 128
+  ) {
+    return err("INVALID_INPUT", "Invalid trace cursor");
+  }
+  return ok({ createdAtMs: createdAtMs as number, traceId });
+};
+
+export const stableTarget = (value: unknown): EvidenceTarget | null => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const record = value as Record<string, unknown>;
+  const target: EvidenceTarget = {};
+  for (const key of [
+    "docid",
+    "sourceHash",
+    "mirrorHash",
+    "uri",
+    "passageHash",
+  ] as const) {
+    if (typeof record[key] === "string") target[key] = record[key];
+  }
+  for (const key of ["seq", "startLine", "endLine"] as const) {
+    if (typeof record[key] === "number") target[key] = record[key];
+  }
+  return target.docid || target.sourceHash || target.mirrorHash || target.uri
+    ? target
+    : null;
+};
+
+const payloadEvidence = (
+  payload: Record<string, unknown>
+): EvidenceTarget[] => {
+  const found: EvidenceTarget[] = [];
+  for (const key of ["ranked", "evidence"] as const) {
+    const values = payload[key];
+    if (!Array.isArray(values)) continue;
+    for (const value of values) {
+      const target = stableTarget(value);
+      if (target) found.push(target);
+    }
+  }
+  return found;
+};
+
+export const allEvidence = (bundle: RetrievalTraceBundle): EvidenceMatch[] => [
+  ...bundle.runs.flatMap((run) =>
+    payloadEvidence(run.payload).map((target) => ({
+      target,
+      runId: run.runId,
+    }))
+  ),
+  ...bundle.events.flatMap((event) =>
+    payloadEvidence(event.payload).map((target) => ({
+      target,
+      runId: event.runId,
+    }))
+  ),
+];
+
+export const refMatches = (target: EvidenceTarget, ref: string): boolean =>
+  [
+    target.uri,
+    target.docid,
+    target.sourceHash,
+    target.mirrorHash,
+    target.passageHash,
+  ].includes(ref);
+
+export const applyTargetKind = (
+  target: EvidenceTarget,
+  input: LabelRetrievalTraceInput
+): StoreResult<EvidenceTarget> => {
+  const targetKind =
+    input.targetKind ??
+    (input.startLine === undefined
+      ? target.seq === undefined
+        ? "document"
+        : "chunk"
+      : "span");
+  if ((input.startLine === undefined) !== (input.endLine === undefined)) {
+    return err("INVALID_INPUT", "Trace span labels require both line bounds");
+  }
+  if (
+    input.startLine !== undefined &&
+    (input.startLine < 1 ||
+      input.endLine! < input.startLine ||
+      target.startLine !== input.startLine ||
+      target.endLine !== input.endLine)
+  ) {
+    return err(
+      "INVALID_INPUT",
+      "Trace label does not match an exact evidence span"
+    );
+  }
+  if (input.sourceHash && target.sourceHash !== input.sourceHash) {
+    return err(
+      "INVALID_INPUT",
+      "Trace label source hash does not match evidence"
+    );
+  }
+  if (input.docid && target.docid !== input.docid) {
+    return err("INVALID_INPUT", "Trace label docid does not match evidence");
+  }
+  if (targetKind === "span" && target.startLine === undefined) {
+    return err(
+      "INVALID_INPUT",
+      "Span labels require exact recorded evidence lines"
+    );
+  }
+  if (targetKind === "chunk" && target.seq === undefined) {
+    return err(
+      "INVALID_INPUT",
+      "Chunk labels require a recorded chunk sequence"
+    );
+  }
+  if (targetKind === "document") {
+    const { docid, sourceHash, mirrorHash, uri } = target;
+    return ok(compactTarget({ docid, sourceHash, mirrorHash, uri }));
+  }
+  return ok(target);
+};
+
+export const targetKey = (
+  targetKind: NonNullable<LabelRetrievalTraceInput["targetKind"]>,
+  target: EvidenceTarget
+): string => hashTraceCanonical({ targetKind, target });
+
+export const latestForTarget = (
+  judgments: RetrievalTraceJudgmentRow[],
+  key: string
+): RetrievalTraceJudgmentRow | undefined =>
+  judgments
+    .filter(
+      (judgment) =>
+        targetKey(
+          judgment.targetKind as NonNullable<
+            LabelRetrievalTraceInput["targetKind"]
+          >,
+          stableTarget(judgment.target) ?? {}
+        ) === key
+    )
+    .at(-1);

package/src/core/retrieval-trace-management-types.ts

@@ -0,0 +1,132 @@
+import type {
+  RetrievalTraceAppendResult,
+  RetrievalTraceBundle,
+  RetrievalTraceDeleteCounts,
+  RetrievalTraceExportFormat,
+  RetrievalTraceExportManifestRow,
+  RetrievalTraceJudgmentLabel,
+  RetrievalTraceJudgmentRow,
+  RetrievalTraceJudgmentTargetKind,
+  RetrievalTracePurgeResult as StoredRetrievalTracePurgeResult,
+  RetrievalTraceRow,
+} from "../store/types";
+import type { RetrievalTraceQrelsArtifact } from "./retrieval-qrels";
+
+export interface RetrievalTraceSummary {
+  traceId: string;
+  schemaVersion: "1.0";
+  redactionMode: RetrievalTraceRow["redactionMode"];
+  replayCapable: boolean;
+  status: RetrievalTraceRow["status"];
+  queryShape: RetrievalTraceRow["queryShape"];
+  goalShape: RetrievalTraceRow["goalShape"];
+  fingerprints: RetrievalTraceRow["fingerprints"];
+  createdAtMs: number;
+  updatedAtMs: number;
+  expiresAtMs: number;
+  byteSize: number;
+  creationDigest: string;
+}
+
+export interface RetrievalTraceListOptions {
+  limit?: number;
+  cursor?: string;
+}
+
+export interface RetrievalTraceListResult {
+  schemaVersion: "1.0";
+  traces: RetrievalTraceSummary[];
+  nextCursor: string | null;
+}
+
+export interface RetrievalTraceDetailOptions {
+  detailLimit?: number;
+}
+
+export interface RetrievalTraceDetail extends Omit<
+  RetrievalTraceBundle,
+  "runs" | "events" | "judgments" | "exports"
+> {
+  schemaVersion: "1.0";
+  runs: RetrievalTraceBundle["runs"];
+  events: RetrievalTraceBundle["events"];
+  judgments: RetrievalTraceBundle["judgments"];
+  exports: RetrievalTraceBundle["exports"];
+  totals: {
+    runs: number;
+    events: number;
+    judgments: number;
+    exports: number;
+  };
+  truncated: {
+    runs: boolean;
+    events: boolean;
+    judgments: boolean;
+    exports: boolean;
+  };
+}
+
+export interface LabelRetrievalTraceInput {
+  traceId: string;
+  label: RetrievalTraceJudgmentLabel;
+  targetRef: string;
+  targetKind?: Exclude<RetrievalTraceJudgmentTargetKind, "query">;
+  startLine?: number;
+  endLine?: number;
+  sourceHash?: string;
+  docid?: string;
+  idempotencyKey?: string;
+}
+
+export interface LabelRetrievalTraceResult {
+  schemaVersion: "1.0";
+  result: RetrievalTraceAppendResult;
+  judgment: RetrievalTraceJudgmentRow;
+}
+
+export interface RetrievalTraceAgenticArtifact {
+  schemaVersion: "1.0";
+  format: "agentic-receipt";
+  traces: Array<Omit<RetrievalTraceBundle, "exports">>;
+}
+
+export type RetrievalTraceArtifact =
+  | RetrievalTraceAgenticArtifact
+  | RetrievalTraceQrelsArtifact;
+
+export interface ExportRetrievalTracesInput<
+  Format extends RetrievalTraceExportFormat = "agentic-receipt",
+> {
+  traceIds: string[];
+  format?: Format;
+}
+
+export interface ExportRetrievalTracesResult<
+  Format extends RetrievalTraceExportFormat = "agentic-receipt",
+> {
+  schemaVersion: "1.0";
+  result: RetrievalTraceAppendResult;
+  manifest: RetrievalTraceExportManifestRow;
+  artifact: Format extends "qrels"
+    ? RetrievalTraceQrelsArtifact
+    : RetrievalTraceAgenticArtifact;
+}
+
+export interface DeleteRetrievalTraceResult {
+  schemaVersion: "1.0";
+  traceId: string;
+  deleted: boolean;
+  counts: RetrievalTraceDeleteCounts;
+}
+
+export interface PurgeRetrievalTracesResult extends StoredRetrievalTracePurgeResult {
+  schemaVersion: "1.0";
+}
+
+export type RetrievalTraceListRequest = RetrievalTraceListOptions;
+export type RetrievalTraceLabelRequest = LabelRetrievalTraceInput;
+export type RetrievalTraceExportRequest = ExportRetrievalTracesInput;
+export type RetrievalTraceLabelResult = LabelRetrievalTraceResult;
+export type RetrievalTraceExportResult = ExportRetrievalTracesResult;
+export type RetrievalTraceDeleteResult = DeleteRetrievalTraceResult;
+export type RetrievalTracePurgeResult = PurgeRetrievalTracesResult;