@astrale-os/kernel-server 1.0.0-beta.1 → 1.0.0-beta.11

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/routes/native.js

@@ -67,6 +67,17 @@ export async function nativeResponse(request, snapshot, options, responseCors) {
                 },
             });
         }
+        if (result.kind === 'execution') {
+            // The call has started or replayed its Execution: accept it with the reference, never a
+            // failure, saying whether this call created it.
+            return new Response(encodedBody(codecs.json.encode({ id: result.execution, replayed: result.replayed })), {
+                status: 202,
+                headers: {
+                    ...responseCors,
+                    'content-type': 'application/json',
+                },
+            });
+        }
         if (result.kind === 'binary') {
             if (isStreamingBinary(result.value)) {
                 // Hand the operation off only once the streaming response is built. A refused render

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/http/render.js

@@ -15,6 +15,14 @@ export function renderHttpResult(result, context) {
                 invocation: context.invocation,
             };
             break;
+        case 'execution':
+            envelope = {
+                execution: result.execution,
+                replayed: result.replayed,
+                requestId: context.requestId,
+                invocation: context.invocation,
+            };
+            break;
         case 'redirect':
             envelope = renderRedirect(context.requestId, context.invocation, result.redirect);
             break;

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),
                 }));
@@ -194,6 +195,14 @@ async function sendResult(socket, codec, requestId, assigned, result, operation,
                 invocation: assigned,
             }, sendOutput);
             return;
+        case 'execution':
+            await send(socket, codec, {
+                execution: result.execution,
+                replayed: result.replayed,
+                requestId,
+                invocation: assigned,
+            }, sendOutput);
+            return;
         case 'redirect':
             await send(socket, codec, renderRedirect(requestId, assigned, result.redirect), sendOutput);
             return;

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.1",
+  "version": "1.0.0-beta.11",
   "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.1",
-    "@astrale-os/kernel-dsl": "1.0.0-beta.1",
-    "@astrale-os/kernel-protocol": "1.0.0-beta.1",
+    "@astrale-os/kernel-core": "1.0.0-beta.11",
+    "@astrale-os/kernel-dsl": "1.0.0-beta.5",
+    "@astrale-os/kernel-protocol": "1.0.0-beta.11",
     "hono": "^4.6.20"
   },
   "devDependencies": {