@sixb/core 0.1.1 → 0.1.2

package/src/storage/executions/provider.ts

@@ -0,0 +1,292 @@
+import type { TrustedPrimitiveKind } from "../../execution/types"
+import { ExecutionStorageError } from "./errors"
+import type { CreateExecutionInput, ExecutionRecord } from "./types"
+import { normalizeExecutionRecord } from "./validation"
+
+export {
+  type ExecutionValidationLookup,
+  normalizeExecutionRecord,
+  validateExecutionRecordReferences,
+} from "./validation"
+
+/** Provider-neutral flattened representation used by the SQL adapters. */
+export interface ExecutionStorageRow {
+  readonly projectId: string
+  readonly id: string
+  readonly executorKind: "agent" | "kernel" | "request" | TrustedPrimitiveKind
+  readonly executorId: string
+  readonly sourceKind: "datasetVersion" | "event" | "execution" | "http" | "schedule" | "webhook"
+  readonly sourceId: string
+  readonly requestedByUserId: string | null
+  readonly requestedByServiceAccountId: string | null
+  readonly correlationId: string
+  /** SQL-only projection of an execution source, used to enforce the parent foreign key. */
+  readonly parentExecutionId: string | null
+  readonly authorityKind: "disabled" | "kernel" | "principal" | "trustedPrimitive"
+  readonly authorityUserId: string | null
+  readonly authorityServiceAccountId: string | null
+  readonly authoritySessionId: string | null
+  readonly authorityAccessTokenId: string | null
+  readonly authorityPrimitiveKind: TrustedPrimitiveKind | null
+  readonly authorityPrimitiveId: string | null
+  readonly authorityKernelOperation: "ontology.recover" | null
+  readonly createdAt: Date
+}
+
+export function executionRecordToStorageRow(record: ExecutionRecord): ExecutionStorageRow {
+  const executor = flattenExecutor(record)
+  const source = flattenSource(record)
+  const authority = flattenAuthority(record)
+  return {
+    projectId: record.projectId,
+    id: record.id,
+    ...executor,
+    ...source,
+    requestedByUserId: record.requestedBy?.type === "user" ? record.requestedBy.id : null,
+    requestedByServiceAccountId:
+      record.requestedBy?.type === "serviceAccount" ? record.requestedBy.id : null,
+    correlationId: record.correlationId,
+    parentExecutionId: record.source.type === "execution" ? record.source.executionId : null,
+    ...authority,
+    createdAt: new Date(record.createdAt),
+  }
+}
+
+export function executionRecordFromStorageRow(row: ExecutionStorageRow): ExecutionRecord {
+  const executor = inflateExecutor(row)
+  const source = inflateSource(row)
+  assertStoredParent(row, source)
+  const authorizationRef = inflateAuthority(row)
+  const requestedBy = row.requestedByUserId
+    ? ({ type: "user", id: row.requestedByUserId } as const)
+    : row.requestedByServiceAccountId
+      ? ({ type: "serviceAccount", id: row.requestedByServiceAccountId } as const)
+      : undefined
+
+  return normalizeExecutionRecord(
+    {
+      id: row.id,
+      projectId: row.projectId,
+      ...(requestedBy === undefined ? {} : { requestedBy }),
+      executor,
+      source,
+      correlationId: row.correlationId,
+      authorizationRef,
+    },
+    row.createdAt
+  )
+}
+
+function assertStoredParent(
+  row: ExecutionStorageRow,
+  source: CreateExecutionInput["source"]
+): void {
+  const expected = source.type === "execution" ? source.executionId : null
+  if (row.parentExecutionId !== expected) {
+    throw new ExecutionStorageError(
+      "invalid_parent_execution",
+      `[Sixb] Stored execution '${row.id}' has inconsistent parent execution provenance.`
+    )
+  }
+}
+
+function flattenExecutor(
+  record: ExecutionRecord
+): Pick<ExecutionStorageRow, "executorId" | "executorKind"> {
+  switch (record.executor.type) {
+    case "request":
+      return { executorKind: "request", executorId: record.executor.requestId }
+    case "primitive":
+      return { executorKind: record.executor.kind, executorId: record.executor.runId }
+    case "agent":
+      return { executorKind: "agent", executorId: record.executor.runId }
+    case "kernel":
+      return { executorKind: "kernel", executorId: record.executor.operation.recoveryId }
+  }
+}
+
+function flattenSource(
+  record: ExecutionRecord
+): Pick<ExecutionStorageRow, "sourceId" | "sourceKind"> {
+  switch (record.source.type) {
+    case "http":
+      return { sourceKind: "http", sourceId: record.source.requestId }
+    case "webhook":
+      return { sourceKind: "webhook", sourceId: record.source.deliveryId }
+    case "schedule":
+    case "event":
+      return { sourceKind: record.source.type, sourceId: record.source.eventId }
+    case "datasetVersion":
+      return {
+        sourceKind: "datasetVersion",
+        sourceId: JSON.stringify([record.source.datasetId, record.source.versionId]),
+      }
+    case "execution":
+      return { sourceKind: "execution", sourceId: record.source.executionId }
+  }
+}
+
+function flattenAuthority(
+  record: ExecutionRecord
+): Pick<
+  ExecutionStorageRow,
+  | "authorityAccessTokenId"
+  | "authorityKernelOperation"
+  | "authorityKind"
+  | "authorityPrimitiveId"
+  | "authorityPrimitiveKind"
+  | "authorityServiceAccountId"
+  | "authoritySessionId"
+  | "authorityUserId"
+> {
+  const empty = {
+    authorityUserId: null,
+    authorityServiceAccountId: null,
+    authoritySessionId: null,
+    authorityAccessTokenId: null,
+    authorityPrimitiveKind: null,
+    authorityPrimitiveId: null,
+    authorityKernelOperation: null,
+  }
+
+  switch (record.authorizationRef.type) {
+    case "principal":
+      return {
+        ...empty,
+        authorityKind: "principal",
+        authorityUserId:
+          record.authorizationRef.principal.type === "user"
+            ? record.authorizationRef.principal.id
+            : null,
+        authorityServiceAccountId:
+          record.authorizationRef.principal.type === "serviceAccount"
+            ? record.authorizationRef.principal.id
+            : null,
+        authoritySessionId:
+          record.authorizationRef.credential?.type === "session"
+            ? record.authorizationRef.credential.id
+            : null,
+        authorityAccessTokenId:
+          record.authorizationRef.credential?.type === "accessToken"
+            ? record.authorizationRef.credential.id
+            : null,
+      }
+    case "trustedPrimitive":
+      return {
+        ...empty,
+        authorityKind: "trustedPrimitive",
+        authorityPrimitiveKind: record.authorizationRef.primitive.kind,
+        authorityPrimitiveId: record.authorizationRef.primitive.id,
+      }
+    case "kernel":
+      return {
+        ...empty,
+        authorityKind: "kernel",
+        authorityKernelOperation: record.authorizationRef.operation.type,
+      }
+    case "disabled":
+      return { ...empty, authorityKind: "disabled" }
+  }
+}
+
+function inflateExecutor(row: ExecutionStorageRow): CreateExecutionInput["executor"] {
+  switch (row.executorKind) {
+    case "request":
+      return { type: "request", requestId: row.executorId }
+    case "agent":
+      return { type: "agent", runId: row.executorId }
+    case "kernel":
+      return {
+        type: "kernel",
+        operation: {
+          type: requireValue(row.authorityKernelOperation, "authority kernel operation"),
+          recoveryId: row.executorId,
+        },
+      }
+    default:
+      return { type: "primitive", kind: row.executorKind, runId: row.executorId }
+  }
+}
+
+function inflateSource(row: ExecutionStorageRow): CreateExecutionInput["source"] {
+  switch (row.sourceKind) {
+    case "http":
+      return { type: "http", requestId: row.sourceId }
+    case "webhook":
+      return { type: "webhook", deliveryId: row.sourceId }
+    case "schedule":
+    case "event":
+      return { type: row.sourceKind, eventId: row.sourceId }
+    case "datasetVersion": {
+      const [datasetId, versionId] = parseDatasetVersionSourceId(row.sourceId)
+      return { type: "datasetVersion", datasetId, versionId }
+    }
+    case "execution":
+      return { type: "execution", executionId: row.sourceId }
+  }
+}
+
+function parseDatasetVersionSourceId(sourceId: string): readonly [string, string] {
+  try {
+    const parsed: unknown = JSON.parse(sourceId)
+    if (
+      Array.isArray(parsed) &&
+      parsed.length === 2 &&
+      parsed.every((value) => typeof value === "string" && value.trim().length > 0)
+    ) {
+      return parsed as unknown as readonly [string, string]
+    }
+  } catch {
+    // Fall through to the provider-corruption error below.
+  }
+  throw new Error("[Sixb] Stored dataset-version execution source is malformed.")
+}
+
+function inflateAuthority(row: ExecutionStorageRow): CreateExecutionInput["authorizationRef"] {
+  switch (row.authorityKind) {
+    case "principal": {
+      const principal = row.authorityUserId
+        ? ({ type: "user", id: row.authorityUserId } as const)
+        : ({
+            type: "serviceAccount",
+            id: requireValue(row.authorityServiceAccountId, "authority service account id"),
+          } as const)
+      const credential = row.authoritySessionId
+        ? ({ type: "session", id: row.authoritySessionId } as const)
+        : row.authorityAccessTokenId
+          ? ({ type: "accessToken", id: row.authorityAccessTokenId } as const)
+          : undefined
+      return {
+        type: "principal",
+        principal,
+        ...(credential === undefined ? {} : { credential }),
+      }
+    }
+    case "trustedPrimitive":
+      return {
+        type: "trustedPrimitive",
+        primitive: {
+          kind: requireValue(row.authorityPrimitiveKind, "authority primitive kind"),
+          id: requireValue(row.authorityPrimitiveId, "authority primitive id"),
+          runId: row.executorId,
+        },
+      }
+    case "kernel":
+      return {
+        type: "kernel",
+        operation: {
+          type: requireValue(row.authorityKernelOperation, "authority kernel operation"),
+          recoveryId: row.executorId,
+        },
+      }
+    case "disabled":
+      return { type: "disabled" }
+  }
+}
+
+function requireValue<T>(value: T | null, label: string): T {
+  if (value === null) {
+    throw new Error(`[Sixb] Stored execution is missing ${label}.`)
+  }
+  return value
+}

package/src/storage/executions/run-link.ts

@@ -0,0 +1,70 @@
+import type { TrustedPrimitiveRef } from "../../execution/types"
+import type { ExecutionRecord, ExecutionStorage } from "./types"
+
+/**
+ * Find the immutable execution that is the authority owned by a primitive run.
+ *
+ * ExecutionStorage owns generic provenance invariants. Primitive providers remain responsible for
+ * deciding which sources they accept and translating a mismatch to their domain-specific error.
+ */
+export async function findPrimitiveRunExecution(input: {
+  readonly executions: ExecutionStorage
+  readonly projectId: string
+  readonly executionId: string
+  readonly primitive: TrustedPrimitiveRef
+  readonly sourceTypes: readonly (
+    | "datasetVersion"
+    | "event"
+    | "execution"
+    | "schedule"
+    | "webhook"
+  )[]
+}): Promise<ExecutionRecord | null> {
+  const execution = await input.executions.getById({
+    projectId: input.projectId,
+    id: input.executionId,
+  })
+  const authority = execution?.authorizationRef
+  if (
+    !execution ||
+    !input.sourceTypes.some((type) => type === execution.source.type) ||
+    execution.executor.type !== "primitive" ||
+    execution.executor.kind !== input.primitive.kind ||
+    execution.executor.runId !== input.primitive.runId ||
+    authority?.type !== "trustedPrimitive" ||
+    authority.primitive.kind !== input.primitive.kind ||
+    authority.primitive.id !== input.primitive.id ||
+    authority.primitive.runId !== input.primitive.runId
+  ) {
+    return null
+  }
+  return execution
+}
+
+/** Find the immutable execution and service-account authority owned by one Agent run. */
+export async function findAgentRunExecution(input: {
+  readonly executions: ExecutionStorage
+  readonly projectId: string
+  readonly executionId: string
+  readonly runId: string
+  readonly serviceAccountId: string
+}): Promise<ExecutionRecord | null> {
+  const execution = await input.executions.getById({
+    projectId: input.projectId,
+    id: input.executionId,
+  })
+  const authority = execution?.authorizationRef
+  if (
+    !execution ||
+    execution.source.type !== "execution" ||
+    execution.executor.type !== "agent" ||
+    execution.executor.runId !== input.runId ||
+    authority?.type !== "principal" ||
+    authority.principal.type !== "serviceAccount" ||
+    authority.principal.id !== input.serviceAccountId ||
+    authority.credential !== undefined
+  ) {
+    return null
+  }
+  return execution
+}

package/src/storage/executions/types.ts

@@ -0,0 +1,49 @@
+import type {
+  AuthorizablePrincipal,
+  AuthorizationRef,
+  KernelOperation,
+  TrustedPrimitiveKind,
+} from "../../execution/types"
+
+/** Executor identity stored independently from the primitive definition owned by its run. */
+export type DurableExecutionExecutor =
+  | { readonly type: "request"; readonly requestId: string }
+  | { readonly type: "primitive"; readonly kind: TrustedPrimitiveKind; readonly runId: string }
+  | { readonly type: "agent"; readonly runId: string }
+  | { readonly type: "kernel"; readonly operation: KernelOperation }
+
+/**
+ * Durable trigger provenance. An `execution` source is the single logical parent; queue delivery
+ * is attempt transport and is never persisted here.
+ */
+export type DurableExecutionSource =
+  | { readonly type: "http"; readonly requestId: string }
+  | { readonly type: "webhook"; readonly deliveryId: string }
+  | { readonly type: "schedule"; readonly eventId: string }
+  | { readonly type: "event"; readonly eventId: string }
+  | { readonly type: "datasetVersion"; readonly datasetId: string; readonly versionId: string }
+  | { readonly type: "execution"; readonly executionId: string }
+
+/** Immutable execution provenance and the reference required to restore its runtime authority. */
+export interface ExecutionRecord {
+  readonly id: string
+  readonly projectId: string
+  readonly requestedBy?: AuthorizablePrincipal
+  readonly executor: DurableExecutionExecutor
+  readonly source: DurableExecutionSource
+  readonly correlationId: string
+  readonly authorizationRef: AuthorizationRef
+  readonly createdAt: Date
+}
+
+/** Creation input; the storage boundary assigns the immutable creation timestamp. */
+export type CreateExecutionInput = Omit<ExecutionRecord, "createdAt">
+
+/** Immutable execution ledger. Records can be created and read, never updated or deleted. */
+export interface ExecutionStorage {
+  create(input: CreateExecutionInput): Promise<ExecutionRecord>
+  getById(params: {
+    readonly projectId: string
+    readonly id: string
+  }): Promise<ExecutionRecord | null>
+}