pipework 0.252.0 → 0.253.0

package/src/core/config/ts-resolve-hooks.ts

@@ -0,0 +1,101 @@
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { stripTypeScriptTypes } from 'node:module'
+
+// ESM loader hooks — run on a separate thread, so this file must be
+// self-contained: no static imports from the rest of pipework. The one
+// exception is `load`, which dynamically imports the flow-step transformer
+// (`../../trace/transformer/apply.js`) only for a file that mentions `@flow_step`.
+//
+// `resolve` rewrites a relative specifier to the TS file that actually backs
+// it (.js→.ts, and extensionless bundler-style imports); `load` fully transpiles
+// that TS — parameter properties, enums, namespaces and all — which
+// `--experimental-strip-types` cannot do. Together they let `pipework dev` and
+// config discovery run a consumer's real TypeScript source unbuilt.
+//
+// Mirrors the inline hook in `registerTsResolveHooks()` (discover.ts) for
+// `resolve` and for TS stripping. They stay separate on purpose: that one
+// registers a self-contained `data:` URL so it works during pipework's own
+// source-mode runs where this compiled `.js` file does not exist yet, and it
+// skips the `@flow_step` transform because config discovery has no steps; this
+// one is a real file loaded via `--import` into child processes (`pipework
+// dev`/`serve`), so it can reach the compiled transformer by relative URL.
+// Keep the `resolve` and strip logic of BOTH hooks in sync.
+//
+// The `.ts` candidate must exist on disk before we rewrite. `nextResolve` does
+// not touch the filesystem for file: URLs, so a missing file is not caught by a
+// try/catch — it surfaces later as a misleading "Cannot find module foo.ts" at
+// load time, even when foo.js sits right there (issue #292).
+export function resolve(
+  specifier: string,
+  context: { parentURL?: string },
+  nextResolve: (specifier: string, context: { parentURL?: string }) => { url: string },
+): { url: string } {
+  const parent = context.parentURL ?? ''
+  const isLocal = (specifier.startsWith('./') || specifier.startsWith('../'))
+    && !parent.includes('/node_modules/') && !parent.includes('/dist/')
+  if (isLocal) {
+    for (const candidate of tsCandidates(specifier)) {
+      let candidatePath: string | null = null
+      try {
+        const url = new URL(candidate, parent)
+        if (url.protocol === 'file:') candidatePath = fileURLToPath(url)
+      } catch {
+        // candidate did not form a valid URL — try the next one.
+      }
+      if (candidatePath !== null && existsSync(candidatePath)) {
+        return nextResolve(candidate, context)
+      }
+    }
+  }
+  return nextResolve(specifier, context)
+}
+
+// Ordered resolution candidates for a relative specifier authored in TS source.
+//   - `./foo.js`  → `./foo.ts`           (NodeNext style: import the emit name)
+//   - `./foo`     → .ts, .js, /index.ts, /index.js  (bundler-style extensionless)
+//   - `./foo.ts`  → []                   (already explicit — let the host resolve)
+// The caller probes each in order and rewrites to the first that exists on disk.
+function tsCandidates(specifier: string): string[] {
+  const jsMatch = specifier.match(/\.([cm]?)js$/)
+  if (jsMatch !== null) {
+    return [specifier.slice(0, -jsMatch[0].length) + '.' + (jsMatch[1] ?? '') + 'ts']
+  }
+  if (/\.[cm]?tsx?$/.test(specifier)) return []
+  return [specifier + '.ts', specifier + '.js', specifier + '/index.ts', specifier + '/index.js']
+}
+
+interface LoadResult {
+  format: string
+  source?: string | ArrayBuffer | NodeJS.TypedArray
+  shortCircuit?: boolean
+}
+
+// Installed by ts-register.js, which marks globalThis[Symbol.for('pipework.tsHooks')]
+// so discovery's inline hook (ts-inline-hooks.ts) is not registered over it.
+// `--experimental-strip-types` only erases annotations — it cannot emit the
+// runtime code that parameter properties, enums, or namespaces require, and it
+// rejects them outright (ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX). This `load` hook
+// does the full transform via Node's bundled `stripTypeScriptTypes` (amaro)
+// instead, so consumer TS using any of those features loads cleanly. Only
+// consumer source is transformed — pipework's own published code is compiled
+// `.js` and node_modules is left to the host loader.
+export async function load(
+  url: string,
+  context: { format?: string | null | undefined },
+  nextLoad: (url: string, context: { format?: string | null | undefined }) => LoadResult | Promise<LoadResult>,
+): Promise<LoadResult> {
+  if (url.endsWith('.ts') && !url.includes('/node_modules/')) {
+    let source = await readFile(fileURLToPath(url), 'utf8')
+    if (source.includes('@flow_step')) {
+      const { applyFlowStepTransform } = await import('../../trace/transformer/apply.js')
+      const applied = applyFlowStepTransform(source, fileURLToPath(url))
+      if (applied !== null) source = applied.code
+    }
+    const code = stripTypeScriptTypes(source, { mode: 'transform', sourceMap: true, sourceUrl: url })
+    return { format: 'module', source: code, shortCircuit: true }
+  }
+  return nextLoad(url, context)
+}
+

package/src/core/errors/base.ts

@@ -0,0 +1,49 @@
+// Cross-realm brand. The HTTP error mapper must recognize a PipeworkError thrown by a
+// shared leaf library that resolved a DIFFERENT physical copy of pipework — where the
+// two PipeworkError class objects are distinct and `instanceof` is false. A global
+// Symbol survives the realm boundary (the same pattern drizzle uses for entityKind),
+// so identity is keyed on the brand, never on the constructor.
+// Stryker disable next-line StringLiteral: static module-init constant; ignoreStatic makes the mutant
+// unreachable. Behavior is covered by tests/errors/brand.test.ts (cross-realm brand identity).
+const PIPEWORK_ERROR = Symbol.for('pipework.error')
+
+export abstract class PipeworkError extends Error {
+  abstract readonly code: string
+  abstract readonly httpStatus: number
+  readonly details: Record<string, unknown>
+
+  constructor(message: string, details: Record<string, unknown> = {}) {
+    super(message)
+    this.name = this.constructor.name
+    this.details = details
+    Object.defineProperty(this, PIPEWORK_ERROR, { value: true, enumerable: false })
+  }
+
+  // The brand is the identity across physical copies of pipework: a branded error is an
+  // instance of the class its prototype chain names, whichever copy constructed it.
+  static override [Symbol.hasInstance](value: unknown): boolean {
+    if (Function.prototype[Symbol.hasInstance].call(this, value)) return true
+    if (!isPipeworkError(value)) return false
+    if (this === PipeworkError) return true
+    for (let proto: unknown = Object.getPrototypeOf(value); proto !== null; proto = Object.getPrototypeOf(proto)) {
+      if ((proto as { constructor?: { name?: unknown } }).constructor?.name === this.name) return true
+    }
+    return false
+  }
+}
+
+/**
+ * True for any PipeworkError, including one thrown across a module-realm boundary
+ * (a shared library that resolved its own copy of pipework). Use this instead of
+ * `instanceof PipeworkError` anywhere an error may cross such a boundary — `instanceof`
+ * silently fails there, mapping a 403/401 to a generic 500.
+ */
+export function isPipeworkError(error: unknown): error is PipeworkError {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    (error as Record<symbol, unknown>)[PIPEWORK_ERROR] === true &&
+    typeof (error as { httpStatus?: unknown }).httpStatus === 'number' &&
+    typeof (error as { code?: unknown }).code === 'string'
+  )
+}

package/src/core/errors/http.ts

@@ -0,0 +1,146 @@
+import { PipeworkError } from './base.js'
+
+export class NotFoundError extends PipeworkError {
+  readonly code = 'NOT_FOUND' as const
+  readonly httpStatus = 404 as const
+
+  constructor(resource: string, details: Record<string, unknown> = {}) {
+    super(`${resource} not found`, details)
+  }
+}
+
+export class UnauthorizedError extends PipeworkError {
+  readonly code = 'UNAUTHORIZED' as const
+  readonly httpStatus = 401 as const
+
+  constructor(message: string = 'Authentication required', details: Record<string, unknown> = {}) {
+    super(message, details)
+  }
+}
+
+export class ForbiddenError extends PipeworkError {
+  readonly code = 'FORBIDDEN' as const
+  readonly httpStatus = 403 as const
+
+  constructor(message: string = 'Insufficient permissions', details: Record<string, unknown> = {}) {
+    super(message, details)
+  }
+}
+
+export class CrossSiteRequestError extends PipeworkError {
+  readonly code = 'CROSS_SITE_REQUEST' as const
+  readonly httpStatus = 403 as const
+
+  constructor(
+    message: string = 'A request authenticated by a cookie must come from the app\'s own site.',
+    details: Record<string, unknown> = {},
+  ) {
+    super(message, details)
+  }
+}
+
+/** Where the failing input came from: the request parts a route validates, or the handler's own response. */
+export type ValidationSource = 'body' | 'query' | 'params' | 'headers' | 'response'
+
+/** One failed check: the path to the field (empty for the root) and the schema's message. Never the input value. */
+export interface ValidationFieldIssue {
+  readonly source: ValidationSource | null
+  readonly path: readonly string[]
+  readonly message: string
+}
+
+export class ValidationError extends PipeworkError {
+  readonly code = 'VALIDATION_ERROR' as const
+  readonly httpStatus = 422 as const
+  readonly fieldErrors: Readonly<Record<string, readonly string[]>>
+  /** The part of the request that failed, when a schema check threw this; null for an error raised by hand. */
+  readonly source: ValidationSource | null
+  readonly issues: readonly ValidationFieldIssue[]
+
+  constructor(message: string)
+  constructor(fieldErrors: Record<string, readonly string[]>, message?: string, detail?: { source: ValidationSource; paths: ReadonlyArray<{ path: readonly string[]; message: string }> })
+  constructor(fieldErrorsOrMessage: Record<string, readonly string[]> | string, message?: string, detail?: { source: ValidationSource; paths: ReadonlyArray<{ path: readonly string[]; message: string }> }) {
+    if (typeof fieldErrorsOrMessage === 'string') {
+      super(fieldErrorsOrMessage, { fieldErrors: {} })
+      this.fieldErrors = {}
+      this.source = null
+      this.issues = []
+    } else {
+      const msg = message ?? 'Invalid input'
+      super(msg, { fieldErrors: fieldErrorsOrMessage })
+      this.fieldErrors = fieldErrorsOrMessage
+      this.source = detail?.source ?? null
+      this.issues = detail !== undefined
+        ? detail.paths.map(p => ({ source: detail.source, path: p.path, message: p.message }))
+        : Object.entries(fieldErrorsOrMessage).flatMap(([key, messages]) =>
+            messages.map(m => ({ source: null, path: key === '_root' ? [] : key.split('.'), message: m })))
+    }
+  }
+}
+
+export class TooManyRequestsError extends PipeworkError {
+  readonly code = 'TOO_MANY_REQUESTS' as const
+  readonly httpStatus = 429 as const
+  readonly retryAfterSeconds: number
+
+  constructor(retryAfterSeconds: number, message: string = 'Too many attempts. Try again later.') {
+    super(message, { retryAfterSeconds })
+    this.retryAfterSeconds = retryAfterSeconds
+  }
+}
+
+export class ConflictError extends PipeworkError {
+  readonly code = 'CONFLICT' as const
+  readonly httpStatus = 409 as const
+
+  constructor(message: string, details: Record<string, unknown> = {}) {
+    super(message, details)
+  }
+}
+
+
+export class PayloadTooLargeError extends PipeworkError {
+  readonly code = 'PAYLOAD_TOO_LARGE' as const
+  readonly httpStatus = 413 as const
+
+  constructor(message: string = 'Request body too large', details: Record<string, unknown> = {}) {
+    super(message, details)
+  }
+}
+
+export class UnsupportedMediaTypeError extends PipeworkError {
+  readonly code = 'UNSUPPORTED_MEDIA_TYPE' as const
+  readonly httpStatus = 415 as const
+
+  constructor(message: string = 'Unsupported media type', details: Record<string, unknown> = {}) {
+    super(message, details)
+  }
+}
+
+export class MalformedMultipartError extends PipeworkError {
+  readonly code = 'MALFORMED_MULTIPART' as const
+  readonly httpStatus = 400 as const
+
+  constructor(message: string = 'The multipart body is malformed or ends before its closing boundary', details: Record<string, unknown> = {}) {
+    super(message, details)
+  }
+}
+
+export class AuthConfigurationError extends PipeworkError {
+  readonly code = 'AUTH_CONFIGURATION' as const
+  readonly httpStatus = 500 as const
+
+  constructor(message: string, details: Record<string, unknown> = {}) {
+    super(message, details)
+  }
+}
+
+export class AuthUnavailableError extends PipeworkError {
+  readonly code = 'AUTH_UNAVAILABLE' as const
+  readonly httpStatus = 503 as const
+
+  constructor(message: string, options: { cause?: unknown; details?: Record<string, unknown> } = {}) {
+    super(message, options.details ?? {})
+    if (options.cause !== undefined) this.cause = options.cause
+  }
+}

package/src/core/errors/index.ts

@@ -0,0 +1,2 @@
+export { PipeworkError, isPipeworkError } from './base.js'
+export { NotFoundError, UnauthorizedError, ForbiddenError, CrossSiteRequestError, AuthConfigurationError, AuthUnavailableError, ValidationError, type ValidationSource, type ValidationFieldIssue, ConflictError, TooManyRequestsError, PayloadTooLargeError, UnsupportedMediaTypeError, MalformedMultipartError } from './http.js'

package/src/core/errors/namespace.ts

@@ -0,0 +1,31 @@
+import { PipeworkError, NotFoundError, UnauthorizedError, ForbiddenError, CrossSiteRequestError, AuthConfigurationError, AuthUnavailableError, ValidationError, ConflictError, TooManyRequestsError, PayloadTooLargeError, UnsupportedMediaTypeError, MalformedMultipartError } from './index.js'
+
+/** Standard error classes — all extend PipeworkError with structured error codes and actionable messages. */
+export const errors = {
+  /** Base error class with code, statusCode, and suggestion fields. */
+  Base: PipeworkError,
+  /** 404 — resource not found. */
+  NotFound: NotFoundError,
+  /** 401 — missing or invalid authentication. */
+  Unauthorized: UnauthorizedError,
+  /** 403 — authenticated but insufficient permissions. */
+  Forbidden: ForbiddenError,
+  /** 403 `CROSS_SITE_REQUEST` — a cookie-authenticated request that did not come from the app's own site. */
+  CrossSiteRequest: CrossSiteRequestError,
+  /** 500 `AUTH_CONFIGURATION` — the auth setup itself is faulty (a signing key that will not load); never a refusal of the caller. */
+  AuthConfiguration: AuthConfigurationError,
+  /** 503 `AUTH_UNAVAILABLE` — authentication could not be decided (its database failed); never read as signed out. */
+  AuthUnavailable: AuthUnavailableError,
+  /** 422 — input validation failed, carries field-level details. */
+  Validation: ValidationError,
+  /** 409 — resource state conflict (duplicate, version mismatch). */
+  Conflict: ConflictError,
+  /** 429 — too many attempts; carries `retryAfterSeconds`, sent in both the `Retry-After` header and the body's `error.retryAfterSeconds`. */
+  TooManyRequests: TooManyRequestsError,
+  /** 413 — request body over the route's size limit. */
+  PayloadTooLarge: PayloadTooLargeError,
+  /** 415 — request body media type not accepted by the route. */
+  UnsupportedMediaType: UnsupportedMediaTypeError,
+  /** 400 `MALFORMED_MULTIPART` — a multipart body that cannot be parsed or ends before its closing boundary. */
+  MalformedMultipart: MalformedMultipartError,
+}

package/src/core/lifecycle/drain.ts

@@ -0,0 +1,33 @@
+import type { FastifyInstance } from 'fastify'
+
+export interface DrainState {
+  readonly inFlight: () => number
+  readonly waitForDrain: (timeoutMs: number) => Promise<void>
+}
+
+export function setupDrain(app: FastifyInstance): DrainState {
+  let count = 0
+
+  app.addHook('onRequest', () => { count++; return Promise.resolve() })
+  app.addHook('onResponse', () => { count--; return Promise.resolve() })
+
+  return {
+    inFlight: () => count,
+    waitForDrain: (timeoutMs: number) => new Promise<void>((resolve, reject) => {
+      if (count === 0) return resolve()
+
+      const deadline = setTimeout(() => {
+        clearInterval(poll)
+        reject(new Error(`[pipework] Drain timeout: ${count} requests still in-flight after ${timeoutMs}ms`))
+      }, timeoutMs)
+
+      const poll = setInterval(() => {
+        if (count === 0) {
+          clearTimeout(deadline)
+          clearInterval(poll)
+          resolve()
+        }
+      }, 50)
+    }),
+  }
+}

package/src/core/lifecycle/health.ts

@@ -0,0 +1,72 @@
+import type { FastifyInstance } from 'fastify'
+import type { Manifold } from '../pipework.js'
+import type { HealthCheck, HealthCheckResult, HealthStatus } from './types.js'
+import { sql } from '../../data/db/sql.js'
+
+const startedAt = Date.now()
+
+export function registerHealthRoutes(
+  app: FastifyInstance,
+  instance: Manifold,
+  checks: readonly HealthCheck[],
+  paths: { health: string; ready: string },
+): void {
+  app.get(paths.health, async (_req, reply) => {
+    return reply.status(200).send({ status: 'healthy', release: instance.release, uptime: Date.now() - startedAt })
+  })
+
+  app.get(paths.ready, async (_req, reply) => {
+    const results: Record<string, HealthCheckResult> = {}
+    let overall: HealthStatus['status'] = 'healthy'
+
+    const dbChecks = await checkDatabases(instance)
+    for (const [name, result] of Object.entries(dbChecks)) {
+      results[name] = result
+      if (result.status === 'unhealthy') overall = 'unhealthy'
+      else if (result.status === 'degraded' && overall !== 'unhealthy') overall = 'degraded'
+    }
+
+    for (const check of checks) {
+      const start = Date.now()
+      try {
+        const result = await check.check()
+        results[check.name] = { ...result, latencyMs: result.latencyMs ?? (Date.now() - start) }
+        if (result.status === 'unhealthy') overall = 'unhealthy'
+        else if (result.status === 'degraded' && overall !== 'unhealthy') overall = 'degraded'
+      } catch (err) {
+        results[check.name] = {
+          status: 'unhealthy',
+          message: err instanceof Error ? err.message : 'check failed',
+          latencyMs: Date.now() - start,
+        }
+        overall = 'unhealthy'
+      }
+    }
+
+    const status: HealthStatus = { status: overall, release: instance.release, uptime: Date.now() - startedAt, checks: results }
+    return reply.status(overall === 'unhealthy' ? 503 : 200).send(status)
+  })
+}
+
+async function checkDatabases(instance: Manifold): Promise<Record<string, HealthCheckResult>> {
+  const results: Record<string, HealthCheckResult> = {}
+  const dbNames = instance.config.databaseNames()
+
+  for (const name of dbNames) {
+    const start = Date.now()
+    try {
+      const dbConfig = instance.config.database(name)
+      const conn = instance.pool.getOrCreate(dbConfig)
+      await conn.drizzle.execute(sql`SELECT 1`)
+      results[`db:${name}`] = { status: 'healthy', latencyMs: Date.now() - start }
+    } catch (err) {
+      results[`db:${name}`] = {
+        status: 'unhealthy',
+        message: err instanceof Error ? err.message : 'connection failed',
+        latencyMs: Date.now() - start,
+      }
+    }
+  }
+
+  return results
+}

package/src/core/lifecycle/index.ts

@@ -0,0 +1,4 @@
+export { orchestrateStartup, type StartupOptions } from './startup.js'
+export { registerHealthRoutes } from './health.js'
+export { setupDrain, type DrainState } from './drain.js'
+export type { LifecycleConfig, StartupHook, ShutdownHook, HealthCheck, HealthCheckResult, HealthStatus } from './types.js'

package/src/core/lifecycle/namespace.ts

@@ -0,0 +1,7 @@
+import { orchestrateStartup } from './startup.js'
+
+/** Application lifecycle namespace — startup orchestration with hooks and timeouts. */
+export const lifecycle = {
+  /** Runs pre-start hooks (DB readiness checks, migrations, etc.) with a configurable timeout. The hooks run in one trace that names the process; the trace-partition hook runs first, outside it. */
+  orchestrate: orchestrateStartup,
+}

package/src/core/lifecycle/startup.ts

@@ -0,0 +1,102 @@
+import { randomUUID } from 'node:crypto'
+import { sql } from '../../data/db/sql.js'
+import type { Manifold } from '../pipework.js'
+import type { StartupHook } from './types.js'
+import { getBaseLogger } from '../logging/index.js'
+import { runScript } from '../../async/jobs/run-script.js'
+import { getContext } from '../../request/context/store.js'
+import { TRACE_PARTITION_HOOK_NAME } from '../../trace/partition/startup-hook.js'
+import { projectStepError } from '../../trace/runtime/step-error.js'
+import { serializeForTrace } from '../../trace/capture/bounded-serializer.js'
+
+export interface StartupOptions {
+  readonly hooks?: readonly StartupHook[]
+  readonly timeoutMs?: number
+}
+
+export async function orchestrateStartup(instance: Manifold, options: StartupOptions = {}): Promise<void> {
+  const logger = getBaseLogger()
+  const timeoutMs = options.timeoutMs ?? 30000
+
+  const doStartupWork = async () => {
+    await verifyDatabases(instance, logger)
+
+    if (options.hooks) {
+      // The partition hook creates today's trace partition, so it runs first and outside the trace.
+      const partition = options.hooks.filter(h => h.name === TRACE_PARTITION_HOOK_NAME)
+      const rest = options.hooks.filter(h => h.name !== TRACE_PARTITION_HOOK_NAME)
+      for (const hook of partition) await runHook(hook)
+      if (rest.length > 0) {
+        await runScript(instance, async () => {
+          for (const hook of rest) await runTracedHook(hook)
+        }, { jobType: 'start', process: { phase: 'preStart', surfaces: instance.surfaceNames() } })
+      }
+    }
+  }
+
+  const runHook = async (hook: StartupHook) => {
+    logger.info({ hook: hook.name }, 'Running pre-start hook')
+    await hook.execute()
+  }
+
+  const runTracedHook = async (hook: StartupHook) => {
+    const startedAt = new Date()
+    const t0 = process.hrtime.bigint()
+    const stage = (error: unknown): void => {
+      const trace = getContext()?.trace
+      if (trace === undefined || trace === null) return
+      trace.buffer.stageExternal({
+        id: randomUUID(),
+        parentStepId: null,
+        flowStepRef: 'external:pipework.start.hook',
+        status: error === undefined ? 'ok' : 'error',
+        startedAt,
+        completedAt: new Date(),
+        durationMicros: (process.hrtime.bigint() - t0) / 1000n,
+        capturedInputs: [serializeForTrace({ hook: hook.name })],
+        error: error === undefined ? null : projectStepError(error),
+      })
+    }
+    try {
+      await runHook(hook)
+    } catch (err) {
+      stage(err)
+      throw err
+    }
+    stage(undefined)
+  }
+
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error(
+        `[pipework] Startup timed out after ${timeoutMs}ms.\n\n` +
+        '  This usually means a database is unreachable or a pre-start hook is hanging.\n' +
+        '  Check your DATABASE_URL values and network connectivity.\n'
+      ))
+    }, timeoutMs)
+    timer.unref()
+  })
+
+  await Promise.race([doStartupWork(), timeoutPromise])
+}
+
+async function verifyDatabases(instance: Manifold, logger: { info(obj: Record<string, unknown>, msg?: string): void }): Promise<void> {
+  const dbNames = instance.config.databaseNames()
+
+  for (const name of dbNames) {
+    const dbConfig = instance.config.database(name)
+    const conn = instance.pool.getOrCreate(dbConfig)
+    try {
+      await conn.drizzle.execute(sql`SELECT 1`)
+      logger.info({ database: name }, 'Database connectivity verified')
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      throw new Error(
+        `[pipework] Cannot connect to database "${name}".\n\n` +
+        `  URL: ${dbConfig.url.replace(/\/\/[^@]+@/, '//***@')}\n` +
+        `  Error: ${message}\n\n` +
+        '  Check that the database is running and the URL is correct.\n'
+      )
+    }
+  }
+}

package/src/core/lifecycle/types.ts

@@ -0,0 +1,36 @@
+export interface LifecycleConfig {
+  readonly preStart?: readonly StartupHook[]
+  readonly preShutdown?: readonly ShutdownHook[]
+  readonly healthChecks?: readonly HealthCheck[]
+  readonly drainTimeoutMs?: number
+  readonly startupTimeoutMs?: number
+}
+
+export interface StartupHook {
+  readonly name: string
+  execute(): Promise<void>
+}
+
+export interface ShutdownHook {
+  readonly name: string
+  execute(): Promise<void>
+}
+
+export interface HealthCheck {
+  readonly name: string
+  check(): Promise<HealthCheckResult>
+}
+
+export interface HealthCheckResult {
+  readonly status: 'healthy' | 'degraded' | 'unhealthy'
+  readonly message?: string
+  readonly latencyMs?: number
+}
+
+export interface HealthStatus {
+  readonly status: 'healthy' | 'degraded' | 'unhealthy'
+  /** The release this process runs (`manifold.release`); null when none is configured or set. */
+  readonly release: string | null
+  readonly uptime: number
+  readonly checks: Record<string, HealthCheckResult>
+}

package/src/core/logging/context.ts

@@ -0,0 +1,60 @@
+import { getContext } from '../../request/context/store.js'
+import { getLoggingConfig } from './logger.js'
+import type { ContextField } from './types.js'
+
+export interface CorrelationFields {
+  requestId?: string
+  tenantId?: string
+  userId?: string
+  sessionId?: string
+  traceId?: string
+  jobType?: string
+  [key: string]: string | undefined
+}
+
+export function getCorrelationFields(): CorrelationFields {
+  const ctx = getContext()
+  if (!ctx) return {}
+
+  const config = getLoggingConfig()
+  const enabled = config?.contextFields
+
+  const fields: CorrelationFields = {}
+
+  if (isEnabled('requestId', enabled) && ctx.requestId !== '') {
+    fields.requestId = ctx.requestId
+  }
+  if (isEnabled('tenantId', enabled) && ctx.tenant !== null) {
+    fields.tenantId = ctx.tenant
+  }
+  if (isEnabled('userId', enabled) && ctx.auth !== null && typeof ctx.auth === 'object' && 'userId' in ctx.auth) {
+    const userId = (ctx.auth as { userId: unknown }).userId
+    if (typeof userId === 'string') fields.userId = userId
+  }
+  if (isEnabled('sessionId', enabled) && ctx.metadata?.sessionId != null) {
+    fields.sessionId = ctx.metadata.sessionId
+  }
+  if (isEnabled('traceId', enabled) && ctx.metadata?.traceId != null) {
+    fields.traceId = ctx.metadata.traceId
+  }
+  if (ctx.jobType !== null) {
+    fields.jobType = ctx.jobType
+  }
+
+  if (config?.authFields != null && ctx.auth !== null && typeof ctx.auth === 'object') {
+    const auth = ctx.auth as Record<string, unknown>
+    for (const field of config.authFields) {
+      const value = auth[field]
+      if (typeof value === 'string') {
+        fields[field] = value
+      }
+    }
+  }
+
+  return fields
+}
+
+function isEnabled(field: ContextField, enabled: readonly ContextField[] | undefined): boolean {
+  if (enabled === undefined) return true
+  return enabled.includes(field)
+}