release-skill 0.1.1

package/src/core/blackbox-hard-gates.mjs

@@ -0,0 +1,142 @@
+/**
+ * README 黑盒测试独立硬门纯函数。
+ *
+ * 供 runner（run-readme-blackbox.mjs）和单测使用，用于独立验证
+ * maintainer persona 产生的 workspace 产物，不信任 persona 自报布尔值。
+ *
+ * @module blackbox-hard-gates
+ */
+
+import { validateVersionConsistency } from './version-consistency.mjs';
+import { validatePlanActionCompleteness } from './plan.mjs';
+
+/**
+ * 验证 project.yaml 配置中的 release unit 属性。
+ *
+ * @param {object} config - 已解析的 project.yaml 对象
+ * @param {object} expectations
+ * @param {string} expectations.expectedUnitId - 预期 unit id（如 'my-plugin'）
+ * @param {string} expectations.expectedSource - 预期 source 路径（如 'packages/my-plugin'）
+ * @param {string} expectations.expectedVersionSource - 预期 version.source（如 'package.json'）
+ * @param {string} [expectations.expectedPublicRepo] - 预期 publicRepo
+ * @param {string} [expectations.expectedTagTemplate] - 预期 tagTemplate
+ * @param {string[]} [expectations.expectedDistributionTypes] - 预期 distribution types
+ * @returns {{ passed: boolean, failures: string[] }}
+ */
+export function verifyMaintainerConfig(config, expectations) {
+  const failures = [];
+  const {
+    expectedUnitId,
+    expectedSource,
+    expectedVersionSource,
+    expectedPublicRepo,
+    expectedTagTemplate,
+    expectedDistributionTypes,
+  } = expectations;
+
+  if (!config || typeof config !== 'object') {
+    return { passed: false, failures: ['config is null or not an object'] };
+  }
+
+  const units = config.releaseUnits;
+  if (!Array.isArray(units) || units.length === 0) {
+    failures.push('releaseUnits is missing or empty');
+    return { passed: false, failures };
+  }
+
+  const unit = units.find(u => u.id === expectedUnitId);
+  if (!unit) {
+    failures.push(`unit "${expectedUnitId}" not found in releaseUnits`);
+  } else {
+    if (unit.source !== expectedSource) {
+      failures.push(`unit "${expectedUnitId}" source is ${JSON.stringify(unit.source)}, expected ${JSON.stringify(expectedSource)}`);
+    }
+    const versionSource = unit.version?.source;
+    if (versionSource !== expectedVersionSource) {
+      failures.push(`unit "${expectedUnitId}" version.source is ${JSON.stringify(versionSource)}, expected ${JSON.stringify(expectedVersionSource)}`);
+    }
+    // publicRepo
+    if (expectedPublicRepo && unit.publicRepo !== expectedPublicRepo) {
+      failures.push(`unit "${expectedUnitId}" publicRepo is ${JSON.stringify(unit.publicRepo)}, expected ${JSON.stringify(expectedPublicRepo)}`);
+    }
+    // tagTemplate
+    if (expectedTagTemplate && unit.version?.tagTemplate !== expectedTagTemplate) {
+      failures.push(`unit "${expectedUnitId}" version.tagTemplate is ${JSON.stringify(unit.version?.tagTemplate)}, expected ${JSON.stringify(expectedTagTemplate)}`);
+    }
+    // distributions
+    if (expectedDistributionTypes) {
+      const actualTypes = (unit.distributions ?? []).map(d => d.type).sort();
+      const sorted = [...expectedDistributionTypes].sort();
+      if (JSON.stringify(actualTypes) !== JSON.stringify(sorted)) {
+        failures.push(`unit "${expectedUnitId}" distribution types are ${JSON.stringify(actualTypes)}, expected ${JSON.stringify(sorted)}`);
+      }
+    }
+  }
+
+  return { passed: failures.length === 0, failures };
+}
+
+/**
+ * 验证冻结发布计划的一致性。
+ *
+ * 两个独立门：
+ * 1. 版本/tag 精确校验（validateVersionConsistency）
+ * 2. 动作完整性校验（validatePlanActionCompleteness）
+ *
+ * @param {object} plan - 已解析的 release-plan.json 对象
+ * @param {object} expectations
+ * @param {string} expectations.expectedUnitId - 预期 unit id
+ * @param {string} expectations.expectedVersion - 预期版本号
+ * @returns {{ passed: boolean, failures: string[], details: object }}
+ */
+export function verifyPlanConsistency(plan, expectations) {
+  const { expectedUnitId, expectedVersion } = expectations;
+
+  // Gate 1: Version/tag exact consistency
+  const versionResult = validateVersionConsistency(plan, expectedVersion, {
+    expectedUnitId,
+  });
+
+  // Gate 2: Action completeness (every unit has its required actions)
+  const actionResult = validatePlanActionCompleteness(plan);
+
+  const allFailures = [
+    ...versionResult.details.failures,
+    ...actionResult.details.failures,
+  ];
+
+  return {
+    passed: versionResult.passed && actionResult.passed,
+    failures: allFailures,
+    details: {
+      unitCount: versionResult.details.unitCount,
+      actionCount: versionResult.details.actionCount,
+      expectedActionCount: actionResult.details.expectedCount,
+      actualActionCount: actionResult.details.actualCount,
+      versionGatePassed: versionResult.passed,
+      actionCompletenessGatePassed: actionResult.passed,
+    },
+  };
+}
+
+/**
+ * 计算 README 黑盒测试总体结论。
+ *
+ * 每个 persona 必须同时满足 success === true 和 verdict === 'PASS'，
+ * 总体才为 PASS。persona 自报 verdict=PASS 但 success=false 时，
+ * 总体必须 FAIL。
+ *
+ * @param {Array<{ success: boolean, verdict: string }>} personaResults
+ * @returns {{ overall_verdict: 'PASS'|'FAIL', pass_count: number, fail_count: number }}
+ */
+export function computeOverallVerdict(personaResults) {
+  const passCount = personaResults.filter(
+    r => r.success === true && r.verdict === 'PASS',
+  ).length;
+  const failCount = personaResults.length - passCount;
+  return {
+    overall_verdict: failCount === 0 && personaResults.length > 0 ? 'PASS' : 'FAIL',
+    pass_count: passCount,
+    fail_count: failCount,
+  };
+}

package/src/core/config.mjs

@@ -0,0 +1,448 @@
+/**
+ * Secure project configuration loader for the release-skill system.
+ *
+ * Design constraints:
+ * - Reads `.release-skill/project.yaml` by default (path overridable).
+ * - YAML parsing rejects aliases (including merge keys) and duplicate keys.
+ * - Parsed content is validated against the release-project JSON Schema
+ *   loaded from the formal `schemas/release-project.schema.json` file
+ *   (single source of truth).
+ * - A deterministic configDigest is computed via canonicalJson + sha256Hex.
+ * - Paths are validated to remain within the project root.
+ * - `unit.source`, `publicFiles.from/to`, and `requiredPublicFiles` are
+ *   validated through the shared `canonicalPublicPath` helper.
+ * - Target collisions use the shared `publicPathCollisionKey` helper.
+ *
+ * @module config
+ */
+
+import { readFile } from 'node:fs/promises';
+import { resolve, isAbsolute, relative, normalize, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import YAML, { Alias } from 'yaml';
+import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
+import { canonicalJson, sha256Hex } from './digest.mjs';
+import { ReleaseError, CONFIG_INVALID } from './errors.mjs';
+import { canonicalPublicPath, publicPathCollisionKey } from '../snapshot/public-path.mjs';
+import { isReservedReleaseControlPath } from './baseline.mjs';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Default configuration file path, relative to the project root. */
+const DEFAULT_CONFIG_REL = '.release-skill/project.yaml';
+
+// ---------------------------------------------------------------------------
+// Load the formal release-project JSON Schema (single source of truth)
+// ---------------------------------------------------------------------------
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const FORMAL_SCHEMA_PATH = resolve(__dirname, '..', '..', 'schemas', 'release-project.schema.json');
+
+let RELEASE_PROJECT_SCHEMA;
+try {
+  const schemaRaw = await readFile(FORMAL_SCHEMA_PATH, 'utf8');
+  RELEASE_PROJECT_SCHEMA = JSON.parse(schemaRaw);
+} catch (err) {
+  // Fail closed: if the formal schema cannot be loaded, refuse to operate.
+  throw new ReleaseError(
+    CONFIG_INVALID,
+    `cannot load formal release-project schema: ${err.message}`,
+    { schemaPath: FORMAL_SCHEMA_PATH, cause: err.code },
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Schema validator (compiled once, reused across calls)
+// ---------------------------------------------------------------------------
+
+const ajv = new Ajv({ allErrors: true, strict: false });
+addFormats(ajv);
+const validateConfig = ajv.compile(RELEASE_PROJECT_SCHEMA);
+
+// ---------------------------------------------------------------------------
+// YAML safety checks
+// ---------------------------------------------------------------------------
+
+/**
+ * Recursively walk a YAML AST node and return true if any Alias node is found.
+ *
+ * An Alias node represents a YAML alias reference (`*name`) or a merge key
+ * (`<<: *name`). Both are rejected for security and determinism reasons.
+ *
+ * @param {import('yaml').Node | null | undefined} node
+ * @returns {boolean}
+ */
+function containsAlias(node) {
+  if (!node || typeof node !== 'object') {
+    return false;
+  }
+
+  // Direct alias node (from the yaml library's Alias class)
+  if (node instanceof Alias) {
+    return true;
+  }
+
+  // YAMLMap or YAMLSeq: walk children
+  if (node.items && Array.isArray(node.items)) {
+    for (const item of node.items) {
+      // Pair (map entry) - check key and value
+      if (item.key !== undefined && containsAlias(item.key)) {
+        return true;
+      }
+      if (item.value !== undefined && containsAlias(item.value)) {
+        return true;
+      }
+      // Bare node in a sequence
+      if (item.key === undefined && containsAlias(item)) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Path validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve and validate a configuration file path.
+ *
+ * The resolved path must be within (or equal to) the project root. Both
+ * absolute and relative configPath values are accepted; if relative, they
+ * are resolved against root.
+ *
+ * @param {string} root - Absolute project root path.
+ * @param {string} configPath - Absolute or relative path to the config file.
+ * @returns {string} The resolved, validated absolute path.
+ * @throws {ReleaseError} CONFIG_INVALID if the path escapes root.
+ */
+function resolveConfigPath(root, configPath) {
+  const rootNorm = normalize(root);
+
+  // Resolve configPath against root if relative
+  const resolved = isAbsolute(configPath)
+    ? normalize(configPath)
+    : resolve(rootNorm, configPath);
+
+  // Ensure resolved path is inside root
+  const rel = relative(rootNorm, resolved);
+  if (rel.startsWith('..') || rel === '..' || isAbsolute(rel)) {
+    throw new ReleaseError(
+      CONFIG_INVALID,
+      `config path "${configPath}" resolves outside project root "${root}"`,
+      { configPath, root, resolved },
+    );
+  }
+
+  return resolved;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Load, parse, validate, and digest a project configuration file.
+ *
+ * Steps:
+ * 1. Resolve and validate the config file path against root.
+ * 2. Read the file content as UTF-8.
+ * 3. Parse as YAML using `parseDocument` to access the AST.
+ * 4. Reject YAML aliases (including merge keys) by walking the AST.
+ * 5. Reject duplicate keys via the document's error list.
+ * 6. Extract the parsed JavaScript value and validate against the schema.
+ * 7. Validate paths using shared canonicalPublicPath helper.
+ * 8. Compile forbiddenContentPatterns (fail closed on invalid regex).
+ * 9. Compute a deterministic configDigest from the canonical JSON.
+ *
+ * @param {Object} options
+ * @param {string} options.root - Absolute path to the project root directory.
+ * @param {string} [options.configPath] - Path to the config file. If relative,
+ *   resolved against root. Defaults to `.release-skill/project.yaml`.
+ *
+ * @returns {Promise<{ config: object, configPath: string, configDigest: string }>}
+ *
+ * @throws {ReleaseError} CONFIG_INVALID on any validation failure, including:
+ *   - File not found or unreadable
+ *   - YAML syntax errors
+ *   - YAML aliases or merge keys detected
+ *   - Duplicate YAML keys
+ *   - Schema validation failure
+ *   - Path escaping project root
+ *   - Invalid path characters (backslash, NUL, traversal)
+ *   - Target collisions (exact, case-fold, NFC)
+ *   - Invalid regex in forbiddenContentPatterns
+ */
+export async function loadProjectConfig({ root, configPath } = {}) {
+  // --- Validate root ---
+  if (!root || typeof root !== 'string') {
+    throw new ReleaseError(CONFIG_INVALID, 'root must be a non-empty string');
+  }
+
+  // --- Resolve config path ---
+  const effectivePath = configPath ?? DEFAULT_CONFIG_REL;
+  const absConfigPath = resolveConfigPath(root, effectivePath);
+
+  // --- Read file ---
+  let content;
+  try {
+    content = await readFile(absConfigPath, 'utf8');
+  } catch (err) {
+    throw new ReleaseError(
+      CONFIG_INVALID,
+      `cannot read config file: ${err.message}`,
+      { configPath: absConfigPath, cause: err.code },
+    );
+  }
+
+  // --- Parse YAML with AST access ---
+  let doc;
+  try {
+    doc = YAML.parseDocument(content);
+  } catch (err) {
+    throw new ReleaseError(
+      CONFIG_INVALID,
+      `YAML parse error: ${err.message}`,
+      { configPath: absConfigPath },
+    );
+  }
+
+  // --- Reject YAML aliases (including merge keys) ---
+  if (containsAlias(doc.contents)) {
+    throw new ReleaseError(
+      CONFIG_INVALID,
+      'YAML aliases and merge keys are not allowed in project configuration',
+      { configPath: absConfigPath },
+    );
+  }
+
+  // --- Reject duplicate keys ---
+  const dupKeyErrors = doc.errors.filter(
+    (e) => e.message && e.message.includes('unique'),
+  );
+  if (dupKeyErrors.length > 0) {
+    throw new ReleaseError(
+      CONFIG_INVALID,
+      `duplicate keys detected in YAML: ${dupKeyErrors[0].message}`,
+      { configPath: absConfigPath, errors: dupKeyErrors.map((e) => e.message) },
+    );
+  }
+
+  // --- Check for any other YAML errors ---
+  if (doc.errors.length > 0) {
+    throw new ReleaseError(
+      CONFIG_INVALID,
+      `YAML parse errors: ${doc.errors.map((e) => e.message).join('; ')}`,
+      { configPath: absConfigPath, errors: doc.errors.map((e) => e.message) },
+    );
+  }
+
+  // --- Extract parsed value ---
+  const config = doc.toJSON();
+  if (config === null || config === undefined || typeof config !== 'object') {
+    throw new ReleaseError(
+      CONFIG_INVALID,
+      'config file must contain a YAML mapping (object)',
+      { configPath: absConfigPath },
+    );
+  }
+
+  // Detect the removed policy-level field before generic schema validation so
+  // existing projects receive one stable, actionable migration diagnostic.
+  if (
+    config.policy &&
+    typeof config.policy === 'object' &&
+    Object.hasOwn(config.policy, 'requiredPublicFiles')
+  ) {
+    throw new ReleaseError(
+      CONFIG_INVALID,
+      'policy.requiredPublicFiles is no longer supported; move it to releaseUnits[].requiredPublicFiles',
+      {
+        field: 'policy.requiredPublicFiles',
+        migrationTarget: 'releaseUnits[].requiredPublicFiles',
+      },
+    );
+  }
+
+  // --- Contextual path prevalidation (BEFORE schema validation) ---
+  // Validates known path fields using the shared canonicalPublicPath helper
+  // to produce rich error details with unitId and field name. Structure
+  // errors (missing fields, wrong types) are left to schema validation.
+  // Contextual prevalidation: confirm releaseUnits is an array; each unit
+  // must be a non-null object before reading properties.
+  if (!Array.isArray(config.releaseUnits)) {
+    // Schema validation will catch this with CONFIG_INVALID.
+    // Skip prevalidation to avoid TypeError.
+  } else {
+  for (const unit of config.releaseUnits) {
+    if (unit === null || unit === undefined || typeof unit !== 'object') continue;
+    if (typeof unit.id !== 'string' || typeof unit.source !== 'string') continue;
+
+    // Validate unit.source (allow standalone `.`)
+    try {
+      canonicalPublicPath(unit.source, { allowDot: true });
+    } catch (err) {
+      throw new ReleaseError(
+        CONFIG_INVALID,
+        `unit "${unit.id}" has invalid source path: ${err.message}`,
+        { unitId: unit.id, source: unit.source, field: 'source' },
+      );
+    }
+
+    // Validate publicFiles[].from and .to
+    if (Array.isArray(unit.publicFiles)) {
+      for (const mapping of unit.publicFiles) {
+        if (typeof mapping === 'object' && mapping !== null) {
+          if (typeof mapping.from === 'string') {
+            try {
+              const canonicalFrom = canonicalPublicPath(mapping.from).path;
+              if (isReservedReleaseControlPath(canonicalFrom)) {
+                throw new Error('release-skill control-plane paths are reserved and cannot be public inputs');
+              }
+            } catch (err) {
+              throw new ReleaseError(
+                CONFIG_INVALID,
+                `unit "${unit.id}" has invalid publicFiles[].from: ${err.message}`,
+                { unitId: unit.id, from: mapping.from, field: 'publicFiles[].from' },
+              );
+            }
+          }
+          if (typeof mapping.to === 'string') {
+            try {
+              canonicalPublicPath(mapping.to);
+            } catch (err) {
+              throw new ReleaseError(
+                CONFIG_INVALID,
+                `unit "${unit.id}" has invalid publicFiles[].to: ${err.message}`,
+                { unitId: unit.id, to: mapping.to, field: 'publicFiles[].to' },
+              );
+            }
+          }
+        }
+      }
+    }
+
+    // Validate requiredPublicFiles
+    if (Array.isArray(unit.requiredPublicFiles)) {
+      for (const req of unit.requiredPublicFiles) {
+        if (typeof req === 'string') {
+          try {
+            canonicalPublicPath(req);
+          } catch (err) {
+            throw new ReleaseError(
+              CONFIG_INVALID,
+              `unit "${unit.id}" has invalid requiredPublicFiles entry: ${err.message}`,
+              { unitId: unit.id, required: req, field: 'requiredPublicFiles' },
+            );
+          }
+        }
+      }
+    }
+  }
+  } // end of contextual prevalidation else block
+
+  // --- Schema validation (using formal JSON schema) ---
+  const valid = validateConfig(config);
+  if (!valid) {
+    const errors = validateConfig.errors ?? [];
+    const summary = errors
+      .map((e) => `${e.instancePath || '/'}: ${e.message}`)
+      .join('; ');
+    throw new ReleaseError(
+      CONFIG_INVALID,
+      `config schema validation failed: ${summary}`,
+      { configPath: absConfigPath, validationErrors: errors },
+    );
+  }
+
+  // --- Compile forbiddenContentPatterns (fail closed on invalid regex) ---
+  const forbiddenContentPatterns = config.policy?.forbiddenContentPatterns ?? [];
+  for (const pattern of forbiddenContentPatterns) {
+    if (typeof pattern !== 'string' || pattern.length === 0) continue;
+    try {
+      new RegExp(pattern);
+    } catch (err) {
+      throw new ReleaseError(
+        CONFIG_INVALID,
+        `invalid regex in forbiddenContentPatterns: "${pattern}": ${err.message}`,
+        { configPath: absConfigPath, pattern, cause: err.message },
+      );
+    }
+  }
+
+  // --- Cross-field validation (cannot be expressed in JSON Schema) ---
+  // JSON Schema validates structure; these checks verify semantic constraints
+  // across fields within each release unit.
+  if (!Array.isArray(config.releaseUnits)) {
+    // Schema validation will catch this with CONFIG_INVALID.
+  } else
+  for (const unit of config.releaseUnits) {
+    if (unit === null || unit === undefined || typeof unit !== 'object') continue;
+    // 1. Validate publicFiles[].to uniqueness using shared collision key
+    const toTargets = unit.publicFiles ?? [];
+    const exactSet = new Set();
+    const collisionKeyMap = new Map();
+    for (const mapping of toTargets) {
+      const to = mapping.to;
+      // Exact duplicate
+      if (exactSet.has(to)) {
+        throw new ReleaseError(
+          CONFIG_INVALID,
+          `unit "${unit.id}" has duplicate publicFiles[].to: "${to}"`,
+          { unitId: unit.id, target: to },
+        );
+      }
+      exactSet.add(to);
+
+      // Collision key: NFC + case-fold (shared helper)
+      const key = publicPathCollisionKey(to);
+      if (collisionKeyMap.has(key)) {
+        const existing = collisionKeyMap.get(key);
+        if (existing !== to) {
+          // Determine collision kind
+          const nfc = to.normalize('NFC');
+          const existingNfc = existing.normalize('NFC');
+          const isNfc = nfc === existingNfc;
+          const isCase = nfc.toLowerCase() === existingNfc.toLowerCase();
+          let kind = 'case+NFC';
+          if (isNfc && !isCase) kind = 'NFC';
+          else if (!isNfc && isCase) kind = 'case-fold';
+
+          throw new ReleaseError(
+            CONFIG_INVALID,
+            `unit "${unit.id}" has ${kind} collision in publicFiles[].to: "${to}" and "${existing}"`,
+            { unitId: unit.id, target: to, existing },
+          );
+        }
+      }
+      collisionKeyMap.set(key, to);
+    }
+
+    // 2. Validate requiredPublicFiles coverage: every required file must
+    //    be exactly covered by some publicFiles[].to.
+    const required = unit.requiredPublicFiles ?? [];
+    const toSet = new Set(toTargets.map((m) => m.to));
+    const uncovered = required.filter((r) => !toSet.has(r));
+    if (uncovered.length > 0) {
+      throw new ReleaseError(
+        CONFIG_INVALID,
+        `unit "${unit.id}" requiredPublicFiles not covered by publicFiles[].to: ${uncovered.join(', ')}`,
+        { unitId: unit.id, uncovered },
+      );
+    }
+  }
+
+  // --- Compute deterministic digest ---
+  const configDigest = sha256Hex(canonicalJson(config));
+
+  return {
+    config,
+    configPath: absConfigPath,
+    configDigest,
+  };
+}

package/src/core/digest.mjs

@@ -0,0 +1,90 @@
+/**
+ * Deterministic canonical JSON serialisation and SHA-256 digest.
+ *
+ * `canonicalJson` recursively sorts object keys (deep-first) while preserving
+ * array element order, then serialises the result as a UTF-8 JSON string.
+ * Two objects with the same logical content but different key insertion order
+ * always produce the identical output.
+ *
+ * `sha256Hex` computes the SHA-256 hash of a UTF-8 string (or Buffer) and
+ * returns the lowercase hex encoding.
+ *
+ * @module digest
+ */
+
+import { createHash } from 'node:crypto';
+
+/**
+ * Recursively sort every object key in depth-first order and serialise as
+ * a deterministic UTF-8 JSON string.
+ *
+ * Rules:
+ * - Object keys are sorted lexicographically (same order as `Array.sort()`).
+ * - Array element order is preserved.
+ * - Primitives (`null`, booleans, numbers, strings) pass through unchanged.
+ * - `undefined` values in objects are omitted (matching `JSON.stringify`).
+ * - `undefined` values inside arrays become `null` (matching `JSON.stringify`).
+ * - `BigInt` values throw (matching `JSON.stringify`).
+ * - `Date` objects are serialised via `.toISOString()` (matching
+ *   `JSON.stringify`).
+ *
+ * @param {*} obj - Any JSON-serialisable value.
+ * @returns {string} A UTF-8 JSON string whose key ordering is deterministic.
+ */
+export function canonicalJson(obj) {
+  return JSON.stringify(canonicalise(obj));
+}
+
+/**
+ * Compute the SHA-256 digest of a UTF-8 string or Buffer.
+ *
+ * @param {string | Buffer} input - The data to hash.
+ * @returns {string} Lowercase hexadecimal SHA-256 digest (64 hex chars).
+ */
+export function sha256Hex(input) {
+  return createHash('sha256').update(input).digest('hex');
+}
+
+// ---- internal helpers (not exported) ----
+
+/**
+ * Deep-clone a value while sorting all object keys lexicographically.
+ *
+ * @param {*} value
+ * @returns {*}
+ */
+function canonicalise(value) {
+  if (value === null || value === undefined) {
+    return value;
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item) => canonicalise(item));
+  }
+
+  // Date gets its own branch so we can call toISOString() before the
+  // typeof === 'object' check swallows it.
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+
+  // Buffer gets its own branch: toJSON() returns {type:'Buffer', data:[...]}
+  // which matches JSON.stringify and survives a JSON roundtrip.
+  if (Buffer.isBuffer(value)) {
+    return canonicalise(value.toJSON());
+  }
+
+  if (typeof value === 'object') {
+    const sorted = {};
+    for (const key of Object.keys(value).sort()) {
+      const v = value[key];
+      // Skip undefined object properties (mirrors JSON.stringify behaviour).
+      if (v === undefined) continue;
+      sorted[key] = canonicalise(v);
+    }
+    return sorted;
+  }
+
+  // Primitives: string, number, boolean, null.
+  return value;
+}