@apifuse/provider-sdk 2.2.0-beta.69 → 2.2.0-beta.70

package/AUTHORING.md

@@ -167,6 +167,23 @@ only for a provider already pinned to an SDK release that serves the route.
 Earlier pins answer `404`, and a failing readiness/startup probe is not
 self-healing, so manifests move to `/readyz` after the pin wave, never before.
 
+`GET /__apifuse/diagnostics/runtime` is the internal runtime diagnostics route on
+the same listener. It answers one JSON report (`schemaVersion: 1`) sampled over a
+short window (`?windowMs=`, default 250, clamped to 50..5000): `cpu.window`
+(`process.cpuUsage()` delta as cores, user/system split), `cpu.lifetime`,
+`memory`, `eventLoop` (`performance.eventLoopUtilization`), `activeResources`
+(`process.getActiveResourcesInfo()` counts by type) and, on Linux, `procfs`
+with per-thread CPU ticks, context switches, wait channel and file-descriptor
+counts by kind from `/proc/self`. Bun 1.2 and 1.3 stub the two Node APIs, so
+their `reported` flag is `false` there; `cpu.window` and `procfs.threads`
+(sorted hottest first, named `bun`, `HTTP Client`, `HeapHelper`, ...) are the
+signals that tell an idle process that still burns CPU apart from a busy one.
+The route is read-only and carries no secrets. It is internal by the same
+boundary as `/health` and `/readyz`: the generated provider NetworkPolicy admits
+only the gateway on this port and the gateway dials canonical operation paths
+only, so operators reach it with `kubectl port-forward` and the tenant-facing
+API never does.
+
 ### Deployment intent
 
 Deployment intent (runtime profile, resources, HPA, Redis, extra TCP ports) has

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.70
+
+- Release candidate for main commit 429f8f7658812835aa4ca1465ef682c2934dfe3e.
+
 ## 2.2.0-beta.69
 
 - Release candidate for main commit 0f4bd33ef5bd41cb6813005e923abf4324158582.

package/README.md

@@ -40,6 +40,8 @@ Do not use internal monorepo placement for bounty workspaces. Accepted provider
 - Dev default: `3900`
 - Start/Docker/container contract: `3000`
 - `GET /health`
+- `GET /readyz`
+- `GET /__apifuse/diagnostics/runtime` (internal runtime diagnostics, see `AUTHORING.md`)
 - `POST /v1/{operation}`
 - `POST /auth/start`
 - `POST /auth/continue`

package/dist/cli/templates/provider/.agents/skills/health-checks-and-fail-closed/SKILL.md.tpl

@@ -116,7 +116,7 @@ Add ONE guard step per stale-if-error probe:
       {
         operationId: "list-items",
         status: "degraded",
-        reasonCode: "expected_absence",
+        reasonCode: "served_stale_cache",
         reasonKey: "health.operations.list-items.dense-district.servedStaleCache",
       },
     ],
@@ -128,9 +128,12 @@ Add ONE guard step per stale-if-error probe:
 - `degraded`, not `down`: the cache policy is behaving as promised and callers
   are still served; it is the upstream that is unavailable, and that has to be
   visible instead of green.
-- `expected_absence` is the only `reasonCode` the guard attribution schema
-  admits today, and it reads correctly here — the FRESH read is what was
-  absent. The tenant-facing wording lives in the localized `reasonKey`.
+- `served_stale_cache`, not `expected_absence`: the platform publishes a
+  stale serve as `degraded` (an upstream fault that opens incidents), while
+  `expected_absence` is published as a non-incident status — neither ok nor
+  degraded, excluded from uptime — for an absence the provider declares in
+  advance (no alert today, a closed shelf, a feed outside its hours). The
+  tenant-facing wording lives in the localized `reasonKey`.
 - Place the freshness guard BEFORE any row or emptiness guard. A stale serve
   that happens to be empty would otherwise be attributed to the emptiness
   reason, which is a confident answer to the wrong question.

package/dist/health-scenario.d.ts

@@ -1549,7 +1549,25 @@ export type StepBase = {
     result: string;
     timeoutMs?: number;
 };
-export type GuardReasonCode = "expected_absence";
+/**
+ * Why a guard stopped the scenario. The platform decides what each reason
+ * publishes; the attribution's `status` is only the scenario rollup.
+ *
+ * - `expected_absence`: the upstream answered exactly as this provider says it
+ *   does when there is nothing to return — no weather alert today, an empty
+ *   shelf, a transit feed outside its operating hours. Published as the
+ *   non-incident status `expected_absence`: neither ok nor degraded, excluded
+ *   from uptime, never an incident. Use it only for an absence the provider
+ *   can declare in advance. Data that must be there (a product that must have
+ *   options) is a failing assertion, not an expected absence.
+ * - `served_stale_cache`: the operation step was answered from the
+ *   stale-if-error window (`served_stale_cache` on the step result) instead
+ *   of a live read. A measured upstream verdict: published `degraded`, opens
+ *   incidents.
+ */
+export type GuardReasonCode = "expected_absence" | "served_stale_cache";
+/** The closed vocabulary as a non-empty tuple, for schema and lint consumers. */
+export declare const GUARD_REASON_CODES: [GuardReasonCode, ...GuardReasonCode[]];
 export type GuardAttribution = {
     operationId: string;
     status: "degraded";
@@ -1579,7 +1597,10 @@ export type OperationResult = {
      * fails the step rather than projecting as fresh.
      *
      * Providers that serve stale-if-error should guard on it, so an outage the
-     * cache is absorbing stops reading as green:
+     * cache is absorbing stops reading as green. Attribute it
+     * `served_stale_cache`, not `expected_absence`: a stale serve is an upstream
+     * fault the platform publishes as `degraded`, while an expected absence is
+     * published as a non-incident status.
      *
      * ```ts
      * {
@@ -1593,7 +1614,7 @@ export type OperationResult = {
      *     expected: true,
      *   },
      *   onFail: {
-     *     attribute: [{ operationId, status: "degraded", reasonCode: "expected_absence", reasonKey }],
+     *     attribute: [{ operationId, status: "degraded", reasonCode: "served_stale_cache", reasonKey }],
      *     stop: "scenario",
      *   },
      * }
@@ -1719,27 +1740,27 @@ export declare const HealthStepSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         attribute: z.ZodPipe<z.ZodArray<z.ZodType<{
             operationId: string;
             status: "degraded";
-            reasonCode: "expected_absence";
+            reasonCode: "expected_absence" | "served_stale_cache";
             reasonKey: string;
         }, unknown, z.core.$ZodTypeInternals<{
             operationId: string;
             status: "degraded";
-            reasonCode: "expected_absence";
+            reasonCode: "expected_absence" | "served_stale_cache";
             reasonKey: string;
         }, unknown>>>, z.ZodTransform<[{
             operationId: string;
             status: "degraded";
-            reasonCode: "expected_absence";
+            reasonCode: "expected_absence" | "served_stale_cache";
             reasonKey: string;
         }, ...{
             operationId: string;
             status: "degraded";
-            reasonCode: "expected_absence";
+            reasonCode: "expected_absence" | "served_stale_cache";
             reasonKey: string;
         }[]], {
             operationId: string;
             status: "degraded";
-            reasonCode: "expected_absence";
+            reasonCode: "expected_absence" | "served_stale_cache";
             reasonKey: string;
         }[]>>;
         stop: z.ZodLiteral<"scenario">;
@@ -1811,27 +1832,27 @@ export declare const GuardStepSchema: z.ZodObject<{
         attribute: z.ZodPipe<z.ZodArray<z.ZodType<{
             operationId: string;
             status: "degraded";
-            reasonCode: "expected_absence";
+            reasonCode: "expected_absence" | "served_stale_cache";
             reasonKey: string;
         }, unknown, z.core.$ZodTypeInternals<{
             operationId: string;
             status: "degraded";
-            reasonCode: "expected_absence";
+            reasonCode: "expected_absence" | "served_stale_cache";
             reasonKey: string;
         }, unknown>>>, z.ZodTransform<[{
             operationId: string;
             status: "degraded";
-            reasonCode: "expected_absence";
+            reasonCode: "expected_absence" | "served_stale_cache";
             reasonKey: string;
         }, ...{
             operationId: string;
             status: "degraded";
-            reasonCode: "expected_absence";
+            reasonCode: "expected_absence" | "served_stale_cache";
             reasonKey: string;
         }[]], {
             operationId: string;
             status: "degraded";
-            reasonCode: "expected_absence";
+            reasonCode: "expected_absence" | "served_stale_cache";
             reasonKey: string;
         }[]>>;
         stop: z.ZodLiteral<"scenario">;

package/dist/health-scenario.js

@@ -172,16 +172,32 @@ export const SafeRegexSchema = z
     .strict()
     .superRefine((value, ctx) => {
     if (/\\[1-9kg]/.test(value.pattern))
-        ctx.addIssue({ code: "custom", path: ["pattern"], message: "backreferences are not supported by RE2" });
+        ctx.addIssue({
+            code: "custom",
+            path: ["pattern"],
+            message: "backreferences are not supported by RE2",
+        });
     if (/\(\?/.test(value.pattern))
-        ctx.addIssue({ code: "custom", path: ["pattern"], message: "extended groups are not supported by RE2" });
+        ctx.addIssue({
+            code: "custom",
+            path: ["pattern"],
+            message: "extended groups are not supported by RE2",
+        });
     if (containsNestedRegexQuantifier(value.pattern))
-        ctx.addIssue({ code: "custom", path: ["pattern"], message: "nested regex quantifiers are not permitted" });
+        ctx.addIssue({
+            code: "custom",
+            path: ["pattern"],
+            message: "nested regex quantifiers are not permitted",
+        });
     try {
         new RegExp(value.pattern, value.flags);
     }
     catch {
-        ctx.addIssue({ code: "custom", path: ["pattern"], message: "pattern must be valid regular-expression syntax" });
+        ctx.addIssue({
+            code: "custom",
+            path: ["pattern"],
+            message: "pattern must be valid regular-expression syntax",
+        });
     }
 });
 const operandLiteralSchema = jsonValueSchema.superRefine((value, ctx) => {
@@ -414,11 +430,24 @@ const stepBaseSchema = z
     timeoutMs: finiteInt(1, 600_000).optional(),
 })
     .strict();
+/**
+ * Every member of the union, pinned in both directions: a code missing here
+ * fails `satisfies Record<GuardReasonCode, true>`, a code added here without
+ * the union fails the excess-property check. The union itself stays a
+ * literal so the type-only entry points (contract, server, testing) do not
+ * have to re-export the runtime tuple.
+ */
+const GUARD_REASON_CODE_SET = {
+    expected_absence: true,
+    served_stale_cache: true,
+};
+/** The closed vocabulary as a non-empty tuple, for schema and lint consumers. */
+export const GUARD_REASON_CODES = Object.keys(GUARD_REASON_CODE_SET);
 const attributionSchema = z
     .object({
     operationId: z.string().min(1),
     status: z.literal("degraded"),
-    reasonCode: z.literal("expected_absence"),
+    reasonCode: z.enum(GUARD_REASON_CODES),
     reasonKey: z.string().min(1),
 })
     .strict();

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export type { ApiFuseConfig, BrowserConfig, ProxyCacheStatus, ProxyProtocol, Pro
 export { defineConfig, loadApiFuseConfig, resolveProxy } from "./config/loader.js";
 export { canonicalJson, digestProviderContract, extractProviderContract, type JsonPrimitive, type JsonValue, PROVIDER_CONTRACT_SCHEMA_VERSION, type ProviderContractOperation, type ProviderContractSnapshot, } from "./contract.js";
 export { centered, delayed, defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, defineStreamOperation, every, type AuthStartNoInputGuard, type OperationDefinitionFor, type ProviderBuilder, type ProviderContextOf, type ProviderDeclaration, type ProviderDefinitionFor, } from "./define.js";
-export { AssertionExpressionSchema, AssertionPredicateSchema, AssertStepSchema, BoundedJsonPathSchema, CandidateBlockSchema, CandidatePolicySchema, CredentialRefDeclarationSchema, defineHealthScenario, HealthScenarioSchema, HealthStepSchema, ExtractStepSchema, FindFirstSchema, GuardStepSchema, JournalPolicySchema, JsonTemplateSchema, ManualTriggerPolicySchema, OperandSchema, OperationStepSchema, QuantifierSchema, ReferenceSchema, RetryPolicySchema, SafeRegexSchema, ScopedAssertionExpressionSchema, ScopedAssertionPredicateSchema, ScopedItemReferenceSchema, ScopedOperandSchema, StepReferenceSchema, RelativeDateNodeSchema, ValueTypeSchema, } from "./health-scenario.js";
+export { AssertionExpressionSchema, AssertionPredicateSchema, AssertStepSchema, BoundedJsonPathSchema, CandidateBlockSchema, CandidatePolicySchema, CredentialRefDeclarationSchema, defineHealthScenario, HealthScenarioSchema, HealthStepSchema, ExtractStepSchema, FindFirstSchema, GUARD_REASON_CODES, GuardStepSchema, JournalPolicySchema, JsonTemplateSchema, ManualTriggerPolicySchema, OperandSchema, OperationStepSchema, QuantifierSchema, ReferenceSchema, RetryPolicySchema, SafeRegexSchema, ScopedAssertionExpressionSchema, ScopedAssertionPredicateSchema, ScopedItemReferenceSchema, ScopedOperandSchema, StepReferenceSchema, RelativeDateNodeSchema, ValueTypeSchema, } from "./health-scenario.js";
 export type { AssertionExpression, AssertionPredicate, AttemptReference, AssertResult, AssertStep, BoundedJsonPath, CandidateBlock, CandidatePolicy, CandidateReference, CredentialReference, CredentialRefDeclaration, EstablishedConnectionReference, ExtractStep, FindFirst, GuardAttribution, GuardReasonCode, GuardResult, GuardStep, HealthScenario, HealthStep, JsonTemplate, JournalPolicy, ManualTriggerPolicy, NonEmpty, OperationResult, OperationStep, Operand, Quantifier, ReferenceNode, Reference, RelativeDateNode, RetryPolicy, SafeRegex, ScopedAssertionExpression, ScopedAssertionPredicate, ScopedItemReference, ScopedOperand, StepBase, StepReference, ExtractResult, ValueType, } from "./health-scenario.js";
 export type { DevServerOptions } from "./dev.js";
 export { createDevServer, startDevServer } from "./dev.js";

package/dist/index.js

@@ -4,7 +4,7 @@ export * from "./ceremonies/index.js";
 export { defineConfig, loadApiFuseConfig, resolveProxy } from "./config/loader.js";
 export { canonicalJson, digestProviderContract, extractProviderContract, PROVIDER_CONTRACT_SCHEMA_VERSION, } from "./contract.js";
 export { centered, delayed, defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, defineStreamOperation, every, } from "./define.js";
-export { AssertionExpressionSchema, AssertionPredicateSchema, AssertStepSchema, BoundedJsonPathSchema, CandidateBlockSchema, CandidatePolicySchema, CredentialRefDeclarationSchema, defineHealthScenario, HealthScenarioSchema, HealthStepSchema, ExtractStepSchema, FindFirstSchema, GuardStepSchema, JournalPolicySchema, JsonTemplateSchema, ManualTriggerPolicySchema, OperandSchema, OperationStepSchema, QuantifierSchema, ReferenceSchema, RetryPolicySchema, SafeRegexSchema, ScopedAssertionExpressionSchema, ScopedAssertionPredicateSchema, ScopedItemReferenceSchema, ScopedOperandSchema, StepReferenceSchema, RelativeDateNodeSchema, ValueTypeSchema, } from "./health-scenario.js";
+export { AssertionExpressionSchema, AssertionPredicateSchema, AssertStepSchema, BoundedJsonPathSchema, CandidateBlockSchema, CandidatePolicySchema, CredentialRefDeclarationSchema, defineHealthScenario, HealthScenarioSchema, HealthStepSchema, ExtractStepSchema, FindFirstSchema, GUARD_REASON_CODES, GuardStepSchema, JournalPolicySchema, JsonTemplateSchema, ManualTriggerPolicySchema, OperandSchema, OperationStepSchema, QuantifierSchema, ReferenceSchema, RetryPolicySchema, SafeRegexSchema, ScopedAssertionExpressionSchema, ScopedAssertionPredicateSchema, ScopedItemReferenceSchema, ScopedOperandSchema, StepReferenceSchema, RelativeDateNodeSchema, ValueTypeSchema, } from "./health-scenario.js";
 export { createDevServer, startDevServer } from "./dev.js";
 export * from "./errors.js";
 export * from "./engine.js";

package/dist/lint.js

@@ -2740,6 +2740,30 @@ function resultBindingChecksFreshness(steps, binding, operationId, siblingBindin
     }
     return false;
 }
+/**
+ * Whether a freshness guard for this operation still attributes
+ * `expected_absence` — the only code the attribution schema admitted before
+ * `served_stale_cache` existed, so earlier guidance recommended it. It IS
+ * freshness coverage (the guard runs and stops the scenario), which is why
+ * `scenarioChecksFreshness` accepts it; but the platform publishes
+ * `expected_absence` as a non-incident status, so the stale serve it catches
+ * would read as "nothing to return" instead of `degraded`.
+ */
+function freshnessGuardAttributesExpectedAbsence(scenario, operationId) {
+    if (!isLintRecord(scenario) || !Array.isArray(scenario.steps))
+        return false;
+    const bindings = operationStepBindings(scenario.steps, operationId);
+    if (bindings.size === 0)
+        return false;
+    return scenario.steps.some((step) => isLintRecord(step) &&
+        step.kind === "guard" &&
+        rejectsStaleServe(step.condition, bindings) &&
+        isLintRecord(step.onFail) &&
+        Array.isArray(step.onFail.attribute) &&
+        step.onFail.attribute.some((entry) => isLintRecord(entry) &&
+            entry.operationId === operationId &&
+            entry.reasonCode === "expected_absence"));
+}
 /** How many uncovered probes the stale-serve message names before eliding. */
 const STALE_SERVE_MESSAGE_PROBE_LIMIT = 8;
 /**
@@ -2773,6 +2797,7 @@ function lintHealthCheckMonitorability(provider) {
     for (const [operationKey, operation] of Object.entries(provider.operations ?? {})) {
         const cases = readHealthCheckCases(operation.healthCheck);
         const unmonitored = [];
+        const absenceAttributed = [];
         for (const [caseIndex, healthCase] of cases.entries()) {
             const caseLabel = typeof healthCase.name === "string" && healthCase.name.length > 0
                 ? `"${healthCase.name}"`
@@ -2785,6 +2810,17 @@ function lintHealthCheckMonitorability(provider) {
                 uncovered.push(`${operationKey} ${caseLabel}`);
                 uncoveredByOperation.set(operationKey, uncovered);
             }
+            if (freshnessGuardAttributesExpectedAbsence(healthCase.scenario, operationKey)) {
+                absenceAttributed.push(caseLabel);
+            }
+        }
+        if (absenceAttributed.length > 0) {
+            diagnostics.push({
+                rule: "health-check-stale-serve-reason",
+                level: "warn",
+                field: `operations.${operationKey}.healthCheck.cases`,
+                message: `${providerLabel} operation "${operationKey}" health-check ${absenceAttributed.length === 1 ? "case" : "cases"} ${absenceAttributed.join(", ")} guard ${SERVED_STALE_CACHE_OPERAND} but attribute reasonCode "expected_absence". The platform publishes expected_absence as a non-incident status (neither ok nor degraded, excluded from uptime and incidents), so an upstream outage this guard catches would read as "nothing to return" instead of degraded. Attribute reasonCode "served_stale_cache" instead; the reasonKey and its copy can stay.`,
+            });
         }
         if (unmonitored.length > 0) {
             diagnostics.push({
@@ -2840,7 +2876,7 @@ function lintHealthCheckMonitorability(provider) {
         rule: "health-check-stale-serve-unguarded",
         level: "warn",
         field: "healthCheck",
-        message: `${providerLabel} serves stale-if-error (staleIfErrorMs in ${[...sources].sort().join(", ")}) and these health-check cases never check ${SERVED_STALE_CACHE_OPERAND}: ${named}. During an upstream outage the cache answers HTTP 200 with a schema-valid body, so every clause over status_code and data still passes and those probes report ok for the whole stale window. Add one guard step per affected probe on { ref: { namespace: "steps", binding: "<operation step result>", path: ["${SERVED_STALE_CACHE_OPERAND}"] } } attributing status "degraded" with reasonCode "expected_absence", placed before any row or emptiness guard.${caveat}`,
+        message: `${providerLabel} serves stale-if-error (staleIfErrorMs in ${[...sources].sort().join(", ")}) and these health-check cases never check ${SERVED_STALE_CACHE_OPERAND}: ${named}. During an upstream outage the cache answers HTTP 200 with a schema-valid body, so every clause over status_code and data still passes and those probes report ok for the whole stale window. Add one guard step per affected probe on { ref: { namespace: "steps", binding: "<operation step result>", path: ["${SERVED_STALE_CACHE_OPERAND}"] } } attributing status "degraded" with reasonCode "served_stale_cache" (a stale serve is an upstream fault; "expected_absence" is the non-incident status for an absence the provider declares in advance), placed before any row or emptiness guard.${caveat}`,
     });
     return diagnostics;
 }

package/dist/provider.d.ts

@@ -1,21 +1,21 @@
-export { AuthAbortError, credentialsAuthChallenge, createAuthFlowHelpers, defineCredentialsAuth, } from "./auth.js";
 export type { CredentialsAuthChallengeDefinition, CredentialsAuthChallengeRequest, CredentialsAuthCompleteResult, CredentialsAuthCredential, CredentialsAuthField, CredentialsAuthFields, CredentialsAuthFieldType, CredentialsAuthInput, CredentialsAuthLoginResult, DefineCredentialsAuthOptions, DefinedCredentialsAuth, } from "./auth.js";
+export { AuthAbortError, createAuthFlowHelpers, credentialsAuthChallenge, defineCredentialsAuth, } from "./auth.js";
 export { createFormCeremony } from "./ceremonies/index.js";
-export { centered, delayed, defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, every, } from "./define.js";
-export type { OperationDefinitionFor, ProviderBuilder, ProviderContextOf, ProviderDeclaration, ProviderDefinitionFor, } from "./define.js";
 export type { JsonPrimitive, JsonValue } from "./contract-json.js";
-export { AssertionExpressionSchema, AssertionPredicateSchema, AssertStepSchema, BoundedJsonPathSchema, CandidateBlockSchema, CandidatePolicySchema, CredentialRefDeclarationSchema, defineHealthScenario, HealthScenarioSchema, HealthStepSchema, ExtractStepSchema, FindFirstSchema, GuardStepSchema, JournalPolicySchema, JsonTemplateSchema, ManualTriggerPolicySchema, OperandSchema, OperationStepSchema, QuantifierSchema, ReferenceSchema, RetryPolicySchema, SafeRegexSchema, ScopedAssertionExpressionSchema, ScopedAssertionPredicateSchema, ScopedItemReferenceSchema, ScopedOperandSchema, StepReferenceSchema, RelativeDateNodeSchema, ValueTypeSchema, } from "./health-scenario.js";
-export type { AssertionExpression, AssertionPredicate, AttemptReference, AssertResult, AssertStep, BoundedJsonPath, CandidateBlock, CandidatePolicy, CandidateReference, CredentialReference, CredentialRefDeclaration, EstablishedConnectionReference, ExtractStep, FindFirst, GuardAttribution, GuardReasonCode, GuardResult, GuardStep, HealthScenario, HealthStep, JsonTemplate, JournalPolicy, ManualTriggerPolicy, NonEmpty, OperationResult, OperationStep, Operand, Quantifier, ReferenceNode, Reference, RelativeDateNode, RetryPolicy, SafeRegex, ScopedAssertionExpression, ScopedAssertionPredicate, ScopedItemReference, ScopedOperand, StepBase, StepReference, ExtractResult, ValueType, } from "./health-scenario.js";
-export { AuthError, HttpRedirectError, isProviderError, isSessionExpiredError, isTransportError, ProviderEgressDeniedError, ProviderEngineAuthenticationError, ProviderEngineProtocolVersionError, ProviderEngineUnavailableError, ProviderError, type ProviderErrorObservability, SDKError, SessionExpiredError, TransportError, ValidationError, } from "./errors.js";
-export { createProviderEnvironment, createInProcessProviderEngine, ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES, ENGINE_OWNED_RESOLVER_CREDENTIAL_ENV_NAMES, ENGINE_OWNED_RUNTIME_ENV_NAMES, ENGINE_OWNED_TELEMETRY_ENV_NAMES, isEngineOwnedEnvName, isEngineOwnedProxyCredentialName, isEngineOwnedResolverCredentialName, isEngineOwnedRuntimeEnvName, isEngineOwnedTelemetryEnvName, PROVIDER_CAPABILITY_KEYS, PROVIDER_ENGINE_MODE_ENV, PROVIDER_ENGINE_PROTOCOL_VERSION, readEngineProxyCredentials, } from "./engine.js";
+export type { OperationDefinitionFor, ProviderBuilder, ProviderContextOf, ProviderDeclaration, ProviderDefinitionFor, } from "./define.js";
+export { centered, defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, delayed, every, } from "./define.js";
 export type { ProviderCapabilityKey, ProviderEngine, ProviderEngineAttachmentInput, ProviderEngineBindingCandidates, ProviderEngineCapabilitySurface, ProviderEngineMode, ProviderEngineRequest, ProviderEngineResidentSurface, ProviderEngineSession, ProviderEngineTransport, } from "./engine.js";
-export { getProviderLocalePath, type ProviderErrorMessageParams, providerLocaleKey, qualifyProviderLocaleKey, } from "./i18n/index.js";
+export { createInProcessProviderEngine, createProviderEnvironment, ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES, ENGINE_OWNED_RESOLVER_CREDENTIAL_ENV_NAMES, ENGINE_OWNED_RUNTIME_ENV_NAMES, ENGINE_OWNED_TELEMETRY_ENV_NAMES, isEngineOwnedEnvName, isEngineOwnedProxyCredentialName, isEngineOwnedResolverCredentialName, isEngineOwnedRuntimeEnvName, isEngineOwnedTelemetryEnvName, PROVIDER_CAPABILITY_KEYS, PROVIDER_ENGINE_MODE_ENV, PROVIDER_ENGINE_PROTOCOL_VERSION, readEngineProxyCredentials, } from "./engine.js";
+export { AuthError, HttpRedirectError, isProviderError, isSessionExpiredError, isTransportError, ProviderEgressDeniedError, ProviderEngineAuthenticationError, ProviderEngineProtocolVersionError, ProviderEngineUnavailableError, ProviderError, type ProviderErrorObservability, SDKError, SessionExpiredError, TransportError, ValidationError, } from "./errors.js";
 export * from "./handle.js";
 export { APIFUSE_HANDLE_META_KEY, HANDLE_KIND_NAME_PATTERN, handleFieldDescription, handleFieldNameFor, handleHasDirectionalFieldNames, isHandleFieldMeta, } from "./handle-meta.js";
+export type { AssertionExpression, AssertionPredicate, AssertResult, AssertStep, AttemptReference, BoundedJsonPath, CandidateBlock, CandidatePolicy, CandidateReference, CredentialRefDeclaration, CredentialReference, EstablishedConnectionReference, ExtractResult, ExtractStep, FindFirst, GuardAttribution, GuardReasonCode, GuardResult, GuardStep, HealthScenario, HealthStep, JournalPolicy, JsonTemplate, ManualTriggerPolicy, NonEmpty, Operand, OperationResult, OperationStep, Quantifier, Reference, ReferenceNode, RelativeDateNode, RetryPolicy, SafeRegex, ScopedAssertionExpression, ScopedAssertionPredicate, ScopedItemReference, ScopedOperand, StepBase, StepReference, ValueType, } from "./health-scenario.js";
+export { AssertionExpressionSchema, AssertionPredicateSchema, AssertStepSchema, BoundedJsonPathSchema, CandidateBlockSchema, CandidatePolicySchema, CredentialRefDeclarationSchema, defineHealthScenario, ExtractStepSchema, FindFirstSchema, GUARD_REASON_CODES, GuardStepSchema, HealthScenarioSchema, HealthStepSchema, JournalPolicySchema, JsonTemplateSchema, ManualTriggerPolicySchema, OperandSchema, OperationStepSchema, QuantifierSchema, ReferenceSchema, RelativeDateNodeSchema, RetryPolicySchema, SafeRegexSchema, ScopedAssertionExpressionSchema, ScopedAssertionPredicateSchema, ScopedItemReferenceSchema, ScopedOperandSchema, StepReferenceSchema, ValueTypeSchema, } from "./health-scenario.js";
+export { getProviderLocalePath, type ProviderErrorMessageParams, providerLocaleKey, qualifyProviderLocaleKey, } from "./i18n/index.js";
 export { type CreateHandleContextOptions, type CreateTestHandleContextOptions, createHandleContext, createTestHandleContext, type HandleNormalizationClass, type NormalizedHandle, normalizeHandle, } from "./runtime/handle.js";
+export type { NativeGatewayProxy, NativeGatewayProxyResolutionInput, NativeGatewayProxySkipReason, NativeGatewayProxySynthesisInput, NativeGatewayProxySynthesisResult, NativeGatewayProxySynthesizer, NativeNetworkClientOptions, NativeNetworkErrorCode, VendorCredentialLookup, VendorCredentialResolver, } from "./runtime/native-network.js";
+export { NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, } from "./runtime/native-network-errors.js";
 export { createMemoryProviderRuntimeState, createUnsupportedProviderRuntimeState, } from "./runtime/state.js";
 export { APIFUSE_CONTENT_PROVENANCE_META_KEY, APIFUSE_CONTENT_TRUST_META_KEY, APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SENSITIVE_KIND_META_KEY, APIFUSE_SENSITIVE_META_KEY, collectSensitivePaths, describeKey, field, fields, isSensitiveSchema, publicField, redactPayload, type SensitiveFieldKind, type SensitiveFieldOptions, type SensitivePath, sensitive, untrustedContent, z, } from "./schema.js";
-export type { AuthAbortData, AuthAbortRetry, AuthFlowTerminalContext, AuthMode, AuthSafeData, AuthSafeJson, FlowContext, HealthCheckAssertionContext, HealthCheckCase, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthScheduleRandomization, HttpAttemptContext, HttpHeadersFactory, HttpRedirectFailureReason, HttpRedirectPolicy, HttpRedirectPolicyMode, HttpRetryOptions, HttpRetrySummary, InferSchemaOutput, NativeContext, NativeNetworkClient, NativeNetworkCloseReason, NativeNetworkConnection, NativeNetworkConnectInput, NativeNetworkConnectOptions, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationExample, OperationErrorCode, ProviderErrorStatus, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationTransport, ProviderAccessVisibility, ProviderContext, ProviderContextFor, ProviderDefinition, ProviderDeploymentOverrides, ProviderFileRef, ProviderFilesContext, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderProxyPolicy, ProxiedOAuthConfig, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderResolvedFile, ProviderRuntimeTarget, ProviderRuntimeState, ProviderStealthConfig, ProviderStateDurationString, ProviderStateNamespace, ProviderSupportLevel, RedirectRunReason, SchemaLike, SmsOtpMatcherDefinition, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateNamespaceScope, StateValue, StateWriteOptions, StealthChallengeClassification, } from "./types.js";
-export { NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, } from "./runtime/native-network-errors.js";
-export type { NativeGatewayProxy, NativeGatewayProxyResolutionInput, NativeGatewayProxySkipReason, NativeGatewayProxySynthesizer, NativeGatewayProxySynthesisResult, NativeGatewayProxySynthesisInput, NativeNetworkClientOptions, NativeNetworkErrorCode, VendorCredentialLookup, VendorCredentialResolver, } from "./runtime/native-network.js";
+export type { AuthAbortData, AuthAbortRetry, AuthFlowTerminalContext, AuthMode, AuthSafeData, AuthSafeJson, FlowContext, HealthCheckAssertionContext, HealthCheckCase, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthScheduleRandomization, HttpAttemptContext, HttpHeadersFactory, HttpRedirectFailureReason, HttpRedirectPolicy, HttpRedirectPolicyMode, HttpRetryOptions, HttpRetrySummary, InferSchemaOutput, NativeContext, NativeNetworkClient, NativeNetworkCloseReason, NativeNetworkConnectInput, NativeNetworkConnection, NativeNetworkConnectOptions, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationErrorCode, OperationExample, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationTransport, ProviderAccessVisibility, ProviderContext, ProviderContextFor, ProviderDefinition, ProviderDeploymentOverrides, ProviderErrorStatus, ProviderFileRef, ProviderFilesContext, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderProxyPolicy, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderResolvedFile, ProviderRuntimeState, ProviderRuntimeTarget, ProviderStateDurationString, ProviderStateNamespace, ProviderStealthConfig, ProviderSupportLevel, ProxiedOAuthConfig, RedirectRunReason, SchemaLike, SmsOtpMatcherDefinition, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateNamespaceScope, StateValue, StateWriteOptions, StealthChallengeClassification, } from "./types.js";
 export { HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, } from "./types.js";

package/dist/provider.js

@@ -1,14 +1,14 @@
-export { AuthAbortError, credentialsAuthChallenge, createAuthFlowHelpers, defineCredentialsAuth, } from "./auth.js";
+export { AuthAbortError, createAuthFlowHelpers, credentialsAuthChallenge, defineCredentialsAuth, } from "./auth.js";
 export { createFormCeremony } from "./ceremonies/index.js";
-export { centered, delayed, defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, every, } from "./define.js";
-export { AssertionExpressionSchema, AssertionPredicateSchema, AssertStepSchema, BoundedJsonPathSchema, CandidateBlockSchema, CandidatePolicySchema, CredentialRefDeclarationSchema, defineHealthScenario, HealthScenarioSchema, HealthStepSchema, ExtractStepSchema, FindFirstSchema, GuardStepSchema, JournalPolicySchema, JsonTemplateSchema, ManualTriggerPolicySchema, OperandSchema, OperationStepSchema, QuantifierSchema, ReferenceSchema, RetryPolicySchema, SafeRegexSchema, ScopedAssertionExpressionSchema, ScopedAssertionPredicateSchema, ScopedItemReferenceSchema, ScopedOperandSchema, StepReferenceSchema, RelativeDateNodeSchema, ValueTypeSchema, } from "./health-scenario.js";
+export { centered, defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, delayed, every, } from "./define.js";
+export { createInProcessProviderEngine, createProviderEnvironment, ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES, ENGINE_OWNED_RESOLVER_CREDENTIAL_ENV_NAMES, ENGINE_OWNED_RUNTIME_ENV_NAMES, ENGINE_OWNED_TELEMETRY_ENV_NAMES, isEngineOwnedEnvName, isEngineOwnedProxyCredentialName, isEngineOwnedResolverCredentialName, isEngineOwnedRuntimeEnvName, isEngineOwnedTelemetryEnvName, PROVIDER_CAPABILITY_KEYS, PROVIDER_ENGINE_MODE_ENV, PROVIDER_ENGINE_PROTOCOL_VERSION, readEngineProxyCredentials, } from "./engine.js";
 export { AuthError, HttpRedirectError, isProviderError, isSessionExpiredError, isTransportError, ProviderEgressDeniedError, ProviderEngineAuthenticationError, ProviderEngineProtocolVersionError, ProviderEngineUnavailableError, ProviderError, SDKError, SessionExpiredError, TransportError, ValidationError, } from "./errors.js";
-export { createProviderEnvironment, createInProcessProviderEngine, ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES, ENGINE_OWNED_RESOLVER_CREDENTIAL_ENV_NAMES, ENGINE_OWNED_RUNTIME_ENV_NAMES, ENGINE_OWNED_TELEMETRY_ENV_NAMES, isEngineOwnedEnvName, isEngineOwnedProxyCredentialName, isEngineOwnedResolverCredentialName, isEngineOwnedRuntimeEnvName, isEngineOwnedTelemetryEnvName, PROVIDER_CAPABILITY_KEYS, PROVIDER_ENGINE_MODE_ENV, PROVIDER_ENGINE_PROTOCOL_VERSION, readEngineProxyCredentials, } from "./engine.js";
-export { getProviderLocalePath, providerLocaleKey, qualifyProviderLocaleKey, } from "./i18n/index.js";
 export * from "./handle.js";
 export { APIFUSE_HANDLE_META_KEY, HANDLE_KIND_NAME_PATTERN, handleFieldDescription, handleFieldNameFor, handleHasDirectionalFieldNames, isHandleFieldMeta, } from "./handle-meta.js";
+export { AssertionExpressionSchema, AssertionPredicateSchema, AssertStepSchema, BoundedJsonPathSchema, CandidateBlockSchema, CandidatePolicySchema, CredentialRefDeclarationSchema, defineHealthScenario, ExtractStepSchema, FindFirstSchema, GUARD_REASON_CODES, GuardStepSchema, HealthScenarioSchema, HealthStepSchema, JournalPolicySchema, JsonTemplateSchema, ManualTriggerPolicySchema, OperandSchema, OperationStepSchema, QuantifierSchema, ReferenceSchema, RelativeDateNodeSchema, RetryPolicySchema, SafeRegexSchema, ScopedAssertionExpressionSchema, ScopedAssertionPredicateSchema, ScopedItemReferenceSchema, ScopedOperandSchema, StepReferenceSchema, ValueTypeSchema, } from "./health-scenario.js";
+export { getProviderLocalePath, providerLocaleKey, qualifyProviderLocaleKey, } from "./i18n/index.js";
 export { createHandleContext, createTestHandleContext, normalizeHandle, } from "./runtime/handle.js";
+export { NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, } from "./runtime/native-network-errors.js";
 export { createMemoryProviderRuntimeState, createUnsupportedProviderRuntimeState, } from "./runtime/state.js";
 export { APIFUSE_CONTENT_PROVENANCE_META_KEY, APIFUSE_CONTENT_TRUST_META_KEY, APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SENSITIVE_KIND_META_KEY, APIFUSE_SENSITIVE_META_KEY, collectSensitivePaths, describeKey, field, fields, isSensitiveSchema, publicField, redactPayload, sensitive, untrustedContent, z, } from "./schema.js";
-export { NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, } from "./runtime/native-network-errors.js";
 export { HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, } from "./types.js";

package/dist/server/index.d.ts

@@ -17,6 +17,7 @@ export type { ProviderErrorObservability } from "../errors.js";
 export { computeSelfTestPlanDigest, createSelfTestApp, createSelfTestAuthFlowInvoke, createSelfTestInvoke, DEFAULT_SELF_TEST_REQUEST_BUDGET_MS, isSelfTestReadOnlyOperation, PROVIDER_RUNTIME_SELF_TEST_REQUEST_BUDGET_MS_ENV, resolveSelfTestPort, SELF_TEST_AUTH_FLOW_MULTI_TURN_SKIP_REASON, SELF_TEST_AUTH_FLOW_REJECTED_SKIP_REASON, SELF_TEST_HEALTHZ_PATH, SELF_TEST_PATH, SELF_TEST_SCHEMA_VERSION, type SelfTestAppOptions, type SelfTestAuthFlowInvoke, type SelfTestAuthFlowRoute, type SelfTestCaseResult, type SelfTestCaseStatus, type SelfTestOperationInvoke, type SelfTestRequest, SelfTestRequestSchema, type SelfTestResponse, } from "./self-test.js";
 export { type InputDateTokenCalendar, resolveHealthCheckInputDateTokens, } from "./self-test-input-tokens.js";
 export { collectSelfTestSensitiveValues, redactSelfTestText, SELF_TEST_MAX_TEXT_LENGTH, SELF_TEST_REDACTED_PLACEHOLDER, } from "./self-test-redaction.js";
+export { type CollectRuntimeDiagnosticsInput, collectRuntimeDiagnostics, DEFAULT_PROCFS_SELF_ROOT, DEFAULT_RUNTIME_DIAGNOSTICS_WINDOW_MS, MAX_RUNTIME_DIAGNOSTICS_WINDOW_MS, MIN_RUNTIME_DIAGNOSTICS_WINDOW_MS, normalizeRuntimeDiagnosticsWindowMs, PROCFS_CLOCK_TICKS_PER_SECOND, resolveRuntimeDiagnosticsWindowMs, RUNTIME_DIAGNOSTICS_ROUTE, RUNTIME_DIAGNOSTICS_SCHEMA_VERSION, RUNTIME_DIAGNOSTICS_WINDOW_QUERY, type RuntimeDiagnosticsActiveResources, type RuntimeDiagnosticsClock, type RuntimeDiagnosticsCpu, type RuntimeDiagnosticsCpuTotals, type RuntimeDiagnosticsEventLoop, type RuntimeDiagnosticsEventLoopUtilization, type RuntimeDiagnosticsFdKind, type RuntimeDiagnosticsMemory, type RuntimeDiagnosticsProcfs, type RuntimeDiagnosticsReport, type RuntimeDiagnosticsThread, type RuntimeDiagnosticsThreadContextSwitches, type RuntimeDiagnosticsThreadCpuTicks, type RuntimeDiagnosticsThreadWindow, } from "./runtime-diagnostics.js";
 export { DEFAULT_SELF_TEST_PORT, deriveSelfTestToken, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_ENV, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_PREVIOUS_ENV, PROVIDER_RUNTIME_SELF_TEST_PORT_ENV, resolveSelfTestMasterSecrets, type SelfTestMasterSecrets, verifySelfTestAuthorization, } from "./self-test-token.js";
 export type { AuthFlowRequest, AuthFlowResponse, AuthFlowSuccessResponse, ConnectionMode, OperationConnection, OperationErrorResponse, OperationRequest, OperationResponse, OperationSuccessResponse, } from "./types.js";
 export { AuthFlowRequestSchema, AuthFlowSuccessResponseSchema, ConnectionModeSchema, ErrorEnvelopeSchema, OperationConnectionSchema, OperationErrorResponseSchema, OperationRequestSchema, OperationSuccessResponseSchema, } from "./types.js";

package/dist/server/index.js

@@ -8,6 +8,7 @@ export { createServerApp, createServerAppAsync, ERROR_OBSERVABILITY_HEADER, serv
 export { computeSelfTestPlanDigest, createSelfTestApp, createSelfTestAuthFlowInvoke, createSelfTestInvoke, DEFAULT_SELF_TEST_REQUEST_BUDGET_MS, isSelfTestReadOnlyOperation, PROVIDER_RUNTIME_SELF_TEST_REQUEST_BUDGET_MS_ENV, resolveSelfTestPort, SELF_TEST_AUTH_FLOW_MULTI_TURN_SKIP_REASON, SELF_TEST_AUTH_FLOW_REJECTED_SKIP_REASON, SELF_TEST_HEALTHZ_PATH, SELF_TEST_PATH, SELF_TEST_SCHEMA_VERSION, SelfTestRequestSchema, } from "./self-test.js";
 export { resolveHealthCheckInputDateTokens, } from "./self-test-input-tokens.js";
 export { collectSelfTestSensitiveValues, redactSelfTestText, SELF_TEST_MAX_TEXT_LENGTH, SELF_TEST_REDACTED_PLACEHOLDER, } from "./self-test-redaction.js";
+export { collectRuntimeDiagnostics, DEFAULT_PROCFS_SELF_ROOT, DEFAULT_RUNTIME_DIAGNOSTICS_WINDOW_MS, MAX_RUNTIME_DIAGNOSTICS_WINDOW_MS, MIN_RUNTIME_DIAGNOSTICS_WINDOW_MS, normalizeRuntimeDiagnosticsWindowMs, PROCFS_CLOCK_TICKS_PER_SECOND, resolveRuntimeDiagnosticsWindowMs, RUNTIME_DIAGNOSTICS_ROUTE, RUNTIME_DIAGNOSTICS_SCHEMA_VERSION, RUNTIME_DIAGNOSTICS_WINDOW_QUERY, } from "./runtime-diagnostics.js";
 export { DEFAULT_SELF_TEST_PORT, deriveSelfTestToken, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_ENV, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_PREVIOUS_ENV, PROVIDER_RUNTIME_SELF_TEST_PORT_ENV, resolveSelfTestMasterSecrets, verifySelfTestAuthorization, } from "./self-test-token.js";
 export { AuthFlowRequestSchema, AuthFlowSuccessResponseSchema, ConnectionModeSchema, ErrorEnvelopeSchema, OperationConnectionSchema, OperationErrorResponseSchema, OperationRequestSchema, OperationSuccessResponseSchema, } from "./types.js";
 export { HttpTelemetryCollector, } from "../runtime/http-telemetry.js";

package/dist/server/runtime-diagnostics.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Internal runtime diagnostics route on the provider's primary listener, next
+ * to `/health` and `/readyz`. It answers one JSON report that tells an idle
+ * process that still burns CPU apart from a busy one without `exec`: process
+ * CPU sampled over a short window, memory, the Node event-loop and
+ * active-resource APIs, and on Linux the per-thread CPU and file-descriptor
+ * picture from `/proc/self`.
+ *
+ * Read-only and secret-free. It shares the boundary of `/health` and `/readyz`:
+ * the generated provider NetworkPolicy admits only the gateway on this port and
+ * the gateway dials canonical operation paths only, so a tenant cannot reach
+ * it; operators use `kubectl port-forward`.
+ */
+export declare const RUNTIME_DIAGNOSTICS_ROUTE = "/__apifuse/diagnostics/runtime";
+export declare const RUNTIME_DIAGNOSTICS_SCHEMA_VERSION: 1;
+/** Query parameter naming the sampling window; clamped, never rejected. */
+export declare const RUNTIME_DIAGNOSTICS_WINDOW_QUERY = "windowMs";
+export declare const DEFAULT_RUNTIME_DIAGNOSTICS_WINDOW_MS = 250;
+export declare const MIN_RUNTIME_DIAGNOSTICS_WINDOW_MS = 50;
+export declare const MAX_RUNTIME_DIAGNOSTICS_WINDOW_MS = 5000;
+/**
+ * Linux USER_HZ. The unit of `utime`/`stime` in `/proc` stat files is an ABI
+ * constant (100 Hz) independent of the kernel's CONFIG_HZ.
+ */
+export declare const PROCFS_CLOCK_TICKS_PER_SECOND = 100;
+export declare const DEFAULT_PROCFS_SELF_ROOT = "/proc/self";
+export interface RuntimeDiagnosticsCpuTotals {
+    readonly userMicros: number;
+    readonly systemMicros: number;
+}
+export interface RuntimeDiagnosticsCpu {
+    /** `process.cpuUsage()` since boot and its average in cores over `uptimeSeconds`. */
+    readonly lifetime: RuntimeDiagnosticsCpuTotals & {
+        readonly averageCores: number;
+    };
+    /** `process.cpuUsage()` delta over the sampling window, as cores (1 = one CPU fully busy). */
+    readonly window: RuntimeDiagnosticsCpuTotals & {
+        readonly userCores: number;
+        readonly systemCores: number;
+        readonly totalCores: number;
+    };
+}
+export interface RuntimeDiagnosticsEventLoopUtilization {
+    readonly idle: number;
+    readonly active: number;
+    readonly utilization: number;
+}
+export interface RuntimeDiagnosticsEventLoop {
+    /**
+     * false when the runtime returned only zeros for the whole process lifetime.
+     * Bun 1.2 and 1.3 stub `performance.eventLoopUtilization`; read
+     * `cpu.window` and `procfs.threads` instead.
+     */
+    readonly reported: boolean;
+    readonly lifetime: RuntimeDiagnosticsEventLoopUtilization;
+    readonly window: RuntimeDiagnosticsEventLoopUtilization;
+}
+export interface RuntimeDiagnosticsActiveResources {
+    /**
+     * false when the runtime listed nothing, although at least the socket that
+     * answers this request is alive. Bun 1.2 and 1.3 stub
+     * `process.getActiveResourcesInfo`; read `procfs.fileDescriptors` instead.
+     */
+    readonly reported: boolean;
+    readonly total: number;
+    readonly byType: Readonly<Record<string, number>>;
+}
+export interface RuntimeDiagnosticsMemory {
+    readonly rss: number;
+    readonly heapTotal: number;
+    readonly heapUsed: number;
+    readonly external: number;
+    readonly arrayBuffers: number;
+}
+export interface RuntimeDiagnosticsThreadCpuTicks {
+    readonly userTicks: number;
+    readonly systemTicks: number;
+}
+export interface RuntimeDiagnosticsThreadContextSwitches {
+    readonly voluntary: number;
+    readonly nonvoluntary: number;
+}
+export interface RuntimeDiagnosticsThreadWindow extends RuntimeDiagnosticsThreadCpuTicks {
+    /** CPU consumed by this thread over the window, in cores. */
+    readonly cores: number;
+    readonly contextSwitches: RuntimeDiagnosticsThreadContextSwitches;
+}
+export interface RuntimeDiagnosticsThread {
+    readonly tid: number;
+    /** Kernel thread name (`comm`, 15 bytes), e.g. `bun`, `HTTP Client`, `HeapHelper`. */
+    readonly name: string;
+    /** Scheduler state letter at the second sample (`R` running, `S` sleeping, ...). */
+    readonly state: string;
+    /** Kernel wait channel at the second sample (`0` while running); null when unreadable. */
+    readonly waitChannel: string | null;
+    readonly lifetime: RuntimeDiagnosticsThreadCpuTicks;
+    /** null for a thread that appeared after the first sample. */
+    readonly window: RuntimeDiagnosticsThreadWindow | null;
+}
+export type RuntimeDiagnosticsFdKind = "socket" | "eventpoll" | "timerfd" | "eventfd" | "pipe" | "file" | "other";
+export interface RuntimeDiagnosticsProcfs {
+    readonly clockTicksPerSecond: number;
+    /**
+     * Elapsed time between the two /proc/self scans. Slightly longer than
+     * `window.observedMs` because it encloses the scans themselves; thread
+     * `window.cores` is computed over this interval.
+     */
+    readonly observedMs: number;
+    readonly threads: {
+        readonly total: number;
+        readonly byName: Readonly<Record<string, number>>;
+        /** Sorted by window cores descending, so the hottest thread is first. */
+        readonly items: readonly RuntimeDiagnosticsThread[];
+    };
+    readonly fileDescriptors: {
+        readonly total: number;
+        readonly byKind: Readonly<Record<RuntimeDiagnosticsFdKind, number>>;
+    };
+}
+export interface RuntimeDiagnosticsReport {
+    readonly schemaVersion: typeof RUNTIME_DIAGNOSTICS_SCHEMA_VERSION;
+    readonly provider: {
+        readonly id: string;
+        readonly version: string;
+    };
+    readonly sdkVersion: string;
+    readonly runtime: {
+        readonly bunVersion: string | null;
+        readonly nodeCompatVersion: string;
+        readonly platform: string;
+        readonly arch: string;
+        readonly pid: number;
+    };
+    readonly sampledAt: string;
+    readonly uptimeSeconds: number;
+    readonly window: {
+        readonly requestedMs: number;
+        readonly observedMs: number;
+    };
+    readonly cpu: RuntimeDiagnosticsCpu;
+    readonly memory: RuntimeDiagnosticsMemory;
+    readonly eventLoop: RuntimeDiagnosticsEventLoop;
+    readonly activeResources: RuntimeDiagnosticsActiveResources;
+    /** null off Linux or when `/proc/self` is unreadable. */
+    readonly procfs: RuntimeDiagnosticsProcfs | null;
+}
+export interface RuntimeDiagnosticsClock {
+    now(): number;
+    sleep(ms: number): Promise<void>;
+}
+export interface CollectRuntimeDiagnosticsInput {
+    readonly provider: {
+        readonly id: string;
+        readonly version: string;
+    };
+    /** Sampling window; clamped to [MIN, MAX]. */
+    readonly windowMs?: number;
+    /** `/proc/self` substitute for tests. */
+    readonly procfsRoot?: string;
+    readonly clock?: RuntimeDiagnosticsClock;
+}
+export declare function normalizeRuntimeDiagnosticsWindowMs(value: number | undefined): number;
+/** Parses the `windowMs` query value; anything unparsable falls back to the default. */
+export declare function resolveRuntimeDiagnosticsWindowMs(raw: string | undefined | null): number;
+export declare function collectRuntimeDiagnostics(input: CollectRuntimeDiagnosticsInput): Promise<RuntimeDiagnosticsReport>;