Skip to content
Python
7.2 KB
Raw Blame
import type {
  ModelProbeOperationReceipt,
  ModelProbeOperationRequest,
  ModelProbeResult,
  ProbeCode,
} from "@one-memory/contracts";
import {
  clearPendingModelProbe,
  type PendingModelProbe,
  readPendingModelProbe,
  savePendingModelProbe,
} from "./pending-model-probe";

export interface ModelProbeTransport {
  lookup(operationId: string): Promise<ModelProbeOperationReceipt>;
  probe(
    profileId: string,
    request: ModelProbeOperationRequest,
  ): Promise<ModelProbeOperationReceipt>;
}

const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
const CODES: readonly ProbeCode[] = [
  "ok",
  "hy_default_unavailable",
  "missing_api_key",
  "unreachable",
  "unauthorized",
  "rate_limited",
  "insufficient_balance",
  "model_not_found",
  "model_list_unsupported",
  "invalid_response",
  "structured_output_unsupported",
  "embedding_model_required",
  "embedding_unavailable",
];
let inFlight = false;

function fail(code = "model_probe_operation_unavailable"): never {
  throw new Error(code);
}
function uuid(value: unknown): value is string {
  return typeof value === "string" && value.length === 36 && UUID.test(value);
}
function revision(value: unknown): value is number {
  return typeof value === "number" && Number.isSafeInteger(value) && value >= 1;
}
function object(
  value: unknown,
  required: readonly string[],
  optional: readonly string[] = [],
): Record<string, unknown> {
  if (!value || typeof value !== "object" || Array.isArray(value)) fail();
  const keys = Reflect.ownKeys(value);
  if (
    keys.some(
      (key) =>
        typeof key !== "string" || ![...required, ...optional].includes(key),
    ) ||
    required.some((key) => !Object.hasOwn(value, key))
  )
    fail();
  const result: Record<string, unknown> = {};
  for (const key of keys) {
    const descriptor = Object.getOwnPropertyDescriptor(value, key);
    if (!descriptor || !("value" in descriptor)) fail();
    result[key as string] = descriptor.value;
  }
  return result;
}

function validateResult(
  value: unknown,
  pending: PendingModelProbe,
): ModelProbeResult {
  const result = object(value, [
    "profile_id",
    "profile_revision",
    "input_profile_revision",
    "stages",
    "capabilities",
  ]);
  if (
    result.profile_id !== pending.profileId ||
    result.input_profile_revision !== pending.inputRevision ||
    !revision(result.profile_revision) ||
    (result.profile_revision !== pending.inputRevision &&
      result.profile_revision !== pending.inputRevision + 1)
  )
    fail();
  const capabilities = object(result.capabilities, [
    "endpoint_reachable",
    "model_available",
    "structured_output",
    "embedding_available",
  ]);
  if (Object.values(capabilities).some((value) => typeof value !== "boolean"))
    fail();
  if (
    !Array.isArray(result.stages) ||
    result.stages.length < 1 ||
    result.stages.length > 4
  )
    fail();
  const stages = result.stages.map((value) => {
    const stage = object(
      value,
      ["stage", "ok", "code", "latency_ms"],
      ["embedding_dimensions"],
    );
    if (
      typeof stage.stage !== "string" ||
      ![
        "endpoint",
        "provider",
        "authentication",
        "model",
        "structured_output",
        "embedding",
      ].includes(stage.stage) ||
      typeof stage.ok !== "boolean" ||
      !CODES.includes(stage.code as ProbeCode) ||
      typeof stage.latency_ms !== "number" ||
      !Number.isSafeInteger(stage.latency_ms) ||
      stage.latency_ms < 0 ||
      (stage.embedding_dimensions !== undefined &&
        stage.embedding_dimensions !== null &&
        !revision(stage.embedding_dimensions))
    )
      fail();
    return stage;
  });
  // Project validated data, never expose extra fields from a transport response.
  return { ...result, stages, capabilities } as unknown as ModelProbeResult;
}

function receipt(value: unknown, operationId: string): Record<string, unknown> {
  const item = object(value, [
    "schema_version",
    "operation_id",
    "profile_id",
    "expected_profile_revision",
    "state",
    "result",
    "code",
    "stale",
  ]);
  if (
    item.schema_version !== 1 ||
    item.operation_id !== operationId ||
    !uuid(item.operation_id) ||
    !["pending", "completed", "failed", "not_found"].includes(
      item.state as string,
    )
  )
    fail();
  if (item.state === "not_found") {
    if (
      item.profile_id !== null ||
      item.expected_profile_revision !== null ||
      item.result !== null ||
      item.code !== null ||
      item.stale !== null
    )
      fail();
  } else if (
    !uuid(item.profile_id) ||
    !revision(item.expected_profile_revision) ||
    typeof item.stale !== "boolean"
  )
    fail();
  return item;
}

function consume(value: unknown, pending: PendingModelProbe): ModelProbeResult {
  const item = receipt(value, pending.operationId);
  if (item.state === "not_found") fail("model_probe_operation_pending");
  if (
    item.profile_id !== pending.profileId ||
    item.expected_profile_revision !== pending.inputRevision
  )
    fail();
  if (item.state === "pending") {
    if (item.result !== null || item.code !== null) fail();
    fail("model_probe_operation_pending");
  }
  if (item.state === "failed") {
    if (
      item.result !== null ||
      !["model_probe_profile_changed", "model_probe_execution_failed"].includes(
        item.code as string,
      )
    )
      fail();
    clearPendingModelProbe(pending.operationId);
    fail("model_probe_operation_stale");
  }
  if (item.code !== null) fail();
  const result = validateResult(item.result, pending);
  clearPendingModelProbe(pending.operationId);
  if (item.stale) fail("model_probe_operation_stale");
  return result;
}

/** One local operation at a time; persisted unknown operations are GET-only.
 * This module neither activates models nor infers retry permission from not_found.
 */
export async function recoverableProbe(
  profileId: string,
  inputRevision: number,
  transport: ModelProbeTransport,
): Promise<ModelProbeResult> {
  if (inFlight) fail("model_probe_in_flight");
  inFlight = true;
  try {
    const previous = readPendingModelProbe();
    if (!uuid(profileId) || !revision(inputRevision))
      fail("model_probe_input_invalid");
    if (previous) {
      if (previous.profileId !== profileId)
        fail("model_probe_other_profile_pending");
      let result: unknown;
      try {
        result = await transport.lookup(previous.operationId);
      } catch {
        return fail("model_probe_operation_pending");
      }
      return consume(result, previous);
    }
    let operationId: string;
    try {
      operationId = crypto.randomUUID();
      if (!uuid(operationId)) fail();
      const capability = receipt(
        await transport.lookup(operationId),
        operationId,
      );
      if (capability.state !== "not_found") fail();
    } catch {
      return fail("model_probe_capability_unavailable");
    }
    const pending = { operationId, profileId, inputRevision };
    savePendingModelProbe(pending);
    let result: unknown;
    try {
      result = await transport.probe(profileId, {
        operation_id: operationId,
        expected_profile_revision: inputRevision,
      });
    } catch {
      return fail("model_probe_operation_pending");
    }
    return consume(result, pending);
  } finally {
    inFlight = false;
  }
}