@sixb/core 0.1.0 → 0.1.2

package/src/error-reporting/internal.ts

@@ -1,13 +1,15 @@
 export {
   attachSixbErrorReporter,
   flushSixbErrors,
+  type ReportActionPhaseFailureInput,
   type ReportEventDeliveryFailureInput,
   type ReportRuleEvaluationFailureInput,
   type ReportRunFailureInput,
+  reportActionPhaseFailure,
   reportEventDeliveryFailure,
   reportRuleEvaluationFailure,
   reportRunFailure,
   shareSixbErrorReporter,
 } from "./capability"
 export { normalizeReportedError } from "./normalize"
-export { SixbErrorReporter } from "./reporter"
+export { type ErrorReporter, SixbErrorReporter } from "./reporter"

package/src/error-reporting/reporter.ts

@@ -3,17 +3,25 @@ import type { SixbErrorContext, SixbErrorHandler } from "./types"
 
 const DEFAULT_FLUSH_TIMEOUT_MS = 5_000
 
+export interface ErrorReporter {
+  report(error: unknown, context: SixbErrorContext): void
+}
+
 /** Failure-isolated, non-blocking adapter around the configured callback. */
-export class SixbErrorReporter {
+export class SixbErrorReporter implements ErrorReporter {
   private readonly pending = new Set<Promise<void>>()
 
   constructor(private readonly handler?: SixbErrorHandler) {}
 
   report(error: unknown, context: SixbErrorContext): void {
-    if (!this.handler) return
+    const normalizedError = normalizeReportedError(error)
+    if (!this.handler) {
+      reportToConsole(normalizedError, context)
+      return
+    }
 
     const invocation = Promise.resolve()
-      .then(() => this.handler?.(normalizeReportedError(error), context))
+      .then(() => this.handler?.(normalizedError, context))
       .then(() => undefined)
       .catch((handlerError) => {
         try {
@@ -47,6 +55,14 @@ export class SixbErrorReporter {
   }
 }
 
+function reportToConsole(error: Error, context: SixbErrorContext): void {
+  try {
+    console.error(`[Sixb] Unhandled ${context.type}:`, error, context)
+  } catch {
+    // Error reporting must never escape back into framework execution.
+  }
+}
+
 async function settleWithin(
   promises: readonly Promise<void>[],
   timeoutMs: number

package/src/error-reporting/reports.ts

@@ -0,0 +1,172 @@
+import { randomUUID } from "node:crypto"
+import { captureSixbFailure } from "../errors/internal"
+import type { SixbFailure } from "../errors/types"
+import type { ActionRunFailure } from "../storage/action-runs"
+import type { ErrorReporter } from "./reporter"
+import type { SixbFailedRun } from "./types"
+
+function resolveOccurredAt(occurredAt?: Date | string): string {
+  if (occurredAt instanceof Date) return occurredAt.toISOString()
+  return occurredAt ?? new Date().toISOString()
+}
+
+export type ReportRunFailureInput = SixbFailedRun & {
+  readonly projectId: string
+  readonly attempt?: number
+}
+
+export function reportRunFailure(
+  reporter: ErrorReporter,
+  error: unknown,
+  input: ReportRunFailureInput
+): void {
+  const occurredAt = input.failure.at
+  reporter.report(error, {
+    ...input,
+    type: "run.failed",
+    notificationId: `project:${input.projectId}:run:${input.runKind}:${input.run.runId}:failed:${occurredAt}`,
+    occurredAt,
+  })
+}
+
+export interface ReportActionPhaseFailureInput {
+  readonly projectId: string
+  readonly actionId: string
+  readonly runId: string
+  readonly phase: "effects"
+  readonly failure: ActionRunFailure<"effects">
+}
+
+export function reportActionPhaseFailure(
+  reporter: ErrorReporter,
+  error: unknown,
+  input: ReportActionPhaseFailureInput
+): void {
+  reporter.report(error, {
+    type: "action.phase.failed",
+    notificationId: `project:${input.projectId}:action:${input.actionId}:run:${input.runId}:phase:${input.phase}:failed:${input.failure.at}`,
+    projectId: input.projectId,
+    occurredAt: input.failure.at,
+    actionId: input.actionId,
+    runId: input.runId,
+    phase: input.phase,
+    failure: input.failure,
+  })
+}
+
+export interface ReportEventDeliveryFailureInput {
+  readonly projectId: string
+  /** Exact durable failure when this delivery was persisted by the ontology outbox. */
+  readonly failure?: SixbFailure<"event.delivery_failed">
+  /** Event types that never reached subscribers. Payloads must not be passed in. */
+  readonly eventTypes: readonly string[]
+  readonly occurredAt?: Date | string
+  /** Delivery attempts so far. Defaults to 1, which is right for a rejected emit. */
+  readonly attempts?: number
+  /** Envelope ids, when the events were persisted before delivery failed. */
+  readonly eventIds?: readonly string[]
+  /**
+   * Identity of this loss, used only when nothing was persisted. Defaults to a fresh id; pass one to
+   * make a report reproducible in a test.
+   */
+  readonly occurrenceId?: string
+}
+
+/**
+ * Report that domain events were lost.
+ *
+ * Both delivery paths land here: the outbox dispatcher, which has persisted envelope ids and retries,
+ * and a rejected `events.emit()`, which has only the types. Reporting must work for both — an earlier
+ * version returned early on an empty `eventIds`, which silently dropped exactly the case this exists
+ * to surface.
+ *
+ * Each path keys on the strongest identity it has. The outbox persisted its envelopes, so the ids plus
+ * the attempt number name the loss exactly and stay stable if one report is delivered twice. A rejected
+ * emit persisted nothing and is always terminal at attempt 1, so the type list alone was its whole
+ * correlation — and two schedules losing `schedule.triggered` in the same broker outage are dispatched
+ * concurrently, land in the same millisecond, and were therefore one notification. A timestamp does not
+ * fix that; an identity does.
+ */
+export function reportEventDeliveryFailure(
+  reporter: ErrorReporter,
+  error: unknown,
+  input: ReportEventDeliveryFailureInput
+): void {
+  const occurredAt = input.failure?.at ?? resolveOccurredAt(input.occurredAt)
+  const attempts = input.attempts ?? 1
+  const eventIds = input.eventIds === undefined ? undefined : [...input.eventIds].sort()
+  const eventTypes = [...input.eventTypes]
+  const failure =
+    input.failure ??
+    captureSixbFailure(error, {
+      allowedCodes: ["event.delivery_failed"],
+      defaultCode: "event.delivery_failed",
+      details: {
+        attempts,
+        eventTypes,
+        ...(eventIds === undefined ? {} : { eventIds }),
+      },
+      at: new Date(occurredAt),
+    })
+  const firstEventId = eventIds?.[0]
+  const occurrence = firstEventId
+    ? `events:${firstEventId}:attempt:${attempts}`
+    : `emit:${input.occurrenceId ?? randomUUID()}`
+  reporter.report(error, {
+    type: "event.delivery.failed",
+    notificationId: `project:${input.projectId}:event-delivery:${occurrence}`,
+    projectId: input.projectId,
+    occurredAt,
+    failure,
+    attempts,
+    eventTypes,
+    ...(eventIds === undefined ? {} : { eventIds }),
+  })
+}
+
+export interface ReportRuleEvaluationFailureInput {
+  readonly projectId: string
+  readonly source: "live" | "reconciliation"
+  readonly eventIds?: readonly string[]
+  readonly occurredAt?: Date | string
+  /** Set when the failure could be attributed to one rule/subject candidate. */
+  readonly ruleId?: string
+  readonly subject?: { readonly objectTypeId: string; readonly primaryId: string }
+}
+
+export function reportRuleEvaluationFailure(
+  reporter: ErrorReporter,
+  error: unknown,
+  input: ReportRuleEvaluationFailureInput
+): void {
+  const occurredAt = resolveOccurredAt(input.occurredAt)
+  const eventIds = [...(input.eventIds ?? [])].sort()
+  const failure = captureSixbFailure(error, {
+    allowedCodes: ["internal.unexpected"],
+    defaultCode: "internal.unexpected",
+    details: {
+      source: input.source,
+      eventIds,
+      ...(input.ruleId === undefined ? {} : { ruleId: input.ruleId }),
+      ...(input.subject === undefined ? {} : { subject: input.subject }),
+    },
+    at: new Date(occurredAt),
+  })
+  // A candidate-level failure keys on the candidate, so two rules failing over the same batch stay
+  // two notifications rather than collapsing into one.
+  const occurrence =
+    input.ruleId && input.subject
+      ? `${input.ruleId}:${input.subject.objectTypeId}:${input.subject.primaryId}`
+      : (eventIds[0] ?? "current-state")
+  reporter.report(error, {
+    type: "rule.evaluation.failed",
+    notificationId: `project:${input.projectId}:rule-evaluation:${input.source}:${occurrence}:failed:${occurredAt}`,
+    projectId: input.projectId,
+    occurredAt,
+    failure,
+    source: input.source,
+    eventIds,
+    ...(input.ruleId === undefined ? {} : { ruleId: input.ruleId }),
+    ...(input.subject === undefined ? {} : { subject: input.subject }),
+  })
+}

package/src/error-reporting/types.ts

@@ -1,49 +1,74 @@
+import type { SixbFailure } from "../errors/types"
+import type { ActionRunFailure } from "../storage/action-runs"
+import type { AgentRunFailureCode } from "../storage/agents"
+import type { PipelineRunFailureCode } from "../storage/pipeline-runs"
+import type { ProjectionRunFailureCode } from "../storage/projection-runs"
+import type { SyncRunFailureCode } from "../storage/sync-runs"
+import type { WebhookRunFailureCode } from "../storage/webhook-runs"
+import type { WorkflowRunFailureCode } from "../storage/workflow-runs"
+
+/** Correlation fields exposed by `run.failed`, indexed by run primitive. */
+export interface SixbRunIdentityByKind {
+  readonly action: {
+    readonly runId: string
+    readonly actionId: string
+  }
+  readonly agent: {
+    readonly runId: string
+    readonly agentId: string
+  }
+  readonly pipeline: {
+    readonly runId: string
+    readonly pipelineId: string
+  }
+  readonly projection: {
+    readonly runId: string
+    readonly projectionId: string
+    readonly projectionKind: "object" | "link" | "telemetry"
+  }
+  readonly sync: {
+    readonly runId: string
+    readonly syncId: string
+  }
+  readonly workflow: {
+    readonly runId: string
+    readonly workflowId: string
+  }
+  readonly webhook: {
+    readonly runId: string
+    readonly connectorId: string
+    readonly webhookId: string
+  }
+}
+
+/** Canonical failure record exposed by `run.failed`, indexed by run primitive. */
+export interface SixbRunFailureByKind {
+  readonly action: ActionRunFailure
+  readonly agent: SixbFailure<AgentRunFailureCode>
+  readonly pipeline: SixbFailure<PipelineRunFailureCode>
+  readonly projection: SixbFailure<ProjectionRunFailureCode>
+  readonly sync: SixbFailure<SyncRunFailureCode>
+  readonly workflow: SixbFailure<WorkflowRunFailureCode>
+  readonly webhook: SixbFailure<WebhookRunFailureCode>
+}
+
 /**
  * The failed unit of work, discriminated by primitive. Each variant carries the correlation its
- * primitive actually has, and there is exactly one variant per `SixbRunKind`.
+ * primitive actually has and the exact failure persisted by that run. There is exactly one variant
+ * per `SixbRunKind`.
  *
  * Rules are deliberately absent: they are evaluated live, per subject, with no run record, so they
  * report through `SixbRuleEvaluationFailedContext` instead of being handed a `runId` that would name
  * an entity nothing can resolve.
  */
-export type SixbFailedRun =
-  | {
-      readonly kind: "action"
-      readonly runId: string
-      readonly actionId: string
-    }
-  | {
-      readonly kind: "agent"
-      readonly runId: string
-      readonly agentId: string
-    }
-  | {
-      readonly kind: "pipeline"
-      readonly runId: string
-      readonly pipelineId: string
-    }
-  | {
-      readonly kind: "projection"
-      readonly runId: string
-      readonly projectionId: string
-      readonly projectionKind: "object" | "link" | "telemetry"
-    }
-  | {
-      readonly kind: "sync"
-      readonly runId: string
-      readonly syncId: string
-    }
-  | {
-      readonly kind: "workflow"
-      readonly runId: string
-      readonly workflowId: string
-    }
-  | {
-      readonly kind: "webhook"
-      readonly runId: string
-      readonly connectorId: string
-      readonly webhookId: string
-    }
+export type SixbFailedRun = {
+  readonly [TKind in keyof SixbRunIdentityByKind]: {
+    /** Top-level discriminant so TypeScript narrows both `run` and `failure` without casts. */
+    readonly runKind: TKind
+    readonly run: SixbRunIdentityByKind[TKind]
+    readonly failure: SixbRunFailureByKind[TKind]
+  }
+}[keyof SixbRunIdentityByKind]
 
 interface SixbFailureContext<TType extends string> {
   readonly type: TType
@@ -59,10 +84,31 @@ interface SixbFailureContext<TType extends string> {
   readonly occurredAt: string
 }
 
-export interface SixbRunFailedContext extends SixbFailureContext<"run.failed"> {
-  /** Queue delivery attempt, when the run was executed through a queue. */
-  readonly attempt?: number
-  readonly run: SixbFailedRun
+export type SixbRunFailedContext = SixbFailureContext<"run.failed"> &
+  SixbFailedRun & {
+    /** Queue delivery attempt, when the run was executed through a queue. */
+    readonly attempt?: number
+  }
+
+/** A post-commit Action effects phase failed without changing the committed Action outcome. */
+export interface SixbActionPhaseFailedContext extends SixbFailureContext<"action.phase.failed"> {
+  readonly actionId: string
+  readonly runId: string
+  readonly phase: "effects"
+  readonly failure: ActionRunFailure<"effects">
+}
+
+/**
+ * A post-commit Action phase failed without changing the committed Action outcome.
+ *
+ * Effects run after the authoritative commit, so the Action run remains succeeded while this
+ * context exposes the exact phase failure stored on the run.
+ */
+export interface SixbActionPhaseFailedContext extends SixbFailureContext<"action.phase.failed"> {
+  readonly actionId: string
+  readonly runId: string
+  readonly phase: "effects"
+  readonly failure: ActionRunFailure<"effects">
 }
 
 /**
@@ -79,6 +125,8 @@ export interface SixbRunFailedContext extends SixbFailureContext<"run.failed"> {
  */
 export interface SixbEventDeliveryFailedContext
   extends SixbFailureContext<"event.delivery.failed"> {
+  /** Canonical delivery failure, also persisted when the outbox owns the delivery. */
+  readonly failure: SixbFailure<"event.delivery_failed">
   /** Delivery attempts so far. A rejected emit is terminal, so it reports 1. */
   readonly attempts: number
   /** Which event types never reached subscribers. Payloads are never included. */
@@ -104,6 +152,11 @@ export interface SixbEventDeliveryFailedContext
  */
 export interface SixbRuleEvaluationFailedContext
   extends SixbFailureContext<"rule.evaluation.failed"> {
+  /**
+   * Canonical snapshot of the thrown value. Rule failures remain `internal.unexpected` until the
+   * evaluator can distinguish deterministic rule failures from retryable dependency failures.
+   */
+  readonly failure: SixbFailure<"internal.unexpected">
   readonly source: "live" | "reconciliation"
   /** Envelope IDs involved in a live evaluation; empty for reconciliation. */
   readonly eventIds: readonly string[]
@@ -117,6 +170,7 @@ export interface SixbRuleEvaluationFailedContext
  * Failure notifications never change the outcome of the operation they observe.
  */
 export type SixbErrorContext =
+  | SixbActionPhaseFailedContext
   | SixbRunFailedContext
   | SixbEventDeliveryFailedContext
   | SixbRuleEvaluationFailedContext

package/src/errors/catalog.ts

@@ -0,0 +1,149 @@
+interface SixbErrorDefinition {
+  readonly publicMessage: string
+  readonly retryable: boolean
+}
+
+/**
+ * Source of truth for stable Sixb error codes and their framework-level policy.
+ *
+ * Keep this catalog internal. Consumers receive the `SixbErrorCode` union and persisted
+ * `SixbFailure` values, not a mutable registry.
+ */
+export const SIXB_ERROR_DEFINITIONS = {
+  "action.phase_failed": {
+    publicMessage: "Action execution failed.",
+    retryable: false,
+  },
+  "agent.execution_failed": {
+    publicMessage: "Agent execution failed.",
+    retryable: false,
+  },
+  "connector.adapter_invalid": {
+    publicMessage: "Connector adapter returned an invalid result.",
+    retryable: false,
+  },
+  "connector.authorization_invalid": {
+    publicMessage: "Connector authorization is invalid.",
+    retryable: false,
+  },
+  "connector.authorization_required": {
+    publicMessage: "Connector authorization is required.",
+    retryable: false,
+  },
+  "connector.configuration_invalid": {
+    publicMessage: "Connector configuration is invalid.",
+    retryable: false,
+  },
+  "connector.credentials_unavailable": {
+    publicMessage: "Connector credentials are unavailable.",
+    retryable: false,
+  },
+  "connector.not_found": {
+    publicMessage: "Connector resource not found.",
+    retryable: false,
+  },
+  "connector.operation_conflict": {
+    publicMessage: "Connector operation conflicts with the current state.",
+    retryable: false,
+  },
+  "connector.operation_in_progress": {
+    publicMessage: "Another connector credential operation is in progress.",
+    retryable: true,
+  },
+  "connector.provider_failed": {
+    publicMessage: "Connector provider operation failed.",
+    retryable: false,
+  },
+  "connector.provider_unavailable": {
+    publicMessage: "Connector provider is temporarily unavailable.",
+    retryable: true,
+  },
+  "connector.replacement_required": {
+    publicMessage: "Connector selection requires explicit replacement.",
+    retryable: false,
+  },
+  "connector.revocation_pending": {
+    publicMessage: "Connector revocation is pending.",
+    retryable: true,
+  },
+  "dataset.not_found": {
+    publicMessage: "Dataset not found.",
+    retryable: false,
+  },
+  "dataset.version_incompatible": {
+    publicMessage: "Dataset version is incompatible.",
+    retryable: false,
+  },
+  "dataset.version_not_found": {
+    publicMessage: "Dataset version not found.",
+    retryable: false,
+  },
+  "dataset.version_read_inconsistent": {
+    publicMessage: "Dataset version could not be read consistently.",
+    retryable: true,
+  },
+  "event.delivery_failed": {
+    publicMessage: "Event delivery failed.",
+    retryable: true,
+  },
+  "internal.unexpected": {
+    publicMessage: "An unexpected internal error occurred.",
+    retryable: false,
+  },
+  "queue.enqueue_failed": {
+    publicMessage: "The job could not be enqueued.",
+    retryable: true,
+  },
+  "pipeline.step_failed": {
+    publicMessage: "Pipeline step execution failed.",
+    retryable: false,
+  },
+  "projection.definition_invalid": {
+    publicMessage: "Projection definition is invalid.",
+    retryable: false,
+  },
+  "projection.execution_failed": {
+    publicMessage: "Projection execution failed.",
+    retryable: false,
+  },
+  "projection.not_found": {
+    publicMessage: "Projection not found.",
+    retryable: false,
+  },
+  "projection.run_already_terminal": {
+    publicMessage: "Projection run is already terminal.",
+    retryable: false,
+  },
+  "projection.run_identity_mismatch": {
+    publicMessage: "Projection run identity does not match the queued job.",
+    retryable: false,
+  },
+  "runtime.cancelled": {
+    publicMessage: "Execution was cancelled.",
+    retryable: false,
+  },
+  "sync.execution_failed": {
+    publicMessage: "Sync execution failed.",
+    retryable: false,
+  },
+  "webhook.delivery_failed": {
+    publicMessage: "Webhook delivery failed.",
+    retryable: true,
+  },
+  "webhook.delivery_rejected": {
+    publicMessage: "Webhook delivery was rejected.",
+    retryable: false,
+  },
+  "workflow.node_failed": {
+    publicMessage: "Workflow node execution failed.",
+    retryable: false,
+  },
+} as const satisfies Readonly<Record<string, SixbErrorDefinition>>
+
+type CatalogErrorCode = keyof typeof SIXB_ERROR_DEFINITIONS
+
+/** Runtime counterpart of `SixbErrorCode` for internal schema boundaries. */
+export const SIXB_ERROR_CODES = Object.freeze(Object.keys(SIXB_ERROR_DEFINITIONS)) as readonly [
+  CatalogErrorCode,
+  ...CatalogErrorCode[],
+]