@openlup/platform 0.28.0 → 0.30.0

package/src/operations/server/platformWatchdogService.ts

@@ -0,0 +1,209 @@
+import type {
+  AlertDecision,
+  AlertSeverity,
+  WatchdogSnapshot,
+} from "../contracts/index.js";
+import {
+  DEFAULT_PAGING_MIN_SEVERITY,
+  shouldPage,
+} from "../index.js";
+import type {
+  AlertLedgerPort,
+  AlertSinkPort,
+  ObservabilityEvidencePort,
+} from "../contracts/index.js";
+import {
+  isActionabilitySuppressed,
+  isDeliveryBackoff,
+  isPagingSuppressed,
+  isSeverityEscalation,
+} from "./platformWatchdogDeliveryPolicy.js";
+
+import {
+  emptyWatchdogDecisionCounts,
+  isCriticalDecision,
+  processWatchdogDecision,
+} from "./platformWatchdogDecision.js";
+import { createSerialWatchdogSink, runWatchdogQueue } from "./platformWatchdogQueue.js";
+
+export type PlatformWatchdogResult<Channel extends string = string> = {
+  ok: boolean;
+  health: "healthy" | "firing";
+  checkOnly: boolean;
+  checkedAt: string;
+  alertCount: number;
+  firingCount: number;
+  /** P0/P1 incidents not covered by an active snooze and still requiring ownership. */
+  actionableCriticalCount: number;
+  /** P0/P1 incidents covered by an active snooze; acknowledged alerts stay actionable. */
+  suppressedCriticalCount: number;
+  /** Alerts that meet the current paging threshold and are not currently page-suppressed. */
+  actionablePageableCount: number;
+  maxSeverity: string | null;
+  decisions: AlertDecision<Channel>[];
+  notified: number;
+  notificationFailures: number;
+  /** Failed deliveries held until their persisted bounded retry time. */
+  deliveryBackoffCount: number;
+  throttledNotifications: number;
+  skippedNotifications: number;
+  belowThreshold: number;
+  suppressed: number;
+  muted: number;
+  resolved: number;
+};
+
+export async function runPlatformWatchdog<Snapshot extends WatchdogSnapshot, CatalogEntry, Channel extends string = string>({
+  evidencePort, evaluate,
+  ledgerPort,
+  sinkPort,
+  catalog,
+  now = new Date(),
+  checkOnly,
+  notificationThrottleSeconds,
+  pagingMinSeverity = DEFAULT_PAGING_MIN_SEVERITY,
+  mutedDedupePrefixes = [],
+  normalizeDecision,
+}: {
+  evidencePort: ObservabilityEvidencePort<Snapshot>;
+  evaluate: (snapshot: Snapshot, catalog: readonly CatalogEntry[], now: Date) => AlertDecision<Channel>[];
+  ledgerPort: AlertLedgerPort<Channel>;
+  sinkPort: AlertSinkPort<Channel>;
+  catalog: readonly CatalogEntry[];
+  now?: Date;
+  checkOnly: boolean;
+  /** Flat override; when omitted, the throttle is scaled per alert severity. */
+  notificationThrottleSeconds?: number;
+  pagingMinSeverity?: AlertSeverity;
+  /**
+   * Dedupe-key prefixes fully muted for this environment (e.g. `job_missed` on a
+   * staging host with no real crons). Muted signals are not recorded, not paged,
+   * and existing open rows for them auto-resolve — keeping the ledger clean.
+   */
+  mutedDedupePrefixes?: readonly string[];
+  normalizeDecision?: (decision: AlertDecision<Channel>) => AlertDecision<Channel>;
+}): Promise<PlatformWatchdogResult<Channel>> {
+  const snapshot = await evidencePort.collectSnapshot(now);
+  const allDecisions = evaluate(snapshot, catalog, now);
+  const decisions = allDecisions
+    .filter((decision) => !isMuted(decision.dedupeKey, mutedDedupePrefixes))
+    .map((decision) => normalizeDecision ? normalizeDecision(decision) : decision);
+  const muted = allDecisions.length - decisions.length;
+  const firingDecisions = decisions.filter((decision) => decision.paging !== "never");
+  const firingCount = firingDecisions.length;
+  const maxSeverity = maxSeverityOf(firingDecisions);
+  const openAlerts = await ledgerPort.listOpenAlerts();
+
+  if (checkOnly) {
+    const alertsByDedupeKey = new Map(openAlerts.map((alert) => [alert.dedupeKey, alert]));
+    let actionableCriticalCount = 0;
+    let suppressedCriticalCount = 0;
+    let actionablePageableCount = 0;
+    let deliveryBackoffCount = 0;
+    let suppressed = 0;
+    for (const decision of decisions) {
+      const alert = alertsByDedupeKey.get(decision.dedupeKey);
+      // The mutating path clears acknowledgement, snooze and delivery cadence on
+      // escalation. Mirror that transition here so a read-only probe cannot
+      // report a stale suppression that the next real tick will remove.
+      const suppressionSurvives = alert ? !isSeverityEscalation(decision, alert) : false;
+      const actionableSuppressed = alert && suppressionSurvives
+        ? isActionabilitySuppressed(alert, now)
+        : false;
+      const pagingSuppressed = alert && suppressionSurvives
+        ? isPagingSuppressed(alert, now)
+        : false;
+      const critical = isCriticalDecision(decision);
+      const pageable = decision.paging !== "never" && shouldPage(decision.severity, pagingMinSeverity);
+      if (critical) {
+        if (actionableSuppressed) suppressedCriticalCount += 1;
+        else actionableCriticalCount += 1;
+      }
+      if (pageable && !pagingSuppressed) actionablePageableCount += 1;
+      if (alert && pageable && !pagingSuppressed && isDeliveryBackoff(alert, now)) {
+        deliveryBackoffCount += 1;
+      }
+      if (pagingSuppressed) suppressed += 1;
+    }
+    return result({ checkOnly, checkedAt: snapshot.checkedAt, decisions, firingCount, actionableCriticalCount, suppressedCriticalCount, actionablePageableCount, notified: 0, notificationFailures: 0, deliveryBackoffCount, throttledNotifications: 0, skippedNotifications: 0, belowThreshold: 0, suppressed, muted, resolved: 0, maxSeverity });
+  }
+
+  const firingKeys = new Set(decisions.map((decision) => decision.dedupeKey));
+  const counts = emptyWatchdogDecisionCounts();
+  const serialSink = createSerialWatchdogSink(sinkPort);
+  await runWatchdogQueue(decisions, async (index) => {
+    const contribution = await processWatchdogDecision(decisions[index], {
+      ledgerPort, sinkPort: serialSink, now, pagingMinSeverity, notificationThrottleSeconds,
+    });
+    for (const key of Object.keys(contribution) as (keyof typeof counts)[]) {
+      counts[key] += contribution[key];
+    }
+  });
+
+  // A rejected decision queue drains before throwing, so it never enters resolution.
+  const staleAlerts = openAlerts.filter((alert) => !firingKeys.has(alert.dedupeKey));
+  await runWatchdogQueue(staleAlerts, async (index) => {
+    await ledgerPort.resolveAlert(staleAlerts[index].dedupeKey, now);
+  });
+
+  return result({ checkOnly, checkedAt: snapshot.checkedAt, decisions, firingCount, ...counts, muted, resolved: staleAlerts.length, maxSeverity });
+}
+
+function isMuted(dedupeKey: string, mutedPrefixes: readonly string[]): boolean {
+  return mutedPrefixes.some((prefix) => prefix.length > 0 && dedupeKey.startsWith(prefix));
+}
+
+function severityRank(severity: AlertSeverity): number {
+  return { p0: 0, p1: 1, p2: 2, p3: 3 }[severity];
+}
+
+function maxSeverityOf(decisions: readonly AlertDecision[]): AlertSeverity | null {
+  return decisions.reduce<AlertSeverity | null>((current, decision) =>
+    current == null || severityRank(decision.severity) < severityRank(current) ? decision.severity : current
+  , null);
+}
+
+function result<Channel extends string>({
+  checkOnly,
+  checkedAt,
+  decisions,
+  firingCount,
+  actionableCriticalCount,
+  suppressedCriticalCount,
+  actionablePageableCount,
+  notified,
+  notificationFailures,
+  deliveryBackoffCount,
+  throttledNotifications,
+  skippedNotifications,
+  belowThreshold,
+  suppressed,
+  muted,
+  resolved,
+  maxSeverity,
+}: Omit<PlatformWatchdogResult<Channel>, "ok" | "health" | "alertCount">): PlatformWatchdogResult<Channel> {
+  return {
+    // Evaluation success is separate from the incident state. HTTP binding may
+    // still fail the request for evidence, notification transport, or config.
+    ok: true,
+    health: firingCount === 0 ? "healthy" : "firing",
+    checkOnly,
+    checkedAt,
+    alertCount: decisions.length,
+    firingCount,
+    actionableCriticalCount,
+    suppressedCriticalCount,
+    actionablePageableCount,
+    maxSeverity,
+    decisions,
+    notified,
+    notificationFailures,
+    deliveryBackoffCount,
+    throttledNotifications,
+    skippedNotifications,
+    belowThreshold,
+    suppressed,
+    muted,
+    resolved,
+  };
+}

package/src/operations/validation.ts

@@ -0,0 +1,3 @@
+import { z } from "zod";
+z.config({ jitless: true });
+export { z };

package/src/portability/filesystemObjects.ts

@@ -0,0 +1,138 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, realpath, rename, rm, type FileHandle } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import {
+  encodeTransferObject, normalizeObjectTransferError, ObjectTransferError, validateTransferObject,
+  type TransferObject, type TransferObjectRead, type TransferObjectStore,
+} from "./objects.js";
+
+// Covers bounded metadata JSON in UTF-8 plus JSON-escaped bounded identifiers.
+const maximumDescriptorBytes = 262144;
+
+/**
+ * Private local transfer store, exclusively controlled by its owner process/account.
+ * Metadata and bytes publish together through one directory rename. Concurrent use through
+ * this adapter is supported; hostile same-UID filesystem mutation is outside that guarantee.
+ */
+export async function createFilesystemTransferObjects(options: {
+  root: string;
+  maximumObjectBytes: number;
+  /** Host label for this filesystem owner's private-read policy; other ACLs refuse. */
+  access: string;
+}): Promise<TransferObjectStore> {
+  if (!isAbsolute(options.root) || !Number.isSafeInteger(options.maximumObjectBytes) || options.maximumObjectBytes < 0
+    || typeof options.access !== "string" || !options.access.trim()) {
+    throw new ObjectTransferError("invalid_input");
+  }
+  const root = resolve(options.root), maximum = options.maximumObjectBytes, access = options.access;
+  try {
+    if (await realpath(dirname(root)) !== dirname(root)) throw new ObjectTransferError("denied");
+    await mkdir(root, { mode: 0o700 }).catch(error => { if (errno(error) !== "EEXIST") throw error; });
+    await privateDirectory(root, true);
+  } catch (error) { throw filesystemFailure(error); }
+  const location = (key: string) => join(root, createHash("sha256").update(JSON.stringify(key)).digest("hex"));
+  return {
+    async read(key, expectedVersion): Promise<TransferObjectRead> {
+      let body: FileHandle | undefined;
+      let published = false;
+      try {
+        await privateDirectory(root, true);
+        const directory = location(key);
+        await privateDirectory(directory);
+        published = true;
+        const metadata = await openPrivateFile(join(directory, "metadata.json"));
+        let object: TransferObject;
+        try {
+          if ((await metadata.stat()).size > maximumDescriptorBytes) throw new ObjectTransferError("integrity_conflict");
+          try { object = JSON.parse(await metadata.readFile("utf8")) as TransferObject; }
+          catch { throw new ObjectTransferError("integrity_conflict"); }
+        } finally { await metadata.close(); }
+        validateTransferObject(object);
+        if (object.access !== access) throw new ObjectTransferError("denied");
+        if (object.key !== key || (expectedVersion !== undefined && object.version !== expectedVersion)) throw new ObjectTransferError("version_conflict");
+        if (object.bytes > maximum) throw new ObjectTransferError("invalid_input");
+        body = await openPrivateFile(join(directory, "bytes"));
+        if ((await body.stat()).size !== object.bytes) throw new ObjectTransferError("integrity_conflict");
+        await body.close();
+        body = undefined;
+        // Open lazily: descriptor refusal must not leave an unconsumed stream holding a file.
+        return { object, body: (async function* () {
+          let opened: FileHandle | undefined;
+          try {
+            await privateDirectory(root, true);
+            await privateDirectory(directory);
+            opened = await openPrivateFile(join(directory, "bytes"));
+            if ((await opened.stat()).size !== object.bytes) throw new ObjectTransferError("integrity_conflict");
+            for await (const chunk of opened.createReadStream({ autoClose: false })) yield Buffer.from(chunk);
+          }
+          catch (error) { throw errno(error) === "ENOENT" ? new ObjectTransferError("integrity_conflict") : filesystemFailure(error); }
+          finally { await opened?.close(); }
+        })() };
+      } catch (error) {
+        await body?.close();
+        if (published && errno(error) === "ENOENT") throw new ObjectTransferError("integrity_conflict");
+        throw filesystemFailure(error);
+      }
+    },
+    async createIfAbsent(object, bytes) {
+      let temporary: string | undefined;
+      try {
+        const encoded = Buffer.from(encodeTransferObject(object));
+        if (encoded.byteLength > maximumDescriptorBytes) throw new ObjectTransferError("invalid_input");
+        if (object.access !== access) throw new ObjectTransferError("denied");
+        const key = object.key;
+        if (object.bytes > maximum || bytes.byteLength !== object.bytes
+          || createHash("sha256").update(bytes).digest("hex") !== object.sha256) throw new ObjectTransferError("integrity_conflict");
+        await privateDirectory(root, true);
+        temporary = join(root, `.partial-${randomUUID()}`);
+        await mkdir(temporary, { mode: 0o700 });
+        await writePrivateFile(join(temporary, "metadata.json"), encoded);
+        await writePrivateFile(join(temporary, "bytes"), bytes);
+        const directoryHandle = await open(temporary, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try { await directoryHandle.sync(); } finally { await directoryHandle.close(); }
+        try {
+          // Existing published objects are nonempty directories, so rename cannot replace them.
+          // Check also refuses an empty directory or symlink occupying a target key.
+          await lstat(location(key));
+          throw new ObjectTransferError("version_conflict");
+        } catch (error) { if (errno(error) !== "ENOENT") throw error; }
+        await rename(temporary, location(key));
+        temporary = undefined;
+        const rootHandle = await open(root, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try { await rootHandle.sync(); } finally { await rootHandle.close(); }
+      } catch (error) { throw filesystemFailure(error); }
+      finally { if (temporary) await rm(temporary, { recursive: true, force: true }); }
+    },
+  };
+}
+
+async function privateDirectory(path: string, storeRoot = false): Promise<void> {
+  const stat = await lstat(path).catch(error => {
+    if (storeRoot && errno(error) === "ENOENT") throw new ObjectTransferError("unavailable");
+    throw error;
+  });
+  if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o777) !== 0o700 || stat.uid !== process.getuid?.()) {
+    throw new ObjectTransferError("denied");
+  }
+}
+async function openPrivateFile(path: string): Promise<FileHandle> {
+  const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.nlink !== 1 || (stat.mode & 0o777) !== 0o600 || stat.uid !== process.getuid?.()) throw new ObjectTransferError("denied");
+    return handle;
+  } catch (error) { await handle.close(); throw error; }
+}
+async function writePrivateFile(path: string, bytes: Uint8Array): Promise<void> {
+  const handle = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+  try { await handle.writeFile(bytes); await handle.sync(); } finally { await handle.close(); }
+}
+function errno(error: unknown): string | undefined { return (error as NodeJS.ErrnoException | undefined)?.code; }
+function filesystemFailure(error: unknown): ObjectTransferError {
+  if (error instanceof ObjectTransferError) return error;
+  if (errno(error) === "ENOENT") return new ObjectTransferError("absent");
+  if (["EACCES", "EPERM", "ELOOP"].includes(errno(error) ?? "")) return new ObjectTransferError("denied");
+  if (["EEXIST", "ENOTEMPTY"].includes(errno(error) ?? "")) return new ObjectTransferError("version_conflict");
+  return normalizeObjectTransferError(error);
+}

package/src/portability/index.ts

@@ -0,0 +1,12 @@
+// Server-only, opt-in data movement. No executor, route or handover is activated.
+export { copyTransferObjects, ObjectTransferError } from "./objects.js";
+export type {
+  ObjectTransferFailure, TransferObject, TransferObjectRead, TransferObjectReader,
+  TransferObjectStore, TransferObjectInventory,
+} from "./objects.js";
+export { createFilesystemTransferObjects } from "./filesystemObjects.js";
+export { captureCompatiblePostgresRows, restoreCompatiblePostgresRows, PostgresTransferError } from "./postgresRows.js";
+export type {
+  CompatiblePostgresTable, TransferPostgresQuery, CompatiblePostgresSnapshot,
+  CompatiblePostgresTarget, CompatiblePostgresPacket, PostgresTransferFailure,
+} from "./postgresRows.js";

package/src/portability/objects.ts

@@ -0,0 +1,160 @@
+import { createHash } from "node:crypto";
+
+export type ObjectTransferFailure = "absent" | "denied" | "unavailable" | "version_conflict" | "integrity_conflict" | "invalid_input";
+
+/** Adapters distinguish missing data from permission and availability failures. */
+export class ObjectTransferError extends Error {
+  constructor(readonly code: ObjectTransferFailure) {
+    super(`object_transfer_${code}`);
+    this.name = "ObjectTransferError";
+  }
+}
+
+export interface TransferObject {
+  key: string;
+  /** Logical immutable source version; never a claim about a target provider's native version ID. */
+  version: string;
+  bytes: number;
+  sha256: string;
+  metadata: Readonly<Record<string, string>>;
+  /** An explicit access classification, never inferred from a public URL. */
+  access: string;
+  lineage?: { sourceId: string; snapshotId: string; sourceVersion: string };
+}
+
+export interface TransferObjectRead {
+  object: TransferObject;
+  body: AsyncIterable<Uint8Array>;
+}
+
+export interface TransferObjectReader {
+  /** Must read the requested version or refuse, never silently read a newer one. */
+  read(key: string, expectedVersion?: string): Promise<TransferObjectRead>;
+}
+
+export interface TransferObjectStore extends TransferObjectReader {
+  /** Atomic publication; an existing key must refuse with version_conflict. */
+  createIfAbsent(object: TransferObject, bytes: Uint8Array): Promise<void>;
+}
+
+export interface TransferObjectInventory {
+  sourceId: string;
+  /** Host prerequisite: complete inventory and stable versioned reads, or a held write fence. */
+  snapshot: { kind: "immutable" | "quiesced"; id: string };
+  objects: readonly TransferObject[];
+}
+
+/** Canonical descriptor encoding also preserves metadata independent of property order. */
+export function encodeTransferObject(object: TransferObject): string {
+  validateTransferObject(object);
+  return JSON.stringify({
+    key: object.key, version: object.version, bytes: object.bytes, sha256: object.sha256,
+    metadata: Object.fromEntries(Object.entries(object.metadata).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)),
+    access: object.access,
+    ...(object.lineage ? { lineage: { sourceId: object.lineage.sourceId, snapshotId: object.lineage.snapshotId, sourceVersion: object.lineage.sourceVersion } } : {}),
+  });
+}
+
+export function validateTransferObject(object: TransferObject): void {
+  if (!object || !text(object.key, 4096) || !text(object.version, 1024)
+    || !Number.isSafeInteger(object.bytes) || object.bytes < 0 || !/^[a-f0-9]{64}$/.test(object.sha256)
+    || !text(object.access, 1024) || !object.metadata || typeof object.metadata !== "object" || Array.isArray(object.metadata)
+    || Object.entries(object.metadata).some(([key, value]) => !text(key, 1024) || typeof value !== "string" || value.length > 8192)
+    || JSON.stringify(object.metadata).length > 65536
+    || (object.lineage !== undefined && (!object.lineage || !text(object.lineage.sourceId, 1024)
+      || !text(object.lineage.snapshotId, 1024) || !text(object.lineage.sourceVersion, 1024)))) {
+    throw new ObjectTransferError("invalid_input");
+  }
+}
+
+/** Bounded in-memory object copy; ceilings are explicit and checked before any destination mutation. */
+export async function copyTransferObjects(input: {
+  inventory: TransferObjectInventory;
+  source: TransferObjectReader;
+  destination: TransferObjectStore;
+  accessMapping: Readonly<Record<string, string>>;
+  maximumObjectBytes: number;
+  maximumTotalBytes: number;
+  /** Called only after destination descriptor and bytes have been read back successfully. */
+  checkpoint?: (object: TransferObject) => Promise<void>;
+}): Promise<{ copied: number; replayed: number; verifiedKeys: string[] }> {
+  const { inventory } = input;
+  if (!inventory || !text(inventory.sourceId, 1024) || !inventory.snapshot
+    || !["immutable", "quiesced"].includes(inventory.snapshot.kind) || !text(inventory.snapshot.id, 1024)
+    || !Array.isArray(inventory.objects) || !input.accessMapping
+    || !ceiling(input.maximumObjectBytes) || !ceiling(input.maximumTotalBytes)) throw new ObjectTransferError("invalid_input");
+  // Snapshot inputs before the first await; a caller cannot change the plan during a copy.
+  const sourceId = inventory.sourceId, snapshotId = inventory.snapshot.id;
+  const keys = new Set<string>();
+  let total = 0;
+  const plan = inventory.objects.map(object => {
+    const source = JSON.parse(encodeTransferObject(object)) as TransferObject;
+    const access = Object.hasOwn(input.accessMapping, source.access) ? input.accessMapping[source.access] : undefined;
+    total += source.bytes;
+    if (keys.has(source.key) || !text(access, 1024) || source.bytes > input.maximumObjectBytes
+      || !Number.isSafeInteger(total) || total > input.maximumTotalBytes) throw new ObjectTransferError("invalid_input");
+    keys.add(source.key);
+    const target: TransferObject = { ...source, access, lineage: { sourceId, snapshotId, sourceVersion: source.version } };
+    return { source, target };
+  });
+  const result = { copied: 0, replayed: 0, verifiedKeys: [] as string[] };
+  for (const { source, target } of plan) {
+    let existing: TransferObjectRead | undefined;
+    try { existing = await input.destination.read(target.key); }
+    catch (error) { if (!failure(error, "absent")) throw normalizeObjectTransferError(error); }
+    if (existing) {
+      await verifyRead(existing, target);
+      result.replayed++;
+    } else {
+      let read: TransferObjectRead;
+      try { read = await input.source.read(source.key, source.version); }
+      catch (error) { throw normalizeObjectTransferError(error); }
+      const bytes = await verifyRead(read, source);
+      let writeFailure: ObjectTransferError | undefined;
+      try { await input.destination.createIfAbsent(target, bytes); }
+      catch (error) {
+        // A competing writer or lost write acknowledgement still requires exact readback.
+        if (!failure(error, "version_conflict") && !failure(error, "unavailable")) throw normalizeObjectTransferError(error);
+        writeFailure = normalizeObjectTransferError(error);
+      }
+      try { await verifyRead(await input.destination.read(target.key), target); }
+      catch (error) { throw failure(error, "absent") && writeFailure ? writeFailure : normalizeObjectTransferError(error); }
+      if (writeFailure) result.replayed++;
+      else result.copied++;
+    }
+    await input.checkpoint?.(JSON.parse(encodeTransferObject(target)) as TransferObject);
+    result.verifiedKeys.push(target.key);
+  }
+  return result;
+}
+
+/** Read exactly the declared bytes and hash; never trust a successful HEAD alone. */
+export async function verifyRead(read: TransferObjectRead, expected: TransferObject): Promise<Uint8Array> {
+  if (encodeTransferObject(read.object) !== encodeTransferObject(expected)) throw new ObjectTransferError("version_conflict");
+  const chunks: Buffer[] = [];
+  const hash = createHash("sha256");
+  let bytes = 0;
+  try {
+    for await (const chunk of read.body) {
+      if (!(chunk instanceof Uint8Array)) throw new ObjectTransferError("integrity_conflict");
+      bytes += chunk.byteLength;
+      if (bytes > expected.bytes) throw new ObjectTransferError("integrity_conflict");
+      const copy = Buffer.from(chunk);
+      chunks.push(copy);
+      hash.update(copy);
+    }
+  } catch (error) { throw normalizeObjectTransferError(error); }
+  if (bytes !== expected.bytes || hash.digest("hex") !== expected.sha256) throw new ObjectTransferError("integrity_conflict");
+  return Buffer.concat(chunks, bytes);
+}
+
+export function normalizeObjectTransferError(error: unknown): ObjectTransferError {
+  return error instanceof ObjectTransferError ? error : new ObjectTransferError("unavailable");
+}
+
+function text(value: unknown, maximum: number): value is string {
+  return typeof value === "string" && value.length > 0 && value.length <= maximum
+    && !Array.from(value).some(character => character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127);
+}
+function ceiling(value: number): boolean { return Number.isSafeInteger(value) && value >= 0; }
+function failure(error: unknown, code: ObjectTransferFailure): boolean { return error instanceof ObjectTransferError && error.code === code; }