/*
 * SPEC: PJ2026-010403 API契约 draft-2026-06-17-r0; PJ2026-0102 Agent编排 draft-2026-06-17-r0; PJ2026-0104010803 Workbench唯一投影 draft-2026-06-19-p1-agentrun-incremental-cursor; draft-2026-06-20-p1-zero-split-durable-realtime; draft-2026-06-24-p0-aggregate-event-stream; PJ2026-010205 HWLAB接入 draft-2026-06-25-p0-session-warm-runner-contract.
 * 职责: Cloud runtime durable store。Code Agent trace/session/projection cursor 投影事实必须从同一持久化适配器写入和恢复。
 */
import { createHash, randomUUID } from "node:crypto";

import {
  ENVIRONMENT_DEV,
  ERROR_CODES,
  HwlabProtocolError,
  assertProtocolRecord
} from "../protocol/index.mjs";
import {
  CLOUD_API_SERVICE_ID,
  createProtocolAuditEvent,
  deriveProtocolActorFromMeta
} from "../audit/index.mjs";
import {
  CLOUD_CORE_MIGRATION_ID,
  CLOUD_RUNTIME_DURABLE_ADAPTER_SCHEMA_VERSION,
  CLOUD_RUNTIME_DURABLE_MIGRATION_TABLE,
  CLOUD_RUNTIME_DURABLE_TABLE_COLUMNS
} from "./schema.ts";

export const RUNTIME_STORE_KIND = "memory";
export const RUNTIME_STORE_KIND_POSTGRES = "postgres";
export const RUNTIME_DURABLE_ADAPTER_MISSING = "runtime_durable_adapter_missing";
export const RUNTIME_DURABLE_ADAPTER_UNCONFIGURED = "runtime_durable_adapter_unconfigured";
export const RUNTIME_DURABLE_ADAPTER_DRIVER_MISSING = "runtime_durable_adapter_driver_missing";
export const RUNTIME_DURABLE_ADAPTER_SSL_BLOCKED = "runtime_durable_adapter_ssl_blocked";
export const RUNTIME_DURABLE_ADAPTER_AUTH_BLOCKED = "runtime_durable_adapter_auth_blocked";
export const RUNTIME_DURABLE_ADAPTER_SCHEMA_BLOCKED = "runtime_durable_adapter_schema_blocked";
export const RUNTIME_DURABLE_ADAPTER_MIGRATION_BLOCKED = "runtime_durable_adapter_migration_blocked";
export const RUNTIME_DURABLE_ADAPTER_QUERY_BLOCKED = "runtime_durable_adapter_query_blocked";
export const RUNTIME_DURABILITY_REQUIRED_EVIDENCE = "runtime_adapter_schema_migration_read_query";

export const RUNTIME_ADAPTER_ENV = "HWLAB_CLOUD_RUNTIME_ADAPTER";
export const RUNTIME_DURABLE_ENV = "HWLAB_CLOUD_RUNTIME_DURABLE";
export const RUNTIME_DB_POOL_MAX_ENV = "HWLAB_CLOUD_DB_POOL_MAX";

export const requiredPostgresSchema = CLOUD_RUNTIME_DURABLE_TABLE_COLUMNS;

export const postgresCountTables = Object.freeze([
  "users",
  "user_sessions",
  "gateway_sessions",
  "box_resources",
  "box_capabilities",
  "hardware_operations",
  "audit_events",
  "evidence_records",
  "agent_sessions",
  "account_workspaces",
  "worker_sessions",
  "agent_trace_events",
  "workbench_projection_state",
  "workbench_sessions",
  "workbench_messages",
  "workbench_parts",
  "workbench_turns",
  "workbench_trace_events",
  "workbench_event_sequences",
  "workbench_events",
  "workbench_session_inputs",
  "workbench_projection_checkpoints"
]);

export const postgresRuntimeReadIndexes = Object.freeze([
  "CREATE INDEX IF NOT EXISTS idx_agent_trace_events_trace_order ON agent_trace_events(trace_id, occurred_at, id)",
  "CREATE INDEX IF NOT EXISTS idx_agent_trace_events_session_order ON agent_trace_events(agent_session_id, occurred_at, id)",
  "CREATE INDEX IF NOT EXISTS idx_agent_trace_events_worker_order ON agent_trace_events(worker_session_id, occurred_at, id)",
  "CREATE INDEX IF NOT EXISTS idx_workbench_projection_state_status_retry_updated ON workbench_projection_state(projection_status, next_retry_at, updated_at)",
  "CREATE INDEX IF NOT EXISTS idx_workbench_projection_state_run_command ON workbench_projection_state(run_id, command_id)",
  "CREATE INDEX IF NOT EXISTS idx_workbench_projection_state_session_updated ON workbench_projection_state(session_id, updated_at DESC)",
  "CREATE INDEX IF NOT EXISTS idx_workbench_sessions_updated ON workbench_sessions(updated_at DESC, session_id)",
  "CREATE INDEX IF NOT EXISTS idx_workbench_sessions_owner_updated ON workbench_sessions(owner_user_id, updated_at DESC, session_id)",
  "CREATE INDEX IF NOT EXISTS idx_workbench_sessions_status_updated ON workbench_sessions(status, updated_at DESC, session_id)",
  "CREATE INDEX IF NOT EXISTS idx_workbench_messages_session_updated ON workbench_messages(session_id, updated_at ASC, message_id)",
  "CREATE INDEX IF NOT EXISTS idx_workbench_messages_trace ON workbench_messages(trace_id, message_id)",
  "CREATE INDEX IF NOT EXISTS idx_workbench_messages_turn ON workbench_messages(turn_id, message_id)",
  "CREATE INDEX IF NOT EXISTS idx_workbench_parts_message_index ON workbench_parts(message_id, part_index, part_id)",
  "CREATE INDEX IF NOT EXISTS idx_workbench_parts_session_trace ON workbench_parts(session_id, trace_id, part_index)",
  "CREATE INDEX IF NOT EXISTS idx_workbench_turns_session_updated ON workbench_turns(session_id, updated_at DESC, turn_id)",
  "CREATE INDEX IF NOT EXISTS idx_workbench_turns_trace ON workbench_turns(trace_id, turn_id)",
  "CREATE INDEX IF NOT EXISTS idx_workbench_trace_events_trace_projected_seq ON workbench_trace_events(trace_id, projected_seq)",
  "CREATE INDEX IF NOT EXISTS idx_workbench_trace_events_session_projected_seq ON workbench_trace_events(session_id, projected_seq)",
  "CREATE INDEX IF NOT EXISTS idx_workbench_event_sequences_session ON workbench_event_sequences(session_id, updated_at DESC, aggregate_id)",
  "CREATE INDEX IF NOT EXISTS idx_workbench_event_sequences_trace ON workbench_event_sequences(trace_id, updated_at DESC, aggregate_id)",
  "CREATE INDEX IF NOT EXISTS idx_workbench_events_trace_seq ON workbench_events(trace_id, event_seq)",
  "CREATE INDEX IF NOT EXISTS idx_workbench_events_session_seq ON workbench_events(session_id, event_seq)",
  "CREATE INDEX IF NOT EXISTS idx_workbench_events_type_seq ON workbench_events(event_type, event_seq)",
  "CREATE INDEX IF NOT EXISTS idx_workbench_session_inputs_session_seq ON workbench_session_inputs(session_id, admitted_seq, input_id)",
  "CREATE INDEX IF NOT EXISTS idx_workbench_session_inputs_trace ON workbench_session_inputs(trace_id, input_id)",
  "CREATE INDEX IF NOT EXISTS idx_workbench_session_inputs_command ON workbench_session_inputs(command_id, input_id) WHERE command_id IS NOT NULL",
  "CREATE INDEX IF NOT EXISTS idx_workbench_projection_checkpoints_status_updated ON workbench_projection_checkpoints(projection_status, updated_at DESC, trace_id)",
  "CREATE INDEX IF NOT EXISTS idx_workbench_projection_checkpoints_session_updated ON workbench_projection_checkpoints(session_id, updated_at DESC, trace_id)"
]);

export function buildPostgresPoolConfig({ dbUrl, sslMode, timeoutMs, poolMax, queryTimeoutMs } = {}) {
  const normalizedSslMode = normalizePostgresSslMode(sslMode ?? postgresSslModeFromConnectionString(dbUrl));
  const normalizedPoolMax = normalizeRuntimePoolMax(poolMax);
  const normalizedQueryTimeoutMs = queryTimeoutMs === undefined || queryTimeoutMs === null || String(queryTimeoutMs).trim() === ""
    ? null
    : normalizeRuntimeTimeoutMs(queryTimeoutMs);
  return {
    connectionString: normalizePostgresConnectionStringForSslMode(dbUrl, normalizedSslMode),
    ssl: postgresSslOption(normalizedSslMode),
    connectionTimeoutMillis: normalizeRuntimeTimeoutMs(timeoutMs),
    ...(normalizedQueryTimeoutMs !== null ? { query_timeout: normalizedQueryTimeoutMs, statement_timeout: normalizedQueryTimeoutMs } : {}),
    ...(normalizedPoolMax !== null ? { max: normalizedPoolMax } : {})
  };
}

export const RUNTIME_DB_QUERY_TIMEOUT_MS_ENV = "HWLAB_CLOUD_DB_QUERY_TIMEOUT_MS";
export const RUNTIME_DB_QUERY_RETRY_MAX_ATTEMPTS_ENV = "HWLAB_CLOUD_DB_QUERY_RETRY_MAX_ATTEMPTS";
export const RUNTIME_DB_QUERY_RETRY_INITIAL_DELAY_MS_ENV = "HWLAB_CLOUD_DB_QUERY_RETRY_INITIAL_DELAY_MS";
export const RUNTIME_DB_QUERY_RETRY_MAX_DELAY_MS_ENV = "HWLAB_CLOUD_DB_QUERY_RETRY_MAX_DELAY_MS";
export const RUNTIME_DB_POOL_RESET_COOLDOWN_MS_ENV = "HWLAB_CLOUD_DB_POOL_RESET_COOLDOWN_MS";
export const DEFAULT_RUNTIME_DB_QUERY_RETRY_MAX_ATTEMPTS = 5;
export const DEFAULT_RUNTIME_DB_QUERY_RETRY_INITIAL_DELAY_MS = 250;
export const DEFAULT_RUNTIME_DB_QUERY_RETRY_MAX_DELAY_MS = 5_000;
export const DEFAULT_RUNTIME_DB_POOL_RESET_COOLDOWN_MS = 10_000;

export function normalizePositiveInteger(value, fallback) {
  const number = Number(value);
  return Number.isFinite(number) && number > 0 ? Math.trunc(number) : fallback;
}

export function delayRuntimeDbQueryRetry(ms) {
  return new Promise((resolve) => setTimeout(resolve, Math.max(0, Math.trunc(Number(ms) || 0))));
}

export function isReadyForDurableRuntimeRead(readiness = {}) {
  return readiness.ready === true && readiness.durable === true && readiness.liveRuntimeEvidence === true;
}

export function normalizeCapabilityInputs(params) {
  const value = params.capabilities ?? params.capability ?? params;
  if (Array.isArray(value)) {
    if (value.length === 0) {
      throw new HwlabProtocolError("capabilities must not be empty", {
        code: ERROR_CODES.invalidParams
      });
    }
    return value.map((item) => asObject(item, "capability"));
  }
  return [asObject(value, "capability")];
}

export function normalizeShellInput(params) {
  const input = normalizeJsonObject(params.input);
  const command = params.command ?? input.command;
  if (command === undefined || command === null || command === "") {
    throw new HwlabProtocolError("hardware.invoke.shell requires input.command or command", {
      code: ERROR_CODES.invalidParams,
      data: {
        required: ["projectId", "gatewaySessionId", "resourceId", "capabilityId", "input.command"]
      }
    });
  }
  if (Array.isArray(command)) {
    return {
      command: command.map((item) => String(item)),
      cwd: input.cwd,
      timeoutMs: input.timeoutMs
    };
  }
  return {
    command: String(command),
    cwd: input.cwd,
    timeoutMs: input.timeoutMs
  };
}

export function normalizeAgentTraceEvent(value, requestMeta = {}, now) {
  const input = normalizeJsonObject(value);
  const traceId = textOr(input.traceId ?? requestMeta.traceId, "");
  if (!traceId) {
    throw new HwlabProtocolError("agent trace event requires traceId", {
      code: ERROR_CODES.invalidParams,
      data: { required: ["traceId"] }
    });
  }
  const seq = positiveIntegerOrNull(input.seq);
  const occurredAt = timestampOr(input.occurredAt ?? input.createdAt ?? input.timestamp, now);
  const status = textOr(input.status, "observed");
  const type = textOr(input.type ?? input.kind, "event");
  const level = traceEventLevel(input.level ?? status ?? type);
  const message = textOr(input.message ?? input.label ?? type, "");
  const agentSessionId = textOr(input.agentSessionId ?? input.sessionId ?? requestMeta.agentSessionId ?? requestMeta.sessionId, "");
  const workerSessionId = textOr(input.workerSessionId ?? input.workerSession?.id ?? input.workerId, "");
  const id = textOr(input.id ?? input.eventId, "") || `tev_${sha256Hex({
    traceId,
    seq,
    source: input.source ?? null,
    sourceSeq: input.sourceSeq ?? null,
    type,
    status,
    label: input.label ?? null,
    message,
    occurredAt
  }).slice(0, 32)}`;
  const event = pruneUndefined({
    ...input,
    traceId,
    seq: seq ?? undefined,
    agentSessionId: agentSessionId || undefined,
    workerSessionId: workerSessionId || undefined,
    level,
    createdAt: timestampOr(input.createdAt ?? occurredAt, occurredAt),
    valuesPrinted: false
  });
  return {
    id,
    traceId,
    agentSessionId: agentSessionId || null,
    workerSessionId: workerSessionId || null,
    level,
    message,
    occurredAt,
    event
  };
}

export function normalizeWorkbenchProjectionState(value, requestMeta = {}, now) {
  const input = normalizeJsonObject(value);
  const traceId = textOr(input.traceId ?? requestMeta.traceId, "");
  const runId = textOr(input.runId ?? input.sourceRunId, "");
  const commandId = textOr(input.commandId ?? input.sourceCommandId, "");
  if (!traceId || !runId || !commandId) {
    throw new HwlabProtocolError("workbench projection state requires traceId, runId, and commandId", {
      code: ERROR_CODES.invalidParams,
      data: { required: ["traceId", "runId", "commandId"] }
    });
  }
  const timestamp = timestampOr(input.updatedAt, now);
  const lastAgentRunSeq = nonNegativeInteger(input.lastAgentRunSeq ?? input.lastSourceSeq);
  const lastProjectedSeq = nonNegativeInteger(input.lastProjectedSeq ?? lastAgentRunSeq);
  const upstreamLatestSeq = nonNegativeIntegerOrNull(input.upstreamLatestSeq ?? input.sourceLatestSeq);
  return pruneUndefined({
    ...input,
    traceId,
    sessionId: textOr(input.sessionId ?? requestMeta.sessionId, "") || null,
    conversationId: textOr(input.conversationId, "") || null,
    threadId: textOr(input.threadId, "") || null,
    ownerUserId: textOr(input.ownerUserId, "") || null,
    ownerRole: textOr(input.ownerRole, "") || null,
    sourceRunId: runId,
    sourceCommandId: commandId,
    runId,
    commandId,
    lastSourceSeq: lastAgentRunSeq,
    lastAgentRunSeq,
    lastProjectedSeq,
    sourceLatestSeq: upstreamLatestSeq ?? lastAgentRunSeq,
    upstreamLatestSeq: upstreamLatestSeq ?? lastAgentRunSeq,
    projectionStatus: projectionStatusOr(input.projectionStatus, "projecting"),
    projectionHealth: projectionHealthOr(input.projectionHealth, "healthy"),
    resultSyncState: resultSyncStateOr(input.resultSyncState, "not_started"),
    lastProjectedAt: timestampOr(input.lastProjectedAt, timestamp),
    lastResultSyncAt: input.lastResultSyncAt ? timestampOr(input.lastResultSyncAt, timestamp) : null,
    lastErrorCode: textOr(input.lastErrorCode, "") || null,
    lastErrorMessage: textOr(input.lastErrorMessage, "") || null,
    failureCount: nonNegativeInteger(input.failureCount),
    nextRetryAt: input.nextRetryAt ? timestampOr(input.nextRetryAt, timestamp) : null,
    createdAt: timestampOr(input.createdAt, timestamp),
    updatedAt: timestamp,
    valuesPrinted: false
  });
}

export function normalizeWorkbenchProjectionAllocation(value, requestMeta = {}, now) {
  const input = normalizeJsonObject(value);
  const traceId = textOr(input.traceId ?? requestMeta.traceId, "");
  const sourceEventId = textOr(input.sourceEventId ?? input.eventId, "");
  if (!traceId || !sourceEventId) {
    throw new HwlabProtocolError("workbench projectedSeq allocation requires traceId and sourceEventId", {
      code: ERROR_CODES.invalidParams,
      data: { required: ["traceId", "sourceEventId"] }
    });
  }
  const timestamp = timestampOr(input.updatedAt ?? input.occurredAt ?? input.createdAt, now);
  return pruneUndefined({
    ...input,
    traceId,
    sessionId: textOr(input.sessionId ?? requestMeta.sessionId, "") || null,
    turnId: textOr(input.turnId ?? requestMeta.turnId ?? traceId, "") || null,
    runId: textOr(input.runId ?? input.sourceRunId, "") || null,
    commandId: textOr(input.commandId ?? input.sourceCommandId, "") || null,
    sourceSeq: nonNegativeInteger(input.sourceSeq ?? input.lastSourceSeq ?? input.lastAgentRunSeq),
    sourceEventId,
    eventType: textOr(input.eventType ?? input.type, "event"),
    createdAt: timestampOr(input.createdAt, timestamp),
    updatedAt: timestamp,
    valuesPrinted: false
  });
}

export function normalizeWorkbenchFacts(value, requestMeta = {}, now) {
  const input = normalizeJsonObject(value);
  return {
    inputs: arrayInput(input.inputs ?? input.input).map((item) => normalizeWorkbenchSessionInputFact(item, requestMeta, now)),
    sessions: arrayInput(input.sessions ?? input.session).map((item) => normalizeWorkbenchSessionFact(item, requestMeta, now)),
    messages: arrayInput(input.messages ?? input.message).map((item) => normalizeWorkbenchMessageFact(item, requestMeta, now)),
    parts: arrayInput(input.parts ?? input.part).map((item) => normalizeWorkbenchPartFact(item, requestMeta, now)),
    turns: arrayInput(input.turns ?? input.turn).map((item) => normalizeWorkbenchTurnFact(item, requestMeta, now)),
    traceEvents: arrayInput(input.traceEvents ?? input.traceEvent).map((item) => normalizeWorkbenchTraceEventFact(item, requestMeta, now)),
    checkpoints: arrayInput(input.checkpoints ?? input.checkpoint).map((item) => normalizeWorkbenchProjectionCheckpoint(item, requestMeta, now))
  };
}

export function normalizeWorkbenchAggregateEventsForFacts(facts = {}, requestMeta = {}, now) {
  const events = [];
  for (const fact of arrayInput(facts.inputs)) appendWorkbenchFactEvent(events, "inputs", fact, requestMeta, now);
  for (const fact of arrayInput(facts.sessions)) appendWorkbenchFactEvent(events, "sessions", fact, requestMeta, now);
  for (const fact of arrayInput(facts.messages)) appendWorkbenchFactEvent(events, "messages", fact, requestMeta, now);
  for (const fact of arrayInput(facts.parts)) appendWorkbenchFactEvent(events, "parts", fact, requestMeta, now);
  for (const fact of arrayInput(facts.traceEvents)) appendWorkbenchFactEvent(events, "traceEvents", fact, requestMeta, now);
  for (const fact of arrayInput(facts.checkpoints)) appendWorkbenchFactEvent(events, "checkpoints", fact, requestMeta, now);
  for (const fact of arrayInput(facts.turns)) appendWorkbenchFactEvent(events, "turns", fact, requestMeta, now);
  return events;
}

export function appendWorkbenchFactEvent(events, factFamily, fact, requestMeta, now) {
  const aggregate = workbenchAggregateForFact(fact, requestMeta);
  const factId = textOr(fact.id ?? fact.inputId ?? fact.sessionId ?? fact.messageId ?? fact.partId ?? fact.turnId ?? fact.traceId, "");
  const rawSourceEventId = textOr(fact.sourceEventId ?? fact.eventId, "") || factId;
  const sourceEventId = rawSourceEventId ? `${factFamily}:${rawSourceEventId}` : null;
  const eventType = workbenchAggregateEventType(factFamily, fact);
  const projectedSeq = nonNegativeInteger(fact.projectedSeq);
  const sourceSeq = nonNegativeInteger(fact.sourceSeq);
  const occurredAt = timestampOr(fact.occurredAt ?? fact.updatedAt ?? fact.createdAt, now);
  events.push(normalizeWorkbenchAggregateEvent({
    ...aggregate,
    factFamily,
    factId,
    factKey: `${factFamily.slice(0, -1) || factFamily}:${factId}`,
    eventId: stableWorkbenchFactId("wbe", { aggregateId: aggregate.aggregateId, factFamily, sourceEventId, eventType, factId }),
    messageId: textOr(fact.messageId, "") || null,
    sourceRunId: textOr(fact.sourceRunId ?? fact.runId, "") || null,
    sourceCommandId: textOr(fact.sourceCommandId ?? fact.commandId, "") || null,
    sourceSeq,
    sourceEventId,
    eventType,
    projectionRevision: projectedSeq || sourceSeq,
    terminal: Boolean(fact.terminal),
    sealed: Boolean(fact.sealed),
    payload: {
      factFamily,
      factId,
      status: textOr(fact.status ?? fact.projectionStatus, "") || null,
      eventType,
      projectedSeq,
      sourceSeq,
      originalSourceEventId: rawSourceEventId || null,
      valuesRedacted: true
    },
    occurredAt,
    committedAt: timestampOr(fact.updatedAt ?? occurredAt, now)
  }, requestMeta, now));
}

export function workbenchAggregateForFact(fact = {}, requestMeta = {}) {
  const sessionId = textOr(fact.sessionId ?? requestMeta.sessionId, "") || null;
  const turnId = textOr(fact.turnId ?? requestMeta.turnId, "") || null;
  const traceId = textOr(fact.traceId ?? requestMeta.traceId, "") || null;
  if (sessionId) return { aggregateId: `session:${sessionId}`, aggregateType: "session", sessionId, turnId, traceId };
  if (turnId) return { aggregateId: `turn:${turnId}`, aggregateType: "turn", sessionId, turnId, traceId };
  if (traceId) return { aggregateId: `trace:${traceId}`, aggregateType: "trace", sessionId, turnId, traceId };
  throw requiredWorkbenchFactError("workbench aggregate event", ["sessionId", "turnId", "traceId"]);
}

export function normalizeWorkbenchAggregateEvent(value, requestMeta = {}, now) {
  const input = normalizeJsonObject(value);
  const aggregateId = textOr(input.aggregateId, "");
  if (!aggregateId) throw requiredWorkbenchFactError("workbench aggregate event", ["aggregateId"]);
  const timestamp = timestampOr(input.committedAt ?? input.occurredAt ?? input.updatedAt ?? input.createdAt, now);
  const sourceSeq = nonNegativeInteger(input.sourceSeq);
  const projectionRevision = nonNegativeInteger(input.projectionRevision ?? input.projectedSeq ?? sourceSeq);
  return pruneUndefined({
    ...input,
    eventSeq: nonNegativeInteger(input.eventSeq),
    eventId: textOr(input.eventId ?? input.id, "") || stableWorkbenchFactId("wbe", { aggregateId, eventType: input.eventType, sourceEventId: input.sourceEventId, sourceSeq, projectionRevision }),
    aggregateId,
    aggregateType: textOr(input.aggregateType, "trace"),
    aggregateSeq: nonNegativeInteger(input.aggregateSeq),
    sessionId: textOr(input.sessionId ?? requestMeta.sessionId, "") || null,
    turnId: textOr(input.turnId ?? requestMeta.turnId, "") || null,
    traceId: textOr(input.traceId ?? requestMeta.traceId, "") || null,
    messageId: textOr(input.messageId ?? requestMeta.messageId, "") || null,
    sourceRunId: textOr(input.sourceRunId ?? input.runId, "") || null,
    sourceCommandId: textOr(input.sourceCommandId ?? input.commandId, "") || null,
    sourceSeq,
    sourceEventId: textOr(input.sourceEventId, "") || null,
    eventType: textOr(input.eventType ?? input.type, "event"),
    projectionRevision,
    terminal: Boolean(input.terminal),
    sealed: Boolean(input.sealed),
    payload: normalizeJsonObject(input.payload),
    occurredAt: timestampOr(input.occurredAt, timestamp),
    committedAt: timestamp,
    valuesPrinted: false
  });
}

export function workbenchAggregateEventType(factFamily, fact = {}) {
  if (factFamily === "inputs") return `input_${textOr(fact.delivery, "queue")}_${textOr(fact.status, "admitted")}`;
  if (factFamily === "sessions") return "session_upsert";
  if (factFamily === "messages") return `${textOr(fact.role, "agent")}_message`;
  if (factFamily === "parts") return `part_${textOr(fact.partType ?? fact.type, "text")}`;
  if (factFamily === "turns") return fact.terminal || fact.sealed ? "turn_terminal" : "turn_update";
  if (factFamily === "traceEvents") return `trace_${textOr(fact.eventType ?? fact.type, "event")}`;
  if (factFamily === "checkpoints") return `checkpoint_${textOr(fact.projectionStatus, "projecting")}`;
  return "event";
}

export function workbenchInputDelivery(value) {
  const text = textOr(value, "queue").toLowerCase();
  return ["queue", "steer", "cancel"].includes(text) ? text : "queue";
}

export function workbenchInputStatus(value) {
  const text = textOr(value, "admitted").toLowerCase().replace(/-/gu, "_");
  return ["admitting", "admitted", "promoted", "blocked", "failed", "canceled", "completed"].includes(text) ? text : "admitted";
}

export function indexWorkbenchAggregateEvents(events = []) {
  const index = new Map();
  for (const event of events) {
    if (event?.factKey) index.set(event.factKey, event);
    if (event?.factFamily && event?.factId) index.set(`${event.factFamily}:${event.factId}`, event);
    if (event?.factFamily === "inputs" && event?.factId) index.set(`input:${event.factId}`, event);
    if (event?.factFamily === "turns" && event?.turnId) index.set(`turn:${event.turnId}`, event);
    if (event?.factFamily === "traceEvents" && event?.factId) index.set(`traceEvent:${event.factId}`, event);
    if (event?.sourceEventId) index.set(`sourceEvent:${event.sourceEventId}`, event);
  }
  return index;
}

export function normalizeWorkbenchSessionInputFact(value, requestMeta = {}, now) {
  const input = normalizeJsonObject(value);
  const sessionId = textOr(input.sessionId ?? requestMeta.sessionId, "");
  if (!sessionId) throw requiredWorkbenchFactError("workbench session input fact", ["sessionId"]);
  const timestamp = timestampOr(input.updatedAt ?? input.createdAt, now);
  const turnId = textOr(input.turnId ?? requestMeta.turnId ?? input.traceId ?? requestMeta.traceId, "") || null;
  const traceId = textOr(input.traceId ?? requestMeta.traceId, "") || null;
  const messageId = textOr(input.messageId ?? requestMeta.messageId, "") || null;
  const commandId = textOr(input.commandId ?? input.sourceCommandId, "") || null;
  const delivery = workbenchInputDelivery(input.delivery);
  const status = workbenchInputStatus(input.status);
  const sourceEventId = textOr(input.sourceEventId ?? input.eventId, "") || `${sessionId}:${turnId ?? "turn-unassigned"}:${delivery}:${traceId ?? commandId ?? messageId ?? "input"}`;
  const inputId = textOr(input.inputId ?? input.id, "") || stableWorkbenchFactId("wsi", { sessionId, turnId, traceId, messageId, commandId, delivery, sourceEventId });
  const admittedSeq = nonNegativeInteger(input.admittedSeq ?? input.aggregateSeq ?? input.sourceSeq);
  const promotedSeq = workbenchSessionInputPromotedSeq({ ...input, status }, admittedSeq);
  return pruneUndefined({
    ...input,
    id: inputId,
    inputId,
    sessionId,
    turnId,
    traceId,
    messageId,
    commandId,
    delivery,
    admittedSeq,
    promotedSeq,
    sourceSeq: admittedSeq,
    projectedSeq: admittedSeq,
    status,
    errorCode: textOr(input.errorCode ?? input.error?.code, "") || null,
    sourceEventId,
    createdAt: timestampOr(input.createdAt, timestamp),
    updatedAt: timestamp,
    valuesPrinted: false,
    valuesRedacted: true
  });
}

export function memoryWorkbenchSessionInputWithSeq(fact, records) {
  const existingFactSeq = nonNegativeInteger(fact.admittedSeq);
  if (existingFactSeq > 0) return workbenchSessionInputWithSeq(fact, existingFactSeq);
  const existing = records.get(fact.inputId) ?? null;
  const existingSeq = nonNegativeInteger(existing?.admittedSeq);
  if (existingSeq > 0) return workbenchSessionInputWithSeq(fact, existingSeq);
  const nextSeq = [...records.values()]
    .filter((record) => record.sessionId === fact.sessionId)
    .reduce((max, record) => Math.max(max, nonNegativeInteger(record.admittedSeq)), 0) + 1;
  return workbenchSessionInputWithSeq(fact, nextSeq);
}

export function inputFactWithAggregateSeq(fact, eventIndex) {
  const existingFactSeq = nonNegativeInteger(fact.admittedSeq);
  if (existingFactSeq > 0) return workbenchSessionInputWithSeq(fact, existingFactSeq);
  const event = eventIndex.get(`input:${fact.inputId}`) ?? eventIndex.get(`sourceEvent:${fact.sourceEventId}`) ?? null;
  const admittedSeq = nonNegativeInteger(event?.aggregateSeq);
  return admittedSeq > 0 ? workbenchSessionInputWithSeq(fact, admittedSeq) : fact;
}

export function workbenchSessionInputWithSeq(fact, admittedSeq) {
  return {
    ...fact,
    admittedSeq,
    promotedSeq: workbenchSessionInputPromotedSeq(fact, admittedSeq),
    sourceSeq: admittedSeq,
    projectedSeq: admittedSeq
  };
}

export function workbenchSessionInputPromotedSeq(fact, admittedSeq) {
  const existing = nonNegativeIntegerOrNull(fact.promotedSeq);
  if (existing !== null && existing > 0) return existing;
  const seq = nonNegativeInteger(admittedSeq);
  return textOr(fact.status, "") === "promoted" && seq > 0 ? seq : existing;
}

export function normalizeWorkbenchSessionFact(value, requestMeta = {}, now) {
  const input = normalizeJsonObject(value);
  const sessionId = textOr(input.sessionId ?? input.id ?? requestMeta.sessionId, "");
  if (!sessionId) throw requiredWorkbenchFactError("workbench session fact", ["sessionId"]);
  const sourceSeq = nonNegativeInteger(input.sourceSeq);
  const projectedSeq = nonNegativeInteger(input.projectedSeq ?? sourceSeq);
  const timestamp = timestampOr(input.updatedAt ?? input.createdAt, now);
  return pruneUndefined({
    ...input,
    id: sessionId,
    sessionId,
    ownerUserId: textOr(input.ownerUserId ?? requestMeta.ownerUserId, "") || null,
    projectId: textOr(input.projectId ?? requestMeta.projectId, "") || null,
    conversationId: textOr(input.conversationId ?? requestMeta.conversationId, "") || null,
    threadId: textOr(input.threadId ?? requestMeta.threadId, "") || null,
    status: textOr(input.status, "unknown"),
    lastTraceId: textOr(input.lastTraceId ?? input.traceId ?? requestMeta.traceId, "") || null,
    projectedSeq,
    sourceSeq,
    sourceEventId: textOr(input.sourceEventId ?? input.eventId, "") || null,
    terminal: Boolean(input.terminal),
    sealed: Boolean(input.sealed),
    createdAt: timestampOr(input.createdAt, timestamp),
    updatedAt: timestamp,
    valuesPrinted: false
  });
}

export function normalizeWorkbenchMessageFact(value, requestMeta = {}, now) {
  const input = normalizeJsonObject(value);
  const sessionId = textOr(input.sessionId ?? requestMeta.sessionId, "");
  if (!sessionId) throw requiredWorkbenchFactError("workbench message fact", ["sessionId"]);
  const traceId = textOr(input.traceId ?? requestMeta.traceId, "") || null;
  const turnId = textOr(input.turnId ?? requestMeta.turnId ?? traceId, "") || null;
  const role = textOr(input.role, "agent");
  const sourceSeq = nonNegativeInteger(input.sourceSeq);
  const projectedSeq = nonNegativeInteger(input.projectedSeq ?? sourceSeq);
  const timestamp = timestampOr(input.updatedAt ?? input.createdAt, now);
  const messageId = textOr(input.messageId ?? input.id, "") || stableWorkbenchFactId("msg", { sessionId, turnId, traceId, role, sourceSeq, projectedSeq });
  return pruneUndefined({
    ...input,
    id: messageId,
    messageId,
    sessionId,
    turnId,
    traceId,
    role,
    status: textOr(input.status, "unknown"),
    projectedSeq,
    sourceSeq,
    sourceEventId: textOr(input.sourceEventId ?? input.eventId, "") || null,
    terminal: Boolean(input.terminal),
    sealed: Boolean(input.sealed),
    createdAt: timestampOr(input.createdAt, timestamp),
    updatedAt: timestamp,
    valuesPrinted: false
  });
}

export function normalizeWorkbenchPartFact(value, requestMeta = {}, now) {
  const input = normalizeJsonObject(value);
  const sessionId = textOr(input.sessionId ?? requestMeta.sessionId, "");
  const messageId = textOr(input.messageId ?? requestMeta.messageId, "");
  if (!sessionId || !messageId) throw requiredWorkbenchFactError("workbench part fact", ["sessionId", "messageId"]);
  const traceId = textOr(input.traceId ?? requestMeta.traceId, "") || null;
  const turnId = textOr(input.turnId ?? requestMeta.turnId ?? traceId, "") || null;
  const partIndex = nonNegativeInteger(input.partIndex ?? input.index);
  const sourceSeq = nonNegativeInteger(input.sourceSeq);
  const projectedSeq = nonNegativeInteger(input.projectedSeq ?? sourceSeq);
  const timestamp = timestampOr(input.updatedAt ?? input.createdAt, now);
  const partType = textOr(input.partType ?? input.type, "text");
  const partId = textOr(input.partId ?? input.id, "") || stableWorkbenchFactId("wpt", { sessionId, messageId, turnId, traceId, partIndex, partType });
  return pruneUndefined({
    ...input,
    id: partId,
    partId,
    messageId,
    sessionId,
    turnId,
    traceId,
    partIndex,
    partType,
    status: textOr(input.status, "unknown"),
    projectedSeq,
    sourceSeq,
    sourceEventId: textOr(input.sourceEventId ?? input.eventId, "") || null,
    terminal: Boolean(input.terminal),
    sealed: Boolean(input.sealed),
    createdAt: timestampOr(input.createdAt, timestamp),
    updatedAt: timestamp,
    valuesPrinted: false
  });
}

export function normalizeWorkbenchTurnFact(value, requestMeta = {}, now) {
  const input = normalizeJsonObject(value);
  const sessionId = textOr(input.sessionId ?? requestMeta.sessionId, "");
  const traceId = textOr(input.traceId ?? requestMeta.traceId, "") || null;
  const turnId = textOr(input.turnId ?? input.id ?? requestMeta.turnId ?? traceId, "");
  if (!sessionId || !turnId) throw requiredWorkbenchFactError("workbench turn fact", ["sessionId", "turnId"]);
  const sourceSeq = nonNegativeInteger(input.sourceSeq);
  const projectedSeq = nonNegativeInteger(input.projectedSeq ?? sourceSeq);
  const timestamp = timestampOr(input.updatedAt ?? input.createdAt, now);
  const status = textOr(input.status, "unknown");
  const terminal = Boolean(input.terminal);
  const sealed = Boolean(input.sealed);
  const finalResponse = input.finalResponse ?? null;
  assertWorkbenchTurnFinalResponseInvariant({ status, terminal, sealed, finalResponse });
  return pruneUndefined({
    ...input,
    id: turnId,
    turnId,
    sessionId,
    traceId,
    messageId: textOr(input.messageId ?? requestMeta.messageId, "") || null,
    status,
    projectedSeq,
    sourceSeq,
    sourceEventId: textOr(input.sourceEventId ?? input.eventId, "") || null,
    terminal,
    sealed,
    finalResponse,
    diagnostic: normalizeJsonObject(input.diagnostic ?? input.projection ?? input.blocker),
    createdAt: timestampOr(input.createdAt, timestamp),
    updatedAt: timestamp,
    valuesPrinted: false
  });
}

export function assertWorkbenchTurnFinalResponseInvariant({ status, terminal, sealed, finalResponse } = {}) {
  if (normalizeWorkbenchFactStatus(status) !== "completed") return;
  if (!terminal && !sealed) return;
  if (workbenchFactFinalResponseText(finalResponse)) return;
  const error = new Error("completed Workbench turn facts must include an authoritative final response before sealing");
  error.code = "workbench_terminal_final_response_missing";
  error.layer = "workbench-read-model";
  error.category = "projection-invariant";
  throw error;
}

export function normalizeWorkbenchFactStatus(value) {
  return textOr(value, "").toLowerCase().replace(/_/gu, "-");
}

export function workbenchFactFinalResponseText(value) {
  if (value && typeof value === "object" && !Array.isArray(value)) {
    return workbenchFactFinalResponseText(value.text ?? value.content ?? value.message ?? value.summary ?? value.preview);
  }
  const text = textOr(value, "");
  return text && text !== "[object Object]" ? text : null;
}

export function normalizeWorkbenchTraceEventFact(value, requestMeta = {}, now) {
  const input = normalizeJsonObject(value);
  const traceId = textOr(input.traceId ?? requestMeta.traceId, "");
  if (!traceId) throw requiredWorkbenchFactError("workbench trace event fact", ["traceId"]);
  const sessionId = textOr(input.sessionId ?? requestMeta.sessionId, "") || null;
  const turnId = textOr(input.turnId ?? requestMeta.turnId ?? traceId, "") || null;
  const sourceSeq = nonNegativeInteger(input.sourceSeq);
  const projectedSeq = nonNegativeInteger(input.projectedSeq ?? input.seq);
  const occurredAt = timestampOr(input.occurredAt ?? input.createdAt ?? input.timestamp, now);
  const eventType = textOr(input.eventType ?? input.type ?? input.kind, "event");
  const id = textOr(input.id ?? input.eventId, "") || stableWorkbenchFactId("wte", { traceId, sourceSeq, projectedSeq, eventType, sourceEventId: input.sourceEventId ?? null, occurredAt });
  return pruneUndefined({
    ...input,
    id,
    traceId,
    sessionId,
    turnId,
    messageId: textOr(input.messageId ?? requestMeta.messageId, "") || null,
    sourceSeq,
    sourceEventId: textOr(input.sourceEventId ?? input.eventId, "") || null,
    projectedSeq,
    eventType,
    terminal: Boolean(input.terminal),
    sealed: Boolean(input.sealed),
    occurredAt,
    updatedAt: timestampOr(input.updatedAt, occurredAt),
    valuesPrinted: false
  });
}

export function normalizeWorkbenchProjectionCheckpoint(value, requestMeta = {}, now) {
  const input = normalizeJsonObject(value);
  const traceId = textOr(input.traceId ?? requestMeta.traceId, "");
  if (!traceId) throw requiredWorkbenchFactError("workbench projection checkpoint", ["traceId"]);
  const sourceSeq = nonNegativeInteger(input.sourceSeq ?? input.lastSourceSeq ?? input.lastAgentRunSeq);
  const projectedSeq = nonNegativeInteger(input.projectedSeq ?? input.lastProjectedSeq ?? sourceSeq);
  const timestamp = timestampOr(input.updatedAt ?? input.lastProjectedAt, now);
  return pruneUndefined({
    ...input,
    id: traceId,
    traceId,
    sessionId: textOr(input.sessionId ?? requestMeta.sessionId, "") || null,
    turnId: textOr(input.turnId ?? requestMeta.turnId ?? traceId, "") || null,
    runId: textOr(input.runId ?? input.sourceRunId, "") || null,
    commandId: textOr(input.commandId ?? input.sourceCommandId, "") || null,
    projectedSeq,
    sourceSeq,
    sourceEventId: textOr(input.sourceEventId ?? input.eventId, "") || null,
    projectionStatus: projectionStatusOr(input.projectionStatus, "projecting"),
    projectionHealth: projectionHealthOr(input.projectionHealth, "healthy"),
    terminal: Boolean(input.terminal),
    sealed: Boolean(input.sealed),
    diagnostic: normalizeJsonObject(input.diagnostic ?? input.blocker),
    createdAt: timestampOr(input.createdAt, timestamp),
    updatedAt: timestamp,
    valuesPrinted: false
  });
}

export function arrayInput(value) {
  if (Array.isArray(value)) return value;
  if (value && typeof value === "object") return [value];
  return [];
}

export function stableWorkbenchFactId(prefix, value) {
  return `${prefix}_${sha256Hex(value).slice(0, 32)}`;
}

export function requiredWorkbenchFactError(label, fields) {
  return new HwlabProtocolError(`${label} requires ${fields.join(", ")}`, {
    code: ERROR_CODES.invalidParams,
    data: { required: fields }
  });
}

export function compareTraceEventRecords(left, right) {
  const leftSeq = positiveIntegerOrNull(left?.event?.seq);
  const rightSeq = positiveIntegerOrNull(right?.event?.seq);
  if (leftSeq && rightSeq && leftSeq !== rightSeq) return leftSeq - rightSeq;
  return String(left?.occurredAt ?? "").localeCompare(String(right?.occurredAt ?? "")) ||
    String(left?.id ?? "").localeCompare(String(right?.id ?? ""));
}

export function compareProjectionStateRecords(left, right) {
  return String(left?.updatedAt ?? "").localeCompare(String(right?.updatedAt ?? "")) ||
    String(left?.traceId ?? "").localeCompare(String(right?.traceId ?? ""));
}

export function compareWorkbenchFactRecords(left, right) {
  return String(left?.updatedAt ?? left?.createdAt ?? "").localeCompare(String(right?.updatedAt ?? right?.createdAt ?? "")) ||
    String(left?.id ?? left?.sessionId ?? left?.messageId ?? left?.turnId ?? left?.traceId ?? "").localeCompare(String(right?.id ?? right?.sessionId ?? right?.messageId ?? right?.turnId ?? right?.traceId ?? ""));
}

export function compareWorkbenchInputFactRecords(left, right) {
  return nonNegativeInteger(left?.admittedSeq) - nonNegativeInteger(right?.admittedSeq) ||
    String(left?.inputId ?? left?.id ?? "").localeCompare(String(right?.inputId ?? right?.id ?? ""));
}

export function compareWorkbenchPartFactRecords(left, right) {
  return String(left?.messageId ?? "").localeCompare(String(right?.messageId ?? "")) ||
    nonNegativeInteger(left?.partIndex) - nonNegativeInteger(right?.partIndex) ||
    compareWorkbenchFactRecords(left, right);
}

export function compareWorkbenchTraceEventFacts(left, right) {
  return nonNegativeInteger(left?.projectedSeq) - nonNegativeInteger(right?.projectedSeq);
}

export function sortWorkbenchFactRows(records, params = {}, family, fallbackCompare) {
  const sorted = [...records];
  if (workbenchFactOrder(params, family) === "updated_desc") {
    return sorted.sort((left, right) => String(right?.updatedAt ?? right?.createdAt ?? "").localeCompare(String(left?.updatedAt ?? left?.createdAt ?? "")) || fallbackCompare(left, right));
  }
  if (family === "inputs") return sorted.sort(compareWorkbenchInputFactRecords);
  return sorted.sort(fallbackCompare);
}

export const WORKBENCH_FACT_FAMILIES = Object.freeze(["inputs", "sessions", "messages", "parts", "turns", "traceEvents", "checkpoints"]);

export function workbenchFactFamilySet(params = {}) {
  const raw = params.families ?? params.factFamilies;
  if (raw === undefined || raw === null || raw === "") return new Set(WORKBENCH_FACT_FAMILIES);
  const values = Array.isArray(raw) ? raw : String(raw).split(",");
  const selected = values.map((value) => String(value ?? "").trim()).filter((value) => WORKBENCH_FACT_FAMILIES.includes(value));
  return new Set(selected.length > 0 ? selected : WORKBENCH_FACT_FAMILIES);
}

export function workbenchFactFamilyForTable(table) {
  if (table === "workbench_session_inputs") return "inputs";
  if (table === "workbench_sessions") return "sessions";
  if (table === "workbench_messages") return "messages";
  if (table === "workbench_parts") return "parts";
  if (table === "workbench_turns") return "turns";
  if (table === "workbench_trace_events") return "traceEvents";
  if (table === "workbench_projection_checkpoints") return "checkpoints";
  return "unknown";
}

export function workbenchSessionSummarySelectClause() {
  return [
    "session_id",
    "owner_user_id",
    "project_id",
    "conversation_id",
    "thread_id",
    "status",
    "last_trace_id",
    "projected_seq",
    "source_seq",
    "source_event_id",
    "terminal",
    "sealed",
    "created_at",
    "updated_at",
    "COALESCE(NULLIF(session_json::jsonb ->> 'providerProfile', ''), NULLIF(session_json::jsonb #>> '{sessionJson,providerProfile}', '')) AS provider_profile"
  ].join(", ");
}

export function workbenchSessionSummaryFactFromRow(row = {}) {
  const sessionId = textOr(row.session_id, "");
  if (!sessionId) return null;
  const providerProfile = textOr(row.provider_profile, "");
  return {
    id: sessionId,
    sessionId,
    ownerUserId: textOr(row.owner_user_id, null),
    projectId: textOr(row.project_id, null),
    conversationId: textOr(row.conversation_id, null),
    threadId: textOr(row.thread_id, null),
    status: textOr(row.status, "unknown"),
    lastTraceId: textOr(row.last_trace_id, null),
    projectedSeq: nonNegativeInteger(row.projected_seq),
    sourceSeq: nonNegativeInteger(row.source_seq),
    sourceEventId: textOr(row.source_event_id, null),
    terminal: row.terminal === true || row.terminal === "t",
    sealed: row.sealed === true || row.sealed === "t",
    ...(providerProfile ? {
      providerProfile,
      sessionJson: {
        providerProfile,
        valuesRedacted: true,
        secretMaterialStored: false
      }
    } : {}),
    createdAt: textOr(row.created_at, null),
    updatedAt: textOr(row.updated_at, row.created_at ?? null),
    valuesPrinted: false,
    valuesRedacted: true
  };
}

export function workbenchFactOrder(params = {}, family = "") {
  const value = params[`${family}Order`] ?? params.order;
  return value === "updated_desc" ? "updated_desc" : "updated_asc";
}

export function traceEventLevel(value) {
  const text = textOr(value, "info").toLowerCase();
  if (["failed", "failure", "error", "timeout"].includes(text)) return "error";
  if (["warn", "warning", "blocked", "canceled", "cancelled"].includes(text)) return "warn";
  if (["debug", "trace"].includes(text)) return "debug";
  return "info";
}

export function positiveIntegerOrNull(value) {
  const parsed = Number.parseInt(value ?? "", 10);
  return Number.isInteger(parsed) && parsed > 0 ? parsed : null;
}

export function nonNegativeInteger(value) {
  const parsed = Number.parseInt(value ?? "", 10);
  return Number.isInteger(parsed) && parsed >= 0 ? parsed : 0;
}

export function nonNegativeIntegerOrNull(value) {
  const parsed = Number.parseInt(value ?? "", 10);
  return Number.isInteger(parsed) && parsed >= 0 ? parsed : null;
}

export function projectionStatusOr(value, fallback) {
  const text = textOr(value, fallback).toLowerCase();
  return ["projecting", "caught_up", "terminal", "degraded", "blocked", "stalled"].includes(text) ? text : fallback;
}

export function projectionHealthOr(value, fallback) {
  const text = textOr(value, fallback).toLowerCase();
  return ["healthy", "degraded", "unavailable", "stalled"].includes(text) ? text : fallback;
}

export function resultSyncStateOr(value, fallback) {
  const text = textOr(value, fallback).toLowerCase();
  return ["not_started", "pending", "synced", "failed", "timed_out"].includes(text) ? text : fallback;
}

export function timestampOr(value, fallback) {
  const text = textOr(value, "");
  if (text) {
    const ms = Date.parse(text);
    if (Number.isFinite(ms)) return new Date(ms).toISOString();
  }
  return textOr(fallback, "") || new Date().toISOString();
}

export function textOr(value, fallback) {
  const text = String(value ?? "").trim();
  return text || fallback;
}

export function textList(value) {
  const raw = Array.isArray(value) ? value : [];
  return [...new Set(raw.map((item) => textOr(item, "")).filter(Boolean))];
}

export function asObject(value, label) {
  if (!value || typeof value !== "object" || Array.isArray(value)) {
    throw new HwlabProtocolError(`${label} must be a JSON object`, {
      code: ERROR_CODES.invalidParams
    });
  }
  return value;
}

export function requireString(input, field) {
  if (typeof input[field] !== "string" || input[field].trim() === "") {
    throw new HwlabProtocolError(`${field} is required`, {
      code: ERROR_CODES.invalidParams,
      data: { field }
    });
  }
  return input[field];
}

export function requireProtocolId(input, field) {
  const value = requireString(input, field);
  return value;
}

export function normalizeJsonObject(value) {
  if (!value || typeof value !== "object" || Array.isArray(value)) {
    return {};
  }
  return { ...value };
}

export function pruneUndefined(input) {
  return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined));
}

export function makeId(prefix) {
  return `${prefix}_${randomUUID()}`;
}

export function stableJson(value) {
  return JSON.stringify(sortJson(value));
}

export function sha256Hex(value) {
  return createHash("sha256").update(stableJson(value)).digest("hex");
}

export function sortJson(value) {
  if (Array.isArray(value)) {
    return value.map(sortJson);
  }
  if (value && typeof value === "object") {
    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortJson(value[key])]));
  }
  return value;
}

export function matchesQuery(record, params, fields) {
  for (const field of fields) {
    if (params[field] !== undefined && params[field] !== null && record[field] !== params[field]) {
      return false;
    }
    const values = textList(params[`${field}s`]);
    if (values.length > 0 && !values.includes(textOr(record[field], ""))) {
      return false;
    }
  }
  return true;
}

export function matchesWorkbenchSessionFactQuery(record, params) {
  if (!matchesQuery(record, params, ["sessionId", "ownerUserId", "projectId", "conversationId", "threadId", "status"])) return false;
  const traceId = textOr(params.traceId ?? params.lastTraceId, "");
  if (traceId && record.lastTraceId !== traceId && record.traceId !== traceId) return false;
  return true;
}

export function limitResults(records, limit) {
  const parsed = Number.parseInt(limit ?? "", 10);
  if (!Number.isInteger(parsed) || parsed <= 0) {
    return records;
  }
  return records.slice(0, parsed);
}

export function normalizeRuntimeAdapter(value) {
  if (typeof value !== "string" || value.trim() === "") {
    return RUNTIME_STORE_KIND;
  }
  const normalized = value.trim().toLowerCase();
  if (["postgres", "postgresql", "pg", "db"].includes(normalized)) {
    return RUNTIME_STORE_KIND_POSTGRES;
  }
  return RUNTIME_STORE_KIND;
}

export function normalizePostgresSslMode(value) {
  const normalized = String(value ?? "").trim().toLowerCase();
  if (["disable", "false", "0", "off", "no"].includes(normalized)) {
    return "disable";
  }
  return "require";
}

export function postgresSslModeFromConnectionString(dbUrl) {
  if (typeof dbUrl !== "string" || dbUrl.trim() === "") return undefined;
  try {
    const url = new URL(dbUrl);
    if (!["postgres:", "postgresql:"].includes(url.protocol)) return undefined;
    return url.searchParams.get("sslmode") ?? url.searchParams.get("ssl") ?? undefined;
  } catch {
    return undefined;
  }
}

export function postgresSslOption(sslMode) {
  return sslMode === "disable" ? false : { rejectUnauthorized: false };
}

export function normalizePostgresConnectionStringForSslMode(dbUrl, sslMode) {
  if (typeof dbUrl !== "string" || dbUrl.trim() === "") {
    return dbUrl;
  }

  let url;
  try {
    url = new URL(dbUrl);
  } catch {
    return dbUrl;
  }

  if (!["postgres:", "postgresql:"].includes(url.protocol)) {
    return dbUrl;
  }

  for (const key of ["ssl", "sslmode", "sslcert", "sslkey", "sslrootcert"]) {
    url.searchParams.delete(key);
  }
  if (sslMode !== "disable") {
    url.searchParams.set("sslmode", "require");
    url.searchParams.set("uselibpqcompat", "true");
  }
  return url.toString();
}

export function postgresAdapterContract() {
  return {
    required: "Postgres-backed durable runtime adapter using HWLAB_CLOUD_DB_URL",
    adapterEnv: RUNTIME_ADAPTER_ENV,
    adapterEnvValue: RUNTIME_STORE_KIND_POSTGRES,
    sourceIssue: "pikasTech/HWLAB#164",
    secretMaterialRequiredInSource: false,
    fixtureEvidenceAllowed: false
  };
}

export function addRuntimeDurabilityContract(summary) {
  return {
    ...summary,
    durabilityContract: {
      ready: summary.durable === true && summary.ready === true && summary.liveRuntimeEvidence === true,
      status: summary.durable === true && summary.ready === true && summary.liveRuntimeEvidence === true ? "ready" : "blocked",
      requiredEvidence: RUNTIME_DURABILITY_REQUIRED_EVIDENCE,
      dbLiveEvidenceIsDurabilityEvidence: false,
      liveRuntimeEvidence: Boolean(summary.liveRuntimeEvidence),
      adapterQueryRequired: true,
      blockedLayer: summary.durable === true && summary.ready === true && summary.liveRuntimeEvidence === true
        ? null
        : durabilityBlockedLayer(summary),
      blocker: summary.blocker ?? null,
      secretMaterialRead: false
    }
  };
}

export function durabilityBlockedLayer(summary = {}) {
  const blocker = summary.blocker;
  if (
    blocker === RUNTIME_DURABLE_ADAPTER_MISSING ||
    blocker === RUNTIME_DURABLE_ADAPTER_UNCONFIGURED ||
    blocker === RUNTIME_DURABLE_ADAPTER_DRIVER_MISSING
  ) {
    return "adapter";
  }
  if (blocker === RUNTIME_DURABLE_ADAPTER_SSL_BLOCKED) {
    return "ssl";
  }
  if (blocker === RUNTIME_DURABLE_ADAPTER_AUTH_BLOCKED) {
    return "auth";
  }
  if (blocker === RUNTIME_DURABLE_ADAPTER_SCHEMA_BLOCKED) {
    return "schema";
  }
  if (blocker === RUNTIME_DURABLE_ADAPTER_MIGRATION_BLOCKED) {
    return "migration";
  }
  if (summary.connection?.queryAttempted || blocker === RUNTIME_DURABLE_ADAPTER_QUERY_BLOCKED) {
    return "durability_query";
  }
  return "adapter";
}

export function runtimeSafety() {
  return {
    devOnly: true,
    secretsRead: false,
    secretMaterialRead: false,
    valuesRedacted: true,
    endpointRedacted: true
  };
}

export function classifyRuntimeDbError(error) {
  const code = typeof error?.code === "string" ? error.code : "UNKNOWN";
  if (isRuntimeDbConnectTimeout(error)) {
    return {
      blocker: RUNTIME_DURABLE_ADAPTER_QUERY_BLOCKED,
      reason: "Postgres runtime adapter connection attempt timed out before completing the runtime query",
      retryable: true,
      transient: true,
      retryAfterMs: 5000,
      connection: {
        queryAttempted: true,
        queryResult: "connect_timeout",
        errorCode: code
      }
    };
  }
  if (code === "HWLAB_PG_DRIVER_MISSING") {
    return {
      blocker: RUNTIME_DURABLE_ADAPTER_DRIVER_MISSING,
      reason: "Postgres runtime adapter is selected, but the pg package is not installed in the runtime image",
      connection: {
        queryAttempted: false,
        queryResult: "driver_missing",
        errorCode: code
      }
    };
  }
  if (isRuntimeDbSslError(error)) {
    return {
      blocker: RUNTIME_DURABLE_ADAPTER_SSL_BLOCKED,
      reason: "Postgres runtime adapter reached the DB driver but SSL negotiation or SSL mode compatibility blocked the schema query",
      connection: {
        queryAttempted: true,
        queryResult: "ssl_negotiation_blocked",
        errorCode: code
      }
    };
  }
  if (["28P01", "28000", "42501"].includes(code)) {
    return {
      blocker: RUNTIME_DURABLE_ADAPTER_AUTH_BLOCKED,
      reason: "Postgres runtime adapter reached the DB driver but authentication or authorization blocked the schema query",
      connection: {
        queryAttempted: true,
        queryResult: "auth_blocked",
        errorCode: code
      }
    };
  }
  if (["42P01", "42703", "3F000"].includes(code)) {
    return {
      blocker: RUNTIME_DURABLE_ADAPTER_SCHEMA_BLOCKED,
      reason: "Postgres runtime adapter reached the database, but the runtime schema is missing or incompatible",
      connection: {
        queryAttempted: true,
        queryResult: "schema_blocked",
        errorCode: code
      }
    };
  }
  if (code === "53300") {
    return {
      blocker: RUNTIME_DURABLE_ADAPTER_QUERY_BLOCKED,
      reason: "Postgres runtime adapter reached the database, but the server has exhausted available connection slots",
      retryable: true,
      transient: true,
      retryAfterMs: 2000,
      connection: {
        queryAttempted: true,
        queryResult: "too_many_connections",
        errorCode: code
      }
    };
  }
  return {
    blocker: RUNTIME_DURABLE_ADAPTER_QUERY_BLOCKED,
    reason: "Postgres runtime adapter could not complete a live runtime schema query",
    connection: {
      queryAttempted: true,
      queryResult: "query_blocked",
      errorCode: code
    }
  };
}

export function isRuntimeDbConnectTimeout(error) {
  const message = String(error?.message ?? error ?? "").toLowerCase();
  const pgConnectTimeout = message.includes("timeout exceeded when trying to connect");
  const pgConnectionTimeoutTermination = message.includes("connection terminated due to connection timeout");
  if (!pgConnectTimeout && !pgConnectionTimeoutTermination) return false;
  if (pgConnectionTimeoutTermination) return true;
  const stack = String(error?.stack ?? "").toLowerCase();
  return !stack || stack.includes("pg-pool") || stack.includes("node_modules/pg");
}

export function durableRuntimeReadBlockedError(method, readiness = {}) {
  return new HwlabProtocolError("Postgres durable runtime adapter is blocked for runtime evidence queries", {
    code: ERROR_CODES.internalError,
    data: durableRuntimeReadBlockedData(method, readiness),
    context: {
      result: "failed"
    }
  });
}

export function durableRuntimeReadBlockedData(method, readiness = {}) {
  const durability = readiness.durabilityContract ?? {};
  const connection = readiness.connection ?? {};
  const blockedLayer = durability.blockedLayer ?? durabilityBlockedLayer(readiness);
  const queryResult = connection.queryResult ?? (blockedLayer === "durability_query" ? "query_blocked" : "not_ready");

  return pruneUndefined({
    method,
    adapter: readiness.adapter ?? RUNTIME_STORE_KIND_POSTGRES,
    status: "blocked",
    blocker: readiness.blocker ?? RUNTIME_DURABLE_ADAPTER_QUERY_BLOCKED,
    durable: false,
    durableRequested: true,
    liveRuntimeEvidence: false,
    queryResult,
    blockedLayer,
    requiredEvidence: durability.requiredEvidence ?? RUNTIME_DURABILITY_REQUIRED_EVIDENCE,
    dbLiveEvidenceIsDurabilityEvidence: false,
    retryable: readiness.retryable === true || connection.queryResult === "connect_timeout",
    transient: readiness.transient === true || connection.queryResult === "connect_timeout",
    retryAfterMs: Number.isFinite(Number(readiness.retryAfterMs)) ? Math.max(0, Math.trunc(Number(readiness.retryAfterMs))) : undefined,
    secretMaterialRead: false,
    valueRedacted: true,
    endpointRedacted: true,
    errorCode: connection.errorCode ?? undefined,
    redaction: {
      valueRedacted: true,
      valuesRedacted: true,
      endpointRedacted: true,
      secretMaterialRead: false
    }
  });
}

export function isRuntimeDbSslError(error) {
  const code = typeof error?.code === "string" ? error.code : "";
  if (code.startsWith("ERR_SSL") || code.startsWith("ERR_TLS")) {
    return true;
  }
  if ([
    "DEPTH_ZERO_SELF_SIGNED_CERT",
    "SELF_SIGNED_CERT_IN_CHAIN",
    "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
    "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
    "CERT_HAS_EXPIRED"
  ].includes(code)) {
    return true;
  }
  const message = typeof error?.message === "string" ? error.message.toLowerCase() : "";
  return [
    "does not support ssl",
    "ssl is not enabled",
    "ssl negotiation",
    "ssl off",
    "ssl required",
    "requires ssl",
    "no ssl encryption",
    "no encryption",
    "hostssl",
    "server requires ssl",
    "before secure tls connection",
    "tls handshake"
  ].some((pattern) => message.includes(pattern));
}

export function summarizeRuntimeSchema(rows, requiredSchema = requiredPostgresSchema) {
  const columnsByTable = new Map();
  for (const row of rows) {
    const table = row.table_name;
    const column = row.column_name;
    if (!table || !column) continue;
    if (!columnsByTable.has(table)) {
      columnsByTable.set(table, new Set());
    }
    columnsByTable.get(table).add(column);
  }

  const missingTables = [];
  const missingColumns = [];
  for (const [table, columns] of Object.entries(requiredSchema)) {
    const observed = columnsByTable.get(table);
    if (!observed) {
      missingTables.push(table);
      missingColumns.push(...columns.map((column) => `${table}.${column}`));
      continue;
    }
    for (const column of columns) {
      if (!observed.has(column)) {
        missingColumns.push(`${table}.${column}`);
      }
    }
  }

  return {
    ready: missingTables.length === 0 && missingColumns.length === 0,
    checked: true,
    requiredTables: Object.keys(requiredSchema),
    missingTables,
    missingColumns
  };
}

export function notCheckedRuntimeMigration() {
  return {
    checked: false,
    ready: false,
    table: CLOUD_RUNTIME_DURABLE_MIGRATION_TABLE,
    requiredMigrationId: CLOUD_CORE_MIGRATION_ID,
    requiredSchemaVersion: CLOUD_RUNTIME_DURABLE_ADAPTER_SCHEMA_VERSION,
    appliedMigrationId: null,
    appliedSchemaVersion: null,
    missing: true
  };
}

export function blockedRuntimeMigration({ errorCode = null } = {}) {
  return {
    ...notCheckedRuntimeMigration(),
    checked: true,
    errorCode
  };
}

export function runtimeGates({
  ssl = notCheckedGate(),
  auth = notCheckedGate(),
  schema = notCheckedGate(),
  migration = notCheckedGate(),
  durability = notCheckedGate()
} = {}) {
  return {
    ssl,
    auth,
    schema,
    migration,
    durability
  };
}

export function defaultRuntimeGates({ blocker, connection, schema, migration } = {}) {
  if (blocker === RUNTIME_DURABLE_ADAPTER_SSL_BLOCKED) {
    return {
      ssl: blockedGate({ checked: true, blocker }),
      auth: notCheckedGate()
    };
  }
  if (blocker === RUNTIME_DURABLE_ADAPTER_AUTH_BLOCKED) {
    return {
      ssl: readyGate(),
      auth: blockedGate({ checked: true, blocker })
    };
  }
  if (blocker === RUNTIME_DURABLE_ADAPTER_SCHEMA_BLOCKED) {
    return {
      ssl: connection?.queryAttempted ? readyGate() : notCheckedGate(),
      auth: connection?.queryAttempted ? readyGate() : notCheckedGate()
    };
  }
  if (blocker === RUNTIME_DURABLE_ADAPTER_QUERY_BLOCKED && schema?.checked && migration?.checked) {
    return {
      ssl: readyGate(),
      auth: readyGate()
    };
  }
  return {
    ssl: notCheckedGate(),
    auth: notCheckedGate()
  };
}

export function defaultSchemaGate({ blocker, schema } = {}) {
  if (schema?.checked) {
    return gateFromReadiness(schema.ready, { blocker: RUNTIME_DURABLE_ADAPTER_SCHEMA_BLOCKED });
  }
  if (blocker === RUNTIME_DURABLE_ADAPTER_SCHEMA_BLOCKED) {
    return blockedGate({ checked: true, blocker });
  }
  return notCheckedGate();
}

export function defaultMigrationGate({ blocker, migration } = {}) {
  if (migration?.checked) {
    return gateFromReadiness(migration.ready, { blocker: RUNTIME_DURABLE_ADAPTER_MIGRATION_BLOCKED });
  }
  if (blocker === RUNTIME_DURABLE_ADAPTER_MIGRATION_BLOCKED) {
    return blockedGate({ checked: true, blocker });
  }
  return notCheckedGate();
}

export function readyGate() {
  return {
    checked: true,
    ready: true,
    status: "ready",
    blocker: null
  };
}

export function blockedGate({ checked = true, blocker = "runtime_durable_adapter_blocked" } = {}) {
  return {
    checked,
    ready: false,
    status: checked ? "blocked" : "not_checked",
    blocker
  };
}

export function notCheckedGate() {
  return {
    checked: false,
    ready: false,
    status: "not_checked",
    blocker: null
  };
}

export function gateFromReadiness(ready, { blocker } = {}) {
  return ready ? readyGate() : blockedGate({ checked: true, blocker });
}

export function snapshotMemory(memory) {
  return {
    gatewaySessions: new Map(memory.gatewaySessions),
    boxResources: new Map(memory.boxResources),
    boxCapabilities: new Map(memory.boxCapabilities),
    hardwareOperations: new Map(memory.hardwareOperations),
    auditEvents: new Map(memory.auditEvents),
    evidenceRecords: new Map(memory.evidenceRecords),
    agentTraceEvents: new Map(memory.agentTraceEvents),
    workbenchProjectionStates: new Map(memory.workbenchProjectionStates),
    workbenchSessions: new Map(memory.workbenchSessions),
    workbenchMessages: new Map(memory.workbenchMessages),
    workbenchParts: new Map(memory.workbenchParts),
    workbenchTurns: new Map(memory.workbenchTurns),
    workbenchTraceEvents: new Map(memory.workbenchTraceEvents),
    workbenchProjectionCheckpoints: new Map(memory.workbenchProjectionCheckpoints)
  };
}

export function newRecords(current, before) {
  return [...current.entries()]
    .filter(([id]) => !before.has(id))
    .map(([, record]) => record);
}

export function changedRecords(current, before) {
  return [...current.entries()]
    .filter(([id, record]) => stableJson(before.get(id)) !== stableJson(record))
    .map(([, record]) => record);
}

export function withPersistence(result, persistence) {
  return {
    ...result,
    persistence
  };
}

export function parseJsonColumn(value, fallback) {
  if (!value) return fallback;
  if (typeof value === "object") return value;
  try {
    return JSON.parse(String(value));
  } catch {
    return fallback;
  }
}

export function postgresPoolStats(pool) {
  if (!pool || typeof pool !== "object") return null;
  return {
    totalCount: Number.isFinite(Number(pool.totalCount)) ? Number(pool.totalCount) : null,
    idleCount: Number.isFinite(Number(pool.idleCount)) ? Number(pool.idleCount) : null,
    waitingCount: Number.isFinite(Number(pool.waitingCount)) ? Number(pool.waitingCount) : null,
    valuesRedacted: true
  };
}

export function toCountKey(table) {
  if (table === "users") return "users";
  if (table === "user_sessions") return "userSessions";
  if (table === "gateway_sessions") return "gatewaySessions";
  if (table === "box_resources") return "boxResources";
  if (table === "box_capabilities") return "boxCapabilities";
  if (table === "hardware_operations") return "hardwareOperations";
  if (table === "audit_events") return "auditEvents";
  if (table === "evidence_records") return "evidenceRecords";
  if (table === "agent_sessions") return "agentSessions";
  if (table === "account_workspaces") return "accountWorkspaces";
  if (table === "worker_sessions") return "workerSessions";
  if (table === "agent_trace_events") return "agentTraceEvents";
  if (table === "workbench_projection_state") return "workbenchProjectionStates";
  if (table === "workbench_sessions") return "workbenchSessions";
  if (table === "workbench_messages") return "workbenchMessages";
  if (table === "workbench_parts") return "workbenchParts";
  if (table === "workbench_turns") return "workbenchTurns";
  if (table === "workbench_trace_events") return "workbenchTraceEvents";
  if (table === "workbench_projection_checkpoints") return "workbenchProjectionCheckpoints";
  return table;
}

export function normalizeRuntimeTimeoutMs(value) {
  const parsed = Number.parseInt(String(value ?? ""), 10);
  if (!Number.isInteger(parsed) || parsed <= 0) {
    return 1200;
  }
  return Math.min(parsed, 5000);
}

export function normalizeRuntimePoolMax(value) {
  if (value === undefined || value === null || String(value).trim() === "") return null;
  const parsed = Number.parseInt(String(value), 10);
  if (!Number.isInteger(parsed) || parsed <= 0 || String(parsed) !== String(value).trim()) {
    const error = new Error(`${RUNTIME_DB_POOL_MAX_ENV} must be a positive integer`);
    error.code = "HWLAB_CLOUD_DB_POOL_MAX_INVALID";
    throw error;
  }
  return parsed;
}
