@mcptoolshop/style-dataset-lab 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.1.0] - 2026-04-16
+
+### Added
+
+- **Dataset spine** -- complete snapshot-to-export pipeline with proof at every stage
+  - `sdlab snapshot create/list/show/diff` -- frozen, deterministic record selections with config fingerprinting
+  - `sdlab eligibility audit` -- training eligibility evaluation with explicit reason traces
+  - `sdlab split build/list/show/audit` -- subject-isolated, lane-balanced train/val/test splitting
+  - `sdlab card generate` -- dataset card generation (markdown + JSON twin)
+  - `sdlab export build/list` -- self-contained export packages with manifest, metadata, images, splits, checksums
+  - `sdlab eval-pack build/list/show` -- canon-aware eval packs (4 task types)
+- **New library modules:**
+  - `lib/snapshot.js` -- snapshot creation, loading, diffing
+  - `lib/eligibility.js` -- eligibility evaluation with reason traces and exclusion categorization
+  - `lib/split.js` -- subject isolation (identity/lineage/suffix), mulberry32 PRNG, lane-balanced splitting, leakage audit
+  - `lib/card.js` -- dataset card rendering from snapshot + split + config
+  - `lib/export.js` -- export package builder with checksums and reproducibility manifest
+  - `lib/eval-pack.js` -- four eval task types (lane coverage, forbidden drift, anchor/gold, subject continuity)
+- **Selection, split, and export profiles** in `lib/config.js` with sensible defaults
+- **Detection functions** (`detectLane`, `detectGroup`) extracted from canon-bind into `lib/config.js` for reuse
+
+### Key properties
+
+- Snapshots are frozen -- once created, never silently changes
+- Inclusion is explainable -- every record has a reason trace
+- Splits preserve canon truth -- no subject family appears in multiple partitions
+- Exports are reproducible -- rebuildable from snapshot ref + split ref + config fingerprint
+
 ## [2.0.0] - 2026-04-15
 
 ### Breaking changes

package/README.md

@@ -9,19 +9,28 @@
 
 # style-dataset-lab
 
-A canon-bound visual dataset pipeline for directed image production.
-
-Define what your project looks like. Generate candidates. Curate against your canon. Bind approved work to constitution rules. Export trustworthy datasets for training, evaluation, and production reuse.
+Turn approved visual work into versioned, review-backed datasets, splits, export packages, and eval packs.
 
 ## What this is
 
-A **visual canon + dataset pipeline** for teams that care about style consistency, provenance, and reviewable judgment. Every asset carries three things:
+A **visual canon and dataset production pipeline**. Define what your project looks like. Curate against constitution rules. Produce reproducible dataset packages with leakage-safe splits. Generate eval packs for future model verification.
+
+The pipeline produces four artifacts:
+
+| Artifact | What it is |
+|----------|-----------|
+| **Snapshot** | Frozen, fingerprinted selection of eligible records. Every inclusion has an explicit reason trace. |
+| **Split** | Leakage-safe train/val/test partition. Records sharing a subject family always land in the same split. |
+| **Export package** | Self-contained dataset: manifest, metadata, images, splits, dataset card, and checksums. |
+| **Eval pack** | Canon-aware verification tasks: lane coverage, forbidden drift, anchor/gold, subject continuity. |
+
+Every asset in the pipeline carries three things:
 
 1. **Provenance** -- full generation history (checkpoint, LoRA, seed, sampler, cfg, timing)
 2. **Canon binding** -- which constitution rules this asset passes, fails, or partially meets
 3. **Quality judgment** -- approved/rejected/borderline with per-dimension scores
 
-The pipeline works for game art, character design, creature design, architecture, vehicle/mech concepts, and any domain where visual production needs to stay on-model.
+Works for game art, character design, creature design, architecture, vehicle/mech concepts, and any domain where visual production needs to stay on-model.
 
 ## Quick start
 
@@ -53,6 +62,16 @@ sdlab curate <id> <status> <explanation>  # Record review judgment
 sdlab compare <a> <b> <winner> <reason>   # Pairwise A-vs-B comparison
 sdlab bind [--project <name>]             # Bind records to constitution rules
 sdlab painterly [--project <name>]        # Post-processing style pass
+
+sdlab snapshot create [--profile <name>]  # Create frozen dataset snapshot
+sdlab snapshot list                       # List all snapshots
+sdlab snapshot diff <a> <b>               # Compare two snapshots
+sdlab eligibility audit                   # Audit record training eligibility
+sdlab split build [--snapshot <id>]       # Build train/val/test split
+sdlab split audit <id>                    # Audit split for leakage + balance
+sdlab card generate                       # Generate dataset card (md + JSON)
+sdlab export build [--snapshot <id>]      # Build versioned export package
+sdlab eval-pack build                     # Build canon-aware eval pack
 ```
 
 All commands accept `--project <name>` (default: `star-freight`).
@@ -74,24 +93,31 @@ projects/
     inputs/prompts/         Prompt packs (JSON)
     outputs/                Generated images (gitignored)
     comparisons/            A-vs-B preference judgments
-    exports/                Training data output (gitignored)
+    snapshots/              Frozen dataset snapshots
+    splits/                 Train/val/test partitions
+    exports/                Versioned export packages
+    eval-packs/             Canon-aware eval instruments
 ```
 
 ## Pipeline
 
 ```
-canon  -->  prompts  -->  generate  -->  curate  -->  bind  -->  compare  -->  export
- |            |             |              |           |            |            |
- rules      packs        ComfyUI       judgment    assertions   preferences   dataset
+canon → generate → curate → bind → snapshot → split → export → eval
+  |        |          |        |        |         |        |       |
+rules   ComfyUI   judgment  rules   frozen    subject  package  verify
+                                    selection isolation
 ```
 
 1. **Define canon** -- write your style constitution and review rubric
-2. **Create prompt packs** -- structured subjects with style prefix and variations
-3. **Generate** -- ComfyUI produces candidates with full provenance
-4. **Curate** -- approve/reject with per-dimension scores and failure modes
-5. **Bind** -- link each asset to constitution rules with pass/fail/partial verdicts
-6. **Compare** -- record pairwise preferences for DPO/ranking datasets
-7. **Export** -- produce training data via [`repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset) in 10+ formats
+2. **Generate** -- ComfyUI produces candidates with full provenance
+3. **Curate** -- approve/reject with per-dimension scores and failure modes
+4. **Bind** -- link each asset to constitution rules with pass/fail/partial verdicts
+5. **Snapshot** -- freeze eligible records into a deterministic, fingerprinted selection
+6. **Split** -- partition into train/val/test with subject isolation and lane balance
+7. **Export** -- build a self-contained package with manifest, metadata, images, and checksums
+8. **Eval** -- generate canon-aware test instruments for model verification
+
+Downstream format conversion (TRL, LLaVA, Parquet, etc.) is handled by [`repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset). `sdlab` owns dataset truth; `repo-dataset` renders it into specialized formats.
 
 ## Domain templates
 
@@ -105,17 +131,30 @@ Each domain template ships with lane definitions, constitution rules, scoring ru
 | **architecture** | exterior, interior, streetscape, structural_detail, ruin, landscape | Structural plausibility, material consistency, perspective, era coherence |
 | **vehicle-mech** | exterior, cockpit, component, schematic, silhouette_sheet, damage_variant | Mechanical logic, functional design language, access points, damage narrative |
 
-## The dataset angle
+## Dataset production
+
+The full dataset spine: snapshot, split, export, eval.
 
-The pipeline produces more than organized images. It produces **trustworthy, structured datasets** with:
+```
+snapshot  -->  split  -->  export  -->  eval-pack
+   |            |            |             |
+  frozen     subject      package       canon-aware
+  selection  isolation    (manifest,    test instruments
+             + lane       metadata,     (4 task types)
+             balance      images,
+                          checksums,
+                          card)
+```
+
+**Snapshots** freeze a deterministic selection of eligible records. Every inclusion has a reason trace. Config fingerprints ensure reproducibility.
+
+**Splits** assign records to train/val/test partitions with subject isolation (no subject family appears in multiple splits) and lane-balanced distribution. Seeded PRNG ensures identical results from the same seed.
 
-- **Full provenance** on every asset (reproducible generations)
-- **Canon-bound judgments** (not just labels -- reasoned verdicts against declared rules)
-- **Pairwise preferences** (for DPO and ranking-based training)
-- **Per-dimension scoring** (fine-grained quality signals, not just pass/fail)
-- **Failure mode tagging** (what specifically went wrong and which rules were violated)
+**Export packages** are self-contained: manifest, metadata.jsonl, images (symlinked or copied), splits, dataset card (markdown + JSON), and BSD-format checksums. Everything needed to rebuild the dataset from scratch.
 
-Export via `repo-dataset` to TRL, LLaVA, Qwen2-VL, JSONL, Parquet, and more.
+**Eval packs** are canon-aware test instruments with four task types: lane coverage, forbidden drift, anchor/gold, and subject continuity. They prove the dataset spine is feeding future model evaluation, not just dumping files.
+
+Export to downstream formats via [`repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset) (TRL, LLaVA, Qwen2-VL, JSONL, Parquet, and more). `repo-dataset` handles format conversion; `sdlab` owns dataset truth.
 
 ## Star Freight example
 
@@ -124,8 +163,15 @@ Clone the repo for a complete working example: 1,182 records, 28 prompt waves, 5
 ```bash
 git clone https://github.com/mcp-tool-shop-org/style-dataset-lab
 cd style-dataset-lab
-sdlab bind --stats --project star-freight
+
+# Validate the project
 sdlab project doctor --project star-freight
+
+# Run the full dataset spine
+sdlab snapshot create --project star-freight    # 839 eligible records
+sdlab split build --project star-freight        # ~80/10/10, zero leakage
+sdlab export build --project star-freight       # package with checksums
+sdlab eval-pack build --project star-freight    # 78 eval records
 ```
 
 ## Migrating from v1.x

package/bin/sdlab.js

@@ -20,6 +20,12 @@ const COMMANDS = {
   'painterly':           '../scripts/painterly.js',
   'painterly:test':      '../scripts/painterly-test.js',
   'migrate':             '../scripts/migrate-records.js',
+  'snapshot':            '../scripts/snapshot.js',
+  'eligibility':         '../scripts/eligibility.js',
+  'split':               '../scripts/split.js',
+  'card':                '../scripts/card.js',
+  'export':              '../scripts/export.js',
+  'eval-pack':           '../scripts/eval-pack.js',
 };
 
 // Two-word commands under "project" namespace
@@ -47,6 +53,23 @@ function printHelp() {
   console.log('  painterly            Post-processing painterly style pass');
   console.log('  painterly:test       Test denoise levels on reference images');
   console.log('');
+  console.log('Dataset:');
+  console.log('  snapshot create      Create a frozen dataset snapshot');
+  console.log('  snapshot list        List all snapshots');
+  console.log('  snapshot show <id>   Show snapshot details');
+  console.log('  snapshot diff <a> <b> Compare two snapshots');
+  console.log('  eligibility audit    Audit record training eligibility');
+  console.log('  split build          Build train/val/test split from snapshot');
+  console.log('  split list           List all splits');
+  console.log('  split show <id>      Show split details');
+  console.log('  split audit <id>     Audit split for leakage and balance');
+  console.log('  card generate        Generate dataset card (markdown + JSON)');
+  console.log('  export build         Build self-contained export package');
+  console.log('  export list          List all export packages');
+  console.log('  eval-pack build      Build canon-aware eval pack');
+  console.log('  eval-pack list       List eval packs');
+  console.log('  eval-pack show <id>  Show eval pack details');
+  console.log('');
   console.log('Options:');
   console.log('  --project <name>     Project to operate on (default: star-freight)');
   console.log('  --game <name>        Deprecated alias for --project');

package/lib/card.js

@@ -0,0 +1,145 @@
+/**
+ * Dataset card generation — markdown + JSON twin.
+ *
+ * Produces a human-readable dataset card summarizing provenance,
+ * selection criteria, split strategy, and distribution statistics.
+ */
+
+import { loadSnapshot, loadSnapshotIncluded } from './snapshot.js';
+import { loadSplit, loadSplitAudit } from './split.js';
+import { loadProjectConfig } from './config.js';
+
+/**
+ * Generate a dataset card from snapshot + split + project config.
+ *
+ * @param {string} projectRoot
+ * @param {string} snapshotId
+ * @param {string} splitId
+ * @returns {Promise<{markdown: string, json: Object}>}
+ */
+export async function generateCard(projectRoot, snapshotId, splitId) {
+  const config = loadProjectConfig(projectRoot);
+  const snapshot = await loadSnapshot(projectRoot, snapshotId);
+  const split = await loadSplit(projectRoot, splitId);
+  const audit = await loadSplitAudit(projectRoot, splitId);
+  const included = await loadSnapshotIncluded(projectRoot, snapshotId);
+
+  const json = {
+    dataset_name: `${config.meta.name}-visual`,
+    version: config.meta.version || '1.0.0',
+    created_at: new Date().toISOString(),
+    created_by: 'sdlab-card-v1',
+    project: {
+      name: config.meta.name,
+      display_name: config.meta.display_name,
+      domain: config.meta.domain,
+    },
+    snapshot: {
+      id: snapshot.snapshot_id,
+      created_at: snapshot.created_at,
+      config_fingerprint: snapshot.config_fingerprint,
+      total_records: snapshot.counts.total_records,
+      included: snapshot.counts.included,
+      excluded: snapshot.counts.excluded,
+    },
+    selection: snapshot.selection_profile,
+    split: {
+      id: split.split_id,
+      strategy: split.profile.strategy,
+      seed: split.profile.seed,
+      ratios: {
+        train: split.profile.train_ratio,
+        val: split.profile.val_ratio,
+        test: split.profile.test_ratio,
+      },
+      counts: split.counts,
+      leakage_free: audit.leakage_check.passed,
+    },
+    lane_balance: audit.lane_balance,
+    constitution: {
+      rule_count: config.constitution.rules?.length || 0,
+    },
+    rubric: {
+      dimension_count: config.rubric.dimensions?.length || 0,
+      thresholds: config.rubric.thresholds,
+    },
+  };
+
+  const markdown = renderMarkdown(json, config);
+
+  return { markdown, json };
+}
+
+function renderMarkdown(card, config) {
+  const lines = [];
+  const add = (s = '') => lines.push(s);
+
+  add(`# ${card.dataset_name}`);
+  add();
+  add(`**Project:** ${card.project.display_name}  `);
+  add(`**Domain:** ${card.project.domain}  `);
+  add(`**Version:** ${card.version}  `);
+  add(`**Generated:** ${card.created_at}  `);
+  add();
+
+  add('## Selection');
+  add();
+  add(`- **Snapshot:** \`${card.snapshot.id}\``);
+  add(`- **Config fingerprint:** \`${card.snapshot.config_fingerprint.slice(0, 16)}...\``);
+  add(`- **Total records evaluated:** ${card.snapshot.total_records}`);
+  add(`- **Included:** ${card.snapshot.included} (${(card.snapshot.included / card.snapshot.total_records * 100).toFixed(1)}%)`);
+  add(`- **Excluded:** ${card.snapshot.excluded}`);
+  add();
+
+  add('### Selection criteria');
+  add();
+  const sel = card.selection;
+  if (sel.require_judgment) add('- Requires human judgment');
+  if (sel.require_status?.length) add(`- Status: ${sel.require_status.join(', ')}`);
+  if (sel.require_canon_bound) add('- Must be canon-bound (constitution assertions)');
+  if (sel.minimum_pass_ratio != null) add(`- Minimum pass ratio: ${(sel.minimum_pass_ratio * 100).toFixed(0)}%`);
+  add();
+
+  add('## Split');
+  add();
+  add(`- **Split ID:** \`${card.split.id}\``);
+  add(`- **Strategy:** ${card.split.strategy}`);
+  add(`- **Seed:** ${card.split.seed}`);
+  add(`- **Subject leakage:** ${card.split.leakage_free ? 'None (verified)' : 'DETECTED'}`);
+  add();
+
+  add('| Partition | Records | % |');
+  add('|-----------|---------|---|');
+  const total = card.split.counts.total_records;
+  add(`| Train | ${card.split.counts.train} | ${(card.split.counts.train / total * 100).toFixed(1)}% |`);
+  add(`| Val | ${card.split.counts.val} | ${(card.split.counts.val / total * 100).toFixed(1)}% |`);
+  add(`| Test | ${card.split.counts.test} | ${(card.split.counts.test / total * 100).toFixed(1)}% |`);
+  add();
+
+  add('## Lane Balance');
+  add();
+  add('| Lane | Total | Train% | Val% | Test% |');
+  add('|------|-------|--------|------|-------|');
+  for (const [lane, b] of Object.entries(card.lane_balance).sort((a, b) => b[1].total - a[1].total)) {
+    add(`| ${lane} | ${b.total} | ${b.train_pct}% | ${b.val_pct}% | ${b.test_pct}% |`);
+  }
+  add();
+
+  add('## Quality Gates');
+  add();
+  add(`- **Constitution rules:** ${card.constitution.rule_count}`);
+  add(`- **Rubric dimensions:** ${card.rubric.dimension_count}`);
+  if (card.rubric.thresholds) {
+    add(`- **Pass threshold:** ${(card.rubric.thresholds.pass * 100).toFixed(0)}%`);
+  }
+  add();
+
+  add('## Provenance');
+  add();
+  add('This dataset was produced by [Style Dataset Lab](https://github.com/mcp-tool-shop-org/style-dataset-lab).');
+  add('Every included record has been human-reviewed, canon-bound, and verified against project constitution rules.');
+  add('Split strategy ensures no subject appears in multiple partitions.');
+  add();
+
+  return lines.join('\n');
+}

package/lib/config.js

@@ -102,3 +102,147 @@ export function loadProjectConfig(projectRoot) {
     terminology: loadTerminology(projectRoot),
   };
 }
+
+// ─── Profile Loaders ─────────────────────────────────────────────────
+
+const DEFAULT_SELECTION_PROFILE = {
+  require_judgment: true,
+  require_status: ['approved'],
+  require_canon_bound: true,
+  minimum_pass_ratio: 0.5,
+  rights_filter: null,
+  exclude_lanes: [],
+  max_per_subject: null,
+  max_per_lane: null,
+};
+
+const DEFAULT_SPLIT_PROFILE = {
+  profile_id: 'balanced-default',
+  strategy: 'subject-isolated',
+  train_ratio: 0.8,
+  val_ratio: 0.1,
+  test_ratio: 0.1,
+  lane_balance: true,
+  subject_isolation: true,
+  seed: 42,
+};
+
+const DEFAULT_EXPORT_PROFILE = {
+  profile_id: 'canonical-package',
+  include_images: true,
+  image_strategy: 'symlink',
+  include_splits: true,
+  include_card: true,
+  include_checksums: true,
+  metadata_fields: ['id', 'asset_path', 'provenance', 'judgment', 'canon', 'identity', 'lineage'],
+};
+
+/**
+ * Load a selection profile from project or return built-in default.
+ */
+export function loadSelectionProfile(projectRoot, profileId) {
+  if (!profileId) return { ...DEFAULT_SELECTION_PROFILE };
+  const data = loadJsonFile(join(projectRoot, 'selection-profiles', `${profileId}.json`));
+  if (!data) return { ...DEFAULT_SELECTION_PROFILE };
+  return { ...DEFAULT_SELECTION_PROFILE, ...data };
+}
+
+/**
+ * Load a split profile from project or return built-in default.
+ */
+export function loadSplitProfile(projectRoot, profileId) {
+  if (!profileId) return { ...DEFAULT_SPLIT_PROFILE };
+  const data = loadJsonFile(join(projectRoot, 'split-profiles', `${profileId}.json`));
+  if (!data) return { ...DEFAULT_SPLIT_PROFILE };
+  return { ...DEFAULT_SPLIT_PROFILE, ...data };
+}
+
+/**
+ * Load an export profile from project or return built-in default.
+ */
+export function loadExportProfile(projectRoot, profileId) {
+  if (!profileId) return { ...DEFAULT_EXPORT_PROFILE };
+  const data = loadJsonFile(join(projectRoot, 'export-profiles', `${profileId}.json`));
+  if (!data) return { ...DEFAULT_EXPORT_PROFILE };
+  return { ...DEFAULT_EXPORT_PROFILE, ...data };
+}
+
+// ─── Detection Functions ─────────────────────────────────────────────
+// Extracted from scripts/canon-bind.js for reuse in eligibility,
+// snapshot, and split modules.
+
+/**
+ * Detect lane from asset ID using project lane config.
+ * Tests each lane's id_patterns as regex against the lowercase ID.
+ * Returns the first match, or the default_lane.
+ */
+export function detectLane(id, prompt, lanesConfig) {
+  const lower = id.toLowerCase();
+  for (const lane of lanesConfig.lanes) {
+    if (!lane.id_patterns || lane.id_patterns.length === 0) continue;
+    for (const pattern of lane.id_patterns) {
+      if (new RegExp(pattern).test(lower)) return lane.id;
+    }
+  }
+  return lanesConfig.default_lane;
+}
+
+/**
+ * Detect group (faction) from asset ID and prompt using terminology config.
+ * Uses explicit id_detection_order and prompt_detection_order when provided
+ * to preserve the exact detection priority of the original implementation.
+ */
+export function detectGroup(id, prompt, termConfig) {
+  const idOrder = termConfig.id_detection_order || Object.keys(termConfig.groups);
+  const promptOrder = termConfig.prompt_detection_order || Object.keys(termConfig.groups);
+
+  // 1. Primary ID patterns per group (id_detection_order)
+  for (const groupName of idOrder) {
+    const group = termConfig.groups[groupName];
+    if (!group?.id_patterns) continue;
+    for (const pattern of group.id_patterns) {
+      if (new RegExp(pattern).test(id)) return groupName;
+    }
+  }
+
+  // 2. Cross-group patterns
+  for (const [pattern, behavior] of Object.entries(termConfig.cross_group_patterns || {})) {
+    if (new RegExp(pattern).test(id)) {
+      if (behavior === 'detect_from_id_suffix') {
+        for (const groupName of idOrder) {
+          if (id.includes(groupName)) return groupName;
+        }
+      }
+      return null;
+    }
+  }
+
+  // 3. Edge defaults
+  for (const [pattern, groupName] of Object.entries(termConfig.edge_defaults || {})) {
+    if (new RegExp(pattern).test(id)) return groupName;
+  }
+
+  // 4. Prompt-based fallback (prompt_detection_order)
+  if (prompt) {
+    const p = prompt.toLowerCase();
+    for (const groupName of promptOrder) {
+      const group = termConfig.groups[groupName];
+      if (!group?.prompt_patterns || group.prompt_patterns.length === 0) continue;
+      for (const keyword of group.prompt_patterns) {
+        if (new RegExp(keyword).test(p)) return groupName;
+      }
+    }
+  }
+
+  // 5. Null-faction patterns (generic rejects — no faction)
+  for (const pattern of termConfig.null_faction_patterns || []) {
+    if (new RegExp(pattern).test(id)) return null;
+  }
+
+  // 6. ID fallback patterns
+  for (const [pattern, groupName] of Object.entries(termConfig.id_fallbacks || {})) {
+    if (new RegExp(pattern).test(id)) return groupName;
+  }
+
+  return null;
+}

package/lib/eligibility.js

@@ -0,0 +1,110 @@
+/**
+ * Eligibility evaluation engine.
+ *
+ * Determines whether each record qualifies for inclusion in a dataset
+ * snapshot, with explicit reason traces for every decision.
+ */
+
+import { detectLane, detectGroup } from './config.js';
+
+/**
+ * Evaluate a single record against a selection profile.
+ * @param {Object} record — full record object
+ * @param {Object} profile — selection profile
+ * @param {Object} lanesConfig — from lanes.json
+ * @param {Object} termConfig — from terminology.json
+ * @returns {{ eligible: boolean, reasons: string[] }}
+ */
+export function evaluateEligibility(record, profile, lanesConfig, termConfig) {
+  const reasons = [];
+
+  // 1. Judgment required
+  if (profile.require_judgment) {
+    if (!record.judgment) {
+      reasons.push('no judgment (record has not been reviewed)');
+    }
+  }
+
+  // 2. Status filter
+  if (profile.require_status?.length > 0 && record.judgment) {
+    if (!profile.require_status.includes(record.judgment.status)) {
+      reasons.push(`status "${record.judgment.status}" not in [${profile.require_status.join(', ')}]`);
+    }
+  }
+
+  // 3. Canon bound
+  if (profile.require_canon_bound) {
+    if (!record.canon?.assertions || record.canon.assertions.length === 0) {
+      reasons.push('not canon-bound (no assertions)');
+    }
+  }
+
+  // 4. Minimum pass ratio
+  if (profile.minimum_pass_ratio != null && record.canon?.assertion_count > 0) {
+    const ratio = record.canon.pass_count / record.canon.assertion_count;
+    if (ratio < profile.minimum_pass_ratio) {
+      reasons.push(`pass ratio ${(ratio * 100).toFixed(0)}% below minimum ${(profile.minimum_pass_ratio * 100).toFixed(0)}%`);
+    }
+  }
+
+  // 5. Lane exclusion
+  if (profile.exclude_lanes?.length > 0) {
+    const prompt = record.provenance?.prompt || '';
+    const lane = detectLane(record.id, prompt, lanesConfig);
+    if (profile.exclude_lanes.includes(lane)) {
+      reasons.push(`lane "${lane}" is excluded`);
+    }
+  }
+
+  // 6. Rights filter
+  if (profile.rights_filter != null) {
+    const rights = record.rights_status || record.training_rights_status || null;
+    if (rights !== profile.rights_filter) {
+      reasons.push(`rights "${rights || 'unknown'}" does not match required "${profile.rights_filter}"`);
+    }
+  }
+
+  // 7. Tag exclusion
+  if (profile.exclude_tags?.length > 0 && record.dataset_tags) {
+    const excluded = record.dataset_tags.filter(t => profile.exclude_tags.includes(t));
+    if (excluded.length > 0) {
+      reasons.push(`has excluded tags: ${excluded.join(', ')}`);
+    }
+  }
+
+  return {
+    eligible: reasons.length === 0,
+    reasons,
+  };
+}
+
+/**
+ * Categorize exclusion reasons for a set of records.
+ * @param {Array<{record_id: string, reasons: string[]}>} excluded
+ * @returns {Object} — category → count mapping
+ */
+export function categorizeExclusions(excluded) {
+  const categories = {
+    no_judgment: 0,
+    wrong_status: 0,
+    not_canon_bound: 0,
+    low_pass_ratio: 0,
+    excluded_lane: 0,
+    rights_filter: 0,
+    excluded_tags: 0,
+  };
+
+  for (const { reasons } of excluded) {
+    for (const r of reasons) {
+      if (r.includes('no judgment')) categories.no_judgment++;
+      else if (r.includes('status')) categories.wrong_status++;
+      else if (r.includes('canon-bound')) categories.not_canon_bound++;
+      else if (r.includes('pass ratio')) categories.low_pass_ratio++;
+      else if (r.includes('lane')) categories.excluded_lane++;
+      else if (r.includes('rights')) categories.rights_filter++;
+      else if (r.includes('tags')) categories.excluded_tags++;
+    }
+  }
+
+  return categories;
+}