JuliusBrussee/caveman · error · Error

${where} structural_cost_share ${motif.structural_cost_share

Error message

${where} structural_cost_share ${motif.structural_cost_share} != ${expectedShare}

What it means

The validator recomputes a motif's structural_cost_share as the eligible-run-weighted average of motif.operations.length / variant.signature.length over every supporting variant (tolerance 1e-6) and throws when the stored value drifts beyond it (validate-continuous-improvement.mjs:126-128). This keeps the share an evidence figure the reader can re-derive rather than an assertion. The typical cause is a rounded or stale stored value, not a disagreement about the formula.

Source

Thrown at packages/shared/contracts/scripts/validate-continuous-improvement.mjs:127

    const where = `report fixture ${reportPaths[index]}: motif ${motif.id}`;
    if (!familyIDs.has(motif.task_family_id)) throw new Error(`${where} references a task family that is not in this report`);
    if (motif.support_variant_count !== motif.variant_ids.length) throw new Error(`${where} support variant count disagrees with its variant ids`);
    let runs = 0;
    let weighted = 0;
    for (const variantID of motif.variant_ids) {
      const variant = variantsByID.get(variantID);
      if (!variant) throw new Error(`${where} references workflow variant ${variantID} that is not in this report`);
      if (variant.task_family_id !== motif.task_family_id) throw new Error(`${where} supporting variant ${variantID} belongs to another task family`);
      if (!contiguouslyContains(variant.signature, motif.operations)) {
        throw new Error(`${where} operations are not a contiguous subsequence of variant ${variantID}'s signature`);
      }
      runs += variant.eligible_runs;
      weighted += (motif.operations.length / variant.signature.length) * variant.eligible_runs;
    }
    if (motif.support_run_count !== runs) throw new Error(`${where} support run count ${motif.support_run_count} != ${runs}`);
    const expectedShare = runs > 0 ? weighted / runs : 0;
    if (Math.abs(motif.structural_cost_share - expectedShare) > 1e-6) {
      throw new Error(`${where} structural_cost_share ${motif.structural_cost_share} != ${expectedShare}`);
    }
  }
  motifCount += report.motifs.length;

  // The causal investigation of every case: the cohort's arms, the traces it
  // selected from them, and the backward hard-dependency slice.
  const unitsByID = new Map(report.analysis_units.map((unit) => [unit.id, unit]));
  const familiesByID = new Map(report.task_families.map((family) => [family.id, family]));
  for (const item of report.cases) {
    const where = `report fixture ${reportPaths[index]}: case ${item.id}`;
    const family = familiesByID.get(item.cohort.task_family_id);
    if (!family) throw new Error(`${where} cohort references a task family that is not in this report`);
    const familyUnits = new Set(family.analysis_unit_ids);
    if (item.cohort.family_unit_count !== familyUnits.size) throw new Error(`${where} cohort family unit count disagrees with the task family`);
    const roles = item.cohort.arms.map((arm) => arm.role);
    if (roles.join(",") !== "baseline,alternative") throw new Error(`${where} cohort arms are not baseline then alternative`);
    const armVariants = new Map();
    let comparedUnits = 0;

View on GitHub (pinned to 766dce6b13)

Solutions

Recompute the share in full double precision: expectedShare = Σ(operations.length / signature.length × eligible_runs) / Σ(eligible_runs), and store it unrounded.
Check the inputs to the average — each ratio uses that variant's current signature length and the motif's current operations list.
When the recomputed runs total is 0, the expected share is exactly 0 — store 0, not a leftover ratio.
Re-run the validator.

Example fix

// before — ops length 3; wf-a signature 6 (24 runs), wf-b signature 9 (31 runs)
{ "structural_cost_share": 0.5 }
// after — (3/6*24 + 3/9*31) / 55 = 0.40606060606060607
{ "structural_cost_share": 0.40606060606060607 }

Defensive patterns

Strategy: validation

Validate before calling

const shareDrift = (report) => {
  const byID = new Map(report.workflow_variants.map((v) => [v.id, v]));
  return report.motifs.filter((m) => {
    let runs = 0, weighted = 0;
    for (const id of m.variant_ids) {
      const v = byID.get(id);
      runs += v.eligible_runs;
      weighted += (m.operations.length / v.signature.length) * v.eligible_runs;
    }
    return Math.abs(m.structural_cost_share - (runs > 0 ? weighted / runs : 0)) > 1e-6;
  });
};

Try / catch

try {
  execFileSync(process.execPath, [VALIDATOR, reportPath, spansPath]);
} catch (err) {
  if (/structural_cost_share/.test(err.message)) {
    failCI(`rounded or stale share — recompute in full precision: ${err.message}`);
  } else throw err;
}

Prevention

Never round derived floats when writing fixtures — store the full double the formula produces.
Keep the 1e-6 tolerance in mind: anything past six decimal digits of drift fails.
Fix support_run_count drift (error 600) first; the share is computed from the same inputs.

When it happens

Trigger: The fixture stores structural_cost_share rounded to 4 decimals while the weighted average needs full double precision; a variant's signature length or eligible_runs changed after the share was computed; motif.operations gained or lost an operation without recomputing. Note the check runs only after support_run_count already matched (error 600), so the inputs to the average are consistent.

Common situations: Serializing floats through a formatter that truncates digits (toFixed(4), JSON writers that round); hand-computing the share in a spreadsheet and pasting a rounded number; a generator emitting shares from an earlier pass over the variants.

Related errors

AI-assisted analysis of JuliusBrussee/caveman@766dce6b13 (2026-08-18). Data as JSON: /api/errors/9f3b56acf6548921. Report an issue: GitHub.