@serve.zone/interfaces 31.9.0 → 32.0.0

package/dist_ts/data/runtimesession.d.ts

@@ -1,25 +1,24 @@
 import type { IIdentityCredential } from './user.js';
-import type { IRuntimeAssignmentObservationV1, IRuntimeAssignmentReferenceV1, IRuntimeAssignmentV1, IRuntimeControllerV1 } from './runtimeassignment.js';
-import type { IRuntimeConfigV1 } from './runtimeconfig.js';
+import type { IRuntimeAssignmentObservation, IRuntimeAssignmentReference, IRuntimeAssignment, IRuntimeController, TRuntimeWorkloadAuthority } from './runtimeassignment.js';
+import { type IProtocolOffer } from '../protocol.js';
+import type { IRuntimeConfig } from './runtimeconfig.js';
 /**
  * Server-issued public binding for the current authenticated physical connection.
  * It contains no bearer, peer ID or client-selected authority. A serialized binding
  * is not authentication: every receiver must compare it with its live peer context.
  * Onebox local execution uses the same shape with its own authenticated IPC owner.
  */
-export interface IRuntimeSessionBindingV1 {
-    schemaVersion: 1;
+export interface IRuntimeSessionBinding {
     reporterSessionId: string;
     nodeId: string;
     credentialGeneration: number;
     sessionEpoch: number;
     controllerInstanceId: string;
-    controller: IRuntimeControllerV1;
+    controller: IRuntimeController;
     runtimeNamespace: string;
 }
 /** Pallet-initiated WSS on its configured Cloudly HTTPS origin; never HTTP RPC. */
-export interface IRegisterPalletRuntimeSessionRequestV1 {
-    schemaVersion: 1;
+export interface IRegisterPalletRuntimeSessionRequest {
     nodeId: string;
     credentialGeneration: number;
     /** Sensitive ephemeral input; exclude the complete request from hooks and logs. */
@@ -29,69 +28,103 @@ export interface IRegisterPalletRuntimeSessionRequestV1 {
      * registration. It proves which node process is registering when the transport cannot:
      * one relay socket carries many nodes, so the physical peer no longer distinguishes a
      * node restart from a replay. It is not a secret and it grants no authority; the bearer
-     * still authenticates. Absent only from legacy senders, which a controller may accept
-     * exclusively from a directly connected node.
+     * still authenticates.
      */
-    nodeInstanceNonce?: string;
+    nodeInstanceNonce: string;
+    /**
+     * What this node can resolve for a workload, sorted and duplicate-free.
+     *
+     * It states a capability of the build that is registering, not a permission: the controller
+     * refuses an assignment whose `requiredWorkloadAuthorities` this list does not cover, instead
+     * of a node accepting work it cannot carry out. It is not part of the registration identity —
+     * a changed build is a new process and therefore a new `nodeInstanceNonce` — so a replay of one
+     * registration with different authorities is a conflict rather than an update.
+     */
+    resolvedAuthorities: TRuntimeWorkloadAuthority[];
+    /** Read and negotiated before anything else on this body; see `runtimeSessionContract`. */
+    protocol: IProtocolOffer;
+}
+/**
+ * What the controller answers an accepted registration with.
+ *
+ * The offer travels beside the binding rather than inside it: the binding is embedded in every
+ * session-scoped request and compared as a whole, so an offer in it would make two builds of one
+ * controller produce two bindings for one session.
+ */
+export interface IRegisterPalletRuntimeSessionResponse {
+    session: IRuntimeSessionBinding;
+    protocol: IProtocolOffer;
 }
-export interface IApplyRuntimeAssignmentRequestV1 {
-    session: IRuntimeSessionBindingV1;
-    assignment: IRuntimeAssignmentV1;
-    config: IRuntimeConfigV1;
+export interface IApplyRuntimeAssignmentRequest {
+    session: IRuntimeSessionBinding;
+    assignment: IRuntimeAssignment;
+    config: IRuntimeConfig;
     /** Exact removed incumbent for a new attempt; not assignment.previous. */
-    predecessor: IRuntimeAssignmentReferenceV1 | null;
+    predecessor: IRuntimeAssignmentReference | null;
 }
 /** Durable admission acknowledgement only; it asserts neither effects nor readiness. */
-export interface IApplyRuntimeAssignmentResponseV1 {
+export interface IApplyRuntimeAssignmentResponse {
     status: 'accepted' | 'replay' | 'historical';
-    assignment: IRuntimeAssignmentReferenceV1;
+    assignment: IRuntimeAssignmentReference;
 }
-export interface IReportRuntimeAssignmentObservationRequestV1 {
+export interface IReportRuntimeAssignmentObservationRequest {
     /** Always the CURRENT authenticated connection, including after credential rotation. */
-    session: IRuntimeSessionBindingV1;
+    session: IRuntimeSessionBinding;
     /** Exact durable outbox body. Never rewrite reporterSessionId, digest or sequence. */
-    observation: IRuntimeAssignmentObservationV1;
+    observation: IRuntimeAssignmentObservation;
 }
-export type TRuntimeObservationAuthorityUseV1 = 'current-session' | 'historical-recovery';
+export type TRuntimeObservationAuthorityUse = 'current-session' | 'historical-recovery';
 /** Content comparison result only; all supplied authority must come from its trusted owner. */
-export interface IRuntimeReporterSessionBindingV1 {
-    session: IRuntimeSessionBindingV1;
-    assignment: IRuntimeAssignmentV1;
-    reporterHistory: IRuntimeSessionBindingV1;
-    authorityUse: TRuntimeObservationAuthorityUseV1;
+export interface IRuntimeReporterSessionBinding {
+    session: IRuntimeSessionBinding;
+    assignment: IRuntimeAssignment;
+    reporterHistory: IRuntimeSessionBinding;
+    authorityUse: TRuntimeObservationAuthorityUse;
 }
-export interface IReportRuntimeAssignmentObservationResponseV1 {
+export interface IReportRuntimeAssignmentObservationResponse {
     /** Exact request body after a durable sequence/receipt transaction. */
-    observation: IRuntimeAssignmentObservationV1;
+    observation: IRuntimeAssignmentObservation;
     /**
      * Historical recovery can advance the durable counter and ACK only. It must not
      * update active readiness, routing or liveness; those require a fresh report
      * from the current session. Neither classification is proof of writer fencing.
      */
-    authorityUse: TRuntimeObservationAuthorityUseV1;
+    authorityUse: TRuntimeObservationAuthorityUse;
 }
-export interface IGetRuntimeRegistryCredentialRequestV1 {
-    session: IRuntimeSessionBindingV1;
+export interface IGetRuntimeRegistryCredentialRequest {
+    session: IRuntimeSessionBinding;
     /** The server must authorize this exact CURRENT assignment, including its node. */
-    assignment: IRuntimeAssignmentReferenceV1;
+    assignment: IRuntimeAssignmentReference;
 }
 /** Sensitive ephemeral material; never persist, hash, log or include in diagnostics. */
-export interface IGetRuntimeRegistryCredentialResponseV1 {
+export interface IGetRuntimeRegistryCredentialResponse {
     username: string;
     password: string;
     expiresAt: number;
 }
 /** Cloudly human/machine JWT registration on a physical TypedSocket; reject HTTP. */
-export interface IRegisterCloudlyClientSessionRequestV1 {
-    schemaVersion: 1;
+export interface IRegisterCloudlyClientSessionRequest {
     /** Authenticate the current JWT server-side; do not accept client identity claims. */
     identity: IIdentityCredential;
+    /** Read and negotiated before the identity is authenticated; see `runtimeSessionContract`. */
+    protocol: IProtocolOffer;
 }
-export interface IRegisterCloudlyClientSessionResponseV1 {
+export interface IRegisterCloudlyClientSessionResponse {
     /** Server-owned identity tagging completed; never trust a client-authored tag. */
     registered: true;
+    /** The controller's offer, so an accepted client can judge the session it just opened. */
+    protocol: IProtocolOffer;
 }
-export declare const runtimeSessionV1Contract: Readonly<{
+/**
+ * The rules every runtime session registration is judged by.
+ *
+ * Every carrier here is judged in the one server order `protocol.readProtocolOffer` states,
+ * against this session kind's own offer, so the snapshots below see a body whose offer this
+ * controller already accepted. For a node that order is also what keeps a refused registration
+ * from touching its packet access: the refusal is named before `networkVpn` is asked to mutate
+ * anything.
+ */
+export declare const runtimeSessionContract: Readonly<{
     readonly maximumWireCanonicalBytes: 327680;
     readonly maximumCredentialBytes: 16384;
     readonly maximumRegistryPasswordBytes: 8192;
@@ -100,33 +133,38 @@ export declare const runtimeSessionV1Contract: Readonly<{
     readonly nodeInstanceNonceFormat: "canonical-lowercase-uuid-per-node-process";
     /** The registration a controller must treat as one: a change in any part is a new session. */
     readonly registrationIdentity: "node-id-and-credential-generation-and-node-instance-nonce";
-    /** A relay socket carries many nodes, so its transport cannot prove a node process. */
-    readonly relayRegistrationRequiresNodeInstanceNonce: true;
     readonly error: "Runtime session contract rejected.";
 }>;
 /** Synchronous detached structural assertion only; never an authentication check. */
-export declare const snapshotRuntimeSessionBindingV1: (valueArg: unknown) => IRuntimeSessionBindingV1;
-export declare const snapshotRegisterPalletRuntimeSessionRequestV1: (valueArg: unknown) => IRegisterPalletRuntimeSessionRequestV1;
-export declare const snapshotApplyRuntimeAssignmentRequestV1: (valueArg: unknown) => IApplyRuntimeAssignmentRequestV1;
-export declare const snapshotApplyRuntimeAssignmentResponseV1: (valueArg: unknown) => IApplyRuntimeAssignmentResponseV1;
-export declare const snapshotReportRuntimeAssignmentObservationRequestV1: (valueArg: unknown) => IReportRuntimeAssignmentObservationRequestV1;
-export declare const snapshotReportRuntimeAssignmentObservationResponseV1: (valueArg: unknown) => IReportRuntimeAssignmentObservationResponseV1;
-export declare const snapshotGetRuntimeRegistryCredentialRequestV1: (valueArg: unknown) => IGetRuntimeRegistryCredentialRequestV1;
-export declare const snapshotGetRuntimeRegistryCredentialResponseV1: (valueArg: unknown) => IGetRuntimeRegistryCredentialResponseV1;
-export declare const snapshotRegisterCloudlyClientSessionRequestV1: (valueArg: unknown) => IRegisterCloudlyClientSessionRequestV1;
-export declare const snapshotRegisterCloudlyClientSessionResponseV1: (valueArg: unknown) => IRegisterCloudlyClientSessionResponseV1;
-/** Bind the authenticated Cloudly registration reply to the node and credential sent. */
-export declare const bindRegisterPalletRuntimeSessionResponseV1: (valueArg: unknown, requestArg: unknown) => IRuntimeSessionBindingV1;
+export declare const snapshotRuntimeSessionBinding: (valueArg: unknown) => IRuntimeSessionBinding;
+export declare const snapshotRegisterPalletRuntimeSessionRequest: (valueArg: unknown) => IRegisterPalletRuntimeSessionRequest;
+export declare const snapshotRegisterPalletRuntimeSessionResponse: (valueArg: unknown) => IRegisterPalletRuntimeSessionResponse;
+export declare const snapshotApplyRuntimeAssignmentRequest: (valueArg: unknown) => IApplyRuntimeAssignmentRequest;
+export declare const snapshotApplyRuntimeAssignmentResponse: (valueArg: unknown) => IApplyRuntimeAssignmentResponse;
+export declare const snapshotReportRuntimeAssignmentObservationRequest: (valueArg: unknown) => IReportRuntimeAssignmentObservationRequest;
+export declare const snapshotReportRuntimeAssignmentObservationResponse: (valueArg: unknown) => IReportRuntimeAssignmentObservationResponse;
+export declare const snapshotGetRuntimeRegistryCredentialRequest: (valueArg: unknown) => IGetRuntimeRegistryCredentialRequest;
+export declare const snapshotGetRuntimeRegistryCredentialResponse: (valueArg: unknown) => IGetRuntimeRegistryCredentialResponse;
+export declare const snapshotRegisterCloudlyClientSessionRequest: (valueArg: unknown) => IRegisterCloudlyClientSessionRequest;
+export declare const snapshotRegisterCloudlyClientSessionResponse: (valueArg: unknown) => IRegisterCloudlyClientSessionResponse;
+/**
+ * Bind the authenticated Cloudly registration reply to the node, credential and offer sent.
+ *
+ * The client negotiates the answered offer against the one it sent: acceptance by a controller is
+ * that controller's judgement, and a node that cannot serve the session it was given must not open
+ * it. Both offers were read from the two bodies, so this compares what was actually exchanged.
+ */
+export declare const bindRegisterPalletRuntimeSessionResponse: (valueArg: unknown, requestArg: unknown) => IRegisterPalletRuntimeSessionResponse;
 /** Reject already expired material; issuance policy and current assignment authority remain server-owned. */
-export declare const bindGetRuntimeRegistryCredentialResponseV1: (valueArg: unknown, nowArg: number) => IGetRuntimeRegistryCredentialResponseV1;
+export declare const bindGetRuntimeRegistryCredentialResponse: (valueArg: unknown, nowArg: number) => IGetRuntimeRegistryCredentialResponse;
 /**
  * Capture every input before awaiting digest verification. trustedSessionArg must
  * come from the receiving live connection, never from another request field.
  * This binds content only; durable CAS, slot admission and authority remain owners.
  */
-export declare const bindApplyRuntimeAssignmentRequestV1: (valueArg: unknown, trustedSessionArg: unknown) => Promise<IApplyRuntimeAssignmentRequestV1>;
+export declare const bindApplyRuntimeAssignmentRequest: (valueArg: unknown, trustedSessionArg: unknown) => Promise<IApplyRuntimeAssignmentRequest>;
 /** Match an admission acknowledgement to the exact sent revision, including historical replies. */
-export declare const bindApplyRuntimeAssignmentResponseV1: (valueArg: unknown, requestArg: unknown) => IApplyRuntimeAssignmentResponseV1;
+export declare const bindApplyRuntimeAssignmentResponse: (valueArg: unknown, requestArg: unknown) => IApplyRuntimeAssignmentResponse;
 /**
  * Synchronous detached content binding, not authentication. trustedSessionArg must
  * be the CURRENT authenticated physical peer; reporterHistoryArg must be immutable
@@ -134,23 +172,23 @@ export declare const bindApplyRuntimeAssignmentResponseV1: (valueArg: unknown, r
  * The owning transaction must recheck current credential/peer authority. Assignment
  * digest validation and report-specific authority remain the caller's responsibility.
  */
-export declare const bindRuntimeReporterSessionV1: (sessionArg: unknown, reporterSessionIdArg: string, assignmentArg: unknown, trustedSessionArg: unknown, reporterHistoryArg: unknown) => IRuntimeReporterSessionBindingV1;
+export declare const bindRuntimeReporterSession: (sessionArg: unknown, reporterSessionIdArg: string, assignmentArg: unknown, trustedSessionArg: unknown, reporterHistoryArg: unknown) => IRuntimeReporterSessionBinding;
 /**
  * trustedSessionArg is the CURRENT authenticated physical peer. reporterHistoryArg
  * must be server-indexed immutable session history, obtained by the original
- * observation's reporterSessionId; never accept caller-supplied history. All V1
- * runtime sessions are Pallet-purpose sessions, so Spark history cannot qualify.
+ * observation's reporterSessionId; never accept caller-supplied history. Every
+ * runtime session is a Pallet-purpose session, so Spark history cannot qualify.
  *
  * This verifies content and classifies recovery, not authentication, history
  * provenance, sequence admission or current authority. The server must transact
  * receipt/counter acceptance under current credential and peer authority. A
  * historical result MUST NOT restore active readiness, routes or liveness.
  */
-export declare const bindReportRuntimeAssignmentObservationRequestV1: (valueArg: unknown, assignmentArg: unknown, trustedSessionArg: unknown, reporterHistoryArg: unknown) => Promise<{
-    request: IReportRuntimeAssignmentObservationRequestV1;
-    authorityUse: TRuntimeObservationAuthorityUseV1;
+export declare const bindReportRuntimeAssignmentObservationRequest: (valueArg: unknown, assignmentArg: unknown, trustedSessionArg: unknown, reporterHistoryArg: unknown) => Promise<{
+    request: IReportRuntimeAssignmentObservationRequest;
+    authorityUse: TRuntimeObservationAuthorityUse;
 }>;
 /** Reject body rewriting and a historical receipt mislabeled as current authority. */
-export declare const bindReportRuntimeAssignmentObservationResponseV1: (valueArg: unknown, requestArg: unknown) => IReportRuntimeAssignmentObservationResponseV1;
+export declare const bindReportRuntimeAssignmentObservationResponse: (valueArg: unknown, requestArg: unknown) => IReportRuntimeAssignmentObservationResponse;
 /** Current assignment lookup and live peer authorization remain mandatory server-owned inputs. */
-export declare const bindGetRuntimeRegistryCredentialRequestV1: (valueArg: unknown, assignmentArg: unknown, trustedSessionArg: unknown) => Promise<IGetRuntimeRegistryCredentialRequestV1>;
+export declare const bindGetRuntimeRegistryCredentialRequest: (valueArg: unknown, assignmentArg: unknown, trustedSessionArg: unknown) => Promise<IGetRuntimeRegistryCredentialRequest>;