@sylphx/sdk 0.11.2 → 0.12.1

package/dist/health/index.d.ts

@@ -1,6 +1,372 @@
 import { Effect } from 'effect';
+import { Meter, Tracer } from '@opentelemetry/api';
 import { monitorEventLoopDelay } from 'node:perf_hooks';
 
+/**
+ * Audit-grade health history for `@sylphx/sdk/health` (ADR-144).
+ *
+ * Every `evaluate()` produces a tamper-evident `HistoryEntry` linked to
+ * the previous entry via a SHA-256 prev-hash chain (the same primitive
+ * AWS CloudTrail uses for digest-based log file integrity validation).
+ * Operators run `sylphx health verify` to walk the chain offline and
+ * detect any post-hoc tampering.
+ *
+ * # Storage is pluggable
+ *
+ * The SDK ships an `InMemoryHistoryStore` (ring buffer, FIFO eviction)
+ * as the reference implementation. Customers wanting compliance-grade
+ * durability (SOC 2 Type II, GDPR Article 32, HIPAA 164.312(b)) plug
+ * their own persistent `HistoryStore` — a thin interface that the SDK
+ * calls with each new entry. Adapter packages for Postgres / S3 / cold
+ * storage ship separately.
+ *
+ * # Cardinal rule (carried from ADR-141 / 142 / 143)
+ *
+ * Recording failures never throw upstream. The `/healthz` response is
+ * the load-bearing contract; the history record is observability
+ * augmentation. A store that throws during `append()` produces a logged
+ * warning (in dev) and is otherwise a no-op for that evaluation.
+ *
+ * # Wire format normative
+ *
+ * Per ADR-144 §3 — sorted-key canonical signal JSON, base16 SHA-256
+ * hashes, six-decimal-place score precision, `|` separator for the
+ * entry-hash preimage. Stable from day one.
+ */
+
+/**
+ * One tamper-evident history entry. The `prevHash` links to the previous
+ * entry's `entryHash`; entry 0 (`sequence === 0`) uses the genesis
+ * placeholder `"0".repeat(64)`. Stable wire shape — additive evolution
+ * only.
+ */
+interface HistoryEntry {
+    /** Monotonic, 0-indexed per service. */
+    readonly sequence: number;
+    /** ISO-8601 timestamp matching `HealthScore.lastTickAt`. */
+    readonly evaluatedAt: string;
+    /** Aggregate score in `[0, 1]`. */
+    readonly score: number;
+    /** Base16 SHA-256 of canonicalized signal map. */
+    readonly signalsDigest: string;
+    /** Base16 SHA-256 of previous entry's `entryHash` (`"0"*64` at sequence 0). */
+    readonly prevHash: string;
+    /** Base16 SHA-256 of `(sequence|evaluatedAt|score|signalsDigest|prevHash)`. */
+    readonly entryHash: string;
+}
+/** Query for `HistoryStore.range`. */
+interface HistoryQuery {
+    /** Inclusive lower sequence. Omit for "from the beginning available". */
+    readonly fromSequence?: number;
+    /** Inclusive upper sequence. Omit for "to the most recent". */
+    readonly toSequence?: number;
+    /** Inclusive lower timestamp (ISO-8601). */
+    readonly fromTimestamp?: string;
+    /** Inclusive upper timestamp (ISO-8601). */
+    readonly toTimestamp?: string;
+    /** Maximum entries returned. Implementations may cap further. */
+    readonly limit?: number;
+}
+/** Pluggable persistence adapter. Implementations may be sync or async. */
+interface HistoryStore {
+    /** Append one entry. MUST persist before resolving for compliance use. */
+    append(entry: HistoryEntry): Promise<void> | void;
+    /** Retrieve entries matching `query` in ascending sequence order. */
+    range(query: HistoryQuery): Promise<readonly HistoryEntry[]> | readonly HistoryEntry[];
+    /** Most recent entry, or null when empty. */
+    latest(): Promise<HistoryEntry | null> | HistoryEntry | null;
+    /** Optional capacity hint for ring-buffer stores. */
+    readonly capacity?: number;
+}
+/** Outcome of chain verification — `verified: false` always carries a reason. */
+interface VerificationResult {
+    readonly verified: boolean;
+    readonly entriesChecked: number;
+    readonly firstBreakAtSequence: number | null;
+    readonly reason: string | null;
+}
+/** Options for the in-memory reference store. */
+interface InMemoryHistoryStoreOptions {
+    /** Ring-buffer capacity. Default 1000. */
+    readonly capacity?: number;
+}
+/** Options for the recorder bound to a `sylphxHealth` instance. */
+interface HistoryRecorderOptions {
+    /** Underlying store. Defaults to `InMemoryHistoryStore`. */
+    readonly store?: HistoryStore;
+    /** Capacity passed to the default in-memory store. Default 1000. */
+    readonly capacity?: number;
+}
+/** The flag value passed via `sylphxHealth({ history })`. */
+type HistoryOption = boolean | HistoryRecorderOptions;
+/** Genesis prev-hash for the very first entry per service. */
+declare const GENESIS_PREV_HASH: string;
+/** Default ring-buffer size when callers don't override. */
+declare const DEFAULT_HISTORY_CAPACITY = 1000;
+/**
+ * Sorted-key JSON canonicalization. Same signals in different insertion
+ * order produce the same string — guarantees `signalsDigest` stability
+ * across V8 / Bun / browser JSON.stringify implementations.
+ */
+declare function canonicalizeSignals(signals: Record<string, number | string | boolean>): string;
+/** Build an in-memory ring-buffer history store. */
+declare function createInMemoryHistoryStore(opts?: InMemoryHistoryStoreOptions): HistoryStore;
+/**
+ * Records every `HealthScore` as a hash-chained entry. Owns a single
+ * `nextSequence` counter + the `prevHash` value carried forward across
+ * recordings. The recorder is per-instance (per-service); the chain is
+ * never shared across services.
+ */
+interface HistoryRecorder {
+    /** Backing store. Exposed for advanced callers (e.g. tests + verification). */
+    readonly store: HistoryStore;
+    /** Record one score. Resolves to the persisted entry (or null on failure). */
+    record(score: HealthScore): Promise<HistoryEntry | null>;
+    /** Convenience: store.range. */
+    range(query: HistoryQuery): Promise<readonly HistoryEntry[]>;
+    /** Convenience: store.latest. */
+    latest(): Promise<HistoryEntry | null>;
+    /**
+     * Verify the chain over a query window. Walks entries in sequence
+     * order, recomputing each `entryHash` and confirming it matches the
+     * next entry's `prevHash`. Returns the first break with a reason.
+     */
+    verify(query: HistoryQuery): Promise<VerificationResult>;
+    /** Tear down internal references. Idempotent. */
+    dispose(): void;
+}
+/** Build a recorder bound to a (defaulted) in-memory store. */
+declare function createHistoryRecorder(opts?: HistoryRecorderOptions): HistoryRecorder;
+/**
+ * Walk an ordered (by sequence) chain of entries, recomputing each
+ * `entryHash` and confirming it matches the next entry's `prevHash`.
+ * Returns the first break encountered.
+ *
+ * Edge cases:
+ *   - Empty input → `verified: true, entriesChecked: 0`. Vacuous truth.
+ *   - First entry has `prevHash !== GENESIS_PREV_HASH` AND `sequence === 0`
+ *     → break ("genesis prev-hash mismatch").
+ *   - First entry's `sequence > 0` but `prevHash === GENESIS_PREV_HASH`
+ *     → this is a sub-window query; we accept and chain forward from
+ *     `entries[0]`.
+ */
+declare function verifyChain(entries: ReadonlyArray<HistoryEntry>): Promise<VerificationResult>;
+
+/**
+ * Causality-aware health propagation for `@sylphx/sdk/health` (ADR-143).
+ *
+ * Reads + writes the OpenTelemetry Baggage entry `sylphx.health.cause`
+ * with value `<signal>@<service>[,<signal>@<service>...]` per ADR-143 §3.1.
+ * Append-only `sylphx.health.cause_chain` carries the hop chain so
+ * operators can reconstruct multi-hop incident paths.
+ *
+ * # Read side (downstream)
+ *
+ * On every `evaluate()`, the SDK reads `propagation.getActiveBaggage()`
+ * before computing the score. When the baggage carries an
+ * `sylphx.health.cause` entry, the resulting `HealthScore.upstreamCause`
+ * surfaces the parsed causes + chain. The OTel emitter then sets
+ * `service.health.cause_root` / `cause_signal` / `cause_chain` span
+ * attributes and increments the `health.downstream_cause` Counter.
+ *
+ * # Write side (upstream — the service whose signal is failing)
+ *
+ * `runWithCause(fn, score)` wraps an async function in a new OTel
+ * context where the cause baggage is set. Used by `withHealth.*`
+ * middleware to inject baggage on every non-/healthz request so that
+ * downstream calls within that request inherit the cause via standard
+ * OTel context propagation (W3C Baggage header on HTTP, native
+ * baggage on gRPC, queue metadata on Kafka/Cloud Tasks).
+ *
+ * # Graceful fallback
+ *
+ * `@opentelemetry/api` is an optional peer dependency (see ADR-142
+ * §2.3). When the dynamic import fails — or when the runtime exposes
+ * only a partial OTel API — the handle transitions to `'unavailable'`,
+ * every method becomes a no-op, and `runWithCause` runs the inner
+ * function with no context modification. The `/healthz` contract is
+ * unchanged in either case (ADR-143 §2.5 cardinal rule).
+ *
+ * # Cardinal rules (carried from ADR-141 / ADR-142)
+ *
+ * - Propagation never throws. Errors in `readCause`, `encodeCause`,
+ *   `runWithCause` are caught and downgraded to no-op behaviour.
+ * - The HTTP response shape is unchanged. Baggage is augmentation;
+ *   probe surface is the load-bearing contract.
+ */
+
+declare const BAGGAGE_KEY_CAUSE = "sylphx.health.cause";
+declare const BAGGAGE_KEY_CHAIN = "sylphx.health.cause_chain";
+/** Default threshold below which a signal triggers cause propagation. */
+declare const DEFAULT_CAUSE_THRESHOLD = 0.5;
+/** Maximum number of hops persisted in the chain baggage (ADR-143 §5). */
+declare const MAX_CHAIN_LENGTH = 5;
+/**
+ * The flag value passed by callers via `sylphxHealth({ causality })` /
+ * `withHealth.hono({ causality })`. `true` (default) enables propagation
+ * with sensible defaults; `false` disables it; an object configures it.
+ */
+type CausalityOption = boolean | CausalityOptions;
+interface CausalityOptions {
+    /**
+     * Below this signal factor, the SDK considers the signal "causing
+     * degradation" and emits a cause entry. Default: `0.5` — matches the
+     * ADR-111 kill threshold. Range: `(0, 1]`.
+     */
+    readonly threshold?: number;
+    /**
+     * Override the service name used in cause entries. Falls back to
+     * `process.env.OTEL_SERVICE_NAME` then `process.env.SERVICE_NAME`
+     * then `"unknown"`. Operators of multi-tenant runtimes typically
+     * override this per evaluator.
+     */
+    readonly serviceName?: string;
+    /**
+     * When true (default), the SDK appends the local service name to
+     * `sylphx.health.cause_chain` baggage so downstream operators can
+     * reconstruct multi-hop incident paths.
+     */
+    readonly propagateChain?: boolean;
+}
+/** Parsed view of an upstream cause read from baggage. */
+interface UpstreamCause {
+    /**
+     * The list of `<signal>@<service>` pairs carried in the baggage entry.
+     * Operators read `causes[0]` for the most-significant root; the full
+     * list preserves multi-cause concurrent failures.
+     */
+    readonly causes: ReadonlyArray<{
+        readonly signal: string;
+        readonly service: string;
+    }>;
+    /**
+     * The hop chain — services that observed this cause and forwarded it.
+     * Most recent service is at the tail. `chain.length === 0` means the
+     * baggage entry was just minted (no downstream services have observed
+     * it yet — typically only at the moment-of-incident origin).
+     */
+    readonly chain: ReadonlyArray<string>;
+}
+/** Operational handle the SDK uses to read + write cause baggage. */
+interface CausalityHandle {
+    /** Async loader state — exposed for tests + diagnostics. */
+    readonly state: 'loading' | 'ready' | 'unavailable' | 'disposed';
+    /** Read upstream cause from active OTel baggage. Returns null when absent. */
+    readCause(): UpstreamCause | null;
+    /**
+     * Encode the local cause string for baggage. Returns null when none of
+     * the signals' factors are below the configured threshold.
+     */
+    encodeCause(score: HealthScore): string | null;
+    /**
+     * Run `fn` within a new OTel context that has our cause + chain
+     * baggage entries set. Used by the middleware to inject baggage on
+     * every non-/healthz request. When OTel API is unavailable, this
+     * degrades to `fn()` directly.
+     */
+    runWithCause<T>(fn: () => T | Promise<T>, score: HealthScore): Promise<T>;
+    /** Tear down internal references. Idempotent. */
+    dispose(): void;
+}
+/**
+ * Build a causality handle. Returns a handle whose state starts at
+ * `'loading'`; emit / read operations are no-ops during loading. Once
+ * the dynamic import resolves, state transitions to `'ready'` (or
+ * `'unavailable'` when OTel API is absent).
+ */
+declare function createCausalityHandle(opts?: CausalityOptions): CausalityHandle;
+
+/**
+ * Static attributes the emitter merges onto every metric / event /
+ * span-attribute it produces. Use to stamp deployment metadata
+ * (`deployment.env`, `git.sha`, …) that the OTel resource detector
+ * doesn't pick up automatically.
+ */
+type OtelStaticAttributes = Readonly<Record<string, string | number | boolean>>;
+interface OtelEmitterOptions {
+    /**
+     * Pre-built OTel Meter. When provided, the emitter uses it directly and
+     * skips the async OTel API load. Common case: tests, sandboxes, multi-
+     * tenant runtimes wiring a custom MeterProvider per request.
+     */
+    readonly meter?: Meter;
+    /**
+     * Pre-built OTel Tracer. Same intent as `meter`. The emitter uses the
+     * tracer only to read the active span when setting attributes /
+     * events; it does not create new spans.
+     */
+    readonly tracer?: Tracer;
+    /**
+     * When true, the emitter records a `health.evaluated` span event on
+     * every evaluation (if a span is active). Default false — high-
+     * frequency probe paths produce many events and most operators only
+     * need the metric.
+     */
+    readonly events?: boolean;
+    /** Static attributes merged onto every emitted metric / span attribute. */
+    readonly attributes?: OtelStaticAttributes;
+}
+/**
+ * The flag value passed by callers via `sylphxHealth({ otel })` /
+ * `withHealth.hono({ otel })`. `true` (default) enables emission with
+ * sensible defaults; `false` disables it; an object configures it.
+ */
+type OtelOption = boolean | OtelEmitterOptions;
+interface OtelEmitter {
+    /**
+     * Emit metrics / span attributes / event for one HealthScore.
+     * `upstreamCause` (ADR-143) carries the parsed causality baggage so the
+     * emitter can record `health.downstream_cause` counter +
+     * `service.health.cause_*` span attributes. Non-throwing.
+     */
+    emit(score: HealthScore, upstreamCause?: UpstreamCause | null): void;
+    /**
+     * Tear down any cached instruments. Called from `sylphxHealth.dispose()`
+     * during graceful shutdown. The OTel SDK owns the underlying meter
+     * lifecycle; this method only releases the emitter's caches.
+     */
+    dispose(): void;
+    /** Readiness state — exposed for tests. `loading` is transient; `ready` and `unavailable` are terminal. */
+    readonly state: 'loading' | 'ready' | 'unavailable' | 'disposed';
+}
+/** Metric names — pinned by ADR-142 §3.1 + ADR-143 §3.3, stable from day one. */
+declare const METRIC_NAMES: {
+    readonly score: "health.score";
+    readonly signalFactor: "health.signal.factor";
+    readonly signalValue: "health.signal.value";
+    readonly signalValueState: "health.signal.value_state";
+    /** ADR-143 §3.3 — increments per evaluation when an upstream cause is observed. */
+    readonly downstreamCause: "health.downstream_cause";
+};
+/** Span attribute names — pinned by ADR-142 §2.1.3 + ADR-143 §3.2, stable from day one. */
+declare const SPAN_ATTRIBUTES: {
+    readonly score: "service.health.score";
+    readonly signalFactor: (name: string) => string;
+    /** ADR-143 §3.2 — the upstream service that originated the failure chain. */
+    readonly causeRoot: "service.health.cause_root";
+    /** ADR-143 §3.2 — the signal at the root that failed. */
+    readonly causeSignal: "service.health.cause_signal";
+    /** ADR-143 §3.2 — comma-delimited hop chain (oldest to newest). */
+    readonly causeChain: "service.health.cause_chain";
+};
+/** Span event name — pinned by ADR-142 §2.1.4. */
+declare const EVENT_NAMES: {
+    readonly evaluated: "health.evaluated";
+};
+/**
+ * Build an OTel emitter.
+ *
+ * Returns a sealed emitter object whose `emit()` is initially a no-op
+ * while the OTel API loads in the background. Once loaded, all subsequent
+ * `emit()` calls produce metrics / span attributes / events per ADR-142.
+ *
+ * When `@opentelemetry/api` is not installed in the host project (the
+ * common case for hobby projects), the emitter transitions to
+ * `unavailable` and all `emit()` calls remain no-ops for the lifetime of
+ * the instance. No exceptions, no warnings.
+ */
+declare function createOtelEmitter(opts?: OtelEmitterOptions): OtelEmitter;
+
 /**
  * Type SSOT for `@sylphx/sdk/health` (ADR-111 §4).
  *
@@ -81,6 +447,14 @@ type Signal = SyncSignal | AsyncSignal;
 interface HealthScore {
     readonly score: number;
     readonly signals: Record<string, number | string | boolean>;
+    /**
+     * Normalised per-signal health factors in [0, 1].
+     *
+     * Additive to the ADR-111 wire shape: existing readers can ignore it,
+     * while ADR-142 OTel emission uses it as the SSOT for
+     * `health.signal.factor`.
+     */
+    readonly signalFactors?: Record<string, number>;
     readonly lastTickAt: string;
 }
 /**
@@ -127,6 +501,48 @@ interface SylphxHealthOptions {
      * `lastTickAt` timestamps.
      */
     readonly now?: () => Date;
+    /**
+     * OpenTelemetry emission (ADR-142). When `true` (default), every
+     * `evaluate()` records `health.score` / `health.signal.*` metrics and
+     * sets `service.health.score` on the active span. `false` disables
+     * emission entirely. An object configures advanced behaviour (custom
+     * meter, span events, static attributes).
+     *
+     * Graceful fallback: if `@opentelemetry/api` is not installed in the
+     * host project, the emitter no-ops cleanly — no warning, no exception.
+     */
+    readonly otel?: OtelOption;
+    /**
+     * Causality-aware health propagation (ADR-143). When `true` (default),
+     * every `evaluate()` reads upstream cause from active OTel baggage
+     * and surfaces it on the metric stream (`health.downstream_cause`
+     * counter + `service.health.cause_root` span attribute). The
+     * `withHealth.*` middleware additionally writes the local cause into
+     * the request context baggage on every non-`/healthz` request so
+     * downstream services inherit causality via standard OTel
+     * propagation. `false` disables both read and write. An object
+     * tunes the threshold + service-name + chain behaviour.
+     *
+     * Graceful fallback: if `@opentelemetry/api` is not installed, the
+     * handle becomes `'unavailable'` and propagation is a no-op.
+     */
+    readonly causality?: CausalityOption;
+    /**
+     * Audit-grade health history (ADR-144). When `true` (default), every
+     * `evaluate()` records a tamper-evident `HistoryEntry` into the
+     * configured `HistoryStore` (default: in-memory ring buffer with
+     * capacity 1000). Entries form a SHA-256 prev-hash chain — operators
+     * (and compliance auditors) can replay the chain to detect post-hoc
+     * tampering.
+     *
+     * Set `false` to disable recording. Pass an object to plug a
+     * persistent store (Postgres / S3 / OpenSearch) or override capacity.
+     *
+     * The in-memory store is suitable for testing + low-stakes single-pod
+     * deployments. SOC 2 / GDPR / HIPAA compliance requires a persistent
+     * adapter; the interface is public and stable so any backend works.
+     */
+    readonly history?: HistoryOption;
 }
 
 /**
@@ -264,6 +680,205 @@ interface UnixSocketServerHandle {
     shutdown(): Promise<void>;
 }
 
+/**
+ * Framework middleware helpers for `@sylphx/sdk/health` (ADR-141 Phase 0).
+ *
+ * Zero-Config one-liners for the most common JS server frameworks. Each
+ * helper creates a `sylphxHealth()` instance internally and returns a
+ * framework-idiomatic middleware / plugin / handler that serves `/healthz`.
+ *
+ * For advanced control (custom signals, scoring strategies, Unix-socket
+ * IPC for the sidecar), import `sylphxHealth` directly — these helpers
+ * are wrappers around the same factory.
+ *
+ * @example Hono
+ * ```ts
+ * import { Hono } from 'hono'
+ * import { withHealth } from '@sylphx/sdk/health'
+ *
+ * const app = new Hono()
+ * app.use('*', withHealth.hono())
+ * ```
+ *
+ * @example Express
+ * ```ts
+ * import express from 'express'
+ * import { withHealth } from '@sylphx/sdk/health'
+ *
+ * const app = express()
+ * app.use(withHealth.express())
+ * ```
+ *
+ * @example Fastify
+ * ```ts
+ * import Fastify from 'fastify'
+ * import { withHealth } from '@sylphx/sdk/health'
+ *
+ * const fastify = Fastify()
+ * await fastify.register(withHealth.fastify())
+ * ```
+ *
+ * @example Bun.serve / Next.js / Deno / edge runtimes
+ * ```ts
+ * import { withHealth } from '@sylphx/sdk/health'
+ *
+ * const handleHealth = withHealth.fetch()
+ * Bun.serve({
+ *   port: 3000,
+ *   fetch(req) {
+ *     if (new URL(req.url).pathname === '/healthz') return handleHealth(req)
+ *     return new Response('hello')
+ *   },
+ * })
+ * ```
+ *
+ * Structural types are used for the framework signatures so this module
+ * has **zero peer dependencies** on Hono / Express / Fastify. The user's
+ * framework supplies the actual types at the call site via TypeScript's
+ * structural typing.
+ */
+
+/**
+ * Common options for every framework helper. Extends `SylphxHealthOptions`
+ * (signals, scoringStrategy, now) with a `path` override.
+ */
+interface WithHealthOptions extends SylphxHealthOptions {
+    /**
+     * HTTP path to serve the health endpoint on. Defaults to `/healthz` —
+     * the de-facto Kubernetes convention adopted by Spring Boot, FastAPI,
+     * and the IETF `application/health+json` draft.
+     */
+    readonly path?: string;
+    /**
+     * Pre-built `SylphxHealth` instance. When provided, options other than
+     * `path` are ignored and the helper just wires the instance up. Use
+     * this when you need to share one health instance across multiple
+     * frameworks (e.g. Hono middleware + Unix-socket IPC for the sidecar).
+     */
+    readonly instance?: SylphxHealth;
+    /**
+     * Bind the same health score on the sidecar IPC socket.
+     *
+     * Default: auto-enable when the platform injects
+     * `SYLPHX_HEALTH_APP_SOCKET` into the app container. This keeps the
+     * one-line helper enough for ADR-111 health-agent score polling while
+     * remaining a no-op on local/dev/edge runtimes without the env var.
+     *
+     * Set `false` to opt out, `true` to bind the default socket path, or
+     * pass `{ path, required }` for explicit control. `required` defaults
+     * to `false` so non-Bun runtimes never fail module import just because
+     * they share the public SDK.
+     */
+    readonly unixSocket?: boolean | {
+        readonly path?: string;
+        readonly required?: boolean;
+        readonly unlinkOnShutdown?: boolean;
+    };
+}
+/**
+ * Minimal structural type for a Hono request context. We only need
+ * `c.req.path` to decide whether the request hits the health endpoint.
+ */
+interface HonoContextLike {
+    readonly req: {
+        readonly path: string;
+    };
+}
+/** Hono `Next` is a parameterless async callback that yields to the next middleware. */
+type HonoNextLike = () => Promise<void>;
+/**
+ * Hono middleware that responds to `GET /healthz` and yields otherwise.
+ *
+ * The returned function carries a `.health` reference (the underlying
+ * `SylphxHealth` instance) and a `.dispose()` method for graceful
+ * shutdown. Wire `dispose()` into your existing SIGTERM handler so the
+ * SDK releases the event-loop-lag histogram + Unix socket on shutdown:
+ *
+ * ```ts
+ * const health = withHealth.hono()
+ * app.use('*', health)
+ * // From your app's signal-handler wiring:
+ * //   onShutdown(() => health.dispose())
+ * ```
+ */
+interface HonoHealthMiddleware {
+    (c: HonoContextLike, next: HonoNextLike): Promise<Response | void>;
+    readonly health: SylphxHealth;
+    dispose(): void;
+}
+declare function honoHelper(opts?: WithHealthOptions): HonoHealthMiddleware;
+/** Express-style request — only `url` is needed to match `/healthz`. */
+interface ExpressRequestLike {
+    readonly url?: string;
+    readonly method?: string;
+}
+/** Express-style response — subset required by the Node handler. */
+interface ExpressResponseLike {
+    statusCode: number;
+    setHeader(name: string, value: string): void;
+    end(body?: string): void;
+}
+/** Express-style next callback — called when the request is not for /healthz. */
+type ExpressNextLike = (err?: unknown) => void;
+interface ExpressHealthMiddleware {
+    (req: ExpressRequestLike, res: ExpressResponseLike, next: ExpressNextLike): void;
+    readonly health: SylphxHealth;
+    dispose(): void;
+}
+declare function expressHelper(opts?: WithHealthOptions): ExpressHealthMiddleware;
+/**
+ * Minimal structural type for a Fastify instance — only the `.get` route
+ * registration is needed. The plugin signature matches Fastify's
+ * encapsulated-plugin contract: `(instance, opts) => Promise<void>`.
+ */
+interface FastifyInstanceLike {
+    get(path: string, handler: (req: unknown, reply: FastifyReplyLike) => Promise<unknown> | unknown): unknown;
+}
+/** Minimal Fastify reply — subset required by the health response. */
+interface FastifyReplyLike {
+    code(code: number): FastifyReplyLike;
+    header(name: string, value: string): FastifyReplyLike;
+    send(body?: unknown): FastifyReplyLike | Promise<FastifyReplyLike> | void;
+}
+interface FastifyHealthPlugin {
+    (instance: FastifyInstanceLike, opts?: unknown): Promise<void>;
+    readonly health: SylphxHealth;
+    dispose(): void;
+}
+declare function fastifyHelper(opts?: WithHealthOptions): FastifyHealthPlugin;
+interface FetchHealthHandler {
+    (req?: Request): Promise<Response>;
+    readonly health: SylphxHealth;
+    dispose(): void;
+}
+declare function fetchHelper(opts?: WithHealthOptions): FetchHealthHandler;
+/**
+ * One-line health-check wiring for popular JS server frameworks.
+ *
+ * All helpers internally create a `sylphxHealth()` instance with sane
+ * defaults (single event-loop-lag signal) and serve `/healthz` returning
+ * the standard `HealthScore` JSON.
+ *
+ * Each returned helper exposes the underlying `SylphxHealth` instance
+ * via `.health` and a `.dispose()` shortcut for graceful shutdown.
+ *
+ * See `sylphxHealth()` for advanced use (custom signals, scoring, IPC).
+ */
+declare const withHealth: {
+    /** Hono middleware. Mount with `app.use('*', withHealth.hono())`. */
+    readonly hono: typeof honoHelper;
+    /** Express / Connect / Polka middleware. Mount with `app.use(withHealth.express())`. */
+    readonly express: typeof expressHelper;
+    /** Fastify plugin. Register with `await fastify.register(withHealth.fastify())`. */
+    readonly fastify: typeof fastifyHelper;
+    /**
+     * Pure Web Fetch handler. Works with Bun.serve, Next.js route
+     * handlers, Deno, Cloudflare Workers, and any other `Request →
+     * Response` runtime.
+     */
+    readonly fetch: typeof fetchHelper;
+};
+
 /**
  * Scoring strategies (ADR-111 §4 — three-tier health gate).
  *
@@ -485,6 +1100,87 @@ interface MemoryPressureOptions {
 }
 declare function memoryPressureSignal(opts?: MemoryPressureOptions): SyncSignal;
 
+/**
+ * `pingSignal` — generic binary readiness signal for any sub-system the
+ * service depends on (Postgres, Redis, Kafka, S3, an upstream API, …).
+ *
+ * The signal calls `ping()` every poll tick and reports:
+ *   - `healthFactor: 1` if the ping resolves (any value) within the timeout
+ *   - `healthFactor: 0` if the ping throws OR times out
+ *
+ * Binary — no partial-credit semantics. For richer scoring use a custom
+ * signal that returns a graded `healthFactor`; `pingSignal` is the
+ * canonical "subsystem reachable yes/no" primitive that 99% of dependency
+ * probes need.
+ *
+ * `databaseSignal` and `redisSignal` are thin convenience wrappers
+ * with idiomatic defaults for those two ubiquitous dependencies.
+ *
+ * @example Generic
+ * ```ts
+ * import { pingSignal } from '@sylphx/sdk/health'
+ *
+ * app.use('*', withHealth.hono({
+ *   signals: [
+ *     pingSignal({
+ *       name: 'upstream-api',
+ *       ping: async () => { await fetch('https://upstream.example/_ping') },
+ *     }),
+ *   ],
+ * }))
+ * ```
+ *
+ * @example Database + Redis
+ * ```ts
+ * import { withHealth, databaseSignal, redisSignal } from '@sylphx/sdk/health'
+ *
+ * app.use('*', withHealth.hono({
+ *   signals: [
+ *     databaseSignal({ ping: () => pool.query('SELECT 1') }),
+ *     redisSignal({ ping: () => redis.ping() }),
+ *   ],
+ * }))
+ * ```
+ */
+
+interface PingSignalOptions {
+    /** Stable signal name. Appears in the wire JSON `signals.<name>` map. */
+    readonly name: string;
+    /**
+     * Async function the SDK calls every poll tick. Resolve (any value) =
+     * healthy. Throw / reject = unhealthy. Timeout → unhealthy.
+     */
+    readonly ping: () => Promise<unknown>;
+    /**
+     * Per-tick timeout in milliseconds. Default 500ms — fast enough to
+     * fold into a `/healthz` response without holding the event loop, slow
+     * enough to avoid false negatives on a momentarily-slow dependency.
+     * Tune up for dependencies that legitimately take longer (e.g. S3 list).
+     */
+    readonly timeoutMs?: number;
+    /** Weight in the weighted-product score. Default 1.0. */
+    readonly weight?: number;
+}
+declare function pingSignal(opts: PingSignalOptions): AsyncSignal;
+interface DependencyPingOptions {
+    readonly ping: () => Promise<unknown>;
+    readonly timeoutMs?: number;
+    readonly weight?: number;
+    /** Override the signal name. Defaults to the subsystem name. */
+    readonly name?: string;
+}
+/**
+ * Postgres / SQL-database readiness — convenience over `pingSignal` with
+ * `name: 'database'`. Wrap the caller's `pool.query('SELECT 1')` or
+ * equivalent.
+ */
+declare function databaseSignal(opts: DependencyPingOptions): AsyncSignal;
+/**
+ * Redis / KV readiness — convenience over `pingSignal` with `name: 'redis'`.
+ * Wrap the caller's `redis.ping()` or equivalent.
+ */
+declare function redisSignal(opts: DependencyPingOptions): AsyncSignal;
+
 /**
  * `queueDepthSignal` — backpressure indicator (ADR-111 §4.3).
  *
@@ -558,6 +1254,12 @@ declare function queueDepthSignal(opts: QueueDepthOptions): AsyncSignal;
  *     "recent5sErrorRate": 0.001,
  *     "memoryPressure": 0.45
  *   },
+ *   "signalFactors": {
+ *     "eventLoopLagMs": 1,
+ *     "queueDepth": 0.8,
+ *     "recent5sErrorRate": 0.99,
+ *     "memoryPressure": 0.7
+ *   },
  *   "lastTickAt": "2026-05-03T12:34:56.789Z"
  * }
  * ```
@@ -619,63 +1321,40 @@ interface SylphxHealth extends HealthEvaluator {
      * polls `/var/run/sylphx/health.sock` by default (ADR-111 §3.2.4).
      */
     serveUnixSocket(opts?: UnixSocketServerOptions): UnixSocketServerHandle;
+    /**
+     * Most recent score returned by `evaluate()`. Returns null before
+     * the first evaluation. Used by `withHealth.*` middleware to inject
+     * cause baggage on non-probe requests (ADR-143).
+     */
+    getLastScore(): HealthScore | null;
+    /**
+     * Run `fn` within an OTel context that has our local cause baggage
+     * set, derived from the most recent `evaluate()`. When causality is
+     * disabled or the OTel API is unavailable, runs `fn()` directly.
+     * Middleware consumers don't usually call this — they let
+     * `withHealth.*` wire it automatically. Exposed for advanced users
+     * who build custom transport wrappers.
+     */
+    runWithCause<T>(fn: () => T | Promise<T>): Promise<T>;
+    /**
+     * Retrieve audit-grade history entries (ADR-144). Returns an empty
+     * array when history is disabled. Operators use this for compliance
+     * evidence + post-incident reconstruction.
+     */
+    getHistory(query?: HistoryQuery): Promise<readonly HistoryEntry[]>;
+    /**
+     * Verify the integrity of the recorded history chain over `query`
+     * (defaults to all available entries). Returns `verified: true`
+     * when the SHA-256 chain matches end-to-end; otherwise reports the
+     * first sequence where tampering is detected.
+     */
+    verifyHistory(query?: HistoryQuery): Promise<VerificationResult>;
     /**
      * Tear down all registered signals. Idempotent. Call during graceful
      * shutdown to release histograms, file watchers, etc.
      */
     dispose(): void;
 }
-/**
- * Build a `SylphxHealth` instance.
- *
- * @example Hono integration:
- * ```ts
- * import { Hono } from 'hono'
- * import {
- *   sylphxHealth,
- *   eventLoopLagSignal,
- *   queueDepthSignal,
- *   errorRateSignal,
- *   memoryPressureSignal,
- * } from '@sylphx/sdk/health'
- *
- * const errors = errorRateSignal({ window: '5s', degradedRate: 0.05 })
- *
- * const health = sylphxHealth({
- *   signals: [
- *     eventLoopLagSignal({ degradedMs: 5000, deadMs: 30000 }),
- *     queueDepthSignal({ getter: () => queue.size, fullThreshold: 1000 }),
- *     errors,
- *     memoryPressureSignal({ degradedRatio: 0.85 }),
- *   ],
- * })
- *
- * const app = new Hono()
- * app.get('/healthz', health.handler())
- *
- * // Track requests for the error-rate signal
- * app.use(async (c, next) => {
- *   try { await next(); errors.recordSuccess() }
- *   catch (err) { errors.recordError(); throw err }
- * })
- *
- * // Or — primary transport for the sidecar:
- * health.serveUnixSocket() // → /var/run/sylphx/health.sock
- * ```
- *
- * @example Worked example — OpenClaw under PDF-extract load (ADR-111 §4.5):
- *
- * ```text
- *   eventLoopLagMs = 6000 → factor 0.4
- *   queueDepth = 12       → factor 1.0
- *   errorRate = 0.002     → factor 1.0
- *   memoryPressure = 0.55 → factor 1.0
- *   score = 0.4^0.4 × 1.0^0.6 ≈ 0.69
- *
- *   → falls in [0.5, 0.8] → sidecar drains traffic, doesn't kill.
- *     Pod gets to finish PDF extraction.
- * ```
- */
 declare function sylphxHealth(opts?: SylphxHealthOptions): SylphxHealth;
 
-export { type AsyncSignal, type ErrorRateOptions, type ErrorRateSignalHandle, type EventLoopLagOptions, HealthError, type HealthEvaluator, type HealthScore, type HealthSnapshot, type MemoryPressureOptions, type QueueDepthOptions, type ScoringStrategy, type Signal, type SignalBase, type SignalReading, type SylphxHealth, type SylphxHealthOptions, type SyncSignal, type UnixSocketServerHandle, type UnixSocketServerOptions, createNodeHandler, createWebHandler, defaultScoringStrategy, errorRateSignal, eventLoopLagSignal, memoryPressureSignal, queueDepthSignal, sylphxHealth, weightedProduct };
+export { type AsyncSignal, BAGGAGE_KEY_CAUSE, BAGGAGE_KEY_CHAIN, type CausalityHandle, type CausalityOption, type CausalityOptions, DEFAULT_CAUSE_THRESHOLD, DEFAULT_HISTORY_CAPACITY, type DependencyPingOptions, type ErrorRateOptions, type ErrorRateSignalHandle, type EventLoopLagOptions, type ExpressHealthMiddleware, type ExpressNextLike, type ExpressRequestLike, type ExpressResponseLike, type FastifyHealthPlugin, type FastifyInstanceLike, type FastifyReplyLike, type FetchHealthHandler, GENESIS_PREV_HASH, HealthError, type HealthEvaluator, type HealthScore, type HealthSnapshot, type HistoryEntry, type HistoryOption, type HistoryQuery, type HistoryRecorder, type HistoryRecorderOptions, type HistoryStore, type HonoContextLike, type HonoHealthMiddleware, type HonoNextLike, type InMemoryHistoryStoreOptions, MAX_CHAIN_LENGTH, type MemoryPressureOptions, EVENT_NAMES as OTEL_EVENT_NAMES, METRIC_NAMES as OTEL_METRIC_NAMES, SPAN_ATTRIBUTES as OTEL_SPAN_ATTRIBUTES, type OtelEmitter, type OtelEmitterOptions, type OtelOption, type OtelStaticAttributes, type PingSignalOptions, type QueueDepthOptions, type ScoringStrategy, type Signal, type SignalBase, type SignalReading, type SylphxHealth, type SylphxHealthOptions, type SyncSignal, type UnixSocketServerHandle, type UnixSocketServerOptions, type UpstreamCause, type VerificationResult, type WithHealthOptions, canonicalizeSignals, createCausalityHandle, createHistoryRecorder, createInMemoryHistoryStore, createNodeHandler, createOtelEmitter, createWebHandler, databaseSignal, defaultScoringStrategy, errorRateSignal, eventLoopLagSignal, memoryPressureSignal, pingSignal, queueDepthSignal, redisSignal, sylphxHealth, verifyChain, weightedProduct, withHealth };