rcf-lite 0.0.1 → 0.8.0

package/src/preflight/scanner.js

@@ -0,0 +1,206 @@
+// Pre-flight service candidate scanner
+// (verification-integrity-cluster-spec §4.3 / §8.3).
+//
+// Deterministic candidate GENERATOR (not a decider). Reads the named
+// PRD and optionally a TAD from the RCF chain, walks every string-shaped
+// prose field on those documents with core's `matchServiceSignals`
+// (imported, never re-implemented — the seed pattern set is the shared
+// source of truth per §5.3), and returns per-candidate provenance
+// records the interactive session then walks with the operator.
+//
+// The scanner intentionally over-collects (spec §4.3 / §4.4): false
+// positives are cheap (the operator dismisses in-session), false
+// negatives are the failure mode that motivated the whole cluster (the
+// d-142 "email channel" miss). Every match records the source doc, a
+// section-anchor guess (heading nearest the match), the matched
+// substring, and the category the seed set fired under.
+//
+// This module is pure: it takes a walker tree (already loaded from
+// disk) plus a target PRD id and optional TAD id, and returns a
+// candidate list. Every side-effect (filesystem, prompting) belongs to
+// the CLI handler in `../cli/preflight.js`.
+
+import { matchServiceSignals, SERVICE_CATEGORY_KEYS } from '#core/patterns/services';
+
+/**
+ * @typedef {object} ScannerSourceRef
+ * @property {string} docId          the PRD / TAD id
+ * @property {string} anchor         the section-anchor guess (heading id / index)
+ * @property {string} phrase         the matched substring
+ * @property {string} category       the seed-set category the match fired under
+ * @property {string} role           'token' | 'verb' | 'vendor'
+ */
+
+/**
+ * @typedef {object} ServiceCandidate
+ * @property {string} id             suggested camelCase service id (best-guess vendor if present, else category)
+ * @property {string} displayName    human-readable label
+ * @property {string} category       the dominant category (first hit)
+ * @property {ScannerSourceRef[]} sourceRefs
+ */
+
+/**
+ * @typedef {object} ScannerResult
+ * @property {ServiceCandidate[]} candidates
+ * @property {string[]} scannedDocIds
+ * @property {string[]} skippedDocIds   docs the caller asked for that were not found
+ */
+
+/**
+ * Extract every string-typed value under `doc` recursively, tagged with
+ * a synthetic anchor derived from the JSON pointer. The anchor lets the
+ * operator locate the match in the source without asking the scanner
+ * to understand every RCF document shape.
+ *
+ * @param {object} doc
+ * @returns {Array<{ anchor: string, text: string }>}
+ */
+function collectProseFields(doc) {
+  /** @type {Array<{ anchor: string, text: string }>} */
+  const out = [];
+  const stack = [{ node: doc, path: '' }];
+  while (stack.length > 0) {
+    const { node, path } = stack.pop();
+    if (node == null) continue;
+    if (typeof node === 'string') {
+      // Ignore very short strings (ids / statuses) unless they carry a
+      // space (a phrase); anything ≥ 3 chars with a space is prose-ish.
+      if (node.length >= 6 && node.includes(' ')) {
+        out.push({ anchor: path || '/', text: node });
+      }
+      continue;
+    }
+    if (Array.isArray(node)) {
+      for (let i = node.length - 1; i >= 0; i -= 1) {
+        stack.push({ node: node[i], path: `${path}/${i}` });
+      }
+      continue;
+    }
+    if (typeof node === 'object') {
+      for (const [k, v] of Object.entries(node)) {
+        stack.push({ node: v, path: `${path}/${k}` });
+      }
+    }
+  }
+  return out;
+}
+
+const CATEGORY_DISPLAY = {
+  emailDelivery: 'Email delivery service',
+  payment: 'Payment provider',
+  smsVoice: 'SMS or voice provider',
+  auth: 'Identity / auth provider',
+  storageCdn: 'Storage or CDN provider',
+  llmAi: 'LLM / AI provider',
+  analyticsTelemetry: 'Analytics or telemetry provider',
+  featureFlags: 'Feature-flag provider',
+  search: 'Search provider',
+};
+
+/**
+ * Best-guess camelCase id for a candidate: vendor name (if any hit was
+ * a vendor role) wins; otherwise the category id. Vendor names are
+ * lower-cased and non-alphanumerics stripped.
+ *
+ * @param {ScannerSourceRef[]} refs
+ * @param {string} fallbackCategory
+ * @returns {{ id: string, displayName: string }}
+ */
+function chooseCandidateName(refs, fallbackCategory) {
+  const vendor = refs.find((r) => r.role === 'vendor');
+  if (vendor) {
+    const cleaned = vendor.phrase.toLowerCase().replace(/[^a-z0-9]+/g, '');
+    if (cleaned.length > 0) {
+      const displayName = vendor.phrase.trim();
+      return { id: cleaned, displayName };
+    }
+  }
+  return {
+    id: fallbackCategory,
+    displayName: CATEGORY_DISPLAY[fallbackCategory] ?? fallbackCategory,
+  };
+}
+
+/**
+ * Group signal matches into service candidates. Groups by category
+ * (§4.4's nine categories); one candidate per category that fired at
+ * least once. Vendor hits within a category promote the candidate's
+ * suggested id + displayName. The operator can split (add a new
+ * candidate) or merge in the interactive session — the scanner does
+ * NOT try to be a classifier (§4.3 candidate generator, not decider).
+ *
+ * @param {ScannerSourceRef[]} refsInDocOrder
+ * @returns {ServiceCandidate[]}
+ */
+function groupIntoCandidates(refsInDocOrder) {
+  /** @type {Map<string, ScannerSourceRef[]>} */
+  const byCategory = new Map();
+  for (const ref of refsInDocOrder) {
+    if (!byCategory.has(ref.category)) byCategory.set(ref.category, []);
+    byCategory.get(ref.category).push(ref);
+  }
+  /** @type {ServiceCandidate[]} */
+  const candidates = [];
+  // Preserve seed-set category order for a stable presentation.
+  for (const category of SERVICE_CATEGORY_KEYS) {
+    const refs = byCategory.get(category);
+    if (!refs || refs.length === 0) continue;
+    const { id, displayName } = chooseCandidateName(refs, category);
+    candidates.push({ id, displayName, category, sourceRefs: refs });
+  }
+  return candidates;
+}
+
+/**
+ * Scan the named PRD (and optional TAD) for third-party service
+ * candidates. The tree is already loaded; the scanner reads only the
+ * documents named by id.
+ *
+ * @param {object} args
+ * @param {import('#core/store/walker.js').TreeModel} args.tree
+ * @param {string} args.prdId
+ * @param {string} [args.tadId]
+ * @returns {ScannerResult}
+ */
+export function scanForServiceCandidates({ tree, prdId, tadId }) {
+  /** @type {ScannerSourceRef[]} */
+  const refs = [];
+  const scannedDocIds = [];
+  const skippedDocIds = [];
+
+  const targets = [{ id: prdId, kind: 'prd' }];
+  if (tadId) targets.push({ id: tadId, kind: 'tad' });
+
+  for (const { id, kind } of targets) {
+    const doc = tree.byId.get(id) ?? (kind === 'prd' ? tree.prd : kind === 'tad' ? tree.tad : null);
+    if (!doc) {
+      skippedDocIds.push(id);
+      continue;
+    }
+    // Sanity-check the id matches the loaded doc (walker binds ids into
+    // byId by their own id field).
+    scannedDocIds.push(id);
+    const proseFields = collectProseFields(doc);
+    for (const { anchor, text } of proseFields) {
+      const matches = matchServiceSignals(text);
+      for (const m of matches) {
+        refs.push({
+          docId: id,
+          anchor,
+          phrase: m.match,
+          category: m.category,
+          role: m.role,
+        });
+      }
+    }
+  }
+
+  const candidates = groupIntoCandidates(refs);
+  return { candidates, scannedDocIds, skippedDocIds };
+}
+
+/**
+ * Public accessor for the display-name lookup so the interactive
+ * session's presentation can stay in one place.
+ */
+export const CATEGORY_DISPLAY_NAMES = Object.freeze({ ...CATEGORY_DISPLAY });

package/src/preflight/secrets.js

@@ -0,0 +1,134 @@
+// Pre-flight credentials side-file (verification-integrity-cluster-spec §4.6).
+//
+// Credentials NEVER enter the RCF chain: the preflight session captures
+// only the env-var NAME the credential lives under, plus a boolean
+// snapshot of whether that env var was present at session time. Values
+// are read from the shell at test/finalise time; the chain is
+// grep-friendly for names and audit-friendly for provenance without
+// ever holding a token.
+//
+// This module owns:
+// - the gitignore aggregator entry (`preflightEntry`) the shared 0.6.0
+//   `managedGitignoreEntries()` seam consumes to keep the side-file out
+//   of the shared repo by default; adding it is exactly the two-line
+//   extension the 0.6.0 spec §4.1 D-4 pattern promises;
+// - the side-file path helper;
+// - the loader/writer/merge helpers, all of which read the shell env
+//   var by NAME only and never accept, log, or persist a value.
+//
+// Redaction discipline (§4.6): every path through this module obeys
+// three rules: values are never read into the record (only presence),
+// values are never returned to callers (only names + presence booleans),
+// and error messages never quote env-var contents.
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import process from 'node:process';
+
+/**
+ * The gitignore entry the aggregator consumes. Shape mirrors
+ * `identityEntry` (0.6.0 aggregator seam contract). Adding this to
+ * `managedGitignoreEntries()` in `../setup/managed-gitignore.js` is the
+ * whole extension: one import line, one array entry.
+ */
+export const preflightEntry = Object.freeze({
+  path: '.rcf/preflight-secrets.local.json',
+  owner: 'rcf preflight: credential name-metadata (values never enter the chain)',
+  since: '0.7.0',
+});
+
+const SECRETS_FILE_REL = '.rcf/preflight-secrets.local.json';
+
+/**
+ * Absolute path of the side-file for a given project root.
+ *
+ * @param {string} projectRoot
+ * @returns {string}
+ */
+export function preflightSecretsPath(projectRoot) {
+  return join(projectRoot, '.rcf', 'preflight-secrets.local.json');
+}
+
+/**
+ * @typedef {object} PreflightSecretEntry
+ * @property {string} serviceId      camelCase service id (matches manifest)
+ * @property {string} envVarName     name only; never the value
+ * @property {boolean} envVarPresentAtSessionTime
+ * @property {string} recordedAt     ISO timestamp
+ */
+
+/**
+ * @typedef {object} PreflightSecretsFile
+ * @property {string} note           human-readable header
+ * @property {PreflightSecretEntry[]} entries
+ */
+
+const FILE_HEADER_NOTE = 'Credential name-metadata only. Values are never written here or into the RCF chain; env vars are read from the shell at runtime.';
+
+/**
+ * Load the side-file. Returns an empty file object when the file does
+ * not exist. Never throws on missing file; propagates any other read
+ * error to the caller.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @returns {Promise<PreflightSecretsFile>}
+ */
+export async function loadPreflightSecretsFile({ projectRoot }) {
+  const path = preflightSecretsPath(projectRoot);
+  let raw;
+  try {
+    raw = await readFile(path, 'utf8');
+  } catch (err) {
+    if (/** @type {NodeJS.ErrnoException} */ (err).code === 'ENOENT') {
+      return { note: FILE_HEADER_NOTE, entries: [] };
+    }
+    throw err;
+  }
+  const parsed = JSON.parse(raw);
+  const entries = Array.isArray(parsed?.entries) ? parsed.entries : [];
+  return { note: FILE_HEADER_NOTE, entries };
+}
+
+/**
+ * Record credential name-metadata for one service. The env var VALUE is
+ * never accepted as input; the loader reads the shell to observe
+ * presence and stores the boolean only.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {string} args.serviceId
+ * @param {string} args.envVarName
+ * @param {NodeJS.ProcessEnv} [args.env]  defaults to process.env
+ * @param {() => string} [args.now]       defaults to () => new Date().toISOString()
+ * @returns {Promise<PreflightSecretEntry>}
+ */
+export async function recordPreflightSecret({
+  projectRoot, serviceId, envVarName, env = process.env, now = () => new Date().toISOString(),
+}) {
+  if (typeof serviceId !== 'string' || serviceId.length === 0) {
+    throw new Error('recordPreflightSecret: serviceId required');
+  }
+  if (typeof envVarName !== 'string' || envVarName.length === 0) {
+    throw new Error('recordPreflightSecret: envVarName required');
+  }
+  const present = Object.prototype.hasOwnProperty.call(env, envVarName)
+    && typeof env[envVarName] === 'string'
+    && env[envVarName].length > 0;
+  const entry = /** @type {PreflightSecretEntry} */ ({
+    serviceId,
+    envVarName,
+    envVarPresentAtSessionTime: present,
+    recordedAt: now(),
+  });
+  const file = await loadPreflightSecretsFile({ projectRoot });
+  const nextEntries = file.entries.filter((e) => e.serviceId !== serviceId);
+  nextEntries.push(entry);
+  nextEntries.sort((a, b) => a.serviceId.localeCompare(b.serviceId));
+  const outFile = { note: FILE_HEADER_NOTE, entries: nextEntries };
+  const path = preflightSecretsPath(projectRoot);
+  await mkdir(dirname(path), { recursive: true });
+  // Deterministic 2-space JSON with trailing newline for editor-friendliness.
+  await writeFile(path, `${JSON.stringify(outFile, null, 2)}\n`, 'utf8');
+  return entry;
+}

package/src/preflight/session.js

@@ -0,0 +1,246 @@
+// Pre-flight interactive session
+// (verification-integrity-cluster-spec §4.5, ADDENDUM §A.1).
+//
+// Walks the scanner's candidates with the operator, then poses any
+// applicable design-shape questions. Emits a session record ready for
+// the manifest writer. Every path in this module operates through an
+// injected prompt/write pair so the CLI handler owns the readline
+// wiring and the tests can drive the session without a TTY.
+//
+// Register (per the 0.5.2 operator-communication register — plain
+// prose, no jargon citations, one leading question, tone of "it's in
+// hand"): the interactive text below reads as a colleague walking the
+// operator through decisions, not as a schema questionnaire.
+
+import { recordPreflightSecret } from './secrets.js';
+import { validateDesignShapeAnswer } from './design-shapes.js';
+
+/**
+ * @typedef {(question: string) => Promise<string>} PromptFn
+ * @typedef {(line: string) => void} WriteFn
+ */
+
+const ATTESTATION_CHOICES = [
+  { key: '1', mode: 'live', label: 'live — tests hit the live service with a real key you supply' },
+  { key: '2', mode: 'sandboxed', label: 'sandboxed — provider sandbox mode with a real key (no delivery)' },
+  { key: '3', mode: 'mocked', label: 'mocked — local fixtures or stubs; not ship-authoritative on its own' },
+  { key: '4', mode: 'declaredMockOnly', label: 'declaredMockOnly — ship mock-only intentionally (feature-flagged off, stub for local dev, pre-launch)' },
+  { key: '5', mode: 'notShipped', label: 'notShipped — for local development only; no production path uses it' },
+];
+
+const MODE_BY_KEY = new Map(ATTESTATION_CHOICES.map((c) => [c.key, c.mode]));
+
+/**
+ * @param {object} args
+ * @param {import('./scanner.js').ServiceCandidate} args.candidate
+ * @param {PromptFn} args.prompt
+ * @param {WriteFn} args.write
+ * @param {string} args.projectRoot
+ * @param {NodeJS.ProcessEnv} [args.env]
+ * @returns {Promise<import('./manifest-writer.js').PreflightServiceRuling>}
+ */
+async function walkOneServiceCandidate({ candidate, prompt, write, projectRoot, env }) {
+  write(`\nService candidate: ${candidate.displayName}`);
+  write(`Suggested id: ${candidate.id} (category ${candidate.category})`);
+  const refsSummary = candidate.sourceRefs.slice(0, 5)
+    .map((r) => `  - ${r.docId}${r.anchor === '/' ? '' : r.anchor} : "${r.phrase}"`)
+    .join('\n');
+  if (refsSummary.length > 0) write(`Where the scanner spotted it:\n${refsSummary}`);
+  if (candidate.sourceRefs.length > 5) {
+    write(`  (+${candidate.sourceRefs.length - 5} more source refs)`);
+  }
+  write('\nHow will tests verify this integration?');
+  for (const c of ATTESTATION_CHOICES) write(`  ${c.key}) ${c.label}`);
+
+  let mode;
+  while (mode === undefined) {
+    const ans = (await prompt('Select 1-5: ')).trim();
+    if (MODE_BY_KEY.has(ans)) mode = MODE_BY_KEY.get(ans);
+    else write('Not one of the five options; try again.');
+  }
+
+  const sourceRefs = Array.from(new Set(candidate.sourceRefs.map((r) => `${r.docId}${r.anchor === '/' ? '' : r.anchor}`)));
+
+  /** @type {import('./manifest-writer.js').PreflightServiceRuling} */
+  const ruling = {
+    id: candidate.id,
+    displayName: candidate.displayName,
+    sourceRefs,
+    attestationMode: mode,
+    credentialSupplied: false,
+    sandboxProvisioned: false,
+  };
+
+  if (mode === 'live' || mode === 'sandboxed') {
+    const envVarName = (await prompt('Which env var carries the credential (name only): ')).trim();
+    if (envVarName.length > 0) {
+      // recordPreflightSecret reads the shell env by NAME only; the
+      // side-file records presence booleans, never a value.
+      const secret = await recordPreflightSecret({ projectRoot, serviceId: candidate.id, envVarName, env });
+      ruling.credentialSupplied = secret.envVarPresentAtSessionTime;
+      if (mode === 'sandboxed') ruling.sandboxProvisioned = true;
+      if (!secret.envVarPresentAtSessionTime) {
+        write(`Note: ${envVarName} is not set in this shell; the side-file records that so the harness knows to prompt at run time.`);
+      }
+    }
+  } else if (mode === 'declaredMockOnly' || mode === 'notShipped') {
+    const reason = (await prompt('One-line reason (recorded on the chain): ')).trim();
+    if (reason.length > 0) ruling.operatorReason = reason;
+  } else if (mode === 'mocked') {
+    const reason = (await prompt('One-line reason a mock is acceptable here (recorded on the chain): ')).trim();
+    if (reason.length > 0) ruling.operatorReason = reason;
+  }
+
+  return ruling;
+}
+
+/**
+ * @param {object} args
+ * @param {import('./design-shapes.js').DesignShapeQuestion} args.question
+ * @param {string} args.reqId
+ * @param {PromptFn} args.prompt
+ * @param {WriteFn} args.write
+ * @returns {Promise<import('./manifest-writer.js').PreflightDesignShapeAnswer|null>}
+ */
+async function walkOneDesignShapeQuestion({ question, reqId, prompt, write }) {
+  write(`\nDesign-shape question against ${reqId}: ${question.prompt}`);
+  for (let i = 0; i < question.choices.length; i += 1) {
+    const c = question.choices[i];
+    write(`  ${i + 1}) ${c.display}${c.triggersOptOut ? '   (records an opt-out on the baseline ledger)' : ''}`);
+  }
+  let choice;
+  while (choice === undefined) {
+    const ans = (await prompt(`Select 1-${question.choices.length}: `)).trim();
+    const idx = Number.parseInt(ans, 10);
+    if (Number.isFinite(idx) && idx >= 1 && idx <= question.choices.length) {
+      choice = question.choices[idx - 1];
+    } else {
+      write('Not one of the listed options; try again.');
+    }
+  }
+  /** @type {import('./manifest-writer.js').PreflightDesignShapeAnswer} */
+  const answer = { questionId: question.id, reqId, answer: choice.value };
+  if (choice.triggersOptOut) {
+    let reason;
+    while (reason === undefined) {
+      const r = (await prompt(`Reason (at least ${question.reasonMinLength} chars, recorded on the ledger): `)).trim();
+      if (r.length >= question.reasonMinLength) reason = r;
+      else write(`That reason is ${r.length} chars; the ledger floor is ${question.reasonMinLength}.`);
+    }
+    answer.reason = reason;
+  }
+  return answer;
+}
+
+/**
+ * Run the interactive session. Returns the composed service rulings and
+ * design-shape answers ready for `composePreflightRecord`.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {import('./scanner.js').ScannerResult} args.scan
+ * @param {object[]} args.reqsForDesignShapes
+ * @param {import('./design-shapes.js').DesignShapeQuestion[]} [args.catalogue]
+ * @param {PromptFn} args.prompt
+ * @param {WriteFn} args.write
+ * @param {NodeJS.ProcessEnv} [args.env]
+ * @returns {Promise<{ services: import('./manifest-writer.js').PreflightServiceRuling[], designShapeAnswers: import('./manifest-writer.js').PreflightDesignShapeAnswer[] }>}
+ */
+export async function runInteractiveSession({
+  projectRoot, scan, reqsForDesignShapes, catalogue, prompt, write, env,
+}) {
+  const services = [];
+  for (const candidate of scan.candidates) {
+    const ruling = await walkOneServiceCandidate({ candidate, prompt, write, projectRoot, env });
+    services.push(ruling);
+  }
+
+  // Operator additions (candidates the scanner missed). Prompted after
+  // the scanner walk so the operator has seen the whole seed set first.
+  while (true) {
+    const wantMore = (await prompt('Add a service the scanner missed? (y/N): ')).trim().toLowerCase();
+    if (wantMore !== 'y' && wantMore !== 'yes') break;
+    const id = (await prompt('Service id (camelCase): ')).trim();
+    if (id.length === 0) continue;
+    const displayName = (await prompt('Display name: ')).trim() || id;
+    const synthetic = {
+      id, displayName, category: 'operatorAdded', sourceRefs: [],
+    };
+    const ruling = await walkOneServiceCandidate({ candidate: synthetic, prompt, write, projectRoot, env });
+    services.push(ruling);
+  }
+
+  const designShapeAnswers = [];
+  const { selectApplicableQuestions } = await import('./design-shapes.js');
+  const applicable = selectApplicableQuestions(reqsForDesignShapes, catalogue);
+  for (const { question, reqId } of applicable) {
+    const answer = await walkOneDesignShapeQuestion({ question, reqId, prompt, write });
+    if (answer) {
+      const err = validateDesignShapeAnswer({
+        questionId: answer.questionId, answer: answer.answer, reason: answer.reason,
+      });
+      if (err) throw new Error(err);
+      designShapeAnswers.push(answer);
+    }
+  }
+
+  write('\nSession summary:');
+  for (const s of services) {
+    write(`  ${s.id} (${s.displayName}) -> ${s.attestationMode}${s.credentialSupplied ? ' [cred present]' : ''}`);
+  }
+  for (const a of designShapeAnswers) {
+    write(`  ${a.questionId} on ${a.reqId} -> ${a.answer}`);
+  }
+  const confirm = (await prompt('\nConfirm this pre-flight record and commit? (yes/no): ')).trim().toLowerCase();
+  if (confirm !== 'y' && confirm !== 'yes') {
+    throw new Error('preflight: session cancelled by operator');
+  }
+  return { services, designShapeAnswers };
+}
+
+/**
+ * Non-interactive path: read a pre-filled input file and validate its
+ * shape enough that a downstream manifest write will validate against
+ * the schema.
+ *
+ * @param {object} input
+ * @returns {{ services: import('./manifest-writer.js').PreflightServiceRuling[], designShapeAnswers: import('./manifest-writer.js').PreflightDesignShapeAnswer[] }}
+ */
+export function normaliseNonInteractiveInput(input) {
+  if (!input || typeof input !== 'object') {
+    throw new Error('preflight: --input file did not parse to an object');
+  }
+  const rawServices = Array.isArray(input.services) ? input.services : [];
+  const services = rawServices.map((s, idx) => {
+    if (!s || typeof s !== 'object') throw new Error(`preflight: services[${idx}] must be an object`);
+    if (typeof s.id !== 'string' || s.id.length === 0) throw new Error(`preflight: services[${idx}].id required`);
+    if (typeof s.attestationMode !== 'string') throw new Error(`preflight: services[${idx}].attestationMode required`);
+    return {
+      id: s.id,
+      displayName: typeof s.displayName === 'string' ? s.displayName : s.id,
+      sourceRefs: Array.isArray(s.sourceRefs) ? s.sourceRefs.map(String) : [],
+      attestationMode: s.attestationMode,
+      credentialSupplied: Boolean(s.credentialSupplied),
+      sandboxProvisioned: Boolean(s.sandboxProvisioned),
+      operatorReason: typeof s.operatorReason === 'string' ? s.operatorReason : undefined,
+      affectedFbsIds: Array.isArray(s.affectedFbsIds) ? s.affectedFbsIds.map(String) : undefined,
+    };
+  });
+  const rawAnswers = Array.isArray(input.designShapeAnswers) ? input.designShapeAnswers : [];
+  const designShapeAnswers = rawAnswers.map((a, idx) => {
+    if (!a || typeof a !== 'object') throw new Error(`preflight: designShapeAnswers[${idx}] must be an object`);
+    if (typeof a.questionId !== 'string') throw new Error(`preflight: designShapeAnswers[${idx}].questionId required`);
+    if (typeof a.answer !== 'string') throw new Error(`preflight: designShapeAnswers[${idx}].answer required`);
+    const err = validateDesignShapeAnswer({
+      questionId: a.questionId, answer: a.answer, reason: a.reason,
+    });
+    if (err) throw new Error(`preflight: designShapeAnswers[${idx}]: ${err}`);
+    return {
+      questionId: a.questionId,
+      reqId: typeof a.reqId === 'string' ? a.reqId : undefined,
+      answer: a.answer,
+      reason: typeof a.reason === 'string' ? a.reason : undefined,
+    };
+  });
+  return { services, designShapeAnswers };
+}