@sixb/core 0.1.0 → 0.1.2

package/src/execution/authorization.ts

@@ -0,0 +1,409 @@
+import type { Principal } from "../auth"
+import { emptyGrantSets, GRANT_KIND_KEYS } from "../authorization/grant-kinds"
+import type { AuthorizationContext, GrantIndex } from "../authorization/types"
+import { createSixbError } from "../errors/internal"
+import {
+  type AuthorizablePrincipal,
+  type AuthorizationRef,
+  createRuntimeAuthorizationCapability,
+  type ExecutionScope,
+  isRuntimeAuthorizationCapability,
+  type KernelOperation,
+  type RuntimeAuthorization,
+  type TrustedPrimitiveKind,
+  type TrustedPrimitiveRef,
+} from "./types"
+
+export type ResolvedRuntimeAuthorization =
+  | {
+      readonly type: "principal"
+      readonly projectId: string
+      readonly context: AuthorizationContext
+      readonly ref: Extract<AuthorizationRef, { readonly type: "principal" }>
+      /** Process-local binding used by provider façades that explicitly support agent runs. */
+      readonly executionBinding?: AgentExecutionBinding
+    }
+  | {
+      readonly type: "unrestricted"
+      readonly projectId: string
+      readonly ref: Exclude<AuthorizationRef, { readonly type: "principal" }>
+    }
+  | { readonly type: "denied" }
+
+type RegisteredRuntimeAuthorization = Exclude<
+  ResolvedRuntimeAuthorization,
+  { readonly type: "denied" }
+>
+
+type PrincipalAuthorizationContext = Omit<AuthorizationContext, "principal"> & {
+  readonly principal: AuthorizablePrincipal
+}
+
+interface AgentExecutionBinding {
+  readonly type: "agent"
+  readonly executionId: string
+  readonly agentId: string
+  readonly runId: string
+}
+
+const registeredAuthorizations = new WeakMap<RuntimeAuthorization, RegisteredRuntimeAuthorization>()
+
+export function createPrincipalRuntimeAuthorization(input: {
+  readonly projectId: string
+  readonly context: AuthorizationContext
+  readonly credential?: Extract<AuthorizationRef, { readonly type: "principal" }>["credential"]
+}): RuntimeAuthorization {
+  return createRegisteredPrincipalAuthorization(input)
+}
+
+/** Register service-account authority bound to one exact agent run. */
+export function createAgentRuntimeAuthorization(input: {
+  readonly projectId: string
+  readonly context: AuthorizationContext
+  readonly executionId: string
+  readonly agentId: string
+  readonly runId: string
+}): RuntimeAuthorization {
+  if (input.context.principal.type !== "serviceAccount") {
+    throw new Error("[Sixb] Agent execution authority must belong to a service account.")
+  }
+  assertNonEmpty(input.executionId, "Execution id")
+  assertNonEmpty(input.agentId, "Agent id")
+  assertNonEmpty(input.runId, "Agent run id")
+  return createRegisteredPrincipalAuthorization(input, {
+    type: "agent",
+    executionId: input.executionId,
+    agentId: input.agentId,
+    runId: input.runId,
+  })
+}
+
+function createRegisteredPrincipalAuthorization(
+  input: {
+    readonly projectId: string
+    readonly context: AuthorizationContext
+    readonly credential?: Extract<AuthorizationRef, { readonly type: "principal" }>["credential"]
+  },
+  executionBinding?: AgentExecutionBinding
+): RuntimeAuthorization {
+  const context = snapshotAuthorizationContext(input.context)
+  const credential = input.credential ? snapshotCredential(input.credential) : undefined
+  assertCredentialMatchesContext(context, credential)
+  const ref: Extract<AuthorizationRef, { readonly type: "principal" }> = Object.freeze({
+    type: "principal",
+    principal: context.principal,
+    ...(credential === undefined ? {} : { credential }),
+  })
+  return register({
+    type: "principal",
+    projectId: input.projectId,
+    context,
+    ref,
+    ...(executionBinding === undefined
+      ? {}
+      : { executionBinding: Object.freeze({ ...executionBinding }) }),
+  })
+}
+
+export function createDisabledRuntimeAuthorization(projectId: string): RuntimeAuthorization {
+  return register({ type: "unrestricted", projectId, ref: Object.freeze({ type: "disabled" }) })
+}
+
+export function createTrustedPrimitiveRuntimeAuthorization(input: {
+  readonly projectId: string
+  readonly primitive: TrustedPrimitiveRef
+}): RuntimeAuthorization {
+  const primitive = snapshotTrustedPrimitive(input.primitive)
+  return register({
+    type: "unrestricted",
+    projectId: input.projectId,
+    ref: Object.freeze({ type: "trustedPrimitive", primitive }),
+  })
+}
+
+export function createKernelRuntimeAuthorization(input: {
+  readonly projectId: string
+  readonly operation: KernelOperation
+}): RuntimeAuthorization {
+  const operation = snapshotKernelOperation(input.operation)
+  return register({
+    type: "unrestricted",
+    projectId: input.projectId,
+    ref: Object.freeze({ type: "kernel", operation }),
+  })
+}
+
+export function resolveRuntimeAuthorization(authorization: unknown): ResolvedRuntimeAuthorization {
+  if (!isRuntimeAuthorizationCapability(authorization)) {
+    return { type: "denied" }
+  }
+  return registeredAuthorizations.get(authorization) ?? { type: "denied" }
+}
+
+export function getAuthorizationRef(authorization: RuntimeAuthorization): AuthorizationRef {
+  const resolved = resolveRuntimeAuthorization(authorization)
+  if (resolved.type === "denied") {
+    throw new Error("[Sixb] Runtime authorization is not a registered Core capability.")
+  }
+  return cloneAuthorizationRef(resolved.ref)
+}
+
+export function assertExecutionScopeProject(projectId: string, scope: ExecutionScope): void {
+  assertNonEmpty(projectId, "Project id")
+  if (scope.execution.projectId !== projectId) {
+    throw createSixbError(
+      "internal.unexpected",
+      `[Sixb] Execution scope belongs to project '${scope.execution.projectId}', not '${projectId}'.`,
+      {
+        details: {
+          executionId: scope.execution.id,
+          expectedProjectId: projectId,
+          scopeProjectId: scope.execution.projectId,
+        },
+      }
+    )
+  }
+
+  const resolved = resolveRuntimeAuthorization(scope.authorization)
+  if (resolved.type === "denied") {
+    throw createSixbError(
+      "internal.unexpected",
+      "[Sixb] Execution scope carries unregistered runtime authorization.",
+      { details: { executionId: scope.execution.id, projectId } }
+    )
+  }
+  if (resolved.projectId !== projectId) {
+    throw createSixbError(
+      "internal.unexpected",
+      `[Sixb] Execution authorization belongs to project '${resolved.projectId}', not '${projectId}'.`,
+      {
+        details: {
+          authorizationProjectId: resolved.projectId,
+          executionId: scope.execution.id,
+          expectedProjectId: projectId,
+        },
+      }
+    )
+  }
+}
+
+/** Validate that one registered authority belongs to the exact execution it accompanies. */
+export function resolveExecutionScopeAuthorization(
+  projectId: string,
+  scope: ExecutionScope
+): RegisteredRuntimeAuthorization {
+  assertExecutionScopeProject(projectId, scope)
+  const resolved = resolveRuntimeAuthorization(scope.authorization)
+  if (resolved.type === "denied") {
+    throw createSixbError(
+      "internal.unexpected",
+      "[Sixb] Execution scope carries unregistered runtime authorization.",
+      { details: { executionId: scope.execution.id, projectId } }
+    )
+  }
+
+  const { execution } = scope
+  switch (execution.executor.type) {
+    case "request":
+      if (
+        execution.source.type !== "http" ||
+        execution.source.requestId !== execution.executor.requestId
+      ) {
+        throw invalidExecutionAuthority(execution.id, "request source does not match its executor")
+      }
+      if (resolved.ref.type === "principal") {
+        if (
+          resolved.type !== "principal" ||
+          resolved.executionBinding !== undefined ||
+          !principalsEqual(execution.requestedBy, resolved.ref.principal)
+        ) {
+          throw invalidExecutionAuthority(
+            execution.id,
+            "request authority does not match its requested-by principal"
+          )
+        }
+        return resolved
+      }
+      if (resolved.ref.type === "disabled" && execution.requestedBy === undefined) return resolved
+      throw invalidExecutionAuthority(
+        execution.id,
+        "request execution requires principal or explicitly disabled authority"
+      )
+
+    case "primitive":
+      if (
+        resolved.ref.type !== "trustedPrimitive" ||
+        resolved.ref.primitive.kind !== execution.executor.kind ||
+        resolved.ref.primitive.id !== execution.executor.id ||
+        resolved.ref.primitive.runId !== execution.executor.runId
+      ) {
+        throw invalidExecutionAuthority(
+          execution.id,
+          "trusted primitive authority does not match its executor"
+        )
+      }
+      return resolved
+
+    case "agent":
+      if (
+        resolved.type !== "principal" ||
+        resolved.ref.type !== "principal" ||
+        resolved.ref.principal.type !== "serviceAccount" ||
+        resolved.ref.credential !== undefined ||
+        resolved.executionBinding?.type !== "agent" ||
+        resolved.executionBinding.executionId !== execution.id ||
+        resolved.executionBinding.agentId !== execution.executor.agentId ||
+        resolved.executionBinding.runId !== execution.executor.runId
+      ) {
+        throw invalidExecutionAuthority(
+          execution.id,
+          "agent authority does not match its execution binding"
+        )
+      }
+      return resolved
+
+    case "kernel":
+      if (
+        resolved.ref.type !== "kernel" ||
+        execution.requestedBy !== undefined ||
+        resolved.ref.operation.type !== execution.executor.operation.type ||
+        resolved.ref.operation.recoveryId !== execution.executor.operation.recoveryId
+      ) {
+        throw invalidExecutionAuthority(
+          execution.id,
+          "kernel authority does not match its executor"
+        )
+      }
+      return resolved
+  }
+}
+
+function principalsEqual(
+  left: AuthorizablePrincipal | undefined,
+  right: AuthorizablePrincipal | undefined
+): boolean {
+  return left?.type === right?.type && left?.id === right?.id
+}
+
+function invalidExecutionAuthority(executionId: string, reason: string): Error {
+  return createSixbError(
+    "internal.unexpected",
+    `[Sixb] Execution '${executionId}' is incompatible with its authority: ${reason}.`,
+    { details: { executionId, reason } }
+  )
+}
+
+function register(input: RegisteredRuntimeAuthorization): RuntimeAuthorization {
+  assertNonEmpty(input.projectId, "Authorization project id")
+  const authorization = createRuntimeAuthorizationCapability()
+  registeredAuthorizations.set(authorization, Object.freeze(input))
+  return authorization
+}
+
+function snapshotAuthorizationContext(
+  context: AuthorizationContext
+): PrincipalAuthorizationContext {
+  const principal = snapshotAuthorizablePrincipal(context.principal)
+  const grants = emptyGrantSets()
+  for (const kind of GRANT_KIND_KEYS) {
+    grants[kind] = new Set(context.grants[kind])
+  }
+  const frozenGrants: GrantIndex = Object.freeze(grants)
+  return Object.freeze({
+    principal,
+    ...(context.sessionId === undefined ? {} : { sessionId: context.sessionId }),
+    groupIds: Object.freeze([...context.groupIds]),
+    roleIds: Object.freeze([...context.roleIds]),
+    grants: frozenGrants,
+  })
+}
+
+function snapshotAuthorizablePrincipal(principal: Principal): AuthorizablePrincipal {
+  if (principal.type !== "user" && principal.type !== "serviceAccount") {
+    throw new Error(`[Sixb] Principal type '${principal.type}' cannot hold runtime authorization.`)
+  }
+  assertNonEmpty(principal.id, "Authorization principal id")
+  return Object.freeze({ type: principal.type, id: principal.id })
+}
+
+function snapshotCredential(
+  credential: NonNullable<Extract<AuthorizationRef, { readonly type: "principal" }>["credential"]>
+): NonNullable<Extract<AuthorizationRef, { readonly type: "principal" }>["credential"]> {
+  assertNonEmpty(credential.id, "Authorization credential id")
+  if (credential.type !== "session" && credential.type !== "accessToken") {
+    const credentialType = (credential as { readonly type: string }).type
+    throw new Error(`[Sixb] Unknown authorization credential type '${credentialType}'.`)
+  }
+  return Object.freeze({ type: credential.type, id: credential.id })
+}
+
+function assertCredentialMatchesContext(
+  context: PrincipalAuthorizationContext,
+  credential:
+    | NonNullable<Extract<AuthorizationRef, { readonly type: "principal" }>["credential"]>
+    | undefined
+): void {
+  if (credential?.type === "session") {
+    if (context.sessionId !== credential.id) {
+      throw new Error(
+        "[Sixb] Session credential id must match the authorization context session id."
+      )
+    }
+    return
+  }
+  if (context.sessionId !== undefined) {
+    throw new Error("[Sixb] Authorization context session requires a matching session credential.")
+  }
+}
+
+function snapshotTrustedPrimitive(primitive: TrustedPrimitiveRef): TrustedPrimitiveRef {
+  if (!isTrustedPrimitiveKind(primitive.kind)) {
+    throw new Error(`[Sixb] Unknown trusted primitive kind '${primitive.kind}'.`)
+  }
+  assertNonEmpty(primitive.id, "Trusted primitive id")
+  assertNonEmpty(primitive.runId, "Trusted primitive run id")
+  return Object.freeze({ kind: primitive.kind, id: primitive.id, runId: primitive.runId })
+}
+
+function snapshotKernelOperation(operation: KernelOperation): KernelOperation {
+  if (operation.type !== "ontology.recover") {
+    throw new Error(`[Sixb] Unknown kernel operation '${operation.type}'.`)
+  }
+  assertNonEmpty(operation.recoveryId, "Kernel recovery id")
+  return Object.freeze({ type: operation.type, recoveryId: operation.recoveryId })
+}
+
+function cloneAuthorizationRef(ref: AuthorizationRef): AuthorizationRef {
+  switch (ref.type) {
+    case "principal":
+      return {
+        type: "principal",
+        principal: { ...ref.principal },
+        ...(ref.credential === undefined ? {} : { credential: { ...ref.credential } }),
+      }
+    case "trustedPrimitive":
+      return { type: "trustedPrimitive", primitive: { ...ref.primitive } }
+    case "kernel":
+      return { type: "kernel", operation: { ...ref.operation } }
+    case "disabled":
+      return { type: "disabled" }
+  }
+}
+
+function isTrustedPrimitiveKind(value: string): value is TrustedPrimitiveKind {
+  return (
+    value === "action" ||
+    value === "pipeline" ||
+    value === "projection" ||
+    value === "rule" ||
+    value === "sync" ||
+    value === "webhook" ||
+    value === "workflow"
+  )
+}
+
+function assertNonEmpty(value: string, label: string): void {
+  if (!value.trim()) {
+    throw new Error(`[Sixb] ${label} must not be empty.`)
+  }
+}

package/src/execution/dispatch.ts

@@ -0,0 +1,7 @@
+/**
+ * Typed boundary for turning one resolved primitive run intent into durable state and transport.
+ * Implementations own their primitive-specific validation, persistence, and queue publication.
+ */
+export interface RunDispatcher<TInput, TResult> {
+  dispatch(input: TInput): Promise<TResult>
+}

package/src/execution/durable.ts

@@ -0,0 +1,193 @@
+import { isDeepStrictEqual } from "node:util"
+import {
+  type CreateExecutionInput,
+  type ExecutionRecord,
+  type ExecutionStorage,
+  ExecutionStorageError,
+} from "../storage/executions"
+import { createTrustedPrimitiveRuntimeAuthorization, getAuthorizationRef } from "./authorization"
+import type {
+  ExecutionContext,
+  ExecutionScope,
+  RuntimeAuthorization,
+  TrustedPrimitiveRef,
+} from "./types"
+
+/** Convert one currently bound execution to the immutable provider representation. */
+export function executionRecordInputFromRuntime(input: {
+  readonly execution: ExecutionContext
+  readonly runtimeAuthorization: RuntimeAuthorization
+}): CreateExecutionInput {
+  const execution = input.execution
+  return {
+    id: execution.id,
+    projectId: execution.projectId,
+    ...(execution.requestedBy === undefined
+      ? {}
+      : { requestedBy: structuredClone(execution.requestedBy) }),
+    executor: durableExecutor(execution),
+    source: structuredClone(execution.source),
+    correlationId: execution.correlationId,
+    authorizationRef: getAuthorizationRef(input.runtimeAuthorization),
+  }
+}
+
+/**
+ * Store a caller execution once. Repeated boundaries may observe the same immutable execution;
+ * only an exact match is idempotent.
+ */
+export async function ensureExecutionRecord(
+  storage: ExecutionStorage,
+  input: CreateExecutionInput
+): Promise<ExecutionRecord> {
+  const existing = await storage.getById({ projectId: input.projectId, id: input.id })
+  if (existing) {
+    assertExecutionRecordMatches(existing, input)
+    return existing
+  }
+
+  try {
+    return await storage.create(input)
+  } catch (error) {
+    if (!(error instanceof ExecutionStorageError) || error.code !== "duplicate_execution") {
+      throw error
+    }
+
+    const raced = await storage.getById({ projectId: input.projectId, id: input.id })
+    if (!raced) throw error
+    assertExecutionRecordMatches(raced, input)
+    return raced
+  }
+}
+
+type PrimitiveExecutionOrigin =
+  | {
+      readonly type: "execution"
+      readonly parent: ExecutionRecord
+    }
+  | {
+      readonly type: "automatic"
+      readonly projectId: string
+      readonly source: Extract<
+        CreateExecutionInput["source"],
+        { readonly type: "schedule" | "event" | "datasetVersion" | "webhook" }
+      >
+      readonly correlationId: string
+      readonly requestedBy?: CreateExecutionInput["requestedBy"]
+    }
+
+/** Build an immutable primitive execution from its parent execution or automatic trigger. */
+export function createPrimitiveExecutionRecord(input: {
+  readonly id: string
+  readonly primitive: TrustedPrimitiveRef
+  readonly origin: PrimitiveExecutionOrigin
+}): CreateExecutionInput {
+  const provenance =
+    input.origin.type === "execution"
+      ? {
+          projectId: input.origin.parent.projectId,
+          ...(input.origin.parent.requestedBy === undefined
+            ? {}
+            : { requestedBy: structuredClone(input.origin.parent.requestedBy) }),
+          source: { type: "execution" as const, executionId: input.origin.parent.id },
+          correlationId: input.origin.parent.correlationId,
+        }
+      : {
+          projectId: input.origin.projectId,
+          ...(input.origin.requestedBy === undefined
+            ? {}
+            : { requestedBy: structuredClone(input.origin.requestedBy) }),
+          source: structuredClone(input.origin.source),
+          correlationId: input.origin.correlationId,
+        }
+
+  return {
+    id: input.id,
+    ...provenance,
+    executor: {
+      type: "primitive",
+      kind: input.primitive.kind,
+      runId: input.primitive.runId,
+    },
+    authorizationRef: {
+      type: "trustedPrimitive",
+      primitive: structuredClone(input.primitive),
+    },
+  }
+}
+
+/** Restore the trusted scope of a provider-validated primitive execution record. */
+export function restoreTrustedPrimitiveExecutionScope(input: {
+  readonly execution: ExecutionRecord
+  readonly primitive: TrustedPrimitiveRef
+}): ExecutionScope {
+  assertPrimitiveExecution(input.execution, input.primitive)
+  const context: ExecutionContext = Object.freeze({
+    id: input.execution.id,
+    projectId: input.execution.projectId,
+    ...(input.execution.requestedBy === undefined
+      ? {}
+      : { requestedBy: Object.freeze(structuredClone(input.execution.requestedBy)) }),
+    executor: Object.freeze({ type: "primitive", ...structuredClone(input.primitive) }),
+    source: Object.freeze(structuredClone(input.execution.source)),
+    correlationId: input.execution.correlationId,
+  })
+  return Object.freeze({
+    execution: context,
+    authorization: createTrustedPrimitiveRuntimeAuthorization({
+      projectId: input.execution.projectId,
+      primitive: input.primitive,
+    }),
+  })
+}
+
+function durableExecutor(execution: ExecutionContext): CreateExecutionInput["executor"] {
+  switch (execution.executor.type) {
+    case "request":
+      return { type: "request", requestId: execution.executor.requestId }
+    case "primitive":
+      return {
+        type: "primitive",
+        kind: execution.executor.kind,
+        runId: execution.executor.runId,
+      }
+    case "agent":
+      return { type: "agent", runId: execution.executor.runId }
+    case "kernel":
+      return { type: "kernel", operation: structuredClone(execution.executor.operation) }
+  }
+}
+
+function assertExecutionRecordMatches(
+  existing: ExecutionRecord,
+  input: CreateExecutionInput
+): void {
+  const { createdAt: _createdAt, ...stored } = existing
+  if (!isDeepStrictEqual(stored, input)) {
+    throw new ExecutionStorageError(
+      "duplicate_execution",
+      `[Sixb] Execution '${input.id}' already exists with different immutable provenance.`
+    )
+  }
+}
+
+function assertPrimitiveExecution(
+  execution: ExecutionRecord,
+  primitive: TrustedPrimitiveRef
+): void {
+  const authority = execution.authorizationRef
+  if (
+    execution.executor.type !== "primitive" ||
+    execution.executor.kind !== primitive.kind ||
+    execution.executor.runId !== primitive.runId ||
+    authority.type !== "trustedPrimitive" ||
+    authority.primitive.kind !== primitive.kind ||
+    authority.primitive.id !== primitive.id ||
+    authority.primitive.runId !== primitive.runId
+  ) {
+    throw new ExecutionStorageError(
+      "invalid_input",
+      `[Sixb] Execution '${execution.id}' does not authorize ${primitive.kind} run '${primitive.runId}'.`
+    )
+  }
+}

package/src/execution/index.ts

@@ -0,0 +1,12 @@
+export type {
+  AuthorizablePrincipal,
+  AuthorizationRef,
+  ExecutionContext,
+  ExecutionExecutor,
+  ExecutionScope,
+  ExecutionSource,
+  KernelOperation,
+  RuntimeAuthorization,
+  TrustedPrimitiveKind,
+  TrustedPrimitiveRef,
+} from "./types"

package/src/execution/primitive.ts

@@ -0,0 +1,50 @@
+import type { OntologySource } from "../ontology"
+import type { OntologyMutationRuntime } from "../runtime/ontology-mutations"
+import { getOntologyMutationRuntime } from "../runtime/ontology-mutations"
+import { isBoundSixb, type Sixb } from "../runtime/sixb"
+import type { ExecutionRecord } from "../storage/executions"
+import { restoreTrustedPrimitiveExecutionScope } from "./durable"
+import type { ExecutionScope, TrustedPrimitiveRef } from "./types"
+
+/** Minimal host boundary required by trusted primitive workers. */
+export interface PrimitiveExecutionHost {
+  readonly id: string
+  withScope(scope: ExecutionScope): object
+}
+
+export interface BoundPrimitiveExecution {
+  readonly sixb: Sixb<readonly OntologySource[]>
+  /** Internal mutation port guarded by the same runtime authority as `sixb`. */
+  readonly ontologyMutations: OntologyMutationRuntime
+}
+
+/** Bind a worker to the immutable execution already owned by its durable primitive run. */
+export function bindDurablePrimitiveExecution(
+  host: PrimitiveExecutionHost,
+  input: {
+    readonly execution: ExecutionRecord
+    readonly primitive: TrustedPrimitiveRef
+  }
+): BoundPrimitiveExecution {
+  return bindPrimitiveScope(host, restoreTrustedPrimitiveExecutionScope(input))
+}
+
+function bindPrimitiveScope(
+  host: PrimitiveExecutionHost,
+  scope: ExecutionScope
+): BoundPrimitiveExecution {
+  let ontologyMutations: OntologyMutationRuntime | undefined
+
+  const sixb = host.withScope(scope)
+  if (!isBoundSixb(sixb)) {
+    throw new Error("[Sixb] Primitive execution host returned an invalid bound SDK.")
+  }
+  const bound: BoundPrimitiveExecution = {
+    sixb,
+    get ontologyMutations() {
+      ontologyMutations ??= getOntologyMutationRuntime(sixb)
+      return ontologyMutations
+    },
+  }
+  return Object.freeze(bound)
+}