@iislee/opencodex 2.11.0 → 2.31.0

package/src/lab/query/latest-observation.ts

@@ -0,0 +1,59 @@
+import type { EvidenceLayer } from "../constants";
+import { closeLabReadConnection, openLabReadConnection } from "./connection";
+
+export interface LatestLabObservationIdentity {
+  layer: EvidenceLayer;
+  subjectId: string;
+  suiteId: string;
+  suiteVersion: string;
+  suiteManifestDigest: string;
+  scenarioId: string;
+  scenarioVersion: string;
+  scenarioManifestDigest: string;
+}
+
+/**
+ * Return the newest non-excluded observation for one exact evidence identity.
+ *
+ * The projection schema provides a composite index for every identity predicate
+ * and the descending freshness order, so planner work is independent of unrelated
+ * observation history retained for the same subject.
+ */
+export function queryLatestLabObservation(
+  identity: LatestLabObservationIdentity,
+  configDir?: string,
+): number | undefined {
+  const conn = openLabReadConnection(configDir);
+  try {
+    const row = conn.db
+      .query(
+        `SELECT o.completed_at
+         FROM observations o
+         JOIN events e ON e.event_id = o.event_id
+         WHERE o.evidence_layer = ?
+           AND o.subject_id = ?
+           AND o.suite_id = ?
+           AND o.suite_version = ?
+           AND o.suite_manifest_digest = ?
+           AND o.scenario_id = ?
+           AND o.scenario_version = ?
+           AND o.scenario_manifest_digest = ?
+           AND e.excluded = 0
+         ORDER BY o.completed_at DESC, o.event_id DESC
+         LIMIT 1`,
+      )
+      .get(
+        identity.layer,
+        identity.subjectId,
+        identity.suiteId,
+        identity.suiteVersion,
+        identity.suiteManifestDigest,
+        identity.scenarioId,
+        identity.scenarioVersion,
+        identity.scenarioManifestDigest,
+      ) as { completed_at: number } | null;
+    return row ? Number(row.completed_at) : undefined;
+  } finally {
+    closeLabReadConnection(conn);
+  }
+}

package/src/lab/query/passive-production.ts

@@ -0,0 +1,159 @@
+import {
+  isLabRouteSubjectId,
+  readRecentUsageEntries,
+  type PersistedUsageAttempt,
+  type PersistedUsageEntry,
+} from "../../usage/log";
+
+export const PASSIVE_PRODUCTION_DEFAULT_LIMIT = 50;
+export const PASSIVE_PRODUCTION_MAX_LIMIT = 200;
+export const PASSIVE_PRODUCTION_MAX_SCAN_ROWS = 2_000;
+
+export type PassiveProductionOutcome =
+  | "success"
+  | "client_cancel"
+  | "route_error"
+  | "environmental"
+  | "unknown";
+
+export interface PassiveRouteSignalV1 {
+  schemaVersion: 1;
+  subjectId: string;
+  source: "production_usage_v1";
+  requestRef: string;
+  decisionRef?: string;
+  attemptOrdinal: number;
+  observedAt: number;
+  outcome: PassiveProductionOutcome;
+  httpStatus?: number;
+}
+
+export interface PassiveProductionSummaryV1 {
+  schemaVersion: 1;
+  subjectId: string;
+  verificationStatus: "not_verification";
+  recentProductionAttempts: number;
+  recentSuccessfulAttempts: number;
+  recentRouteErrorSignals: number;
+  lastObservedProductionAttempt?: number;
+}
+
+export interface PassiveProductionQueryResultV1 {
+  schemaVersion: 1;
+  verificationStatus: "not_verification";
+  summary: PassiveProductionSummaryV1;
+  signals: PassiveRouteSignalV1[];
+  scannedRows: number;
+  truncated: boolean;
+}
+
+const ROUTE_ERROR_CODES = new Set([
+  "upstream_error",
+  "upstream_transport_error",
+  "upstream_connect_error",
+  "upstream_timeout",
+]);
+const ENVIRONMENTAL_ERROR_CODES = new Set([
+  "authentication_error",
+  "rate_limit_error",
+  "admission_rejected",
+  "upstream_host_circuit_open",
+]);
+
+function boundedLimit(value: number | undefined): number {
+  if (value === undefined) return PASSIVE_PRODUCTION_DEFAULT_LIMIT;
+  if (!Number.isSafeInteger(value) || value < 1) throw new RangeError("passive production limit must be a positive integer");
+  return Math.min(value, PASSIVE_PRODUCTION_MAX_LIMIT);
+}
+
+function isFinalAttempt(entry: PersistedUsageEntry, attempt: PersistedUsageAttempt): boolean {
+  const attempts = entry.attempts ?? [];
+  return attempts.length > 0 && attempts[attempts.length - 1]?.ordinal === attempt.ordinal;
+}
+
+function classifyOutcome(entry: PersistedUsageEntry, attempt: PersistedUsageAttempt): PassiveProductionOutcome {
+  if (attempt.status >= 200 && attempt.status < 300) return "success";
+  if (isFinalAttempt(entry, attempt) && entry.closeReason === "client_cancel") return "client_cancel";
+  if (attempt.errorCode && ENVIRONMENTAL_ERROR_CODES.has(attempt.errorCode)) return "environmental";
+  if (attempt.errorCode && ROUTE_ERROR_CODES.has(attempt.errorCode)) return "route_error";
+  return "unknown";
+}
+
+function signalFor(entry: PersistedUsageEntry, attempt: PersistedUsageAttempt): PassiveRouteSignalV1 | null {
+  const subjectId = attempt.labRouteSubjectId;
+  if (!isLabRouteSubjectId(subjectId)) return null;
+  return {
+    schemaVersion: 1,
+    subjectId,
+    source: "production_usage_v1",
+    requestRef: entry.requestId,
+    ...(entry.routeDecision?.decisionId ? { decisionRef: entry.routeDecision.decisionId } : {}),
+    attemptOrdinal: attempt.ordinal,
+    observedAt: entry.timestamp,
+    outcome: classifyOutcome(entry, attempt),
+    httpStatus: attempt.status,
+  };
+}
+
+export function derivePassiveProductionSignals(
+  entries: readonly PersistedUsageEntry[],
+  subjectId: string,
+  limit?: number,
+): PassiveProductionQueryResultV1 {
+  if (!isLabRouteSubjectId(subjectId)) throw new Error("invalid passive production subject id");
+  const maxResults = boundedLimit(limit);
+  const signals: PassiveRouteSignalV1[] = [];
+  // readRecentUsageEntries returns the selected append-only rows oldest-first.
+  // Tail selection, reverse iteration, and signals[0] as the newest observation rely on this ordering.
+  const scanRows = entries.slice(-PASSIVE_PRODUCTION_MAX_SCAN_ROWS);
+  const scanTruncated = entries.length > PASSIVE_PRODUCTION_MAX_SCAN_ROWS;
+  let resultTruncated = false;
+
+  scan: for (let rowIndex = scanRows.length - 1; rowIndex >= 0; rowIndex--) {
+    const entry = scanRows[rowIndex]!;
+    const attempts = entry.attempts ?? [];
+    for (let attemptIndex = attempts.length - 1; attemptIndex >= 0; attemptIndex--) {
+      const signal = signalFor(entry, attempts[attemptIndex]!);
+      if (signal?.subjectId !== subjectId) continue;
+      if (signals.length >= maxResults) {
+        resultTruncated = true;
+        break scan;
+      }
+      signals.push(signal);
+    }
+  }
+
+  const recentSuccessfulAttempts = signals.filter(signal => signal.outcome === "success").length;
+  const recentRouteErrorSignals = signals.filter(signal => signal.outcome === "route_error").length;
+  return {
+    schemaVersion: 1,
+    verificationStatus: "not_verification",
+    summary: {
+      schemaVersion: 1,
+      subjectId,
+      verificationStatus: "not_verification",
+      recentProductionAttempts: signals.length,
+      recentSuccessfulAttempts,
+      recentRouteErrorSignals,
+      ...(signals[0] ? { lastObservedProductionAttempt: signals[0].observedAt } : {}),
+    },
+    signals,
+    scannedRows: scanRows.length,
+    truncated: scanTruncated || resultTruncated,
+  };
+}
+
+/** Read-only bounded CL-09 projection over the existing usage-log authority. */
+export function queryPassiveProductionSignals(
+  subjectId: string,
+  limit?: number,
+  configDir?: string,
+): PassiveProductionQueryResultV1 {
+  return derivePassiveProductionSignals(
+    // Read one row past the scan cap so the projection can distinguish an exact-cap history
+    // from a history with older rows omitted by the bounded reader.
+    readRecentUsageEntries(PASSIVE_PRODUCTION_MAX_SCAN_ROWS + 1, configDir),
+    subjectId,
+    limit,
+  );
+}

package/src/lab/query/queries.ts

@@ -0,0 +1,444 @@
+import {
+  LAB_QUERY_DEFAULT_PAGE_SIZE,
+  LAB_QUERY_MAX_PAGE_SIZE,
+} from "./constants";
+import {
+  closeLabReadConnection,
+  countTable,
+  openLabReadConnection,
+  type LabReadConnection,
+} from "./connection";
+import {
+  assertCursorFilters,
+  artifactCursor,
+  decodeLabCursor,
+  encodeLabCursor,
+  eventCursor,
+  filterKeyFor,
+  observationCursor,
+  subjectCursor,
+  verdictCursor,
+} from "./cursor";
+import {
+  mapArtifactRow,
+  mapEventListRow,
+  mapObservationRow,
+  mapSubjectJson,
+  mapSubjectListRow,
+  mapVerdictRow,
+  parseEventPayloadToDto,
+} from "./dto-map";
+import { InvalidCursorError } from "./errors";
+import { queryLabCatalog } from "./catalog";
+import type {
+  ArtifactFilters,
+  ArtifactMetadataDto,
+  EventFilters,
+  EventListItemDto,
+  LabEventDto,
+  LabStatusDto,
+  ObservationDto,
+  ObservationFilters,
+  PaginatedResult,
+  SubjectDto,
+  SubjectListItemDto,
+  VerdictDto,
+  VerdictFilters,
+} from "./types";
+
+function clampLimit(limit: number | undefined): number {
+  if (limit === undefined) return LAB_QUERY_DEFAULT_PAGE_SIZE;
+  return Math.min(Math.max(limit, 1), LAB_QUERY_MAX_PAGE_SIZE);
+}
+
+export function queryLabStatus(configDir?: string): LabStatusDto {
+  try {
+    const conn = openLabReadConnection(configDir);
+    try {
+      return {
+        projectionAvailable: true,
+        sqliteSchemaVersion: conn.schemaVersion,
+        projectionSpecVersion: conn.projectionSpecVersion,
+        builtAtMs: conn.builtAtMs,
+        eventCount: countTable(conn, "events"),
+        subjectCount: countTable(conn, "subjects"),
+        observationCount: countTable(conn, "observations"),
+        claimCount: countTable(conn, "claims"),
+        verdictCount: countTable(conn, "verdicts"),
+        artifactCount: countTable(conn, "artifacts"),
+        corruptionCount: countTable(conn, "corruption"),
+      };
+    } finally {
+      closeLabReadConnection(conn);
+    }
+  } catch (err) {
+    if (err && typeof err === "object" && "code" in err) {
+      const code = String((err as { code: unknown }).code);
+      if (code === "lab_projection_incompatible") {
+        return { projectionAvailable: false, projectionIncompatible: true };
+      }
+    }
+    return { projectionAvailable: false };
+  }
+}
+
+function withConnection<T>(configDir: string | undefined, fn: (conn: LabReadConnection) => T): T {
+  const conn = openLabReadConnection(configDir);
+  try {
+    return fn(conn);
+  } finally {
+    closeLabReadConnection(conn);
+  }
+}
+
+export function queryLabVerdicts(
+  filters: VerdictFilters = {},
+  cursorRaw?: string | null,
+  limit?: number,
+  configDir?: string,
+): PaginatedResult<VerdictDto> {
+  const pageSize = clampLimit(limit);
+  const filterRecord: Record<string, unknown> = { ...filters };
+  const decoded = cursorRaw ? decodeLabCursor(cursorRaw) : null;
+  if (cursorRaw && !decoded) throw new InvalidCursorError();
+  if (decoded) assertCursorFilters(decoded, filterRecord, "verdicts");
+
+  return withConnection(configDir, (conn) => {
+    const where: string[] = [];
+    const params: Array<string | number> = [];
+    if (filters.subjectId) {
+      where.push("subject_id = ?");
+      params.push(filters.subjectId);
+    }
+    if (filters.layer) {
+      where.push("evidence_layer = ?");
+      params.push(filters.layer);
+    }
+    if (filters.suiteId) {
+      where.push("suite_id = ?");
+      params.push(filters.suiteId);
+    }
+    if (filters.verdict) {
+      where.push("verdict = ?");
+      params.push(filters.verdict);
+    }
+    if (filters.from !== undefined) {
+      where.push("as_of >= ?");
+      params.push(filters.from);
+    }
+    if (filters.to !== undefined) {
+      where.push("as_of <= ?");
+      params.push(filters.to);
+    }
+    if (decoded && decoded.k === "verdicts") {
+      where.push("(as_of < ? OR (as_of = ? AND projection_key > ?))");
+      params.push(decoded.a, decoded.a, decoded.p);
+    }
+    const whereSql = where.length > 0 ? `WHERE ${where.join(" AND ")}` : "";
+    const rows = conn.db
+      .query(
+        `SELECT projection_key, subject_id, evidence_layer, suite_id, suite_version,
+                suite_manifest_digest, projection_spec_version, verdict, as_of,
+                scenario_manifest_digests_json, claim_source_digest,
+                contributing_event_ids_json, contradicting_event_ids_json, notes_json
+         FROM verdicts ${whereSql}
+         ORDER BY as_of DESC, projection_key ASC
+         LIMIT ?`,
+      )
+      .all(...params, pageSize + 1) as Array<Record<string, unknown>>;
+
+    const hasMore = rows.length > pageSize;
+    const pageRows = hasMore ? rows.slice(0, pageSize) : rows;
+    const items = pageRows.map(mapVerdictRow);
+    let nextCursor: string | undefined;
+    if (hasMore && pageRows.length > 0) {
+      const last = pageRows[pageRows.length - 1]!;
+      nextCursor = encodeLabCursor(
+        verdictCursor(Number(last.as_of), String(last.projection_key), filterRecord),
+      );
+    }
+    return { items, hasMore, ...(nextCursor ? { nextCursor } : {}) };
+  });
+}
+
+export function queryLabSubjects(
+  kind?: string,
+  cursorRaw?: string | null,
+  limit?: number,
+  configDir?: string,
+): PaginatedResult<SubjectListItemDto> {
+  const pageSize = clampLimit(limit);
+  const filterRecord: Record<string, unknown> = { kind };
+  const decoded = cursorRaw ? decodeLabCursor(cursorRaw) : null;
+  if (cursorRaw && !decoded) throw new InvalidCursorError();
+  if (decoded) assertCursorFilters(decoded, filterRecord, "subjects");
+
+  return withConnection(configDir, (conn) => {
+    const where: string[] = [];
+    const params: Array<string | number> = [];
+    if (kind) {
+      where.push("subject_kind = ?");
+      params.push(kind);
+    }
+    if (decoded && decoded.k === "subjects") {
+      where.push("subject_id > ?");
+      params.push(decoded.s);
+    }
+    const whereSql = where.length > 0 ? `WHERE ${where.join(" AND ")}` : "";
+    const rows = conn.db
+      .query(`SELECT subject_id, subject_kind FROM subjects ${whereSql} ORDER BY subject_id ASC LIMIT ?`)
+      .all(...params, pageSize + 1) as Array<Record<string, unknown>>;
+
+    const hasMore = rows.length > pageSize;
+    const pageRows = hasMore ? rows.slice(0, pageSize) : rows;
+    const items = pageRows.map(mapSubjectListRow);
+    let nextCursor: string | undefined;
+    if (hasMore && pageRows.length > 0) {
+      const last = pageRows[pageRows.length - 1]!;
+      nextCursor = encodeLabCursor(subjectCursor(String(last.subject_id), filterRecord));
+    }
+    return { items, hasMore, ...(nextCursor ? { nextCursor } : {}) };
+  });
+}
+
+export function queryLabSubjectById(subjectId: string, configDir?: string): SubjectDto | null {
+  return withConnection(configDir, (conn) => {
+    const row = conn.db
+      .query("SELECT subject_json FROM subjects WHERE subject_id = ?")
+      .get(subjectId) as { subject_json: string } | null;
+    if (!row) return null;
+    return mapSubjectJson(row.subject_json);
+  });
+}
+
+export function queryLabObservations(
+  filters: ObservationFilters = {},
+  cursorRaw?: string | null,
+  limit?: number,
+  configDir?: string,
+): PaginatedResult<ObservationDto> {
+  const pageSize = clampLimit(limit);
+  const filterRecord: Record<string, unknown> = { ...filters };
+  const decoded = cursorRaw ? decodeLabCursor(cursorRaw) : null;
+  if (cursorRaw && !decoded) throw new InvalidCursorError();
+  if (decoded) assertCursorFilters(decoded, filterRecord, "observations");
+
+  return withConnection(configDir, (conn) => {
+    const where: string[] = [];
+    const params: Array<string | number> = [];
+    if (filters.subjectId) {
+      where.push("o.subject_id = ?");
+      params.push(filters.subjectId);
+    }
+    if (filters.layer) {
+      where.push("o.evidence_layer = ?");
+      params.push(filters.layer);
+    }
+    if (filters.suiteId) {
+      where.push("o.suite_id = ?");
+      params.push(filters.suiteId);
+    }
+    if (filters.scenarioId) {
+      where.push("o.scenario_id = ?");
+      params.push(filters.scenarioId);
+    }
+    if (filters.outcome) {
+      where.push("o.outcome = ?");
+      params.push(filters.outcome);
+    }
+    if (filters.executionMode) {
+      where.push("o.execution_mode = ?");
+      params.push(filters.executionMode);
+    }
+    if (filters.from !== undefined) {
+      where.push("o.completed_at >= ?");
+      params.push(filters.from);
+    }
+    if (filters.to !== undefined) {
+      where.push("o.completed_at <= ?");
+      params.push(filters.to);
+    }
+    if (decoded && decoded.k === "observations") {
+      where.push("(o.completed_at < ? OR (o.completed_at = ? AND o.event_id < ?))");
+      params.push(decoded.c, decoded.c, decoded.e);
+    }
+    const whereSql = where.length > 0 ? `WHERE ${where.join(" AND ")}` : "";
+    const rows = conn.db
+      .query(
+        `SELECT o.event_id, o.subject_id, o.evidence_layer, o.suite_id, o.suite_version,
+                o.suite_manifest_digest, o.scenario_id, o.scenario_version, o.scenario_manifest_digest,
+                o.outcome, o.completed_at, o.execution_mode,
+                e.excluded, e.exclusion_reason
+         FROM observations o
+         JOIN events e ON e.event_id = o.event_id
+         ${whereSql}
+         ORDER BY o.completed_at DESC, o.event_id DESC
+         LIMIT ?`,
+      )
+      .all(...params, pageSize + 1) as Array<Record<string, unknown>>;
+
+    const hasMore = rows.length > pageSize;
+    const pageRows = hasMore ? rows.slice(0, pageSize) : rows;
+    const items = pageRows.map((row) =>
+      mapObservationRow(row, Number(row.excluded) === 1, row.exclusion_reason ? String(row.exclusion_reason) : null),
+    );
+    let nextCursor: string | undefined;
+    if (hasMore && pageRows.length > 0) {
+      const last = pageRows[pageRows.length - 1]!;
+      nextCursor = encodeLabCursor(
+        observationCursor(Number(last.completed_at), String(last.event_id), filterRecord),
+      );
+    }
+    return { items, hasMore, ...(nextCursor ? { nextCursor } : {}) };
+  });
+}
+
+export function queryLabEvents(
+  filters: EventFilters = {},
+  cursorRaw?: string | null,
+  limit?: number,
+  configDir?: string,
+): PaginatedResult<EventListItemDto> {
+  const pageSize = clampLimit(limit);
+  const filterRecord: Record<string, unknown> = { ...filters };
+  const decoded = cursorRaw ? decodeLabCursor(cursorRaw) : null;
+  if (cursorRaw && !decoded) throw new InvalidCursorError();
+  if (decoded) assertCursorFilters(decoded, filterRecord, "events");
+
+  return withConnection(configDir, (conn) => {
+    const where: string[] = [];
+    const params: Array<string | number> = [];
+    if (filters.eventKind) {
+      where.push("e.event_kind = ?");
+      params.push(filters.eventKind);
+    }
+    if (filters.from !== undefined) {
+      where.push("e.recorded_at >= ?");
+      params.push(filters.from);
+    }
+    if (filters.to !== undefined) {
+      where.push("e.recorded_at <= ?");
+      params.push(filters.to);
+    }
+    if (filters.excluded !== undefined) {
+      where.push("e.excluded = ?");
+      params.push(filters.excluded ? 1 : 0);
+    }
+    if (filters.subjectId) {
+      where.push(
+        "(EXISTS (SELECT 1 FROM observations ox WHERE ox.event_id = e.event_id AND ox.subject_id = ?) OR EXISTS (SELECT 1 FROM claims cx WHERE cx.event_id = e.event_id AND cx.subject_id = ?))",
+      );
+      params.push(filters.subjectId, filters.subjectId);
+    }
+    if (decoded && decoded.k === "events") {
+      where.push("(e.recorded_at < ? OR (e.recorded_at = ? AND e.event_id < ?))");
+      params.push(decoded.r, decoded.r, decoded.e);
+    }
+    const whereSql = where.length > 0 ? `WHERE ${where.join(" AND ")}` : "";
+    const rows = conn.db
+      .query(
+        `SELECT e.event_id, e.event_kind, e.recorded_at, e.excluded, e.exclusion_reason
+         FROM events e
+         ${whereSql}
+         ORDER BY e.recorded_at DESC, e.event_id DESC
+         LIMIT ?`,
+      )
+      .all(...params, pageSize + 1) as Array<Record<string, unknown>>;
+
+    const hasMore = rows.length > pageSize;
+    const pageRows = hasMore ? rows.slice(0, pageSize) : rows;
+    const items = pageRows.map(mapEventListRow);
+    let nextCursor: string | undefined;
+    if (hasMore && pageRows.length > 0) {
+      const last = pageRows[pageRows.length - 1]!;
+      nextCursor = encodeLabCursor(
+        eventCursor(Number(last.recorded_at), String(last.event_id), filterRecord),
+      );
+    }
+    return { items, hasMore, ...(nextCursor ? { nextCursor } : {}) };
+  });
+}
+
+export function queryLabEventById(eventId: string, configDir?: string): LabEventDto | null {
+  return withConnection(configDir, (conn) => {
+    const row = conn.db
+      .query(
+        "SELECT event_id, payload_json, excluded, exclusion_reason FROM events WHERE event_id = ?",
+      )
+      .get(eventId) as { payload_json: string; excluded: number; exclusion_reason: string | null } | null;
+    if (!row) return null;
+    const excluded = Number(row.excluded) === 1;
+    const exclusionReason = row.exclusion_reason ? String(row.exclusion_reason) : null;
+    return parseEventPayloadToDto(row.payload_json, excluded, exclusionReason);
+  });
+}
+
+export function queryLabArtifacts(
+  filters: ArtifactFilters = {},
+  cursorRaw?: string | null,
+  limit?: number,
+  configDir?: string,
+): PaginatedResult<ArtifactMetadataDto> {
+  const pageSize = clampLimit(limit);
+  const filterRecord: Record<string, unknown> = { ...filters };
+  const decoded = cursorRaw ? decodeLabCursor(cursorRaw) : null;
+  if (cursorRaw && !decoded) throw new InvalidCursorError();
+  if (decoded) assertCursorFilters(decoded, filterRecord, "artifacts");
+
+  return withConnection(configDir, (conn) => {
+    const where: string[] = [];
+    const params: Array<string | number> = [];
+    if (filters.status) {
+      where.push("status = ?");
+      params.push(filters.status);
+    }
+    if (filters.artifactClass) {
+      where.push("artifact_class = ?");
+      params.push(filters.artifactClass);
+    }
+    if (decoded && decoded.k === "artifacts") {
+      where.push("digest > ?");
+      params.push(decoded.d);
+    }
+    const whereSql = where.length > 0 ? `WHERE ${where.join(" AND ")}` : "";
+    const rows = conn.db
+      .query(
+        `SELECT digest, artifact_class, media_type, byte_count, status, last_error
+         FROM artifacts ${whereSql} ORDER BY digest ASC LIMIT ?`,
+      )
+      .all(...params, pageSize + 1) as Array<Record<string, unknown>>;
+
+    const hasMore = rows.length > pageSize;
+    const pageRows = hasMore ? rows.slice(0, pageSize) : rows;
+    const items = pageRows.map(mapArtifactRow);
+    let nextCursor: string | undefined;
+    if (hasMore && pageRows.length > 0) {
+      const last = pageRows[pageRows.length - 1]!;
+      nextCursor = encodeLabCursor(artifactCursor(String(last.digest), filterRecord));
+    }
+    return { items, hasMore, ...(nextCursor ? { nextCursor } : {}) };
+  });
+}
+
+export function queryLabArtifactByDigest(digest: string, configDir?: string): ArtifactMetadataDto | null {
+  return withConnection(configDir, (conn) => {
+    const row = conn.db
+      .query(
+        "SELECT digest, artifact_class, media_type, byte_count, status, last_error FROM artifacts WHERE digest = ?",
+      )
+      .get(digest) as Record<string, unknown> | null;
+    if (!row) return null;
+    return mapArtifactRow(row);
+  });
+}
+
+export function queryLabCatalogEntries(
+  filters: { layer?: string; suiteId?: string } = {},
+): ReturnType<typeof queryLabCatalog> {
+  return queryLabCatalog({
+    layer: filters.layer as import("../constants").EvidenceLayer | undefined,
+    suiteId: filters.suiteId,
+  });
+}
+
+export { filterKeyFor };