@nurix/etna 0.19.41 → 0.19.43

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

@@ -0,0 +1,596 @@
+// 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. Deterministic: same
+// signature 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'));
+}
+
+// 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 = censusRows ?? 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();
+}