@sixb/core 0.1.0 → 0.1.2

package/src/storage/agents/types.ts

@@ -1,5 +1,6 @@
 import type { AgentMessage, AgentMessagePart, AgentMessageRole } from "../../agents/message"
 import type { Principal } from "../../auth"
+import type { SixbErrorCode, SixbFailure } from "../../errors/types"
 import type { JsonValue } from "../../json"
 
 // ── agent_threads — one conversation with an agent ──────────────────────────────────────────────
@@ -58,6 +59,15 @@ export type AgentExecutionStatus = "queued" | "running" | "succeeded" | "failed"
 
 export type AgentRunStatus = AgentExecutionStatus
 
+/** Error codes an agent execution can persist and expose through its public contract. */
+export const AGENT_RUN_FAILURE_CODES = [
+  "internal.unexpected",
+  "runtime.cancelled",
+  "agent.execution_failed",
+] as const satisfies readonly [SixbErrorCode, ...SixbErrorCode[]]
+
+export type AgentRunFailureCode = (typeof AGENT_RUN_FAILURE_CODES)[number]
+
 /**
  * Why a run ended — our own SDK-independent vocabulary (it mirrors the AI SDK unified finish
  * reasons), so reads are typed and exhaustive without core depending on `ai`. `other`/`unknown` are
@@ -90,14 +100,6 @@ export function coerceAgentRunFinishReason(
     : "unknown"
 }
 
-export interface AgentRunUsage {
-  readonly inputTokens?: number
-  readonly outputTokens?: number
-  readonly totalTokens?: number
-  readonly reasoningTokens?: number
-  readonly cachedInputTokens?: number
-}
-
 /** Stable, user-facing diagnostics emitted by the platform while executing a run. */
 export const AGENT_RUN_DIAGNOSTIC_CODES = [
   "output_file_limit_exceeded",
@@ -143,20 +145,20 @@ export interface AgentRunExecution {
 export interface AgentRunRecord {
   readonly id: string
   readonly projectId: string
+  readonly executionId: string
   readonly threadId: string
   readonly agentId: string
   readonly triggerMessageId: string
-  readonly requestedByPrincipal: Principal
-  readonly executionPrincipal?: Extract<Principal, { readonly type: "serviceAccount" }>
+  /** Durable group memberships snapshotted when the run was admitted. */
+  readonly requesterGroupIds: readonly string[]
   readonly status: AgentRunStatus
   readonly modelId?: string
   /** Why the run ended (our own SDK-independent enum). */
   readonly finishReason?: AgentRunFinishReason
-  readonly usage?: AgentRunUsage
   /** Platform diagnostics are transcript annotations, never agent-authored message content. */
   readonly diagnostics?: readonly AgentRunDiagnostic[]
-  /** Failure message when the run did not succeed. */
-  readonly error?: string
+  /** Portable failure snapshot when the run did not succeed. */
+  readonly error?: SixbFailure<AgentRunFailureCode>
   /** Execution attempts: `0` while queued, `1` on first start, incremented on redelivery. */
   readonly attempt: number
   readonly execution?: AgentRunExecution
@@ -168,17 +170,17 @@ export interface AgentRunRecord {
 export interface CreateAgentRunInput {
   readonly id: string
   readonly projectId: string
+  readonly executionId: string
   readonly threadId: string
   readonly agentId: string
   readonly triggerMessageId: string
-  readonly requestedByPrincipal: Principal
+  readonly requesterGroupIds: readonly string[]
   readonly createdAt?: Date
 }
 
 export interface StartAgentRunInput {
   readonly id: string
   readonly projectId: string
-  readonly executionPrincipal?: Extract<Principal, { readonly type: "serviceAccount" }>
   readonly modelId?: string
   readonly execution: AgentRunExecution
   readonly startedAt?: Date
@@ -188,7 +190,7 @@ export interface FinishQueuedAgentRunInput {
   readonly id: string
   readonly projectId: string
   readonly status: "failed" | "cancelled"
-  readonly error?: string
+  readonly error?: SixbFailure<AgentRunFailureCode>
   readonly completedAt?: Date
 }
 
@@ -214,7 +216,6 @@ export type FinishAgentRunInput =
       readonly status: "succeeded"
       readonly modelId?: string
       readonly finishReason?: AgentRunFinishReason
-      readonly usage?: AgentRunUsage
       readonly diagnostics?: readonly AgentRunDiagnostic[]
       readonly completedAt?: Date
     }
@@ -225,9 +226,8 @@ export type FinishAgentRunInput =
       readonly status: "failed" | "cancelled"
       readonly modelId?: string
       readonly finishReason?: AgentRunFinishReason
-      readonly usage?: AgentRunUsage
       readonly diagnostics?: readonly AgentRunDiagnostic[]
-      readonly error?: string
+      readonly error?: SixbFailure<AgentRunFailureCode>
       readonly completedAt?: Date
     }
 

package/src/storage/ai-usage/errors.ts

@@ -0,0 +1,13 @@
+export type AiUsageStorageErrorCode = "duplicate_id" | "missing_execution"
+
+/** Storage failure specific to the AI model-call usage ledger. */
+export class AiUsageStorageError extends Error {
+  readonly name = "AiUsageStorageError"
+
+  constructor(
+    readonly code: AiUsageStorageErrorCode,
+    message: string
+  ) {
+    super(message)
+  }
+}

package/src/storage/ai-usage/in-memory.ts

@@ -0,0 +1,162 @@
+import type { ExecutionStorage } from "../executions"
+import { AiUsageStorageError } from "./errors"
+import { assertAiUsageExecutionId, normalizeAiModelCallRecord } from "./record"
+import type {
+  AiModelCallUsageRecord,
+  AiUsageExecutionSummary,
+  AiUsageStorage,
+  RecordAiModelCallInput,
+  RecordAiModelCallResult,
+  SummarizeAiUsageExecutionInput,
+  SummarizeAiUsageExecutionsInput,
+} from "./types"
+import { aggregateAiModelCallUsage } from "./usage"
+
+export interface InMemoryAiUsageGroupRow {
+  readonly projectId: string
+  readonly usageRecordId: string
+  readonly groupId: string
+  readonly occurredAt: Date
+}
+
+export interface InMemoryAiUsageStorageSnapshot {
+  readonly records: Map<string, AiModelCallUsageRecord>
+  readonly recordKeysByIdempotencyKey: Map<string, string>
+  readonly groupRows: Map<string, InMemoryAiUsageGroupRow>
+}
+
+/** In-memory model-call ledger used by development runtimes and storage contract tests. */
+export class InMemoryAiUsageStorage implements AiUsageStorage {
+  private readonly records = new Map<string, AiModelCallUsageRecord>()
+  private readonly recordKeysByIdempotencyKey = new Map<string, string>()
+  private readonly groupRows = new Map<string, InMemoryAiUsageGroupRow>()
+
+  constructor(private readonly executions: Pick<ExecutionStorage, "getById">) {}
+
+  async recordModelCall(input: RecordAiModelCallInput): Promise<RecordAiModelCallResult> {
+    const record = normalizeAiModelCallRecord(input)
+    await this.assertExecutionExists(record.projectId, record.executionId)
+    const idempotencyKey = modelCallIdempotencyKey(record)
+    const existingRecordKey = this.recordKeysByIdempotencyKey.get(idempotencyKey)
+    if (existingRecordKey !== undefined) {
+      const existing = this.records.get(existingRecordKey)
+      if (!existing) {
+        throw new Error("[Sixb] In-memory AI usage idempotency index is inconsistent.")
+      }
+      return { record: structuredClone(existing), created: false }
+    }
+
+    const recordKey = modelCallRecordKey(record.projectId, record.id)
+    if (this.records.has(recordKey)) {
+      throw new AiUsageStorageError(
+        "duplicate_id",
+        `[Sixb] AI usage record '${record.id}' already exists for project '${record.projectId}'.`
+      )
+    }
+
+    this.records.set(recordKey, structuredClone(record))
+    this.recordKeysByIdempotencyKey.set(idempotencyKey, recordKey)
+    for (const groupId of record.requesterGroupIds) {
+      const row: InMemoryAiUsageGroupRow = {
+        projectId: record.projectId,
+        usageRecordId: record.id,
+        groupId,
+        occurredAt: record.occurredAt,
+      }
+      this.groupRows.set(groupRowKey(row), row)
+    }
+
+    return { record: structuredClone(record), created: true }
+  }
+
+  async summarizeExecution(
+    input: SummarizeAiUsageExecutionInput
+  ): Promise<AiUsageExecutionSummary> {
+    const [summary] = await this.summarizeExecutions({
+      projectId: input.projectId,
+      executionIds: [input.executionId],
+    })
+    return summary!
+  }
+
+  async summarizeExecutions(
+    input: SummarizeAiUsageExecutionsInput
+  ): Promise<readonly AiUsageExecutionSummary[]> {
+    if (typeof input.projectId !== "string" || input.projectId.trim().length === 0) {
+      throw new TypeError("[Sixb] AI usage projectId must be nonblank.")
+    }
+
+    const usageByExecutionId = new Map<string, AiModelCallUsageRecord["usage"][]>()
+    for (const executionId of input.executionIds) {
+      assertAiUsageExecutionId(executionId)
+      usageByExecutionId.set(executionId, [])
+    }
+    if (usageByExecutionId.size === 0) return []
+
+    for (const record of this.records.values()) {
+      if (record.projectId !== input.projectId) continue
+      usageByExecutionId.get(record.executionId)?.push(record.usage)
+    }
+
+    return input.executionIds.map((executionId) => {
+      const usages = usageByExecutionId.get(executionId) ?? []
+      return {
+        modelCallCount: usages.length,
+        usage: aggregateAiModelCallUsage(usages),
+      }
+    })
+  }
+
+  snapshot(): InMemoryAiUsageStorageSnapshot {
+    return structuredClone({
+      records: this.records,
+      recordKeysByIdempotencyKey: this.recordKeysByIdempotencyKey,
+      groupRows: this.groupRows,
+    })
+  }
+
+  restore(snapshot: InMemoryAiUsageStorageSnapshot): void {
+    replaceMap(this.records, snapshot.records)
+    replaceMap(this.recordKeysByIdempotencyKey, snapshot.recordKeysByIdempotencyKey)
+    replaceMap(this.groupRows, snapshot.groupRows)
+  }
+
+  private async assertExecutionExists(projectId: string, executionId: string): Promise<void> {
+    const execution = await this.executions.getById({ projectId, id: executionId })
+    if (execution) return
+    throw new AiUsageStorageError(
+      "missing_execution",
+      `[Sixb] AI usage execution '${executionId}' does not exist in project '${projectId}'.`
+    )
+  }
+}
+
+function modelCallRecordKey(projectId: string, id: string): string {
+  return JSON.stringify([projectId, id])
+}
+
+function modelCallIdempotencyKey(
+  record: Pick<
+    AiModelCallUsageRecord,
+    "projectId" | "executionId" | "attempt" | "callId" | "responseId"
+  >
+): string {
+  return JSON.stringify([
+    record.projectId,
+    record.executionId,
+    record.attempt,
+    record.callId,
+    record.responseId,
+  ])
+}
+
+function groupRowKey(row: InMemoryAiUsageGroupRow): string {
+  return JSON.stringify([row.projectId, row.usageRecordId, row.groupId])
+}
+
+function replaceMap<TKey, TValue>(target: Map<TKey, TValue>, source: Map<TKey, TValue>): void {
+  target.clear()
+  for (const [key, value] of structuredClone(source)) {
+    target.set(key, value)
+  }
+}

package/src/storage/ai-usage/index.ts

@@ -0,0 +1,21 @@
+export type { AiUsageStorageErrorCode } from "./errors"
+export { AiUsageStorageError } from "./errors"
+export type {
+  InMemoryAiUsageGroupRow,
+  InMemoryAiUsageStorageSnapshot,
+} from "./in-memory"
+export { InMemoryAiUsageStorage } from "./in-memory"
+export { assertAiUsageExecutionId, normalizeAiModelCallRecord } from "./record"
+export type {
+  AiModelCallUsage,
+  AiModelCallUsageInput,
+  AiModelCallUsageRecord,
+  AiUsageExecutionSummary,
+  AiUsageReportingStatus,
+  AiUsageStorage,
+  RecordAiModelCallInput,
+  RecordAiModelCallResult,
+  SummarizeAiUsageExecutionInput,
+  SummarizeAiUsageExecutionsInput,
+} from "./types"
+export { aggregateAiModelCallUsage, normalizeAiModelCallUsage } from "./usage"

package/src/storage/ai-usage/record.ts

@@ -0,0 +1,74 @@
+import { normalizeRequesterGroupIds } from "../../auth/attribution"
+import { assertJsonValue, isPlainRecord } from "../../json"
+import type { AiModelCallUsageRecord, RecordAiModelCallInput } from "./types"
+import { normalizeAiModelCallUsage } from "./usage"
+
+/** Validate and defensively snapshot one provider-neutral model-call ledger input. */
+export function normalizeAiModelCallRecord(input: RecordAiModelCallInput): AiModelCallUsageRecord {
+  assertNonBlank(input.id, "id")
+  assertNonBlank(input.projectId, "projectId")
+  assertAiUsageExecutionId(input.executionId)
+  assertPositiveSafeInteger(input.attempt, "attempt")
+  assertNonBlank(input.callId, "callId")
+  assertNonBlank(input.providerId, "providerId")
+  assertNonBlank(input.requestedModelId, "requestedModelId")
+  if (input.responseModelId !== undefined) {
+    assertNonBlank(input.responseModelId, "responseModelId")
+  }
+  assertNonBlank(input.responseId, "responseId")
+
+  const occurredAt = cloneValidDate(input.occurredAt, "occurredAt")
+  const recordedAt = cloneValidDate(input.recordedAt ?? new Date(), "recordedAt")
+  const requesterGroupIds = normalizeRequesterGroupIds(input.requesterGroupIds)
+  const rawUsage = cloneRawUsage(input.rawUsage)
+
+  return {
+    id: input.id,
+    projectId: input.projectId,
+    executionId: input.executionId,
+    attempt: input.attempt,
+    callId: input.callId,
+    requesterGroupIds,
+    providerId: input.providerId,
+    requestedModelId: input.requestedModelId,
+    ...(input.responseModelId === undefined ? {} : { responseModelId: input.responseModelId }),
+    responseId: input.responseId,
+    usage: normalizeAiModelCallUsage(input.usage),
+    ...(rawUsage === undefined ? {} : { rawUsage }),
+    occurredAt,
+    recordedAt,
+  }
+}
+
+/** Validate a durable execution reference at storage and query boundaries. */
+export function assertAiUsageExecutionId(executionId: string): void {
+  assertNonBlank(executionId, "executionId")
+}
+
+function cloneRawUsage(rawUsage: RecordAiModelCallInput["rawUsage"]) {
+  if (rawUsage === undefined) return undefined
+  if (!isPlainRecord(rawUsage)) {
+    throw new TypeError("[Sixb] AI usage rawUsage must be a JSON object.")
+  }
+  assertJsonValue(rawUsage, "AI usage rawUsage")
+  return structuredClone(rawUsage)
+}
+
+function assertNonBlank(value: string, field: string): void {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new TypeError(`[Sixb] AI usage ${field} must be nonblank.`)
+  }
+}
+
+function assertPositiveSafeInteger(value: number, field: string): void {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new TypeError(`[Sixb] AI usage ${field} must be a positive safe integer.`)
+  }
+}
+
+function cloneValidDate(value: Date, field: string): Date {
+  if (!(value instanceof Date) || !Number.isFinite(value.getTime())) {
+    throw new TypeError(`[Sixb] AI usage ${field} must be a valid Date.`)
+  }
+  return new Date(value)
+}

package/src/storage/ai-usage/types.ts

@@ -0,0 +1,102 @@
+import type { ReadonlyJsonObject } from "../../json"
+
+/** How much normalized token usage a provider reported for one model call. */
+export type AiUsageReportingStatus = "complete" | "partial" | "unavailable"
+
+/** Provider-neutral token counts accepted at the model-call boundary. */
+export interface AiModelCallUsageInput {
+  readonly inputTokens?: number
+  readonly outputTokens?: number
+  readonly uncachedInputTokens?: number
+  readonly cacheReadInputTokens?: number
+  readonly cacheWriteInputTokens?: number
+  readonly textOutputTokens?: number
+  readonly reasoningOutputTokens?: number
+}
+
+/** Normalized token counts for one completed model call. Details overlap their input/output totals. */
+export interface AiModelCallUsage extends AiModelCallUsageInput {
+  /** Present only when both input and output totals are known. */
+  readonly totalTokens?: number
+  readonly reportingStatus: AiUsageReportingStatus
+}
+
+/** Aggregated usage and call presence for one durable execution. */
+export interface AiUsageExecutionSummary {
+  /** Number of idempotent model-call ledger records included across every delivery attempt. */
+  readonly modelCallCount: number
+  /** Unavailable with a positive call count means the provider reported no normalized counts. */
+  readonly usage: AiModelCallUsage
+}
+
+/** Input for an idempotent model-call ledger append. */
+export interface RecordAiModelCallInput {
+  readonly id: string
+  readonly projectId: string
+  /** Immutable execution-ledger record that owns this provider call. */
+  readonly executionId: string
+  /** Queue delivery attempt that made the provider call. */
+  readonly attempt: number
+  /** AI SDK generation ID. Tool-loop model calls share it and are distinguished by responseId. */
+  readonly callId: string
+  /**
+   * Durable group memberships snapshotted when the parent run was admitted. The requester itself
+   * is read from the immutable execution record.
+   */
+  readonly requesterGroupIds: readonly string[]
+  /** AI SDK provider that handled the call, such as `openai`, `anthropic`, or `gateway`. */
+  readonly providerId: string
+  readonly requestedModelId: string
+  /** Provider-returned model identity when the capture path exposes it. */
+  readonly responseModelId?: string
+  /** Provider-returned response ID used for later usage and cost reconciliation. */
+  readonly responseId: string
+  readonly usage: AiModelCallUsageInput
+  readonly rawUsage?: ReadonlyJsonObject
+  /** When the provider call completed, used for historical pricing and accounting periods. */
+  readonly occurredAt: Date
+  readonly recordedAt?: Date
+}
+
+/** Immutable accounting record for one completed provider model call. */
+export interface AiModelCallUsageRecord extends RecordAiModelCallInput {
+  readonly usage: AiModelCallUsage
+  readonly recordedAt: Date
+}
+
+export interface RecordAiModelCallResult {
+  readonly record: AiModelCallUsageRecord
+  /** False when the idempotency key already existed and its record was returned. */
+  readonly created: boolean
+}
+
+export interface SummarizeAiUsageExecutionInput {
+  readonly projectId: string
+  readonly executionId: string
+}
+
+export interface SummarizeAiUsageExecutionsInput {
+  readonly projectId: string
+  readonly executionIds: readonly string[]
+}
+
+/** Durable, provider-neutral accounting for completed language-model calls. */
+export interface AiUsageStorage {
+  /**
+   * Append one model-call record idempotently. The identity is project, execution ID, attempt, call
+   * ID, and response ID; retrying that identity returns the existing record with `created: false`.
+   */
+  recordModelCall(input: RecordAiModelCallInput): Promise<RecordAiModelCallResult>
+
+  /** Aggregate normalized usage and call presence across every attempt of one execution. */
+  summarizeExecution(input: SummarizeAiUsageExecutionInput): Promise<AiUsageExecutionSummary>
+
+  /**
+   * Aggregate multiple executions in one storage read. Results have the same length and order as
+   * `executionIds`. Executions without ledger records have a zero model-call count and unavailable
+   * usage.
+   */
+  summarizeExecutions(
+    input: SummarizeAiUsageExecutionsInput
+  ): Promise<readonly AiUsageExecutionSummary[]>
+}

package/src/storage/ai-usage/usage.ts

@@ -0,0 +1,104 @@
+import type { AiModelCallUsage, AiModelCallUsageInput } from "./types"
+
+const USAGE_FIELDS = [
+  "inputTokens",
+  "outputTokens",
+  "uncachedInputTokens",
+  "cacheReadInputTokens",
+  "cacheWriteInputTokens",
+  "textOutputTokens",
+  "reasoningOutputTokens",
+] as const
+
+type AiUsageField = (typeof USAGE_FIELDS)[number]
+
+/** Validate provider-neutral counts and derive total/reporting fields without inventing zeroes. */
+export function normalizeAiModelCallUsage(input: AiModelCallUsageInput): AiModelCallUsage {
+  for (const field of USAGE_FIELDS) {
+    assertUsageCount(input[field], field)
+  }
+
+  const totalTokens =
+    input.inputTokens === undefined || input.outputTokens === undefined
+      ? undefined
+      : addUsageCounts(input.inputTokens, input.outputTokens, "totalTokens")
+  const reportingStatus =
+    input.inputTokens !== undefined && input.outputTokens !== undefined
+      ? "complete"
+      : USAGE_FIELDS.some((field) => input[field] !== undefined)
+        ? "partial"
+        : "unavailable"
+
+  return {
+    ...(input.inputTokens === undefined ? {} : { inputTokens: input.inputTokens }),
+    ...(input.outputTokens === undefined ? {} : { outputTokens: input.outputTokens }),
+    ...(totalTokens === undefined ? {} : { totalTokens }),
+    ...(input.uncachedInputTokens === undefined
+      ? {}
+      : { uncachedInputTokens: input.uncachedInputTokens }),
+    ...(input.cacheReadInputTokens === undefined
+      ? {}
+      : { cacheReadInputTokens: input.cacheReadInputTokens }),
+    ...(input.cacheWriteInputTokens === undefined
+      ? {}
+      : { cacheWriteInputTokens: input.cacheWriteInputTokens }),
+    ...(input.textOutputTokens === undefined ? {} : { textOutputTokens: input.textOutputTokens }),
+    ...(input.reasoningOutputTokens === undefined
+      ? {}
+      : { reasoningOutputTokens: input.reasoningOutputTokens }),
+    reportingStatus,
+  }
+}
+
+/**
+ * Aggregate model-call usage without treating a missing count as zero.
+ *
+ * A field is present only when every call reported it. This prevents a partial provider response
+ * from becoming an apparently complete execution total. Zero remains a reported value.
+ */
+export function aggregateAiModelCallUsage(
+  usages: Iterable<AiModelCallUsageInput>
+): AiModelCallUsage {
+  const normalized = Array.from(usages, normalizeAiModelCallUsage)
+  const fields = Object.fromEntries(
+    USAGE_FIELDS.map((field) => [field, sumUsageField(normalized, field)])
+  ) as Record<AiUsageField, number | undefined>
+  const aggregate = normalizeAiModelCallUsage(fields)
+
+  if (
+    aggregate.reportingStatus === "unavailable" &&
+    normalized.some((usage) => usage.reportingStatus !== "unavailable")
+  ) {
+    return { ...aggregate, reportingStatus: "partial" }
+  }
+  return aggregate
+}
+
+function sumUsageField(
+  usages: readonly AiModelCallUsage[],
+  field: AiUsageField
+): number | undefined {
+  if (usages.length === 0) return undefined
+
+  let total = 0
+  for (const usage of usages) {
+    const value = usage[field]
+    if (value === undefined) return undefined
+    total = addUsageCounts(total, value, `aggregate ${field}`)
+  }
+  return total
+}
+
+function assertUsageCount(value: number | undefined, field: AiUsageField): void {
+  if (value !== undefined && (!Number.isSafeInteger(value) || value < 0)) {
+    throw new TypeError(`[Sixb] AI model-call usage ${field} must be a non-negative safe integer.`)
+  }
+}
+
+function addUsageCounts(left: number, right: number, field: string): number {
+  const result = left + right
+  if (!Number.isSafeInteger(result)) {
+    throw new TypeError(`[Sixb] AI model-call usage ${field} exceeds the safe integer range.`)
+  }
+  return result
+}

package/src/storage/auth/types.ts

@@ -437,6 +437,7 @@ export interface AuthServiceAccountStore {
     readonly projectId: string
     readonly id: string
   }): Promise<ServiceAccountRecord | null>
+  /** Update only the provided fields; omitted fields must remain unchanged atomically. */
   update(input: UpdateAuthServiceAccountInput): Promise<ServiceAccountRecord>
   list(input: ListAuthServiceAccountsInput): Promise<ListAuthServiceAccountsResult>
 }

package/src/storage/connector-connections/errors.ts

@@ -0,0 +1,24 @@
+export type ConnectorConnectionStorageErrorCode =
+  | "attempt_conflict"
+  | "attempt_invalid"
+  | "run_conflict"
+  | "run_invalid"
+  | "authorization_conflict"
+  | "connection_conflict"
+  | "invalid_input"
+
+/**
+ * Storage-provider control signal for atomic conflicts and invalid calls.
+ *
+ * These codes belong to the provider contract, not `SixbErrorCode`; Core translates errors that
+ * cross the connector lifecycle boundary into documented `connector.*` failures.
+ */
+export class ConnectorConnectionStorageError extends Error {
+  readonly code: ConnectorConnectionStorageErrorCode
+
+  constructor(code: ConnectorConnectionStorageErrorCode, message: string) {
+    super(message)
+    this.name = "ConnectorConnectionStorageError"
+    this.code = code
+  }
+}