@sixb/core 0.1.1 → 0.1.2

package/src/events/execution.ts

@@ -0,0 +1,45 @@
+import { assertPrivileged, canViewEvent } from "../authorization"
+import type { SixbRuntimeContext } from "../runtime/types"
+import type {
+  EventsAppendInput,
+  EventsEmitOptions,
+  EventsReadInput,
+  EventsSubscribeInput,
+} from "./service"
+import type { StoredDomainEvent } from "./types"
+
+export interface EventsRuntime {
+  canRead(event: StoredDomainEvent): boolean
+  append(input: EventsAppendInput): Promise<readonly StoredDomainEvent[]>
+  emit(input: EventsAppendInput, options: EventsEmitOptions): Promise<void>
+  read(input?: EventsReadInput): Promise<readonly StoredDomainEvent[]>
+  latestCursor(): Promise<string | undefined>
+  subscribe(
+    input: EventsSubscribeInput,
+    handler: (events: readonly StoredDomainEvent[]) => void
+  ): Promise<() => void>
+}
+
+export function createEventsRuntime(runtime: SixbRuntimeContext): EventsRuntime {
+  return {
+    canRead: (event) => canViewEvent(runtime.authorization, event),
+    append: (input) => {
+      assertPrivileged(runtime, "events.append")
+      return runtime.events.append(input)
+    },
+    emit: (input, options) => {
+      assertPrivileged(runtime, "events.emit")
+      return runtime.events.emit(input, options)
+    },
+    read: async (input) => {
+      const events = await runtime.events.read(input)
+      return events.filter((event) => canViewEvent(runtime.authorization, event))
+    },
+    latestCursor: () => runtime.events.latestCursor(),
+    subscribe: (input, handler) =>
+      runtime.events.subscribe(input, (events) => {
+        const visible = events.filter((event) => canViewEvent(runtime.authorization, event))
+        if (visible.length > 0) handler(visible)
+      }),
+  }
+}

package/src/events/index.ts

@@ -1,3 +1,4 @@
+export type { ErrorReporter } from "../error-reporting/reporter"
 export type { EventDefinition, EventDefinitionGroup, EventDefinitionMap } from "./definitions"
 export {
   ACTION_EVENT_DEFINITIONS,
@@ -5,7 +6,6 @@ export {
   EVENT_DEFINITIONS,
   EVENT_TOPICS,
   EVENT_TYPES,
-  getEventTopic,
   isDomainEventType,
   isOntologyFactType,
   LINK_EVENT_DEFINITIONS,
@@ -23,19 +23,6 @@ export {
   OntologyOutboxDispatcher,
   type OntologyOutboxDispatcherOptions,
 } from "./outbox-dispatcher"
-export {
-  DEFAULT_EVENTS_RETENTION_MS,
-  type DomainEventLog,
-  EVENTS_STREAM,
-  type EventsAppendInput,
-  type EventsEmitOptions,
-  type EventsReadInput,
-  EventsRuntime,
-  type EventsRuntimeOptions,
-  type EventsSubscribeInput,
-  type StableEventEnvelope,
-  type StableEventPublisher,
-} from "./runtime"
 export type { EventScopeKeys } from "./scope"
 export { scopeKeysForEvent } from "./scope"
 export {
@@ -79,6 +66,20 @@ export {
   type SyncEventSelectorEvent,
   type SyncEventToken,
 } from "./selectors"
+export {
+  createDomainEventService,
+  DEFAULT_EVENTS_RETENTION_MS,
+  type DomainEventLog,
+  DomainEventService,
+  type DomainEventServiceOptions,
+  EVENTS_STREAM,
+  type EventsAppendInput,
+  type EventsEmitOptions,
+  type EventsReadInput,
+  type EventsSubscribeInput,
+  type StableEventEnvelope,
+  type StableEventPublisher,
+} from "./service"
 export { toStoredEvent } from "./toStoredEvent"
 export type {
   ActionCompletedEvent,

package/src/events/outbox-dispatcher.ts

@@ -1,19 +1,30 @@
 import { randomUUID } from "node:crypto"
-import type { ClaimedOntologyOutboxRow, OntologyOutboxStorage, Storage } from "../storage"
-import type { StableEventPublisher } from "./runtime"
-
-const DEFAULT_BATCH_SIZE = 100
+import { createSixbError, serializeSixbFailure, toSixbFailure } from "../errors/internal"
+import type {
+  ClaimedOntologyOutboxRow,
+  OntologyOutboxFailure,
+  OntologyOutboxStorage,
+  Storage,
+} from "../storage"
+import { ONTOLOGY_OUTBOX_FAILURE_CODES } from "../storage/ontology/outbox"
+import type { StableEventPublisher } from "./service"
+
+const DEFAULT_BATCH_SIZE = 1_000
 const DEFAULT_LEASE_DURATION_MS = 30_000
 const DEFAULT_INITIAL_RETRY_DELAY_MS = 1_000
 const DEFAULT_MAX_RETRY_DELAY_MS = 5 * 60_000
 const DEFAULT_RETRY_JITTER_RATIO = 0.2
-const DEFAULT_MAX_ISOLATION_ATTEMPTS = 16
+// Isolating one poison row from a 1,000-row batch needs up to 21 broker calls: one failed call
+// and, at each split depth, one healthy sibling plus the failing half. Keep bounded headroom for
+// uneven splits while rescheduling unresolved groups once this pass reaches the cap.
+const DEFAULT_MAX_ISOLATION_ATTEMPTS = 32
 const DEFAULT_MAX_CLAIMS_PER_DRAIN = 10
 const DEFAULT_SHUTDOWN_TIMEOUT_MS = 30_000
-const SHUTDOWN_RESCHEDULE_ERROR = "Outbox dispatcher stopped before publication completed."
 
 export interface OntologyOutboxDeliveryFailure {
   readonly occurredAt: string
+  /** Exact failure persisted on every envelope represented by this report. */
+  readonly failure: OntologyOutboxFailure
   readonly attempts: number
   readonly eventIds: readonly string[]
   /** Types of the undelivered envelopes. The one field both delivery paths can always report. */
@@ -317,7 +328,12 @@ export class OntologyOutboxDispatcher {
     const failedAt = this.now()
 
     for (const [attempts, attemptRows] of rowsByAttempts(settling)) {
-      failures.add(error, failedAt.toISOString(), attempts, attemptRows)
+      const deliveryError = createEventDeliveryError(error, attempts)
+      const failure = toSixbFailure(deliveryError, {
+        allowedCodes: ONTOLOGY_OUTBOX_FAILURE_CODES,
+        at: failedAt,
+      })
+      failures.add(deliveryError, failure, failedAt.toISOString(), attempts, attemptRows)
       try {
         await this.withOutbox((outbox) =>
           outbox.reschedule({
@@ -325,7 +341,7 @@ export class OntologyOutboxDispatcher {
             ids: eventIds(attemptRows),
             leaseId: sharedLeaseId(attemptRows),
             availableAt: new Date(failedAt.getTime() + this.retryDelayMs(attempts)).toISOString(),
-            error: errorMessage(error),
+            failure,
           })
         )
       } catch (rescheduleError) {
@@ -355,7 +371,6 @@ export class OntologyOutboxDispatcher {
           ids: eventIds(rows),
           leaseId: sharedLeaseId(rows),
           availableAt: this.now().toISOString(),
-          error: SHUTDOWN_RESCHEDULE_ERROR,
         })
       )
     } catch (error) {
@@ -404,19 +419,30 @@ interface AccumulatedDeliveryFailure {
 /** Coalesces bisection failures so one claimed row is reported once per delivery attempt. */
 class DeliveryFailureAccumulator {
   private readonly groups = new Map<
-    number,
-    { error: unknown; occurredAt: string; eventIds: Set<string>; eventTypes: Set<string> }
+    string,
+    {
+      error: unknown
+      failure: OntologyOutboxFailure
+      occurredAt: string
+      attempts: number
+      eventIds: Set<string>
+      eventTypes: Set<string>
+    }
   >()
 
   add(
     error: unknown,
+    failure: OntologyOutboxFailure,
     occurredAt: string,
     attempts: number,
     rows: readonly ClaimedOntologyOutboxRow[]
   ): void {
-    const group = this.groups.get(attempts) ?? {
+    const key = serializeSixbFailure(failure, ONTOLOGY_OUTBOX_FAILURE_CODES)
+    const group = this.groups.get(key) ?? {
       error,
+      failure,
       occurredAt,
+      attempts,
       eventIds: new Set<string>(),
       eventTypes: new Set<string>(),
     }
@@ -424,15 +450,16 @@ class DeliveryFailureAccumulator {
       group.eventIds.add(row.envelope.id)
       group.eventTypes.add(row.envelope.type)
     }
-    this.groups.set(attempts, group)
+    this.groups.set(key, group)
   }
 
   list(): readonly AccumulatedDeliveryFailure[] {
-    return [...this.groups.entries()].map(([attempts, group]) => ({
+    return [...this.groups.values()].map((group) => ({
       error: group.error,
       context: {
         occurredAt: group.occurredAt,
-        attempts,
+        failure: group.failure,
+        attempts: group.attempts,
         eventIds: [...group.eventIds].sort(),
         eventTypes: [...group.eventTypes].sort(),
       },
@@ -484,9 +511,17 @@ function sharedLeaseId(rows: readonly ClaimedOntologyOutboxRow[]): string {
   return leaseId
 }
 
-function errorMessage(error: unknown): string {
-  const message = error instanceof Error ? `${error.name}: ${error.message}` : String(error)
-  return message.slice(0, 2_000)
+function createEventDeliveryError(cause: unknown, attempts: number) {
+  return createSixbError(
+    "event.delivery_failed",
+    "[Sixb] Could not deliver persisted ontology events.",
+    {
+      cause,
+      details: {
+        attempts,
+      },
+    }
+  )
 }
 
 async function publishUntilStopped(

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}'.`
+  )
+}