@astrale-os/kernel-protocol 0.5.0-beta.9 → 0.5.0

package/dist/artifact/index.d.ts

@@ -1 +1 @@
-export { accept, identify, type Digest, type Ref } from './ref.js';
+export { accept, canonicalMediaType, identify, type Digest, type Ref } from './ref.js';

package/dist/artifact/index.js

@@ -1 +1 @@
-export { accept, identify } from './ref.js';
+export { accept, canonicalMediaType, identify } from './ref.js';

package/dist/artifact/ref.d.ts

@@ -8,3 +8,5 @@ export interface Ref {
 export declare function accept(input: unknown): Ref;
 /** Identify exact bytes under one canonical media type. */
 export declare function identify(bytes: Uint8Array, mediaType: string): Ref;
+/** Canonicalize one portable artifact media type, retaining token parameters and their values. */
+export declare function canonicalMediaType(input: string): string;

package/dist/artifact/ref.js

@@ -18,7 +18,7 @@ export function accept(input) {
     }
     return Object.freeze({
         digest: value.digest,
-        mediaType: normalizeMediaType(value.mediaType),
+        mediaType: canonicalMediaType(value.mediaType),
         size: value.size,
     });
 }
@@ -31,11 +31,12 @@ export function identify(bytes, mediaType) {
         hexadecimal += byte.toString(16).padStart(2, '0');
     return Object.freeze({
         digest: `sha256:${hexadecimal}`,
-        mediaType: normalizeMediaType(mediaType),
+        mediaType: canonicalMediaType(mediaType),
         size: bytes.byteLength,
     });
 }
-function normalizeMediaType(input) {
+/** Canonicalize one portable artifact media type, retaining token parameters and their values. */
+export function canonicalMediaType(input) {
     const [essence, ...parametersInput] = input.split(';');
     const [rawType, rawSubtype, ...extra] = essence.trim().split('/');
     if (rawType === undefined ||

package/dist/codecs/index.d.ts

@@ -1,4 +1,3 @@
 export { DecodeError, type Codec, type EncodedEnvelope } from './codec.js';
 export { json } from './json.js';
-export { CONTENT_TYPE_JSON, CONTENT_TYPE_MSGPACK } from './media-types.js';
-export { loadMsgpack } from './msgpack.js';
+export { CONTENT_TYPE_JSON } from './media-types.js';

package/dist/codecs/index.js

@@ -1,4 +1,3 @@
 export { DecodeError } from './codec.js';
 export { json } from './json.js';
-export { CONTENT_TYPE_JSON, CONTENT_TYPE_MSGPACK } from './media-types.js';
-export { loadMsgpack } from './msgpack.js';
+export { CONTENT_TYPE_JSON } from './media-types.js';

package/dist/codecs/media-types.d.ts

@@ -1,2 +1 @@
 export declare const CONTENT_TYPE_JSON: 'application/vnd.astrale+json';
-export declare const CONTENT_TYPE_MSGPACK: 'application/vnd.astrale.msgpack';

package/dist/codecs/media-types.js

@@ -1,2 +1 @@
 export const CONTENT_TYPE_JSON = 'application/vnd.astrale+json';
-export const CONTENT_TYPE_MSGPACK = 'application/vnd.astrale.msgpack';

package/dist/errors/index.d.ts

@@ -3,3 +3,4 @@ export { httpStatusOf } from './http-status.js';
 export { acceptPayload, type ErrorPayload } from './payload.js';
 export { ProtocolError } from './protocol-error.js';
 export { acceptReason, reasonOf, type ErrorReason } from './reason.js';
+export { MAXIMUM_RETRY_AFTER_MS, RETRY_REASONS, retryAfterField, retryAfterOf, retryReason, type RetryReason, type RetryReasonCode, } from './retry.js';

package/dist/errors/index.js

@@ -3,3 +3,4 @@ export { httpStatusOf } from './http-status.js';
 export { acceptPayload } from './payload.js';
 export { ProtocolError } from './protocol-error.js';
 export { acceptReason, reasonOf } from './reason.js';
+export { MAXIMUM_RETRY_AFTER_MS, RETRY_REASONS, retryAfterField, retryAfterOf, retryReason, } from './retry.js';

package/dist/errors/retry.d.ts

@@ -0,0 +1,25 @@
+import type { ErrorPayload } from './payload.js';
+import type { ErrorReason } from './reason.js';
+/**
+ * Reasons for a request refused before any work was admitted. The same request may be sent again
+ * once `retryAfterMs` has elapsed; every other public error keeps its own retry meaning.
+ */
+export declare const RETRY_REASONS: Readonly<{
+    /** A bounded Kernel resource is exhausted. */
+    readonly CAPACITY_EXHAUSTED: 'CAPACITY_EXHAUSTED';
+    /** The server stopped admitting work before it shuts down. */
+    readonly SERVER_DRAINING: 'SERVER_DRAINING';
+    /** The Instance is under a maintenance session that admits only its root operator. */
+    readonly INSTANCE_MAINTENANCE: 'INSTANCE_MAINTENANCE';
+}>;
+export type RetryReasonCode = (typeof RETRY_REASONS)[keyof typeof RETRY_REASONS];
+export type RetryReason<Code extends RetryReasonCode = RetryReasonCode> = ErrorReason<Code, {
+    readonly retryAfterMs: number;
+}>;
+/** One hour bounds a hint that only schedules the next attempt. */
+export declare const MAXIMUM_RETRY_AFTER_MS = 3600000;
+export declare function retryReason<Code extends RetryReasonCode>(code: Code, retryAfterMs: number): RetryReason<Code>;
+/** Return the retry delay of a back-pressure, draining or maintenance refusal, and nothing else. */
+export declare function retryAfterOf(error: ErrorPayload): number | undefined;
+/** Present a retry delay as an HTTP `Retry-After` delta in whole seconds, rounded up. */
+export declare function retryAfterField(retryAfterMs: number): string;

package/dist/errors/retry.js

@@ -0,0 +1,46 @@
+import { CODES } from './codes.js';
+import { reasonOf } from './reason.js';
+/**
+ * Reasons for a request refused before any work was admitted. The same request may be sent again
+ * once `retryAfterMs` has elapsed; every other public error keeps its own retry meaning.
+ */
+export const RETRY_REASONS = Object.freeze({
+    /** A bounded Kernel resource is exhausted. */
+    CAPACITY_EXHAUSTED: 'CAPACITY_EXHAUSTED',
+    /** The server stopped admitting work before it shuts down. */
+    SERVER_DRAINING: 'SERVER_DRAINING',
+    /** The Instance is under a maintenance session that admits only its root operator. */
+    INSTANCE_MAINTENANCE: 'INSTANCE_MAINTENANCE',
+});
+/** One hour bounds a hint that only schedules the next attempt. */
+export const MAXIMUM_RETRY_AFTER_MS = 3_600_000;
+const CODES_SET = new Set(Object.values(RETRY_REASONS));
+export function retryReason(code, retryAfterMs) {
+    if (!CODES_SET.has(code))
+        throw new TypeError('Retry reason code is invalid.');
+    if (!isRetryAfter(retryAfterMs))
+        throw new TypeError('Retry reason retryAfterMs is invalid.');
+    return Object.freeze({ code, details: Object.freeze({ retryAfterMs }) });
+}
+/** Return the retry delay of a back-pressure, draining or maintenance refusal, and nothing else. */
+export function retryAfterOf(error) {
+    if (error.code !== CODES.BACKEND_UNAVAILABLE)
+        return undefined;
+    const reason = reasonOf(error.data);
+    if (reason === undefined || !CODES_SET.has(reason.code))
+        return undefined;
+    const retryAfterMs = reason.details.retryAfterMs;
+    return isRetryAfter(retryAfterMs) ? retryAfterMs : undefined;
+}
+/** Present a retry delay as an HTTP `Retry-After` delta in whole seconds, rounded up. */
+export function retryAfterField(retryAfterMs) {
+    if (!isRetryAfter(retryAfterMs))
+        throw new TypeError('Retry-After delay is invalid.');
+    return String(Math.ceil(retryAfterMs / 1_000));
+}
+function isRetryAfter(input) {
+    return (typeof input === 'number' &&
+        Number.isSafeInteger(input) &&
+        input >= 0 &&
+        input <= MAXIMUM_RETRY_AFTER_MS);
+}

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export * as artifact from './artifact/index.js';
 export * as invocation from './invocation/index.js';
 export * as codecs from './codecs/index.js';
 export * as errors from './errors/index.js';
-export * as publication from './publication/index.js';
+export * as release from './release/index.js';
 export * as schema from './schema/index.js';
 export * as routes from './routes/index.js';
 export * as issuer from './issuer/index.js';

package/dist/index.js

@@ -2,7 +2,7 @@ export * as artifact from './artifact/index.js';
 export * as invocation from './invocation/index.js';
 export * as codecs from './codecs/index.js';
 export * as errors from './errors/index.js';
-export * as publication from './publication/index.js';
+export * as release from './release/index.js';
 export * as schema from './schema/index.js';
 export * as routes from './routes/index.js';
 export * as issuer from './issuer/index.js';

package/dist/invocation/admission.d.ts

@@ -3,7 +3,7 @@ import { NodePath } from '@astrale-os/kernel-core/path';
 import { Key } from '@astrale-os/kernel-dsl/v1/addressing';
 import { type Object as ValueObject } from '@astrale-os/kernel-dsl/value';
 import type { ErrorPayload } from '../errors/index.js';
-import type { Etag } from '../publication/index.js';
+import type { Sha256Digest } from '../release/digest.js';
 import { type RequestId } from './correlation.js';
 import { type InvocationId } from './identity.js';
 export declare function portableObject(input: unknown, label: string): ValueObject;
@@ -16,7 +16,7 @@ export declare function nodePath(input: unknown, label: string): NodePath;
 export declare function issuerId(input: unknown, label: string): IssuerId;
 export declare function string(input: unknown, label: string): string;
 export declare function count(input: unknown, label: string): number;
-export declare function digest(input: unknown, label: string): Etag;
+export declare function digest(input: unknown, label: string): Sha256Digest;
 export declare function callableKey(input: unknown, label: string): Key.Callable;
 export declare function errorPayload(input: unknown, label: string): ErrorPayload;
 export declare function acceptHeaders(input: unknown): Readonly<Record<string, string>>;

package/dist/invocation/admission.js

@@ -2,14 +2,14 @@ import { AuthValueError } from '@astrale-os/kernel-core/auth/error';
 import { accept as acceptIssuer } from '@astrale-os/kernel-core/auth/issuer';
 import { NodePath, PathError } from '@astrale-os/kernel-core/path';
 import { callableAddress, Key } from '@astrale-os/kernel-dsl/v1/addressing';
-import { accept as acceptValue, BoundaryError, } from '@astrale-os/kernel-dsl/value';
+import { acceptForRead, BoundaryError, } from '@astrale-os/kernel-dsl/value';
 import { CODES, acceptPayload, ProtocolError } from '../errors/index.js';
 import { acceptRequestId } from './correlation.js';
 import { acceptInvocationId, InvocationError } from './identity.js';
 export function portableObject(input, label) {
-    let cloned;
+    let snapshot;
     try {
-        cloned = acceptValue(input);
+        snapshot = acceptForRead(input);
     }
     catch (cause) {
         if (cause instanceof BoundaryError) {
@@ -17,9 +17,9 @@ export function portableObject(input, label) {
         }
         throw cause;
     }
-    if (!isValueObject(cloned))
+    if (!isValueObject(snapshot))
         invalid(`${label} must be an object`);
-    return cloned;
+    return snapshot;
 }
 export function exactDataObject(input, label) {
     if (input === null || typeof input !== 'object' || Array.isArray(input)) {

package/dist/invocation/binary.d.ts

@@ -6,6 +6,7 @@ export interface BinaryResponse {
     readonly invocation: InvocationId;
     readonly body: Uint8Array;
     readonly mediaType: string;
+    readonly status: number;
     readonly headers?: Readonly<Record<string, string>>;
 }
 export declare function decodeBinaryResponse(input: unknown): BinaryResponse;

package/dist/invocation/binary.js

@@ -1,6 +1,14 @@
+import { canonicalMediaType } from '../artifact/index.js';
 import { acceptHeaders, exactDataObject, exactFields, invalid, invocation, requestId, required, string, } from './admission.js';
-const FIELDS = new Set(['kind', 'requestId', 'invocation', 'body', 'mediaType', 'headers']);
-const MEDIA_TYPE = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+\/[!#$%&'*+.^_`|~0-9A-Za-z-]+$/u;
+const FIELDS = new Set([
+    'kind',
+    'requestId',
+    'invocation',
+    'body',
+    'mediaType',
+    'status',
+    'headers',
+]);
 export function decodeBinaryResponse(input) {
     const object = exactDataObject(input, 'binary response');
     exactFields(object, FIELDS, 'binary response');
@@ -9,9 +17,17 @@ export function decodeBinaryResponse(input) {
         invalid('binary response.kind must be "binary"');
     if (!(object.body instanceof Uint8Array))
         invalid('binary response.body must be a Uint8Array');
-    const mediaType = string(object.mediaType, 'binary response.mediaType');
-    if (!MEDIA_TYPE.test(mediaType))
+    let mediaType;
+    try {
+        mediaType = canonicalMediaType(string(object.mediaType, 'binary response.mediaType'));
+    }
+    catch {
         invalid('binary response.mediaType is invalid');
+    }
+    const status = object.status ?? 200;
+    if (!Number.isInteger(status) || status < 200 || status > 599) {
+        invalid('binary response.status is invalid');
+    }
     const headers = object.headers === undefined ? undefined : acceptHeaders(object.headers);
     return Object.freeze({
         kind: 'binary',
@@ -19,6 +35,7 @@ export function decodeBinaryResponse(input) {
         invocation: invocation(object.invocation, 'binary response.invocation'),
         body: new Uint8Array(object.body),
         mediaType,
+        status: status,
         ...(headers === undefined ? {} : { headers }),
     });
 }

package/dist/invocation/binding-codecs.d.ts

@@ -1,8 +1,9 @@
 import type { Codec } from '../codecs/codec.js';
-export type CodecProfile = 'json' | 'msgpack';
-export interface SupportedCodec {
+type CodecProfile = 'json';
+interface SupportedCodec {
     readonly codec: Codec;
     readonly profile: CodecProfile;
 }
 export declare function codecProfile(codec: Codec): CodecProfile | undefined;
 export declare function admitSupportedCodecs(supported: readonly Codec[]): readonly SupportedCodec[];
+export {};

package/dist/invocation/binding-codecs.js

@@ -1,11 +1,6 @@
 import { json } from '../codecs/json.js';
-import { isMsgpackCodec } from '../codecs/msgpack.js';
 export function codecProfile(codec) {
-    if (codec === json)
-        return 'json';
-    if (isMsgpackCodec(codec))
-        return 'msgpack';
-    return undefined;
+    return codec === json ? 'json' : undefined;
 }
 export function admitSupportedCodecs(supported) {
     if (!Array.isArray(supported))

package/dist/invocation/delegate.d.ts

@@ -1,24 +1,4 @@
-export declare namespace Delegate {
-    type Expr = {
-        readonly kind: 'identity';
-        readonly self: true;
-    } | {
-        readonly kind: 'identity';
-        readonly credential: string;
-    } | {
-        readonly kind: 'union';
-        readonly operands: readonly Expr[];
-    } | {
-        readonly kind: 'intersect';
-        readonly operands: readonly Expr[];
-    } | {
-        readonly kind: 'exclude';
-        readonly base: Expr;
-        readonly excluded: readonly Expr[];
-    };
-}
 export interface Delegate {
     readonly ttlSeconds: number;
-    readonly attenuation?: Delegate.Expr;
 }
 export declare function acceptDelegate(input: unknown): Delegate;

package/dist/invocation/delegate.js

@@ -1,6 +1,5 @@
-import { AuthValueError, grant } from '@astrale-os/kernel-core/auth';
 import { exactDataObject, exactFields, invalid, required } from './admission.js';
-const FIELDS = new Set(['ttlSeconds', 'attenuation']);
+const FIELDS = new Set(['ttlSeconds']);
 export function acceptDelegate(input) {
     const object = exactDataObject(input, 'delegate');
     exactFields(object, FIELDS, 'delegate');
@@ -8,36 +7,5 @@ export function acceptDelegate(input) {
     if (!Number.isSafeInteger(object.ttlSeconds) || object.ttlSeconds < 1) {
         invalid('delegate.ttlSeconds must be a positive safe integer');
     }
-    let attenuation;
-    if (object.attenuation !== undefined) {
-        try {
-            attenuation = grant.acceptUnresolved({ v: 1, expr: object.attenuation }).expr;
-        }
-        catch (cause) {
-            if (cause instanceof AuthValueError)
-                invalid('delegate.attenuation must be a valid expression');
-            throw cause;
-        }
-        requireTextCredentials(attenuation);
-    }
-    return Object.freeze({
-        ttlSeconds: object.ttlSeconds,
-        ...(attenuation === undefined ? {} : { attenuation: attenuation }),
-    });
-}
-function requireTextCredentials(input) {
-    if (input.kind === 'identity') {
-        if ('credential' in input && typeof input.credential !== 'string') {
-            invalid('delegate.attenuation credentials must be non-empty text');
-        }
-        return;
-    }
-    if (input.kind === 'exclude') {
-        requireTextCredentials(input.base);
-        for (const operand of input.excluded)
-            requireTextCredentials(operand);
-        return;
-    }
-    for (const operand of input.operands)
-        requireTextCredentials(operand);
+    return Object.freeze({ ttlSeconds: object.ttlSeconds });
 }

package/dist/invocation/http/binary.d.ts

@@ -1,11 +1,13 @@
 import { type InvocationId } from '../identity.js';
 export declare const BINARY_HEADERS_FIELD: 'x-astrale-binary-headers';
+export declare const BINARY_DELIVERY_FIELD: 'x-astrale-binary-delivery';
+export declare const STREAMING_BINARY_DELIVERY: 'streaming';
 export declare const REQUEST_ID_FIELD: 'x-astrale-request-id';
 export declare const INVOCATION_FIELD: 'x-astrale-invocation';
 export declare const MAXIMUM_INVOCATION_FIELD_BYTES = 8192;
 /** Encode one admitted InvocationId as percent-encoded source plus opaque ID. */
 export declare function encodeInvocationId(input: InvocationId): string;
-/** Decode one complete finite-binary InvocationId field. */
+/** Decode one complete binary InvocationId field. */
 export declare function decodeInvocationId(input: string | null): InvocationId;
 export declare function isApplicationBinaryHeader(name: string): boolean;
 export declare function encodeBinaryHeaderNames(headers: Readonly<Record<string, string>> | undefined): string;

package/dist/invocation/http/binary.js

@@ -1,6 +1,9 @@
 import { CODES, ProtocolError } from '../../errors/index.js';
 import { acceptInvocationId } from '../identity.js';
+import { BINARY_LENGTH_FIELD } from './request.js';
 export const BINARY_HEADERS_FIELD = 'x-astrale-binary-headers';
+export const BINARY_DELIVERY_FIELD = 'x-astrale-binary-delivery';
+export const STREAMING_BINARY_DELIVERY = 'streaming';
 export const REQUEST_ID_FIELD = 'x-astrale-request-id';
 export const INVOCATION_FIELD = 'x-astrale-invocation';
 export const MAXIMUM_INVOCATION_FIELD_BYTES = 8_192;
@@ -33,6 +36,8 @@ const RESERVED = new Set([
     'www-authenticate',
     EMPTY_MANIFEST,
     BINARY_HEADERS_FIELD,
+    BINARY_DELIVERY_FIELD,
+    BINARY_LENGTH_FIELD,
     INVOCATION_FIELD,
     REQUEST_ID_FIELD,
     'x-astrale-stream-framing',
@@ -52,7 +57,7 @@ export function encodeInvocationId(input) {
     }
     return encoded;
 }
-/** Decode one complete finite-binary InvocationId field. */
+/** Decode one complete binary InvocationId field. */
 export function decodeInvocationId(input) {
     if (input === null ||
         input.length === 0 ||

package/dist/invocation/http/index.d.ts

@@ -1,4 +1,5 @@
-export { BINARY_HEADERS_FIELD, decodeBinaryHeaderNames, decodeInvocationId, encodeBinaryHeaderNames, encodeInvocationId, isApplicationBinaryHeader, MAXIMUM_INVOCATION_FIELD_BYTES, INVOCATION_FIELD, REQUEST_ID_FIELD, } from './binary.js';
+export { BINARY_DELIVERY_FIELD, BINARY_HEADERS_FIELD, decodeBinaryHeaderNames, decodeInvocationId, encodeBinaryHeaderNames, encodeInvocationId, isApplicationBinaryHeader, MAXIMUM_INVOCATION_FIELD_BYTES, INVOCATION_FIELD, REQUEST_ID_FIELD, STREAMING_BINARY_DELIVERY, } from './binary.js';
 export { codecForContentType, negotiateResponseCodec } from './negotiation.js';
+export { BINARY_LENGTH_FIELD, BINARY_REQUEST_CONTENT_TYPE, decodeBinaryLength, decodeBinaryRequestEnvelope, encodeBinaryRequestEnvelope, MAXIMUM_REQUEST_ENVELOPE_BYTES, REQUEST_ENVELOPE_FIELD, } from './request.js';
 export { encodeStreamFrame, LENGTH_PREFIX_V1, STREAM_FRAMING_FIELD } from './stream.js';
 export { BAGGAGE_FIELD, decodeTraceHeaders, encodeTraceHeaders, TRACEPARENT_FIELD, TRACESTATE_FIELD, } from './trace.js';

package/dist/invocation/http/index.js

@@ -1,4 +1,5 @@
-export { BINARY_HEADERS_FIELD, decodeBinaryHeaderNames, decodeInvocationId, encodeBinaryHeaderNames, encodeInvocationId, isApplicationBinaryHeader, MAXIMUM_INVOCATION_FIELD_BYTES, INVOCATION_FIELD, REQUEST_ID_FIELD, } from './binary.js';
+export { BINARY_DELIVERY_FIELD, BINARY_HEADERS_FIELD, decodeBinaryHeaderNames, decodeInvocationId, encodeBinaryHeaderNames, encodeInvocationId, isApplicationBinaryHeader, MAXIMUM_INVOCATION_FIELD_BYTES, INVOCATION_FIELD, REQUEST_ID_FIELD, STREAMING_BINARY_DELIVERY, } from './binary.js';
 export { codecForContentType, negotiateResponseCodec } from './negotiation.js';
+export { BINARY_LENGTH_FIELD, BINARY_REQUEST_CONTENT_TYPE, decodeBinaryLength, decodeBinaryRequestEnvelope, encodeBinaryRequestEnvelope, MAXIMUM_REQUEST_ENVELOPE_BYTES, REQUEST_ENVELOPE_FIELD, } from './request.js';
 export { encodeStreamFrame, LENGTH_PREFIX_V1, STREAM_FRAMING_FIELD } from './stream.js';
 export { BAGGAGE_FIELD, decodeTraceHeaders, encodeTraceHeaders, TRACEPARENT_FIELD, TRACESTATE_FIELD, } from './trace.js';

package/dist/invocation/http/negotiation.js

@@ -1,4 +1,4 @@
-import { CONTENT_TYPE_JSON, CONTENT_TYPE_MSGPACK } from '../../codecs/index.js';
+import { CONTENT_TYPE_JSON } from '../../codecs/index.js';
 import { admitSupportedCodecs } from '../binding-codecs.js';
 const TOKEN = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/u;
 const QVALUE = /^(?:0(?:\.\d{0,3})?|1(?:\.0{0,3})?)$/u;
@@ -9,11 +9,7 @@ export function codecForContentType(contentType, supported) {
     const mediaType = parseContentType(contentType);
     if (mediaType === undefined)
         return undefined;
-    const profile = mediaType === CONTENT_TYPE_JSON
-        ? 'json'
-        : mediaType === CONTENT_TYPE_MSGPACK
-            ? 'msgpack'
-            : undefined;
+    const profile = mediaType === CONTENT_TYPE_JSON ? 'json' : undefined;
     return admitted.find((entry) => entry.profile === profile)?.codec;
 }
 export function negotiateResponseCodec(accept, requestCodec, supported) {
@@ -27,7 +23,7 @@ export function negotiateResponseCodec(accept, requestCodec, supported) {
     if (ranges.length === 0)
         return undefined;
     const candidates = admitted.flatMap((entry) => {
-        const [type, subtype] = contentTypeOf(entry.profile).split('/');
+        const [type, subtype] = CONTENT_TYPE_JSON.split('/');
         const governing = ranges
             .filter((range) => range.mediaParameters === 0 &&
             (range.type === '*' || range.type === type) &&
@@ -56,9 +52,6 @@ export function negotiateResponseCodec(accept, requestCodec, supported) {
     });
     return candidates[0]?.codec;
 }
-function contentTypeOf(profile) {
-    return profile === 'json' ? CONTENT_TYPE_JSON : CONTENT_TYPE_MSGPACK;
-}
 function parseContentType(input) {
     if (splitOutsideQuotes(input, ',')?.length !== 1)
         return undefined;

package/dist/invocation/http/request.d.ts

@@ -0,0 +1,11 @@
+import { type Request } from '../request.js';
+export declare const REQUEST_ENVELOPE_FIELD: 'x-astrale-request';
+export declare const BINARY_LENGTH_FIELD: 'x-astrale-binary-length';
+export declare const BINARY_REQUEST_CONTENT_TYPE: 'application/octet-stream';
+export declare const MAXIMUM_REQUEST_ENVELOPE_BYTES = 8192;
+/** Decode one declared byte count: a canonical unsigned decimal within the safe integer range. */
+export declare function decodeBinaryLength(input: string): number | undefined;
+/** Encode one canonical V2 Request into the binary-request HTTP field. */
+export declare function encodeBinaryRequestEnvelope(input: Request): string;
+/** Decode one bounded base64url JSON V2 Request from the binary-request HTTP field. */
+export declare function decodeBinaryRequestEnvelope(input: string | null): Request;

package/dist/invocation/http/request.js

@@ -0,0 +1,69 @@
+import { json } from '../../codecs/index.js';
+import { CODES, ProtocolError } from '../../errors/index.js';
+import { decodeRequest } from '../request.js';
+export const REQUEST_ENVELOPE_FIELD = 'x-astrale-request';
+export const BINARY_LENGTH_FIELD = 'x-astrale-binary-length';
+export const BINARY_REQUEST_CONTENT_TYPE = 'application/octet-stream';
+export const MAXIMUM_REQUEST_ENVELOPE_BYTES = 8_192;
+const BASE64URL = /^[A-Za-z0-9_-]+$/u;
+const MAXIMUM_ENCODED_BYTES = Math.ceil(MAXIMUM_REQUEST_ENVELOPE_BYTES / 3) * 4;
+const DECIMAL = /^(?:0|[1-9][0-9]*)$/u;
+/** Decode one declared byte count: a canonical unsigned decimal within the safe integer range. */
+export function decodeBinaryLength(input) {
+    if (!DECIMAL.test(input))
+        return undefined;
+    const length = Number(input);
+    return Number.isSafeInteger(length) ? length : undefined;
+}
+/** Encode one canonical V2 Request into the binary-request HTTP field. */
+export function encodeBinaryRequestEnvelope(input) {
+    const request = decodeRequest(input);
+    const encoded = json.encode(request);
+    if (typeof encoded !== 'string')
+        throw new TypeError('JSON Request codec returned non-text output.');
+    const bytes = new TextEncoder().encode(encoded);
+    if (bytes.byteLength > MAXIMUM_REQUEST_ENVELOPE_BYTES)
+        return invalid();
+    return btoa(String.fromCharCode(...bytes))
+        .replaceAll('+', '-')
+        .replaceAll('/', '_')
+        .replace(/=+$/u, '');
+}
+/** Decode one bounded base64url JSON V2 Request from the binary-request HTTP field. */
+export function decodeBinaryRequestEnvelope(input) {
+    if (input === null ||
+        input.length === 0 ||
+        input.length > MAXIMUM_ENCODED_BYTES ||
+        !BASE64URL.test(input)) {
+        return invalid();
+    }
+    let bytes;
+    try {
+        const binary = atob(input.replaceAll('-', '+').replaceAll('_', '/') + '='.repeat((4 - (input.length % 4)) % 4));
+        bytes = Uint8Array.from(binary, (character) => character.charCodeAt(0));
+    }
+    catch {
+        return invalid();
+    }
+    if (bytes.byteLength > MAXIMUM_REQUEST_ENVELOPE_BYTES)
+        return invalid();
+    try {
+        // Require canonical base64url so alternate encodings cannot name the same envelope.
+        const canonical = btoa(String.fromCharCode(...bytes))
+            .replaceAll('+', '-')
+            .replaceAll('/', '_')
+            .replace(/=+$/u, '');
+        if (canonical !== input)
+            return invalid();
+        return decodeRequest(json.decode(bytes));
+    }
+    catch {
+        return invalid();
+    }
+}
+function invalid() {
+    throw new ProtocolError({
+        code: CODES.INVALID_REQUEST,
+        message: 'HTTP binary Request envelope is invalid.',
+    });
+}

package/dist/invocation/index.d.ts

@@ -5,16 +5,17 @@ export { acceptIdempotencyKey, HTTP_IDEMPOTENCY_KEY, MAXIMUM_IDEMPOTENCY_KEY_LEN
 export { acceptInvocationId, InvocationError, MAXIMUM_INVOCATION_ID_LENGTH, sameInvocationId, type InvocationId, } from './identity.js';
 export * as http from './http/index.js';
 export { acceptDelegate, type Delegate } from './delegate.js';
+export { acceptMaintenance, MAXIMUM_MAINTENANCE_SESSION_LENGTH, type Maintenance, type MaintenanceSession, } from './maintenance.js';
 export { decodeMiss, miss, type Miss } from './miss.js';
 export { acceptRoute, acceptRedirection, decodeRedirectResponse, remoteRoute, type RemoteBindingInput, type Redirection, type RedirectResponse, type Route, } from './redirect.js';
 export { decodeRequest, type Request } from './request.js';
 export { admitTrace, MAXIMUM_TRACEPARENT_BYTES, MAXIMUM_TRACESTATE_BYTES, MAXIMUM_TRACESTATE_MEMBERS, type Trace, } from './trace.js';
-export { acceptRouting, type Refresh, type Routing, type Via } from './routing.js';
+export { acceptRouting, routedDigest, routedRevision, type Refresh, type Routing, type Via, } from './routing.js';
 export { acceptSchemaTarget, type SchemaTarget } from './schema.js';
-export { decodeResponse, type ErrorResponse, type Response, type ResponseContext, type SuccessResponse, } from './response.js';
-export { SCHEMA_UPGRADE_REQUIRED, SCHEMA_REVISION_MISMATCH, SERVICE_CANDIDATE_INVALID, SERVICE_TRUST_REQUIRED, SERVICE_UNAVAILABLE, serviceErrorOf, type SchemaUpgradeRequiredDetails, type SchemaUpgradeRequiredReason, type SchemaRevisionMismatchDetails, type SchemaRevisionMismatchReason, type ServiceCandidateInvalidDetails, type ServiceCandidateInvalidReason, type ServiceErrorPayload, type ServiceReason, type ServiceTrustRequiredDetails, type ServiceTrustRequiredReason, type ServiceUnavailableDetails, type ServiceUnavailableReason, } from './service-reason.js';
+export { decodeResponse, type ErrorResponse, type ExecutionResponse, type Response, type ResponseContext, type SuccessResponse, } from './response.js';
+export { CALLABLE_FINGERPRINT_MISMATCH, DEPLOYMENT_RETIRED, SERVICE_CANDIDATE_INVALID, SERVICE_TRUST_REQUIRED, SERVICE_UNAVAILABLE, serviceErrorOf, type CallableFingerprintMismatchDetails, type CallableFingerprintMismatchReason, type DeploymentRetiredDetails, type DeploymentRetiredReason, type ServiceCandidateInvalidDetails, type ServiceCandidateInvalidReason, type ServiceErrorPayload, type ServiceReason, type ServiceTrustRequiredDetails, type ServiceTrustRequiredReason, type ServiceUnavailableDetails, type ServiceUnavailableReason, } from './service-reason.js';
 export { decodeStale, stale, type Stale } from './stale-route.js';
 export { decodeStreamFrame, type StreamEndFrame, type StreamErrorFrame, type StreamFrame, type StreamItemFrame, type StreamStartFrame, } from './stream.js';
-export { acceptCall, type Call } from './target.js';
+export { Target, targetPath, acceptCall, type Call } from './target.js';
 export { VERSION, type Version } from './version.js';
 export * as websocket from './websocket/index.js';

package/dist/invocation/index.js

@@ -5,16 +5,17 @@ export { acceptIdempotencyKey, HTTP_IDEMPOTENCY_KEY, MAXIMUM_IDEMPOTENCY_KEY_LEN
 export { acceptInvocationId, InvocationError, MAXIMUM_INVOCATION_ID_LENGTH, sameInvocationId, } from './identity.js';
 export * as http from './http/index.js';
 export { acceptDelegate } from './delegate.js';
+export { acceptMaintenance, MAXIMUM_MAINTENANCE_SESSION_LENGTH, } from './maintenance.js';
 export { decodeMiss, miss } from './miss.js';
 export { acceptRoute, acceptRedirection, decodeRedirectResponse, remoteRoute, } from './redirect.js';
 export { decodeRequest } from './request.js';
 export { admitTrace, MAXIMUM_TRACEPARENT_BYTES, MAXIMUM_TRACESTATE_BYTES, MAXIMUM_TRACESTATE_MEMBERS, } from './trace.js';
-export { acceptRouting } from './routing.js';
+export { acceptRouting, routedDigest, routedRevision, } from './routing.js';
 export { acceptSchemaTarget } from './schema.js';
 export { decodeResponse, } from './response.js';
-export { SCHEMA_UPGRADE_REQUIRED, SCHEMA_REVISION_MISMATCH, SERVICE_CANDIDATE_INVALID, SERVICE_TRUST_REQUIRED, SERVICE_UNAVAILABLE, serviceErrorOf, } from './service-reason.js';
+export { CALLABLE_FINGERPRINT_MISMATCH, DEPLOYMENT_RETIRED, SERVICE_CANDIDATE_INVALID, SERVICE_TRUST_REQUIRED, SERVICE_UNAVAILABLE, serviceErrorOf, } from './service-reason.js';
 export { decodeStale, stale } from './stale-route.js';
 export { decodeStreamFrame, } from './stream.js';
-export { acceptCall } from './target.js';
+export { Target, targetPath, acceptCall } from './target.js';
 export { VERSION } from './version.js';
 export * as websocket from './websocket/index.js';

package/dist/invocation/maintenance.d.ts

@@ -0,0 +1,14 @@
+declare const MAINTENANCE_SESSION: unique symbol;
+/** Identity of the install Execution that owns one maintenance session; it grants no authority. */
+export type MaintenanceSession = string & {
+    readonly [MAINTENANCE_SESSION]: true;
+};
+/** Source-Kernel guard naming the maintenance session a root request expects to act within. */
+export interface Maintenance {
+    readonly session: MaintenanceSession;
+}
+/** An Execution identifier: 1-255 ASCII characters drawn from `[A-Za-z0-9._-]`. */
+export declare const MAXIMUM_MAINTENANCE_SESSION_LENGTH = 255;
+/** Admit one exact maintenance guard without deciding whether its session is active. */
+export declare function acceptMaintenance(input: unknown): Maintenance;
+export {};