settld 0.1.0

package/src/core/robots.js

@@ -0,0 +1,152 @@
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+function assertPlainObject(value, name) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${name} must be an object`);
+  if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+    throw new TypeError(`${name} must be a plain object`);
+  }
+}
+
+function assertIsoDate(value, name) {
+  assertNonEmptyString(value, name);
+  const t = Date.parse(value);
+  if (!Number.isFinite(t)) throw new TypeError(`${name} must be an ISO date string`);
+}
+
+function assertSafeNumber(value, name) {
+  if (typeof value !== "number" || !Number.isFinite(value)) throw new TypeError(`${name} must be a finite number`);
+}
+
+function assertAvailabilityWindow(window, name) {
+  assertPlainObject(window, name);
+  const allowed = new Set(["startAt", "endAt"]);
+  for (const key of Object.keys(window)) {
+    if (!allowed.has(key)) throw new TypeError(`${name} contains unknown field: ${key}`);
+  }
+  assertIsoDate(window.startAt, `${name}.startAt`);
+  assertIsoDate(window.endAt, `${name}.endAt`);
+  const start = Date.parse(window.startAt);
+  const end = Date.parse(window.endAt);
+  if (start >= end) throw new TypeError(`${name}.startAt must be before endAt`);
+}
+
+export function validateRobotRegisteredPayload(payload) {
+  assertPlainObject(payload, "payload");
+  const allowed = new Set([
+    "robotId",
+    "tenantId",
+    "ownerId",
+    "capabilities",
+    "trustScore",
+    "signerKeyId",
+    "name",
+    "homeZoneId",
+    "currentZoneId"
+  ]);
+  for (const key of Object.keys(payload)) {
+    if (!allowed.has(key)) throw new TypeError(`payload contains unknown field: ${key}`);
+  }
+
+  assertNonEmptyString(payload.robotId, "payload.robotId");
+  if (payload.tenantId !== undefined && payload.tenantId !== null) assertNonEmptyString(payload.tenantId, "payload.tenantId");
+  if (payload.ownerId !== undefined && payload.ownerId !== null) assertNonEmptyString(payload.ownerId, "payload.ownerId");
+  if (payload.capabilities !== undefined) assertPlainObject(payload.capabilities, "payload.capabilities");
+  if (payload.trustScore !== undefined) {
+    assertSafeNumber(payload.trustScore, "payload.trustScore");
+    if (payload.trustScore < 0 || payload.trustScore > 1) throw new TypeError("payload.trustScore must be within 0..1");
+  }
+  if (payload.signerKeyId !== undefined && payload.signerKeyId !== null) assertNonEmptyString(payload.signerKeyId, "payload.signerKeyId");
+  if (payload.name !== undefined && payload.name !== null) assertNonEmptyString(payload.name, "payload.name");
+  if (payload.homeZoneId !== undefined && payload.homeZoneId !== null) assertNonEmptyString(payload.homeZoneId, "payload.homeZoneId");
+  if (payload.currentZoneId !== undefined && payload.currentZoneId !== null) assertNonEmptyString(payload.currentZoneId, "payload.currentZoneId");
+
+  return payload;
+}
+
+export function validateRobotHeartbeatPayload(payload) {
+  assertPlainObject(payload, "payload");
+  const allowed = new Set(["batteryPct", "status", "location", "errorCodes", "selfCheckStatus", "healthScore"]);
+  for (const key of Object.keys(payload)) {
+    if (!allowed.has(key)) throw new TypeError(`payload contains unknown field: ${key}`);
+  }
+
+  if (payload.batteryPct !== undefined) {
+    assertSafeNumber(payload.batteryPct, "payload.batteryPct");
+    if (payload.batteryPct < 0 || payload.batteryPct > 1) throw new TypeError("payload.batteryPct must be within 0..1");
+  }
+  if (payload.status !== undefined) assertNonEmptyString(payload.status, "payload.status");
+  if (payload.location !== undefined) assertPlainObject(payload.location, "payload.location");
+  if (payload.errorCodes !== undefined && payload.errorCodes !== null) {
+    if (!Array.isArray(payload.errorCodes)) throw new TypeError("payload.errorCodes must be an array");
+    for (const c of payload.errorCodes) assertNonEmptyString(c, "payload.errorCodes[]");
+  }
+  if (payload.selfCheckStatus !== undefined && payload.selfCheckStatus !== null) {
+    assertNonEmptyString(payload.selfCheckStatus, "payload.selfCheckStatus");
+  }
+  if (payload.healthScore !== undefined && payload.healthScore !== null) {
+    if (!Number.isSafeInteger(payload.healthScore)) throw new TypeError("payload.healthScore must be a safe integer");
+    if (payload.healthScore < 0 || payload.healthScore > 100) throw new TypeError("payload.healthScore must be within 0..100");
+  }
+  return payload;
+}
+
+export function validateRobotAvailabilitySetPayload(payload) {
+  assertPlainObject(payload, "payload");
+  const allowed = new Set(["robotId", "availability", "timezone"]);
+  for (const key of Object.keys(payload)) {
+    if (!allowed.has(key)) throw new TypeError(`payload contains unknown field: ${key}`);
+  }
+  assertNonEmptyString(payload.robotId, "payload.robotId");
+
+  if (!Array.isArray(payload.availability) || payload.availability.length === 0) {
+    throw new TypeError("payload.availability must be a non-empty array");
+  }
+  for (let i = 0; i < payload.availability.length; i += 1) {
+    assertAvailabilityWindow(payload.availability[i], `payload.availability[${i}]`);
+  }
+
+  // Require windows to be non-overlapping to keep dispatch deterministic.
+  const sorted = payload.availability
+    .map((w) => ({ ...w, start: Date.parse(w.startAt), end: Date.parse(w.endAt) }))
+    .sort((a, b) => a.start - b.start);
+  for (let i = 1; i < sorted.length; i += 1) {
+    if (sorted[i].start < sorted[i - 1].end) throw new TypeError("payload.availability windows must not overlap");
+  }
+
+  if (payload.timezone !== undefined) assertNonEmptyString(payload.timezone, "payload.timezone");
+  return payload;
+}
+
+export function validateRobotStatusChangedPayload(payload) {
+  assertPlainObject(payload, "payload");
+  const allowed = new Set(["robotId", "status", "reason"]);
+  for (const key of Object.keys(payload)) {
+    if (!allowed.has(key)) throw new TypeError(`payload contains unknown field: ${key}`);
+  }
+  assertNonEmptyString(payload.robotId, "payload.robotId");
+  assertNonEmptyString(payload.status, "payload.status");
+  if (payload.reason !== undefined) assertNonEmptyString(payload.reason, "payload.reason");
+  return payload;
+}
+
+export function windowsOverlap(a, b) {
+  const aStart = Date.parse(a.startAt);
+  const aEnd = Date.parse(a.endAt);
+  const bStart = Date.parse(b.startAt);
+  const bEnd = Date.parse(b.endAt);
+  return Number.isFinite(aStart) && Number.isFinite(aEnd) && Number.isFinite(bStart) && Number.isFinite(bEnd) && aStart < bEnd && bStart < aEnd;
+}
+
+export function robotIsAvailableForWindow(robot, window) {
+  if (!robot) return false;
+  if (robot.status && robot.status !== "active") return false;
+  if (!window?.startAt || !window?.endAt) return false;
+  const start = Date.parse(window.startAt);
+  const end = Date.parse(window.endAt);
+  if (!Number.isFinite(start) || !Number.isFinite(end) || start >= end) return false;
+
+  const availability = Array.isArray(robot.availability) ? robot.availability : [];
+  return availability.some((w) => Date.parse(w.startAt) <= start && Date.parse(w.endAt) >= end);
+}

package/src/core/s3-presign.js

@@ -0,0 +1,111 @@
+import crypto from "node:crypto";
+
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+function encodeRfc3986(value) {
+  return encodeURIComponent(value).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+
+function encodePathPreservingSlashes(pathname) {
+  const parts = pathname.split("/").filter((p) => p !== "");
+  return `/${parts.map((p) => encodeRfc3986(p)).join("/")}`;
+}
+
+function sha256HexUtf8(value) {
+  return crypto.createHash("sha256").update(value, "utf8").digest("hex");
+}
+
+function hmacSha256(key, value, encoding = null) {
+  const h = crypto.createHmac("sha256", key).update(value, "utf8");
+  return encoding ? h.digest(encoding) : h.digest();
+}
+
+function toAmzDate(date) {
+  // YYYYMMDDTHHMMSSZ
+  return date.toISOString().replace(/[:-]|\.\d{3}/g, "");
+}
+
+function signingKey({ secretAccessKey, dateStamp, region, service }) {
+  const kDate = hmacSha256(`AWS4${secretAccessKey}`, dateStamp);
+  const kRegion = hmacSha256(kDate, region);
+  const kService = hmacSha256(kRegion, service);
+  return hmacSha256(kService, "aws4_request");
+}
+
+function canonicalQueryString(params) {
+  const encoded = params.map(([k, v]) => [encodeRfc3986(String(k)), encodeRfc3986(String(v))]);
+  encoded.sort((a, b) => {
+    const kc = a[0].localeCompare(b[0]);
+    if (kc !== 0) return kc;
+    return a[1].localeCompare(b[1]);
+  });
+  return encoded.map(([k, v]) => `${k}=${v}`).join("&");
+}
+
+export function presignS3Url({
+  endpoint,
+  region,
+  bucket,
+  key,
+  method,
+  accessKeyId,
+  secretAccessKey,
+  forcePathStyle = true,
+  expiresInSeconds,
+  now = new Date()
+}) {
+  assertNonEmptyString(endpoint, "endpoint");
+  assertNonEmptyString(region, "region");
+  assertNonEmptyString(bucket, "bucket");
+  assertNonEmptyString(key, "key");
+  assertNonEmptyString(method, "method");
+  assertNonEmptyString(accessKeyId, "accessKeyId");
+  assertNonEmptyString(secretAccessKey, "secretAccessKey");
+  if (!Number.isSafeInteger(expiresInSeconds) || expiresInSeconds <= 0) throw new TypeError("expiresInSeconds must be a positive integer");
+  if (expiresInSeconds > 60 * 60 * 24 * 7) throw new TypeError("expiresInSeconds must be <= 604800 (7 days)");
+
+  const base = new URL(endpoint);
+  const encodedKey = encodePathPreservingSlashes(key).slice(1); // strip leading /
+  const bucketSeg = encodeRfc3986(bucket);
+
+  if (forcePathStyle) {
+    base.pathname = `/${bucketSeg}/${encodedKey}`;
+  } else {
+    base.hostname = `${bucket}.${base.hostname}`;
+    base.pathname = `/${encodedKey}`;
+  }
+  base.search = "";
+
+  const host = String(base.host).toLowerCase();
+  const amzDate = toAmzDate(now);
+  const dateStamp = amzDate.slice(0, 8);
+  const scope = `${dateStamp}/${region}/s3/aws4_request`;
+
+  const params = [
+    ["X-Amz-Algorithm", "AWS4-HMAC-SHA256"],
+    ["X-Amz-Credential", `${accessKeyId}/${scope}`],
+    ["X-Amz-Date", amzDate],
+    ["X-Amz-Expires", String(expiresInSeconds)],
+    ["X-Amz-SignedHeaders", "host"]
+  ];
+  const query = canonicalQueryString(params);
+
+  const canonicalRequest = [
+    method.toUpperCase(),
+    base.pathname,
+    query,
+    `host:${host}\n`,
+    "host",
+    "UNSIGNED-PAYLOAD"
+  ].join("\n");
+
+  const stringToSign = ["AWS4-HMAC-SHA256", amzDate, scope, sha256HexUtf8(canonicalRequest)].join("\n");
+  const kSigning = signingKey({ secretAccessKey, dateStamp, region, service: "s3" });
+  const signature = hmacSha256(kSigning, stringToSign, "hex");
+
+  base.search = `${query}&X-Amz-Signature=${signature}`;
+  return base.toString();
+}
+

package/src/core/secrets.js

@@ -0,0 +1,128 @@
+import fs from "node:fs/promises";
+
+import { normalizeTenantId } from "./tenancy.js";
+
+export const SECRET_ERROR_CODE = Object.freeze({
+  REF_INVALID: "SECRET_REF_INVALID",
+  PROVIDER_FORBIDDEN: "SECRET_PROVIDER_FORBIDDEN",
+  PROVIDER_UNAVAILABLE: "SECRET_PROVIDER_UNAVAILABLE",
+  NOT_FOUND: "SECRET_NOT_FOUND",
+  READ_FAILED: "SECRET_READ_FAILED"
+});
+
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+function parseTtlSeconds(raw, { fallbackSeconds = 30 } = {}) {
+  if (raw === null || raw === undefined || String(raw).trim() === "") return fallbackSeconds;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0) throw new TypeError("secrets cache TTL must be a positive number");
+  return Math.floor(n);
+}
+
+export class SecretRefError extends Error {
+  constructor(code, message, { cause, provider, tenantId, ref } = {}) {
+    super(message);
+    this.name = "SecretRefError";
+    this.code = code;
+    if (provider) this.provider = provider;
+    if (tenantId) this.tenantId = tenantId;
+    if (ref) this.ref = ref;
+    if (cause) this.cause = cause;
+  }
+}
+
+function isDevEnv() {
+  const env = typeof process !== "undefined" ? process.env.NODE_ENV : "";
+  return env === "development";
+}
+
+function splitRef(ref) {
+  assertNonEmptyString(ref, "ref");
+  const idx = ref.indexOf(":");
+  if (idx === -1) {
+    return { provider: "opaque", key: ref.trim() };
+  }
+  const provider = ref.slice(0, idx).trim().toLowerCase();
+  const key = ref.slice(idx + 1);
+  if (!provider) throw new SecretRefError(SECRET_ERROR_CODE.REF_INVALID, "secret ref is missing provider", { ref });
+  if (!key || String(key).trim() === "") throw new SecretRefError(SECRET_ERROR_CODE.REF_INVALID, "secret ref is missing key", { ref, provider });
+  return { provider, key: String(key) };
+}
+
+function normalizeSecretValue(value) {
+  const v = typeof value === "string" ? value : Buffer.isBuffer(value) ? value.toString("utf8") : String(value ?? "");
+  // K8s secrets commonly have a trailing newline.
+  return v.replace(/\r?\n$/, "");
+}
+
+export function createSecretsProvider({
+  allowEnv = typeof process !== "undefined" && (process.env.PROXY_ENABLE_ENV_SECRETS === "1" || isDevEnv()),
+  cacheTtlSeconds = typeof process !== "undefined" ? parseTtlSeconds(process.env.PROXY_SECRETS_CACHE_TTL_SECONDS, { fallbackSeconds: 30 }) : 30
+} = {}) {
+  if (!Number.isSafeInteger(cacheTtlSeconds) || cacheTtlSeconds <= 0) throw new TypeError("cacheTtlSeconds must be a positive integer");
+
+  const cache = new Map(); // `${tenantId}\n${ref}` -> { expiresAtMs, secret }
+
+  async function readEnvSecret({ tenantId, ref, key }) {
+    if (!allowEnv) throw new SecretRefError(SECRET_ERROR_CODE.PROVIDER_FORBIDDEN, "env secrets provider is disabled", { provider: "env", tenantId, ref });
+    const name = String(key).trim();
+    if (!/^[A-Z0-9_]+$/.test(name)) {
+      throw new SecretRefError(SECRET_ERROR_CODE.REF_INVALID, "env secret ref must be env:NAME", { provider: "env", tenantId, ref });
+    }
+    const value = typeof process !== "undefined" ? process.env[name] : undefined;
+    if (typeof value !== "string" || value.trim() === "") {
+      throw new SecretRefError(SECRET_ERROR_CODE.NOT_FOUND, "secret not found", { provider: "env", tenantId, ref });
+    }
+    return { type: "string", value: normalizeSecretValue(value), metadata: { provider: "env", name } };
+  }
+
+  async function readFileSecret({ tenantId, ref, key }) {
+    const p = String(key);
+    // Require an absolute path so refs are unambiguous in production.
+    if (!p.startsWith("/")) throw new SecretRefError(SECRET_ERROR_CODE.REF_INVALID, "file secret ref must be file:/absolute/path", { provider: "file", tenantId, ref });
+    let data;
+    try {
+      data = await fs.readFile(p, "utf8");
+    } catch (err) {
+      if (err?.code === "ENOENT") throw new SecretRefError(SECRET_ERROR_CODE.NOT_FOUND, "secret not found", { provider: "file", tenantId, ref, cause: err });
+      throw new SecretRefError(SECRET_ERROR_CODE.READ_FAILED, "failed to read secret", { provider: "file", tenantId, ref, cause: err });
+    }
+    const value = normalizeSecretValue(data);
+    if (!value || value.trim() === "") throw new SecretRefError(SECRET_ERROR_CODE.NOT_FOUND, "secret is empty", { provider: "file", tenantId, ref });
+    return { type: "string", value, metadata: { provider: "file", path: p } };
+  }
+
+  async function readVaultSecret({ tenantId, ref }) {
+    throw new SecretRefError(SECRET_ERROR_CODE.PROVIDER_UNAVAILABLE, "vault secrets provider is not configured", { provider: "vault", tenantId, ref });
+  }
+
+  async function getSecret({ tenantId, ref }) {
+    tenantId = normalizeTenantId(tenantId);
+    assertNonEmptyString(ref, "ref");
+    const key = `${tenantId}\n${ref}`;
+    const nowMs = Date.now();
+    const cached = cache.get(key) ?? null;
+    if (cached && Number.isFinite(cached.expiresAtMs) && cached.expiresAtMs > nowMs) return cached.secret;
+
+    const { provider, key: providerKey } = splitRef(ref);
+
+    let secret;
+    if (provider === "env") {
+      secret = await readEnvSecret({ tenantId, ref, key: providerKey });
+    } else if (provider === "file") {
+      secret = await readFileSecret({ tenantId, ref, key: providerKey });
+    } else if (provider === "vault") {
+      secret = await readVaultSecret({ tenantId, ref });
+    } else {
+      throw new SecretRefError(SECRET_ERROR_CODE.REF_INVALID, "unsupported secret provider", { provider, tenantId, ref });
+    }
+
+    cache.set(key, { expiresAtMs: nowMs + cacheTtlSeconds * 1000, secret });
+    return secret;
+  }
+
+  return Object.freeze({ getSecret });
+}
+

package/src/core/settlement-adjustment.js

@@ -0,0 +1,151 @@
+import { canonicalJsonStringify, normalizeForCanonicalJson } from "./canonical-json.js";
+import { sha256Hex } from "./crypto.js";
+
+export const SETTLEMENT_ADJUSTMENT_SCHEMA_VERSION = "SettlementAdjustment.v1";
+
+export const SETTLEMENT_ADJUSTMENT_KIND = Object.freeze({
+  HOLDBACK_RELEASE: "holdback_release",
+  HOLDBACK_REFUND: "holdback_refund"
+});
+
+function assertPlainObject(value, name) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${name} must be an object`);
+  if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+    throw new TypeError(`${name} must be a plain object`);
+  }
+}
+
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+function assertIsoDate(value, name) {
+  assertNonEmptyString(value, name);
+  if (!Number.isFinite(Date.parse(value))) throw new TypeError(`${name} must be an ISO date string`);
+}
+
+function normalizeId(value, name, { min = 1, max = 200 } = {}) {
+  assertNonEmptyString(value, name);
+  const out = String(value).trim();
+  if (out.length < min || out.length > max) throw new TypeError(`${name} must be length ${min}..${max}`);
+  if (!/^[A-Za-z0-9:_-]+$/.test(out)) throw new TypeError(`${name} must match ^[A-Za-z0-9:_-]+$`);
+  return out;
+}
+
+function normalizeHexHash(value, name) {
+  assertNonEmptyString(value, name);
+  const out = String(value).trim().toLowerCase();
+  if (!/^[0-9a-f]{64}$/.test(out)) throw new TypeError(`${name} must be a 64-hex sha256`);
+  return out;
+}
+
+function normalizeCurrency(value, name) {
+  const raw = typeof value === "string" && value.trim() !== "" ? value : "USD";
+  const out = raw.trim().toUpperCase();
+  if (!/^[A-Z][A-Z0-9_]{2,11}$/.test(out)) throw new TypeError(`${name} must match ^[A-Z][A-Z0-9_]{2,11}$`);
+  return out;
+}
+
+function assertNonNegativeSafeInt(value, name) {
+  const n = Number(value);
+  if (!Number.isSafeInteger(n) || n < 0) throw new TypeError(`${name} must be a non-negative safe integer`);
+  return n;
+}
+
+function normalizeKind(value, name) {
+  const normalized = typeof value === "string" ? value.trim().toLowerCase() : "";
+  if (!Object.values(SETTLEMENT_ADJUSTMENT_KIND).includes(normalized)) {
+    throw new TypeError(`${name} must be one of: ${Object.values(SETTLEMENT_ADJUSTMENT_KIND).join("|")}`);
+  }
+  return normalized;
+}
+
+export function computeSettlementAdjustmentHashV1(adjustmentCore) {
+  assertPlainObject(adjustmentCore, "adjustmentCore");
+  const copy = { ...adjustmentCore };
+  delete copy.adjustmentHash;
+  delete copy.metadata;
+  const normalized = normalizeForCanonicalJson(copy, { path: "$" });
+  return sha256Hex(canonicalJsonStringify(normalized));
+}
+
+export function buildSettlementAdjustmentV1({
+  adjustmentId,
+  tenantId,
+  agreementHash,
+  receiptHash,
+  holdHash,
+  kind,
+  amountCents,
+  currency,
+  createdAt,
+  verdictRef = null,
+  metadata = null
+} = {}) {
+  const at = createdAt ?? new Date().toISOString();
+  assertIsoDate(at, "createdAt");
+
+  const normalizedVerdictRef =
+    verdictRef && typeof verdictRef === "object" && !Array.isArray(verdictRef)
+      ? normalizeForCanonicalJson(
+          {
+            caseId: verdictRef.caseId ? String(verdictRef.caseId) : null,
+            verdictHash: verdictRef.verdictHash ? String(verdictRef.verdictHash).toLowerCase() : null
+          },
+          { path: "$" }
+        )
+      : null;
+  if (normalizedVerdictRef) {
+    if (normalizedVerdictRef.caseId === null || normalizedVerdictRef.caseId === "") throw new TypeError("verdictRef.caseId is required");
+    if (!/^[0-9a-f]{64}$/.test(normalizedVerdictRef.verdictHash ?? "")) throw new TypeError("verdictRef.verdictHash must be a 64-hex sha256");
+  }
+
+  const base = {
+    schemaVersion: SETTLEMENT_ADJUSTMENT_SCHEMA_VERSION,
+    adjustmentId: normalizeId(adjustmentId, "adjustmentId", { min: 3, max: 200 }),
+    tenantId: normalizeId(tenantId, "tenantId", { min: 1, max: 128 }),
+    agreementHash: normalizeHexHash(agreementHash, "agreementHash"),
+    receiptHash: normalizeHexHash(receiptHash, "receiptHash"),
+    holdHash: normalizeHexHash(holdHash, "holdHash"),
+    kind: normalizeKind(kind, "kind"),
+    amountCents: assertNonNegativeSafeInt(amountCents, "amountCents"),
+    currency: normalizeCurrency(currency, "currency"),
+    createdAt: at
+  };
+  if (normalizedVerdictRef) base.verdictRef = normalizedVerdictRef;
+  const normalized = normalizeForCanonicalJson(base, { path: "$" });
+  const adjustmentHash = computeSettlementAdjustmentHashV1(normalized);
+  const out = {
+    ...normalized,
+    adjustmentHash
+  };
+  if (metadata && typeof metadata === "object" && !Array.isArray(metadata)) {
+    out.metadata = normalizeForCanonicalJson(metadata, { path: "$" });
+  }
+  return normalizeForCanonicalJson(out, { path: "$" });
+}
+
+export function validateSettlementAdjustmentV1(adjustment) {
+  assertPlainObject(adjustment, "adjustment");
+  if (adjustment.schemaVersion !== SETTLEMENT_ADJUSTMENT_SCHEMA_VERSION) {
+    throw new TypeError(`adjustment.schemaVersion must be ${SETTLEMENT_ADJUSTMENT_SCHEMA_VERSION}`);
+  }
+  normalizeId(adjustment.adjustmentId, "adjustment.adjustmentId", { min: 3, max: 200 });
+  normalizeId(adjustment.tenantId, "adjustment.tenantId", { min: 1, max: 128 });
+  normalizeHexHash(adjustment.agreementHash, "adjustment.agreementHash");
+  normalizeHexHash(adjustment.receiptHash, "adjustment.receiptHash");
+  normalizeHexHash(adjustment.holdHash, "adjustment.holdHash");
+  normalizeKind(adjustment.kind, "adjustment.kind");
+  assertNonNegativeSafeInt(adjustment.amountCents, "adjustment.amountCents");
+  normalizeCurrency(adjustment.currency, "adjustment.currency");
+  if (adjustment.verdictRef !== null && adjustment.verdictRef !== undefined) {
+    assertPlainObject(adjustment.verdictRef, "adjustment.verdictRef");
+    assertNonEmptyString(adjustment.verdictRef.caseId, "adjustment.verdictRef.caseId");
+    normalizeHexHash(adjustment.verdictRef.verdictHash, "adjustment.verdictRef.verdictHash");
+  }
+  assertIsoDate(adjustment.createdAt, "adjustment.createdAt");
+  const hash = normalizeHexHash(adjustment.adjustmentHash, "adjustment.adjustmentHash");
+  const computed = computeSettlementAdjustmentHashV1(adjustment);
+  if (computed !== hash) throw new TypeError("adjustmentHash mismatch");
+  return true;
+}