@serve.zone/interfaces 32.14.0 → 32.16.0

package/ts/data/runtimestorageclaim.ts

@@ -3,6 +3,8 @@ import type { IRuntimeAssignment, IRuntimeAuthorityReference, IRuntimeController
 import { snapshotRuntimeAssignment, validateRuntimeAssignment } from './runtimeassignment.js';
 import { normalizeServiceAbsolutePath } from './service.js';
 import type { IResolvedFilesystemStorageBinding } from '../platform/storage.js';
+import type { IAppStoreFilesystemStorageRequest } from '../appstore/types.js';
+import { createStorageRequestSha256, normalizeStorageRequest } from '../platform/storage.js';
 import { canonicalizeStrictJson, createCanonicalJsonSha256Hex } from '../private/canonicaljson.js';
 import { isClusterNodeId } from '../private/nodeidentifier.js';
 
@@ -16,6 +18,35 @@ export interface IRuntimeStorageClaimBinding extends Pick<IResolvedFilesystemSto
   capabilities: { durability: 'persistent'; topology: 'singleNode' };
 }
 
+/**
+ * Cloudly's requested filesystem binding identity before the storage provider reports readiness.
+ * Provider-produced observation, resource and capability fields cannot be stated in this shape.
+ */
+export interface IRuntimeStorageClaimRequestedFilesystemBinding {
+  serviceId: string;
+  request: IAppStoreFilesystemStorageRequest & {
+    accessMode: 'ReadWriteOnce';
+    reclaimPolicy: 'retain';
+  };
+  requestDigest: string;
+}
+
+/** Cloudly-owned claim identity and desired request before a provider-produced ready binding exists. */
+export interface IRuntimeStorageClaimIntent {
+  id: string;
+  generation: number;
+  previous: IRuntimeAuthorityReference | null;
+  controller: IRuntimeController & { kind: 'cloudly' };
+  organizationId: string;
+  clusterId: string;
+  nodeId: string;
+  runtimeNamespace: string;
+  serviceId: string;
+  requestedBinding: IRuntimeStorageClaimRequestedFilesystemBinding;
+  reclaimPolicy: 'retain';
+  digest: TSha256Digest;
+}
+
 /** Cloudly authority for one retained, node-local volume; no host path or attachment attempt. */
 export interface IRuntimeStorageClaim {
   id: string;
@@ -33,6 +64,7 @@ export interface IRuntimeStorageClaim {
 }
 
 export const runtimeStorageClaimContract = Object.freeze({
+  intentDigestDomain: 'serve.zone/runtime-storage-claim-intent',
   digestDomain: 'serve.zone/runtime-storage-claim',
   accessMode: 'ReadWriteOnce',
   reclaimPolicy: 'retain',
@@ -71,6 +103,10 @@ const digest = (valueArg: unknown): TSha256Digest => {
   requireValue(typeof valueArg === 'string' && /^sha256:[a-f0-9]{64}$/.test(valueArg));
   return valueArg as TSha256Digest;
 };
+const requestDigest = (valueArg: unknown): string => {
+  requireValue(typeof valueArg === 'string' && /^[a-f0-9]{64}$/.test(valueArg));
+  return valueArg as string;
+};
 const reference = (valueArg: unknown): IRuntimeAuthorityReference => {
   const value = record(valueArg, ['id', 'generation', 'digest']);
   return { id: assignmentId(value.id), generation: generation(value.generation), digest: digest(value.digest) };
@@ -86,26 +122,72 @@ const mountPath = (valueArg: unknown): string => {
     && !valueArg.startsWith('/run/secrets/') && !'/run/secrets'.startsWith(`${valueArg}/`));
   return valueArg as string;
 };
+const requestedBinding = (valueArg: unknown): IRuntimeStorageClaimRequestedFilesystemBinding => {
+  const value = record(valueArg, ['serviceId', 'request', 'requestDigest']);
+  const request = normalizeStorageRequest(value.request);
+  requireValue(request.kind === 'filesystem' && request.accessMode === 'ReadWriteOnce'
+    && request.reclaimPolicy === 'retain' && mountPath(request.mountPath) === request.mountPath);
+  return { serviceId: assignmentId(value.serviceId),
+    request: request as IRuntimeStorageClaimRequestedFilesystemBinding['request'],
+    requestDigest: requestDigest(value.requestDigest) };
+};
 const binding = (valueArg: unknown): IRuntimeStorageClaimBinding => {
   const value = record(valueArg, ['id', 'serviceId', 'requestId', 'requestDigest', 'kind',
     'generation', 'observedGeneration', 'status', 'policy', 'resourceRef', 'mountPath',
     'accessMode', 'capabilities']);
   requireValue(value.kind === 'filesystem' && value.status === 'ready'
-    && value.accessMode === 'ReadWriteOnce'
-    && typeof value.requestDigest === 'string' && /^[a-f0-9]{64}$/.test(value.requestDigest));
+    && value.accessMode === 'ReadWriteOnce');
   const policy = record(value.policy, ['classId', 'revision']);
   const capabilities = record(value.capabilities, ['durability', 'topology']);
   requireValue(capabilities.durability === 'persistent' && capabilities.topology === 'singleNode');
   const bindingGeneration = generation(value.generation);
   requireValue(generation(value.observedGeneration) === bindingGeneration);
   return { id: id(value.id), serviceId: assignmentId(value.serviceId), requestId: id(value.requestId),
-    requestDigest: value.requestDigest as string, kind: 'filesystem', generation: bindingGeneration,
+    requestDigest: requestDigest(value.requestDigest), kind: 'filesystem', generation: bindingGeneration,
     observedGeneration: bindingGeneration, status: 'ready',
     policy: { classId: id(policy.classId), revision: id(policy.revision) },
     resourceRef: id(value.resourceRef), mountPath: mountPath(value.mountPath),
     accessMode: 'ReadWriteOnce', capabilities: { durability: 'persistent', topology: 'singleNode' } };
 };
 
+/** Detached exact-schema snapshot. This shape deliberately cannot state provider readiness. */
+export const snapshotRuntimeStorageClaimIntent = (valueArg: unknown): IRuntimeStorageClaimIntent => {
+  const value = record(valueArg, ['id', 'generation', 'previous', 'controller', 'organizationId',
+    'clusterId', 'nodeId', 'runtimeNamespace', 'serviceId', 'requestedBinding', 'reclaimPolicy', 'digest']);
+  const claimId = assignmentId(value.id), claimGeneration = generation(value.generation);
+  const previous = value.previous === null ? null : reference(value.previous);
+  requireValue(claimGeneration === 1 ? previous === null
+    : previous?.id === claimId && previous.generation === claimGeneration - 1);
+  requireValue(isClusterNodeId(value.nodeId) && value.reclaimPolicy === 'retain');
+  const claimBinding = requestedBinding(value.requestedBinding), serviceId = assignmentId(value.serviceId);
+  requireValue(claimBinding.serviceId === serviceId);
+  return { id: claimId, generation: claimGeneration, previous, controller: controller(value.controller),
+    organizationId: assignmentId(value.organizationId), clusterId: id(value.clusterId),
+    nodeId: value.nodeId as string, runtimeNamespace: assignmentId(value.runtimeNamespace), serviceId,
+    requestedBinding: claimBinding, reclaimPolicy: 'retain', digest: digest(value.digest) };
+};
+
+export const computeRuntimeStorageClaimIntentDigest = async (valueArg: unknown): Promise<TSha256Digest> => {
+  const { digest: _digest, ...payload } = snapshotRuntimeStorageClaimIntent(valueArg);
+  return `sha256:${await createCanonicalJsonSha256Hex(canonicalizeStrictJson({
+    domain: runtimeStorageClaimContract.intentDigestDomain, payload,
+  }, fail), fail)}`;
+};
+
+export const validateRuntimeStorageClaimIntent = async (valueArg: unknown): Promise<string[]> => {
+  try {
+    const intent = snapshotRuntimeStorageClaimIntent(valueArg);
+    if (intent.requestedBinding.requestDigest
+      !== await createStorageRequestSha256(intent.requestedBinding.request)) {
+      return ['runtime storage claim intent request digest does not match'];
+    }
+    return intent.digest === await computeRuntimeStorageClaimIntentDigest(intent)
+      ? [] : ['runtime storage claim intent digest does not match'];
+  } catch {
+    return ['runtime storage claim intent must use its exact canonical schema'];
+  }
+};
+
 /** Detached exact-schema snapshot. Digest and authoritative provider readiness are separate checks. */
 export const snapshotRuntimeStorageClaim = (valueArg: unknown): IRuntimeStorageClaim => {
   const value = record(valueArg, ['id', 'generation', 'previous', 'controller', 'organizationId',
@@ -140,6 +222,43 @@ export const validateRuntimeStorageClaim = async (valueArg: unknown): Promise<st
   }
 };
 
+/**
+ * Joins Cloudly-owned identity and request facts to a provider-produced ready binding.
+ * This content check does not authenticate either producer or grant attachment authority.
+ */
+export const bindRuntimeStorageClaimToIntent = async (
+  claimArg: unknown,
+  intentArg: unknown,
+): Promise<{ claim: IRuntimeStorageClaim; intent: IRuntimeStorageClaimIntent }> => {
+  const claim = snapshotRuntimeStorageClaim(claimArg);
+  const intent = snapshotRuntimeStorageClaimIntent(intentArg);
+  if ((await validateRuntimeStorageClaim(claim)).length
+    || (await validateRuntimeStorageClaimIntent(intent)).length) fail();
+  const claimPrevious = claim.previous, intentPrevious = intent.previous;
+  requireValue(claim.id === intent.id
+    && claim.generation === intent.generation
+    && (claimPrevious === null
+      ? intentPrevious === null
+      : intentPrevious !== null
+        && claimPrevious.id === intentPrevious.id
+        && claimPrevious.generation === intentPrevious.generation
+        && claimPrevious.digest === intentPrevious.digest)
+    && claim.controller.id === intent.controller.id
+    && claim.controller.epoch === intent.controller.epoch
+    && claim.organizationId === intent.organizationId
+    && claim.clusterId === intent.clusterId
+    && claim.nodeId === intent.nodeId
+    && claim.runtimeNamespace === intent.runtimeNamespace
+    && claim.serviceId === intent.serviceId
+    && claim.binding.serviceId === intent.requestedBinding.serviceId
+    && claim.binding.requestId === intent.requestedBinding.request.id
+    && claim.binding.requestDigest === intent.requestedBinding.requestDigest
+    && claim.binding.mountPath === intent.requestedBinding.request.mountPath
+    && claim.binding.accessMode === intent.requestedBinding.request.accessMode
+    && claim.reclaimPolicy === intent.reclaimPolicy);
+  return { claim, intent };
+};
+
 /** Content binding only; controller authentication, provider checks and attachment fencing remain owner-owned. */
 export const bindRuntimeStorageClaimToAssignment = async (
   claimArg: unknown, assignmentArg: unknown, expectedClusterIdArg: unknown,

package/ts/requests/fleetcutover.ts

@@ -5,6 +5,10 @@ import type { IServiceRuntimeSpec } from '../data/serviceruntime.js';
 import type {
   IFleetCutoverAcceptedEvidenceReference,
   IFleetCutoverCorestoreAdoptionReceipt,
+  IFleetCutoverPreparedVolumeHandoffAggregate,
+  IFleetCutoverPreparedVolumeHandoffIntent,
+  IFleetCutoverPreparedVolumeHandoffMutation,
+  IFleetCutoverStorageAdoptionBundle,
   IFleetCutoverIngressDesignation,
   IFleetCutoverIngressPreparationRequest,
   IFleetCutoverIngressAuthority,
@@ -15,6 +19,7 @@ import type {
   TFleetCutoverRuntimeSpecRelease,
   TFleetCutoverVolumeFence,
 } from '../data/fleetcutover.js';
+import type { IRuntimeStorageClaim } from '../data/runtimestorageclaim.js';
 
 export interface IReq_Any_Cloudly_GetFleetCutoverScope
 extends plugins.typedrequestInterfaces.implementsTR<
@@ -44,6 +49,28 @@ extends plugins.typedrequestInterfaces.implementsTR<
   response: { scope: IFleetCutoverScope };
 }
 
+/**
+ * Admin CAS input selects authenticated legacy mounts and desired filesystem requests. Cloudly
+ * derives every owner identity and evidence reference, then rewrites one complete aggregate
+ * revision without truncating untouched entries.
+ */
+export interface IReq_Admin_Cloudly_PrepareFleetCutoverVolumeHandoffs
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Admin_Cloudly_PrepareFleetCutoverVolumeHandoffs
+> {
+  method: 'prepareFleetCutoverVolumeHandoffs';
+  request: {
+    identity: IIdentityCredential;
+    mutation: IFleetCutoverPreparedVolumeHandoffMutation;
+  };
+  response: {
+    aggregate: IFleetCutoverPreparedVolumeHandoffAggregate;
+    handoffs: IFleetCutoverPreparedVolumeHandoffIntent[];
+    replayed: boolean;
+  };
+}
+
 /**
  * Forward-only legal phase CAS. All receipt references are dereferenced by Cloudly in the same
  * transaction; caller-supplied records or booleans never satisfy a cutover condition.
@@ -104,7 +131,10 @@ extends plugins.typedrequestInterfaces.implementsTR<
   response: { authority: IFleetCutoverIngressAuthority | null };
 }
 
-/** Root-local only. Holding an intent creates negative storage authority and no runtime session. */
+/**
+ * @deprecated Published 32.x declaration retained for wire compatibility. Production owners do
+ * not register it; remove at the next protocol major.
+ */
 export interface IReq_PalletLocal_Pallet_HoldFleetCutoverVolumeFence
 extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
@@ -115,6 +145,17 @@ extends plugins.typedrequestInterfaces.implementsTR<
   response: { fence: Extract<TFleetCutoverVolumeFence, { state: 'held' }> };
 }
 
+/** Spark calls only this fixed root-private Pallet socket operation for a prepared handoff. */
+export interface IReq_SparkLocal_Pallet_HoldPreparedFleetCutoverVolumeFence
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_SparkLocal_Pallet_HoldPreparedFleetCutoverVolumeFence
+> {
+  method: 'holdPreparedFleetCutoverVolumeFence';
+  request: { fenceId: string; handoffIntent: IFleetCutoverPreparedVolumeHandoffIntent };
+  response: { fence: Extract<TFleetCutoverVolumeFence, { state: 'held' }> };
+}
+
 export interface IReq_PalletLocal_Pallet_GetFleetCutoverVolumeFence
 extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
@@ -126,8 +167,8 @@ extends plugins.typedrequestInterfaces.implementsTR<
 }
 
 /**
- * Pallet consumes the local fence only around a current accepted Corestore adoption result. The
- * receipt carries the real ready storage-claim reference; the earlier handoff intent does not.
+ * @deprecated Ownership-inverted published 32.x declaration. Production owners do not register
+ * or adapt it; remove at the next protocol major.
  */
 export interface IReq_PalletLocal_Pallet_ConsumeFleetCutoverVolumeFence
 extends plugins.typedrequestInterfaces.implementsTR<
@@ -143,8 +184,22 @@ extends plugins.typedrequestInterfaces.implementsTR<
 }
 
 /**
- * Corestore owns the one-shot initial lineage/RWO CAS. The local caller supplies the held fence
- * and server-owned handoff intent; Corestore returns the claim only after its provider is ready.
+ * Root-private trigger names only the durable hold. Pallet owns the per-volume lane, obtains and
+ * later revalidates a current controller grant, invokes Corestore, then consumes atomically.
+ */
+export interface IReq_PalletLocal_Pallet_AdoptFleetCutoverVolumeFence
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_PalletLocal_Pallet_AdoptFleetCutoverVolumeFence
+> {
+  method: 'adoptFleetCutoverVolumeFence';
+  request: { fence: IFleetCutoverAcceptedEvidenceReference };
+  response: { bundle: IFleetCutoverStorageAdoptionBundle };
+}
+
+/**
+ * @deprecated Published 32.x declaration retained but unsupported and unregistered. Its handoff
+ * cannot carry the complete desired claim intent; remove at the next protocol major.
  */
 export interface IReq_Pallet_Corestore_AdoptFleetCutoverVolume
 extends plugins.typedrequestInterfaces.implementsTR<
@@ -158,3 +213,23 @@ extends plugins.typedrequestInterfaces.implementsTR<
   };
   response: { adoption: IFleetCutoverCorestoreAdoptionReceipt };
 }
+
+/**
+ * Private isolated one-shot invocation. Corestore performs physical-lineage proof and initial
+ * ready-claim CAS while its native attachment fence is held, with no callback into Pallet.
+ */
+export interface IReq_Pallet_Corestore_AdoptPreparedFleetCutoverVolume
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Pallet_Corestore_AdoptPreparedFleetCutoverVolume
+> {
+  method: 'adoptPreparedFleetCutoverVolume';
+  request: {
+    handoffIntent: IFleetCutoverPreparedVolumeHandoffIntent;
+    palletFence: Extract<TFleetCutoverVolumeFence, { state: 'held' }>;
+  };
+  response: {
+    adoption: IFleetCutoverCorestoreAdoptionReceipt;
+    claim: IRuntimeStorageClaim;
+  };
+}

package/ts/requests/runtimesession.ts

@@ -5,6 +5,8 @@ import type * as network from '../data/networkdelivery.js';
 import type * as protection from '../data/networkprotection.js';
 import type * as credential from '../data/networkcredential.js';
 import type * as assignmentSecret from '../runtime.assignmentsecret.js';
+import type * as fleet from '../data/fleetcutover.js';
+import type { IRuntimeStorageClaim } from '../data/runtimestorageclaim.js';
 
 /** Current-peer, exact-projection authorization; response contains secret keys. */
 export interface IReq_Pallet_Controller_GetRuntimeManagedVpnCredential extends plugins.typedrequestInterfaces.implementsTR<
@@ -24,6 +26,61 @@ export interface IReq_Pallet_Controller_ReportRuntimeNetworkProtection extends p
   response: protection.IReportRuntimeNetworkProtectionResponse;
 }
 
+/**
+ * Current authenticated Pallet session only. Cloudly reads the current pallet runtime and exact
+ * owner records, then grants one held prepared handoff; serialized session content is no proof.
+ */
+export interface IReq_Pallet_Controller_AuthorizeFleetCutoverStorageAdoption
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Pallet_Controller_AuthorizeFleetCutoverStorageAdoption
+> {
+  method: 'authorizeFleetCutoverStorageAdoption';
+  request: {
+    session: data.IRuntimeSessionBinding;
+    handoffIntent: fleet.IFleetCutoverAcceptedEvidenceReference;
+    fence: fleet.IFleetCutoverAcceptedEvidenceReference;
+  };
+  response: { grant: fleet.IFleetCutoverStorageAdoptionGrant; replayed: boolean };
+}
+
+/**
+ * Pallet revalidates current session, pallet phase and grant after the provider call, then reports
+ * the exact consumed bundle. A stale grant leaves the durable local hold unchanged.
+ */
+export interface IReq_Pallet_Controller_ReportFleetCutoverStorageAdoption
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Pallet_Controller_ReportFleetCutoverStorageAdoption
+> {
+  method: 'reportFleetCutoverStorageAdoption';
+  request: {
+    session: data.IRuntimeSessionBinding;
+    bundle: fleet.IFleetCutoverStorageAdoptionBundle;
+  };
+  response: {
+    status: 'accepted' | 'replay';
+    grant: fleet.IFleetCutoverAcceptedEvidenceReference;
+    fence: fleet.IFleetCutoverAcceptedEvidenceReference;
+    adoption: fleet.IFleetCutoverAcceptedEvidenceReference;
+    claim: fleet.IFleetCutoverAcceptedEvidenceReference;
+  };
+}
+
+/** Current-session read of one accepted ready claim by its exact immutable reference. */
+export interface IReq_Pallet_Controller_GetRuntimeStorageClaim
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Pallet_Controller_GetRuntimeStorageClaim
+> {
+  method: 'getRuntimeStorageClaim';
+  request: {
+    session: data.IRuntimeSessionBinding;
+    claim: fleet.IFleetCutoverAcceptedEvidenceReference;
+  };
+  response: { claim: IRuntimeStorageClaim };
+}
+
 /** Dedicated signing trust installed only through the current authenticated physical peer. */
 export interface IReq_Controller_Pallet_ApplyRuntimeNetworkSigningAuthority extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest, IReq_Controller_Pallet_ApplyRuntimeNetworkSigningAuthority