@simulatte/doppler 0.1.5 → 0.1.6

package/src/training/checkpoint.js

@@ -184,12 +184,22 @@ export async function saveCheckpoint(key, payload, options = {}) {
 
   if (useNodeStore) {
     await writeNodeCheckpointRecord(nodePath, data);
-    return;
+    return {
+      key,
+      path: nodePath,
+      metadata: data.metadata,
+      data,
+    };
   }
 
   return new Promise((resolve, reject) => {
     const tx = browserStore.db.transaction(browserStore.storeName, 'readwrite');
-    tx.oncomplete = () => resolve();
+    tx.oncomplete = () => resolve({
+      key,
+      path: null,
+      metadata: data.metadata,
+      data,
+    });
     tx.onerror = () => reject(tx.error);
     const store = tx.objectStore(browserStore.storeName);
     store.put(data, key);

package/src/training/distillation/artifacts.d.ts

@@ -0,0 +1,71 @@
+import type { LoadedTrainingWorkload } from '../workloads.js';
+
+export declare function createDistillationRunArtifacts(options: {
+  loadedWorkload: LoadedTrainingWorkload;
+  runRoot?: string | null;
+  timestamp?: string | Date | null;
+}): Promise<{
+  layout: {
+    runRoot: string;
+    logs: string;
+    checkpoints: string;
+    eval: string;
+    scoreboard: string;
+    exports: string;
+    compare: string;
+    qualityGate: string;
+  };
+  runContract: { path: string; sha256: string; relativePath: string };
+  workloadLock: { path: string; sha256: string; relativePath: string };
+  runContractPayload: Record<string, unknown>;
+}>;
+
+export declare function writeDistillStageManifest(
+  layout: Record<string, string>,
+  payload: Record<string, unknown>
+): Promise<{ path: string; sha256: string; relativePath: string }>;
+
+export declare function writeDistillCheckpointMetadata(
+  layout: Record<string, string>,
+  stageId: string,
+  checkpointId: string,
+  payload: Record<string, unknown>
+): Promise<{ path: string; sha256: string; relativePath: string }>;
+
+export declare function writeDistillCheckpointComplete(
+  layout: Record<string, string>,
+  stageId: string,
+  checkpointId: string,
+  payload: Record<string, unknown>
+): Promise<{ path: string; sha256: string; relativePath: string }>;
+
+export declare function writeDistillEvalReport(
+  layout: Record<string, string>,
+  payload: Record<string, unknown>
+): Promise<{ path: string; sha256: string; relativePath: string }>;
+
+export declare function writeDistillCompareReport(
+  layout: Record<string, string>,
+  payload: Record<string, unknown>
+): Promise<{ path: string; sha256: string; relativePath: string }>;
+
+export declare function writeDistillQualityGateReport(
+  layout: Record<string, string>,
+  payload: Record<string, unknown>
+): Promise<{ path: string; sha256: string; relativePath: string }>;
+
+export declare function buildDistillArtifactBase(
+  loadedWorkload: LoadedTrainingWorkload,
+  options: {
+    prefix?: string;
+    artifactType: string;
+    datasetPath?: string | null;
+    datasetHash?: string | null;
+    stage?: string | null;
+    checkpointStep?: number | null;
+    parentArtifacts?: Array<Record<string, unknown>>;
+    runtime?: string;
+    surface?: string;
+    configHash?: string | null;
+  }
+): Record<string, unknown>;

package/src/training/distillation/artifacts.js

@@ -0,0 +1,132 @@
+import { mkdir } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+
+import {
+  buildArtifactBase,
+  createTrainingRunLayout,
+  hashArtifactPayload,
+  writeJsonArtifact,
+  writeRunContract,
+  writeWorkloadLock,
+} from '../operator-artifacts.js';
+
+function toReportId(prefix, workloadId, suffix) {
+  return `${prefix}_${workloadId}_${suffix}`;
+}
+
+export async function createDistillationRunArtifacts(options) {
+  const loadedWorkload = options.loadedWorkload;
+  const workload = loadedWorkload?.workload;
+  if (!workload || workload.kind !== 'distill') {
+    throw new Error('createDistillationRunArtifacts requires a distill workload pack.');
+  }
+  const layout = options.runRoot
+    ? {
+      runRoot: resolve(String(options.runRoot)),
+      logs: join(resolve(String(options.runRoot)), 'logs'),
+      checkpoints: join(resolve(String(options.runRoot)), 'checkpoints'),
+      eval: join(resolve(String(options.runRoot)), 'eval'),
+      scoreboard: join(resolve(String(options.runRoot)), 'scoreboard'),
+      exports: join(resolve(String(options.runRoot)), 'exports'),
+      compare: join(resolve(String(options.runRoot)), 'compare'),
+      qualityGate: join(resolve(String(options.runRoot)), 'quality-gate'),
+    }
+    : await createTrainingRunLayout({
+      kind: 'distill',
+      workloadId: workload.id,
+      timestamp: options.timestamp || null,
+    });
+  await Promise.all(
+    Object.values(layout).map((dirPath) => mkdir(dirPath, { recursive: true }))
+  );
+  const runContractPayload = {
+    artifactType: 'training_run_contract',
+    schemaVersion: 1,
+    generatedAt: new Date().toISOString(),
+    workloadId: workload.id,
+    workloadPath: loadedWorkload.absolutePath,
+    workloadSha256: loadedWorkload.workloadSha256,
+    configHash: workload.configHash,
+    claimBoundary: workload.claimBoundary,
+    kind: workload.kind,
+    stagePlan: workload.pipeline.stagePlan,
+    datasetPath: workload.datasetPath,
+    evalDatasets: workload.evalDatasets,
+    surfaceSupport: workload.surfaceSupport,
+  };
+  const runContract = await writeRunContract(layout, runContractPayload);
+  const workloadLock = await writeWorkloadLock(layout, loadedWorkload);
+  return {
+    layout,
+    runContract,
+    workloadLock,
+    runContractPayload,
+  };
+}
+
+export async function writeDistillStageManifest(layout, payload) {
+  const stageId = String(payload?.stageId || payload?.stage || 'stage').trim();
+  const filePath = join(layout.checkpoints, stageId, 'distill_stage_manifest.json');
+  return writeJsonArtifact(filePath, payload);
+}
+
+export async function writeDistillCheckpointMetadata(layout, stageId, checkpointId, payload) {
+  const filePath = join(layout.checkpoints, stageId, checkpointId, 'checkpoint.json');
+  return writeJsonArtifact(filePath, payload);
+}
+
+export async function writeDistillCheckpointComplete(layout, stageId, checkpointId, payload) {
+  const filePath = join(layout.checkpoints, stageId, checkpointId, 'checkpoint.complete.json');
+  return writeJsonArtifact(filePath, payload);
+}
+
+export async function writeDistillEvalReport(layout, payload) {
+  const stageId = String(payload?.stage || 'stage').trim();
+  const checkpointId = String(payload?.checkpointId || 'checkpoint').trim();
+  const evalDatasetId = String(payload?.evalDatasetId || 'eval').trim();
+  const filePath = join(layout.eval, stageId, `${checkpointId}__${evalDatasetId}.json`);
+  return writeJsonArtifact(filePath, payload);
+}
+
+export async function writeDistillCompareReport(layout, payload) {
+  return writeJsonArtifact(join(layout.compare, 'compare.json'), payload);
+}
+
+export async function writeDistillQualityGateReport(layout, payload) {
+  return writeJsonArtifact(join(layout.qualityGate, 'quality-gate.json'), payload);
+}
+
+export function buildDistillArtifactBase(loadedWorkload, options) {
+  const workload = loadedWorkload.workload;
+  const checkpointStep = Number.isInteger(options.checkpointStep)
+    ? options.checkpointStep
+    : null;
+  const reportId = toReportId(
+    options.prefix || 'dst',
+    workload.id,
+    `${options.stage || 'stage'}_${checkpointStep == null ? 'final' : String(checkpointStep).padStart(6, '0')}`
+  );
+  const payload = buildArtifactBase({
+    artifactType: options.artifactType,
+    reportId,
+    workload,
+    workloadPath: loadedWorkload.absolutePath,
+    workloadSha256: loadedWorkload.workloadSha256,
+    datasetPath: options.datasetPath || workload.datasetPath,
+    datasetHash: options.datasetHash || null,
+    baseModelId: workload.baseModelId,
+    teacherModelId: workload.teacherModelId,
+    studentModelId: workload.studentModelId,
+    stage: options.stage || null,
+    checkpointStep,
+    parentArtifacts: options.parentArtifacts || [],
+    runtime: options.runtime || 'node',
+    surface: options.surface || 'node',
+    claimBoundary: workload.claimBoundary,
+    configHash: options.configHash || workload.configHash,
+  });
+  return {
+    ...payload,
+    artifactHash: hashArtifactPayload(payload),
+  };
+}

package/src/training/distillation/checkpoint-watch.d.ts

@@ -0,0 +1,10 @@
+import type { LoadedTrainingWorkload } from '../workloads.js';
+
+export declare function watchDistillationCheckpoints(options: {
+  loadedWorkload: LoadedTrainingWorkload;
+  layout: Record<string, string>;
+  checkpointsDir?: string | null;
+  manifestPath?: string | null;
+  pollIntervalMs?: number | null;
+  stopWhenIdle?: boolean;
+}): Promise<{ ok: true; processedCount: number; manifestPath: string }>;

package/src/training/distillation/checkpoint-watch.js

@@ -0,0 +1,57 @@
+import { join, resolve } from 'node:path';
+
+import { watchFinalizedCheckpoints } from '../checkpoint-watch.js';
+import { appendDistillationScoreboardRow } from './scoreboard.js';
+import { evaluateDistillationCheckpoint, readDistillCheckpointMarker } from './eval.js';
+
+export async function watchDistillationCheckpoints(options) {
+  const layout = options.layout;
+  const loadedWorkload = options.loadedWorkload;
+  const checkpointsDir = resolve(options.checkpointsDir || layout.checkpoints);
+  const manifestPath = resolve(options.manifestPath || join(layout.scoreboard, 'checkpoint-watch-manifest.json'));
+  return watchFinalizedCheckpoints({
+    checkpointsDir,
+    manifestPath,
+    pollIntervalMs: options.pollIntervalMs || 2000,
+    stopWhenIdle: options.stopWhenIdle === true,
+    onCheckpoint: async (markerPath) => {
+      const { marker } = await readDistillCheckpointMarker(markerPath);
+      const reports = await evaluateDistillationCheckpoint({
+        loadedWorkload,
+        checkpointPath: marker.checkpointPath,
+        checkpointId: marker.checkpointId,
+        checkpointStep: marker.checkpointStep,
+        stageId: marker.stage,
+        layout,
+        stageAArtifact: marker.stageArtifact || null,
+        stageAArtifactHash: marker.stageArtifactHash || null,
+      });
+      for (const report of reports) {
+        await appendDistillationScoreboardRow(layout, String(marker.stage || 'stage'), {
+          artifactType: 'training_scoreboard',
+          schemaVersion: 1,
+          generatedAt: new Date().toISOString(),
+          stage: marker.stage,
+          checkpointId: report.checkpointId,
+          checkpointStep: report.checkpointStep,
+          evalDatasetId: report.evalDatasetId,
+          selectionMetric: report.primaryMetric,
+          selectionGoal: 'max',
+          primaryMetric: report.primaryMetric,
+          primaryScore: report.primaryScore,
+          bleu: report.bleu,
+          chrf: report.chrf,
+          reportPath: report.reportPath || null,
+          metrics: {
+            bleu: report.bleu,
+            chrf: report.chrf,
+            primaryScore: report.primaryScore,
+          },
+        }, {
+          selectionMetric: report.primaryMetric,
+          selectionGoal: 'max',
+        });
+      }
+    },
+  });
+}

package/src/training/distillation/dataset.d.ts

@@ -0,0 +1,59 @@
+export interface CanonicalTranslationRow {
+  row_id: string;
+  src_lang: string | null;
+  tgt_lang: string | null;
+  pair: string | null;
+  source: string;
+  target_pos: string;
+  target_neg: string | null;
+}
+
+export interface CanonicalTranslationDataset {
+  absolutePath: string;
+  raw: string;
+  rows: CanonicalTranslationRow[];
+  rowCount: number;
+  directionCounts: Record<string, number>;
+  datasetHash: string;
+  canonicalHash: string;
+  rowIdsHash: string;
+}
+
+export declare function normalizeDistillationPair(
+  value: unknown,
+  srcLang?: string | null,
+  tgtLang?: string | null
+): string | null;
+
+export declare function normalizeTranslationPairRow(
+  record: Record<string, unknown>,
+  index: number,
+  options?: { strictPairContract?: boolean }
+): CanonicalTranslationRow | null;
+
+export declare function loadCanonicalTranslationDataset(
+  datasetPath: string,
+  options?: {
+    strictPairContract?: boolean;
+    sourceLangs?: string[] | string | null;
+    targetLangs?: string[] | string | null;
+    pairAllowlist?: string[] | string | null;
+  }
+): Promise<CanonicalTranslationDataset>;
+
+export declare function buildFrozenSubset(options: {
+  datasetPath: string;
+  outputDir: string;
+  strictPairContract?: boolean;
+  sourceLangs?: string[] | string | null;
+  targetLangs?: string[] | string | null;
+  pairAllowlist?: string[] | string | null;
+  subsetSpec?: Record<string, unknown> | null;
+}): Promise<{
+  dataset: CanonicalTranslationDataset;
+  subsetRows: CanonicalTranslationRow[];
+  subsetJsonlPath: string;
+  rowIdsPath: string;
+  manifestPath: string;
+  manifest: Record<string, unknown>;
+}>;

package/src/training/distillation/dataset.js

@@ -0,0 +1,337 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+
+import { parseJsonl } from '../datasets/jsonl.js';
+import { sha256Hex } from '../../utils/sha256.js';
+
+function stableSortObject(value) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => stableSortObject(entry));
+  }
+  if (!value || typeof value !== 'object') {
+    return value;
+  }
+  const sorted = {};
+  for (const key of Object.keys(value).sort()) {
+    sorted[key] = stableSortObject(value[key]);
+  }
+  return sorted;
+}
+
+function stableJson(value) {
+  return JSON.stringify(stableSortObject(value));
+}
+
+function asOptionalString(value) {
+  if (value === undefined || value === null) return null;
+  const trimmed = String(value).trim();
+  return trimmed || null;
+}
+
+function asOptionalStringArray(value) {
+  if (value === undefined || value === null) return null;
+  const input = Array.isArray(value)
+    ? value
+    : (typeof value === 'string' ? value.split(',') : null);
+  if (!Array.isArray(input)) {
+    return null;
+  }
+  const normalized = input
+    .map((entry) => asOptionalString(entry))
+    .filter(Boolean);
+  return normalized.length > 0 ? normalized : null;
+}
+
+function normalizeLangCode(value) {
+  const normalized = asOptionalString(value);
+  if (!normalized) return null;
+  const compact = normalized.toLowerCase().replace(/_/g, '-');
+  if (compact.startsWith('en')) return 'en';
+  if (compact.startsWith('es')) return 'es';
+  return compact;
+}
+
+export function normalizeDistillationPair(value, srcLang = null, tgtLang = null) {
+  const pair = asOptionalString(value);
+  if (!pair) {
+    if (!srcLang || !tgtLang) return null;
+    return `${srcLang}->${tgtLang}`;
+  }
+  const normalized = pair.toLowerCase().replace(/_/g, '-').replace(/\s+/g, '');
+  const separator = normalized.includes('->') ? '->' : '-';
+  const parts = normalized.split(separator).filter(Boolean);
+  if (parts.length !== 2) return null;
+  const source = normalizeLangCode(parts[0]) || parts[0];
+  const target = normalizeLangCode(parts[1]) || parts[1];
+  return `${source}->${target}`;
+}
+
+function resolveStringCandidate(record, keys) {
+  for (const key of keys) {
+    const value = asOptionalString(record?.[key]);
+    if (value) return value;
+  }
+  return null;
+}
+
+function resolveStableRowId(record, index, canonical) {
+  const explicit = asOptionalString(record?.row_id ?? record?.rowId);
+  if (explicit) return explicit;
+  return sha256Hex(stableJson({
+    index,
+    src_lang: canonical.src_lang,
+    tgt_lang: canonical.tgt_lang,
+    pair: canonical.pair,
+    source: canonical.source,
+    target_pos: canonical.target_pos,
+    target_neg: canonical.target_neg,
+  }));
+}
+
+export function normalizeTranslationPairRow(record, index, options = {}) {
+  if (!record || typeof record !== 'object' || Array.isArray(record)) {
+    return null;
+  }
+  const source = resolveStringCandidate(record, ['source', 'query', 'prompt']);
+  const targetPos = resolveStringCandidate(record, ['target_pos', 'target', 'pos', 'completion']);
+  const targetNeg = resolveStringCandidate(record, ['target_neg', 'neg']);
+  if (!source || !targetPos) {
+    return null;
+  }
+  const srcLang = normalizeLangCode(record?.src_lang ?? record?.source_lang);
+  const tgtLang = normalizeLangCode(record?.tgt_lang ?? record?.target_lang ?? record?.lang);
+  const pair = normalizeDistillationPair(record?.pair, srcLang, tgtLang);
+  const strict = options.strictPairContract === true;
+  if (strict) {
+    if (!srcLang || !tgtLang) {
+      throw new Error('strictPairContract requires src_lang and tgt_lang on each row.');
+    }
+    if (!pair) {
+      throw new Error('strictPairContract requires pair on each row.');
+    }
+    if (pair !== `${srcLang}->${tgtLang}`) {
+      throw new Error(`row pair "${record?.pair}" does not match src/tgt "${srcLang}->${tgtLang}".`);
+    }
+  }
+  const canonical = {
+    src_lang: srcLang,
+    tgt_lang: tgtLang,
+    pair: pair || null,
+    source,
+    target_pos: targetPos,
+    target_neg: targetNeg,
+  };
+  canonical.row_id = resolveStableRowId(record, index, canonical);
+  return canonical;
+}
+
+function normalizeFilterSet(value, normalizer) {
+  const entries = asOptionalStringArray(value);
+  if (!entries) return null;
+  const normalized = entries
+    .map((entry) => normalizer(entry))
+    .filter(Boolean);
+  return normalized.length > 0 ? new Set(normalized) : null;
+}
+
+function applyDatasetFilters(rows, options = {}) {
+  const sourceLangs = normalizeFilterSet(options.sourceLangs, normalizeLangCode);
+  const targetLangs = normalizeFilterSet(options.targetLangs, normalizeLangCode);
+  const pairs = normalizeFilterSet(options.pairAllowlist, normalizeDistillationPair);
+  return rows.filter((row) => {
+    if (sourceLangs && (!row.src_lang || !sourceLangs.has(row.src_lang))) {
+      return false;
+    }
+    if (targetLangs && (!row.tgt_lang || !targetLangs.has(row.tgt_lang))) {
+      return false;
+    }
+    if (pairs && (!row.pair || !pairs.has(row.pair))) {
+      return false;
+    }
+    return true;
+  });
+}
+
+function normalizeSubsetSpec(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return null;
+  }
+  const sizeRaw = Number(value.size ?? value.count ?? value.rowCount ?? 0);
+  const size = Number.isInteger(sizeRaw) && sizeRaw > 0 ? sizeRaw : null;
+  const seedRaw = Number(value.seed ?? 1337);
+  const seed = Number.isInteger(seedRaw) ? seedRaw : 1337;
+  const balanceBy = asOptionalString(value.balanceBy ?? value.allocationMode ?? value.stratifyBy);
+  return {
+    id: asOptionalString(value.id ?? value.name) || null,
+    size,
+    seed,
+    balanceBy,
+    parentSubsetManifest: asOptionalString(
+      value.parentSubsetManifest
+      ?? value.parentSubset
+      ?? value.parentManifest
+    ),
+  };
+}
+
+function buildDeterministicRank(seed, rowId) {
+  return sha256Hex(`${seed}:${rowId}`);
+}
+
+async function resolveParentRowIds(parentSubsetManifest) {
+  if (!parentSubsetManifest) return null;
+  const absolutePath = resolve(parentSubsetManifest);
+  const raw = await readFile(absolutePath, 'utf8');
+  const parsed = JSON.parse(raw);
+  const rowIds = Array.isArray(parsed?.rowIds)
+    ? parsed.rowIds
+    : [];
+  return rowIds.length > 0 ? new Set(rowIds.map((entry) => String(entry))) : new Set();
+}
+
+function buildPairBalancedSubset(rows, size, seed) {
+  const byPair = new Map();
+  for (const row of rows) {
+    const key = row.pair || 'unknown';
+    const bucket = byPair.get(key) || [];
+    bucket.push(row);
+    byPair.set(key, bucket);
+  }
+  for (const bucket of byPair.values()) {
+    bucket.sort((left, right) => {
+      const leftRank = buildDeterministicRank(seed, left.row_id);
+      const rightRank = buildDeterministicRank(seed, right.row_id);
+      return leftRank.localeCompare(rightRank);
+    });
+  }
+  const pairKeys = [...byPair.keys()].sort((left, right) => left.localeCompare(right));
+  const selected = [];
+  let cursor = 0;
+  while (selected.length < size) {
+    let progressed = false;
+    for (const pairKey of pairKeys) {
+      const bucket = byPair.get(pairKey);
+      if (!bucket || cursor >= bucket.length) continue;
+      selected.push(bucket[cursor]);
+      progressed = true;
+      if (selected.length >= size) break;
+    }
+    if (!progressed) break;
+    cursor += 1;
+  }
+  return selected;
+}
+
+function selectSubsetRows(rows, subsetSpec) {
+  if (!subsetSpec || !subsetSpec.size || subsetSpec.size >= rows.length) {
+    return rows.slice();
+  }
+  if (subsetSpec.balanceBy === 'pair' || subsetSpec.balanceBy === 'pair_balance') {
+    return buildPairBalancedSubset(rows, subsetSpec.size, subsetSpec.seed);
+  }
+  return rows
+    .slice()
+    .sort((left, right) => {
+      const leftRank = buildDeterministicRank(subsetSpec.seed, left.row_id);
+      const rightRank = buildDeterministicRank(subsetSpec.seed, right.row_id);
+      return leftRank.localeCompare(rightRank);
+    })
+    .slice(0, subsetSpec.size);
+}
+
+function computeDirectionCounts(rows) {
+  const counts = {};
+  for (const row of rows) {
+    const key = row.pair || 'unknown';
+    counts[key] = (counts[key] || 0) + 1;
+  }
+  return counts;
+}
+
+export async function loadCanonicalTranslationDataset(datasetPath, options = {}) {
+  const absolutePath = resolve(String(datasetPath));
+  const raw = await readFile(absolutePath, 'utf8');
+  const parsed = absolutePath.endsWith('.json')
+    ? JSON.parse(raw)
+    : parseJsonl(raw);
+  if (!Array.isArray(parsed)) {
+    throw new Error(`Distillation dataset "${absolutePath}" must be a JSON array or JSONL file.`);
+  }
+  const normalizedRows = [];
+  for (let index = 0; index < parsed.length; index += 1) {
+    const row = normalizeTranslationPairRow(parsed[index], index, options);
+    if (row) {
+      normalizedRows.push(row);
+    }
+  }
+  const filteredRows = applyDatasetFilters(normalizedRows, options);
+  if (filteredRows.length === 0) {
+    throw new Error(`Distillation dataset "${absolutePath}" has no usable rows after contract checks and filters.`);
+  }
+  const rowIds = filteredRows.map((row) => row.row_id);
+  return {
+    absolutePath,
+    raw,
+    rows: filteredRows,
+    rowCount: filteredRows.length,
+    directionCounts: computeDirectionCounts(filteredRows),
+    datasetHash: sha256Hex(raw),
+    canonicalHash: sha256Hex(stableJson(filteredRows)),
+    rowIdsHash: sha256Hex(rowIds.join('\n')),
+  };
+}
+
+export async function buildFrozenSubset(options) {
+  const dataset = await loadCanonicalTranslationDataset(options.datasetPath, {
+    strictPairContract: options.strictPairContract === true,
+    sourceLangs: options.sourceLangs,
+    targetLangs: options.targetLangs,
+    pairAllowlist: options.pairAllowlist,
+  });
+  const subsetSpec = normalizeSubsetSpec(options.subsetSpec);
+  const parentRowIds = subsetSpec?.parentSubsetManifest
+    ? await resolveParentRowIds(subsetSpec.parentSubsetManifest)
+    : null;
+  const scopedRows = parentRowIds
+    ? dataset.rows.filter((row) => parentRowIds.has(row.row_id))
+    : dataset.rows;
+  const subsetRows = selectSubsetRows(scopedRows, subsetSpec);
+  const outputDir = resolve(String(options.outputDir));
+  const subsetJsonlPath = join(outputDir, 'subset.jsonl');
+  const rowIdsPath = join(outputDir, 'row_ids.txt');
+  const manifestPath = join(outputDir, 'subset_manifest.json');
+  const serializedRows = `${subsetRows.map((row) => JSON.stringify(row)).join('\n')}\n`;
+  const rowIdsText = `${subsetRows.map((row) => row.row_id).join('\n')}\n`;
+  const manifest = {
+    artifactType: 'subset_manifest',
+    schemaVersion: 1,
+    generatedAt: new Date().toISOString(),
+    datasetPath: dataset.absolutePath,
+    datasetHash: dataset.datasetHash,
+    canonicalHash: dataset.canonicalHash,
+    rowIdsHash: sha256Hex(rowIdsText),
+    universeRowCount: dataset.rowCount,
+    subsetRowCount: subsetRows.length,
+    directionCounts: computeDirectionCounts(subsetRows),
+    subsetSpec,
+    parentSubsetManifest: subsetSpec?.parentSubsetManifest || null,
+    rowIds: subsetRows.map((row) => row.row_id),
+    output: {
+      subsetJsonlPath,
+      rowIdsPath,
+    },
+  };
+  await mkdir(outputDir, { recursive: true });
+  await writeFile(subsetJsonlPath, serializedRows, 'utf8');
+  await writeFile(rowIdsPath, rowIdsText, 'utf8');
+  await mkdir(dirname(manifestPath), { recursive: true });
+  await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+  return {
+    dataset,
+    subsetRows,
+    subsetJsonlPath,
+    rowIdsPath,
+    manifestPath,
+    manifest,
+  };
+}