@sixb/core 0.0.1

package/src/error-reporting/capability.ts

@@ -0,0 +1,160 @@
+import { randomUUID } from "node:crypto"
+import { SixbErrorReporter } from "./reporter"
+import type { SixbErrorHandler, SixbFailedRun } from "./types"
+
+function resolveOccurredAt(occurredAt?: Date | string): string {
+  if (occurredAt instanceof Date) return occurredAt.toISOString()
+  return occurredAt ?? new Date().toISOString()
+}
+
+const ERROR_REPORTER = Symbol("sixb.error-reporter")
+
+type ErrorReporterHost = {
+  [ERROR_REPORTER]?: SixbErrorReporter
+}
+
+function asHost(value: unknown): ErrorReporterHost | null {
+  if ((typeof value !== "object" && typeof value !== "function") || value === null) {
+    return null
+  }
+  return value as ErrorReporterHost
+}
+
+export function attachSixbErrorReporter(
+  host: object,
+  handler?: SixbErrorHandler
+): SixbErrorReporter {
+  const reporter = new SixbErrorReporter(handler)
+  ;(host as ErrorReporterHost)[ERROR_REPORTER] = reporter
+  return reporter
+}
+
+export function shareSixbErrorReporter(source: object, target: object): void {
+  const reporter = (source as ErrorReporterHost)[ERROR_REPORTER]
+  if (reporter) (target as ErrorReporterHost)[ERROR_REPORTER] = reporter
+}
+
+export interface ReportRunFailureInput {
+  readonly projectId: string
+  readonly run: SixbFailedRun
+  readonly occurredAt?: Date | string
+  readonly attempt?: number
+}
+
+export function reportRunFailure(
+  host: unknown,
+  error: unknown,
+  input: ReportRunFailureInput
+): void {
+  const reporter = asHost(host)?.[ERROR_REPORTER]
+  if (!reporter) return
+
+  const occurredAt = resolveOccurredAt(input.occurredAt)
+  reporter.report(error, {
+    type: "run.failed",
+    notificationId: `project:${input.projectId}:run:${input.run.kind}:${input.run.runId}:failed:${occurredAt}`,
+    projectId: input.projectId,
+    occurredAt,
+    ...(input.attempt === undefined ? {} : { attempt: input.attempt }),
+    run: input.run,
+  })
+}
+
+export interface ReportEventDeliveryFailureInput {
+  readonly projectId: string
+  /** 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(
+  host: unknown,
+  error: unknown,
+  input: ReportEventDeliveryFailureInput
+): void {
+  const reporter = asHost(host)?.[ERROR_REPORTER]
+  if (!reporter) return
+
+  const occurredAt = resolveOccurredAt(input.occurredAt)
+  const attempts = input.attempts ?? 1
+  const eventIds = input.eventIds === undefined ? undefined : [...input.eventIds].sort()
+  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,
+    attempts,
+    eventTypes: input.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(
+  host: unknown,
+  error: unknown,
+  input: ReportRuleEvaluationFailureInput
+): void {
+  const reporter = asHost(host)?.[ERROR_REPORTER]
+  if (!reporter) return
+
+  const occurredAt = resolveOccurredAt(input.occurredAt)
+  const eventIds = [...(input.eventIds ?? [])].sort()
+  // 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,
+    source: input.source,
+    eventIds,
+    ...(input.ruleId === undefined ? {} : { ruleId: input.ruleId }),
+    ...(input.subject === undefined ? {} : { subject: input.subject }),
+  })
+}
+
+export async function flushSixbErrors(host: unknown, timeoutMs?: number): Promise<void> {
+  await asHost(host)?.[ERROR_REPORTER]?.flush(timeoutMs)
+}

package/src/error-reporting/internal.ts

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

package/src/error-reporting/normalize.ts

@@ -0,0 +1,35 @@
+function safeString(value: unknown): string {
+  try {
+    return String(value)
+  } catch {
+    return "Unknown thrown value"
+  }
+}
+
+/** Preserve native errors and safely wrap arbitrary thrown values. */
+export function normalizeReportedError(value: unknown): Error {
+  if (value instanceof Error) {
+    return value
+  }
+
+  if (typeof value === "object" && value !== null) {
+    let message: unknown
+    let name: unknown
+    try {
+      message = Reflect.get(value, "message")
+      name = Reflect.get(value, "name")
+    } catch {
+      return new Error("Unknown thrown value")
+    }
+
+    if (typeof message === "string") {
+      const error = new Error(message)
+      if (typeof name === "string" && name.trim()) {
+        error.name = name
+      }
+      return error
+    }
+  }
+
+  return new Error(safeString(value))
+}

package/src/error-reporting/reporter.ts

@@ -0,0 +1,65 @@
+import { normalizeReportedError } from "./normalize"
+import type { SixbErrorContext, SixbErrorHandler } from "./types"
+
+const DEFAULT_FLUSH_TIMEOUT_MS = 5_000
+
+/** Failure-isolated, non-blocking adapter around the configured callback. */
+export class SixbErrorReporter {
+  private readonly pending = new Set<Promise<void>>()
+
+  constructor(private readonly handler?: SixbErrorHandler) {}
+
+  report(error: unknown, context: SixbErrorContext): void {
+    if (!this.handler) return
+
+    const invocation = Promise.resolve()
+      .then(() => this.handler?.(normalizeReportedError(error), context))
+      .then(() => undefined)
+      .catch((handlerError) => {
+        try {
+          console.error("[Sixb] onError handler failed:", handlerError)
+        } catch {
+          // Error reporting must never escape back into framework execution.
+        }
+      })
+
+    const tracked = invocation.finally(() => {
+      this.pending.delete(tracked)
+    })
+    this.pending.add(tracked)
+  }
+
+  async flush(timeoutMs = DEFAULT_FLUSH_TIMEOUT_MS): Promise<void> {
+    const deadline = Date.now() + Math.max(0, timeoutMs)
+    while (this.pending.size > 0) {
+      const remainingMs = deadline - Date.now()
+      if (remainingMs <= 0 || !(await settleWithin([...this.pending], remainingMs))) {
+        try {
+          console.error(
+            `[Sixb] Timed out after ${timeoutMs}ms waiting for ${this.pending.size} onError handler(s).`
+          )
+        } catch {
+          // Error reporting must never escape back into framework shutdown.
+        }
+        return
+      }
+    }
+  }
+}
+
+async function settleWithin(
+  promises: readonly Promise<void>[],
+  timeoutMs: number
+): Promise<boolean> {
+  let timeout: ReturnType<typeof setTimeout> | undefined
+  try {
+    return await Promise.race([
+      Promise.allSettled(promises).then(() => true),
+      new Promise<false>((resolve) => {
+        timeout = setTimeout(() => resolve(false), timeoutMs)
+      }),
+    ])
+  } finally {
+    if (timeout) clearTimeout(timeout)
+  }
+}

package/src/error-reporting/types.ts

@@ -0,0 +1,125 @@
+/**
+ * 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`.
+ *
+ * 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
+    }
+
+interface SixbFailureContext<TType extends string> {
+  readonly type: TType
+  /**
+   * Stable key for this one failure occurrence, usable as an idempotency key when notifying.
+   *
+   * Two distinct failures never share it. Each context keys on the strongest identity its failure has —
+   * a run id, a rule and subject, persisted envelope ids — and a failure with no such identity carries
+   * one of its own rather than borrowing a timestamp, which concurrent failures share.
+   */
+  readonly notificationId: string
+  readonly projectId: 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
+}
+
+/**
+ * A batch of domain events never reached its subscribers.
+ *
+ * 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.
+ *
+ * Two paths report here, which is why `eventIds` is optional. The outbox dispatcher persists envelopes
+ * before publishing them, so it has ids and reports a rising `attempts` as it retries. A rejected
+ * `events.emit()` never got that far: nothing was persisted, so only the types are known and the
+ * failure is terminal at `attempts: 1`. `eventTypes` is the field both paths can always fill, and the
+ * one an operator reads first.
+ */
+export interface SixbEventDeliveryFailedContext
+  extends SixbFailureContext<"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. */
+  readonly eventTypes: readonly string[]
+  /**
+   * Stable envelope IDs, present only when the events were persisted before delivery failed.
+   * Payloads and lease identifiers are never exposed.
+   */
+  readonly eventIds?: readonly string[]
+}
+
+/**
+ * A rule evaluation failed.
+ *
+ * `source` is the field to alert on. A failing `live` evaluation is recoverable: the periodic
+ * reconciliation pass rebuilds rule state from committed objects, so the affected subjects are
+ * re-evaluated within one interval. A failing `reconciliation` pass is not — it *is* the repair path,
+ * so while it keeps failing, rule state stops converging.
+ *
+ * `ruleId` and `subject` are present whenever the failure could be attributed to one candidate. They
+ * are absent when the failure took down a whole batch or pass before any single candidate could be
+ * blamed, which is itself the case worth escalating.
+ */
+export interface SixbRuleEvaluationFailedContext
+  extends SixbFailureContext<"rule.evaluation.failed"> {
+  readonly source: "live" | "reconciliation"
+  /** Envelope IDs involved in a live evaluation; empty for reconciliation. */
+  readonly eventIds: readonly string[]
+  readonly ruleId?: string
+  readonly subject?: { readonly objectTypeId: string; readonly primaryId: string }
+}
+
+/**
+ * Context supplied to the global Sixb error handler, discriminated by `type`.
+ *
+ * Failure notifications never change the outcome of the operation they observe.
+ */
+export type SixbErrorContext =
+  | SixbRunFailedContext
+  | SixbEventDeliveryFailedContext
+  | SixbRuleEvaluationFailedContext
+
+/** Observes runtime failures without changing their outcome. */
+export type SixbErrorHandler = (error: Error, context: SixbErrorContext) => void | Promise<void>

package/src/events/definitions.ts

@@ -0,0 +1,241 @@
+import { EventsError } from "./errors"
+import type { ActionEvent } from "./types/actions"
+import type { DatasetEvent } from "./types/datasets"
+import type { DomainEvent, DomainEventDraft } from "./types/index"
+import type { LinkEvent } from "./types/links"
+import type { ObjectEvent } from "./types/objects"
+import type { PipelineEvent } from "./types/pipelines"
+import type { RuleEvent } from "./types/rules"
+import type { ScheduleEvent } from "./types/schedules"
+import type { SyncEvent } from "./types/syncs"
+import type { TelemetryEvent } from "./types/telemetry"
+import type { WorkflowEvent } from "./types/workflows"
+
+export type EventDefinition<Event extends DomainEvent = DomainEvent> = {
+  readonly topic: Event["topic"]
+  readonly partitionKey: (payload: Event["payload"]) => string
+}
+
+export type EventDefinitionGroup<Event extends DomainEvent> = {
+  readonly [Type in Event["type"]]: EventDefinition<Extract<Event, { type: Type }>>
+}
+
+export type EventDefinitionMap = {
+  readonly [Type in DomainEvent["type"]]: EventDefinition<Extract<DomainEvent, { type: Type }>>
+}
+
+function defineEventGroup<Event extends DomainEvent>(
+  definitions: EventDefinitionGroup<Event>
+): EventDefinitionGroup<Event> {
+  return definitions
+}
+
+export const OBJECT_EVENT_DEFINITIONS = defineEventGroup<ObjectEvent>({
+  "object.created": {
+    topic: "objects",
+    partitionKey: (payload) => `${payload.objectTypeId}:${payload.primaryId}`,
+  },
+  "object.updated": {
+    topic: "objects",
+    partitionKey: (payload) => `${payload.objectTypeId}:${payload.primaryId}`,
+  },
+  "object.deleted": {
+    topic: "objects",
+    partitionKey: (payload) => `${payload.objectTypeId}:${payload.primaryId}`,
+  },
+})
+
+export const TELEMETRY_EVENT_DEFINITIONS = defineEventGroup<TelemetryEvent>({
+  "telemetry.appended": {
+    topic: "telemetry",
+    partitionKey: (payload) => `${payload.objectTypeId}:${payload.objectId}:${payload.propertyId}`,
+  },
+})
+
+export const LINK_EVENT_DEFINITIONS = defineEventGroup<LinkEvent>({
+  "link.created": {
+    topic: "links",
+    partitionKey: (payload) => `${payload.sourceTypeId}:${payload.sourceId}:${payload.linkId}`,
+  },
+  "link.updated": {
+    topic: "links",
+    partitionKey: (payload) => `${payload.sourceTypeId}:${payload.sourceId}:${payload.linkId}`,
+  },
+  "link.deleted": {
+    topic: "links",
+    partitionKey: (payload) => `${payload.sourceTypeId}:${payload.sourceId}:${payload.linkId}`,
+  },
+})
+
+export const ACTION_EVENT_DEFINITIONS = defineEventGroup<ActionEvent>({
+  "action.requested": {
+    topic: "actions",
+    partitionKey: (payload) => payload.actionId,
+  },
+  "action.completed": {
+    topic: "actions",
+    partitionKey: (payload) => payload.actionId,
+  },
+  "action.failed": {
+    topic: "actions",
+    partitionKey: (payload) => payload.actionId,
+  },
+})
+
+export const SCHEDULE_EVENT_DEFINITIONS = defineEventGroup<ScheduleEvent>({
+  "schedule.triggered": {
+    topic: "schedules",
+    partitionKey: (payload) => payload.scheduleId,
+  },
+})
+
+export const RULE_EVENT_DEFINITIONS = defineEventGroup<RuleEvent>({
+  "rule.triggered": {
+    topic: "rules",
+    partitionKey: (payload) =>
+      `${payload.ruleId}:${payload.subject.objectTypeId}:${payload.subject.primaryId}`,
+  },
+  "rule.resolved": {
+    topic: "rules",
+    partitionKey: (payload) =>
+      `${payload.ruleId}:${payload.subject.objectTypeId}:${payload.subject.primaryId}`,
+  },
+})
+
+export const SYNC_EVENT_DEFINITIONS = defineEventGroup<SyncEvent>({
+  "sync.run.started": {
+    topic: "syncs",
+    partitionKey: (payload) => `${payload.syncId}:${payload.runId}`,
+  },
+  "sync.run.finished": {
+    topic: "syncs",
+    partitionKey: (payload) => `${payload.syncId}:${payload.runId}`,
+  },
+})
+
+export const PIPELINE_EVENT_DEFINITIONS = defineEventGroup<PipelineEvent>({
+  "pipeline.run.started": {
+    topic: "pipelines",
+    partitionKey: (payload) => `${payload.pipelineId}:${payload.runId}`,
+  },
+  "pipeline.run.step.started": {
+    topic: "pipelines",
+    partitionKey: (payload) => `${payload.pipelineId}:${payload.runId}`,
+  },
+  "pipeline.run.step.finished": {
+    topic: "pipelines",
+    partitionKey: (payload) => `${payload.pipelineId}:${payload.runId}`,
+  },
+  "pipeline.run.finished": {
+    topic: "pipelines",
+    partitionKey: (payload) => `${payload.pipelineId}:${payload.runId}`,
+  },
+})
+
+export const WORKFLOW_EVENT_DEFINITIONS = defineEventGroup<WorkflowEvent>({
+  "workflow.run.queued": {
+    topic: "workflows",
+    partitionKey: (payload) => `${payload.workflowId}:${payload.runId}`,
+  },
+  "workflow.run.started": {
+    topic: "workflows",
+    partitionKey: (payload) => `${payload.workflowId}:${payload.runId}`,
+  },
+  "workflow.run.node.started": {
+    topic: "workflows",
+    partitionKey: (payload) => `${payload.workflowId}:${payload.runId}`,
+  },
+  "workflow.run.waiting": {
+    topic: "workflows",
+    partitionKey: (payload) => `${payload.workflowId}:${payload.runId}`,
+  },
+  "workflow.run.node.waiting": {
+    topic: "workflows",
+    partitionKey: (payload) => `${payload.workflowId}:${payload.runId}`,
+  },
+  "workflow.run.node.finished": {
+    topic: "workflows",
+    partitionKey: (payload) => `${payload.workflowId}:${payload.runId}`,
+  },
+  "workflow.run.finished": {
+    topic: "workflows",
+    partitionKey: (payload) => `${payload.workflowId}:${payload.runId}`,
+  },
+  "workflow.intervention.requested": {
+    topic: "workflows",
+    partitionKey: (payload) => `${payload.workflowId}:${payload.runId}`,
+  },
+  "workflow.intervention.submitted": {
+    topic: "workflows",
+    partitionKey: (payload) => `${payload.workflowId}:${payload.runId}`,
+  },
+  "workflow.intervention.cancelled": {
+    topic: "workflows",
+    partitionKey: (payload) => `${payload.workflowId}:${payload.runId}`,
+  },
+  "workflow.intervention.expired": {
+    topic: "workflows",
+    partitionKey: (payload) => `${payload.workflowId}:${payload.runId}`,
+  },
+})
+
+export const DATASET_EVENT_DEFINITIONS = defineEventGroup<DatasetEvent>({
+  "dataset.version.committed": {
+    topic: "datasets",
+    partitionKey: (payload) => payload.datasetId,
+  },
+})
+
+export const EVENT_DEFINITIONS = {
+  ...OBJECT_EVENT_DEFINITIONS,
+  ...TELEMETRY_EVENT_DEFINITIONS,
+  ...LINK_EVENT_DEFINITIONS,
+  ...ACTION_EVENT_DEFINITIONS,
+  ...SCHEDULE_EVENT_DEFINITIONS,
+  ...SYNC_EVENT_DEFINITIONS,
+  ...PIPELINE_EVENT_DEFINITIONS,
+  ...WORKFLOW_EVENT_DEFINITIONS,
+  ...DATASET_EVENT_DEFINITIONS,
+  ...RULE_EVENT_DEFINITIONS,
+} as const satisfies EventDefinitionMap
+
+export const EVENT_TYPES = Object.keys(EVENT_DEFINITIONS) as readonly DomainEvent["type"][]
+export const EVENT_TOPICS = [
+  ...new Set(
+    Object.values(EVENT_DEFINITIONS).map((definition): DomainEvent["topic"] => definition.topic)
+  ),
+] as readonly DomainEvent["topic"][]
+
+export function isDomainEventType(value: string): value is DomainEvent["type"] {
+  return Object.hasOwn(EVENT_DEFINITIONS, value)
+}
+
+export function isOntologyFactType(
+  value: string
+): value is ObjectEvent["type"] | LinkEvent["type"] | TelemetryEvent["type"] {
+  return (
+    Object.hasOwn(OBJECT_EVENT_DEFINITIONS, value) ||
+    Object.hasOwn(LINK_EVENT_DEFINITIONS, value) ||
+    Object.hasOwn(TELEMETRY_EVENT_DEFINITIONS, value)
+  )
+}
+
+export function getEventTopic(type: DomainEvent["type"]): DomainEvent["topic"] {
+  return EVENT_DEFINITIONS[type].topic
+}
+
+export function resolveEventStorage(event: DomainEventDraft): {
+  readonly topic: DomainEvent["topic"]
+  readonly partitionKey: string
+} {
+  const eventType = event.type as string
+  if (!isDomainEventType(eventType)) {
+    throw new EventsError(`Unknown event type: ${eventType}`)
+  }
+
+  const definition = EVENT_DEFINITIONS[eventType] as EventDefinition
+  return {
+    topic: definition.topic,
+    partitionKey: definition.partitionKey(event.payload),
+  }
+}