@fabricorg/experiments-datasets 0.1.0

package/README.md

@@ -0,0 +1,13 @@
+# @fabricorg/experiments-datasets
+
+Versioned, tenant-aware JSON datasets for Fabric Experiments AI Quality suites.
+
+```ts
+import { InMemoryDatasetStore, parseJsonl } from '@fabricorg/experiments-datasets';
+```
+
+The package provides schemas, deterministic JSONL import, content hashing, a
+storage contract, and an in-memory reference store. Frozen versions own their
+values and cannot be changed by mutating caller or returned objects.
+
+See [experiments.fabric.pro/docs/ai-quality/overview](https://experiments.fabric.pro/docs/ai-quality/overview).

package/dist/index.cjs

@@ -0,0 +1,198 @@
+'use strict';
+
+var zod = require('zod');
+var crypto = require('crypto');
+
+// src/schema.ts
+var JsonValue = zod.z.lazy(
+  () => zod.z.union([
+    zod.z.null(),
+    zod.z.boolean(),
+    zod.z.number().finite(),
+    zod.z.string(),
+    zod.z.array(JsonValue),
+    zod.z.record(JsonValue)
+  ])
+);
+var DatasetId = zod.z.string().min(2).max(64).regex(/^[a-z][a-z0-9-]*$/, "lowercase kebab-case, must start with a letter");
+var DatasetSplit = zod.z.enum(["train", "test", "validation"]);
+var DatasetExample = zod.z.object({
+  exampleId: zod.z.string().uuid(),
+  input: JsonValue,
+  /** Reference/expected output; optional — judges without ground truth ignore it. */
+  expectedOutput: JsonValue.optional(),
+  metadata: zod.z.record(JsonValue).default({}),
+  split: DatasetSplit.default("test")
+}).strict();
+var DatasetSpec = zod.z.object({
+  id: DatasetId,
+  name: zod.z.string().min(1).max(120),
+  description: zod.z.string().max(2e3).optional()
+});
+var DatasetVersion = zod.z.object({
+  datasetId: DatasetId,
+  version: zod.z.number().int().min(1),
+  exampleCount: zod.z.number().int().min(0),
+  /** SHA-256 over the canonical JSON of sorted example ids + example hashes. */
+  contentHash: zod.z.string().regex(/^[a-f0-9]{64}$/),
+  createdAtIso: zod.z.string().datetime(),
+  note: zod.z.string().max(500).optional()
+});
+var Dataset = DatasetSpec.extend({
+  tenantId: zod.z.string().min(1),
+  latestVersion: zod.z.number().int().min(0),
+  exampleCount: zod.z.number().int().min(0),
+  createdAtIso: zod.z.string().datetime(),
+  updatedAtIso: zod.z.string().datetime()
+});
+function canonicalJson(value) {
+  return JSON.stringify(sortValue(value));
+}
+function sortValue(value) {
+  if (Array.isArray(value)) return value.map(sortValue);
+  if (value !== null && typeof value === "object") {
+    const entries = Object.entries(value).filter(([, v]) => v !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+    return Object.fromEntries(entries.map(([k, v]) => [k, sortValue(v)]));
+  }
+  return value;
+}
+function sha256Hex(input) {
+  return crypto.createHash("sha256").update(input, "utf8").digest("hex");
+}
+
+// src/memory.ts
+var InMemoryDatasetStore = class {
+  byTenant = /* @__PURE__ */ new Map();
+  tenant(tenantId) {
+    let m = this.byTenant.get(tenantId);
+    if (!m) {
+      m = /* @__PURE__ */ new Map();
+      this.byTenant.set(tenantId, m);
+    }
+    return m;
+  }
+  async create(tenantId, spec, nowIso) {
+    const m = this.tenant(tenantId);
+    if (m.has(spec.id)) throw new Error(`dataset already exists: ${spec.id}`);
+    const dataset = {
+      ...spec,
+      tenantId,
+      latestVersion: 0,
+      exampleCount: 0,
+      createdAtIso: nowIso,
+      updatedAtIso: nowIso
+    };
+    m.set(spec.id, { dataset, examples: [], versions: [] });
+    return clone(dataset);
+  }
+  async get(tenantId, datasetId) {
+    const dataset = this.tenant(tenantId).get(datasetId)?.dataset;
+    return dataset ? clone(dataset) : null;
+  }
+  async list(tenantId) {
+    return [...this.tenant(tenantId).values()].map((s) => clone(s.dataset));
+  }
+  async addExamples(tenantId, datasetId, examples, nowIso) {
+    const stored = this.require(tenantId, datasetId);
+    const validated = examples.map((example) => DatasetExample.parse(example));
+    const ids = new Set(stored.examples.map((e) => e.exampleId));
+    for (const e of validated) {
+      if (ids.has(e.exampleId)) throw new Error(`duplicate exampleId: ${e.exampleId}`);
+      ids.add(e.exampleId);
+    }
+    stored.examples.push(...validated.map(clone));
+    stored.dataset = {
+      ...stored.dataset,
+      exampleCount: stored.examples.length,
+      updatedAtIso: nowIso
+    };
+    return validated.map(clone);
+  }
+  async listExamples(query) {
+    const stored = this.require(query.tenantId, query.datasetId);
+    let pool = stored.examples;
+    if (query.version !== void 0) {
+      const v = stored.versions.find((x) => x.version === query.version);
+      if (!v) throw new Error(`unknown version ${query.version} for dataset ${query.datasetId}`);
+      pool = pool.slice(0, v.frozenCount);
+    }
+    if (query.split) pool = pool.filter((e) => e.split === query.split);
+    const offset = query.offset ?? 0;
+    const limit = query.limit ?? 100;
+    return { examples: pool.slice(offset, offset + limit).map(clone), total: pool.length };
+  }
+  async createVersion(tenantId, datasetId, nowIso, note) {
+    const stored = this.require(tenantId, datasetId);
+    const frozenCount = stored.examples.length;
+    const contentHash = hashExamples(stored.examples);
+    const version = {
+      datasetId,
+      version: stored.dataset.latestVersion + 1,
+      exampleCount: frozenCount,
+      contentHash,
+      createdAtIso: nowIso,
+      ...note === void 0 ? {} : { note },
+      frozenCount
+    };
+    stored.versions.push(version);
+    stored.dataset = { ...stored.dataset, latestVersion: version.version, updatedAtIso: nowIso };
+    const { frozenCount: _drop, ...pub } = version;
+    return clone(pub);
+  }
+  async listVersions(tenantId, datasetId) {
+    return this.require(tenantId, datasetId).versions.map(
+      ({ frozenCount: _drop, ...v }) => clone(v)
+    );
+  }
+  require(tenantId, datasetId) {
+    const stored = this.tenant(tenantId).get(datasetId);
+    if (!stored) throw new Error(`unknown dataset: ${datasetId}`);
+    return stored;
+  }
+};
+function hashExamples(examples) {
+  const entries = examples.map((e) => [e.exampleId, sha256Hex(canonicalJson(e))]).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+  return sha256Hex(canonicalJson(entries));
+}
+function clone(value) {
+  return structuredClone(value);
+}
+
+// src/import.ts
+function parseJsonl(text, makeId) {
+  const examples = [];
+  const errors = [];
+  const lines = text.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i].trim();
+    if (raw === "") continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (e) {
+      errors.push({ line: i + 1, message: `invalid JSON: ${e.message}` });
+      continue;
+    }
+    const candidate = parsed !== null && typeof parsed === "object" && !("exampleId" in parsed) ? { ...parsed, exampleId: makeId(i + 1) } : parsed;
+    const result = DatasetExample.safeParse(candidate);
+    if (result.success) examples.push(result.data);
+    else
+      errors.push({ line: i + 1, message: result.error.issues[0]?.message ?? "invalid example" });
+  }
+  return { examples, errors };
+}
+
+exports.Dataset = Dataset;
+exports.DatasetExample = DatasetExample;
+exports.DatasetId = DatasetId;
+exports.DatasetSpec = DatasetSpec;
+exports.DatasetSplit = DatasetSplit;
+exports.DatasetVersion = DatasetVersion;
+exports.InMemoryDatasetStore = InMemoryDatasetStore;
+exports.JsonValue = JsonValue;
+exports.canonicalJson = canonicalJson;
+exports.hashExamples = hashExamples;
+exports.parseJsonl = parseJsonl;
+exports.sha256Hex = sha256Hex;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schema.ts","../src/hash.ts","../src/memory.ts","../src/import.ts"],"names":["z","createHash"],"mappings":"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","file":"index.cjs","sourcesContent":["import { z } from 'zod';\n\n/** JSON-compatible values accepted by public dataset and prompt surfaces. */\nexport type JsonValue =\n  | null\n  | boolean\n  | number\n  | string\n  | JsonValue[]\n  | { [key: string]: JsonValue };\n\n/**\n * `z.unknown()` accepts `undefined`, which makes an object field effectively\n * optional and also admits values that cannot survive JSONL/Delta storage.\n * Datasets are durable evidence, so their public shape is deliberately the\n * portable JSON subset.\n */\nexport const JsonValue: z.ZodType<JsonValue> = z.lazy(() =>\n  z.union([\n    z.null(),\n    z.boolean(),\n    z.number().finite(),\n    z.string(),\n    z.array(JsonValue),\n    z.record(JsonValue),\n  ]),\n);\n\nexport const DatasetId = z\n  .string()\n  .min(2)\n  .max(64)\n  .regex(/^[a-z][a-z0-9-]*$/, 'lowercase kebab-case, must start with a letter');\nexport type DatasetId = z.infer<typeof DatasetId>;\n\nexport const DatasetSplit = z.enum(['train', 'test', 'validation']);\nexport type DatasetSplit = z.infer<typeof DatasetSplit>;\n\n/**\n * A single evaluation example. `input`/`output` are open JSON values so the\n * same shape carries chat transcripts, RAG tuples, or plain string pairs —\n * mirroring OpenInference conventions so trace-derived examples (M7) import\n * without transformation.\n */\nexport const DatasetExample = z\n  .object({\n    exampleId: z.string().uuid(),\n    input: JsonValue,\n    /** Reference/expected output; optional — judges without ground truth ignore it. */\n    expectedOutput: JsonValue.optional(),\n    metadata: z.record(JsonValue).default({}),\n    split: DatasetSplit.default('test'),\n  })\n  .strict();\nexport type DatasetExample = z.infer<typeof DatasetExample>;\n\nexport const DatasetSpec = z.object({\n  id: DatasetId,\n  name: z.string().min(1).max(120),\n  description: z.string().max(2000).optional(),\n});\nexport type DatasetSpec = z.infer<typeof DatasetSpec>;\n\n/**\n * Immutable version pointer. Examples are append-only; a version freezes the\n * set of example ids visible at creation time and records a content hash so\n * two versions with identical membership are provably identical (same\n * content-addressing discipline as the edge manifest).\n */\nexport const DatasetVersion = z.object({\n  datasetId: DatasetId,\n  version: z.number().int().min(1),\n  exampleCount: z.number().int().min(0),\n  /** SHA-256 over the canonical JSON of sorted example ids + example hashes. */\n  contentHash: z.string().regex(/^[a-f0-9]{64}$/),\n  createdAtIso: z.string().datetime(),\n  note: z.string().max(500).optional(),\n});\nexport type DatasetVersion = z.infer<typeof DatasetVersion>;\n\nexport const Dataset = DatasetSpec.extend({\n  tenantId: z.string().min(1),\n  latestVersion: z.number().int().min(0),\n  exampleCount: z.number().int().min(0),\n  createdAtIso: z.string().datetime(),\n  updatedAtIso: z.string().datetime(),\n});\nexport type Dataset = z.infer<typeof Dataset>;\n","import { createHash } from 'node:crypto';\n\n/** Deterministic JSON: object keys sorted recursively, arrays kept in order. */\nexport function canonicalJson(value: unknown): string {\n  return JSON.stringify(sortValue(value));\n}\n\nfunction sortValue(value: unknown): unknown {\n  if (Array.isArray(value)) return value.map(sortValue);\n  if (value !== null && typeof value === 'object') {\n    const entries = Object.entries(value as Record<string, unknown>)\n      .filter(([, v]) => v !== undefined)\n      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));\n    return Object.fromEntries(entries.map(([k, v]) => [k, sortValue(v)]));\n  }\n  return value;\n}\n\nexport function sha256Hex(input: string): string {\n  return createHash('sha256').update(input, 'utf8').digest('hex');\n}\n","import { canonicalJson, sha256Hex } from './hash.js';\nimport { type Dataset, DatasetExample, type DatasetSpec, type DatasetVersion } from './schema.js';\nimport type { DatasetStore, ExamplePage, ListExamplesQuery } from './store.js';\n\ninterface StoredDataset {\n  dataset: Dataset;\n  /** Append-only example log; versions freeze a prefix of this log. */\n  examples: DatasetExample[];\n  versions: Array<DatasetVersion & { frozenCount: number }>;\n}\n\n/** Reference implementation: unit tests, `fx dev`, and harness fixtures. */\nexport class InMemoryDatasetStore implements DatasetStore {\n  private byTenant = new Map<string, Map<string, StoredDataset>>();\n\n  private tenant(tenantId: string): Map<string, StoredDataset> {\n    let m = this.byTenant.get(tenantId);\n    if (!m) {\n      m = new Map();\n      this.byTenant.set(tenantId, m);\n    }\n    return m;\n  }\n\n  async create(tenantId: string, spec: DatasetSpec, nowIso: string): Promise<Dataset> {\n    const m = this.tenant(tenantId);\n    if (m.has(spec.id)) throw new Error(`dataset already exists: ${spec.id}`);\n    const dataset: Dataset = {\n      ...spec,\n      tenantId,\n      latestVersion: 0,\n      exampleCount: 0,\n      createdAtIso: nowIso,\n      updatedAtIso: nowIso,\n    };\n    m.set(spec.id, { dataset, examples: [], versions: [] });\n    return clone(dataset);\n  }\n\n  async get(tenantId: string, datasetId: string): Promise<Dataset | null> {\n    const dataset = this.tenant(tenantId).get(datasetId)?.dataset;\n    return dataset ? clone(dataset) : null;\n  }\n\n  async list(tenantId: string): Promise<Dataset[]> {\n    return [...this.tenant(tenantId).values()].map((s) => clone(s.dataset));\n  }\n\n  async addExamples(\n    tenantId: string,\n    datasetId: string,\n    examples: readonly DatasetExample[],\n    nowIso: string,\n  ): Promise<DatasetExample[]> {\n    const stored = this.require(tenantId, datasetId);\n    const validated = examples.map((example) => DatasetExample.parse(example));\n    const ids = new Set(stored.examples.map((e) => e.exampleId));\n    for (const e of validated) {\n      if (ids.has(e.exampleId)) throw new Error(`duplicate exampleId: ${e.exampleId}`);\n      ids.add(e.exampleId);\n    }\n    // Keep an owned copy. Callers may mutate the object they passed after this\n    // method returns; a frozen version must never change as a side effect.\n    stored.examples.push(...validated.map(clone));\n    stored.dataset = {\n      ...stored.dataset,\n      exampleCount: stored.examples.length,\n      updatedAtIso: nowIso,\n    };\n    return validated.map(clone);\n  }\n\n  async listExamples(query: ListExamplesQuery): Promise<ExamplePage> {\n    const stored = this.require(query.tenantId, query.datasetId);\n    let pool = stored.examples;\n    if (query.version !== undefined) {\n      const v = stored.versions.find((x) => x.version === query.version);\n      if (!v) throw new Error(`unknown version ${query.version} for dataset ${query.datasetId}`);\n      pool = pool.slice(0, v.frozenCount);\n    }\n    if (query.split) pool = pool.filter((e) => e.split === query.split);\n    const offset = query.offset ?? 0;\n    const limit = query.limit ?? 100;\n    return { examples: pool.slice(offset, offset + limit).map(clone), total: pool.length };\n  }\n\n  async createVersion(\n    tenantId: string,\n    datasetId: string,\n    nowIso: string,\n    note?: string,\n  ): Promise<DatasetVersion> {\n    const stored = this.require(tenantId, datasetId);\n    const frozenCount = stored.examples.length;\n    const contentHash = hashExamples(stored.examples);\n    const version: DatasetVersion & { frozenCount: number } = {\n      datasetId,\n      version: stored.dataset.latestVersion + 1,\n      exampleCount: frozenCount,\n      contentHash,\n      createdAtIso: nowIso,\n      ...(note === undefined ? {} : { note }),\n      frozenCount,\n    };\n    stored.versions.push(version);\n    stored.dataset = { ...stored.dataset, latestVersion: version.version, updatedAtIso: nowIso };\n    const { frozenCount: _drop, ...pub } = version;\n    return clone(pub);\n  }\n\n  async listVersions(tenantId: string, datasetId: string): Promise<DatasetVersion[]> {\n    return this.require(tenantId, datasetId).versions.map(({ frozenCount: _drop, ...v }) =>\n      clone(v),\n    );\n  }\n\n  private require(tenantId: string, datasetId: string): StoredDataset {\n    const stored = this.tenant(tenantId).get(datasetId);\n    if (!stored) throw new Error(`unknown dataset: ${datasetId}`);\n    return stored;\n  }\n}\n\n/** Content hash over sorted example ids + per-example canonical hashes. */\nexport function hashExamples(examples: readonly DatasetExample[]): string {\n  const entries = examples\n    .map((e) => [e.exampleId, sha256Hex(canonicalJson(e))] as const)\n    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));\n  return sha256Hex(canonicalJson(entries));\n}\n\nfunction clone<T>(value: T): T {\n  return structuredClone(value);\n}\n","import { DatasetExample } from './schema.js';\n\nexport interface ImportResult {\n  examples: DatasetExample[];\n  errors: Array<{ line: number; message: string }>;\n}\n\n/**\n * Parse JSONL into examples. Accepts either full example objects (with\n * `exampleId`) or bare `{input, expectedOutput?, metadata?, split?}` rows;\n * bare rows get ids from `makeId` (injected — no ambient randomness, matching\n * the deterministic-by-default rule the Harness agents follow).\n */\nexport function parseJsonl(text: string, makeId: (line: number) => string): ImportResult {\n  const examples: DatasetExample[] = [];\n  const errors: ImportResult['errors'] = [];\n  const lines = text.split('\\n');\n  for (let i = 0; i < lines.length; i++) {\n    const raw = lines[i]!.trim();\n    if (raw === '') continue;\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(raw);\n    } catch (e) {\n      errors.push({ line: i + 1, message: `invalid JSON: ${(e as Error).message}` });\n      continue;\n    }\n    const candidate =\n      parsed !== null && typeof parsed === 'object' && !('exampleId' in (parsed as object))\n        ? { ...(parsed as object), exampleId: makeId(i + 1) }\n        : parsed;\n    const result = DatasetExample.safeParse(candidate);\n    if (result.success) examples.push(result.data);\n    else\n      errors.push({ line: i + 1, message: result.error.issues[0]?.message ?? 'invalid example' });\n  }\n  return { examples, errors };\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,186 @@
+import { z } from 'zod';
+
+/** JSON-compatible values accepted by public dataset and prompt surfaces. */
+type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * `z.unknown()` accepts `undefined`, which makes an object field effectively
+ * optional and also admits values that cannot survive JSONL/Delta storage.
+ * Datasets are durable evidence, so their public shape is deliberately the
+ * portable JSON subset.
+ */
+declare const JsonValue: z.ZodType<JsonValue>;
+declare const DatasetId: z.ZodString;
+type DatasetId = z.infer<typeof DatasetId>;
+declare const DatasetSplit: z.ZodEnum<["train", "test", "validation"]>;
+type DatasetSplit = z.infer<typeof DatasetSplit>;
+/**
+ * A single evaluation example. `input`/`output` are open JSON values so the
+ * same shape carries chat transcripts, RAG tuples, or plain string pairs —
+ * mirroring OpenInference conventions so trace-derived examples (M7) import
+ * without transformation.
+ */
+declare const DatasetExample: z.ZodObject<{
+    exampleId: z.ZodString;
+    input: z.ZodType<JsonValue, z.ZodTypeDef, JsonValue>;
+    /** Reference/expected output; optional — judges without ground truth ignore it. */
+    expectedOutput: z.ZodOptional<z.ZodType<JsonValue, z.ZodTypeDef, JsonValue>>;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodType<JsonValue, z.ZodTypeDef, JsonValue>>>;
+    split: z.ZodDefault<z.ZodEnum<["train", "test", "validation"]>>;
+}, "strict", z.ZodTypeAny, {
+    exampleId: string;
+    input: JsonValue;
+    metadata: Record<string, JsonValue>;
+    split: "validation" | "train" | "test";
+    expectedOutput?: JsonValue | undefined;
+}, {
+    exampleId: string;
+    input: JsonValue;
+    expectedOutput?: JsonValue | undefined;
+    metadata?: Record<string, JsonValue> | undefined;
+    split?: "validation" | "train" | "test" | undefined;
+}>;
+type DatasetExample = z.infer<typeof DatasetExample>;
+declare const DatasetSpec: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    name: string;
+    description?: string | undefined;
+}, {
+    id: string;
+    name: string;
+    description?: string | undefined;
+}>;
+type DatasetSpec = z.infer<typeof DatasetSpec>;
+/**
+ * Immutable version pointer. Examples are append-only; a version freezes the
+ * set of example ids visible at creation time and records a content hash so
+ * two versions with identical membership are provably identical (same
+ * content-addressing discipline as the edge manifest).
+ */
+declare const DatasetVersion: z.ZodObject<{
+    datasetId: z.ZodString;
+    version: z.ZodNumber;
+    exampleCount: z.ZodNumber;
+    /** SHA-256 over the canonical JSON of sorted example ids + example hashes. */
+    contentHash: z.ZodString;
+    createdAtIso: z.ZodString;
+    note: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    datasetId: string;
+    version: number;
+    exampleCount: number;
+    contentHash: string;
+    createdAtIso: string;
+    note?: string | undefined;
+}, {
+    datasetId: string;
+    version: number;
+    exampleCount: number;
+    contentHash: string;
+    createdAtIso: string;
+    note?: string | undefined;
+}>;
+type DatasetVersion = z.infer<typeof DatasetVersion>;
+declare const Dataset: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+} & {
+    tenantId: z.ZodString;
+    latestVersion: z.ZodNumber;
+    exampleCount: z.ZodNumber;
+    createdAtIso: z.ZodString;
+    updatedAtIso: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    name: string;
+    exampleCount: number;
+    createdAtIso: string;
+    tenantId: string;
+    latestVersion: number;
+    updatedAtIso: string;
+    description?: string | undefined;
+}, {
+    id: string;
+    name: string;
+    exampleCount: number;
+    createdAtIso: string;
+    tenantId: string;
+    latestVersion: number;
+    updatedAtIso: string;
+    description?: string | undefined;
+}>;
+type Dataset = z.infer<typeof Dataset>;
+
+interface ListExamplesQuery {
+    tenantId: string;
+    datasetId: string;
+    /** Pin to a frozen version; latest mutable view when omitted. */
+    version?: number;
+    split?: DatasetExample['split'];
+    limit?: number;
+    offset?: number;
+}
+interface ExamplePage {
+    examples: DatasetExample[];
+    total: number;
+}
+/**
+ * Storage contract for datasets. Implementations live where the drivers live
+ * (warehouse package: DuckDB local, Databricks Delta) — this package stays
+ * domain-only. `InMemoryDatasetStore` is the reference implementation used by
+ * unit tests and `fx dev`.
+ */
+interface DatasetStore {
+    create(tenantId: string, spec: DatasetSpec, nowIso: string): Promise<Dataset>;
+    get(tenantId: string, datasetId: string): Promise<Dataset | null>;
+    list(tenantId: string): Promise<Dataset[]>;
+    /** Append examples to the mutable head. Returns the stored examples. */
+    addExamples(tenantId: string, datasetId: string, examples: readonly DatasetExample[], nowIso: string): Promise<DatasetExample[]>;
+    listExamples(query: ListExamplesQuery): Promise<ExamplePage>;
+    /** Freeze the current head into an immutable numbered version. */
+    createVersion(tenantId: string, datasetId: string, nowIso: string, note?: string): Promise<DatasetVersion>;
+    listVersions(tenantId: string, datasetId: string): Promise<DatasetVersion[]>;
+}
+
+/** Reference implementation: unit tests, `fx dev`, and harness fixtures. */
+declare class InMemoryDatasetStore implements DatasetStore {
+    private byTenant;
+    private tenant;
+    create(tenantId: string, spec: DatasetSpec, nowIso: string): Promise<Dataset>;
+    get(tenantId: string, datasetId: string): Promise<Dataset | null>;
+    list(tenantId: string): Promise<Dataset[]>;
+    addExamples(tenantId: string, datasetId: string, examples: readonly DatasetExample[], nowIso: string): Promise<DatasetExample[]>;
+    listExamples(query: ListExamplesQuery): Promise<ExamplePage>;
+    createVersion(tenantId: string, datasetId: string, nowIso: string, note?: string): Promise<DatasetVersion>;
+    listVersions(tenantId: string, datasetId: string): Promise<DatasetVersion[]>;
+    private require;
+}
+/** Content hash over sorted example ids + per-example canonical hashes. */
+declare function hashExamples(examples: readonly DatasetExample[]): string;
+
+interface ImportResult {
+    examples: DatasetExample[];
+    errors: Array<{
+        line: number;
+        message: string;
+    }>;
+}
+/**
+ * Parse JSONL into examples. Accepts either full example objects (with
+ * `exampleId`) or bare `{input, expectedOutput?, metadata?, split?}` rows;
+ * bare rows get ids from `makeId` (injected — no ambient randomness, matching
+ * the deterministic-by-default rule the Harness agents follow).
+ */
+declare function parseJsonl(text: string, makeId: (line: number) => string): ImportResult;
+
+/** Deterministic JSON: object keys sorted recursively, arrays kept in order. */
+declare function canonicalJson(value: unknown): string;
+declare function sha256Hex(input: string): string;
+
+export { Dataset, DatasetExample, DatasetId, DatasetSpec, DatasetSplit, type DatasetStore, DatasetVersion, type ExamplePage, type ImportResult, InMemoryDatasetStore, JsonValue, type ListExamplesQuery, canonicalJson, hashExamples, parseJsonl, sha256Hex };

package/dist/index.d.ts

@@ -0,0 +1,186 @@
+import { z } from 'zod';
+
+/** JSON-compatible values accepted by public dataset and prompt surfaces. */
+type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * `z.unknown()` accepts `undefined`, which makes an object field effectively
+ * optional and also admits values that cannot survive JSONL/Delta storage.
+ * Datasets are durable evidence, so their public shape is deliberately the
+ * portable JSON subset.
+ */
+declare const JsonValue: z.ZodType<JsonValue>;
+declare const DatasetId: z.ZodString;
+type DatasetId = z.infer<typeof DatasetId>;
+declare const DatasetSplit: z.ZodEnum<["train", "test", "validation"]>;
+type DatasetSplit = z.infer<typeof DatasetSplit>;
+/**
+ * A single evaluation example. `input`/`output` are open JSON values so the
+ * same shape carries chat transcripts, RAG tuples, or plain string pairs —
+ * mirroring OpenInference conventions so trace-derived examples (M7) import
+ * without transformation.
+ */
+declare const DatasetExample: z.ZodObject<{
+    exampleId: z.ZodString;
+    input: z.ZodType<JsonValue, z.ZodTypeDef, JsonValue>;
+    /** Reference/expected output; optional — judges without ground truth ignore it. */
+    expectedOutput: z.ZodOptional<z.ZodType<JsonValue, z.ZodTypeDef, JsonValue>>;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodType<JsonValue, z.ZodTypeDef, JsonValue>>>;
+    split: z.ZodDefault<z.ZodEnum<["train", "test", "validation"]>>;
+}, "strict", z.ZodTypeAny, {
+    exampleId: string;
+    input: JsonValue;
+    metadata: Record<string, JsonValue>;
+    split: "validation" | "train" | "test";
+    expectedOutput?: JsonValue | undefined;
+}, {
+    exampleId: string;
+    input: JsonValue;
+    expectedOutput?: JsonValue | undefined;
+    metadata?: Record<string, JsonValue> | undefined;
+    split?: "validation" | "train" | "test" | undefined;
+}>;
+type DatasetExample = z.infer<typeof DatasetExample>;
+declare const DatasetSpec: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    name: string;
+    description?: string | undefined;
+}, {
+    id: string;
+    name: string;
+    description?: string | undefined;
+}>;
+type DatasetSpec = z.infer<typeof DatasetSpec>;
+/**
+ * Immutable version pointer. Examples are append-only; a version freezes the
+ * set of example ids visible at creation time and records a content hash so
+ * two versions with identical membership are provably identical (same
+ * content-addressing discipline as the edge manifest).
+ */
+declare const DatasetVersion: z.ZodObject<{
+    datasetId: z.ZodString;
+    version: z.ZodNumber;
+    exampleCount: z.ZodNumber;
+    /** SHA-256 over the canonical JSON of sorted example ids + example hashes. */
+    contentHash: z.ZodString;
+    createdAtIso: z.ZodString;
+    note: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    datasetId: string;
+    version: number;
+    exampleCount: number;
+    contentHash: string;
+    createdAtIso: string;
+    note?: string | undefined;
+}, {
+    datasetId: string;
+    version: number;
+    exampleCount: number;
+    contentHash: string;
+    createdAtIso: string;
+    note?: string | undefined;
+}>;
+type DatasetVersion = z.infer<typeof DatasetVersion>;
+declare const Dataset: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+} & {
+    tenantId: z.ZodString;
+    latestVersion: z.ZodNumber;
+    exampleCount: z.ZodNumber;
+    createdAtIso: z.ZodString;
+    updatedAtIso: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    name: string;
+    exampleCount: number;
+    createdAtIso: string;
+    tenantId: string;
+    latestVersion: number;
+    updatedAtIso: string;
+    description?: string | undefined;
+}, {
+    id: string;
+    name: string;
+    exampleCount: number;
+    createdAtIso: string;
+    tenantId: string;
+    latestVersion: number;
+    updatedAtIso: string;
+    description?: string | undefined;
+}>;
+type Dataset = z.infer<typeof Dataset>;
+
+interface ListExamplesQuery {
+    tenantId: string;
+    datasetId: string;
+    /** Pin to a frozen version; latest mutable view when omitted. */
+    version?: number;
+    split?: DatasetExample['split'];
+    limit?: number;
+    offset?: number;
+}
+interface ExamplePage {
+    examples: DatasetExample[];
+    total: number;
+}
+/**
+ * Storage contract for datasets. Implementations live where the drivers live
+ * (warehouse package: DuckDB local, Databricks Delta) — this package stays
+ * domain-only. `InMemoryDatasetStore` is the reference implementation used by
+ * unit tests and `fx dev`.
+ */
+interface DatasetStore {
+    create(tenantId: string, spec: DatasetSpec, nowIso: string): Promise<Dataset>;
+    get(tenantId: string, datasetId: string): Promise<Dataset | null>;
+    list(tenantId: string): Promise<Dataset[]>;
+    /** Append examples to the mutable head. Returns the stored examples. */
+    addExamples(tenantId: string, datasetId: string, examples: readonly DatasetExample[], nowIso: string): Promise<DatasetExample[]>;
+    listExamples(query: ListExamplesQuery): Promise<ExamplePage>;
+    /** Freeze the current head into an immutable numbered version. */
+    createVersion(tenantId: string, datasetId: string, nowIso: string, note?: string): Promise<DatasetVersion>;
+    listVersions(tenantId: string, datasetId: string): Promise<DatasetVersion[]>;
+}
+
+/** Reference implementation: unit tests, `fx dev`, and harness fixtures. */
+declare class InMemoryDatasetStore implements DatasetStore {
+    private byTenant;
+    private tenant;
+    create(tenantId: string, spec: DatasetSpec, nowIso: string): Promise<Dataset>;
+    get(tenantId: string, datasetId: string): Promise<Dataset | null>;
+    list(tenantId: string): Promise<Dataset[]>;
+    addExamples(tenantId: string, datasetId: string, examples: readonly DatasetExample[], nowIso: string): Promise<DatasetExample[]>;
+    listExamples(query: ListExamplesQuery): Promise<ExamplePage>;
+    createVersion(tenantId: string, datasetId: string, nowIso: string, note?: string): Promise<DatasetVersion>;
+    listVersions(tenantId: string, datasetId: string): Promise<DatasetVersion[]>;
+    private require;
+}
+/** Content hash over sorted example ids + per-example canonical hashes. */
+declare function hashExamples(examples: readonly DatasetExample[]): string;
+
+interface ImportResult {
+    examples: DatasetExample[];
+    errors: Array<{
+        line: number;
+        message: string;
+    }>;
+}
+/**
+ * Parse JSONL into examples. Accepts either full example objects (with
+ * `exampleId`) or bare `{input, expectedOutput?, metadata?, split?}` rows;
+ * bare rows get ids from `makeId` (injected — no ambient randomness, matching
+ * the deterministic-by-default rule the Harness agents follow).
+ */
+declare function parseJsonl(text: string, makeId: (line: number) => string): ImportResult;
+
+/** Deterministic JSON: object keys sorted recursively, arrays kept in order. */
+declare function canonicalJson(value: unknown): string;
+declare function sha256Hex(input: string): string;
+
+export { Dataset, DatasetExample, DatasetId, DatasetSpec, DatasetSplit, type DatasetStore, DatasetVersion, type ExamplePage, type ImportResult, InMemoryDatasetStore, JsonValue, type ListExamplesQuery, canonicalJson, hashExamples, parseJsonl, sha256Hex };

package/dist/index.js

@@ -0,0 +1,185 @@
+import { z } from 'zod';
+import { createHash } from 'crypto';
+
+// src/schema.ts
+var JsonValue = z.lazy(
+  () => z.union([
+    z.null(),
+    z.boolean(),
+    z.number().finite(),
+    z.string(),
+    z.array(JsonValue),
+    z.record(JsonValue)
+  ])
+);
+var DatasetId = z.string().min(2).max(64).regex(/^[a-z][a-z0-9-]*$/, "lowercase kebab-case, must start with a letter");
+var DatasetSplit = z.enum(["train", "test", "validation"]);
+var DatasetExample = z.object({
+  exampleId: z.string().uuid(),
+  input: JsonValue,
+  /** Reference/expected output; optional — judges without ground truth ignore it. */
+  expectedOutput: JsonValue.optional(),
+  metadata: z.record(JsonValue).default({}),
+  split: DatasetSplit.default("test")
+}).strict();
+var DatasetSpec = z.object({
+  id: DatasetId,
+  name: z.string().min(1).max(120),
+  description: z.string().max(2e3).optional()
+});
+var DatasetVersion = z.object({
+  datasetId: DatasetId,
+  version: z.number().int().min(1),
+  exampleCount: z.number().int().min(0),
+  /** SHA-256 over the canonical JSON of sorted example ids + example hashes. */
+  contentHash: z.string().regex(/^[a-f0-9]{64}$/),
+  createdAtIso: z.string().datetime(),
+  note: z.string().max(500).optional()
+});
+var Dataset = DatasetSpec.extend({
+  tenantId: z.string().min(1),
+  latestVersion: z.number().int().min(0),
+  exampleCount: z.number().int().min(0),
+  createdAtIso: z.string().datetime(),
+  updatedAtIso: z.string().datetime()
+});
+function canonicalJson(value) {
+  return JSON.stringify(sortValue(value));
+}
+function sortValue(value) {
+  if (Array.isArray(value)) return value.map(sortValue);
+  if (value !== null && typeof value === "object") {
+    const entries = Object.entries(value).filter(([, v]) => v !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+    return Object.fromEntries(entries.map(([k, v]) => [k, sortValue(v)]));
+  }
+  return value;
+}
+function sha256Hex(input) {
+  return createHash("sha256").update(input, "utf8").digest("hex");
+}
+
+// src/memory.ts
+var InMemoryDatasetStore = class {
+  byTenant = /* @__PURE__ */ new Map();
+  tenant(tenantId) {
+    let m = this.byTenant.get(tenantId);
+    if (!m) {
+      m = /* @__PURE__ */ new Map();
+      this.byTenant.set(tenantId, m);
+    }
+    return m;
+  }
+  async create(tenantId, spec, nowIso) {
+    const m = this.tenant(tenantId);
+    if (m.has(spec.id)) throw new Error(`dataset already exists: ${spec.id}`);
+    const dataset = {
+      ...spec,
+      tenantId,
+      latestVersion: 0,
+      exampleCount: 0,
+      createdAtIso: nowIso,
+      updatedAtIso: nowIso
+    };
+    m.set(spec.id, { dataset, examples: [], versions: [] });
+    return clone(dataset);
+  }
+  async get(tenantId, datasetId) {
+    const dataset = this.tenant(tenantId).get(datasetId)?.dataset;
+    return dataset ? clone(dataset) : null;
+  }
+  async list(tenantId) {
+    return [...this.tenant(tenantId).values()].map((s) => clone(s.dataset));
+  }
+  async addExamples(tenantId, datasetId, examples, nowIso) {
+    const stored = this.require(tenantId, datasetId);
+    const validated = examples.map((example) => DatasetExample.parse(example));
+    const ids = new Set(stored.examples.map((e) => e.exampleId));
+    for (const e of validated) {
+      if (ids.has(e.exampleId)) throw new Error(`duplicate exampleId: ${e.exampleId}`);
+      ids.add(e.exampleId);
+    }
+    stored.examples.push(...validated.map(clone));
+    stored.dataset = {
+      ...stored.dataset,
+      exampleCount: stored.examples.length,
+      updatedAtIso: nowIso
+    };
+    return validated.map(clone);
+  }
+  async listExamples(query) {
+    const stored = this.require(query.tenantId, query.datasetId);
+    let pool = stored.examples;
+    if (query.version !== void 0) {
+      const v = stored.versions.find((x) => x.version === query.version);
+      if (!v) throw new Error(`unknown version ${query.version} for dataset ${query.datasetId}`);
+      pool = pool.slice(0, v.frozenCount);
+    }
+    if (query.split) pool = pool.filter((e) => e.split === query.split);
+    const offset = query.offset ?? 0;
+    const limit = query.limit ?? 100;
+    return { examples: pool.slice(offset, offset + limit).map(clone), total: pool.length };
+  }
+  async createVersion(tenantId, datasetId, nowIso, note) {
+    const stored = this.require(tenantId, datasetId);
+    const frozenCount = stored.examples.length;
+    const contentHash = hashExamples(stored.examples);
+    const version = {
+      datasetId,
+      version: stored.dataset.latestVersion + 1,
+      exampleCount: frozenCount,
+      contentHash,
+      createdAtIso: nowIso,
+      ...note === void 0 ? {} : { note },
+      frozenCount
+    };
+    stored.versions.push(version);
+    stored.dataset = { ...stored.dataset, latestVersion: version.version, updatedAtIso: nowIso };
+    const { frozenCount: _drop, ...pub } = version;
+    return clone(pub);
+  }
+  async listVersions(tenantId, datasetId) {
+    return this.require(tenantId, datasetId).versions.map(
+      ({ frozenCount: _drop, ...v }) => clone(v)
+    );
+  }
+  require(tenantId, datasetId) {
+    const stored = this.tenant(tenantId).get(datasetId);
+    if (!stored) throw new Error(`unknown dataset: ${datasetId}`);
+    return stored;
+  }
+};
+function hashExamples(examples) {
+  const entries = examples.map((e) => [e.exampleId, sha256Hex(canonicalJson(e))]).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+  return sha256Hex(canonicalJson(entries));
+}
+function clone(value) {
+  return structuredClone(value);
+}
+
+// src/import.ts
+function parseJsonl(text, makeId) {
+  const examples = [];
+  const errors = [];
+  const lines = text.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i].trim();
+    if (raw === "") continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (e) {
+      errors.push({ line: i + 1, message: `invalid JSON: ${e.message}` });
+      continue;
+    }
+    const candidate = parsed !== null && typeof parsed === "object" && !("exampleId" in parsed) ? { ...parsed, exampleId: makeId(i + 1) } : parsed;
+    const result = DatasetExample.safeParse(candidate);
+    if (result.success) examples.push(result.data);
+    else
+      errors.push({ line: i + 1, message: result.error.issues[0]?.message ?? "invalid example" });
+  }
+  return { examples, errors };
+}
+
+export { Dataset, DatasetExample, DatasetId, DatasetSpec, DatasetSplit, DatasetVersion, InMemoryDatasetStore, JsonValue, canonicalJson, hashExamples, parseJsonl, sha256Hex };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schema.ts","../src/hash.ts","../src/memory.ts","../src/import.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import { z } from 'zod';\n\n/** JSON-compatible values accepted by public dataset and prompt surfaces. */\nexport type JsonValue =\n  | null\n  | boolean\n  | number\n  | string\n  | JsonValue[]\n  | { [key: string]: JsonValue };\n\n/**\n * `z.unknown()` accepts `undefined`, which makes an object field effectively\n * optional and also admits values that cannot survive JSONL/Delta storage.\n * Datasets are durable evidence, so their public shape is deliberately the\n * portable JSON subset.\n */\nexport const JsonValue: z.ZodType<JsonValue> = z.lazy(() =>\n  z.union([\n    z.null(),\n    z.boolean(),\n    z.number().finite(),\n    z.string(),\n    z.array(JsonValue),\n    z.record(JsonValue),\n  ]),\n);\n\nexport const DatasetId = z\n  .string()\n  .min(2)\n  .max(64)\n  .regex(/^[a-z][a-z0-9-]*$/, 'lowercase kebab-case, must start with a letter');\nexport type DatasetId = z.infer<typeof DatasetId>;\n\nexport const DatasetSplit = z.enum(['train', 'test', 'validation']);\nexport type DatasetSplit = z.infer<typeof DatasetSplit>;\n\n/**\n * A single evaluation example. `input`/`output` are open JSON values so the\n * same shape carries chat transcripts, RAG tuples, or plain string pairs —\n * mirroring OpenInference conventions so trace-derived examples (M7) import\n * without transformation.\n */\nexport const DatasetExample = z\n  .object({\n    exampleId: z.string().uuid(),\n    input: JsonValue,\n    /** Reference/expected output; optional — judges without ground truth ignore it. */\n    expectedOutput: JsonValue.optional(),\n    metadata: z.record(JsonValue).default({}),\n    split: DatasetSplit.default('test'),\n  })\n  .strict();\nexport type DatasetExample = z.infer<typeof DatasetExample>;\n\nexport const DatasetSpec = z.object({\n  id: DatasetId,\n  name: z.string().min(1).max(120),\n  description: z.string().max(2000).optional(),\n});\nexport type DatasetSpec = z.infer<typeof DatasetSpec>;\n\n/**\n * Immutable version pointer. Examples are append-only; a version freezes the\n * set of example ids visible at creation time and records a content hash so\n * two versions with identical membership are provably identical (same\n * content-addressing discipline as the edge manifest).\n */\nexport const DatasetVersion = z.object({\n  datasetId: DatasetId,\n  version: z.number().int().min(1),\n  exampleCount: z.number().int().min(0),\n  /** SHA-256 over the canonical JSON of sorted example ids + example hashes. */\n  contentHash: z.string().regex(/^[a-f0-9]{64}$/),\n  createdAtIso: z.string().datetime(),\n  note: z.string().max(500).optional(),\n});\nexport type DatasetVersion = z.infer<typeof DatasetVersion>;\n\nexport const Dataset = DatasetSpec.extend({\n  tenantId: z.string().min(1),\n  latestVersion: z.number().int().min(0),\n  exampleCount: z.number().int().min(0),\n  createdAtIso: z.string().datetime(),\n  updatedAtIso: z.string().datetime(),\n});\nexport type Dataset = z.infer<typeof Dataset>;\n","import { createHash } from 'node:crypto';\n\n/** Deterministic JSON: object keys sorted recursively, arrays kept in order. */\nexport function canonicalJson(value: unknown): string {\n  return JSON.stringify(sortValue(value));\n}\n\nfunction sortValue(value: unknown): unknown {\n  if (Array.isArray(value)) return value.map(sortValue);\n  if (value !== null && typeof value === 'object') {\n    const entries = Object.entries(value as Record<string, unknown>)\n      .filter(([, v]) => v !== undefined)\n      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));\n    return Object.fromEntries(entries.map(([k, v]) => [k, sortValue(v)]));\n  }\n  return value;\n}\n\nexport function sha256Hex(input: string): string {\n  return createHash('sha256').update(input, 'utf8').digest('hex');\n}\n","import { canonicalJson, sha256Hex } from './hash.js';\nimport { type Dataset, DatasetExample, type DatasetSpec, type DatasetVersion } from './schema.js';\nimport type { DatasetStore, ExamplePage, ListExamplesQuery } from './store.js';\n\ninterface StoredDataset {\n  dataset: Dataset;\n  /** Append-only example log; versions freeze a prefix of this log. */\n  examples: DatasetExample[];\n  versions: Array<DatasetVersion & { frozenCount: number }>;\n}\n\n/** Reference implementation: unit tests, `fx dev`, and harness fixtures. */\nexport class InMemoryDatasetStore implements DatasetStore {\n  private byTenant = new Map<string, Map<string, StoredDataset>>();\n\n  private tenant(tenantId: string): Map<string, StoredDataset> {\n    let m = this.byTenant.get(tenantId);\n    if (!m) {\n      m = new Map();\n      this.byTenant.set(tenantId, m);\n    }\n    return m;\n  }\n\n  async create(tenantId: string, spec: DatasetSpec, nowIso: string): Promise<Dataset> {\n    const m = this.tenant(tenantId);\n    if (m.has(spec.id)) throw new Error(`dataset already exists: ${spec.id}`);\n    const dataset: Dataset = {\n      ...spec,\n      tenantId,\n      latestVersion: 0,\n      exampleCount: 0,\n      createdAtIso: nowIso,\n      updatedAtIso: nowIso,\n    };\n    m.set(spec.id, { dataset, examples: [], versions: [] });\n    return clone(dataset);\n  }\n\n  async get(tenantId: string, datasetId: string): Promise<Dataset | null> {\n    const dataset = this.tenant(tenantId).get(datasetId)?.dataset;\n    return dataset ? clone(dataset) : null;\n  }\n\n  async list(tenantId: string): Promise<Dataset[]> {\n    return [...this.tenant(tenantId).values()].map((s) => clone(s.dataset));\n  }\n\n  async addExamples(\n    tenantId: string,\n    datasetId: string,\n    examples: readonly DatasetExample[],\n    nowIso: string,\n  ): Promise<DatasetExample[]> {\n    const stored = this.require(tenantId, datasetId);\n    const validated = examples.map((example) => DatasetExample.parse(example));\n    const ids = new Set(stored.examples.map((e) => e.exampleId));\n    for (const e of validated) {\n      if (ids.has(e.exampleId)) throw new Error(`duplicate exampleId: ${e.exampleId}`);\n      ids.add(e.exampleId);\n    }\n    // Keep an owned copy. Callers may mutate the object they passed after this\n    // method returns; a frozen version must never change as a side effect.\n    stored.examples.push(...validated.map(clone));\n    stored.dataset = {\n      ...stored.dataset,\n      exampleCount: stored.examples.length,\n      updatedAtIso: nowIso,\n    };\n    return validated.map(clone);\n  }\n\n  async listExamples(query: ListExamplesQuery): Promise<ExamplePage> {\n    const stored = this.require(query.tenantId, query.datasetId);\n    let pool = stored.examples;\n    if (query.version !== undefined) {\n      const v = stored.versions.find((x) => x.version === query.version);\n      if (!v) throw new Error(`unknown version ${query.version} for dataset ${query.datasetId}`);\n      pool = pool.slice(0, v.frozenCount);\n    }\n    if (query.split) pool = pool.filter((e) => e.split === query.split);\n    const offset = query.offset ?? 0;\n    const limit = query.limit ?? 100;\n    return { examples: pool.slice(offset, offset + limit).map(clone), total: pool.length };\n  }\n\n  async createVersion(\n    tenantId: string,\n    datasetId: string,\n    nowIso: string,\n    note?: string,\n  ): Promise<DatasetVersion> {\n    const stored = this.require(tenantId, datasetId);\n    const frozenCount = stored.examples.length;\n    const contentHash = hashExamples(stored.examples);\n    const version: DatasetVersion & { frozenCount: number } = {\n      datasetId,\n      version: stored.dataset.latestVersion + 1,\n      exampleCount: frozenCount,\n      contentHash,\n      createdAtIso: nowIso,\n      ...(note === undefined ? {} : { note }),\n      frozenCount,\n    };\n    stored.versions.push(version);\n    stored.dataset = { ...stored.dataset, latestVersion: version.version, updatedAtIso: nowIso };\n    const { frozenCount: _drop, ...pub } = version;\n    return clone(pub);\n  }\n\n  async listVersions(tenantId: string, datasetId: string): Promise<DatasetVersion[]> {\n    return this.require(tenantId, datasetId).versions.map(({ frozenCount: _drop, ...v }) =>\n      clone(v),\n    );\n  }\n\n  private require(tenantId: string, datasetId: string): StoredDataset {\n    const stored = this.tenant(tenantId).get(datasetId);\n    if (!stored) throw new Error(`unknown dataset: ${datasetId}`);\n    return stored;\n  }\n}\n\n/** Content hash over sorted example ids + per-example canonical hashes. */\nexport function hashExamples(examples: readonly DatasetExample[]): string {\n  const entries = examples\n    .map((e) => [e.exampleId, sha256Hex(canonicalJson(e))] as const)\n    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));\n  return sha256Hex(canonicalJson(entries));\n}\n\nfunction clone<T>(value: T): T {\n  return structuredClone(value);\n}\n","import { DatasetExample } from './schema.js';\n\nexport interface ImportResult {\n  examples: DatasetExample[];\n  errors: Array<{ line: number; message: string }>;\n}\n\n/**\n * Parse JSONL into examples. Accepts either full example objects (with\n * `exampleId`) or bare `{input, expectedOutput?, metadata?, split?}` rows;\n * bare rows get ids from `makeId` (injected — no ambient randomness, matching\n * the deterministic-by-default rule the Harness agents follow).\n */\nexport function parseJsonl(text: string, makeId: (line: number) => string): ImportResult {\n  const examples: DatasetExample[] = [];\n  const errors: ImportResult['errors'] = [];\n  const lines = text.split('\\n');\n  for (let i = 0; i < lines.length; i++) {\n    const raw = lines[i]!.trim();\n    if (raw === '') continue;\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(raw);\n    } catch (e) {\n      errors.push({ line: i + 1, message: `invalid JSON: ${(e as Error).message}` });\n      continue;\n    }\n    const candidate =\n      parsed !== null && typeof parsed === 'object' && !('exampleId' in (parsed as object))\n        ? { ...(parsed as object), exampleId: makeId(i + 1) }\n        : parsed;\n    const result = DatasetExample.safeParse(candidate);\n    if (result.success) examples.push(result.data);\n    else\n      errors.push({ line: i + 1, message: result.error.issues[0]?.message ?? 'invalid example' });\n  }\n  return { examples, errors };\n}\n"]}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@fabricorg/experiments-datasets",
+  "version": "0.1.0",
+  "description": "Versioned evaluation datasets for Fabric Experiments: schemas, store contract, JSONL import.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "module": "./dist/index.js",
+  "exports": {
+    ".": {
+      "import": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
+      "require": { "types": "./dist/index.d.cts", "default": "./dist/index.cjs" }
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.7"
+  }
+}