Function lintStoryboardIdempotency

scripts/build-compliance.cjs:272–444

(sourceDir, schemasDir)

}

function lintStoryboardIdempotency(sourceDir, schemasDir) {
  const { refs: mutatingRefs, tools: mutatingTools } = loadMutatingSchemaRefs(schemasDir);
  const violations = [];
  const stableKeyViolations = [];
  const duplicateGeneratedKeyViolations = [];
  const missingSchemaRefs = [];
  const generatedKeyUses = new Map();
  const duplicateGeneratedKeyAllowedFiles = new Set([
    'universal/idempotency.yaml',
    'universal/webhook-emission.yaml',
  ]);

  function isGeneratedIdempotencyKey(value, generatedContextNames) {
    if (typeof value !== 'string') return false;
    if (value.startsWith('$generate:uuid_v4')) return true;
    const contextMatch = value.match(/^\$context\.([A-Za-z0-9_]+)$/);
    return Boolean(contextMatch && generatedContextNames.has(contextMatch[1]));
  }

  function rememberGeneratedUuidContextOutputs(step, generatedContextNames) {
    for (const output of step?.context_outputs ?? []) {
      if (output?.generate === 'uuid_v4' && typeof output.name === 'string') {
        generatedContextNames.add(output.name);
      }
    }
  }

  function lintFile(p) {
    const rel = path.relative(sourceDir, p);
    // Not storyboards: test-kit fixtures and the schema doc itself.
    if (rel.startsWith('test-kits/')) return;
    if (rel.endsWith('storyboard-schema.yaml')) return;

    let doc;
    try { doc = yaml.load(fs.readFileSync(p, 'utf8')); }
    catch { return; }
    if (!doc || typeof doc !== 'object' || !Array.isArray(doc.phases)) return;
    const generatedContextNames = new Set();

    for (const phase of doc.phases) {
      if (!phase || !Array.isArray(phase.steps)) continue;
      for (const step of phase.steps) {
        if (!step || typeof step !== 'object' || !step.task) continue;
        // Steps without schema_ref are HTTP probes, controller calls, or
        // synthetic invocations (e.g., comply_test_controller's
        // simulate_budget scenarios, universal/security.yaml's probe steps)
        // that don't send a task request schema. They're out of scope for
        // this lint — UNLESS the task name itself is a known mutating tool,
        // in which case the missing schema_ref is itself a storyboard bug
        // (the step would bypass the idempotency_key lint above). Positive
        // check per red-team I-9 / security.mdx storyboard hygiene.
        if (step.task && mutatingTools.has(step.task) && !step.schema_ref) {
          missingSchemaRefs.push({
            file: rel,
            step: step.id,
            msg: `Step uses mutating tool "${step.task}" but has no schema_ref`,
          });
        }