@sixb/core 0.1.0 → 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

@@ -159,10 +159,17 @@ 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.
+  {
+    operationId: "listObjectLinks",
+    method: "GET",
+    path: "/api/objects/:objectTypeId/:objectId/links",
+    accessToken: true,
+    agentApi: true,
+  },
+  // 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",
@@ -252,6 +259,20 @@ export const SIXB_API_ROUTES: readonly SixbApiRoute[] = [
     accessToken: true,
     agentApi: true,
   },
+  {
+    operationId: "uploadFileRaw",
+    method: "POST",
+    path: "/api/files",
+    accessToken: true,
+    agentApi: true,
+  },
+  {
+    operationId: "listActionRuns",
+    method: "GET",
+    path: "/api/action-runs",
+    accessToken: true,
+    agentApi: true,
+  },
   {
     operationId: "getActionRun",
     method: "GET",
@@ -278,21 +299,35 @@ export const SIXB_API_ROUTES: readonly SixbApiRoute[] = [
     method: "GET",
     path: "/api/workflows",
     accessToken: true,
-    agentApi: false,
+    agentApi: true,
   },
   {
     operationId: "getWorkflow",
     method: "GET",
     path: "/api/workflows/:workflowId",
     accessToken: true,
-    agentApi: false,
+    agentApi: true,
   },
   {
     operationId: "requestWorkflowRun",
     method: "POST",
     path: "/api/workflows/:workflowId/runs",
     accessToken: true,
-    agentApi: false,
+    agentApi: true,
+  },
+  {
+    operationId: "listWorkflowRuns",
+    method: "GET",
+    path: "/api/workflow-runs",
+    accessToken: true,
+    agentApi: true,
+  },
+  {
+    operationId: "getWorkflowRun",
+    method: "GET",
+    path: "/api/workflow-runs/:runId",
+    accessToken: true,
+    agentApi: true,
   },
   {
     operationId: "cancelWorkflowRun",
@@ -313,7 +348,7 @@ export const SIXB_API_ROUTES: readonly SixbApiRoute[] = [
     method: "GET",
     path: "/api/workflow-runs/:runId/files/content",
     accessToken: true,
-    agentApi: false,
+    agentApi: true,
   },
   {
     operationId: "headWorkflowRunFileContent",