@bitkyc08/opencodex 2.11.1 → 2.12.0

package/src/lab/projection/verification.ts

@@ -0,0 +1,332 @@
+import type { ObservationEvent, ProtocolSubjectV1, RouteSubjectV1 } from "../events/types";
+import { EVIDENCE_LAYERS, type ExecutionMode } from "../constants";
+import type { SuiteManifestV1 } from "../conformance/suite-manifest";
+import type { VerificationRole } from "../conformance/types";
+import { isSha256Hex } from "../digest";
+
+export interface VerificationEvaluation {
+  applicableRequiredScenarioIds: string[];
+  passingRequiredScenarioIds: string[];
+  missingRequiredScenarioIds: string[];
+  canVerify: boolean;
+  notes: string[];
+}
+
+export type LoadScenarioManifest = (digest: string) => Record<string, unknown> | null;
+
+export interface ScenarioRequirements {
+  inboundProtocols?: string[];
+  upstreamProtocols?: string[];
+  surfaces?: string[];
+  requiredClaims?: string[];
+  freshness?: { maxAgeMs: number | null };
+}
+
+export type LoadScenarioRequirements = (digest: string) => ScenarioRequirements | null;
+
+/** Live-reserved scenarios are inapplicable in fixture-mode protocol conformance. */
+export function isScenarioApplicable(
+  scenarioId: string,
+  executionMode: ExecutionMode,
+  evidenceLayer: string,
+): boolean {
+  if (evidenceLayer === "protocol_conformance" && executionMode === "fixture") {
+    // The frozen CL-00 scenario schema has no explicit execution-mode field.
+    // Use an exact dot-delimited `live` segment rather than substring matching.
+    if (scenarioId.split(".").includes("live")) return false;
+  }
+  return true;
+}
+
+function scenarioApplicableToRequirements(
+  requirements: ScenarioRequirements,
+  subject: ProtocolSubjectV1,
+): boolean {
+  const inbound = requirements.inboundProtocols ?? [];
+  const upstream = requirements.upstreamProtocols ?? [];
+  const surfaces = requirements.surfaces ?? [];
+  return (
+    inbound.includes(subject.inboundProtocol) &&
+    upstream.includes(subject.upstreamProtocol) &&
+    surfaces.includes(subject.surface)
+  );
+}
+
+/** Applicability for live_route_compatibility using exact RouteSubjectV1 plus validated claim state. */
+export function routeSubjectApplicableToRequirements(
+  requirements: ScenarioRequirements,
+  subject: RouteSubjectV1,
+  supportedClaims: readonly string[],
+): boolean {
+  const inbound = requirements.inboundProtocols ?? [];
+  const upstream = requirements.upstreamProtocols ?? [];
+  const surfaces = requirements.surfaces ?? [];
+  const requiredClaims = requirements.requiredClaims ?? [];
+  const claimsOk = requiredClaims.every((claim) => supportedClaims.includes(claim));
+  return (
+    inbound.includes(subject.inboundProtocol) &&
+    upstream.includes(subject.upstreamProtocol) &&
+    surfaces.includes(subject.surface) &&
+    claimsOk
+  );
+}
+
+function isNonNegativeInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+
+function parseFreshness(value: unknown): { maxAgeMs: number | null } | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const maxAgeMs = (value as { maxAgeMs?: unknown }).maxAgeMs;
+  if (maxAgeMs === null) return { maxAgeMs: null };
+  if (!isNonNegativeInteger(maxAgeMs)) return null;
+  return { maxAgeMs };
+}
+
+function parseStringArray(value: unknown): string[] | null {
+  if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) return null;
+  return value;
+}
+
+function scenarioContractFromManifest(
+  scenarioManifest: Record<string, unknown> | null,
+): ScenarioRequirements | null {
+  if (!scenarioManifest) return null;
+  const req = scenarioManifest.requirements;
+  if (!req || typeof req !== "object" || Array.isArray(req)) return null;
+  const row = req as Record<string, unknown>;
+  const inboundProtocols = parseStringArray(row.inboundProtocols);
+  const upstreamProtocols = parseStringArray(row.upstreamProtocols);
+  const surfaces = parseStringArray(row.surfaces);
+  if (!inboundProtocols || !upstreamProtocols || !surfaces) return null;
+  const requiredClaims = row.requiredClaims === undefined ? [] : parseStringArray(row.requiredClaims);
+  if (!requiredClaims) return null;
+  const freshness = parseFreshness(scenarioManifest.freshness);
+  if (!freshness) return null;
+  return { inboundProtocols, upstreamProtocols, surfaces, requiredClaims, freshness };
+}
+
+function effectiveMaxAgeMs(
+  suiteMaxAgeMs: number | null,
+  scenarioMaxAgeMs: number | null,
+): number | null {
+  if (suiteMaxAgeMs === null) return scenarioMaxAgeMs;
+  if (scenarioMaxAgeMs === null) return suiteMaxAgeMs;
+  return Math.min(suiteMaxAgeMs, scenarioMaxAgeMs);
+}
+
+export function newestObservationByScenario(
+  observations: ObservationEvent[],
+): Map<string, ObservationEvent> {
+  const byScenario = new Map<string, ObservationEvent>();
+  const ordered = [...observations].sort((a, b) => {
+    if (a.completedAt !== b.completedAt) return a.completedAt - b.completedAt;
+    return a.eventId < b.eventId ? -1 : a.eventId > b.eventId ? 1 : 0;
+  });
+  for (const obs of ordered) {
+    byScenario.set(obs.scenarioId, obs);
+  }
+  return byScenario;
+}
+
+/**
+ * Evaluate `all-applicable-required-pass-v1` per frozen CL-00 semantics.
+ * Positive VERIFIED requires a non-empty applicable required/control set and a
+ * current, fresh pass for every applicable required scenario and negative control.
+ */
+export function evaluateAllApplicableRequiredPassV1(
+  suiteManifest: SuiteManifestV1,
+  observations: ObservationEvent[],
+  executionMode: ExecutionMode,
+  opts: {
+    subject?: ProtocolSubjectV1 | RouteSubjectV1;
+    /** For live projection this must come from validated current claim snapshots for subjectId. */
+    routeSupportedClaims?: readonly string[];
+    loadScenarioManifest?: LoadScenarioManifest;
+    loadScenarioRequirements?: LoadScenarioRequirements;
+    asOf?: number;
+  } = {},
+): VerificationEvaluation {
+  const notes: string[] = [];
+  if (suiteManifest.verificationRule !== "all-applicable-required-pass-v1") {
+    return {
+      applicableRequiredScenarioIds: [],
+      passingRequiredScenarioIds: [],
+      missingRequiredScenarioIds: [],
+      canVerify: false,
+      notes: ["unsupported_verification_rule"],
+    };
+  }
+  if (suiteManifest.evidenceLayer === "live_route_compatibility") {
+    if (opts.subject?.subjectKind !== "route") {
+      return { applicableRequiredScenarioIds: [], passingRequiredScenarioIds: [], missingRequiredScenarioIds: [], canVerify: false, notes: ["route_subject_required"] };
+    }
+    if (opts.routeSupportedClaims === undefined) {
+      return { applicableRequiredScenarioIds: [], passingRequiredScenarioIds: [], missingRequiredScenarioIds: [], canVerify: false, notes: ["route_claim_state_required"] };
+    }
+  }
+
+  const requiredScenarios = suiteManifest.scenarios.filter(
+    (s) => s.role === "required" || s.role === "negative_control",
+  );
+  const applicableRequired: string[] = [];
+  const unavailableManifests: string[] = [];
+  const scenarioMaxAgeById = new Map<string, number | null>();
+
+  for (const s of requiredScenarios) {
+    if (!isScenarioApplicable(s.id, executionMode, suiteManifest.evidenceLayer)) continue;
+
+    let requirements: ScenarioRequirements | null = null;
+    const scenarioManifest = opts.loadScenarioManifest?.(s.manifestDigest) ?? null;
+    if (scenarioManifest) {
+      requirements = scenarioContractFromManifest(scenarioManifest);
+      if (!requirements) {
+        unavailableManifests.push(s.id);
+        continue;
+      }
+    } else {
+      requirements = opts.loadScenarioRequirements?.(s.manifestDigest) ?? null;
+      if (!requirements || !requirements.freshness) {
+        unavailableManifests.push(s.id);
+        continue;
+      }
+    }
+
+    if (suiteManifest.evidenceLayer === "protocol_conformance" && opts.subject?.subjectKind === "protocol") {
+      if (!scenarioApplicableToRequirements(requirements, opts.subject)) continue;
+    }
+    if (suiteManifest.evidenceLayer === "live_route_compatibility" && opts.subject?.subjectKind === "route") {
+      if (!routeSubjectApplicableToRequirements(requirements, opts.subject, opts.routeSupportedClaims!)) continue;
+    }
+    applicableRequired.push(s.id);
+    scenarioMaxAgeById.set(s.id, requirements.freshness?.maxAgeMs ?? null);
+  }
+  applicableRequired.sort();
+
+  if (unavailableManifests.length > 0) {
+    return {
+      applicableRequiredScenarioIds: applicableRequired,
+      passingRequiredScenarioIds: [],
+      missingRequiredScenarioIds: [...new Set([...applicableRequired, ...unavailableManifests])].sort(),
+      canVerify: false,
+      notes: unavailableManifests.map((id) => `scenario_manifest_unavailable:${id}`),
+    };
+  }
+
+  if (applicableRequired.length === 0) {
+    return {
+      applicableRequiredScenarioIds: [],
+      passingRequiredScenarioIds: [],
+      missingRequiredScenarioIds: [],
+      canVerify: false,
+      notes: ["empty_applicable_required_set"],
+    };
+  }
+
+  const newest = newestObservationByScenario(observations);
+  const passing: string[] = [];
+  const missing: string[] = [];
+  const asOf = opts.asOf ?? observations.reduce((max, obs) => Math.max(max, obs.completedAt), 0);
+
+  for (const scenarioId of applicableRequired) {
+    const scenarioRef = requiredScenarios.find((s) => s.id === scenarioId)!;
+    const obs = newest.get(scenarioId);
+    if (!obs) {
+      missing.push(scenarioId);
+      continue;
+    }
+    if (obs.scenarioManifestDigest !== scenarioRef.manifestDigest) {
+      missing.push(scenarioId);
+      notes.push(`digest_mismatch:${scenarioId}`);
+      continue;
+    }
+    const maxAgeMs = effectiveMaxAgeMs(
+      suiteManifest.freshness.maxAgeMs,
+      scenarioMaxAgeById.get(scenarioId) ?? null,
+    );
+    if (maxAgeMs !== null && asOf - obs.completedAt > maxAgeMs) {
+      missing.push(scenarioId);
+      notes.push(`stale_observation:${scenarioId}`);
+      continue;
+    }
+    if (obs.outcome !== "pass") {
+      missing.push(scenarioId);
+      continue;
+    }
+    passing.push(scenarioId);
+  }
+
+  return {
+    applicableRequiredScenarioIds: applicableRequired,
+    passingRequiredScenarioIds: passing,
+    missingRequiredScenarioIds: missing,
+    canVerify: missing.length === 0 && passing.length === applicableRequired.length,
+    notes,
+  };
+}
+
+function requireNonEmptyString(value: unknown): string | null {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+export function parseSuiteManifestFromArtifact(parsed: unknown): SuiteManifestV1 | null {
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+  const raw = parsed as Record<string, unknown>;
+  if (raw.schemaVersion !== 1) return null;
+
+  const id = requireNonEmptyString(raw.id);
+  const version = requireNonEmptyString(raw.version);
+  const capability = requireNonEmptyString(raw.capability);
+  const assertionDslVersion = requireNonEmptyString(raw.assertionDslVersion);
+  const evidenceSchemaVersion = requireNonEmptyString(raw.evidenceSchemaVersion);
+  const contradictionRule = requireNonEmptyString(raw.contradictionRule);
+  const verificationRule = requireNonEmptyString(raw.verificationRule);
+  if (
+    !id || !version || !capability || !assertionDslVersion ||
+    !evidenceSchemaVersion || !contradictionRule ||
+    verificationRule !== "all-applicable-required-pass-v1"
+  ) return null;
+  if (
+    typeof raw.evidenceLayer !== "string" ||
+    !(EVIDENCE_LAYERS as readonly string[]).includes(raw.evidenceLayer)
+  ) return null;
+  const freshness = parseFreshness(raw.freshness);
+  if (!freshness || !Array.isArray(raw.scenarios)) return null;
+
+  const roles = new Set<VerificationRole>(["required", "supplemental", "negative_control"]);
+  const seenScenarioIds = new Set<string>();
+  const scenarios: SuiteManifestV1["scenarios"] = [];
+  for (const s of raw.scenarios) {
+    if (!s || typeof s !== "object" || Array.isArray(s)) return null;
+    const row = s as Record<string, unknown>;
+    const scenarioId = requireNonEmptyString(row.id);
+    const scenarioVersion = requireNonEmptyString(row.version);
+    const manifestDigest = requireNonEmptyString(row.manifestDigest);
+    if (
+      !scenarioId || !scenarioVersion || !manifestDigest || !isSha256Hex(manifestDigest) ||
+      typeof row.role !== "string" || !roles.has(row.role as VerificationRole) ||
+      seenScenarioIds.has(scenarioId)
+    ) return null;
+    seenScenarioIds.add(scenarioId);
+    scenarios.push({
+      id: scenarioId,
+      version: scenarioVersion,
+      role: row.role as VerificationRole,
+      manifestDigest,
+    });
+  }
+
+  return {
+    schemaVersion: 1,
+    id,
+    version,
+    evidenceLayer: raw.evidenceLayer,
+    capability,
+    assertionDslVersion,
+    evidenceSchemaVersion,
+    freshness,
+    contradictionRule,
+    scenarios,
+    verificationRule,
+  };
+}

package/src/lab/query/catalog.ts

@@ -0,0 +1,72 @@
+import {
+  discoverLiveScenarios,
+  expandLiveScenario,
+  loadLiveCaseAuthority,
+} from "../live/manifest";
+import {
+  liveSuiteManifestDigestForCase,
+} from "../live/suite-manifest";
+import {
+  discoverScenarios,
+  expandScenario,
+  loadCaseAuthority,
+} from "../conformance/manifest";
+import {
+  suiteManifestDigestForCase,
+} from "../conformance/suite-manifest";
+import { scenarioManifestDigest } from "../digest";
+import type { CaseRecord } from "../conformance/types";
+import type { CatalogFilters, CatalogScenarioDto } from "./types";
+
+function mapCaseToCatalogScenario(
+  caseRecord: CaseRecord,
+  authority: ReturnType<typeof loadCaseAuthority>,
+  suiteDigestFn: (caseRecord: CaseRecord, authority: ReturnType<typeof loadCaseAuthority>) => string,
+  expandFn: (caseRecord: CaseRecord, authority: ReturnType<typeof loadCaseAuthority>) => Record<string, unknown>,
+): CatalogScenarioDto {
+  const expanded = expandFn(caseRecord, authority);
+  return {
+    scenarioId: caseRecord.id,
+    scenarioVersion: authority.manifestDefaults.version,
+    evidenceLayer: authority.manifestDefaults.evidenceLayer,
+    suiteId: caseRecord.suite,
+    suiteVersion: authority.manifestDefaults.suiteVersion,
+    capability: caseRecord.capability,
+    verificationRole: caseRecord.verificationRole ?? authority.manifestDefaults.verificationRole,
+    requirements: {
+      inboundProtocols: [...caseRecord.requirements.inboundProtocols],
+      upstreamProtocols: [...caseRecord.requirements.upstreamProtocols],
+      surfaces: [...caseRecord.requirements.surfaces],
+    },
+    freshness: { ...authority.manifestDefaults.freshness },
+    scenarioManifestDigest: scenarioManifestDigest(expanded),
+    suiteManifestDigest: suiteDigestFn(caseRecord, authority),
+  };
+}
+
+export function queryLabCatalog(filters: CatalogFilters = {}): CatalogScenarioDto[] {
+  const items: CatalogScenarioDto[] = [];
+  if (!filters.layer || filters.layer === "protocol_conformance") {
+    const authority = loadCaseAuthority();
+    const suites = filters.suiteId ? [filters.suiteId] : undefined;
+    const scenarios = discoverScenarios(authority, suites ?? undefined);
+    for (const caseRecord of scenarios) {
+      items.push(mapCaseToCatalogScenario(caseRecord, authority, suiteManifestDigestForCase, expandScenario));
+    }
+  }
+  if (!filters.layer || filters.layer === "live_route_compatibility") {
+    const authority = loadLiveCaseAuthority();
+    const suites = filters.suiteId ? [filters.suiteId] : undefined;
+    const scenarios = discoverLiveScenarios(authority, suites ?? undefined);
+    for (const caseRecord of scenarios) {
+      items.push(mapCaseToCatalogScenario(caseRecord, authority, liveSuiteManifestDigestForCase, expandLiveScenario));
+    }
+  }
+  return items.sort((a, b) => {
+    const layerCmp = a.evidenceLayer.localeCompare(b.evidenceLayer);
+    if (layerCmp !== 0) return layerCmp;
+    const suiteCmp = a.suiteId.localeCompare(b.suiteId);
+    if (suiteCmp !== 0) return suiteCmp;
+    return a.scenarioId.localeCompare(b.scenarioId);
+  });
+}

package/src/lab/query/connection.ts

@@ -0,0 +1,107 @@
+import { Database } from "bun:sqlite";
+import { existsSync } from "node:fs";
+import { LAB_PROJECTION_SPEC_VERSION } from "../constants";
+import { labSqlitePath } from "../paths";
+import { LAB_SQLITE_SCHEMA_VERSION } from "../projection/schema";
+import { LabProjectionIncompatibleError, LabProjectionUnavailableError } from "./errors";
+
+export interface LabReadConnection {
+  db: Database;
+  sqlitePath: string;
+  schemaVersion: number;
+  projectionSpecVersion: string;
+  builtAtMs: number;
+}
+
+const COUNTABLE_TABLES = [
+  "events",
+  "subjects",
+  "observations",
+  "claims",
+  "verdicts",
+  "artifacts",
+  "corruption",
+] as const;
+
+export type CountableTable = (typeof COUNTABLE_TABLES)[number];
+
+const COUNT_TABLE_SQL: Record<CountableTable, string> = {
+  events: "SELECT COUNT(*) AS c FROM events",
+  subjects: "SELECT COUNT(*) AS c FROM subjects",
+  observations: "SELECT COUNT(*) AS c FROM observations",
+  claims: "SELECT COUNT(*) AS c FROM claims",
+  verdicts: "SELECT COUNT(*) AS c FROM verdicts",
+  artifacts: "SELECT COUNT(*) AS c FROM artifacts",
+  corruption: "SELECT COUNT(*) AS c FROM corruption",
+};
+
+export function resolveLabSqlitePath(configDir?: string): string {
+  return labSqlitePath(configDir);
+}
+
+export function openLabReadConnection(configDir?: string): LabReadConnection {
+  const sqlitePath = resolveLabSqlitePath(configDir);
+  if (!existsSync(sqlitePath)) {
+    throw new LabProjectionUnavailableError();
+  }
+  let db: Database;
+  try {
+    db = new Database(sqlitePath, { readonly: true });
+  } catch {
+    throw new LabProjectionUnavailableError();
+  }
+  try {
+    const metaRows = db
+      .query("SELECT key, value FROM schema_meta")
+      .all() as Array<{ key: string; value: string }>;
+    const meta = new Map(metaRows.map((r) => [r.key, r.value]));
+    const schemaRaw = meta.get("schema_version");
+    const specRaw = meta.get("projection_spec_version");
+    const builtRaw = meta.get("built_at_ms");
+    if (!schemaRaw || !specRaw || !builtRaw) {
+      db.close();
+      throw new LabProjectionUnavailableError();
+    }
+    const schemaVersion = Number(schemaRaw);
+    const projectionSpecVersion = specRaw;
+    const builtAtMs = Number(builtRaw);
+    if (
+      !Number.isInteger(schemaVersion) ||
+      schemaVersion !== LAB_SQLITE_SCHEMA_VERSION ||
+      projectionSpecVersion !== LAB_PROJECTION_SPEC_VERSION ||
+      !Number.isFinite(builtAtMs)
+    ) {
+      db.close();
+      throw new LabProjectionIncompatibleError();
+    }
+    return {
+      db,
+      sqlitePath,
+      schemaVersion,
+      projectionSpecVersion,
+      builtAtMs,
+    };
+  } catch (err) {
+    try {
+      db.close();
+    } catch {
+      /* ignore */
+    }
+    if (err instanceof LabProjectionUnavailableError || err instanceof LabProjectionIncompatibleError) {
+      throw err;
+    }
+    throw new LabProjectionUnavailableError();
+  }
+}
+
+export function closeLabReadConnection(conn: LabReadConnection): void {
+  conn.db.close();
+}
+
+export function countTable(conn: LabReadConnection, table: CountableTable): number {
+  if (!(COUNTABLE_TABLES as readonly string[]).includes(table)) {
+    throw new LabProjectionUnavailableError();
+  }
+  const row = conn.db.query(COUNT_TABLE_SQL[table]).get() as { c: number };
+  return Number(row.c);
+}

package/src/lab/query/constants.ts

@@ -0,0 +1,4 @@
+export const LAB_QUERY_DEFAULT_PAGE_SIZE = 50;
+export const LAB_QUERY_MAX_PAGE_SIZE = 100;
+export const LAB_QUERY_CURSOR_VERSION = 1;
+export const LAB_QUERY_MAX_CURSOR_BYTES = 4096;

package/src/lab/query/cursor.ts

@@ -0,0 +1,132 @@
+import { LAB_QUERY_CURSOR_VERSION, LAB_QUERY_MAX_CURSOR_BYTES } from "./constants";
+import { InvalidCursorError } from "./errors";
+
+export type VerdictCursorPayload = {
+  v: typeof LAB_QUERY_CURSOR_VERSION;
+  k: "verdicts";
+  a: number;
+  p: string;
+  f: string;
+};
+
+export type ObservationCursorPayload = {
+  v: typeof LAB_QUERY_CURSOR_VERSION;
+  k: "observations";
+  c: number;
+  e: string;
+  f: string;
+};
+
+export type EventCursorPayload = {
+  v: typeof LAB_QUERY_CURSOR_VERSION;
+  k: "events";
+  r: number;
+  e: string;
+  f: string;
+};
+
+export type SubjectCursorPayload = {
+  v: typeof LAB_QUERY_CURSOR_VERSION;
+  k: "subjects";
+  s: string;
+  f: string;
+};
+
+export type ArtifactCursorPayload = {
+  v: typeof LAB_QUERY_CURSOR_VERSION;
+  k: "artifacts";
+  d: string;
+  f: string;
+};
+
+export type LabCursorPayload =
+  | VerdictCursorPayload
+  | ObservationCursorPayload
+  | EventCursorPayload
+  | SubjectCursorPayload
+  | ArtifactCursorPayload;
+
+function stableFilterKey(filters: Record<string, unknown>): string {
+  const entries = Object.entries(filters)
+    .filter(([, v]) => v !== undefined && v !== null)
+    .sort(([a], [b]) => a.localeCompare(b));
+  return JSON.stringify(entries);
+}
+
+export function encodeLabCursor(payload: LabCursorPayload): string {
+  return Buffer.from(JSON.stringify(payload)).toString("base64url");
+}
+
+export function decodeLabCursor(raw: string | null | undefined): LabCursorPayload | null {
+  if (typeof raw !== "string" || raw.length === 0 || raw.length > LAB_QUERY_MAX_CURSOR_BYTES) return null;
+  try {
+    const parsed = JSON.parse(Buffer.from(raw, "base64url").toString("utf8")) as Record<string, unknown>;
+    if (parsed.v !== LAB_QUERY_CURSOR_VERSION || typeof parsed.k !== "string") return null;
+    if (parsed.k === "verdicts") {
+      if (typeof parsed.a !== "number" || !Number.isFinite(parsed.a)) return null;
+      if (typeof parsed.p !== "string" || parsed.p.length === 0 || parsed.p.length > 256) return null;
+      if (typeof parsed.f !== "string") return null;
+      return parsed as VerdictCursorPayload;
+    }
+    if (parsed.k === "observations") {
+      if (typeof parsed.c !== "number" || !Number.isFinite(parsed.c)) return null;
+      if (typeof parsed.e !== "string" || parsed.e.length === 0 || parsed.e.length > 256) return null;
+      if (typeof parsed.f !== "string") return null;
+      return parsed as ObservationCursorPayload;
+    }
+    if (parsed.k === "events") {
+      if (typeof parsed.r !== "number" || !Number.isFinite(parsed.r)) return null;
+      if (typeof parsed.e !== "string" || parsed.e.length === 0 || parsed.e.length > 256) return null;
+      if (typeof parsed.f !== "string") return null;
+      return parsed as EventCursorPayload;
+    }
+    if (parsed.k === "subjects") {
+      if (typeof parsed.s !== "string" || parsed.s.length === 0 || parsed.s.length > 256) return null;
+      if (typeof parsed.f !== "string") return null;
+      return parsed as SubjectCursorPayload;
+    }
+    if (parsed.k === "artifacts") {
+      if (typeof parsed.d !== "string" || parsed.d.length === 0 || parsed.d.length > 128) return null;
+      if (typeof parsed.f !== "string") return null;
+      return parsed as ArtifactCursorPayload;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+export function assertCursorFilters(
+  cursor: LabCursorPayload,
+  filters: Record<string, unknown>,
+  kind: LabCursorPayload["k"],
+): void {
+  if (cursor.k !== kind) throw new InvalidCursorError();
+  const expected = stableFilterKey(filters);
+  const actual = (cursor as { f: string }).f;
+  if (actual !== expected) throw new InvalidCursorError();
+}
+
+export function filterKeyFor(filters: Record<string, unknown>): string {
+  return stableFilterKey(filters);
+}
+
+export function verdictCursor(asOf: number, projectionKey: string, filters: Record<string, unknown>): VerdictCursorPayload {
+  return { v: LAB_QUERY_CURSOR_VERSION, k: "verdicts", a: asOf, p: projectionKey, f: stableFilterKey(filters) };
+}
+
+export function observationCursor(completedAt: number, eventId: string, filters: Record<string, unknown>): ObservationCursorPayload {
+  return { v: LAB_QUERY_CURSOR_VERSION, k: "observations", c: completedAt, e: eventId, f: stableFilterKey(filters) };
+}
+
+export function eventCursor(recordedAt: number, eventId: string, filters: Record<string, unknown>): EventCursorPayload {
+  return { v: LAB_QUERY_CURSOR_VERSION, k: "events", r: recordedAt, e: eventId, f: stableFilterKey(filters) };
+}
+
+export function subjectCursor(subjectId: string, filters: Record<string, unknown>): SubjectCursorPayload {
+  return { v: LAB_QUERY_CURSOR_VERSION, k: "subjects", s: subjectId, f: stableFilterKey(filters) };
+}
+
+export function artifactCursor(digest: string, filters: Record<string, unknown>): ArtifactCursorPayload {
+  return { v: LAB_QUERY_CURSOR_VERSION, k: "artifacts", d: digest, f: stableFilterKey(filters) };
+}