@boyingliu01/xp-gate 0.31.1 → 0.31.3

package/hooks/lib/validate-code-walkthrough.cjs

@@ -2,10 +2,21 @@
 'use strict';
 
 const fs = require('node:fs');
+const path = require('node:path');
 
 const REQUIRED_ROLES = ['architecture', 'technical', 'feasibility'];
 const VALIDITY_MS = 60 * 60 * 1000;
 
+/**
+ * Project-level Delphi seat configuration.
+ *
+ * Present => evidence is BOUND to it (#574): each expert's `requested_model`
+ * must be exactly the seat the config assigns to that expert's role.
+ * Absent  => evidence stays unbound (the #423 behaviour), so projects that
+ * review through another platform's channel are unaffected.
+ */
+const DELPHI_CONFIG_FILE = '.delphi-config.json';
+
 /**
  * Allowed provenance values for an expert record.
  *
@@ -58,7 +69,126 @@ function parseTimestamp(value, field) {
   return date.getTime();
 }
 
-function validateExpert(expert, index, roles, models, resolvedModels) {
+/**
+ * Record one seat into `seats` if the entry carries a usable model id.
+ * Shared by both `experts` shapes so the acceptance rule lives in exactly one
+ * place (#599: the two branches were byte-for-byte copies, which is what pushed
+ * this function over the complexity block threshold).
+ *
+ * @param {Map<string, string>} seats role -> trimmed model id, mutated
+ * @param {string} role configured role name
+ * @param {unknown} entry candidate expert record
+ */
+function addSeat(seats, role, entry) {
+  if (!isPlainObject(entry)) return;
+  const model = entry.model ?? entry.requested_model;
+  if (typeof model === 'string' && model.trim() !== '') seats.set(role, model.trim());
+}
+
+/**
+ * Normalise the two `experts` shapes `.delphi-config.json` appears in — an
+ * object keyed by role (what xp-gate writes) and an array carrying `role` —
+ * into a plain role -> model map. Mirrors `normalizeExperts()` in
+ * `plugins/dsh/src/delphi-config.ts` and `iter_seats()` in
+ * `scripts/check_delphi_local_models.py`: one config shape, one reading.
+ *
+ * @param {unknown} experts raw `experts` value
+ * @returns {Map<string, string>} role -> trimmed model id
+ */
+function seatsFromExperts(experts) {
+  const seats = new Map();
+  if (Array.isArray(experts)) {
+    for (const entry of experts) {
+      if (isPlainObject(entry) && typeof entry.role === 'string') {
+        addSeat(seats, entry.role, entry);
+      }
+    }
+  } else if (isPlainObject(experts)) {
+    for (const [role, entry] of Object.entries(experts)) {
+      addSeat(seats, role, entry);
+    }
+  }
+  return seats;
+}
+
+/**
+ * Resolve the binding seats from a parsed `.delphi-config.json`.
+ *
+ * Only the ACTIVE profile binds, exactly like every other Delphi loader. A
+ * config that names profiles but leaves no resolvable active one is rejected
+ * rather than ignored: silently falling back to "unbound" would turn a broken
+ * config into a bypass.
+ *
+ * @param {unknown} config parsed config document
+ * @returns {Map<string, string>} role -> model id that evidence must match
+ */
+function resolveBindingSeats(config) {
+  if (!isPlainObject(config)) fail(`${DELPHI_CONFIG_FILE} must contain a JSON object.`);
+
+  const profiles = config.profiles;
+  if (!isPlainObject(profiles) || Object.keys(profiles).length === 0) {
+    // Legacy/flat shape: experts live at the top level.
+    return seatsFromExperts(config.experts);
+  }
+
+  const active = config.active_profile;
+  if (typeof active !== 'string' || !isPlainObject(profiles[active])) {
+    const available = Object.keys(profiles).join(', ');
+    fail(
+      `${DELPHI_CONFIG_FILE} has no resolvable active_profile (active_profile=${JSON.stringify(active)}; `
+        + `available: ${available}). Set one so the gate knows which seats bind.`
+    );
+  }
+  return seatsFromExperts(profiles[active].experts);
+}
+
+/**
+ * Read the binding seats for the project rooted at `projectRoot`.
+ *
+ * The root is passed EXPLICITLY by the caller, never derived from
+ * `process.cwd()`. Deriving it from cwd made the binding depend on where the
+ * validator was launched from: running the test suite from inside xp-gate
+ * itself picked up xp-gate's own `.delphi-config.json` and re-bound every
+ * fixture to xp-gate's seats. The gate's subject is the repository being
+ * pushed, so that is what must be named.
+ *
+ * @param {string} projectRoot repository root whose config binds the evidence
+ * @returns {Map<string, string> | null} seats, or null when no config exists
+ */
+function loadBindingSeats(projectRoot) {
+  const configPath = path.join(projectRoot, DELPHI_CONFIG_FILE);
+  let raw;
+  try {
+    raw = fs.readFileSync(configPath, 'utf8');
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return null;
+    fail(`cannot read ${DELPHI_CONFIG_FILE}: ${error && error.message ? error.message : String(error)}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    fail(`${DELPHI_CONFIG_FILE} is not valid JSON: ${error.message}`);
+  }
+  const seats = resolveBindingSeats(parsed);
+  for (const role of REQUIRED_ROLES) {
+    if (!seats.has(role)) {
+      fail(`${DELPHI_CONFIG_FILE} declares no seat for the ${role} role; all three roles must be configured.`);
+    }
+  }
+  return seats;
+}
+
+/**
+ * Validate an expert's identity fields: shape, role, approval status, and
+ * channel provenance. Split out of `validateExpert`, which exceeded the
+ * complexity block threshold (#599).
+ *
+ * @param {object} expert expert record
+ * @param {number} index position in the experts array
+ * @param {Set<string>} roles roles seen so far; the role is added
+ */
+function validateExpertIdentity(expert, index, roles) {
   if (!isPlainObject(expert)) fail(`experts[${index}] must be a plain object.`);
   if (!REQUIRED_ROLES.includes(expert.role)) fail(`experts[${index}].role is invalid.`);
   if (roles.has(expert.role)) fail(`expert role ${expert.role} is duplicated.`);
@@ -80,14 +210,33 @@ function validateExpert(expert, index, roles, models, resolvedModels) {
       `expert ${expert.role} channel must be one of: ${VALID_CHANNELS.join(', ')}.`
     );
   }
+}
 
-  // requested_model is compared EXACTLY (after trimming); resolved_model below is
-  // compared case-INSENSITIVELY. The asymmetry is intentional, not an oversight:
-  // a requested ID is a case-sensitive gateway identifier and AGENTS.md requires
-  // "three distinct trimmed requested model IDs", whereas resolved_model answers
-  // "did these actually run on one model?" -- and gateways do report the same model
-  // with different casing per call, which is how #423 slipped through. Pinned by
-  // scripts/__tests__/gate-mw-provenance.test.cjs (AC-423-08).
+/**
+ * Validate the requested model: non-empty, distinct across experts, and — when
+ * the project binds seats — exactly the model configured for this role.
+ *
+ * requested_model is compared EXACTLY (after trimming) while resolved_model is
+ * compared case-INSENSITIVELY. The asymmetry is intentional, not an oversight: a
+ * requested ID is a case-sensitive gateway identifier and AGENTS.md requires
+ * "three distinct trimmed requested model IDs", whereas resolved_model answers
+ * "did these actually run on one model?" -- and gateways do report the same model
+ * with different casing per call, which is how #423 slipped through. Pinned by
+ * scripts/__tests__/gate-mw-provenance.test.cjs (AC-423-08).
+ *
+ * #574: when the project ships a `.delphi-config.json`, the seat this role was
+ * configured with is the ONLY model allowed to report for it. Distinctness alone
+ * was satisfiable by any three of the gateway's ~138 models -- measured
+ * 2026-10-22, a walkthrough ran on s-deepseek-v4.1-flash / g-deepseek-v4-pro /
+ * doubao-seed-2.0-pro while the config named three local-* seats, and this
+ * validator passed it. Membership is checked per ROLE (not as a set) so a swapped
+ * pair is rejected too: the role attribution would otherwise be a lie.
+ *
+ * @param {object} expert expert record
+ * @param {Set<string>} models requested models seen so far; this one is added
+ * @param {Map<string, string>|null} bindingSeats configured seats, or null
+ */
+function validateRequestedModel(expert, models, bindingSeats) {
   if (typeof expert.requested_model !== 'string' || expert.requested_model.trim() === '') {
     fail(`expert ${expert.role} requested_model must be non-empty.`);
   }
@@ -95,10 +244,28 @@ function validateExpert(expert, index, roles, models, resolvedModels) {
   if (models.has(model)) fail(`requested_model ${model} is duplicated.`);
   models.add(model);
 
-  // `resolved_model` must be a real, DISTINCT model. Previously null was allowed,
-  // so an expert that never resolved a model still counted as successful; and
-  // nothing compared resolved models, so all three could report the same one
-  // while `requested_model` differed.
+  if (bindingSeats !== null) {
+    const configured = bindingSeats.get(expert.role);
+    if (model !== configured) {
+      fail(
+        `expert ${expert.role} requested_model ${model} does not match the configured seat `
+          + `${configured} from ${DELPHI_CONFIG_FILE}.`
+      );
+    }
+  }
+}
+
+/**
+ * Validate the resolved model: a non-empty string, distinct ignoring case.
+ *
+ * Previously null was allowed, so an expert that never resolved a model still
+ * counted as successful; and nothing compared resolved models, so all three could
+ * report the same one while `requested_model` differed.
+ *
+ * @param {object} expert expert record
+ * @param {Set<string>} resolvedModels resolved models seen so far; added here
+ */
+function validateResolvedModel(expert, resolvedModels) {
   if (typeof expert.resolved_model !== 'string' || expert.resolved_model.trim() === '') {
     fail(`expert ${expert.role} resolved_model must be a non-empty string.`);
   }
@@ -109,7 +276,13 @@ function validateExpert(expert, index, roles, models, resolvedModels) {
   resolvedModels.add(resolved);
 }
 
-function validateEvidence(evidence, expectedCommit, expectedBranch, now) {
+function validateExpert(expert, index, roles, models, resolvedModels, bindingSeats) {
+  validateExpertIdentity(expert, index, roles);
+  validateRequestedModel(expert, models, bindingSeats);
+  validateResolvedModel(expert, resolvedModels);
+}
+
+function validateEvidence(evidence, expectedCommit, expectedBranch, now, bindingSeats) {
   if (!isPlainObject(evidence)) fail('top level must be a plain object.');
   if (evidence.commit !== expectedCommit) fail('commit does not match HEAD.');
   if (evidence.branch !== expectedBranch) fail('branch does not match the current branch.');
@@ -139,25 +312,53 @@ function validateEvidence(evidence, expectedCommit, expectedBranch, now) {
   // next (a long-lived process validating several pushes).
   const resolvedModels = new Set();
   evidence.experts.forEach((expert, index) => {
-    validateExpert(expert, index, roles, models, resolvedModels);
+    validateExpert(expert, index, roles, models, resolvedModels, bindingSeats);
   });
   if (roles.size !== REQUIRED_ROLES.length) fail('all required expert roles must be present.');
 }
 
+/**
+ * Read and parse the evidence document, failing with a readable message rather
+ * than letting a raw ENOENT/JSON.parse error escape.
+ *
+ * @param {string} file path to the evidence JSON
+ * @returns {unknown} parsed document
+ */
+function readEvidence(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return fail('file must exist and contain valid JSON.');
+  }
+}
+
+/**
+ * Resolve the project root the caller named, if any.
+ *
+ * #574: the seats that bind are the ones configured in the repository being
+ * pushed. The caller names that root; a missing argument means "no project
+ * context", which keeps evidence unbound rather than guessing from cwd.
+ *
+ * @param {string|undefined} projectRoot raw argv value
+ * @returns {string|null} absolute root, or null for "no project context"
+ */
+function resolveProjectRoot(projectRoot) {
+  if (projectRoot === undefined || projectRoot === '') return null;
+  return path.resolve(projectRoot);
+}
+
 function main() {
-  const [file, expectedCommit, expectedBranch, nowValue] = process.argv.slice(2);
+  const [file, expectedCommit, expectedBranch, nowValue, projectRoot] = process.argv.slice(2);
   if (!file || !expectedCommit || !expectedBranch) {
-    fail('usage: validate-code-walkthrough.cjs <file> <commit> <branch> [now].');
+    fail(`usage: validate-code-walkthrough.cjs <file> <commit> <branch> [now] [project-root].`);
   }
 
-  let evidence;
-  try {
-    evidence = JSON.parse(fs.readFileSync(file, 'utf8'));
-  } catch {
-    fail('file must exist and contain valid JSON.');
-  }
+  const evidence = readEvidence(file);
   const now = nowValue === undefined ? Date.now() : parseTimestamp(nowValue, 'current time');
-  validateEvidence(evidence, expectedCommit, expectedBranch, now);
+
+  const root = resolveProjectRoot(projectRoot);
+  const bindingSeats = root === null ? null : loadBindingSeats(root);
+  validateEvidence(evidence, expectedCommit, expectedBranch, now, bindingSeats);
 }
 
 main();