@sixb/core 0.1.0 → 0.1.2

package/src/events/{runtime.ts → service.ts}

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto"
 import type { Broker, BrokerCursor, BrokerRecord, BrokerStreamDefinition } from "../broker"
-import { reportEventDeliveryFailure } from "../error-reporting/capability"
+import { type ErrorReporter, SixbErrorReporter } from "../error-reporting/reporter"
+import { reportEventDeliveryFailure } from "../error-reporting/reports"
 import { getInvalidJsonValueReason, type JsonValue } from "../json"
 import type { OntologyMaterializationEvent } from "../materialization/events"
 import {
@@ -27,15 +28,12 @@ export const EVENTS_STREAM: BrokerStreamDefinition = {
   retention: { maxAgeMs: DEFAULT_EVENTS_RETENTION_MS },
 }
 
-export interface EventsRuntimeOptions {
+export interface DomainEventServiceOptions {
   readonly projectId: string
   readonly broker: Broker
   readonly stream?: BrokerStreamDefinition
-  /**
-   * The `Sixb` instance — or anything sharing its error reporter — that owns this runtime. Only `emit`
-   * needs it, to escalate a lost batch. Absent means a lost batch is logged and nothing more.
-   */
-  readonly host?: object
+  /** Internal failure reporter. Defaults to the console when this runtime is used standalone. */
+  readonly errorReporter?: ErrorReporter
 }
 
 export interface EventsAppendInput {
@@ -46,7 +44,7 @@ export interface EventsAppendInput {
 }
 
 export interface EventsEmitOptions {
-  /** Package prefix for the console line, such as `SixbPipelineWorker`. */
+  /** Framework component that initiated the emission, such as `SixbPipelineWorker`. */
   readonly source: string
 }
 
@@ -90,19 +88,19 @@ export interface StableEventPublisher {
   publishEnvelopes(envelopes: readonly StableEventEnvelope[]): Promise<readonly StoredDomainEvent[]>
 }
 
-/** Project-scoped domain event runtime backed by the shared broker provider. */
-export class EventsRuntime implements DomainEventLog, StableEventPublisher {
+/** Project-scoped domain event service backed by the shared broker provider. */
+export class DomainEventService implements DomainEventLog, StableEventPublisher {
   private readonly projectId: string
   private readonly broker: Broker
   private readonly stream: BrokerStreamDefinition
-  private readonly host: object | undefined
+  private readonly errorReporter: ErrorReporter
   private readonly ensureStreamPromises = new Map<string, Promise<void>>()
 
-  constructor(options: EventsRuntimeOptions) {
+  constructor(options: DomainEventServiceOptions) {
     this.projectId = options.projectId
     this.broker = options.broker
     this.stream = options.stream ?? EVENTS_STREAM
-    this.host = options.host
+    this.errorReporter = options.errorReporter ?? new SixbErrorReporter()
   }
 
   /**
@@ -112,29 +110,23 @@ export class EventsRuntime implements DomainEventLog, StableEventPublisher {
    * turn a successful run into a failed one. It is not a swallow either — every event Sixb publishes is
    * a potential trigger edge (a rule's `.when()`, an event schedule, a workflow's wait node), so a lost
    * batch is a handler that silently never runs. The loss is escalated to `onError` as
-   * `event.delivery.failed`; the console line is there for local debugging.
+   * `event.delivery.failed`, or to the default console reporter when no handler was configured.
    *
    * Framework emit sites want this. Application code wants `append`, which reports failure to the
    * caller and returns the stored envelopes.
    */
-  async emit(input: EventsAppendInput, options: EventsEmitOptions): Promise<void> {
+  async emit(input: EventsAppendInput, _options: EventsEmitOptions): Promise<void> {
     try {
       await this.append(input)
     } catch (error) {
       try {
         const eventTypes = input.events.map((event) => event.type)
-        // Escalate before logging. `console` is replaceable and `onError` is the contract, so a
-        // replacement that throws must not be what loses the report.
-        reportEventDeliveryFailure(this.host, error, {
+        reportEventDeliveryFailure(this.errorReporter, error, {
           projectId: this.projectId,
           eventTypes,
         })
-        console.error(`[${options.source}] Failed to emit ${eventTypes.join(", ")}:`, error)
       } catch {
-        // The contract above is absolute, so escalation cannot be the thing that breaks it: a replaced
-        // `console` that throws would turn a run that already succeeded into a failed one. The loss is
-        // already unreported at this point — rejecting on top of it helps nobody. `SixbErrorReporter`
-        // guards its own console line the same way.
+        // The contract above is absolute, so escalation cannot be the thing that breaks it.
       }
     }
   }
@@ -306,6 +298,10 @@ export class EventsRuntime implements DomainEventLog, StableEventPublisher {
   }
 }
 
+export function createDomainEventService(options: DomainEventServiceOptions): DomainEventService {
+  return new DomainEventService(options)
+}
+
 type StoredEventPayload = Omit<StoredAuthorableEvent, "cursor">
 
 function toStoredEventPayload(params: {

package/src/events/types/pipelines.ts

@@ -1,3 +1,5 @@
+import type { SixbFailure } from "../../errors/types"
+import type { PipelineRunFailureCode } from "../../storage/pipeline-runs/types"
 import type { EventEnvelope } from "../envelope"
 
 export interface PipelineRunStartedEvent extends EventEnvelope {
@@ -43,7 +45,7 @@ export interface PipelineRunStepFinishedEvent extends EventEnvelope {
     finishedAt: string
     versionId?: string
     rowsWritten?: number
-    error?: string
+    error?: SixbFailure<PipelineRunFailureCode>
   }
 }
 
@@ -57,6 +59,7 @@ export interface PipelineRunFinishedEvent extends EventEnvelope {
     status: "succeeded" | "failed" | "cancelled"
     datasetId?: string
     versionId?: string
+    error?: SixbFailure<PipelineRunFailureCode>
   }
 }
 

package/src/events/types/syncs.ts

@@ -1,3 +1,5 @@
+import type { SixbFailure } from "../../errors/types"
+import type { SyncRunFailureCode } from "../../storage/sync-runs/types"
 import type { EventEnvelope } from "../envelope"
 
 export interface SyncRunStartedEvent extends EventEnvelope {
@@ -21,6 +23,7 @@ export interface SyncRunFinishedEvent extends EventEnvelope {
     status: "succeeded" | "failed" | "cancelled"
     datasetId?: string
     versionId?: string
+    error?: SixbFailure<SyncRunFailureCode>
   }
 }
 

package/src/events/types/workflows.ts

@@ -1,3 +1,5 @@
+import type { SixbFailure } from "../../errors/types"
+import type { WorkflowRunFailureCode } from "../../storage/workflow-runs/types"
 import type { WorkflowRunSource } from "../../workflows/types"
 import type { EventEnvelope } from "../envelope"
 
@@ -85,7 +87,7 @@ export interface WorkflowRunNodeFinishedEvent extends EventEnvelope {
     nodeKey: string
     status: "succeeded" | "failed" | "cancelled"
     finishedAt: string
-    error?: string
+    error?: SixbFailure<WorkflowRunFailureCode>
   }
 }
 
@@ -98,7 +100,7 @@ export interface WorkflowRunFinishedEvent extends EventEnvelope {
     runId: string
     status: "succeeded" | "failed" | "cancelled"
     finishedAt: string
-    error?: string
+    error?: SixbFailure<WorkflowRunFailureCode>
   }
 }
 

package/src/execution/agent.ts

@@ -0,0 +1,130 @@
+import { agentServiceAccountId } from "../agents/authority"
+import type { AuthorizationContext } from "../authorization"
+import type { OntologySource } from "../ontology"
+import { isBoundSixb, type Sixb } from "../runtime/sixb"
+import type { CreateExecutionInput, ExecutionRecord } from "../storage/executions"
+import { ExecutionStorageError } from "../storage/executions"
+import { createAgentRuntimeAuthorization } from "./authorization"
+import type { AuthorizablePrincipal, ExecutionContext, ExecutionScope } from "./types"
+
+/** Minimal host boundary required by agent workers. */
+export interface AgentExecutionHost {
+  readonly id: string
+  withScope(scope: ExecutionScope): object
+}
+
+/** Build the immutable child execution owned by one direct or Workflow Agent run. */
+export function createAgentExecutionRecord(input: {
+  readonly id: string
+  readonly parent: ExecutionRecord
+  readonly agentId: string
+  readonly runId: string
+  readonly principal: Extract<AuthorizablePrincipal, { readonly type: "serviceAccount" }>
+}): CreateExecutionInput {
+  assertAgentPrincipal(input.agentId, input.principal)
+  return {
+    id: input.id,
+    projectId: input.parent.projectId,
+    ...(input.parent.requestedBy === undefined
+      ? {}
+      : { requestedBy: structuredClone(input.parent.requestedBy) }),
+    executor: { type: "agent", runId: input.runId },
+    source: { type: "execution", executionId: input.parent.id },
+    correlationId: input.parent.correlationId,
+    authorizationRef: {
+      type: "principal",
+      principal: structuredClone(input.principal),
+    },
+  }
+}
+
+/** Bind a worker to the immutable execution already owned by its durable Agent run. */
+export function bindDurableAgentExecution(
+  host: AgentExecutionHost,
+  input: {
+    readonly execution: ExecutionRecord
+    readonly agentId: string
+    readonly runId: string
+    readonly authorization: AuthorizationContext
+  }
+): Sixb<readonly OntologySource[]> {
+  const scope = restoreAgentExecutionScope(input)
+  const sixb = host.withScope(scope)
+  if (!isBoundSixb(sixb)) {
+    throw new Error("[Sixb] Agent execution host returned an invalid bound SDK.")
+  }
+  return sixb
+}
+
+/** Restore one provider-validated Agent execution with its currently resolved grants. */
+export function restoreAgentExecutionScope(input: {
+  readonly execution: ExecutionRecord
+  readonly agentId: string
+  readonly runId: string
+  readonly authorization: AuthorizationContext
+}): ExecutionScope {
+  assertAgentExecutionRecord(input)
+  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: "agent", agentId: input.agentId, runId: input.runId }),
+    source: Object.freeze(structuredClone(input.execution.source)),
+    correlationId: input.execution.correlationId,
+  })
+  return Object.freeze({
+    execution: context,
+    authorization: createAgentRuntimeAuthorization({
+      projectId: input.execution.projectId,
+      context: input.authorization,
+      executionId: input.execution.id,
+      agentId: input.agentId,
+      runId: input.runId,
+    }),
+  })
+}
+
+/** Validate that a durable record belongs to the exact resolved Agent execution. */
+export function assertAgentExecutionRecord(input: {
+  readonly execution: ExecutionRecord
+  readonly agentId: string
+  readonly runId: string
+  readonly authorization: AuthorizationContext
+}): void {
+  const authority = input.execution.authorizationRef
+  if (
+    input.execution.executor.type !== "agent" ||
+    input.execution.executor.runId !== input.runId ||
+    input.execution.source.type !== "execution" ||
+    authority.type !== "principal" ||
+    authority.principal.type !== "serviceAccount" ||
+    input.authorization.principal.type !== "serviceAccount" ||
+    authority.principal.id !== input.authorization.principal.id ||
+    authority.credential !== undefined
+  ) {
+    invalidAgentExecution(input.execution.id, input.runId)
+  }
+  assertAgentPrincipal(input.agentId, authority.principal)
+}
+
+function assertAgentPrincipal(
+  agentId: string,
+  principal: Extract<AuthorizablePrincipal, { readonly type: "serviceAccount" }>
+): void {
+  const expectedId = agentServiceAccountId(agentId)
+  if (principal.id !== expectedId) {
+    throw new ExecutionStorageError(
+      "invalid_input",
+      `[Sixb] Agent '${agentId}' execution authority must reference service account '${expectedId}'.`
+    )
+  }
+}
+
+function invalidAgentExecution(executionId: string, runId: string): never {
+  throw new ExecutionStorageError(
+    "invalid_input",
+    `[Sixb] Execution '${executionId}' does not authorize Agent run '${runId}'.`
+  )
+}