@serve.zone/interfaces 32.1.0 → 32.3.0

package/ts/data/clusternode.ts

@@ -6,7 +6,11 @@ import {
   canonicalizeStrictJson,
   createCanonicalJsonSha256Hex,
 } from '../private/canonicaljson.js';
-import { hasExactKeys } from '../private/dataproperties.js';
+import {
+  hasExactKeys,
+  readDataElements,
+  readDataProperties,
+} from '../private/dataproperties.js';
 
 export interface IClusterNodeMetrics {
   cpuUsagePercent: number;
@@ -610,6 +614,29 @@ export const validateSparkSwarmObservation = async (
   }
 };
 
+/**
+ * Which node is reporting, in the two members every Spark route body carries.
+ *
+ * All four routes authenticate the same reporter from the same pair, so the rule lives here: a
+ * copy per route is how one route ends up admitting a bearer another refuses.
+ */
+const validateSparkReporterIdentity = (
+  requestArg: Record<string, unknown>,
+  labelArg: string,
+): string[] => {
+  const errors: string[] = [];
+  if (!isRuntimeIdentifier(requestArg.nodeId)) {
+    errors.push(`${labelArg} nodeId must be canonical`);
+  }
+  if (typeof requestArg.nodeToken !== 'string'
+    || requestArg.nodeToken.length < 1
+    || requestArg.nodeToken.length > 512
+    || requestArg.nodeToken.trim() !== requestArg.nodeToken) {
+    errors.push(`${labelArg} nodeToken must be a bounded opaque token`);
+  }
+  return errors;
+};
+
 export const validateSparkSwarmObservationRequest = async (
   requestArg: unknown,
 ): Promise<string[]> => {
@@ -632,15 +659,10 @@ export const validateSparkSwarmObservationRequest = async (
       'Spark Swarm observation request protocol',
     );
     errors.push(...await validateSparkSwarmObservation(requestArg.observation));
-    if (!isRuntimeIdentifier(requestArg.nodeId)) {
-      errors.push('Spark Swarm observation request nodeId must be canonical');
-    }
-    if (typeof requestArg.nodeToken !== 'string'
-      || requestArg.nodeToken.length < 1
-      || requestArg.nodeToken.length > 512
-      || requestArg.nodeToken.trim() !== requestArg.nodeToken) {
-      errors.push('Spark Swarm observation request nodeToken must be a bounded opaque token');
-    }
+    errors.push(...validateSparkReporterIdentity(
+      requestArg,
+      'Spark Swarm observation request',
+    ));
     return errors;
   } catch {
     return ['Spark Swarm observation request must be safely inspectable'];
@@ -735,6 +757,431 @@ export const validateSparkSwarmObservationResponse = async (
   }
 };
 
+/** A runtime description or a service name: bounded, and free of bytes JSON text cannot carry. */
+const maximumSparkRuntimeTextLength = 512;
+/** An operator-facing message, which may hold line breaks but is still bounded. */
+const maximumSparkMessageTextLength = 2048;
+/** `sparkSwarmNodeContracts.actionResult` states what a server keeps of an action's output. */
+const maximumSparkActionResultTextLength = 4000;
+/**
+ * The route's own byte bound refuses an oversized runtime description first; this stops an
+ * in-process caller from making the validator walk a list no route could have delivered.
+ */
+const maximumSparkRuntimeServices = 64;
+
+const sparkCloudlyConnectionStatuses = new Set<TSparkCloudlyConnectionStatus>([
+  'not-configured',
+  'connecting',
+  'connected',
+  'failed',
+]);
+const sparkNodeModes = new Set<TSparkNodeMode>(['cloudly', 'coreflow-node']);
+const sparkActionResultStatuses = new Set<TNodeActionStatus>([
+  'running',
+  'succeeded',
+  'failed',
+]);
+
+const isBoundedText = (
+  valueArg: unknown,
+  maximumLengthArg = maximumSparkRuntimeTextLength,
+): valueArg is string => (
+  typeof valueArg === 'string'
+  && valueArg.length > 0
+  && valueArg.length <= maximumLengthArg
+  && !/[\u0000-\u001f\u007f]/u.test(valueArg)
+);
+
+/** Message text a node reports: line breaks and tabs are its content, other control bytes are not. */
+const isBoundedMessageText = (
+  valueArg: unknown,
+  maximumLengthArg: number,
+): valueArg is string => (
+  typeof valueArg === 'string'
+  && valueArg.length <= maximumLengthArg
+  && !/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/u.test(valueArg)
+);
+
+const isNonNegativeNumber = (
+  valueArg: unknown,
+  maximumArg = Number.MAX_SAFE_INTEGER,
+): valueArg is number => (
+  typeof valueArg === 'number'
+  && Number.isFinite(valueArg)
+  && !Object.is(valueArg, -0)
+  && valueArg >= 0
+  && valueArg <= maximumArg
+);
+
+const isNonNegativeSafeInteger = (valueArg: unknown): valueArg is number => (
+  Number.isSafeInteger(valueArg) && !Object.is(valueArg, -0) && (valueArg as number) >= 0
+);
+
+/** A record a Spark body states, detached from the caller's object, or `null` with the reason. */
+interface ISparkRecordReading {
+  record: Record<string, unknown> | null;
+  errors: string[];
+}
+
+/**
+ * One level of a Spark body: own enumerable data properties only, then the exact key set.
+ *
+ * The heartbeat, metrics-sample and action-result bodies are judged member by member rather than
+ * as canonical bytes, because only the observation is digested and those three legitimately carry
+ * fractional CPU, memory and rate observations that the digest's integer encoding would refuse.
+ * What the canonical reader also gave — a body that cannot run code or answer differently on a
+ * second read — is kept here by copying the data properties away from the caller's object before
+ * any member is judged.
+ */
+const readSparkRecord = (
+  valueArg: unknown,
+  labelArg: string,
+  requiredKeysArg: readonly string[],
+  optionalKeysArg: readonly string[] = [],
+): ISparkRecordReading => {
+  const record = readDataProperties(valueArg);
+  if (record === null) {
+    return { record: null, errors: [`${labelArg} must contain plain JSON data properties`] };
+  }
+  if (!hasExactKeys(record, requiredKeysArg, optionalKeysArg)) {
+    return { record: null, errors: [`${labelArg} must use its exact schema`] };
+  }
+  return { record, errors: [] };
+};
+
+/**
+ * The envelope a Spark route body states before its payload: the exact key set, the reporter's
+ * protocol offer read by name, and the reporter's identity — in that order, because a server
+ * answers an unreadable offer before it looks at anything the body claims about a node.
+ */
+const readSparkRouteEnvelope = (
+  requestArg: unknown,
+  labelArg: string,
+  requiredKeysArg: readonly string[],
+  optionalKeysArg: readonly string[] = [],
+): ISparkRecordReading => {
+  const reading = readSparkRecord(requestArg, labelArg, requiredKeysArg, optionalKeysArg);
+  if (reading.record === null) {
+    return reading;
+  }
+  return {
+    record: reading.record,
+    errors: [
+      ...validateProtocolOfferOn(reading.record, `${labelArg} protocol`),
+      ...validateSparkReporterIdentity(reading.record, labelArg),
+    ],
+  };
+};
+
+/**
+ * One reason per member, collected rather than thrown.
+ *
+ * A Spark route answers a refusal before the node is authenticated, so the reporter only ever
+ * learns which member of its own body was wrong; naming that member is what lets an operator fix
+ * a node without reading the server's source.
+ */
+const createSparkFieldErrors = (
+  recordArg: Record<string, unknown>,
+  labelArg: string,
+) => {
+  const errors: string[] = [];
+  return {
+    errors,
+    number: (keyArg: string, maximumArg?: number): void => {
+      if (!isNonNegativeNumber(recordArg[keyArg], maximumArg)) {
+        errors.push(`${labelArg} ${keyArg} must be a bounded non-negative number`);
+      }
+    },
+    percentage: (keyArg: string): void => {
+      if (!isNonNegativeNumber(recordArg[keyArg], 100)) {
+        errors.push(`${labelArg} ${keyArg} must be a percentage between 0 and 100`);
+      }
+    },
+    count: (keyArg: string): void => {
+      if (!isNonNegativeSafeInteger(recordArg[keyArg])) {
+        errors.push(`${labelArg} ${keyArg} must be a non-negative safe integer`);
+      }
+    },
+    instant: (keyArg: string): void => {
+      if (!isPositiveSafeInteger(recordArg[keyArg])) {
+        errors.push(`${labelArg} ${keyArg} must be a positive safe integer timestamp`);
+      }
+    },
+    text: (keyArg: string): void => {
+      if (!isBoundedText(recordArg[keyArg])) {
+        errors.push(`${labelArg} ${keyArg} must be bounded non-empty text`);
+      }
+    },
+    messageText: (keyArg: string, maximumLengthArg: number): void => {
+      if (!isBoundedMessageText(recordArg[keyArg], maximumLengthArg)) {
+        errors.push(`${labelArg} ${keyArg} must be bounded message text`);
+      }
+    },
+    identifier: (keyArg: string): void => {
+      if (!isRuntimeIdentifier(recordArg[keyArg])) {
+        errors.push(`${labelArg} ${keyArg} must be canonical`);
+      }
+    },
+    boolean: (keyArg: string): void => {
+      if (typeof recordArg[keyArg] !== 'boolean') {
+        errors.push(`${labelArg} ${keyArg} must be a boolean`);
+      }
+    },
+    member: <TMember extends string>(keyArg: string, allowedArg: ReadonlySet<TMember>): void => {
+      if (!allowedArg.has(recordArg[keyArg] as TMember)) {
+        errors.push(`${labelArg} ${keyArg} is outside the supported values`);
+      }
+    },
+    /** Runs `checkArg` only when the optional member is present at all. */
+    optional: (keyArg: string, checkArg: (keyArg: string) => void): void => {
+      if (recordArg[keyArg] !== undefined) {
+        checkArg(keyArg);
+      }
+    },
+  };
+};
+
+const validateSparkNodeMetrics = (valueArg: unknown, labelArg: string): string[] => {
+  const reading = readSparkRecord(valueArg, labelArg, [
+    'cpuUsagePercent',
+    'memoryUsedMB',
+    'memoryAvailableMB',
+    'diskUsedGB',
+    'diskAvailableGB',
+    'containerCount',
+    'timestamp',
+  ]);
+  if (reading.record === null) {
+    return reading.errors;
+  }
+  const field = createSparkFieldErrors(reading.record, labelArg);
+  field.percentage('cpuUsagePercent');
+  field.number('memoryUsedMB');
+  field.number('memoryAvailableMB');
+  field.number('diskUsedGB');
+  field.number('diskAvailableGB');
+  field.count('containerCount');
+  field.instant('timestamp');
+  return field.errors;
+};
+
+const validateNodeMetricsSample = (valueArg: unknown, labelArg: string): string[] => {
+  const reading = readSparkRecord(
+    valueArg,
+    labelArg,
+    ['timestamp', 'cpuUsagePercent', 'memoryUsedMB', 'memoryAvailableMB'],
+    ['networkRxBytesPerSec', 'networkTxBytesPerSec'],
+  );
+  if (reading.record === null) {
+    return reading.errors;
+  }
+  const field = createSparkFieldErrors(reading.record, labelArg);
+  field.instant('timestamp');
+  field.percentage('cpuUsagePercent');
+  field.number('memoryUsedMB');
+  field.number('memoryAvailableMB');
+  field.optional('networkRxBytesPerSec', field.number);
+  field.optional('networkTxBytesPerSec', field.number);
+  return field.errors;
+};
+
+const validateServeZoneServiceRuntimeInfo = (
+  valueArg: unknown,
+  labelArg: string,
+): string[] => {
+  const reading = readSparkRecord(
+    valueArg,
+    labelArg,
+    ['name', 'running', 'checkedAt'],
+    [
+      'serviceId',
+      'image',
+      'desiredImage',
+      'imageVersion',
+      'runningImageId',
+      'runningTaskCount',
+      'updatedAt',
+      'error',
+    ],
+  );
+  if (reading.record === null) {
+    return reading.errors;
+  }
+  const field = createSparkFieldErrors(reading.record, labelArg);
+  field.text('name');
+  field.boolean('running');
+  field.instant('checkedAt');
+  field.optional('serviceId', field.text);
+  field.optional('image', field.text);
+  field.optional('desiredImage', field.text);
+  field.optional('imageVersion', field.text);
+  field.optional('runningImageId', field.text);
+  field.optional('runningTaskCount', field.count);
+  field.optional('updatedAt', field.instant);
+  field.optional('error', (keyArg) => field.messageText(keyArg, maximumSparkMessageTextLength));
+  return field.errors;
+};
+
+const validateSparkNodeRuntimeInfo = (valueArg: unknown, labelArg: string): string[] => {
+  const reading = readSparkRecord(
+    valueArg,
+    labelArg,
+    [
+      'runtime',
+      'nodeId',
+      'platform',
+      'arch',
+      'sparkVersion',
+      'cloudlyConnectionStatus',
+      'dockerAvailable',
+      'checkedAt',
+    ],
+    [
+      'mode',
+      'hostname',
+      'osRelease',
+      'cloudlyUrl',
+      'swarmNodeId',
+      'serveZoneServices',
+      'lastError',
+    ],
+  );
+  if (reading.record === null) {
+    return reading.errors;
+  }
+  const runtimeInfo = reading.record;
+  const field = createSparkFieldErrors(runtimeInfo, labelArg);
+  if (runtimeInfo.runtime !== 'spark') {
+    field.errors.push(`${labelArg} runtime must be spark`);
+  }
+  field.identifier('nodeId');
+  field.text('platform');
+  field.text('arch');
+  field.text('sparkVersion');
+  field.member('cloudlyConnectionStatus', sparkCloudlyConnectionStatuses);
+  field.boolean('dockerAvailable');
+  field.instant('checkedAt');
+  field.optional('mode', (keyArg) => field.member(keyArg, sparkNodeModes));
+  field.optional('hostname', field.text);
+  field.optional('osRelease', field.text);
+  field.optional('cloudlyUrl', field.text);
+  field.optional('swarmNodeId', field.identifier);
+  field.optional('lastError', (keyArg) => field.messageText(keyArg, maximumSparkMessageTextLength));
+  if (runtimeInfo.serveZoneServices !== undefined) {
+    const services = readDataElements(runtimeInfo.serveZoneServices, maximumSparkRuntimeServices);
+    if (services === null) {
+      field.errors.push(
+        `${labelArg} serveZoneServices must be a bounded list of at most `
+        + `${maximumSparkRuntimeServices} described services`,
+      );
+    } else {
+      services.forEach((serviceArg, indexArg) => {
+        field.errors.push(...validateServeZoneServiceRuntimeInfo(
+          serviceArg,
+          `${labelArg} serveZoneServices[${indexArg}]`,
+        ));
+      });
+    }
+  }
+  return field.errors;
+};
+
+/**
+ * Spark -> Cloudly body for `sparkSwarmNodeContracts.heartbeat.endpoint`.
+ *
+ * Stated here beside the shape it judges, so the server that reads the beat and the node that
+ * writes it apply one set of acceptance rules; a reader that kept its own member checks would
+ * decide on its own which beats exist.
+ *
+ * Every Spark route validator answers the same way — one string per refused member, empty for an
+ * admissible body, and the same `(body) => Promise<string[]>` signature, so a server can hold the
+ * four routes in one table.
+ */
+export const validateSparkSwarmNodeHeartbeatRequest = async (
+  requestArg: unknown,
+): Promise<string[]> => {
+  const label = 'Spark Swarm node heartbeat request';
+  try {
+    const envelope = readSparkRouteEnvelope(
+      requestArg,
+      label,
+      ['nodeId', 'nodeToken', 'protocol', 'metrics', 'runtimeInfo'],
+    );
+    if (envelope.record === null) {
+      return envelope.errors;
+    }
+    envelope.errors.push(...validateSparkNodeMetrics(
+      envelope.record.metrics,
+      `${label} metrics`,
+    ));
+    envelope.errors.push(...validateSparkNodeRuntimeInfo(
+      envelope.record.runtimeInfo,
+      `${label} runtimeInfo`,
+    ));
+    return envelope.errors;
+  } catch {
+    return [`${label} must be safely inspectable`];
+  }
+};
+
+/** Spark -> Cloudly body for `sparkSwarmNodeContracts.metricsSample.endpoint`. */
+export const validateSparkMetricsSampleRequest = async (
+  requestArg: unknown,
+): Promise<string[]> => {
+  const label = 'Spark metrics sample request';
+  try {
+    const envelope = readSparkRouteEnvelope(
+      requestArg,
+      label,
+      ['nodeId', 'nodeToken', 'protocol', 'sample'],
+    );
+    if (envelope.record === null) {
+      return envelope.errors;
+    }
+    envelope.errors.push(...validateNodeMetricsSample(
+      envelope.record.sample,
+      `${label} sample`,
+    ));
+    return envelope.errors;
+  } catch {
+    return [`${label} must be safely inspectable`];
+  }
+};
+
+/**
+ * Spark -> Cloudly body for `sparkSwarmNodeContracts.actionResult.endpoint`.
+ *
+ * `pending` is the one status a node never reports: an action it has not started has no result to
+ * post, and a server that accepted one would reopen an action it already handed out.
+ */
+export const validateSparkActionResultRequest = async (
+  requestArg: unknown,
+): Promise<string[]> => {
+  const label = 'Spark action result request';
+  try {
+    const envelope = readSparkRouteEnvelope(
+      requestArg,
+      label,
+      ['nodeId', 'nodeToken', 'protocol', 'actionId', 'status'],
+      ['resultText'],
+    );
+    if (envelope.record === null) {
+      return envelope.errors;
+    }
+    const field = createSparkFieldErrors(envelope.record, label);
+    field.identifier('actionId');
+    field.member('status', sparkActionResultStatuses);
+    field.optional('resultText', (keyArg) => field.messageText(
+      keyArg,
+      maximumSparkActionResultTextLength,
+    ));
+    envelope.errors.push(...field.errors);
+    return envelope.errors;
+  } catch {
+    return [`${label} must be safely inspectable`];
+  }
+};
+
 /**
  * The exact five members of a target that the set digest is taken over.
  *

package/ts/platform/storage.golden.ts

@@ -0,0 +1,97 @@
+import type {
+  IAppStoreFilesystemStorageRequest,
+  IAppStoreObjectStorageRequest,
+} from '../appstore/types.js';
+import { deepFreezeValue } from '../private/canonicaljson.js';
+
+export interface IStorageRequestCanonicalDigestGoldenVector<TInput> {
+  input: TInput;
+  canonicalJson: string;
+  sha256: string;
+}
+
+const filesystemRequest: IAppStoreFilesystemStorageRequest = {
+  id: 'app-state',
+  kind: 'filesystem',
+  storageClass: 'databaseFast',
+  accessMode: 'ReadWriteOnce',
+  reclaimPolicy: 'delete',
+  mountPath: '/var/lib/app',
+  capacity: {
+    request: '20GiB',
+    limit: '40GiB',
+  },
+  protection: {
+    backup: 'required',
+    snapshots: 'portable',
+    consistency: 'applicationConsistent',
+  },
+};
+
+const objectStorageLauncherEnvironmentRequest: IAppStoreObjectStorageRequest = {
+  id: 'object-data',
+  kind: 'objectStorage',
+  storageClass: 'backupCapacity',
+  accessMode: 'readWrite',
+  reclaimPolicy: 'retain',
+  delivery: {
+    type: 'launcher-environment',
+    keys: {
+      endpoint: 'APP_S3_ENDPOINT',
+      bucket: 'APP_S3_BUCKET',
+      region: 'APP_S3_REGION',
+      accessKeyId: 'APP_S3_ACCESS_KEY',
+      secretAccessKey: 'APP_S3_SECRET_KEY',
+    },
+  },
+  capacity: {
+    request: '500GiB',
+  },
+  protection: {
+    backup: 'required',
+    versioning: 'required',
+    retentionDays: 30,
+  },
+};
+
+const objectStorageFileRequest: IAppStoreObjectStorageRequest = {
+  id: 'object-archive',
+  kind: 'objectStorage',
+  storageClass: 'archiveCapacity',
+  accessMode: 'readOnly',
+  reclaimPolicy: 'delete',
+  delivery: {
+    type: 'file',
+    targetPath: '/run/secrets/object-archive.json',
+    format: 'servezone-object-storage',
+    uid: 10_000,
+    gid: 10_000,
+    mode: 0o400,
+  },
+};
+
+/**
+ * The storage request digest, written down for both kinds and both deliveries.
+ *
+ * A control plane and its consumer compare this value, so it is stated here as bytes rather than
+ * as whatever the current normalizer happens to produce: a member that starts or stops
+ * participating, an optional member that starts being carried when it is absent, or a delivery
+ * mode written as anything but its number would move these digests and be caught here.
+ */
+export const storageRequestCanonicalDigestGoldenVectors = deepFreezeValue({
+  filesystem: {
+    input: filesystemRequest,
+    canonicalJson: '{"accessMode":"ReadWriteOnce","capacity":{"limit":"40GiB","request":"20GiB"},"id":"app-state","kind":"filesystem","mountPath":"/var/lib/app","protection":{"backup":"required","consistency":"applicationConsistent","snapshots":"portable"},"reclaimPolicy":"delete","storageClass":"databaseFast"}',
+    sha256: '0f8dc2e480ade7110be1f1d95f666cc56d5b90110d1c4a1b8b8383e2eeda6fae',
+  },
+  objectStorageLauncherEnvironment: {
+    input: objectStorageLauncherEnvironmentRequest,
+    canonicalJson: '{"accessMode":"readWrite","capacity":{"request":"500GiB"},"delivery":{"keys":{"accessKeyId":"APP_S3_ACCESS_KEY","bucket":"APP_S3_BUCKET","endpoint":"APP_S3_ENDPOINT","region":"APP_S3_REGION","secretAccessKey":"APP_S3_SECRET_KEY"},"type":"launcher-environment"},"id":"object-data","kind":"objectStorage","protection":{"backup":"required","retentionDays":30,"versioning":"required"},"reclaimPolicy":"retain","storageClass":"backupCapacity"}',
+    sha256: '88bd943800bea75b576612b966484e66ddbf7ec9529a7f29dd1eadc9a36e2b79',
+  },
+  objectStorageFile: {
+    input: objectStorageFileRequest,
+    canonicalJson: '{"accessMode":"readOnly","delivery":{"format":"servezone-object-storage","gid":10000,"mode":256,"targetPath":"/run/secrets/object-archive.json","type":"file","uid":10000},"id":"object-archive","kind":"objectStorage","reclaimPolicy":"delete","storageClass":"archiveCapacity"}',
+    sha256: '13186abbfe733b3917363e0694d367f2d6aa87a4064445532d7c857ee274f795',
+  },
+});

package/ts/platform/storage.ts

@@ -1,4 +1,10 @@
+import type { TAppStoreStorageRequest } from '../appstore/types.js';
 import type { TSecretManagementScope } from '../data/secret.js';
+import {
+  canonicalizeStrictJson,
+  createCanonicalJsonSha256Hex,
+} from '../private/canonicaljson.js';
+import { createStorageContractReaders } from '../private/storagecontract.js';
 
 /**
  * Backend-neutral storage vocabulary shared by App Store manifests, control
@@ -186,8 +192,12 @@ export interface IResolvedStorageBindingBase {
   /** Stable App Store storageRequests[].id. */
   requestId: string;
   /**
-   * Canonical digest of the normalized request. Adapters use it to distinguish
-   * an idempotent reconciliation from a migration.
+   * Canonical digest of the normalized request, exactly as
+   * `createStorageRequestSha256` states it: bare lowercase hex over the request
+   * alone. Adapters use it to distinguish an idempotent reconciliation from a
+   * migration, and a consumer re-derives it to recognise the request it asked
+   * for, so the control plane and the consumer call that one function rather
+   * than each deriving a value the other cannot reproduce.
    */
   requestDigest: string;
   kind: TStorageResourceKind;
@@ -232,3 +242,72 @@ extends IResolvedStorageBindingBase {
 export type TResolvedStorageBinding =
   | IResolvedFilesystemStorageBinding
   | IResolvedObjectStorageBinding;
+
+export class StorageContractError extends Error {
+  public constructor(reasonArg: string) {
+    super(`storage contract error: ${reasonArg}`);
+    this.name = 'StorageContractError';
+  }
+}
+
+const fail = (reasonArg: string): never => {
+  throw new StorageContractError(reasonArg);
+};
+
+const { normalizeStorageRequest: readStorageRequest } =
+  createStorageContractReaders(fail);
+
+/**
+ * The one judgement of what a storage request is: the request read against its exact schema and
+ * returned in its contract shape — required members present, optional members carried only when
+ * the request declares them, and every value within the bounds an adapter can fulfil.
+ *
+ * A control plane that admits requests, a fulfillment adapter that provisions them, and an App
+ * Store front end that assembles them all have to agree on the same acceptance rules; a second
+ * copy of them anywhere is a second answer to which requests exist, and the digest one side issues
+ * would name a request the other never accepted. `canonicalizeStorageRequest` and
+ * `createStorageRequestSha256` are derived from this function rather than the other way round, so
+ * a consumer that needs the judged request itself does not have to re-parse its own canonical
+ * bytes.
+ *
+ * The returned request is a fresh value; the input is never read again after normalization and
+ * never mutated. Anything that is not a storage request is refused with `StorageContractError`,
+ * whose message names the failing field so a consumer can map it to its own status vocabulary.
+ */
+export const normalizeStorageRequest = (
+  valueArg: unknown,
+): TAppStoreStorageRequest => {
+  return readStorageRequest(valueArg, 'storage request');
+};
+
+/**
+ * The exact bytes a storage request's digest is taken over: the request normalized to its contract
+ * shape, written as strict canonical JSON — keys in UTF-16 code-unit order, no whitespace, no
+ * absent member carried as `null`.
+ *
+ * Anything that is not a storage request is refused rather than hashed, because a digest of an
+ * unjudged body would name a request no adapter could fulfil.
+ */
+export const canonicalizeStorageRequest = (valueArg: unknown): string => {
+  return canonicalizeStrictJson(normalizeStorageRequest(valueArg), fail);
+};
+
+/**
+ * The storage request digest: bare lowercase hex SHA-256 over the canonical request, with no
+ * prefix and nothing but the request in the hashed value.
+ *
+ * A control plane issues this value on a binding and a consumer re-derives it from the request it
+ * declared; the two only agree because they call this one function. A second derivation elsewhere
+ * — a prefix, or a wrapper object around the request — is a different value for the same binding,
+ * and the consumer would keep rejecting a binding that is in fact its own.
+ */
+export const createStorageRequestSha256 = async (
+  valueArg: unknown,
+): Promise<string> => {
+  return createCanonicalJsonSha256Hex(canonicalizeStorageRequest(valueArg), fail);
+};
+
+export {
+  storageRequestCanonicalDigestGoldenVectors,
+  type IStorageRequestCanonicalDigestGoldenVector,
+} from './storage.golden.js';