@serve.zone/interfaces 31.8.0 → 32.0.0

package/ts/data/serviceruntime.ts

@@ -0,0 +1,208 @@
+import type {
+  IRuntimeAssignmentObservation, IRuntimeAssignmentReference, TRuntimeAssignmentDisposition,
+} from './runtimeassignment.js';
+import type { IRuntimeConfigLogPolicy, TRuntimeConfigReadiness } from './runtimeconfig.js';
+import { runtimeNetworkAuthorityContract } from './networkauthority.js';
+import { captureNetwork, networkCanonical, networkCounter, networkId, networkList, networkRecord, networkSorted,
+  requireNetwork } from '../private/networkcontract.js';
+import { failProducer, isOneOf, producerSafe, variantOf } from '../private/producercontract.js';
+import { assertRuntimeReadiness, isBoundedInteger, isRuntimeCpuMillis, isRuntimeIdentityNumber, isRuntimeLogPolicy,
+  isRuntimeMemoryBytes } from '../private/runtimepolicy.js';
+
+/** `nodes` pins the service to exactly these nodes: sorted, unique and never empty. */
+export type TServiceRuntimePlacement =
+  | { kind: 'every-node' }
+  | { kind: 'nodes'; nodeIds: string[] };
+
+/**
+ * The execution policy a service's runtime configs are built with. It carries everything the
+ * runtime config seals except what only the service and its image supply: environment, working
+ * directory and target ports. A readiness probe names a target port, which the runtime config then
+ * requires the service to declare.
+ */
+export interface IServiceRuntimeProfile {
+  /** null explicitly requests no CPU quota. */
+  cpuMillis: number | null;
+  memoryBytes: number;
+  readiness: TRuntimeConfigReadiness;
+  logs: IRuntimeConfigLogPolicy;
+  readonlyRootfs: boolean;
+  /** null runs the image's own OCI user, exactly as a runtime config's null identity pair does. */
+  runAs: { user: number; group: number } | null;
+}
+
+/**
+ * `isolated` gives the workload no network authority. `attached` joins the runtime network with
+ * public egress on or off and the platform endpoints it may reach, by id: sorted and unique.
+ */
+export type TServiceRuntimeNetwork =
+  | { mode: 'isolated' }
+  | { mode: 'attached'; publicEgress: boolean; platformEndpointIds: string[] };
+
+/**
+ * What Cloudly runs for one service on a Pallet cluster. Stored complete, never defaulted at read
+ * time, and beside the service document rather than inside it, so a hold written by a cutover
+ * never races an operator's service edit.
+ */
+export interface IServiceRuntimeSpec {
+  /** The service id. */
+  id: string;
+  /** The service's organization, copied by Cloudly; never caller-chosen. */
+  organizationId: string;
+  clusterId: string;
+  placement: TServiceRuntimePlacement;
+  replicasPerNode: number;
+  /** While true, the service runs nowhere and every slot keeps its storage. */
+  hold: boolean;
+  profile: IServiceRuntimeProfile;
+  network: TServiceRuntimeNetwork;
+  /** Compare-and-swap counter; every write advances it by one. */
+  revision: number;
+}
+
+/** What an administrator writes; Cloudly supplies the service id, organization and revision. */
+export type TServiceRuntimeSpecWritableData = Omit<IServiceRuntimeSpec, 'id' | 'organizationId' | 'revision'>;
+
+export const serviceRuntimeContract = Object.freeze({
+  maximumReplicasPerNode: 64,
+  /** A service whose placement desires more replicas than this is refused as `replica-limit`. */
+  maximumReplicas: 64,
+  /** A node can run workloads only as an egress member of the protected authority, which admits at most this many. */
+  maximumPinnedNodes: runtimeNetworkAuthorityContract.maximumEgressAuthorities,
+  maximumPlatformEndpoints: runtimeNetworkAuthorityContract.maximumPlatformEndpoints,
+  /** The largest `limit` `getClusterRuntimeAssignments` accepts; Cloudly refuses a larger one. */
+  maximumAssignmentPageSize: 256,
+} as const);
+
+const serviceRuntimeWaitingReasons = ['node-network-pending', 'conflict', 'failure-backoff'] as const;
+const serviceRuntimeRefusals = [
+  'cluster-runtime-missing', 'organization-missing', 'image-plan-missing', 'platform-unsupported',
+  'secrets-unsupported', 'volumes-unsupported', 'port-protocol-unsupported', 'readiness-target-undeclared',
+  'environment-too-large', 'no-eligible-node', 'replica-limit',
+] as const;
+
+/**
+ * Why the producer is not converging yet, though nothing needs an administrator:
+ * `node-network-pending` waits for a node's network readiness, `conflict` for a sweep over inputs
+ * that changed while it ran, `failure-backoff` for a failed replica's backoff to elapse.
+ */
+export type TServiceRuntimeWaitingReason = typeof serviceRuntimeWaitingReasons[number];
+
+/** Why the producer admits nothing for this spec revision. A refusal never retires running slots. */
+export type TServiceRuntimeRefusal = typeof serviceRuntimeRefusals[number];
+
+interface IServiceRuntimeStatusBase {
+  /** The service id. */
+  id: string;
+  /** The spec revision this verdict is about. */
+  specRevision: number;
+  /** Unix milliseconds on Cloudly's clock. Written only when the verdict changes. */
+  changedAt: number;
+}
+
+/** The producer's verdict on one spec revision. */
+export type IServiceRuntimeStatus = IServiceRuntimeStatusBase & (
+  | { state: 'converged' | 'converging'; reason: null }
+  | { state: 'waiting'; reason: TServiceRuntimeWaitingReason }
+  | { state: 'refused'; reason: TServiceRuntimeRefusal }
+);
+
+/**
+ * `delivered` once the node's own evidence, an observation or a terminal receipt, cites this exact
+ * revision; `undelivered` until then. Cloudly keeps no acknowledgement journal, so a revision the
+ * node admitted but has not yet reported on reads as undelivered.
+ */
+export type TServiceRuntimeAssignmentDelivery = 'undelivered' | 'delivered';
+
+/** One replica slot's current assignment, as an administrator reads it. */
+export interface IServiceRuntimeAssignmentView {
+  serviceId: string;
+  replicaId: string;
+  nodeId: string;
+  /** The current revision; its generation is the one the disposition belongs to. */
+  assignment: IRuntimeAssignmentReference;
+  disposition: TRuntimeAssignmentDisposition;
+  /** The latest accepted observation of this attempt, which may cite an earlier revision. */
+  observation: Pick<IRuntimeAssignmentObservation, 'phase' | 'ready' | 'observedAt' | 'sequence'> | null;
+  /** Joined stop and remove receipts of this attempt. */
+  terminalReceiptCount: 0 | 1 | 2;
+  delivery: TServiceRuntimeAssignmentDelivery;
+}
+
+const sortedIds = (value: unknown, maximum: number): string[] =>
+  networkSorted(networkList(value, maximum, networkId), id => id);
+
+const placementOf = (value: unknown): TServiceRuntimePlacement => {
+  const kind = variantOf(value, 'kind');
+  if (kind === 'every-node') {
+    networkRecord(value, ['kind']);
+    return { kind };
+  }
+  requireNetwork(kind === 'nodes');
+  const nodeIds = sortedIds(networkRecord(value, ['kind', 'nodeIds']).nodeIds, serviceRuntimeContract.maximumPinnedNodes);
+  requireNetwork(nodeIds.length > 0);
+  return { kind, nodeIds };
+};
+
+const runAsOf = (value: unknown): IServiceRuntimeProfile['runAs'] => {
+  if (value === null) return null;
+  const item = networkRecord(value, ['user', 'group']);
+  requireNetwork(isRuntimeIdentityNumber(item.user) && isRuntimeIdentityNumber(item.group));
+  return { user: item.user, group: item.group };
+};
+
+const profileOf = (value: unknown): IServiceRuntimeProfile => {
+  const item = networkRecord(value, ['cpuMillis', 'memoryBytes', 'readiness', 'logs', 'readonlyRootfs', 'runAs']);
+  requireNetwork(isRuntimeCpuMillis(item.cpuMillis) && isRuntimeMemoryBytes(item.memoryBytes)
+    && isRuntimeLogPolicy(item.logs) && typeof item.readonlyRootfs === 'boolean');
+  // The profile precedes the service's target ports; the runtime config refuses a target they do not declare.
+  assertRuntimeReadiness(item.readiness, () => true, failProducer);
+  const { maximumLineBytes, maximumBufferedBytes, retentionMs } = item.logs;
+  return { cpuMillis: item.cpuMillis, memoryBytes: item.memoryBytes,
+    readiness: JSON.parse(networkCanonical(item.readiness)) as TRuntimeConfigReadiness,
+    logs: { maximumLineBytes, maximumBufferedBytes, retentionMs }, readonlyRootfs: item.readonlyRootfs, runAs: runAsOf(item.runAs) };
+};
+
+const networkOf = (value: unknown): TServiceRuntimeNetwork => {
+  const mode = variantOf(value, 'mode');
+  if (mode === 'isolated') {
+    networkRecord(value, ['mode']);
+    return { mode };
+  }
+  requireNetwork(mode === 'attached');
+  const item = networkRecord(value, ['mode', 'publicEgress', 'platformEndpointIds']);
+  requireNetwork(typeof item.publicEgress === 'boolean');
+  return { mode, publicEgress: item.publicEgress,
+    platformEndpointIds: sortedIds(item.platformEndpointIds, serviceRuntimeContract.maximumPlatformEndpoints) };
+};
+
+/**
+ * Structural snapshot for exact persistence and for a spec write. Whether the cluster, the nodes and
+ * the platform endpoints exist, and whether the service declares the readiness target, is Cloudly's.
+ */
+export const snapshotServiceRuntimeSpec = (value: unknown): IServiceRuntimeSpec => producerSafe(() => {
+  const item = networkRecord(captureNetwork(value), ['id', 'organizationId', 'clusterId', 'placement',
+    'replicasPerNode', 'hold', 'profile', 'network', 'revision']);
+  requireNetwork(isBoundedInteger(item.replicasPerNode, 1, serviceRuntimeContract.maximumReplicasPerNode)
+    && typeof item.hold === 'boolean');
+  return { id: networkId(item.id), organizationId: networkId(item.organizationId), clusterId: networkId(item.clusterId),
+    placement: placementOf(item.placement), replicasPerNode: item.replicasPerNode, hold: item.hold,
+    profile: profileOf(item.profile), network: networkOf(item.network), revision: networkCounter(item.revision) };
+});
+
+/** Structural snapshot for exact persistence: a reason belongs to exactly one state. */
+export const snapshotServiceRuntimeStatus = (value: unknown): IServiceRuntimeStatus => producerSafe(() => {
+  const item = networkRecord(captureNetwork(value), ['id', 'specRevision', 'state', 'reason', 'changedAt']);
+  const base: IServiceRuntimeStatusBase = { id: networkId(item.id), specRevision: networkCounter(item.specRevision),
+    changedAt: networkCounter(item.changedAt) };
+  if (item.state === 'converged' || item.state === 'converging') {
+    requireNetwork(item.reason === null);
+    return { ...base, state: item.state, reason: null };
+  }
+  if (item.state === 'waiting') {
+    requireNetwork(isOneOf(serviceRuntimeWaitingReasons, item.reason));
+    return { ...base, state: item.state, reason: item.reason };
+  }
+  requireNetwork(item.state === 'refused' && isOneOf(serviceRuntimeRefusals, item.reason));
+  return { ...base, state: item.state, reason: item.reason };
+});

package/ts/data/sparknodereport.ts

@@ -1,6 +1,9 @@
+import { isReleaseVersion } from '../private/releaseversion.js';
+import { readExactDataRecord } from '../private/dataproperties.js';
+import { protocolRefusalHttpStatus, readProtocolOffer, type IProtocolOffer } from '../protocol.js';
+
 /** Host observations only. Container and workload readiness belong to Pallet. */
-export interface ISparkNodeReportV2 {
-  schemaVersion: 2;
+export interface ISparkNodeReport {
   observedAt: number;
   metrics: {
     cpuUsagePercent: number;
@@ -21,51 +24,55 @@ export interface ISparkNodeReportV2 {
 }
 
 /** HTTPS POST body. Never log, persist, or return nodeToken. */
-export interface ISparkNodeHeartbeatRequestV2 {
+export interface ISparkNodeHeartbeatRequest {
   nodeId: string;
   nodeToken: string;
-  report: ISparkNodeReportV2;
+  /** Read and negotiated before the node is authenticated; see `sparkNodeHeartbeatContract`. */
+  protocol: IProtocolOffer;
+  report: ISparkNodeReport;
 }
 
 /** Historical acceptance evidence, not current authority or workload readiness. */
-export interface ISparkNodeHeartbeatReceiptV2 {
-  schemaVersion: 2;
+export interface ISparkNodeHeartbeatReceipt {
   accepted: true;
   nodeId: string;
   credentialGeneration: number;
   sessionEpoch: number;
   acceptedAt: number;
+  /** The controller's offer, so an accepted node judges the session it just reported into. */
+  protocol: IProtocolOffer;
 }
 
 /** Persist only after the server's current Spark credential transaction commits. */
-export interface ISparkNodeReportRecordV2 {
-  report: ISparkNodeReportV2;
-  receipt: ISparkNodeHeartbeatReceiptV2;
+export interface ISparkNodeReportRecord {
+  report: ISparkNodeReport;
+  receipt: ISparkNodeHeartbeatReceipt;
 }
 
-export const sparkNodeHeartbeatV2Contract = Object.freeze({
-  endpoint: '/spark/v2/nodes/heartbeat',
+/**
+ * The node runtime's own heartbeat route.
+ *
+ * Judged in the one server order `protocol.readProtocolOffer` states, against this server's
+ * `sparkNode` offer and within `maxRequestBytes`. The route carries no typed error, so a refusal
+ * is answered with `protocolRefusalStatus` and an `IProtocolRefusal` body — before the report is
+ * snapshotted and before the node is authenticated, because a route that authenticated first would
+ * answer a peer of another major with a credential verdict it cannot act on.
+ */
+export const sparkNodeHeartbeatContract = Object.freeze({
+  endpoint: '/spark/nodes/heartbeat',
   maxRequestBytes: 8192,
   maxResponseBytes: 2048,
+  protocolRefusalStatus: protocolRefusalHttpStatus,
 } as const);
 
 const fail = (): never => { throw new Error('Spark node heartbeat contract rejected.'); };
 function requireValue(valueArg: unknown): asserts valueArg {
   if (!valueArg) fail();
 }
+/** Exactly these keys, carrying data: the shared reader refuses an accessor instead of running it. */
 const record = (valueArg: unknown, keysArg: readonly string[]): Record<string, unknown> => {
-  requireValue(valueArg !== null && typeof valueArg === 'object' && !Array.isArray(valueArg));
-  const prototype = Object.getPrototypeOf(valueArg);
-  requireValue(prototype === Object.prototype || prototype === null);
-  const keys = Reflect.ownKeys(valueArg);
-  requireValue(keys.length === keysArg.length);
-  const result: Record<string, unknown> = Object.create(null);
-  for (const key of keys) {
-    requireValue(typeof key === 'string' && keysArg.includes(key));
-    const descriptor = Object.getOwnPropertyDescriptor(valueArg, key);
-    requireValue(descriptor?.enumerable && Object.hasOwn(descriptor, 'value'));
-    result[key] = descriptor.value;
-  }
+  const result = readExactDataRecord(valueArg, keysArg);
+  requireValue(result !== null);
   return result;
 };
 const text = (valueArg: unknown, patternArg: RegExp, maxLengthArg: number): string => {
@@ -73,6 +80,11 @@ const text = (valueArg: unknown, patternArg: RegExp, maxLengthArg: number): stri
     && valueArg.match(patternArg)?.[0] === valueArg);
   return valueArg;
 };
+// The shared grammar, not a copy of it: a stored bundle version has to be one the release
+// comparison can order, and a second rule here would be a second answer to that question.
+const releaseVersion = (valueArg: unknown): string => (
+  isReleaseVersion(valueArg) ? valueArg : fail()
+);
 const number = (valueArg: unknown, maxArg = Number.MAX_SAFE_INTEGER): number => {
   requireValue(typeof valueArg === 'number' && Number.isFinite(valueArg)
     && !Object.is(valueArg, -0) && valueArg >= 0 && valueArg <= maxArg);
@@ -85,9 +97,8 @@ const integer = (valueArg: unknown, minimumArg: number): number => {
 };
 
 /** Exact inert JSON records; detaches and freezes before any consumer awaits. */
-export const snapshotSparkNodeReportV2 = (valueArg: unknown): ISparkNodeReportV2 => {
-  const value = record(valueArg, ['schemaVersion', 'observedAt', 'metrics', 'runtime']);
-  requireValue(value.schemaVersion === 2);
+export const snapshotSparkNodeReport = (valueArg: unknown): ISparkNodeReport => {
+  const value = record(valueArg, ['observedAt', 'metrics', 'runtime']);
   const metrics = record(value.metrics, ['cpuUsagePercent', 'memoryUsedMB', 'memoryAvailableMB',
     'diskUsedGB', 'diskAvailableGB']);
   const runtime = record(value.runtime, ['hostname', 'platform', 'arch', 'osRelease', 'bundle',
@@ -98,7 +109,6 @@ export const snapshotSparkNodeReportV2 = (valueArg: unknown): ISparkNodeReportV2
   requireValue(hostname.split('.').every((label) => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label)));
   const bundle = record(runtime.bundle, ['version', 'sourceCommit', 'manifestSha256']);
   return Object.freeze({
-    schemaVersion: 2,
     observedAt: integer(value.observedAt, 1),
     metrics: Object.freeze({
       cpuUsagePercent: number(metrics.cpuUsagePercent, 100),
@@ -109,7 +119,7 @@ export const snapshotSparkNodeReportV2 = (valueArg: unknown): ISparkNodeReportV2
       hostname, platform: 'linux', arch: runtime.arch as 'x86_64' | 'aarch64',
       osRelease: text(runtime.osRelease, /^[\x20-\x7e]+$/, 256),
       bundle: Object.freeze({
-        version: text(bundle.version, /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/, 64),
+        version: releaseVersion(bundle.version),
         sourceCommit: text(bundle.sourceCommit, /^[a-f0-9]{40}$/, 40),
         manifestSha256: text(bundle.manifestSha256, /^[a-f0-9]{64}$/, 64),
       }),
@@ -118,23 +128,25 @@ export const snapshotSparkNodeReportV2 = (valueArg: unknown): ISparkNodeReportV2
   });
 };
 
-export const snapshotSparkNodeHeartbeatRequestV2 = (valueArg: unknown): ISparkNodeHeartbeatRequestV2 => {
-  const value = record(valueArg, ['nodeId', 'nodeToken', 'report']);
+export const snapshotSparkNodeHeartbeatRequest = (valueArg: unknown): ISparkNodeHeartbeatRequest => {
+  const value = record(valueArg, ['nodeId', 'nodeToken', 'protocol', 'report']);
   return Object.freeze({
     nodeId: text(value.nodeId, /^[A-Za-z0-9_-]+$/, 128),
     // Both freshly enrolled and explicitly adopted credentials use this bearer format.
     nodeToken: text(value.nodeToken, /^secureToken[a-f0-9]{64}$/, 75),
-    report: snapshotSparkNodeReportV2(value.report),
+    protocol: readProtocolOffer(value),
+    report: snapshotSparkNodeReport(value.report),
   });
 };
 
-export const snapshotSparkNodeHeartbeatReceiptV2 = (valueArg: unknown): ISparkNodeHeartbeatReceiptV2 => {
-  const value = record(valueArg, ['schemaVersion', 'accepted', 'nodeId', 'credentialGeneration',
-    'sessionEpoch', 'acceptedAt']);
-  requireValue(value.schemaVersion === 2 && value.accepted === true);
+export const snapshotSparkNodeHeartbeatReceipt = (valueArg: unknown): ISparkNodeHeartbeatReceipt => {
+  const value = record(valueArg, ['accepted', 'nodeId', 'credentialGeneration',
+    'sessionEpoch', 'acceptedAt', 'protocol']);
+  requireValue(value.accepted === true);
   return Object.freeze({
-    schemaVersion: 2, accepted: true, nodeId: text(value.nodeId, /^[A-Za-z0-9_-]+$/, 128),
+    accepted: true, nodeId: text(value.nodeId, /^[A-Za-z0-9_-]+$/, 128),
     credentialGeneration: integer(value.credentialGeneration, 1),
     sessionEpoch: integer(value.sessionEpoch, 0), acceptedAt: integer(value.acceptedAt, 1),
+    protocol: readProtocolOffer(value),
   });
 };

package/ts/data/webpush.ts

@@ -101,7 +101,6 @@ export interface IWebPushBinding {
  * from their authenticated API after receiving this event.
  */
 export interface IWebPushNotificationPayload {
-  schemaVersion: 1;
   event: 'notificationAvailable';
   eventId: string;
   /** Same-origin application route beginning with a single slash. */

package/ts/index.ts

@@ -2,6 +2,7 @@ import * as data from './data/index.js';
 import * as appstore from './appstore/index.js';
 import * as platform from './platform/index.js';
 import * as platformservice from './platformservice/index.js';
+import * as protocol from './protocol.js';
 import * as requests from './requests/index.js';
 
 export {
@@ -9,5 +10,6 @@ export {
   data,
   platform,
   platformservice,
+  protocol,
   requests
 }

package/ts/platform/objectstorageretention.ts

@@ -1,19 +1,19 @@
 import { createCanonicalJsonSha256Hex } from '../private/canonicaljson.js';
 import { validatePlatformObjectStorageBucketName } from './objectstorage.js';
+import { hasExactKeys } from '../private/dataproperties.js';
 
 export const objectStorageRetentionLimits = Object.freeze({
   maximumPolicyIdLength: 96,
   maximumRetentionDurationSeconds: 100 * 366 * 24 * 60 * 60,
 });
 
-export interface IObjectStorageRetentionIntentV1 {
+export interface IObjectStorageRetentionIntent {
   mode: 'compliance';
   policyId: string;
   retentionDurationSeconds: number;
 }
 
-export interface IObjectStorageRetentionCapabilityEvidenceV1 {
-  version: 1;
+export interface IObjectStorageRetentionCapabilityEvidence {
   supported: true;
   backend: 'standalone' | 'clustered';
   modes: ['compliance'];
@@ -21,16 +21,15 @@ export interface IObjectStorageRetentionCapabilityEvidenceV1 {
   retainedMultipartSupported: false;
 }
 
-export interface IObjectStorageRetentionAuthorityV1 {
+export interface IObjectStorageRetentionAuthority {
   serviceId: string;
   bindingId: string;
   reconciliationGeneration: number;
   bindingRequestDigest: string;
 }
 
-export interface IObjectStorageRetentionSentinelEvidenceV1
-extends IObjectStorageRetentionIntentV1 {
-  version: 1;
+export interface IObjectStorageRetentionSentinelEvidence
+extends IObjectStorageRetentionIntent {
   createdAt: number;
   retainUntil: number;
   payloadSha256: string;
@@ -38,33 +37,32 @@ extends IObjectStorageRetentionIntentV1 {
   etag: string;
 }
 
-export interface IObjectStorageRetentionReceiptV1
-extends IObjectStorageRetentionIntentV1 {
+export interface IObjectStorageRetentionReceipt
+extends IObjectStorageRetentionIntent {
   bucketName: string;
   configuredAt: number;
   sentinelKey: string;
-  sentinel: IObjectStorageRetentionSentinelEvidenceV1;
+  sentinel: IObjectStorageRetentionSentinelEvidence;
 }
 
-export interface IObjectStorageRetentionEvidenceV1 {
-  intent: IObjectStorageRetentionIntentV1;
+export interface IObjectStorageRetentionEvidence {
+  intent: IObjectStorageRetentionIntent;
   intentSha256: string;
-  authority: IObjectStorageRetentionAuthorityV1;
-  capability: IObjectStorageRetentionCapabilityEvidenceV1;
-  receipt: IObjectStorageRetentionReceiptV1;
+  authority: IObjectStorageRetentionAuthority;
+  capability: IObjectStorageRetentionCapabilityEvidence;
+  receipt: IObjectStorageRetentionReceipt;
   verifiedAt: number;
 }
 
 /** Value-free desired intent with optional exact provider evidence. */
-export interface IObjectStorageRetentionBindingV1 {
-  schemaVersion: 1;
-  intent: IObjectStorageRetentionIntentV1;
-  evidence?: IObjectStorageRetentionEvidenceV1;
+export interface IObjectStorageRetentionBinding {
+  intent: IObjectStorageRetentionIntent;
+  evidence?: IObjectStorageRetentionEvidence;
 }
 
-export interface IObjectStorageRetentionEvidenceExpectationV1
-extends IObjectStorageRetentionAuthorityV1 {
-  intent: IObjectStorageRetentionIntentV1;
+export interface IObjectStorageRetentionEvidenceExpectation
+extends IObjectStorageRetentionAuthority {
+  intent: IObjectStorageRetentionIntent;
   bucketName: string;
 }
 
@@ -72,7 +70,7 @@ const policyIdPattern = /^[A-Za-z0-9._-]{1,96}$/;
 const identifierPattern = /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/;
 const sha256Pattern = /^[a-f0-9]{64}$/;
 const etagPattern = /^[a-f0-9]{32}$/;
-const sentinelKeyPattern = /^\.smartstorage-retention\/v1\/sentinel-[a-f0-9]{64}\.json$/;
+const sentinelKeyPattern = /^\.smartstorage-retention\/sentinel-[a-f0-9]{64}\.json$/;
 
 const isRecord = (valueArg: unknown): valueArg is Record<string, unknown> => (
   Boolean(valueArg)
@@ -82,16 +80,6 @@ const isRecord = (valueArg: unknown): valueArg is Record<string, unknown> => (
     || Object.getPrototypeOf(valueArg) === null)
 );
 
-const hasExactKeys = (
-  valueArg: Record<string, unknown>,
-  keysArg: readonly string[],
-): boolean => {
-  const actualKeys = Object.keys(valueArg).sort();
-  const expectedKeys = [...keysArg].sort();
-  return actualKeys.length === expectedKeys.length
-    && actualKeys.every((keyArg, indexArg) => keyArg === expectedKeys[indexArg]);
-};
-
 const isPositiveSafeInteger = (valueArg: unknown): valueArg is number => (
   Number.isSafeInteger(valueArg) && (valueArg as number) > 0
 );
@@ -135,7 +123,7 @@ export const createObjectStorageRetentionRetainUntil = (
 };
 
 export const createObjectStorageRetentionIntentDigestInput = (
-  intentArg: IObjectStorageRetentionIntentV1,
+  intentArg: IObjectStorageRetentionIntent,
 ): string => {
   const errors = validateObjectStorageRetentionIntent(intentArg);
   if (errors.length > 0) throw new Error(errors[0]);
@@ -146,12 +134,11 @@ export const createObjectStorageRetentionIntentDigestInput = (
       policyId: intentArg.policyId,
       retentionDurationSeconds: intentArg.retentionDurationSeconds,
     },
-    version: 1,
   });
 };
 
 export const computeObjectStorageRetentionIntentSha256 = async (
-  intentArg: IObjectStorageRetentionIntentV1,
+  intentArg: IObjectStorageRetentionIntent,
 ): Promise<string> => createCanonicalJsonSha256Hex(
   createObjectStorageRetentionIntentDigestInput(intentArg),
   (reasonArg) => { throw new Error(reasonArg); },
@@ -162,12 +149,12 @@ export const objectStorageRetentionIntentsEqual = (
   rightArg: unknown,
 ): boolean => validateObjectStorageRetentionIntent(leftArg).length === 0
   && validateObjectStorageRetentionIntent(rightArg).length === 0
-  && (leftArg as IObjectStorageRetentionIntentV1).mode
-    === (rightArg as IObjectStorageRetentionIntentV1).mode
-  && (leftArg as IObjectStorageRetentionIntentV1).policyId
-    === (rightArg as IObjectStorageRetentionIntentV1).policyId
-  && (leftArg as IObjectStorageRetentionIntentV1).retentionDurationSeconds
-    === (rightArg as IObjectStorageRetentionIntentV1).retentionDurationSeconds;
+  && (leftArg as IObjectStorageRetentionIntent).mode
+    === (rightArg as IObjectStorageRetentionIntent).mode
+  && (leftArg as IObjectStorageRetentionIntent).policyId
+    === (rightArg as IObjectStorageRetentionIntent).policyId
+  && (leftArg as IObjectStorageRetentionIntent).retentionDurationSeconds
+    === (rightArg as IObjectStorageRetentionIntent).retentionDurationSeconds;
 
 const retentionIntentFieldsEqual = (
   leftArg: unknown,
@@ -183,7 +170,7 @@ const retentionIntentFieldsEqual = (
 
 export const validateObjectStorageRetentionEvidence = async (
   evidenceArg: unknown,
-  expectedArg: IObjectStorageRetentionEvidenceExpectationV1,
+  expectedArg: IObjectStorageRetentionEvidenceExpectation,
 ): Promise<string[]> => {
   if (!isRecord(evidenceArg)
     || !hasExactKeys(evidenceArg, [
@@ -197,7 +184,7 @@ export const validateObjectStorageRetentionEvidence = async (
     return ['objectstorage retention evidence must use its exact schema'];
   }
   const errors = validateObjectStorageRetentionIntent(evidenceArg.intent);
-  const intent = evidenceArg.intent as IObjectStorageRetentionIntentV1;
+  const intent = evidenceArg.intent as IObjectStorageRetentionIntent;
   if (!retentionIntentFieldsEqual(intent, expectedArg.intent)) {
     errors.push('objectstorage retention evidence intent must equal the expected intent');
   }
@@ -233,14 +220,12 @@ export const validateObjectStorageRetentionEvidence = async (
   const capability = evidenceArg.capability;
   if (!isRecord(capability)
     || !hasExactKeys(capability, [
-      'version',
       'supported',
       'backend',
       'modes',
       'atomicCreateOnly',
       'retainedMultipartSupported',
     ])
-    || capability.version !== 1
     || capability.supported !== true
     || (capability.backend !== 'standalone' && capability.backend !== 'clustered')
     || !Array.isArray(capability.modes)
@@ -283,7 +268,6 @@ export const validateObjectStorageRetentionEvidence = async (
   const sentinel = receipt.sentinel;
   if (!isRecord(sentinel)
     || !hasExactKeys(sentinel, [
-      'version',
       'mode',
       'policyId',
       'retentionDurationSeconds',
@@ -296,7 +280,7 @@ export const validateObjectStorageRetentionEvidence = async (
     errors.push('objectstorage retention sentinel evidence must use its exact schema');
     return errors;
   }
-  if (sentinel.version !== 1 || !retentionIntentFieldsEqual(sentinel, intent)) {
+  if (!retentionIntentFieldsEqual(sentinel, intent)) {
     errors.push('objectstorage retention sentinel intent must equal its evidence intent');
   }
   if (!isPositiveSafeInteger(sentinel.createdAt)
@@ -331,17 +315,14 @@ export const validateObjectStorageRetentionEvidence = async (
 
 export const validateObjectStorageRetentionBinding = async (
   bindingArg: unknown,
-  expectedArg: IObjectStorageRetentionEvidenceExpectationV1,
+  expectedArg: IObjectStorageRetentionEvidenceExpectation,
 ): Promise<string[]> => {
   if (!isRecord(bindingArg)
-    || !Object.hasOwn(bindingArg, 'schemaVersion')
     || !Object.hasOwn(bindingArg, 'intent')
-    || Object.keys(bindingArg).some((keyArg) => !['schemaVersion', 'intent', 'evidence'].includes(keyArg))) {
+    || Object.keys(bindingArg).some((keyArg) => !['intent', 'evidence'].includes(keyArg))) {
     return ['objectstorage retention binding must use its exact schema'];
   }
-  const errors = bindingArg.schemaVersion === 1
-    ? validateObjectStorageRetentionIntent(bindingArg.intent)
-    : ['objectstorage retention binding schemaVersion must be 1'];
+  const errors = validateObjectStorageRetentionIntent(bindingArg.intent);
   if (!retentionIntentFieldsEqual(bindingArg.intent, expectedArg.intent)) {
     errors.push('objectstorage retention binding intent must equal the trusted expected intent');
   }
@@ -356,7 +337,7 @@ export const validateObjectStorageRetentionBinding = async (
 
 export const validatePlatformBindingObjectStorageRetention = async (
   bindingArg: unknown,
-  expectedArg: IObjectStorageRetentionEvidenceExpectationV1,
+  expectedArg: IObjectStorageRetentionEvidenceExpectation,
 ): Promise<string[]> => {
   if (!isRecord(bindingArg)) {
     return ['platform objectstorage retention binding must be an object'];

package/ts/platform/storage.ts

@@ -102,7 +102,6 @@ export type TStorageClassCapabilities =
  * addresses, mount options, principals, and credential values are private.
  */
 export interface IStorageCapabilityAdvertisement {
-  schemaVersion: 2;
   featureIds: string[];
   classes: TStorageClassCapabilities[];
 }
@@ -131,7 +130,7 @@ export interface IObjectStorageFileDelivery {
    * JSON object with endpoint, bucket, region, accessKeyId,
    * secretAccessKey, and optional sessionToken fields.
    */
-  format: 'servezone-object-storage-v1';
+  format: 'servezone-object-storage';
   uid: number;
   gid: number;
   mode: 0o400 | 0o440;
@@ -181,7 +180,6 @@ export interface IResolvedStorageCapacity {
 }
 
 export interface IResolvedStorageBindingBase {
-  schemaVersion: 2;
   /** Stable binding/allocation identity. */
   id: string;
   serviceId: string;