@serve.zone/interfaces 31.8.0 → 32.0.0

package/ts/private/producercontract.ts

@@ -0,0 +1,19 @@
+import { requireNetwork } from './networkcontract.js';
+
+/**
+ * The runtime producer records read decoded input with the network family's strict JSON readers,
+ * and every producer snapshot runs inside `producerSafe`: whichever rule refused, a caller sees
+ * this one rejection and learns nothing about which field failed.
+ */
+export const failProducer = (): never => { throw new Error('Runtime producer contract rejected.'); };
+export const producerSafe = <T>(operation: () => T): T => { try { return operation(); } catch { return failProducer(); } };
+
+/** Membership in a closed union whose members are listed once, as the array the union is derived from. */
+export const isOneOf = <T extends string>(members: readonly T[], value: unknown): value is T =>
+  (members as readonly unknown[]).includes(value);
+
+/** The tag of a captured tagged record, read before the record's exact keys are known. */
+export const variantOf = (value: unknown, tag: string): unknown => {
+  requireNetwork(value !== null && typeof value === 'object' && !Array.isArray(value));
+  return (value as Record<string, unknown>)[tag];
+};

package/ts/private/releaseversion.ts

@@ -0,0 +1,70 @@
+/**
+ * The release-version grammar every serve.zone package agrees on.
+ *
+ * Exactly what a published release is named and nothing else: no prerelease, because gitzone
+ * refuses to publish one, and no build metadata, because two strings that name one release would
+ * then compare unequal. Components are read as numbers, which is the whole reason this rule
+ * exists — `32.10.0` is above `32.9.0`, and a lexical comparison of the strings says the opposite.
+ */
+export interface IReleaseVersion {
+  major: number;
+  minor: number;
+  patch: number;
+}
+
+/** Canonical decimal components: no leading zeros, no prefix, no suffix. */
+const releaseVersionPattern = /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/;
+
+/**
+ * Bounds the string before anything parses it.
+ *
+ * Every component of a real release fits many times over, so the only values this refuses are
+ * digit runs that no release could carry and that a reader would otherwise have to count.
+ */
+export const maximumReleaseVersionLength = 32;
+
+/**
+ * The three components of one release version, or `null` for everything that is not one.
+ *
+ * A component beyond the safe-integer range is refused rather than rounded: two such versions
+ * would compare equal after rounding, and an ordering that cannot tell two releases apart is
+ * worse than no answer.
+ */
+export const parseReleaseVersion = (valueArg: unknown): IReleaseVersion | null => {
+  if (typeof valueArg !== 'string' || valueArg.length > maximumReleaseVersionLength) {
+    return null;
+  }
+  const components = releaseVersionPattern.exec(valueArg);
+  if (components === null) {
+    return null;
+  }
+  const [major, minor, patch] = components.slice(1).map(Number);
+  if (!Number.isSafeInteger(major) || !Number.isSafeInteger(minor) || !Number.isSafeInteger(patch)) {
+    return null;
+  }
+  return { major, minor, patch };
+};
+
+/**
+ * Whether a value names one published release.
+ *
+ * Every rule of the grammar goes through `parseReleaseVersion`, including the numeric one, so a
+ * validator that accepts a version cannot accept one the comparison then refuses to order.
+ */
+export const isReleaseVersion = (valueArg: unknown): valueArg is string => (
+  parseReleaseVersion(valueArg) !== null
+);
+
+/** Negative, zero or positive as the left version is below, equal to or above the right one. */
+export const compareReleaseVersions = (
+  leftArg: IReleaseVersion,
+  rightArg: IReleaseVersion,
+): number => {
+  if (leftArg.major !== rightArg.major) {
+    return leftArg.major - rightArg.major;
+  }
+  if (leftArg.minor !== rightArg.minor) {
+    return leftArg.minor - rightArg.minor;
+  }
+  return leftArg.patch - rightArg.patch;
+};

package/ts/private/runtimepolicy.ts

@@ -0,0 +1,105 @@
+import type { IRuntimeConfigLogPolicy } from '../data/runtimeconfig.js';
+
+/**
+ * The execution policy a runtime config seals and a service runtime profile states ahead of it.
+ * Both validators apply these timing, HTTP request, CPU, memory, identity and log rules. Only the
+ * service's target ports decide whether a readiness target exists, which a profile cannot know.
+ *
+ * Every check here reads captured plain data only, the output of `snapshotBoundedJson` or
+ * `captureNetwork`: on live input a getter could pass a check and then hand the caller another value.
+ */
+export const runtimePolicyLimits = Object.freeze({
+  minimumMemoryBytes: 16 * 1024 * 1024,
+  maximumMemoryBytes: 2 ** 50,
+  maximumCpuMillis: 1_000_000,
+  maximumIdentityNumber: 2 ** 31 - 1,
+  maximumReadinessDurationMs: 3_600_000,
+  maximumLogRetentionMs: 31_536_000_000,
+} as const);
+
+export type TRuntimePolicyFailure = (messageArg: string) => never;
+
+export const isBoundedInteger = (valueArg: unknown, minimumArg: number, maximumArg: number): valueArg is number =>
+  typeof valueArg === 'number' && Number.isSafeInteger(valueArg) && !Object.is(valueArg, -0)
+  && valueArg >= minimumArg && valueArg <= maximumArg;
+export const isRuntimePortName = (valueArg: unknown): valueArg is string =>
+  typeof valueArg === 'string' && /^[a-z0-9][a-z0-9_.-]{0,62}$/.test(valueArg);
+export const isExactRecord = (
+  valueArg: unknown, keysArg: readonly string[],
+): valueArg is Record<string, unknown> => {
+  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) return false;
+  const keys = Object.keys(valueArg);
+  return keys.length === keysArg.length && keys.every((keyArg) => keysArg.includes(keyArg));
+};
+
+/** null explicitly requests no CPU quota; zero is never a quota. */
+export const isRuntimeCpuMillis = (valueArg: unknown): valueArg is number | null =>
+  valueArg === null || isBoundedInteger(valueArg, 1, runtimePolicyLimits.maximumCpuMillis);
+export const isRuntimeMemoryBytes = (valueArg: unknown): valueArg is number =>
+  isBoundedInteger(valueArg, runtimePolicyLimits.minimumMemoryBytes, runtimePolicyLimits.maximumMemoryBytes);
+export const isRuntimeIdentityNumber = (valueArg: unknown): valueArg is number =>
+  isBoundedInteger(valueArg, 0, runtimePolicyLimits.maximumIdentityNumber);
+
+export const isRuntimeLogPolicy = (valueArg: unknown): valueArg is IRuntimeConfigLogPolicy =>
+  isExactRecord(valueArg, ['maximumLineBytes', 'maximumBufferedBytes', 'retentionMs'])
+  && isBoundedInteger(valueArg.maximumLineBytes, 1, 1_048_576)
+  && isBoundedInteger(valueArg.maximumBufferedBytes, 1, 67_108_864)
+  && valueArg.maximumBufferedBytes >= valueArg.maximumLineBytes
+  && isBoundedInteger(valueArg.retentionMs, 1, runtimePolicyLimits.maximumLogRetentionMs);
+
+const timingKeys = ['initialDelayMs', 'startupGraceMs', 'intervalMs', 'timeoutMs',
+  'successThreshold', 'failureThreshold'] as const;
+
+/**
+ * Readiness policy. `selectsTcpTargetArg` decides whether a probe's named target and port exist:
+ * a config answers from its own target ports, a profile ahead of any config cannot know them.
+ */
+export const assertRuntimeReadiness = (
+  valueArg: unknown,
+  selectsTcpTargetArg: (targetPortArg: string, portArg: number) => boolean,
+  failArg: TRuntimePolicyFailure,
+): void => {
+  if (!valueArg || typeof valueArg !== 'object') failArg('runtime config readiness is required');
+  const value = valueArg as Record<string, unknown>;
+  const keys = value.kind === 'process' ? ['kind', ...timingKeys]
+    : value.kind === 'tcp' ? ['kind', ...timingKeys, 'targetPort', 'port']
+      : value.kind === 'http' ? ['kind', ...timingKeys, 'targetPort', 'port',
+        'scheme', 'host', 'path', 'expectedStatusCodes', 'followRedirects'] : [];
+  const maximumDurationMs = runtimePolicyLimits.maximumReadinessDurationMs;
+  if (keys.length === 0 || !isExactRecord(value, keys)
+    || !isBoundedInteger(value.initialDelayMs, 0, maximumDurationMs)
+    || !isBoundedInteger(value.startupGraceMs, 0, maximumDurationMs)
+    || !isBoundedInteger(value.intervalMs, 100, maximumDurationMs)
+    || !isBoundedInteger(value.timeoutMs, 1, 60_000)
+    || !isBoundedInteger(value.successThreshold, 1, 100)
+    || !isBoundedInteger(value.failureThreshold, 1, 100)
+    || value.timeoutMs > value.intervalMs || value.initialDelayMs > value.startupGraceMs) {
+    failArg('runtime config readiness must use explicit bounded timing and exact schema');
+  }
+  if (value.kind === 'process') return;
+  if (!isRuntimePortName(value.targetPort) || !isBoundedInteger(value.port, 1, 65535)
+    || !selectsTcpTargetArg(value.targetPort, value.port)) {
+    failArg('runtime config readiness must select a declared TCP target and port');
+  }
+  if (value.kind === 'tcp') return;
+  if ((value.scheme !== 'http' && value.scheme !== 'https') || value.followRedirects !== false
+    || typeof value.host !== 'string' || value.host.length > 253
+    || !/^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$/.test(value.host)
+    || typeof value.path !== 'string' || value.path.length > 4096
+    || !value.path.startsWith('/') || value.path.startsWith('//')
+    || /[^\x21-\x7e]|[\\#]/.test(value.path)
+    || /%(?![0-9A-F]{2})/.test(value.path)
+    || !Array.isArray(value.expectedStatusCodes) || value.expectedStatusCodes.length === 0
+    || value.expectedStatusCodes.length > 32) {
+    failArg('runtime config HTTP readiness must use an exact bounded request policy');
+  }
+  const parsed = new URL(value.path, 'http://runtime.invalid');
+  if (`${parsed.pathname}${parsed.search}` !== value.path) failArg('runtime config HTTP path must be canonical');
+  let previousCode = 0;
+  for (const code of value.expectedStatusCodes) {
+    if (!isBoundedInteger(code, 200, 599) || code <= previousCode) {
+      failArg('runtime config HTTP status expectations must be sorted unique final codes');
+    }
+    previousCode = code;
+  }
+};

package/ts/private/tokenlist.ts

@@ -0,0 +1,30 @@
+/**
+ * Judging a list of tokens a peer sent against the vocabulary it may draw from.
+ *
+ * Every such list in this package is compared byte for byte by its receiver, so they all obey one
+ * rule; a second spelling of that rule elsewhere would be a second answer to what a canonical list
+ * is. A caller adds whatever else its own contract demands — a required subset, a bound — as its
+ * own clause beside this one.
+ */
+import { compareWireTokens } from './canonicaljson.js';
+
+/**
+ * True when a value is exactly a canonical token list: known names, strictly increasing.
+ *
+ * Strictly increasing states sorted and duplicate-free in one rule, which is what lets a replayed
+ * list be compared byte for byte instead of as a set. A hole is refused rather than skipped over:
+ * array iteration passes holes by, so a sparse list would satisfy every rule about its entries
+ * while carrying none of the entries a receiver then compares.
+ */
+export const isCanonicalTokenList = <TTokenGeneric extends string>(
+  valueArg: unknown,
+  vocabularyArg: readonly TTokenGeneric[],
+): valueArg is TTokenGeneric[] => (
+  Array.isArray(valueArg)
+  && Object.keys(valueArg).length === valueArg.length
+  && valueArg.every((entryArg, indexArg) => (
+    vocabularyArg.some((tokenArg) => tokenArg === entryArg)
+    && (indexArg === 0
+      || compareWireTokens(valueArg[indexArg - 1] as string, entryArg as string) < 0)
+  ))
+);

package/ts/protocol.ts

@@ -0,0 +1,364 @@
+import { commitinfo } from './00_commitinfo_data.js';
+import {
+  isPlainRecord, readDataProperty, readExactDataRecord,
+} from './private/dataproperties.js';
+import {
+  compareReleaseVersions,
+  isReleaseVersion,
+  maximumReleaseVersionLength,
+  parseReleaseVersion,
+  type IReleaseVersion,
+} from './private/releaseversion.js';
+
+/**
+ * The contract this build speaks: the installed `@serve.zone/interfaces` release.
+ *
+ * There is no protocol number beside it and no per-shape version anywhere in this package. One
+ * release of these interfaces is exactly one contract, so naming the release is the complete
+ * statement about what a peer sends and what it can read.
+ */
+export const protocolVersion: string = commitinfo.version;
+
+/**
+ * What one side of a session speaks, and the oldest peer it accepts.
+ *
+ * Frozen across majors together with `IProtocolRefusal`: a peer built against the next major must
+ * still be able to read this, or the mismatch it exists to name arrives as an unreadable body and
+ * degrades into a generic contract rejection.
+ */
+export interface IProtocolOffer {
+  /** `MAJOR.MINOR.PATCH` of the `@serve.zone/interfaces` release the sender was built against. */
+  interfacesVersion: string;
+  /**
+   * The oldest peer release this side accepts: in the same major as `interfacesVersion` and never
+   * above it. A deployable raises it in the commit that starts depending on a later minor, for the
+   * session kind that depends on it, which is what orders a rollout: peers first.
+   */
+  minimumPeerVersion: string;
+}
+
+const protocolOfferKeys = ['interfacesVersion', 'minimumPeerVersion'] as const;
+
+/**
+ * Why two offers cannot serve one session, judged from the side that refuses.
+ *
+ * `peer-below-minimum` and `self-below-peer-minimum` are the same fact seen from the two sides,
+ * which is why both exist: a log line names who was too old without the reader having to know
+ * which side wrote it.
+ */
+const protocolIncompatibilities = [
+  'major-mismatch',
+  'peer-below-minimum',
+  'self-below-peer-minimum',
+] as const;
+
+export type TProtocolIncompatibility = (typeof protocolIncompatibilities)[number];
+
+/**
+ * The named refusal, carried as `TypedResponseError.errorData` on a TypedRequest hop and as the
+ * response body on the Spark heartbeat's refusal status. Frozen across majors.
+ */
+export interface IProtocolRefusal {
+  code: 'protocol-incompatible';
+  /** Judged from the refusing side. */
+  reason: TProtocolIncompatibility;
+  /** The offer of the side that refused. */
+  refusing: IProtocolOffer;
+  /** The offer it refused. */
+  refused: IProtocolOffer;
+}
+
+const protocolRefusalKeys = ['code', 'reason', 'refusing', 'refused'] as const;
+
+export type TProtocolNegotiation =
+  | { compatible: true }
+  | { compatible: false; refusal: IProtocolRefusal };
+
+/**
+ * The cadence at which a refused client offers again.
+ *
+ * Shared so that no client invents its own: a refusal stands until one of the two sides is
+ * upgraded, which is an operator action, so offering faster only costs connections.
+ */
+export const refusedOfferRetryIntervalMs = 300_000;
+
+/**
+ * The status a route that carries no typed error answers a refusal with, body `IProtocolRefusal`.
+ *
+ * The Spark routes are plain HTTPS POSTs, so the refusal needs a status of its own: 422 says the
+ * body was read and judged, which is exactly what happened, and separates a refused offer from the
+ * 401 an unknown node gets and the 400 a malformed body gets.
+ */
+export const protocolRefusalHttpStatus = 422;
+
+const exactSchemaMessage = (pathArg: string): string => `${pathArg} must use its exact schema`;
+
+const releaseVersionMessage = (pathArg: string): string => (
+  `${pathArg} must be a MAJOR.MINOR.PATCH release version of at most `
+  + `${maximumReleaseVersionLength} characters, without prerelease or build metadata`
+);
+
+const requireReleaseVersion = (valueArg: unknown, pathArg: string): IReleaseVersion => {
+  const version = parseReleaseVersion(valueArg);
+  if (version === null) {
+    throw new Error(releaseVersionMessage(pathArg));
+  }
+  return version;
+};
+
+/**
+ * The one place an offer is built: frozen, over two values that were read once and then judged.
+ *
+ * Every offer this module hands out comes from here, so what a caller holds shares nothing with
+ * the body it arrived on and cannot change under a session that was already negotiated.
+ */
+const buildProtocolOffer = (
+  interfacesVersionArg: string,
+  minimumPeerVersionArg: string,
+): IProtocolOffer => Object.freeze({
+  interfacesVersion: interfacesVersionArg,
+  minimumPeerVersion: minimumPeerVersionArg,
+});
+
+/** Every reason two values are not one offer, in the order a reader fixes them. */
+const offerErrors = (
+  interfacesVersionArg: unknown,
+  minimumPeerVersionArg: unknown,
+  pathArg: string,
+): string[] => {
+  const spoken = parseReleaseVersion(interfacesVersionArg);
+  const minimum = parseReleaseVersion(minimumPeerVersionArg);
+  if (spoken === null || minimum === null) {
+    return [
+      ...(spoken === null ? [releaseVersionMessage(`${pathArg} interfacesVersion`)] : []),
+      ...(minimum === null ? [releaseVersionMessage(`${pathArg} minimumPeerVersion`)] : []),
+    ];
+  }
+  return [
+    ...(spoken.major !== minimum.major
+      ? [`${pathArg} minimumPeerVersion must be in the same major as interfacesVersion`]
+      : []),
+    ...(compareReleaseVersions(minimum, spoken) > 0
+      ? [`${pathArg} minimumPeerVersion must not be above interfacesVersion`]
+      : []),
+  ];
+};
+
+/** What reading one value produced: the offer it carried, or every reason it carried none. */
+interface IProtocolOfferRead {
+  offer: IProtocolOffer | null;
+  errors: string[];
+}
+
+/**
+ * Reads both fields once and judges those two values.
+ *
+ * The copy is built from what was judged rather than read again from the source: an offer arrives
+ * on a body a peer wrote, and the session must be served by the offer the validator saw. A field
+ * that is not plain data is refused by `readExactDataRecord` instead of run, so reading an offer
+ * never executes a peer's code and cannot observe two different values.
+ */
+const readOffer = (valueArg: unknown, pathArg = 'protocol offer'): IProtocolOfferRead => {
+  const offer = readExactDataRecord(valueArg, protocolOfferKeys);
+  if (offer === null) {
+    return { offer: null, errors: [exactSchemaMessage(pathArg)] };
+  }
+  const interfacesVersion: unknown = offer.interfacesVersion;
+  const minimumPeerVersion: unknown = offer.minimumPeerVersion;
+  // The grammar is judged first because the rules below compare two releases, and a value that
+  // names none cannot be compared to one.
+  if (!isReleaseVersion(interfacesVersion) || !isReleaseVersion(minimumPeerVersion)) {
+    return { offer: null, errors: offerErrors(interfacesVersion, minimumPeerVersion, pathArg) };
+  }
+  const errors = offerErrors(interfacesVersion, minimumPeerVersion, pathArg);
+  return errors.length > 0
+    ? { offer: null, errors }
+    : { offer: buildProtocolOffer(interfacesVersion, minimumPeerVersion), errors };
+};
+
+/**
+ * Validates one protocol offer and names every reason it is refused.
+ *
+ * Shape and self-consistency only, like every other validator in this package: whether the peer
+ * that sent it may open a session is the server's decision against its own records, and whether
+ * the two sides can serve one is `negotiateProtocol`.
+ */
+export const validateProtocolOffer = (
+  valueArg: unknown,
+  pathArg = 'protocol offer',
+): string[] => readOffer(valueArg, pathArg).errors;
+
+/**
+ * Every reason the `protocol` key of a body does not carry one offer.
+ *
+ * The naming twin of `readProtocolOffer`, for a validator that lists reasons instead of throwing:
+ * both read that key once as a data property, so a carrier never runs an accessor a peer put on a
+ * body, and both judge the copy that read produced rather than the peer's object.
+ */
+export const validateProtocolOfferOn = (
+  bodyArg: unknown,
+  pathArg = 'protocol offer',
+): string[] => validateProtocolOffer(readDataProperty(bodyArg, 'protocol')?.value, pathArg);
+
+/** One valid offer, detached and inert, or the first reason the value is not one. */
+const requireProtocolOffer = (valueArg: unknown, pathArg: string): IProtocolOffer => {
+  const read = readOffer(valueArg, pathArg);
+  if (read.offer === null) {
+    throw new Error(read.errors[0]);
+  }
+  return read.offer;
+};
+
+/**
+ * This build's offer towards one kind of peer.
+ *
+ * The spoken version is never stated by the caller: it is the installed release, so an offer
+ * cannot claim a contract this build does not carry. A minimum above that release, or in another
+ * major, is refused here — at start-up of the deployable that declared it, rather than at its
+ * first registration in production.
+ */
+export const createProtocolOffer = (minimumPeerVersionArg: string): IProtocolOffer => (
+  requireProtocolOffer({
+    interfacesVersion: protocolVersion,
+    minimumPeerVersion: minimumPeerVersionArg,
+  }, 'protocol offer')
+);
+
+/**
+ * The offer on a request or response body, read before anything else on that body.
+ *
+ * This is where the one server order on every carrier is written down, so that each carrier can
+ * refer to it instead of restating it: read the raw body as a bounded record, `readProtocolOffer`
+ * on it, `negotiateProtocol` against this server's offer for that session kind, answer a refusal,
+ * and only then the carrier's exact-key validator, the bearer and any mutation. The offer comes
+ * before the validator because every validator in this package is exact-key: a peer of a later
+ * major sends keys this build cannot validate, so a server that shape-checked first would answer
+ * an incompatible peer with a generic malformed-body rejection instead of the named refusal it
+ * backs off from. A carrier whose validator also checks `protocol` checks it for self-consistency
+ * within one major; the negotiation has already happened by then.
+ *
+ * Reads `protocol` alone and touches no other key, for that same reason. The returned offer is
+ * detached, so validating the rest of the body afterwards cannot change what was negotiated.
+ */
+export const readProtocolOffer = (bodyArg: unknown): IProtocolOffer => {
+  if (!isPlainRecord(bodyArg)) {
+    throw new Error('protocol offer must be carried as the protocol key of a body record');
+  }
+  // One data property, read once: a `protocol` key that is an accessor carries no offer this
+  // module will serve a session from, exactly like a key that is missing or malformed.
+  return requireProtocolOffer(readDataProperty(bodyArg, 'protocol')?.value, 'protocol offer');
+};
+
+/**
+ * The one place an `IProtocolRefusal` is built: frozen, over two offers this module already
+ * detached, so a refusal states what was judged and nothing a caller can change afterwards.
+ */
+const buildProtocolRefusal = (
+  reasonArg: TProtocolIncompatibility,
+  refusingArg: IProtocolOffer,
+  refusedArg: IProtocolOffer,
+): IProtocolRefusal => Object.freeze({
+  code: 'protocol-incompatible',
+  reason: reasonArg,
+  refusing: refusingArg,
+  refused: refusedArg,
+});
+
+/** One side of a negotiation: the offer it named, detached, and the two versions that offer states. */
+interface INegotiatingSide {
+  offer: IProtocolOffer;
+  spoken: IReleaseVersion;
+  minimum: IReleaseVersion;
+}
+
+/**
+ * One side, read exactly once.
+ *
+ * Only the grammar is judged here: whether two offers can serve one session is the decision this
+ * feeds, and a side whose own two versions disagree still has to get a named answer rather than a
+ * different error. Reading once is what lets the refusal state what was judged while each caller
+ * goes on holding, and changing, its own offer object.
+ */
+const readNegotiatingSide = (offerArg: IProtocolOffer, pathArg: string): INegotiatingSide => {
+  const { interfacesVersion, minimumPeerVersion } = offerArg;
+  const spoken = requireReleaseVersion(interfacesVersion, `${pathArg} interfacesVersion`);
+  const minimum = requireReleaseVersion(minimumPeerVersion, `${pathArg} minimumPeerVersion`);
+  return { offer: buildProtocolOffer(interfacesVersion, minimumPeerVersion), spoken, minimum };
+};
+
+/**
+ * Whether the two sides can serve one session, judged from the local side.
+ *
+ * Pure, and the order of the three checks is part of the contract: a major mismatch is reported as
+ * a major mismatch even when a minimum would also fail, because that is the fact an operator acts
+ * on. The two minimum rules are mirror images — one of them holding means the other holds on the
+ * peer, and they can never hold at once, since that would need each version to be below the other.
+ * An offer whose versions are not release versions is refused by throwing, at the caller that
+ * passed it, rather than named as an incompatibility between two peers.
+ */
+export const negotiateProtocol = (
+  localArg: IProtocolOffer,
+  remoteArg: IProtocolOffer,
+): TProtocolNegotiation => {
+  const local = readNegotiatingSide(localArg, 'local protocol offer');
+  const remote = readNegotiatingSide(remoteArg, 'remote protocol offer');
+  const refuse = (reasonArg: TProtocolIncompatibility): TProtocolNegotiation => ({
+    compatible: false,
+    refusal: buildProtocolRefusal(reasonArg, local.offer, remote.offer),
+  });
+  if (local.spoken.major !== remote.spoken.major) {
+    return refuse('major-mismatch');
+  }
+  if (compareReleaseVersions(remote.spoken, local.minimum) < 0) {
+    return refuse('peer-below-minimum');
+  }
+  if (compareReleaseVersions(local.spoken, remote.minimum) < 0) {
+    return refuse('self-below-peer-minimum');
+  }
+  return { compatible: true };
+};
+
+const isProtocolIncompatibility = (valueArg: unknown): valueArg is TProtocolIncompatibility => (
+  protocolIncompatibilities.some((reasonArg) => reasonArg === valueArg)
+);
+
+/**
+ * The refusal inside an error payload or a response body, or `null` when the value is not one.
+ *
+ * Every transport hands it over as plain JSON, so this reads a value that survived serialization
+ * and answers `null` for everything else: that is how a client tells a protocol refusal, which it
+ * must not retry quickly, apart from every other error a server may return.
+ */
+export const readProtocolRefusal = (valueArg: unknown): IProtocolRefusal | null => {
+  const refusal = readExactDataRecord(valueArg, protocolRefusalKeys);
+  if (refusal === null) {
+    return null;
+  }
+  // Every field is read once and both offers are judged as copies, so what a client waits on is
+  // what its own check answered `null` or a refusal for.
+  const code: unknown = refusal.code;
+  const reason: unknown = refusal.reason;
+  if (code !== 'protocol-incompatible' || !isProtocolIncompatibility(reason)) {
+    return null;
+  }
+  const refusing = readOffer(refusal.refusing).offer;
+  const refused = readOffer(refusal.refused).offer;
+  if (refusing === null || refused === null) {
+    return null;
+  }
+  return buildProtocolRefusal(reason, refusing, refused);
+};
+
+/**
+ * One line naming both sides, for the log a refusal is judged from.
+ *
+ * It opens with the code, which is the text prefix frozen across majors, so a refusal stays
+ * recognisable in a log written by a build nobody runs any more.
+ */
+export const describeProtocolRefusal = (refusalArg: IProtocolRefusal): string => (
+  `${refusalArg.code} (${refusalArg.reason}): `
+  + `refusing side speaks ${refusalArg.refusing.interfacesVersion} `
+  + `and accepts from ${refusalArg.refusing.minimumPeerVersion}; `
+  + `refused side speaks ${refusalArg.refused.interfacesVersion} `
+  + `and accepts from ${refusalArg.refused.minimumPeerVersion}`
+);

package/ts/requests/admin.ts

@@ -1,16 +1,16 @@
 import * as plugins from '../plugins.js';
 import type { IIdentity, IIdentityCredential, IServiceDeploymentGrant } from '../data/user.js';
 import type {
-  IServiceMachineCredentialMetadataV1, IServiceMachineCredentialMutationResultV1,
-  TServiceMachineCredentialMutationV1,
+  IServiceMachineCredentialMetadata, IServiceMachineCredentialMutationResult,
+  TServiceMachineCredentialMutation,
 } from '../data/servicecredential.js';
 
-export interface IReq_Admin_GetServiceMachineCredentialV1 extends plugins.typedrequestInterfaces.implementsTR<
-  plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_GetServiceMachineCredentialV1
+export interface IReq_Admin_GetServiceMachineCredential extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_GetServiceMachineCredential
 > {
-  method: 'getServiceMachineCredentialV1';
+  method: 'getServiceMachineCredential';
   request: { identity: IIdentityCredential; organizationId: string; serviceId: string };
-  response: { credential: IServiceMachineCredentialMetadataV1 | null };
+  response: { credential: IServiceMachineCredentialMetadata | null };
 }
 
 /**
@@ -18,12 +18,12 @@ export interface IReq_Admin_GetServiceMachineCredentialV1 extends plugins.typedr
  * encrypted SecretSet delivery and the replay receipt in one fenced transaction.
  * No bearer is returned. Existing legacy deployment/cluster credentials are separate.
  */
-export interface IReq_Admin_MutateServiceMachineCredentialV1 extends plugins.typedrequestInterfaces.implementsTR<
-  plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_MutateServiceMachineCredentialV1
+export interface IReq_Admin_MutateServiceMachineCredential extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_MutateServiceMachineCredential
 > {
-  method: 'mutateServiceMachineCredentialV1';
-  request: { identity: IIdentityCredential; mutation: TServiceMachineCredentialMutationV1 };
-  response: IServiceMachineCredentialMutationResultV1;
+  method: 'mutateServiceMachineCredential';
+  request: { identity: IIdentityCredential; mutation: TServiceMachineCredentialMutation };
+  response: IServiceMachineCredentialMutationResult;
 }
 
 /** Backend-owned human credential metadata; never includes a password verifier. */