@sixb/core 0.0.1

package/src/logging/runtime.ts

@@ -0,0 +1,341 @@
+import type { Broker, BrokerRecord, BrokerRetention, BrokerStreamDefinition } from "../broker"
+import { getInvalidJsonValueReason, type JsonValue } from "../json"
+import { noopLoggerProvider } from "./console-logger"
+import { type LogPublisher, RunLogSession } from "./run-logger"
+import {
+  DEFAULT_LOG_BATCH_MAX_BYTES,
+  DEFAULT_LOG_BATCH_MAX_DELAY_MS,
+  DEFAULT_LOG_BATCH_MAX_RECORDS,
+  DEFAULT_LOG_MAX_BUFFERED_BYTES,
+  DEFAULT_LOGS_RETENTION,
+  DEFAULT_MAX_LINES_PER_EXECUTION,
+  DEFAULT_MAX_LOG_RECORD_BYTES,
+  LOGS_STREAM,
+} from "./stream"
+import {
+  isLogRecord,
+  LOG_LEVELS,
+  type LoggerProvider,
+  type LogLevel,
+  type LogRecord,
+  type LogRunRef,
+  SIXB_RUN_KINDS,
+  type SixbRunKind,
+  type StoredLogLine,
+} from "./types"
+
+export interface LogsPage {
+  readonly lines: readonly StoredLogLine[]
+  readonly cursor?: string
+  readonly hasMore: boolean
+}
+
+export interface LogsReadInput {
+  readonly afterCursor?: string
+  readonly limit?: number
+  readonly kinds?: readonly SixbRunKind[]
+  readonly levels?: readonly LogLevel[]
+  readonly run?: LogRunRef
+}
+
+export interface LogsTailInput {
+  readonly beforeCursor?: string
+  readonly limit?: number
+  readonly kinds?: readonly SixbRunKind[]
+  readonly levels?: readonly LogLevel[]
+  readonly run?: LogRunRef
+}
+
+export interface LogsSubscribeInput {
+  readonly from?: "latest" | "earliest"
+  readonly afterCursor?: string
+  readonly kinds?: readonly SixbRunKind[]
+  readonly levels?: readonly LogLevel[]
+  readonly run?: LogRunRef
+}
+
+export interface LogsObservabilityOptions {
+  /** Forward handler logs to the broker. Defaults to `true`. */
+  readonly enabled?: boolean
+  /** Minimum level captured by the broker. Defaults to `"info"`. */
+  readonly level?: LogLevel
+  /** Retention overrides merged with the bounded defaults. */
+  readonly retention?: BrokerRetention
+  /** Captured lines per worker execution. Defaults to 10,000. */
+  readonly maxLinesPerExecution?: number
+  readonly redact?: {
+    /** Dot paths relative to `fields` (an optional `fields.` prefix is accepted). */
+    readonly paths: readonly string[]
+    /** Replacement value. Defaults to `"[REDACTED]"`. */
+    readonly censor?: JsonValue
+  }
+}
+
+export interface ObservabilityOptions {
+  readonly logs?: LogsObservabilityOptions
+}
+
+export interface LogsRuntimeOptions {
+  readonly projectId: string
+  /** Broker backing the `__logs` stream. Absent means output-only logging. */
+  readonly broker?: Broker
+  /** Optional process-level output provider. Omit for broker-only logging. */
+  readonly logger?: LoggerProvider
+  readonly observability?: LogsObservabilityOptions
+  /** Internal/testing stream override. */
+  readonly stream?: BrokerStreamDefinition
+}
+
+/** Project-scoped logger factory and broker capture runtime. */
+export class LogsRuntime {
+  private readonly projectId: string
+  private readonly broker?: Broker
+  private readonly provider: LoggerProvider
+  private readonly captureEnabled: boolean
+  private readonly captureLevel: LogLevel
+  private readonly maxLinesPerExecution: number
+  private readonly redactPaths: readonly string[]
+  private readonly redactCensor: JsonValue
+  private readonly stream: BrokerStreamDefinition
+  private ensureStreamPromise?: Promise<void>
+
+  constructor(options: LogsRuntimeOptions) {
+    const config = options.observability ?? {}
+    this.projectId = options.projectId
+    this.broker = options.broker
+    this.provider = options.logger ?? noopLoggerProvider
+    this.captureEnabled = config.enabled ?? true
+    this.captureLevel = logLevel(config.level ?? "info", "observability.logs.level")
+    this.maxLinesPerExecution = nonNegativeInteger(
+      config.maxLinesPerExecution ?? DEFAULT_MAX_LINES_PER_EXECUTION,
+      "observability.logs.maxLinesPerExecution"
+    )
+    this.redactPaths = normalizeRedactPaths(config.redact?.paths ?? [])
+    this.redactCensor = config.redact?.censor ?? "[REDACTED]"
+    const censorReason = getInvalidJsonValueReason(
+      this.redactCensor,
+      "observability.logs.redact.censor"
+    )
+    if (censorReason) {
+      throw new TypeError(censorReason)
+    }
+
+    this.stream =
+      options.stream ??
+      ({
+        ...LOGS_STREAM,
+        retention: mergeLogsRetention(config.retention),
+      } satisfies BrokerStreamDefinition)
+  }
+
+  /** Start the single logger session owned by one worker execution. */
+  startExecution(run: LogRunRef): RunLogSession {
+    const publish = this.publisher()
+    return new RunLogSession({
+      run,
+      provider: this.provider,
+      capture: publish
+        ? {
+            publish,
+            level: this.captureLevel,
+            maxLinesPerExecution: this.maxLinesPerExecution,
+            maxRecordBytes: DEFAULT_MAX_LOG_RECORD_BYTES,
+            maxBufferedBytes: DEFAULT_LOG_MAX_BUFFERED_BYTES,
+            batchMaxRecords: DEFAULT_LOG_BATCH_MAX_RECORDS,
+            batchMaxBytes: DEFAULT_LOG_BATCH_MAX_BYTES,
+            batchMaxDelayMs: DEFAULT_LOG_BATCH_MAX_DELAY_MS,
+            redactPaths: this.redactPaths,
+            redactCensor: this.redactCensor,
+          }
+        : undefined,
+    })
+  }
+
+  async read(input: LogsReadInput = {}): Promise<LogsPage> {
+    if (!this.broker || (input.limit !== undefined && input.limit <= 0)) {
+      return { lines: [], cursor: input.afterCursor, hasMore: false }
+    }
+    await this.ensureStream()
+    const page = await this.broker.read({
+      projectId: this.projectId,
+      streamId: this.stream.id,
+      afterCursor: input.afterCursor,
+      limit: input.limit,
+      names: logRecordNames(input.kinds, input.levels, input.run),
+      keys: input.run ? [`${input.run.kind}:${input.run.id}`] : undefined,
+    })
+    return {
+      lines: page.records.map(hydrateLogRecord),
+      cursor: page.cursor,
+      hasMore: page.hasMore,
+    }
+  }
+
+  async tail(input: LogsTailInput = {}): Promise<LogsPage> {
+    if (!this.broker || (input.limit !== undefined && input.limit <= 0)) {
+      return { lines: [], cursor: input.beforeCursor, hasMore: false }
+    }
+    await this.ensureStream()
+    const page = await this.broker.tail({
+      projectId: this.projectId,
+      streamId: this.stream.id,
+      beforeCursor: input.beforeCursor,
+      limit: input.limit,
+      names: logRecordNames(input.kinds, input.levels, input.run),
+      keys: input.run ? [`${input.run.kind}:${input.run.id}`] : undefined,
+    })
+    return {
+      lines: page.records.map(hydrateLogRecord),
+      cursor: page.cursor,
+      hasMore: page.hasMore,
+    }
+  }
+
+  async subscribe(
+    input: LogsSubscribeInput,
+    handler: (lines: readonly StoredLogLine[]) => void
+  ): Promise<() => void> {
+    const broker = this.broker
+    if (!broker) {
+      return () => undefined
+    }
+    await this.ensureStream()
+    return broker.subscribe(
+      {
+        projectId: this.projectId,
+        streamId: this.stream.id,
+        from: input.from,
+        afterCursor: input.afterCursor,
+        names: logRecordNames(input.kinds, input.levels, input.run),
+        keys: input.run ? [`${input.run.kind}:${input.run.id}`] : undefined,
+      },
+      (records) => {
+        const lines = records.map(hydrateLogRecord)
+        if (lines.length === 0) return
+        try {
+          handler(lines)
+        } catch {
+          // Subscriber failures never break broker delivery.
+        }
+      }
+    )
+  }
+
+  /** Flush the process provider. Execution sessions never call this globally. */
+  async flush(): Promise<void> {
+    await this.provider.flush?.()
+  }
+
+  /** Close the process provider. Lifecycle ownership stays outside handler loggers. */
+  async close(): Promise<void> {
+    if (this.provider.close) {
+      await this.provider.close()
+      return
+    }
+    await this.provider.flush?.()
+  }
+
+  private publisher(): LogPublisher | undefined {
+    const broker = this.broker
+    if (!broker || !this.captureEnabled) {
+      return undefined
+    }
+    return async (records) => {
+      await this.ensureStream()
+      await broker.append({
+        projectId: this.projectId,
+        streamId: this.stream.id,
+        records: records.map((record) => ({
+          name: `${record.context.run.kind}.${record.level}`,
+          key: `${record.context.run.kind}:${record.context.run.id}`,
+          payload: record as unknown as JsonValue,
+        })),
+      })
+    }
+  }
+
+  private ensureStream(): Promise<void> {
+    const broker = this.broker
+    if (!broker) {
+      return Promise.resolve()
+    }
+    if (!this.ensureStreamPromise) {
+      this.ensureStreamPromise = broker
+        .ensureStream({ projectId: this.projectId, stream: this.stream })
+        .catch((error) => {
+          this.ensureStreamPromise = undefined
+          throw error
+        })
+    }
+    return this.ensureStreamPromise
+  }
+}
+
+/** Resolve a worker runtime, falling back to a silent output-only runtime. */
+export function resolveLogsRuntime(projectId: string, logs?: LogsRuntime): LogsRuntime {
+  return logs ?? new LogsRuntime({ projectId, logger: noopLoggerProvider })
+}
+
+function normalizeRedactPaths(paths: readonly string[]): readonly string[] {
+  const normalized = new Set<string>()
+  for (const path of paths) {
+    if (typeof path !== "string" || path.trim().length === 0) {
+      throw new TypeError("observability.logs.redact.paths must contain non-empty strings")
+    }
+    normalized.add(path.trim())
+  }
+  return [...normalized]
+}
+
+function mergeLogsRetention(retention: BrokerRetention | undefined): BrokerRetention {
+  return {
+    maxAgeMs: nonNegativeInteger(
+      retention?.maxAgeMs ?? DEFAULT_LOGS_RETENTION.maxAgeMs,
+      "observability.logs.retention.maxAgeMs"
+    ),
+    maxRecords: nonNegativeInteger(
+      retention?.maxRecords ?? DEFAULT_LOGS_RETENTION.maxRecords,
+      "observability.logs.retention.maxRecords"
+    ),
+    maxBytes: nonNegativeInteger(
+      retention?.maxBytes ?? DEFAULT_LOGS_RETENTION.maxBytes,
+      "observability.logs.retention.maxBytes"
+    ),
+  }
+}
+
+function logLevel(value: LogLevel, path: string): LogLevel {
+  if (value !== "debug" && value !== "info" && value !== "warn" && value !== "error") {
+    throw new TypeError(`${path} must be one of: debug, info, warn, error`)
+  }
+  return value
+}
+
+function nonNegativeInteger(value: number, path: string): number {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new TypeError(`${path} must be a non-negative safe integer`)
+  }
+  return value
+}
+
+function logRecordNames(
+  kinds: readonly SixbRunKind[] | undefined,
+  levels: readonly LogLevel[] | undefined,
+  run: LogRunRef | undefined
+): readonly string[] | undefined {
+  const selectedKinds = run ? [run.kind] : kinds
+  if ((!selectedKinds || selectedKinds.length === 0) && (!levels || levels.length === 0)) {
+    return undefined
+  }
+  const resolvedKinds = selectedKinds && selectedKinds.length > 0 ? selectedKinds : SIXB_RUN_KINDS
+  const resolvedLevels = levels && levels.length > 0 ? levels : LOG_LEVELS
+  return resolvedKinds.flatMap((kind) => resolvedLevels.map((level) => `${kind}.${level}`))
+}
+
+function hydrateLogRecord(record: BrokerRecord): StoredLogLine {
+  const payload = record.payload
+  if (!isLogRecord(payload)) {
+    throw new Error(`[Sixb] Broker record at cursor '${record.cursor}' is not a log line.`)
+  }
+  return { ...(payload as LogRecord), cursor: record.cursor }
+}

package/src/logging/stream.ts

@@ -0,0 +1,38 @@
+import type { BrokerStreamDefinition } from "../broker"
+
+/** 30 days in milliseconds — the age bound for retained log lines. */
+const THIRTY_DAYS_MS = 30 * 24 * 60 * 60 * 1000
+
+/** Default upper bound for the complete retained logs stream. */
+export const DEFAULT_LOGS_MAX_BYTES = 256 * 1024 * 1024
+
+/** Portable retention for the project-wide, ephemeral logs stream. */
+export const DEFAULT_LOGS_RETENTION = {
+  maxAgeMs: THIRTY_DAYS_MS,
+  maxRecords: 100_000,
+  maxBytes: DEFAULT_LOGS_MAX_BYTES,
+} as const
+
+/** The single project-wide broker stream that carries every run's log lines. */
+export const LOGS_STREAM: BrokerStreamDefinition = {
+  id: "__logs",
+  retention: DEFAULT_LOGS_RETENTION,
+}
+
+/** Maximum captured lines per worker execution, excluding its truncation marker. */
+export const DEFAULT_MAX_LINES_PER_EXECUTION = 10_000
+
+/** Maximum UTF-8 size of one serialized broker record payload. */
+export const DEFAULT_MAX_LOG_RECORD_BYTES = 64 * 1024
+
+/** Number of records that triggers an immediate broker append. */
+export const DEFAULT_LOG_BATCH_MAX_RECORDS = 64
+
+/** Serialized payload bytes that trigger an immediate broker append. */
+export const DEFAULT_LOG_BATCH_MAX_BYTES = 256 * 1024
+
+/** Maximum time a partial batch waits before being appended. */
+export const DEFAULT_LOG_BATCH_MAX_DELAY_MS = 10
+
+/** Maximum pending bytes while a previous broker append is in flight. */
+export const DEFAULT_LOG_MAX_BUFFERED_BYTES = 1024 * 1024

package/src/logging/types.ts

@@ -0,0 +1,156 @@
+import { isJsonValue, type JsonValue } from "../json"
+
+/** Log severity, ordered `debug < info < warn < error`. */
+export const LOG_LEVELS = ["debug", "info", "warn", "error"] as const
+export type LogLevel = (typeof LOG_LEVELS)[number]
+
+/** Structured, JSON-serializable fields attached by project code. */
+export type LogFields = Record<string, JsonValue>
+
+/**
+ * The logger surface exposed to project handlers.
+ *
+ * Calls are deliberately fire-and-forget: logging must never fail a handler.
+ * `child()` only binds user fields; framework-owned context stays immutable.
+ */
+export interface Logger {
+  debug(message: string, fields?: LogFields): void
+  info(message: string, fields?: LogFields): void
+  warn(message: string, fields?: LogFields): void
+  error(message: string | Error, fields?: LogFields): void
+  child(bindings: LogFields): Logger
+}
+
+/**
+ * Every kind of run Sixb records on a project's behalf.
+ *
+ * This is the one list: log lines, failed-run reports, and log stream selectors all name their
+ * producer from here. A kind is listed as soon as the run record exists, even when nothing writes logs
+ * for it yet — adding a writer later is additive, widening this union is not.
+ *
+ * The test is whether the thing has a run with an id. Rules do not: they are evaluated live, per
+ * subject, and Sixb keeps no record of an evaluation, which is why they are absent here and report
+ * through `SixbRuleEvaluationFailedContext` instead.
+ */
+export const SIXB_RUN_KINDS = [
+  "action",
+  "agent",
+  "pipeline",
+  "projection",
+  "sync",
+  "webhook",
+  "workflow",
+] as const
+export type SixbRunKind = (typeof SIXB_RUN_KINDS)[number]
+
+/** Points a log line back at the run that produced it. */
+export interface LogRunRef {
+  readonly kind: SixbRunKind
+  readonly id: string
+}
+
+/** Framework-owned metadata. It cannot be overwritten through `Logger.child()`. */
+export interface LogContext {
+  readonly run: LogRunRef
+  readonly stepId?: string
+  readonly phase?: string
+  readonly attempt?: number
+}
+
+/** One complete entry sent to the configured output provider. */
+export interface LogEntry {
+  readonly level: LogLevel
+  readonly message: string
+  readonly fields?: LogFields
+  /** ISO-8601 emission timestamp. */
+  readonly at: string
+  readonly context: LogContext
+}
+
+/** One sanitized, bounded log line stored in the `__logs` broker stream. */
+export type LogRecord = LogEntry
+
+/** A broker-backed log line tagged with its opaque stream cursor. */
+export type StoredLogLine = LogRecord & { readonly cursor: string }
+
+/**
+ * Process-level output destination. Providers own their lifecycle; handlers
+ * only receive the narrower {@link Logger} façade.
+ */
+export interface LoggerProvider {
+  write(entry: LogEntry): void
+  flush?(): void | Promise<void>
+  close?(): void | Promise<void>
+}
+
+/** True when `level` meets or exceeds the `threshold`. */
+export function isLevelEnabled(level: LogLevel, threshold: LogLevel): boolean {
+  const levelIndex = LOG_LEVELS.indexOf(level)
+  const thresholdIndex = LOG_LEVELS.indexOf(threshold)
+  return levelIndex >= 0 && thresholdIndex >= 0 && levelIndex >= thresholdIndex
+}
+
+/** Every log level at or above the threshold, in ascending severity order. */
+export function logLevelsAtOrAbove(threshold: LogLevel): readonly LogLevel[] {
+  const thresholdIndex = LOG_LEVELS.indexOf(threshold)
+  return thresholdIndex < 0 ? [] : LOG_LEVELS.slice(thresholdIndex)
+}
+
+export function isLogLevel(value: unknown): value is LogLevel {
+  return typeof value === "string" && (LOG_LEVELS as readonly string[]).includes(value)
+}
+
+export function isSixbRunKind(value: unknown): value is SixbRunKind {
+  return typeof value === "string" && (SIXB_RUN_KINDS as readonly string[]).includes(value)
+}
+
+export function isLogRecord(value: unknown): value is LogRecord {
+  return (
+    isRecord(value) &&
+    isLogLevel(value.level) &&
+    typeof value.message === "string" &&
+    typeof value.at === "string" &&
+    (value.fields === undefined || isLogFields(value.fields)) &&
+    isLogContext(value.context)
+  )
+}
+
+export function isStoredLogLine(value: unknown): value is StoredLogLine {
+  return isRecord(value) && isLogRecord(value) && typeof value.cursor === "string"
+}
+
+function isLogFields(value: unknown): value is LogFields {
+  return isRecord(value) && isJsonValue(value)
+}
+
+function isLogContext(value: unknown): value is LogContext {
+  return (
+    isRecord(value) &&
+    isRecord(value.run) &&
+    isSixbRunKind(value.run.kind) &&
+    typeof value.run.id === "string" &&
+    (value.stepId === undefined || typeof value.stepId === "string") &&
+    (value.phase === undefined || typeof value.phase === "string") &&
+    (value.attempt === undefined ||
+      (typeof value.attempt === "number" && Number.isFinite(value.attempt)))
+  )
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+/** Normalize an `error(message | Error)` call into a string message + fields. */
+export function normalizeLogError(
+  message: string | Error,
+  fields?: LogFields
+): { message: string; fields?: LogFields } {
+  if (message instanceof Error) {
+    const error: LogFields = { name: message.name }
+    if (message.stack !== undefined) {
+      error.stack = message.stack
+    }
+    return { message: message.message, fields: { ...fields, error } }
+  }
+  return { message, fields }
+}

package/src/maintenance/index.ts

@@ -0,0 +1,9 @@
+export { OntologyMaintenance } from "./ontology-maintenance"
+export type {
+  OntologyMaintenanceCleanupSnapshot,
+  OntologyMaintenanceHandle,
+  OntologyMaintenanceOptions,
+  OntologyMaintenanceSnapshot,
+  OntologyOperationalStatus,
+  SixbReadiness,
+} from "./types"