@astrale-os/kernel-server 1.0.0-beta.4 → 1.0.0-beta.5

package/dist/errors/classify.d.ts

@@ -3,7 +3,9 @@ import * as errors from '@astrale-os/kernel-protocol/errors';
 export declare function classifyError(input: unknown): errors.ErrorPayload;
 /**
  * Classify the failure of one request. Its own deadline or cancellation names the failure, except an
- * outcome already unknown: ending the request proves nothing about an effect.
+ * outcome already unknown: ending the request proves nothing about an effect. A request the Server's
+ * close ended keeps the draining refusal only when that refusal is the failure itself: the Server
+ * refused before dispatch, or the Handler proved it ran nothing.
  */
 export declare function classifyRequestError(input: unknown, request: {
     readonly timedOut: boolean;

package/dist/errors/classify.js

@@ -19,7 +19,9 @@ export function classifyError(input) {
 }
 /**
  * Classify the failure of one request. Its own deadline or cancellation names the failure, except an
- * outcome already unknown: ending the request proves nothing about an effect.
+ * outcome already unknown: ending the request proves nothing about an effect. A request the Server's
+ * close ended keeps the draining refusal only when that refusal is the failure itself: the Server
+ * refused before dispatch, or the Handler proved it ran nothing.
  */
 export function classifyRequestError(input, request) {
     if (input instanceof errors.ProtocolError &&
@@ -28,10 +30,18 @@ export function classifyRequestError(input, request) {
     }
     if (request.timedOut)
         return publicError('DEADLINE_EXCEEDED', 'Invocation deadline exceeded.');
-    if (request.signal.aborted)
+    if (request.signal.aborted) {
+        if (draining(request.signal.reason) && draining(input))
+            return input.payload;
         return publicError('CANCELLED', 'Invocation was cancelled.');
+    }
     return classifyError(input);
 }
+function draining(input) {
+    return (input instanceof errors.ProtocolError &&
+        errors.retryAfterOf(input.payload) !== undefined &&
+        errors.reasonOf(input.payload.data)?.code === errors.RETRY_REASONS.SERVER_DRAINING);
+}
 function publicError(name, message) {
     return { code: errors.CODES[name], message };
 }

package/dist/invocation/types.d.ts

@@ -55,6 +55,8 @@ export interface HandlerRequest {
     readonly via?: protocol.Via;
     /** Source-only local-target or remote-revision Schema Registration precondition. */
     readonly schema?: protocol.SchemaTarget;
+    /** Source-only maintenance session guard forwarded unchanged to Runtime. */
+    readonly maintenance?: protocol.Maintenance;
     /** Exact Server-pinned release for a request at a release-backed destination. */
     readonly release?: ReleaseSnapshot;
     readonly context: InvocationContext;

package/dist/lifecycle/active.d.ts

@@ -11,7 +11,8 @@ export interface ActiveOperation {
     readonly timedOut: boolean;
     /** Register cooperative cleanup and return an idempotent unregistration function. */
     onCancel(cancel: CancelWork): () => void;
-    cancel(reason: string): void;
+    /** Abort with `cause` as the signal reason, or a plain Error naming `reason`. */
+    cancel(reason: string, cause?: Error): void;
     /** Replace the remaining budget after a trusted transport binding is admitted. */
     extend(timeoutMs: number): void;
     settle(): void;

package/dist/lifecycle/active.js

@@ -1,3 +1,5 @@
+import * as errors from '@astrale-os/kernel-protocol/errors';
+import { admissionRefusal } from '../errors/index.js';
 // Streaming iterators can need several microtasks to return after cancellation. Keep the
 // cleanup join bounded even when a producer ignores its cancellation signal.
 const CANCELLATION_CLEANUP_GRACE_MS = 250;
@@ -85,8 +87,10 @@ export class ActiveOperations {
         await this.waitUntilIdleOr(deadline);
         const hasCancellationWork = [...this.operations].some((operation) => operation.hasCancellationWork);
         if (this.operations.size > 0) {
+            // The typed draining refusal lets a Handler that ran nothing answer it, to be retried elsewhere.
+            const closing = new errors.ProtocolError(admissionRefusal(false));
             for (const operation of this.operations)
-                operation.cancel('server closing');
+                operation.cancel('server closing', closing);
         }
         this.closeSockets();
         if (hasCancellationWork) {
@@ -196,13 +200,13 @@ class Operation {
             this.cancelWork.delete(cancel);
         };
     }
-    cancel(reason) {
+    cancel(reason, cause) {
         if (this.cancelled || this.settled)
             return;
         this.cancelled = true;
         clearTimeout(this.timer);
         this.detachExternal();
-        this.controller.abort(new Error(reason));
+        this.controller.abort(cause ?? new Error(reason));
         for (const cancel of this.cancelWork)
             void settleCancellation(cancel, reason);
         this.cancelWork.clear();

package/dist/server.js

@@ -71,7 +71,13 @@ function createPreparedServer(input, config) {
     if (config.health !== undefined) {
         app.get(config.health.path, (context) => {
             const ready = active.isAvailable && config.health.probe.check();
-            return context.json({ status: ready ? 'ready' : 'not-ready' }, ready ? 200 : 503, {
+            const maintenance = config.health.probe.maintenance?.();
+            const uncertified = config.health.probe.uncertified?.() === true;
+            return context.json({
+                status: ready ? 'ready' : 'not-ready',
+                ...(maintenance === undefined ? {} : { maintenance }),
+                ...(uncertified ? { certification: 'uncertified' } : {}),
+            }, ready ? 200 : 503, {
                 ...config.cors.response(context.req.raw),
                 'cache-control': 'no-store',
             });
@@ -224,7 +230,25 @@ function servedDocumentPaths(_kind, issuer) {
 }
 function captureHealthProbe(probe) {
     const check = captureMethod(probe, 'check', 'Health probe is invalid.');
-    return Object.freeze({ check });
+    const maintenance = probe.maintenance === undefined
+        ? undefined
+        : captureMethod(probe, 'maintenance', 'Health probe is invalid.');
+    const uncertified = probe.uncertified === undefined
+        ? undefined
+        : captureMethod(probe, 'uncertified', 'Health probe is invalid.');
+    return Object.freeze({
+        check,
+        ...(maintenance === undefined
+            ? {}
+            : {
+                // A mode that is not a short token is not reported rather than echoed.
+                maintenance: () => {
+                    const mode = maintenance();
+                    return typeof mode === 'string' && /^[a-z]{1,32}$/u.test(mode) ? mode : undefined;
+                },
+            }),
+        ...(uncertified === undefined ? {} : { uncertified: () => uncertified() === true }),
+    });
 }
 function captureWebSocket(adapter) {
     const upgrade = captureMethod(adapter, 'upgrade', 'WebSocket adapter is invalid.');

package/dist/transport/http/handler.js

@@ -176,6 +176,7 @@ export function createHttpHandler(config) {
                     ...(envelope.delegate === undefined ? {} : { delegate: envelope.delegate }),
                     ...(envelope.routing?.kind === 'via' ? { via: envelope.routing } : {}),
                     ...(envelope.schema === undefined ? {} : { schema: envelope.schema }),
+                    ...(envelope.maintenance === undefined ? {} : { maintenance: envelope.maintenance }),
                     ...(served === undefined ? {} : pinned(served)),
                     context: invocationContext(assigned, active, config.active, host, undefined, envelope.idempotencyKey, binary),
                 }));

package/dist/transport/websocket/session.js

@@ -142,6 +142,7 @@ export function createWebSocketSession(config) {
                     ...(envelope.delegate === undefined ? {} : { delegate: envelope.delegate }),
                     ...(envelope.routing?.kind === 'via' ? { via: envelope.routing } : {}),
                     ...(envelope.schema === undefined ? {} : { schema: envelope.schema }),
+                    ...(envelope.maintenance === undefined ? {} : { maintenance: envelope.maintenance }),
                     ...(served === undefined ? {} : pinned(served)),
                     context: invocationContext(assigned, operation, config.active, config.host, undefined, envelope.idempotencyKey),
                 }));

package/dist/types.d.ts

@@ -35,6 +35,16 @@ export interface ServerCloseOptions {
 export interface HealthProbe {
     /** Non-blocking snapshot; health never performs provider I/O. */
     check(): boolean;
+    /**
+     * The Instance admission mode the Host reports beside readiness: maintenance never lowers
+     * readiness, so health names it instead. A non-blocking snapshot, absent to report nothing.
+     */
+    maintenance?(): string | undefined;
+    /**
+     * True while the Instance carries the break-glass `uncertified` mark: no certificate covers its
+     * data until an install validates it in full. Health names it; it never lowers readiness.
+     */
+    uncertified?(): boolean;
 }
 /** Static transport configuration admitted before Runtime Boot performs I/O. */
 export interface ServerOptions {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/kernel-server",
-  "version": "1.0.0-beta.4",
+  "version": "1.0.0-beta.5",
   "description": "Portable HTTP and WebSocket boundary for Astrale invocation, Release, installation, and issuer protocols",
   "license": "Apache-2.0",
   "repository": {
@@ -25,9 +25,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@astrale-os/kernel-core": "1.0.0-beta.4",
+    "@astrale-os/kernel-core": "1.0.0-beta.5",
     "@astrale-os/kernel-dsl": "1.0.0-beta.3",
-    "@astrale-os/kernel-protocol": "1.0.0-beta.4",
+    "@astrale-os/kernel-protocol": "1.0.0-beta.5",
     "hono": "^4.6.20"
   },
   "devDependencies": {