@iislee/opencodex 2.11.0 → 2.35.0

package/src/lab/query/types.ts

@@ -0,0 +1,266 @@
+import type {
+  ArtifactClass,
+  CompatibilityVerdict,
+  EvidenceLayer,
+  ExecutionMode,
+  InvalidationReason,
+  LabEventKind,
+  ObservationOutcome,
+  PurgeAction,
+} from "../constants";
+
+export interface LabStatusDto {
+  projectionAvailable: boolean;
+  projectionIncompatible?: boolean;
+  sqliteSchemaVersion?: number;
+  projectionSpecVersion?: string;
+  builtAtMs?: number;
+  eventCount?: number;
+  subjectCount?: number;
+  observationCount?: number;
+  claimCount?: number;
+  verdictCount?: number;
+  artifactCount?: number;
+  corruptionCount?: number;
+}
+
+export interface VerdictDto {
+  projectionKey: string;
+  subjectId: string;
+  evidenceLayer: EvidenceLayer;
+  suiteId: string;
+  suiteVersion: string;
+  suiteManifestDigest: string;
+  projectionSpecVersion: string;
+  verdict: CompatibilityVerdict;
+  asOf: number;
+  scenarioManifestDigests: string[];
+  claimSourceDigest: string | null;
+  contributingEventIds: string[];
+  contradictingEventIds: string[];
+  notes: string[];
+}
+
+export interface ProtocolSubjectDto {
+  subjectKind: "protocol";
+  subjectSchemaVersion: 1;
+  opencodexCompatibilityVersion: string;
+  effectiveAdapter: string;
+  inboundProtocol: string;
+  upstreamProtocol: string;
+  surface: string;
+  behaviorFingerprint: string;
+}
+
+export interface RouteDependencyDto {
+  role: string;
+  providerId: string;
+  providerInstanceFingerprint: string;
+  clientModelId: string;
+  upstreamModelId: string;
+  effectiveAdapter: string;
+  upstreamProtocol: string;
+  endpointFingerprint: string;
+  behaviorFingerprint: string;
+}
+
+export interface RouteSubjectDto {
+  subjectKind: "route";
+  subjectSchemaVersion: 1;
+  providerId: string;
+  providerInstanceFingerprint: string;
+  clientModelId: string;
+  upstreamModelId: string;
+  effectiveAdapter: string;
+  inboundProtocol: string;
+  upstreamProtocol: string;
+  surface: string;
+  opencodexCompatibilityVersion: string;
+  behaviorFingerprint: string;
+  endpointFingerprint: string;
+  dependencies: RouteDependencyDto[];
+}
+
+export interface TaskSubjectDto {
+  subjectKind: "task";
+  subjectSchemaVersion: 1;
+  routeSubject: RouteSubjectDto;
+  taskClassId: string;
+  taskClassVersion: string;
+  taskFixtureDigest: string;
+  verifierManifestDigest: string;
+  fabricCompatibilityVersion: string;
+  sandboxProfileDigest: string;
+}
+
+export type SubjectDto = ProtocolSubjectDto | RouteSubjectDto | TaskSubjectDto;
+
+export interface SubjectListItemDto {
+  subjectId: string;
+  subjectKind: string;
+}
+
+export interface ObservationDto {
+  eventId: string;
+  subjectId: string;
+  evidenceLayer: EvidenceLayer;
+  suiteId: string;
+  suiteVersion: string;
+  suiteManifestDigest: string;
+  scenarioId: string;
+  scenarioVersion: string;
+  scenarioManifestDigest: string;
+  outcome: ObservationOutcome;
+  completedAt: number;
+  executionMode: ExecutionMode;
+  excluded: boolean;
+  exclusionReason: string | null;
+}
+
+export interface ObservationEventDto {
+  eventKind: "observation";
+  eventId: string;
+  recordedAt: number;
+  producer: string;
+  producerVersion: string;
+  evidenceLayer: EvidenceLayer;
+  scenarioId: string;
+  scenarioVersion: string;
+  scenarioManifestDigest: string;
+  suiteId: string;
+  suiteVersion: string;
+  suiteManifestDigest: string;
+  subjectId: string;
+  startedAt: number;
+  completedAt: number;
+  executionMode: ExecutionMode;
+  attempt: number;
+  outcome: ObservationOutcome;
+  excluded: boolean;
+  exclusionReason: string | null;
+}
+
+export interface ClaimSnapshotEventDto {
+  eventKind: "claim_snapshot";
+  eventId: string;
+  recordedAt: number;
+  producer: string;
+  producerVersion: string;
+  subjectId: string;
+  capability: string;
+  polarity: string;
+  sourceManifestDigest: string;
+  effectiveAt: number;
+  excluded: boolean;
+  exclusionReason: string | null;
+}
+
+export interface InvalidationEventDto {
+  eventKind: "invalidation";
+  eventId: string;
+  recordedAt: number;
+  producer: string;
+  producerVersion: string;
+  reason: InvalidationReason;
+  targetEventIds: string[];
+  excluded: boolean;
+  exclusionReason: string | null;
+}
+
+export interface PurgeTombstoneEventDto {
+  eventKind: "purge_tombstone";
+  eventId: string;
+  recordedAt: number;
+  producer: string;
+  producerVersion: string;
+  targetEventIds: string[];
+  targetArtifactDigests: string[];
+  purgeActions: PurgeAction[];
+  excluded: boolean;
+  exclusionReason: string | null;
+}
+
+export type LabEventDto =
+  | ObservationEventDto
+  | ClaimSnapshotEventDto
+  | InvalidationEventDto
+  | PurgeTombstoneEventDto;
+
+export interface EventListItemDto {
+  eventId: string;
+  eventKind: LabEventKind;
+  recordedAt: number;
+  excluded: boolean;
+  exclusionReason: string | null;
+}
+
+export interface ArtifactMetadataDto {
+  digest: string;
+  artifactClass: ArtifactClass | null;
+  mediaType: string | null;
+  byteCount: number | null;
+  status: "present" | "corrupt" | "purged_unavailable";
+  lastError: string | null;
+}
+
+export interface CatalogScenarioDto {
+  scenarioId: string;
+  scenarioVersion: string;
+  evidenceLayer: EvidenceLayer;
+  suiteId: string;
+  suiteVersion: string;
+  capability: string;
+  verificationRole: string;
+  requirements: {
+    inboundProtocols: string[];
+    upstreamProtocols: string[];
+    surfaces: string[];
+  };
+  freshness: Record<string, unknown>;
+  scenarioManifestDigest: string;
+  suiteManifestDigest: string;
+}
+
+export interface PaginatedResult<T> {
+  items: T[];
+  nextCursor?: string;
+  hasMore: boolean;
+}
+
+export interface VerdictFilters {
+  subjectId?: string;
+  layer?: EvidenceLayer;
+  suiteId?: string;
+  verdict?: CompatibilityVerdict;
+  from?: number;
+  to?: number;
+}
+
+export interface ObservationFilters {
+  subjectId?: string;
+  layer?: EvidenceLayer;
+  suiteId?: string;
+  scenarioId?: string;
+  outcome?: ObservationOutcome;
+  executionMode?: ExecutionMode;
+  from?: number;
+  to?: number;
+}
+
+export interface EventFilters {
+  eventKind?: LabEventKind;
+  subjectId?: string;
+  from?: number;
+  to?: number;
+  excluded?: boolean;
+}
+
+export interface ArtifactFilters {
+  status?: "present" | "corrupt" | "purged_unavailable";
+  artifactClass?: ArtifactClass;
+}
+
+export interface CatalogFilters {
+  layer?: EvidenceLayer;
+  suiteId?: string;
+}

package/src/lab/subject/behavior-fingerprint.ts

@@ -0,0 +1,77 @@
+import { createHash } from "node:crypto";
+import { jcsStringify } from "../digest";
+import type { LabBehaviorSource, LabBehaviorValues } from "../live/types";
+
+const CLOSED_KEYS = new Set([
+  "wire.adapter", "wire.upstreamProtocol", "wire.responsesPath", "wire.commandCodeVersion", "wire.modelSuffixMode",
+  "auth.mode", "auth.transport",
+  "responses.stateful", "responses.upstreamStreaming", "responses.serviceTier", "responses.fastWireKind", "responses.fastWireValue", "responses.snapshotRepair", "responses.itemIdRepair",
+  "limits.contextWindow", "limits.maxInputTokens", "limits.maxOutputTokens",
+  "modalities.input",
+  "sampling.omitTemperature", "sampling.omitTopP", "sampling.omitPenalties",
+  "reasoning.supported", "reasoning.efforts", "reasoning.defaultEffort", "reasoning.effortMap", "reasoning.wireFormat",
+  "reasoning.summaryMode", "reasoning.replayMode", "reasoning.splitMode", "reasoning.toggleMode", "reasoning.budgetMode",
+  "tools.choiceRestrictions", "tools.parallel", "tools.hostedPreference", "tools.customFreeform", "tools.builtinNameEscaping",
+  "cache.forwarding", "cache.retention", "anthropic.eofPolicy", "openai-chat.eofPolicy",
+  "google.mode", "google.projectFingerprint", "google.locationFingerprint",
+  "openrouter.order", "openrouter.only", "openrouter.allowFallbacks",
+  "sidecars.vision", "sidecars.webSearch",
+  "mcp.maxTools", "mcp.maxSchemaBytes", "mcp.maxResultBytes", "mcp.nativeLocalExec",
+  "runtime.bunVersion", "runtime.platform", "runtime.arch", "runtime.streamMode", "runtime.fastMode", "runtime.effortCap",
+  "headers.nonCredentialBehaviorDigest",
+] as const);
+
+const SOURCES = new Set<LabBehaviorSource>([
+  "request", "model_override", "provider_config", "registry_runtime_default", "generated_model_metadata",
+  "global_config", "adapter_default", "lab_forced",
+]);
+
+const SET_ARRAY_KEYS = new Set(["modalities.input", "reasoning.efforts", "tools.choiceRestrictions", "openrouter.only"]);
+const ORDERED_ARRAY_KEYS = new Set(["openrouter.order"]);
+const REQUIRED_KEYS = [
+  "wire.adapter", "wire.upstreamProtocol", "auth.mode", "auth.transport", "mcp.nativeLocalExec",
+  "runtime.bunVersion", "runtime.platform", "runtime.arch", "runtime.streamMode", "runtime.fastMode", "runtime.effortCap",
+] as const;
+
+function canonicalArray(key: string, value: unknown[]): unknown[] {
+  if (SET_ARRAY_KEYS.has(key)) {
+    const byBytes = value.map((item) => ({ item, bytes: jcsStringify(item) }));
+    const seen = new Set<string>();
+    for (const row of byBytes) {
+      if (seen.has(row.bytes)) throw new Error(`harness_failure: duplicate behavior array value for ${key}`);
+      seen.add(row.bytes);
+    }
+    byBytes.sort((a, b) => a.bytes < b.bytes ? -1 : a.bytes > b.bytes ? 1 : 0);
+    return byBytes.map((row) => row.item);
+  }
+  if (ORDERED_ARRAY_KEYS.has(key)) return [...value];
+  throw new Error(`harness_failure: unclassified_behavior_input array for ${key}`);
+}
+
+export function normalizeBehaviorValues(values: LabBehaviorValues): LabBehaviorValues {
+  if (!values || typeof values !== "object" || Array.isArray(values)) {
+    throw new Error("harness_failure: behavior resolver output is required");
+  }
+  for (const key of REQUIRED_KEYS) {
+    if (!(key in values)) throw new Error(`harness_failure: unclassified_behavior_input missing ${key}`);
+  }
+  const normalized: LabBehaviorValues = {};
+  for (const key of Object.keys(values).sort()) {
+    if (!CLOSED_KEYS.has(key as never)) throw new Error(`harness_failure: unclassified_behavior_input ${key}`);
+    const row = values[key];
+    if (!row || typeof row !== "object" || Array.isArray(row) || !SOURCES.has(row.source)) {
+      throw new Error(`harness_failure: invalid behavior source for ${key}`);
+    }
+    normalized[key] = {
+      source: row.source,
+      value: Array.isArray(row.value) ? canonicalArray(key, row.value) : row.value,
+    };
+  }
+  return normalized;
+}
+
+/** Hash the authoritative production resolver output; Lab performs validation/canonicalization only. */
+export function buildBehaviorFingerprintV1(values: LabBehaviorValues): string {
+  const payload = { schemaVersion: 1, resolverVersion: 2, values: normalizeBehaviorValues(values) };
+  return createHash("sha256").update(jcsStringify(payload)).digest("hex");
+}

package/src/lab/subject/installation-salt.ts

@@ -0,0 +1,112 @@
+import { closeSync, fsyncSync, linkSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { dirname } from "node:path";
+import { labInstallationSaltPath, labRoot } from "../paths";
+
+const SALT_BYTES = 32;
+export const INSTALLATION_SALT_CACHE_MAX_ENTRIES = 16;
+export const installationSaltCache = new Map<string, Uint8Array>();
+const UNSUPPORTED_DIRECTORY_FSYNC_CODES = new Set(["EINVAL", "ENOTSUP", "EOPNOTSUPP", "ENOSYS"]);
+
+export function rememberInstallationSalt(path: string, salt: Uint8Array): void {
+  installationSaltCache.delete(path);
+  installationSaltCache.set(path, salt);
+  while (installationSaltCache.size > INSTALLATION_SALT_CACHE_MAX_ENTRIES) {
+    const oldest = installationSaltCache.keys().next().value;
+    if (oldest === undefined) break;
+    installationSaltCache.delete(oldest);
+  }
+}
+
+function readSaltFile(path: string): Uint8Array {
+  const bytes = readFileSync(path);
+  if (bytes.byteLength !== SALT_BYTES) {
+    throw new Error("harness_failure: invalid installation salt length");
+  }
+  return new Uint8Array(bytes);
+}
+
+function cacheSalt(path: string, salt: Uint8Array): Uint8Array {
+  const cached = new Uint8Array(salt);
+  rememberInstallationSalt(path, cached);
+  return new Uint8Array(cached);
+}
+
+/** Read the existing local fingerprint salt without creating Lab state. */
+export function readExistingInstallationSalt(configDir?: string): Uint8Array | null {
+  const path = labInstallationSaltPath(configDir);
+  const cached = installationSaltCache.get(path);
+  if (cached) return new Uint8Array(cached);
+  try {
+    return cacheSalt(path, readSaltFile(path));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+function removeStagingFile(path: string): void {
+  try { unlinkSync(path); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+}
+
+function fsyncDirectory(path: string): void {
+  // Windows has no portable directory-fsync primitive. Some POSIX-backed
+  // filesystems (notably virtual/shared filesystems) report directory fsync as
+  // unsupported. In those cases the fsync'd staging inode plus atomic same-dir
+  // hard-link publication is the supported durability fallback. Unexpected I/O
+  // errors remain fatal.
+  if (process.platform === "win32") return;
+  const dirFd = openSync(path, "r");
+  try {
+    try { fsyncSync(dirFd); }
+    catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code && UNSUPPORTED_DIRECTORY_FSYNC_CODES.has(code)) return;
+      throw error;
+    }
+  } finally { closeSync(dirFd); }
+}
+
+/** Read or atomically publish the per-installation salt used for local fingerprinting. */
+export function readInstallationSalt(configDir?: string): Uint8Array {
+  const path = labInstallationSaltPath(configDir);
+  const root = labRoot(configDir);
+  mkdirSync(root, { recursive: true, mode: 0o700 });
+
+  try { return cacheSalt(path, readSaltFile(path)); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+
+  // The final pathname must never become visible before all 32 bytes are durable in the
+  // staging inode. A hard-link publish is atomic and fails with EEXIST when another process won.
+  const stagingPath = `${path}.tmp-${process.pid}-${randomBytes(8).toString("hex")}`;
+  if (dirname(stagingPath) !== dirname(path)) throw new Error("harness_failure: installation salt staging path escaped directory");
+  const salt = randomBytes(SALT_BYTES);
+  let fd: number | undefined;
+  try {
+    fd = openSync(stagingPath, "wx", 0o600);
+    writeFileSync(fd, salt);
+    fsyncSync(fd);
+    closeSync(fd);
+    fd = undefined;
+
+    try {
+      linkSync(stagingPath, path);
+      try { fsyncDirectory(dirname(path)); }
+      catch { throw new Error("harness_failure: installation salt directory fsync failed"); }
+      return cacheSalt(path, salt);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      return cacheSalt(path, readSaltFile(path));
+    }
+  } finally {
+    if (fd !== undefined) {
+      try { closeSync(fd); } catch { /* best-effort close before cleanup */ }
+    }
+    removeStagingFile(stagingPath);
+  }
+}

package/src/lab/subject/protocol-subject.ts

@@ -0,0 +1,80 @@
+import { createHash } from "node:crypto";
+import { jcsStringify } from "../digest";
+import type { ProtocolSubjectV1 } from "../events/types";
+import type { ProtocolExecutionContextV1 } from "../conformance/types";
+
+/** Frozen CL-01 protocol compatibility identity. */
+export const PROTOCOL_COMPATIBILITY_VERSION = "protocol-v1";
+
+/** Adapter identity used by the deterministic protocol harness for a wire protocol. */
+export function protocolAdapterForUpstreamProtocol(protocol: string): string {
+  switch (protocol) {
+    case "openai-responses":
+      return "openai-responses";
+    case "anthropic-messages":
+      return "anthropic";
+    case "openai-chat":
+      return "openai-chat";
+    default:
+      throw new Error(`unsupported protocol identity: ${protocol}`);
+  }
+}
+
+/**
+ * Exact CL-01 behavior fingerprint for one protocol execution context.
+ *
+ * `effectiveAdapter` is optional so the harness keeps its historical mapping,
+ * while routing consumers may require an exact production adapter match. A
+ * provider-specific adapter that merely speaks an OpenAI-shaped wire therefore
+ * cannot borrow generic protocol evidence unless CL-01 actually produced the
+ * same adapter identity.
+ */
+export function protocolBehaviorFingerprintV1(
+  ctx: ProtocolExecutionContextV1,
+  effectiveAdapter = protocolAdapterForUpstreamProtocol(ctx.upstreamProtocol),
+): string {
+  const values = {
+    schemaVersion: 1,
+    resolverVersion: 1,
+    values: {
+      "wire.adapter": {
+        source: "lab_forced",
+        value: effectiveAdapter,
+      },
+      "wire.upstreamProtocol": {
+        source: "lab_forced",
+        value: ctx.upstreamProtocol,
+      },
+      "runtime.arch": {
+        source: "lab_forced",
+        value: process.arch,
+      },
+      "runtime.bunVersion": {
+        source: "lab_forced",
+        value: process.versions.bun ?? Bun.version,
+      },
+      "runtime.platform": {
+        source: "lab_forced",
+        value: process.platform,
+      },
+    },
+  };
+  return createHash("sha256").update(jcsStringify(values)).digest("hex");
+}
+
+/** Build the exact ProtocolSubjectV1 consumed by CL-01 projection. */
+export function buildProtocolSubjectV1(
+  ctx: ProtocolExecutionContextV1,
+  effectiveAdapter = protocolAdapterForUpstreamProtocol(ctx.upstreamProtocol),
+): ProtocolSubjectV1 {
+  return Object.freeze({
+    subjectSchemaVersion: 1,
+    subjectKind: "protocol",
+    opencodexCompatibilityVersion: PROTOCOL_COMPATIBILITY_VERSION,
+    effectiveAdapter,
+    inboundProtocol: ctx.inboundProtocol,
+    upstreamProtocol: ctx.upstreamProtocol,
+    surface: ctx.surface,
+    behaviorFingerprint: protocolBehaviorFingerprintV1(ctx, effectiveAdapter),
+  });
+}

package/src/lab/subject/route-subject.ts

@@ -0,0 +1,74 @@
+import { localFingerprint } from "../digest";
+import type { RouteDependencyV1, RouteSubjectV1 } from "../events/types";
+import type { LabDestinationV1, LabRouteContext } from "../live/types";
+import { buildBehaviorFingerprintV1 } from "./behavior-fingerprint";
+import { readInstallationSalt } from "./installation-salt";
+
+function compareDependency(a: RouteDependencyV1, b: RouteDependencyV1): number {
+  const fields: Array<keyof RouteDependencyV1> = [
+    "role", "providerId", "providerInstanceFingerprint", "upstreamModelId", "endpointFingerprint",
+    "clientModelId", "effectiveAdapter", "upstreamProtocol", "behaviorFingerprint",
+  ];
+  for (const field of fields) {
+    const av = a[field];
+    const bv = b[field];
+    if (av < bv) return -1;
+    if (av > bv) return 1;
+  }
+  return 0;
+}
+
+function canonicalDependencies(dependencies: RouteDependencyV1[] | undefined): RouteDependencyV1[] {
+  const rows = (dependencies ?? []).map((row) => Object.freeze({ ...row }));
+  rows.sort(compareDependency);
+  for (let i = 1; i < rows.length; i++) {
+    if (compareDependency(rows[i - 1]!, rows[i]!) === 0) {
+      throw new Error("harness_failure: duplicate route dependency");
+    }
+  }
+  return rows;
+}
+
+/** Build RouteSubjectV1 only from an approved immutable destination and authoritative effective resolver inputs. */
+export function buildRouteSubjectV1(
+  routeContext: LabRouteContext,
+  destination: LabDestinationV1,
+  configDir?: string,
+  installationSalt?: Uint8Array | string,
+): RouteSubjectV1 {
+  if (!routeContext.providerInstanceKey) throw new Error("harness_failure: provider instance identity is required");
+  if (!/^[0-9a-f]{64}$/.test(routeContext.opencodexCompatibilityVersion)) {
+    throw new Error("harness_failure: invalid opencodexCompatibilityVersion");
+  }
+  const adapterValue = routeContext.behaviorValues["wire.adapter"]?.value;
+  const protocolValue = routeContext.behaviorValues["wire.upstreamProtocol"]?.value;
+  if (adapterValue !== routeContext.effectiveAdapter || protocolValue !== routeContext.upstreamProtocol) {
+    throw new Error("harness_failure: behavior resolver output does not match exact route");
+  }
+  const salt = installationSalt ?? readInstallationSalt(configDir);
+  const providerInstanceFingerprint = localFingerprint("providerInstance", routeContext.providerInstanceKey, salt);
+  const dependencies = canonicalDependencies(routeContext.dependencies);
+  const subject: RouteSubjectV1 = {
+    subjectSchemaVersion: 1,
+    subjectKind: "route",
+    providerId: routeContext.providerId,
+    providerInstanceFingerprint,
+    clientModelId: routeContext.clientModelId,
+    upstreamModelId: routeContext.upstreamModelId,
+    effectiveAdapter: routeContext.effectiveAdapter,
+    inboundProtocol: routeContext.inboundProtocol,
+    upstreamProtocol: routeContext.upstreamProtocol,
+    surface: routeContext.surface,
+    opencodexCompatibilityVersion: routeContext.opencodexCompatibilityVersion,
+    behaviorFingerprint: buildBehaviorFingerprintV1(routeContext.behaviorValues),
+    endpointFingerprint: destination.fingerprint,
+    dependencies,
+  };
+  return freezeRouteSubject(subject);
+}
+
+/** Deep-freeze route dependencies as well as the subject shell. */
+export function freezeRouteSubject(subject: RouteSubjectV1): RouteSubjectV1 {
+  const dependencies = subject.dependencies.map((row) => Object.freeze({ ...row }));
+  return Object.freeze({ ...subject, dependencies: Object.freeze(dependencies) as unknown as RouteDependencyV1[] });
+}

package/src/lib/admin-secrets.ts

@@ -1,3 +1,4 @@
+import { timingSafeEqual } from "node:crypto";
 import { lstatSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { getConfigDir } from "../config";
@@ -23,3 +24,26 @@ export function loadAdminTokenFromFile(configDir = getConfigDir()): string | nul
 export function configuredAdminToken(configDir = getConfigDir(), env: NodeJS.ProcessEnv = process.env): string | null {
   return env.OPENCODEX_ADMIN_AUTH_TOKEN?.trim() || loadAdminTokenFromFile(configDir);
 }
+
+export const ADMIN_TOKEN_PREFIX = "ocx_admin_";
+
+function secretTextEquals(left: string, right: string): boolean {
+  const a = Buffer.from(left);
+  const b = Buffer.from(right);
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+/**
+ * True when `token` is a management credential: minted `ocx_admin_…` shape, or
+ * byte-equal to the configured admin token (env or admin-api-token file).
+ * Used by the service write/start chokepoint and by doctor so the two cannot drift.
+ */
+export function tokenCollidesWithAdmin(
+  token: string,
+  env: NodeJS.ProcessEnv = process.env,
+  configDir = getConfigDir(),
+): boolean {
+  if (token.startsWith(ADMIN_TOKEN_PREFIX)) return true;
+  const admin = configuredAdminToken(configDir, env);
+  return admin !== null && secretTextEquals(token, admin);
+}

package/src/lib/app-owned-memory-stores.ts

@@ -34,6 +34,10 @@ import {
   evictOldestUsageSummaryForBudget,
   usageSummaryRetainedStoreSnapshot,
 } from "../server/management/usage-summary-cache";
+import {
+  discardRetainedUsageSnapshot,
+  retainedUsageSnapshotStats,
+} from "../usage/log";
 import {
   cursorBlobRetainedStoreSnapshot,
   evictOldestCursorBlobForBudget,
@@ -57,6 +61,18 @@ function ringSnapshot(metrics: { entries: number; bytes: number; oldestAt: numbe
   };
 }
 
+/** The retained usage tail is a single all-or-nothing entry: evicting it drops the whole tail. */
+function usageSnapshotRetainedStoreSnapshot(): RetainedStoreSnapshot {
+  const stats = retainedUsageSnapshotStats();
+  return {
+    count: stats.count,
+    bytes: stats.bytes,
+    evictableBytes: stats.bytes,
+    pinnedBytes: 0,
+    oldestAt: stats.oldestAt,
+  };
+}
+
 function providerDebugSnapshot(): RetainedStoreSnapshot {
   return ringSnapshot(debugBufferMetrics());
 }
@@ -134,6 +150,12 @@ export const APP_OWNED_RETAINED_STORE_REGISTRATIONS = [
     snapshot: usageSummaryRetainedStoreSnapshot,
     evictOldest: evictOldestUsageSummaryForBudget,
   },
+  {
+    id: "usage_snapshot",
+    category: "caches",
+    snapshot: usageSnapshotRetainedStoreSnapshot,
+    evictOldest: discardRetainedUsageSnapshot,
+  },
   {
     id: "cursor_blobs",
     category: "blobs",