@nurix/etna 0.19.66 → 0.19.67

package/data/harnesses/apollo/skills/design/scripts/select-chart.mjs

@@ -1,622 +0,0 @@
-// skills/design/scripts/select-chart.mjs - B1 chart-selection engine: eliminate, rank, refuse
-//
-// One graph question per call. The model authors the data-signature JSON (the judgment
-// half); this script computes elimination, scoring, ranking, and refusal (the mechanical
-// half) over the chart-leaf census at ../data/charts/census.csv — the census and this
-// engine are one designed artifact and ship together (dimension-placement chapter 12).
-// Callers may pass explicit census rows (module arg or the signature's `census` array);
-// the local CSV is the default. Deterministic: same signature + census in, same output
-// out. No network, stdlib only.
-//
-// OUTPUT CONTRACT (docs/features/design-skill/07-evaluation-integrity.md §B1 — exact):
-//   {
-//     "admissible":     ["chart-id"],
-//     "eliminated":     [{ "id": "chart-id", "reasonCode": "elimination-code" }],
-//     "ranking":        [{ "id": "chart-id", "score": 0, "reasonCodes": ["reason-code"] }],
-//     "recommendation": "chart-id-or-null",
-//     "refusal":        "refusal-code-or-null"
-//   }
-//
-// INPUT SIGNATURE (fixed schema; the fuzzy question->schema derivation is the caller's job):
-//   {
-//     question:    string (audit only — no rule reads it),
-//     questions:   [string]  — optional; >1 entries signals a compound question (refusal),
-//     structure:   "flat|tree|edges|matrix|geo|interval|grid|scalar|text" (default flat;
-//                  scalar is derived when dimensions are empty and a measure exists),
-//     granularity: "raw-observations|pre-aggregated" (default pre-aggregated),
-//     rows:        number — dataset row count (drives the overplotting regime),
-//     measures:    [{ id, kind, unit, sign: "positive|signed|fraction", integer, isId, ambiguous }],
-//     dimensions:  [{ id, kind: "nominal|ordinal|temporal|geo", ordered, cardinality,
-//                     spacing: "regular|irregular", ambiguous }],
-//     target:      { value, source } — optional explicit target,
-//     semantics:   { targetExists, partsFormWhole, orderedProgression, temporalSubject,
-//                    negativeValues, wholeUnits, uncertainty, mixedUnits },
-//     task:        { primary, secondary: [<=2] } — optional; derived from schema defaults
-//                  when absent (explicit caller cues always win over the defaults),
-//     ambiguities: [{ field, alternatives }] — optional; non-empty signals refusal,
-//     constraints: { viewport: "mobile|tablet|desktop|wide" (default desktop),
-//                    interactionAllowed, colorVisionSafe, guardOverrides }
-//   }
-//
-// REFUSAL CONTRACT — four codes (graph-selection research 02 §7), checked in this order:
-//   1. "unmappable-structure"     (R-UNMAPPABLE)  structure fits no signature: free prose,
-//      a lone non-numeric fact, or an empty signature (no fields at all).
-//   2. "compound-question"        (R-COMPOUND)    input.questions carries >1 disjoint graph
-//      questions; decomposition is the invoker's job — the engine never charts two at once.
-//   3. "ambiguous-schema"         (R-AMBIGUOUS)   the schema derives two ways that land in
-//      different families (any field marked ambiguous, or input.ambiguities non-empty).
-//   4. "no-quantitative-measure"  (R-NO-MEASURE)  no measure and no countable structure —
-//      a bare entity list is a table row-set, not a chart; the engine refuses rather than
-//      inventing a count.
-//
-// FIXED OPEN PARAMETERS (the research left these open; fixed here, per 01 §B1):
-//   * Scoring constants (research §5 M-table, rescaled to reduce clamp saturation at 100
-//     while preserving every ordering relationship: M1 dominant, |M3 match| > |M2|,
-//     over-cap ~ -M3): BASE 50, clamp [0,100];
-//       M1 native fit: family anchor +20, native +16, fallback (table family) +6
-//       M2 encoding: position/length +8, angle/area/color-only -8, else 0
-//       M3 primary-task match +12 / mismatch -8 (leaves with no native task: 0)
-//       M4 secondary-task match +4 each (<=2)
-//       M5 cardinality: comfortable +4, near cap -4, over cap -12 (+ facet escape code)
-//       M6 dataset size: rows>=10000 binned +8 / point -8; rows>=1000 hexbin +4
-//       M7 decorative/low-precision -8 (pictogram, gauge, streamgraph, radar)
-//       M8 flag synergy +6 (temporalSubject->line family; partsFormWhole->part-to-whole
-//          family; targetExists->target-native leaves; uncertainty->error-bands)
-//     Threshold constants (research §6, fixed by decision inside the evidenced bands):
-//       K1 pie slices 6 · K2 bar categories 12 · K3 line series 6 · K4 stacked totals 10
-//       K5 overplot 1000 offered / 10000 mandatory · K6 facet panels 20 · K7 grouped
-//       series 4 · K8 waffle 10x10 · K9 SPLOM vars 8 · K10 network nodes 300.
-//       Hard elimination sits at 2x the comfort cap ("cardinality-exceeded"); between
-//       comfort and 2x the leaf is demoted, never killed (T-H: membership is decided only
-//       in elimination, so only 2x-destructive overflow counts as an expressiveness kill).
-//   * Task facets (research open question 3): primary + <=2 secondary facets are accepted
-//     on explicit input.task; schema-default derivation supplies a primary only. Rationale:
-//     one question can carry compound facets ("compare regions over time"), but the engine
-//     never invents a secondary the caller didn't assert.
-//   * Ambiguity handling (research open question 4): R-AMBIGUOUS stays a refusal variant,
-//     not a third response type — two response types keep the invoker contract simple
-//     (the research's own recommendation, adopted).
-//   * Guard overrides (research open question 5): guard variants (dual axes, truncated
-//     bar axes, broken axes, 3D) are census-level exclusions — they are design variants,
-//     not chart leaves, so there is nothing in the 57-leaf universe to resurrect.
-//     constraints.guardOverrides is accepted for forward compatibility and is currently a
-//     no-op on this closed output contract; overrides remain a rendering-layer concern
-//     recorded by the caller (per the ruling: overridable by explicit flag, logged).
-//   * The research's "conditional section" (options that unlock if a flag flips) folds
-//     into `eliminated` with flag-gate reason codes ("parts-form-whole-not-asserted",
-//     "target-not-asserted", ...) because the ratified 07 §B1 contract is closed — the
-//     unlock flag is recoverable from the reason code.
-//
-// CENSUS FLAG SEMANTICS (requires_flags / excludes_flags, |-separated):
-//   Flags fall into three classes; requires_flags evaluates per class:
-//     ordering class  {temporal, ordered-progression}            — OR (any one satisfies)
-//     structure class {tree, edges, matrix, geo, interval, scalar, grid} — OR
-//     semantic class  (everything else)                          — AND (each required)
-//   excludes_flags: any listed flag present in the derived input flags eliminates the leaf.
-//   Elimination emits one reasonCode per leaf, first match in this fixed precedence:
-//     structure-incompatible -> excluded-flag codes -> missing-required-flag codes
-//     ("ordered-x-required" for the ordering class, "structure-required" for the structure
-//     class, "<flag>-not-asserted"/"-required" for semantic flags) -> signature-mismatch
-//     -> cardinality-exceeded -> viewport-too-small.
-
-import fs from 'node:fs';
-import path from 'node:path';
-import process from 'node:process';
-import { fileURLToPath } from 'node:url';
-
-const VIEWPORT_ORDER = ['mobile', 'tablet', 'desktop', 'wide'];
-const ORDER_FLAGS = new Set(['temporal', 'ordered-progression']);
-const STRUCTURE_FLAGS = new Set(['tree', 'edges', 'matrix', 'geo', 'interval', 'scalar', 'grid']);
-const REFUSING_STRUCTURES = new Set(['text', 'prose', 'text-weights', 'none', 'unknown']);
-
-const EXCLUDE_REASON_BY_FLAG = {
-  temporal: 'temporal-series-incompatible',
-  'negative-values': 'negative-values-incompatible',
-  'irregular-temporal': 'irregular-temporal-incompatible',
-  'mixed-units': 'mixed-units-incompatible',
-  'no-color-encoding': 'color-encoding-inaccessible',
-};
-
-const REQUIRE_REASON_BY_FLAG = {
-  'parts-form-whole': 'parts-form-whole-not-asserted',
-  'target-exists': 'target-not-asserted',
-  'negative-values': 'negative-values-not-asserted',
-  'raw-observations': 'raw-observations-required',
-  'whole-units': 'whole-units-required',
-  uncertainty: 'uncertainty-not-asserted',
-};
-
-// EL-4: a non-flat structure admits only these leaves (plus any leaf that requires it).
-const STRUCTURE_COMPAT = {
-  tree: ['treemap', 'sunburst', 'tree-diagram', 'table', 'table-hybrid'],
-  edges: ['sankey', 'chord', 'network-graph', 'table', 'table-hybrid'],
-  matrix: ['heatmap', 'chord', 'table', 'table-hybrid'],
-  geo: ['choropleth', 'symbol-map', 'flow-map', 'point-map', 'table', 'table-hybrid'],
-  interval: ['gantt', 'event-timeline', 'table', 'table-hybrid'],
-  scalar: ['kpi-card', 'gauge', 'progress-bar', 'bullet', 'table', 'table-hybrid'],
-  grid: ['heatmap', 'table', 'table-hybrid'],
-};
-
-// M1 tiers: the settled core mappings (research 00 §C-1) anchor each family.
-const FAMILY_ANCHORS = new Set([
-  'bar', 'line-basic', 'pie', 'histogram', 'scatter', 'ordered-bar', 'sankey',
-  'network-graph', 'choropleth', 'event-timeline', 'kpi-card', 'heatmap', 'candlestick',
-]);
-const FALLBACK_LEAVES = new Set(['table', 'table-hybrid']);
-
-// M2: position/length reads most accurately; angle/area/color-only reads worst.
-const POSITION_LEAVES = new Set([
-  'bar', 'grouped-bar', 'stacked-bar', 'diverging-bar', 'lollipop', 'dot-plot', 'dumbbell',
-  'line-basic', 'line-multi', 'line-with-target', 'slope', 'bump', 'sparkline', 'ordered-bar',
-  'pareto', 'waterfall', 'scatter', 'histogram', 'box-plot', 'strip-plot', 'bullet',
-  'progress-bar', 'gantt', 'candlestick', 'error-bands',
-]);
-const LOW_PRECISION_LEAVES = new Set([
-  'pie', 'waffle', 'treemap', 'sunburst', 'marimekko', 'funnel', 'streamgraph', 'bubble',
-  'radar', 'pictogram', 'gauge', 'chord', 'heatmap', 'calendar-heatmap', 'choropleth',
-  'symbol-map',
-]);
-
-// M7: decorative/low-precision forms named by the research.
-const DECORATIVE_LEAVES = new Set(['pictogram', 'gauge', 'streamgraph', 'radar']);
-
-// M3/M4 native-task table (research §5, Amar-10 + trend/compare/overview).
-const NATIVE_TASKS = {
-  correlate: ['scatter', 'hexbin', 'splom', 'parallel-coordinates', 'bubble'],
-  trend: ['line-basic', 'line-multi', 'line-with-target', 'area', 'sparkline'],
-  distribution: ['histogram', 'density', 'box-plot', 'violin', 'strip-plot'],
-  'retrieve-value': ['table', 'table-hybrid', 'kpi-card'],
-  filter: ['table', 'table-hybrid'],
-  extremum: ['bar', 'ordered-bar', 'pareto'],
-  sort: ['ordered-bar', 'pareto', 'bar'],
-  compare: ['bar', 'grouped-bar', 'dot-plot', 'slope'],
-  cluster: ['scatter', 'heatmap'],
-  anomalies: ['scatter', 'box-plot'],
-  range: ['dumbbell', 'box-plot', 'gantt'],
-  derive: ['table', 'waterfall'],
-  overview: ['bar', 'line-basic', 'heatmap'],
-};
-const NATIVE_TASKS_BY_LEAF = (() => {
-  const byLeaf = new Map();
-  for (const [task, leaves] of Object.entries(NATIVE_TASKS)) {
-    for (const leaf of leaves) {
-      if (!byLeaf.has(leaf)) byLeaf.set(leaf, new Set());
-      byLeaf.get(leaf).add(task);
-    }
-  }
-  return byLeaf;
-})();
-
-// M5 cardinality rules per leaf: comfort cap (K constants), hard kill at 2x comfort
-// unless the census constraint is itself hard (slope's 2-3 x positions).
-const CARDINALITY_RULES = {
-  pie: { kind: 'categories', comfort: 6 },            // K1
-  waffle: { kind: 'categories', comfort: 6 },          // mirrors K1
-  bar: { kind: 'categories', comfort: 12, demoteOnly: true },       // K2
-  'ordered-bar': { kind: 'categories', comfort: 12, demoteOnly: true },
-  lollipop: { kind: 'categories', comfort: 12, demoteOnly: true },
-  'dot-plot': { kind: 'categories', comfort: 12, demoteOnly: true },
-  'grouped-bar': { kind: 'series', comfort: 4 },       // K7
-  'stacked-bar': { kind: 'series', comfort: 10 },      // K4
-  'line-multi': { kind: 'series', comfort: 6 },        // K3
-  bump: { kind: 'series', comfort: 6 },
-  slope: { kind: 'x-positions', comfort: 3, hard: 3 },
-  radar: { kind: 'categories', comfort: 3 },
-  'network-graph': { kind: 'nodes', comfort: 150, hard: 300 },      // K10
-};
-
-// M6 dataset-size regimes (K5).
-const BINNED_LEAVES = new Set(['hexbin', 'histogram', 'density', 'box-plot', 'heatmap', 'calendar-heatmap']);
-const POINT_LEAVES = new Set(['scatter', 'strip-plot', 'bubble']);
-const OVERPLOT_OFFERED = 1000;
-const OVERPLOT_MANDATORY = 10000;
-
-// M8 synergy targets beyond the family-level ones.
-const TARGET_NATIVE_LEAVES = new Set(['progress-bar', 'bullet', 'gauge', 'line-with-target']);
-
-const SCORE = {
-  base: 50,
-  m1Anchor: 20,
-  m1Native: 16,
-  m1Fallback: 6,
-  m2Position: 8,
-  m2LowPrecision: -8,
-  m3Match: 12,
-  m3Mismatch: -8,
-  m4Secondary: 4,
-  m5Comfortable: 4,
-  m5NearCap: -4,
-  m5OverCap: -12,
-  m6Binned: 8,
-  m6Overplot: -8,
-  m6HexbinOffered: 4,
-  m7Decorative: -8,
-  m8Synergy: 6,
-};
-
-// Parses one CSV line honoring double-quoted fields.
-function parseCsvLine(line) {
-  const cells = [];
-  let cell = '';
-  let inQuotes = false;
-  for (let i = 0; i < line.length; i += 1) {
-    const ch = line[i];
-    if (inQuotes) {
-      if (ch === '"' && line[i + 1] === '"') { cell += '"'; i += 1; }
-      else if (ch === '"') inQuotes = false;
-      else cell += ch;
-    } else if (ch === '"') inQuotes = true;
-    else if (ch === ',') { cells.push(cell); cell = ''; }
-    else cell += ch;
-  }
-  cells.push(cell);
-  return cells;
-}
-
-export function parseCensusCsv(text) {
-  const lines = text.split(/\r?\n/).filter((line) => line.trim() !== '');
-  const header = parseCsvLine(lines[0]).map((h) => h.trim());
-  const expected = ['id', 'family', 'min_measures', 'max_measures', 'min_dims', 'max_dims', 'requires_flags', 'excludes_flags', 'viewport_min', 'notes'];
-  if (header.join(',') !== expected.join(',')) {
-    throw new Error(`census header mismatch: expected "${expected.join(',')}" got "${header.join(',')}"`);
-  }
-  return lines.slice(1).map((line, index) => {
-    const cells = parseCsvLine(line);
-    const row = {};
-    header.forEach((key, i) => { row[key] = (cells[i] ?? '').trim(); });
-    return {
-      id: row.id,
-      family: row.family,
-      minMeasures: Number(row.min_measures),
-      maxMeasures: Number(row.max_measures),
-      minDims: Number(row.min_dims),
-      maxDims: Number(row.max_dims),
-      requiresFlags: row.requires_flags === '' ? [] : row.requires_flags.split('|').map((f) => f.trim()),
-      excludesFlags: row.excludes_flags === '' ? [] : row.excludes_flags.split('|').map((f) => f.trim()),
-      viewportMin: row.viewport_min === '' ? 'mobile' : row.viewport_min,
-      notes: row.notes,
-      order: index,
-    };
-  });
-}
-
-export function loadDefaultCensus() {
-  const censusPath = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'data', 'charts', 'census.csv');
-  return parseCensusCsv(fs.readFileSync(censusPath, 'utf8'));
-}
-
-// Accepts census rows in the engine's leaf shape (or a row shape with snake_case columns
-// and pipe-joined flag strings) and normalizes onto the leaf shape.
-export function normalizeCensusRows(rows) {
-  if (!Array.isArray(rows) || rows.length === 0) {
-    throw new Error('census rows are required — the shipped census at data/charts/census.csv is the default');
-  }
-  const toFlagList = (value) =>
-    Array.isArray(value) ? value : value == null || value === '' ? [] : String(value).split('|').map((f) => f.trim());
-  return rows.map((row, index) => ({
-    id: row.id ?? row.slug,
-    family: row.family,
-    minMeasures: Number(row.minMeasures ?? row.min_measures),
-    maxMeasures: Number(row.maxMeasures ?? row.max_measures),
-    minDims: Number(row.minDims ?? row.min_dims),
-    maxDims: Number(row.maxDims ?? row.max_dims),
-    requiresFlags: toFlagList(row.requiresFlags ?? row.requires_flags),
-    excludesFlags: toFlagList(row.excludesFlags ?? row.excludes_flags),
-    viewportMin: row.viewportMin ?? row.viewport_min ?? 'mobile',
-    notes: row.notes ?? '',
-    order: row.order ?? row.ord ?? index,
-  }));
-}
-
-// Normalizes loose dimension-kind aliases onto the N/O/Q/T backbone.
-function dimensionKind(dim) {
-  const kind = dim.kind || 'nominal';
-  if (kind === 'categorical') return 'nominal';
-  return kind;
-}
-
-function effectiveMeasures(input) {
-  return (input.measures || []).filter((m) => m.isId !== true);
-}
-
-// Derives the auditable flag set the census rows are gated on.
-function deriveFlags(input) {
-  const dims = input.dimensions || [];
-  const measures = effectiveMeasures(input);
-  const semantics = input.semantics || {};
-  const constraints = input.constraints || {};
-  const structure = deriveStructure(input);
-  const flags = new Set();
-
-  if (dims.some((d) => dimensionKind(d) === 'temporal')) flags.add('temporal');
-  if (semantics.orderedProgression === true || dims.some((d) => d.ordered === true && dimensionKind(d) !== 'temporal')) {
-    flags.add('ordered-progression');
-  }
-  if (semantics.partsFormWhole === true) flags.add('parts-form-whole');
-  if (semantics.targetExists === true || input.target != null) flags.add('target-exists');
-  if (semantics.negativeValues === true || measures.some((m) => m.sign === 'signed')) flags.add('negative-values');
-  if ((input.granularity || 'pre-aggregated') === 'raw-observations') flags.add('raw-observations');
-  if (semantics.wholeUnits === true
-    || (measures.length > 0 && measures.every((m) => m.kind === 'count' || m.unit === 'count' || m.integer === true))) {
-    flags.add('whole-units');
-  }
-  if (dims.some((d) => dimensionKind(d) === 'temporal' && d.spacing === 'irregular')) flags.add('irregular-temporal');
-  if (semantics.uncertainty === true || semantics.uncertaintyExists === true) flags.add('uncertainty');
-  if (semantics.mixedUnits === true
-    || (measures.length > 1 && new Set(measures.map((m) => m.unit ?? m.kind ?? '')).size > 1)) {
-    flags.add('mixed-units');
-  }
-  const accessibility = constraints.accessibility;
-  if (constraints.colorVisionSafe === true
-    || accessibility === 'color-independent'
-    || (Array.isArray(accessibility) && accessibility.includes('color-independent'))) {
-    flags.add('no-color-encoding');
-  }
-  if (STRUCTURE_FLAGS.has(structure)) flags.add(structure);
-  return { flags, structure };
-}
-
-function deriveStructure(input) {
-  if (input.structure) return input.structure;
-  const dims = input.dimensions || [];
-  const measures = effectiveMeasures(input);
-  if (dims.length === 0 && measures.length > 0) return 'scalar';
-  return 'flat';
-}
-
-// Refusal check — fires instead of a ranking; order is part of the contract (header).
-function deriveRefusal(input, structure) {
-  const dims = input.dimensions || [];
-  const measures = effectiveMeasures(input);
-  const allFields = [...(input.measures || []), ...dims];
-  if (REFUSING_STRUCTURES.has(structure)) return 'unmappable-structure';
-  if (structure === 'flat' && measures.length === 0 && dims.length === 0 && input.target == null) {
-    return 'unmappable-structure';
-  }
-  if (Array.isArray(input.questions) && input.questions.length > 1) return 'compound-question';
-  if ((Array.isArray(input.ambiguities) && input.ambiguities.length > 0)
-    || allFields.some((f) => f.ambiguous === true)) {
-    return 'ambiguous-schema';
-  }
-  if (measures.length === 0 && structure === 'flat'
-    && !dims.some((d) => ['temporal', 'geo'].includes(dimensionKind(d)))) {
-    return 'no-quantitative-measure';
-  }
-  return null;
-}
-
-// Schema-default task derivation (the engine's half of the two-stage derivation;
-// explicit query-cue extraction is the caller's half and arrives as input.task).
-function deriveTask(input, flags) {
-  if (input.task && input.task.primary) {
-    return {
-      primary: input.task.primary,
-      secondary: (input.task.secondary || []).slice(0, 2),
-    };
-  }
-  const dims = input.dimensions || [];
-  const measures = effectiveMeasures(input);
-  const catDims = dims.filter((d) => ['nominal', 'ordinal'].includes(dimensionKind(d)));
-  let primary;
-  if (dims.length === 0) primary = flags.has('target-exists') ? 'compare' : 'retrieve-value';
-  else if (measures.length >= 2 && flags.has('raw-observations')) primary = 'correlate';
-  else if (flags.has('temporal') && measures.length >= 1) primary = 'trend';
-  else if (measures.length === 1 && flags.has('raw-observations') && catDims.length <= 1) primary = 'distribution';
-  else if (measures.length >= 2) primary = 'correlate';
-  else if (catDims.length >= 1 && measures.length >= 1) primary = 'compare';
-  else primary = 'overview';
-  return { primary, secondary: [] };
-}
-
-// Resolves the cardinality the leaf's M5 rule inspects.
-function cardinalityFor(rule, input) {
-  const dims = input.dimensions || [];
-  const catDims = dims.filter((d) => ['nominal', 'ordinal'].includes(dimensionKind(d)));
-  const orderedDims = dims.filter((d) => dimensionKind(d) === 'temporal' || d.ordered === true);
-  const cards = (list) => list.map((d) => d.cardinality).filter((c) => Number.isFinite(c));
-  switch (rule.kind) {
-    case 'categories': {
-      const c = cards(catDims.length > 0 ? catDims : dims);
-      return c.length > 0 ? c[0] : undefined;
-    }
-    case 'series': {
-      const nonOrdered = dims.filter((d) => !(dimensionKind(d) === 'temporal' || d.ordered === true));
-      if (orderedDims.length > 0 && nonOrdered.length > 0) {
-        const c = cards(nonOrdered);
-        return c.length > 0 ? Math.max(...c) : undefined;
-      }
-      const c = cards(catDims);
-      return c.length >= 2 ? Math.min(...c) : c[0];
-    }
-    case 'x-positions': {
-      const c = cards(orderedDims);
-      return c.length > 0 ? c[0] : undefined;
-    }
-    case 'nodes': {
-      const c = cards(dims);
-      return c.length > 0 ? Math.max(...c) : undefined;
-    }
-    default:
-      return undefined;
-  }
-}
-
-// Elimination — one reasonCode per leaf, fixed precedence (see header).
-function eliminationReason(leaf, input, flags, structure, viewport) {
-  const measures = effectiveMeasures(input);
-  const dims = input.dimensions || [];
-
-  if (structure !== 'flat' && STRUCTURE_COMPAT[structure]
-    && !STRUCTURE_COMPAT[structure].includes(leaf.id)
-    && !leaf.requiresFlags.includes(structure)) {
-    return 'structure-incompatible';
-  }
-
-  for (const flag of leaf.excludesFlags) {
-    if (flags.has(flag)) return EXCLUDE_REASON_BY_FLAG[flag] || `${flag}-incompatible`;
-  }
-
-  const orderingRequired = leaf.requiresFlags.filter((f) => ORDER_FLAGS.has(f));
-  if (orderingRequired.length > 0 && !orderingRequired.some((f) => flags.has(f))) {
-    return 'ordered-x-required';
-  }
-  const structureRequired = leaf.requiresFlags.filter((f) => STRUCTURE_FLAGS.has(f));
-  if (structureRequired.length > 0 && !structureRequired.some((f) => flags.has(f))) {
-    return 'structure-required';
-  }
-  for (const flag of leaf.requiresFlags) {
-    if (ORDER_FLAGS.has(flag) || STRUCTURE_FLAGS.has(flag)) continue;
-    if (!flags.has(flag)) return REQUIRE_REASON_BY_FLAG[flag] || `${flag}-not-asserted`;
-  }
-
-  if (measures.length < leaf.minMeasures || measures.length > leaf.maxMeasures
-    || dims.length < leaf.minDims || dims.length > leaf.maxDims) {
-    return 'signature-mismatch';
-  }
-
-  const rule = CARDINALITY_RULES[leaf.id];
-  if (rule && !rule.demoteOnly) {
-    const card = cardinalityFor(rule, input);
-    const hard = rule.hard ?? rule.comfort * 2;
-    if (card !== undefined && card > hard) return 'cardinality-exceeded';
-  }
-
-  if (VIEWPORT_ORDER.indexOf(viewport) < VIEWPORT_ORDER.indexOf(leaf.viewportMin)) {
-    return 'viewport-too-small';
-  }
-  return null;
-}
-
-// Scoring — additive over the fixed M-table; every weight is a constant (header).
-function scoreLeaf(leaf, input, flags, task) {
-  let score = SCORE.base;
-  const reasonCodes = [];
-
-  if (FAMILY_ANCHORS.has(leaf.id)) { score += SCORE.m1Anchor; reasonCodes.push('m1-native-anchor'); }
-  else if (FALLBACK_LEAVES.has(leaf.id)) { score += SCORE.m1Fallback; reasonCodes.push('m1-fallback'); }
-  else { score += SCORE.m1Native; reasonCodes.push('m1-native-fit'); }
-
-  if (POSITION_LEAVES.has(leaf.id)) { score += SCORE.m2Position; reasonCodes.push('m2-position-encoding'); }
-  else if (LOW_PRECISION_LEAVES.has(leaf.id)) { score += SCORE.m2LowPrecision; reasonCodes.push('m2-low-precision-encoding'); }
-
-  const nativeTasks = NATIVE_TASKS_BY_LEAF.get(leaf.id);
-  if (nativeTasks && task.primary) {
-    if (nativeTasks.has(task.primary)) { score += SCORE.m3Match; reasonCodes.push(`m3-task-match:${task.primary}`); }
-    else { score += SCORE.m3Mismatch; reasonCodes.push('m3-task-mismatch'); }
-    for (const secondary of task.secondary) {
-      if (nativeTasks.has(secondary)) { score += SCORE.m4Secondary; reasonCodes.push(`m4-secondary-task-match:${secondary}`); }
-    }
-  }
-
-  const rule = CARDINALITY_RULES[leaf.id];
-  if (rule) {
-    const card = cardinalityFor(rule, input);
-    if (card !== undefined) {
-      if (card <= rule.comfort) { score += SCORE.m5Comfortable; reasonCodes.push('m5-cardinality-comfortable'); }
-      else if (card <= (rule.hard ?? rule.comfort * 2)) { score += SCORE.m5NearCap; reasonCodes.push('m5-cardinality-near-cap'); }
-      else { score += SCORE.m5OverCap; reasonCodes.push('m5-cardinality-over-cap', 'op-facet-suggested'); }
-    }
-  }
-
-  const rows = Number.isFinite(input.rows) ? input.rows : undefined;
-  if (rows !== undefined) {
-    if (rows >= OVERPLOT_MANDATORY) {
-      if (BINNED_LEAVES.has(leaf.id)) { score += SCORE.m6Binned; reasonCodes.push('m6-binned-boost'); }
-      if (POINT_LEAVES.has(leaf.id)) { score += SCORE.m6Overplot; reasonCodes.push('m6-overplot-penalty'); }
-    } else if (rows >= OVERPLOT_OFFERED && leaf.id === 'hexbin') {
-      score += SCORE.m6HexbinOffered;
-      reasonCodes.push('m6-binned-boost');
-    }
-  }
-
-  if (DECORATIVE_LEAVES.has(leaf.id)) { score += SCORE.m7Decorative; reasonCodes.push('m7-decorative-penalty'); }
-
-  const semantics = input.semantics || {};
-  if (semantics.temporalSubject === true && leaf.family === 'line') {
-    score += SCORE.m8Synergy; reasonCodes.push('m8-flag-synergy:temporal-subject');
-  }
-  if (flags.has('parts-form-whole') && leaf.family === 'part-to-whole') {
-    score += SCORE.m8Synergy; reasonCodes.push('m8-flag-synergy:parts-form-whole');
-  }
-  if (flags.has('target-exists') && TARGET_NATIVE_LEAVES.has(leaf.id)) {
-    score += SCORE.m8Synergy; reasonCodes.push('m8-flag-synergy:target-exists');
-  }
-  if (flags.has('uncertainty') && leaf.id === 'error-bands') {
-    score += SCORE.m8Synergy; reasonCodes.push('m8-flag-synergy:uncertainty');
-  }
-
-  return { score: Math.max(0, Math.min(100, score)), reasonCodes };
-}
-
-// The B1 decision function — one engine, two callers (CLI here, contract runner imports).
-export function selectChart(input, censusRows) {
-  if (input == null || typeof input !== 'object' || Array.isArray(input)) {
-    throw new Error('selectChart: input must be a data-signature object');
-  }
-  const census = normalizeCensusRows(censusRows ?? input.census ?? loadDefaultCensus());
-  const { flags, structure } = deriveFlags(input);
-
-  const refusal = deriveRefusal(input, structure);
-  if (refusal !== null) {
-    return { admissible: [], eliminated: [], ranking: [], recommendation: null, refusal };
-  }
-
-  const viewport = (input.constraints && input.constraints.viewport) || 'desktop';
-  const task = deriveTask(input, flags);
-
-  const admissibleLeaves = [];
-  const eliminated = [];
-  for (const leaf of census) {
-    const reasonCode = eliminationReason(leaf, input, flags, structure, viewport);
-    if (reasonCode !== null) eliminated.push({ id: leaf.id, reasonCode });
-    else admissibleLeaves.push(leaf);
-  }
-
-  const ranking = admissibleLeaves
-    .map((leaf) => ({ leaf, ...scoreLeaf(leaf, input, flags, task) }))
-    .sort((a, b) => (b.score - a.score) || (a.leaf.order - b.leaf.order))
-    .map((entry) => ({ id: entry.leaf.id, score: entry.score, reasonCodes: entry.reasonCodes }));
-
-  return {
-    admissible: admissibleLeaves.map((leaf) => leaf.id),
-    eliminated,
-    ranking,
-    recommendation: ranking.length > 0 ? ranking[0].id : null,
-    refusal: null,
-  };
-}
-
-// Reads the whole of stdin (used when no input path is given).
-function readStdin() {
-  return fs.readFileSync(0, 'utf8');
-}
-
-function main() {
-  const inputPath = process.argv[2];
-  let raw;
-  try {
-    raw = inputPath ? fs.readFileSync(inputPath, 'utf8') : readStdin();
-  } catch (error) {
-    console.error(`select-chart: cannot read input: ${error.message}`);
-    process.exit(1);
-  }
-  let input;
-  try {
-    input = JSON.parse(raw);
-  } catch (error) {
-    console.error(`select-chart: input is not valid JSON: ${error.message}`);
-    process.exit(1);
-  }
-  let output;
-  try {
-    output = selectChart(input);
-  } catch (error) {
-    console.error(`select-chart: ${error.message}`);
-    process.exit(1);
-  }
-  process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
-}
-
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
-  main();
-}