@sylphx/sdk 0.12.1 → 0.13.0

package/dist/health/index.d.ts

@@ -591,12 +591,10 @@ declare function evaluateEffect(evaluator: () => Promise<HealthScore>): Effect.E
  * (Hono / Bun.serve / itty-router / Next.js routes) or, via thin adapters,
  * a Node `(req, res) => void` (Express / Fastify-as-classic-handler).
  *
- * The handler always returns **HTTP 200** unless the SDK itself failed to
- * compute a score (rare; caught and returned as 500 for ops to triage).
- * The three-tier 200 / 503 gate (ADR-111 §4.4) lives in the **sidecar**,
- * not here — the SDK's job ends at exposing the score so the sidecar
- * can decide. This separation is documented in the README ("apps don't
- * need to think about probe semantics").
+ * The handler returns HTTP 200 for scores at or above the direct-probe
+ * liveness floor and HTTP 503 below it. The response body is always the
+ * complete HealthSnapshot, so the ADR-111 sidecar can still read the score
+ * even when direct kubelet probes need a status-coded failure.
  */
 
 /**
@@ -791,18 +789,17 @@ type HonoNextLike = () => Promise<void>;
  *
  * 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:
+ * shutdown. Wire `.dispose()` into the app entry point's existing
+ * graceful-shutdown coordinator.
  *
  * ```ts
  * const health = withHealth.hono()
  * app.use('*', health)
- * // From your app's signal-handler wiring:
- * //   onShutdown(() => health.dispose())
+ * registerShutdown(() => health.dispose())
  * ```
  */
 interface HonoHealthMiddleware {
-    (c: HonoContextLike, next: HonoNextLike): Promise<Response | void>;
+    (c: HonoContextLike, next: HonoNextLike): Promise<Response | undefined>;
     readonly health: SylphxHealth;
     dispose(): void;
 }
@@ -838,7 +835,7 @@ interface FastifyInstanceLike {
 interface FastifyReplyLike {
     code(code: number): FastifyReplyLike;
     header(name: string, value: string): FastifyReplyLike;
-    send(body?: unknown): FastifyReplyLike | Promise<FastifyReplyLike> | void;
+    send(body?: unknown): unknown;
 }
 interface FastifyHealthPlugin {
     (instance: FastifyInstanceLike, opts?: unknown): Promise<void>;

package/dist/health/index.mjs

@@ -18,14 +18,10 @@ async function tryLoadCausalityApi() {
   }
   return cachedApi;
 }
-function resolveServiceNameFromEnv(env) {
-  if (env.OTEL_SERVICE_NAME) return env.OTEL_SERVICE_NAME;
-  if (env.SERVICE_NAME) return env.SERVICE_NAME;
-  return "unknown";
-}
 function defaultServiceName() {
   if (typeof process !== "undefined" && process.env) {
-    return resolveServiceNameFromEnv(process.env);
+    if (process.env.OTEL_SERVICE_NAME !== void 0) return process.env.OTEL_SERVICE_NAME;
+    if (process.env.SERVICE_NAME !== void 0) return process.env.SERVICE_NAME;
   }
   return "unknown";
 }
@@ -203,12 +199,16 @@ function evaluateEffect(evaluator) {
 }
 
 // src/health/handler.ts
+var DIRECT_PROBE_LIVENESS_FLOOR = 0.5;
+function statusForScore(score) {
+  return Number.isFinite(score) && score >= DIRECT_PROBE_LIVENESS_FLOOR ? 200 : 503;
+}
 function createWebHandler(source) {
   return async (_req) => {
     try {
       const score = await source.evaluate();
       return new Response(JSON.stringify(score), {
-        status: 200,
+        status: statusForScore(score.score),
         headers: {
           "Content-Type": "application/json",
           // Cache-Control: never cache. Even 1-second cache on a
@@ -238,7 +238,7 @@ function createNodeHandler(source) {
   return async (_req, res) => {
     try {
       const score = await source.evaluate();
-      res.statusCode = 200;
+      res.statusCode = statusForScore(score.score);
       res.setHeader("Content-Type", "application/json");
       res.setHeader("Cache-Control", "no-store, no-cache, must-revalidate");
       res.end(JSON.stringify(score));
@@ -255,6 +255,8 @@ function createNodeHandler(source) {
 // src/health/history.ts
 var GENESIS_PREV_HASH = "0".repeat(64);
 var DEFAULT_HISTORY_CAPACITY = 1e3;
+var HASH_TEXT_ENCODER = new TextEncoder();
+var HEX_BYTE = Array.from({ length: 256 }, (_, i) => i.toString(16).padStart(2, "0"));
 function canonicalizeSignals(signals) {
   const keys = Object.keys(signals).sort();
   const pairs = keys.map((k) => {
@@ -271,12 +273,12 @@ async function sha256Hex(input) {
   if (!subtle || typeof subtle.digest !== "function") {
     return "";
   }
-  const buf = new TextEncoder().encode(input);
+  const buf = HASH_TEXT_ENCODER.encode(input);
   const digest = await subtle.digest("SHA-256", buf);
   const bytes = new Uint8Array(digest);
   let out = "";
   for (let i = 0; i < bytes.length; i++) {
-    out += (bytes[i] | 0).toString(16).padStart(2, "0");
+    out += HEX_BYTE[bytes[i]];
   }
   return out;
 }
@@ -379,7 +381,14 @@ var HistoryRecorderImpl = class {
     this.inFlight = job.catch(() => void 0);
     return await job;
   }
+  async drainPendingRecords() {
+    try {
+      await this.inFlight;
+    } catch {
+    }
+  }
   async range(query) {
+    await this.drainPendingRecords();
     try {
       return await this.store.range(query);
     } catch {
@@ -387,6 +396,7 @@ var HistoryRecorderImpl = class {
     }
   }
   async latest() {
+    await this.drainPendingRecords();
     try {
       return await this.store.latest();
     } catch {
@@ -766,9 +776,9 @@ function getEnvSocketPath() {
   const value = proc?.env?.SYLPHX_HEALTH_APP_SOCKET;
   return value && value.trim().length > 0 ? value.trim() : void 0;
 }
-function resolveSocketPath(explicit, envPath) {
-  if (explicit) return explicit;
-  if (envPath) return envPath;
+function resolveUnixSocketPath(inputPath, envPath) {
+  if (inputPath !== void 0) return inputPath;
+  if (envPath !== void 0) return envPath;
   return DEFAULT_SOCKET_PATH;
 }
 function resolveUnixSocketOption(input) {
@@ -781,7 +791,7 @@ function resolveUnixSocketOption(input) {
     return { path: envPath ?? DEFAULT_SOCKET_PATH, required: false };
   }
   return {
-    path: resolveSocketPath(input.path, envPath),
+    path: resolveUnixSocketPath(input.path, envPath),
     required: input.required ?? false,
     ...input.unlinkOnShutdown !== void 0 ? { unlinkOnShutdown: input.unlinkOnShutdown } : {}
   };
@@ -816,6 +826,7 @@ function honoHelper(opts = {}) {
   const middleware = (async (c, next) => {
     if (c.req.path === path) return respond();
     await health.runWithCause(() => next());
+    return void 0;
   });
   Object.defineProperty(middleware, "health", { value: health, enumerable: true });
   Object.defineProperty(middleware, "dispose", {