@sixb/core 0.1.1 → 0.1.2

package/src/execution/request.ts

@@ -0,0 +1,109 @@
+import { randomUUID } from "node:crypto"
+import type { AuthorizationContext } from "../authorization"
+import type { OntologySource } from "../ontology"
+import { isBoundSixb, type Sixb } from "../runtime/sixb"
+import { createDisabledRequestScope, createPrincipalRequestScope } from "./scopes"
+import type { AuthorizationRef, ExecutionScope } from "./types"
+
+export type { ActionRunsRuntime, ActionsRuntime } from "../actions/execution"
+export type {
+  AgentRunListResult,
+  AgentRunsRuntime,
+  AgentRunView,
+  AgentsRuntime,
+  AgentThreadsRuntime,
+  CreateExecutionAgentThreadInput,
+  ExecutionAgentRequestInput,
+  ListExecutionAgentThreadsInput,
+} from "../agents/execution"
+export type { AuthorizationContext } from "../authorization"
+export type { DatasetsRuntime } from "../datasets/execution"
+export type { EventsRuntime } from "../events/execution"
+export type { LogsRuntime } from "../logging/execution"
+export type {
+  ExecutionObjectByIdHandle,
+  ExecutionObjectSet,
+  ObjectsRuntime,
+} from "../objects/execution"
+export type {
+  PipelineRunsRuntime,
+  PipelinesRuntime,
+} from "../pipelines/execution"
+export type {
+  ProjectionRunsRuntime,
+  ProjectionsRuntime,
+} from "../projections/execution"
+export type { RuleStatesRuntime, RulesRuntime } from "../rules/execution"
+export type { Sixb } from "../runtime/sixb"
+export type { SyncRunsRuntime, SyncsRuntime } from "../syncs/execution"
+export type {
+  LatestWorkflowRunListResult,
+  ListWorkflowRunNodesInput,
+  WorkflowAgentNodeRunView,
+  WorkflowInterventionsRuntime,
+  WorkflowNodeRunListResult,
+  WorkflowNodeRunView,
+  WorkflowRunListResult,
+  WorkflowRunsRuntime,
+  WorkflowRunView,
+  WorkflowsRuntime,
+} from "../workflows/execution"
+export type { AuthorizationRef, ExecutionContext } from "./types"
+
+export type RequestExecutionAuthorization =
+  | {
+      readonly type: "principal"
+      readonly context: AuthorizationContext
+      readonly credential?: Extract<AuthorizationRef, { readonly type: "principal" }>["credential"]
+    }
+  | { readonly type: "disabled" }
+
+export interface BindRequestExecutionInput {
+  readonly request: Request
+  readonly authorization: RequestExecutionAuthorization
+}
+
+export interface RequestExecutionHost {
+  readonly id: string
+  withScope(scope: ExecutionScope): object
+}
+
+/** Bind one HTTP or WebSocket request without exposing trusted or kernel capability factories. */
+export function bindRequestExecution(
+  host: RequestExecutionHost,
+  input: BindRequestExecutionInput
+): Sixb<readonly OntologySource[]> {
+  const requestId = requestIdentifier(input.request)
+  const correlationId = correlationIdentifier(input.request, requestId)
+  const scope =
+    input.authorization.type === "principal"
+      ? createPrincipalRequestScope({
+          projectId: host.id,
+          requestId,
+          correlationId,
+          context: input.authorization.context,
+          ...(input.authorization.credential === undefined
+            ? {}
+            : { credential: input.authorization.credential }),
+        })
+      : createDisabledRequestScope({ projectId: host.id, requestId, correlationId })
+
+  const sixb = host.withScope(scope)
+  if (!isBoundSixb(sixb)) {
+    throw new Error("[Sixb] Request host did not return an execution-bound Sixb SDK.")
+  }
+  return sixb
+}
+
+function requestIdentifier(request: Request): string {
+  return headerIdentifier(request, "x-request-id") ?? `req_${randomUUID()}`
+}
+
+function correlationIdentifier(request: Request, requestId: string): string {
+  return headerIdentifier(request, "x-correlation-id") ?? requestId
+}
+
+function headerIdentifier(request: Request, name: string): string | undefined {
+  const value = request.headers.get(name)?.trim()
+  return value ? value : undefined
+}

package/src/execution/scopes.ts

@@ -0,0 +1,198 @@
+import { randomUUID } from "node:crypto"
+import type { AuthorizationContext } from "../authorization"
+import {
+  createDisabledRuntimeAuthorization,
+  createKernelRuntimeAuthorization,
+  createPrincipalRuntimeAuthorization,
+} from "./authorization"
+import type {
+  AuthorizablePrincipal,
+  AuthorizationRef,
+  ExecutionContext,
+  ExecutionScope,
+  ExecutionSource,
+  KernelOperation,
+} from "./types"
+
+export function createPrincipalRequestScope(input: {
+  readonly projectId: string
+  readonly requestId: string
+  readonly correlationId: string
+  readonly context: AuthorizationContext
+  readonly credential?: Extract<AuthorizationRef, { readonly type: "principal" }>["credential"]
+}): ExecutionScope {
+  const execution = createRequestExecution({
+    projectId: input.projectId,
+    requestId: input.requestId,
+    correlationId: input.correlationId,
+    requestedBy: asAuthorizablePrincipal(input.context.principal),
+  })
+
+  return Object.freeze({
+    execution,
+    authorization: createPrincipalRuntimeAuthorization({
+      projectId: input.projectId,
+      context: input.context,
+      ...(input.credential === undefined ? {} : { credential: input.credential }),
+    }),
+  })
+}
+
+export function createDisabledRequestScope(input: {
+  readonly projectId: string
+  readonly requestId: string
+  readonly correlationId: string
+}): ExecutionScope {
+  return Object.freeze({
+    execution: createRequestExecution(input),
+    authorization: createDisabledRuntimeAuthorization(input.projectId),
+  })
+}
+
+export function createKernelScope(input: {
+  readonly projectId: string
+  readonly operation: KernelOperation
+  readonly source: ExecutionSource
+  readonly correlationId?: string
+}): ExecutionScope {
+  const operation = Object.freeze({ ...input.operation })
+  const execution = createKernelExecution({
+    projectId: input.projectId,
+    operation,
+    source: input.source,
+    correlationId: input.correlationId,
+  })
+  return Object.freeze({
+    execution,
+    authorization: createKernelRuntimeAuthorization({ projectId: input.projectId, operation }),
+  })
+}
+
+function createKernelExecution(input: {
+  readonly projectId: string
+  readonly operation: KernelOperation
+  readonly source: ExecutionSource
+  readonly correlationId?: string
+}): ExecutionContext {
+  const source = snapshotExecutionSource(input.source)
+  assertNestedProvenance(source, input.correlationId)
+  return freezeExecution({
+    id: `exec_${randomUUID()}`,
+    projectId: input.projectId,
+    executor: Object.freeze({ type: "kernel", operation: input.operation }),
+    source,
+    correlationId: input.correlationId ?? `corr_${randomUUID()}`,
+  })
+}
+
+function assertNestedProvenance(source: ExecutionSource, correlationId: string | undefined): void {
+  if (source.type === "execution" && correlationId === undefined) {
+    throw new Error("[Sixb] Nested execution must preserve its parent correlation id.")
+  }
+}
+
+export function createTestingScope(input: {
+  readonly projectId: string
+  readonly context?: AuthorizationContext
+  readonly executionId?: string
+  readonly requestId?: string
+  readonly correlationId?: string
+}): ExecutionScope {
+  const context = input.context ? withoutSession(input.context) : undefined
+  const requestId = input.requestId ?? `test_request_${randomUUID()}`
+  const execution = createRequestExecution({
+    projectId: input.projectId,
+    requestId,
+    correlationId: input.correlationId ?? `test_correlation_${randomUUID()}`,
+    ...(context === undefined ? {} : { requestedBy: asAuthorizablePrincipal(context.principal) }),
+    executionId: input.executionId,
+  })
+  return Object.freeze({
+    execution,
+    authorization: context
+      ? createPrincipalRuntimeAuthorization({ projectId: input.projectId, context })
+      : createDisabledRuntimeAuthorization(input.projectId),
+  })
+}
+
+function withoutSession(context: AuthorizationContext): AuthorizationContext {
+  return {
+    principal: context.principal,
+    groupIds: context.groupIds,
+    roleIds: context.roleIds,
+    grants: context.grants,
+  }
+}
+
+function createRequestExecution(input: {
+  readonly projectId: string
+  readonly requestId: string
+  readonly correlationId: string
+  readonly requestedBy?: AuthorizablePrincipal
+  readonly executionId?: string
+}): ExecutionContext {
+  assertNonEmpty(input.projectId, "Execution project id")
+  assertNonEmpty(input.requestId, "Execution request id")
+  assertNonEmpty(input.correlationId, "Execution correlation id")
+  const id = input.executionId ?? `exec_${randomUUID()}`
+  assertNonEmpty(id, "Execution id")
+  return freezeExecution({
+    id,
+    projectId: input.projectId,
+    ...(input.requestedBy === undefined ? {} : { requestedBy: input.requestedBy }),
+    executor: Object.freeze({ type: "request", requestId: input.requestId }),
+    source: Object.freeze({ type: "http", requestId: input.requestId }),
+    correlationId: input.correlationId,
+  })
+}
+
+function freezeExecution(execution: ExecutionContext): ExecutionContext {
+  assertNonEmpty(execution.id, "Execution id")
+  assertNonEmpty(execution.projectId, "Execution project id")
+  assertNonEmpty(execution.correlationId, "Execution correlation id")
+  return Object.freeze(execution)
+}
+
+function snapshotExecutionSource(source: ExecutionSource): ExecutionSource {
+  const field = sourceIdentifier(source)
+  assertNonEmpty(field.value, field.label)
+  if (source.type === "datasetVersion") {
+    assertNonEmpty(source.datasetId, "Execution source dataset id")
+  }
+  return Object.freeze({ ...source })
+}
+
+function sourceIdentifier(source: ExecutionSource): {
+  readonly label: string
+  readonly value: string
+} {
+  switch (source.type) {
+    case "http":
+      return { label: "Execution source request id", value: source.requestId }
+    case "webhook":
+      return { label: "Execution source delivery id", value: source.deliveryId }
+    case "schedule":
+    case "event":
+      return { label: "Execution source event id", value: source.eventId }
+    case "datasetVersion":
+      return { label: "Execution source dataset version id", value: source.versionId }
+    case "execution":
+      return { label: "Execution source execution id", value: source.executionId }
+  }
+}
+
+function asAuthorizablePrincipal(
+  principal: AuthorizationContext["principal"]
+): AuthorizablePrincipal {
+  if (principal.type !== "user" && principal.type !== "serviceAccount") {
+    throw new Error(`[Sixb] Principal type '${principal.type}' cannot hold runtime authorization.`)
+  }
+  assertNonEmpty(principal.id, "Execution principal id")
+  return Object.freeze({ type: principal.type, id: principal.id })
+}
+
+function assertNonEmpty(value: string, label: string): void {
+  if (!value.trim()) {
+    throw new Error(`[Sixb] ${label} must not be empty.`)
+  }
+}

package/src/execution/types.ts

@@ -0,0 +1,113 @@
+import type { Principal } from "../auth/types"
+
+/** User or service account that may initiate or authorize an execution. */
+export type AuthorizablePrincipal = Extract<Principal, { readonly type: "user" | "serviceAccount" }>
+
+/** Registered primitive kinds that may receive internal trusted authority. */
+export type TrustedPrimitiveKind =
+  | "action"
+  | "pipeline"
+  | "projection"
+  | "rule"
+  | "sync"
+  | "webhook"
+  | "workflow"
+
+export interface TrustedPrimitiveRef {
+  readonly kind: TrustedPrimitiveKind
+  readonly id: string
+  readonly runId: string
+}
+
+export type KernelOperation = {
+  readonly type: "ontology.recover"
+  readonly recoveryId: string
+}
+
+/** Workload currently executing. This is provenance and never grants authority by itself. */
+export type ExecutionExecutor =
+  | { readonly type: "request"; readonly requestId: string }
+  | {
+      readonly type: "primitive"
+      readonly kind: TrustedPrimitiveKind
+      readonly id: string
+      readonly runId: string
+    }
+  | { readonly type: "agent"; readonly agentId: string; readonly runId: string }
+  | { readonly type: "kernel"; readonly operation: KernelOperation }
+
+/**
+ * Occurrence that directly triggered an execution.
+ *
+ * An `execution` source is the single logical parent of a nested execution.
+ */
+export type ExecutionSource =
+  | { 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 provenance for one request, primitive run, agent run, or kernel operation. */
+export interface ExecutionContext {
+  readonly id: string
+  readonly projectId: string
+  readonly requestedBy?: AuthorizablePrincipal
+  readonly executor: ExecutionExecutor
+  readonly source: ExecutionSource
+  readonly correlationId: string
+}
+
+/** Durable descriptor used to rebuild authority. A reference is never authoritative by itself. */
+export type AuthorizationRef =
+  | {
+      readonly type: "principal"
+      readonly principal: AuthorizablePrincipal
+      readonly credential?:
+        | { readonly type: "session"; readonly id: string }
+        | { readonly type: "accessToken"; readonly id: string }
+    }
+  | { readonly type: "trustedPrimitive"; readonly primitive: TrustedPrimitiveRef }
+  | { readonly type: "kernel"; readonly operation: KernelOperation }
+  | { readonly type: "disabled" }
+
+class RuntimeAuthorizationCapability {
+  readonly #runtimeAuthorization = true
+
+  private constructor() {}
+
+  static create(): RuntimeAuthorizationCapability {
+    const capability = new RuntimeAuthorizationCapability()
+    Object.freeze(capability)
+    return capability
+  }
+
+  static is(value: unknown): value is RuntimeAuthorizationCapability {
+    return typeof value === "object" && value !== null && #runtimeAuthorization in value
+  }
+}
+
+/**
+ * Opaque, process-local authority.
+ *
+ * The private class makes it nominal in TypeScript; Core registry membership makes it authoritative
+ * at runtime. The capability itself is never persisted.
+ */
+export type RuntimeAuthorization = RuntimeAuthorizationCapability
+
+/** Execution provenance paired with the process-local authority that permits its operations. */
+export interface ExecutionScope {
+  readonly execution: ExecutionContext
+  readonly authorization: RuntimeAuthorization
+}
+
+/** Internal constructor; the package root exports only the opaque type. */
+export function createRuntimeAuthorizationCapability(): RuntimeAuthorization {
+  return RuntimeAuthorizationCapability.create()
+}
+
+/** Internal runtime guard; registry membership remains the source of authority. */
+export function isRuntimeAuthorizationCapability(value: unknown): value is RuntimeAuthorization {
+  return RuntimeAuthorizationCapability.is(value)
+}

package/src/http/api-routes.ts

@@ -166,10 +166,10 @@ export const SIXB_API_ROUTES: readonly SixbApiRoute[] = [
     accessToken: true,
     agentApi: true,
   },
-  // The four write routes. Bearer-capable because they now enforce scoped authorization
-  // (`edit:object` / `append:telemetry`), which is exactly the precondition this table's rule states.
+  // The four write routes. Bearer-capable because their execution facade enforces authorization
+  // (`edit:object` / `append:telemetry`), which is exactly the precondition this table requires.
   // NOT agent-proxied: letting an agent turn write objects on its own is a separate decision, and
-  // the gateway already hands routes a scoped runtime, so flipping `agentApi` later needs no
+  // the gateway already hands routes an execution SDK, so flipping `agentApi` later needs no
   // authorization work — only that decision.
   {
     operationId: "upsertObject",

package/src/index.ts

@@ -24,6 +24,7 @@ export type {
   ObjectTypeWithPropertyTokens,
   ObjectTypeWithTokens,
   Ontology,
+  OntologyDefinitionCatalog,
   OntologyRegistryOptions,
   PrimitiveSchema,
   Property,
@@ -60,6 +61,7 @@ export type {
   ActionBlobContext,
   ActionBuilder,
   ActionDefinition,
+  ActionDefinitionCatalog,
   ActionEditsContext,
   ActionEditsHandler,
   ActionEffectsContext,
@@ -331,6 +333,7 @@ export type {
   LogFields,
   Logger,
   LoggerProvider,
+  LoggingService,
   LogLevel,
   LogRecord,
   LogRunRef,
@@ -436,6 +439,7 @@ export type {
   GrantDefinition,
   GroupDefinition,
   GroupReference,
+  ManageGrant,
   MembershipOperation,
   MembershipPolicyDefinition,
   ObserveGrant,
@@ -444,7 +448,7 @@ export type {
   RoleDefinition,
   RunGrant,
   RunGrantTarget,
-  SecurityRegistry,
+  SecurityDefinitionCatalog,
   Selection,
   ViewGrant,
   ViewGrantTarget,
@@ -464,6 +468,12 @@ export {
 // The full storage-provider contract lives at `@sixb/core/storage`.
 
 export type {
+  CreateExecutionInput,
+  DurableExecutionExecutor,
+  DurableExecutionSource,
+  ExecutionRecord,
+  ExecutionStorage,
+  InMemoryStorageOptions,
   MigrationCapableStorage,
   MigrationReport,
   // `status()` returns these, so reading a migrator from here needs them; without them
@@ -588,12 +598,30 @@ export {
 // ── Connectors ─────────────────────────────────────────────
 
 export type {
+  AnyConnectorAdapter,
+  ConnectorAccessToken,
+  ConnectorAccountCandidate,
   ConnectorAdapter,
   ConnectorClient,
+  ConnectorConnectionClientContext,
+  ConnectorConnectionMetadata,
+  ConnectorConnectionOptions,
+  ConnectorConnectionOwner,
+  ConnectorConnectionSelector,
   ConnectorContext,
   ConnectorDefinition,
+  ConnectorOAuth2Authentication,
+  ConnectorOAuthCredentials,
+  ConnectorOAuthErrorKind,
+  ConnectorTokenSource,
+  OAuthConnectorAdapter,
+  OAuthConnectorAuthorizationContext,
+  OAuthConnectorAuthorizationUrlInput,
+  OAuthConnectorCodeExchangeInput,
+  ProjectConnectorConnectionOwner,
+  StaticConnectorDefinition,
 } from "./connectors"
-export { defineConnector } from "./connectors"
+export { ConnectorOAuthError, defineConnector } from "./connectors"
 
 // ── Webhooks ───────────────────────────────────────────────
 
@@ -631,6 +659,7 @@ export type {
   DatasetSyncTarget,
   RequestSyncRunInput,
   SyncBuilder,
+  SyncConnectorConnection,
   SyncDefinition,
   SyncMode,
   SyncReadBuilder,
@@ -749,6 +778,7 @@ export type {
   WorkflowRunRequestOptions,
   WorkflowRunRequestResult,
   WorkflowRunSource,
+  WorkflowRuntimeFacade,
   WorkflowScheduleMapper,
   WorkflowScheduleTriggerDefinition,
   WorkflowStepMapper,
@@ -770,16 +800,49 @@ export {
   WorkflowValidationError,
 } from "./workflows"
 
+// ── Execution ───────────────────────────────────────────────
+
+export type {
+  AuthorizablePrincipal,
+  AuthorizationRef,
+  ExecutionContext,
+  ExecutionExecutor,
+  ExecutionScope,
+  ExecutionSource,
+  KernelOperation,
+  RuntimeAuthorization,
+  TrustedPrimitiveKind,
+  TrustedPrimitiveRef,
+} from "./execution"
+
 // ── Runtime ─────────────────────────────────────────────────
 
+export type { ActionRunsRuntime, ActionsRuntime } from "./actions/execution"
 export type {
+  AgentRunListResult,
+  AgentRunsRuntime,
+  AgentRunView,
+  AgentsRuntime,
+  AgentThreadsRuntime,
+  ExecutionAgentRunResult,
+} from "./agents/execution"
+export type { BlobsRuntime } from "./blob-storage/execution"
+export type { ConnectorRuntime } from "./connectors/execution"
+export type { DatasetsRuntime } from "./datasets/execution"
+export type {
+  SixbActionPhaseFailedContext,
   SixbErrorContext,
   SixbErrorHandler,
   SixbEventDeliveryFailedContext,
   SixbFailedRun,
   SixbRuleEvaluationFailedContext,
   SixbRunFailedContext,
+  SixbRunFailureByKind,
+  SixbRunIdentityByKind,
 } from "./error-reporting/types"
+export type { SixbErrorCode, SixbFailure } from "./errors/types"
+export type { EventsRuntime } from "./events/execution"
+export type { LogsRuntime } from "./logging/execution"
 export type {
   OntologyMaintenanceCleanupSnapshot,
   OntologyMaintenanceHandle,
@@ -788,9 +851,21 @@ export type {
   OntologyOperationalStatus,
   SixbReadiness,
 } from "./maintenance"
+export type {
+  ExecutionObjectByIdHandle,
+  ExecutionObjectSet,
+  ObjectsRuntime,
+} from "./objects/execution"
+export type { PipelineRunsRuntime, PipelinesRuntime } from "./pipelines/execution"
+export type {
+  ProjectionRunsRuntime,
+  ProjectionsRuntime,
+} from "./projections/execution"
+export type { RuleStatesRuntime, RulesRuntime } from "./rules/execution"
 export type {
   BatchItemResult,
   CreateSixbOptions,
+  DefinitionCatalog,
   ListResult,
   ListResultWithoutTotal,
   ObjectByIdHandle,
@@ -812,12 +887,11 @@ export type {
   OntologySource,
   RegisteredObjectType,
   RegisteredValueTypes,
-  ScopedObjectByIdHandle,
-  ScopedObjectSet,
-  ScopedSixb,
-  SixbInstance,
-  SixbOptions,
-  SixbRuntimeContext,
+  SchedulerController,
+  Sixb,
+  SixbDefinitions,
+  SixbHostOptions,
+  SixbHostView,
   TelemetryAppendInput,
   TelemetryChannel,
   TelemetryHistoryInput,
@@ -834,9 +908,34 @@ export {
   OntologyValidationError,
   ProjectionValidationError,
   RuntimeError,
-  Sixb,
+  SixbHost,
   SyncValidationError,
 } from "./runtime"
+export type { SchedulesRuntime } from "./schedules/execution"
+export type {
+  ActionRunFailure,
+  ActionRunFailureCode,
+  ActionRunPhase,
+  AgentRunFailureCode,
+  PipelineRunFailureCode,
+  ProjectionRunFailureCode,
+  SyncRunFailureCode,
+  WebhookRunFailureCode,
+  WorkflowRunFailureCode,
+} from "./storage"
+export type { SyncRunsRuntime, SyncsRuntime } from "./syncs/execution"
+export type {
+  LatestWorkflowRunListResult,
+  ListWorkflowRunNodesInput,
+  WorkflowAgentNodeRunView,
+  WorkflowInterventionsRuntime,
+  WorkflowNodeRunListResult,
+  WorkflowNodeRunView,
+  WorkflowRunListResult,
+  WorkflowRunsRuntime,
+  WorkflowRunView,
+  WorkflowsRuntime,
+} from "./workflows/execution"
 
 // ── Agents ──────────────────────────────────────────────────
 
@@ -918,6 +1017,7 @@ export type {
   ObjectProjectionDefinition,
   ObjectProjectionTarget,
   ProjectionDefinition,
+  ProjectionDefinitionCatalog,
   ProjectionTarget,
   ProjectionTargetByKind,
   TelemetryProjectionDefinition,

package/src/json.ts

@@ -26,10 +26,6 @@ export function cloneJsonValue(value: ReadonlyJsonValue, label = "value"): JsonV
   return JSON.parse(JSON.stringify(value)) as JsonValue
 }
 
-export function jsonValuesEqual(left: unknown, right: unknown): boolean {
-  return stableJsonStringify(left) === stableJsonStringify(right)
-}
-
 export function stableJsonStringify(value: unknown): string {
   if (value === undefined) return "undefined"
   if (value === null || typeof value !== "object") return JSON.stringify(value)