openpond-sdk 0.11.5 → 0.11.6

package/dist/dataset-workspaces.js

@@ -1,4 +1,8 @@
 import {
+  TaskDesignProposalSchema
+} from "./chunk-2NBI5UOK.js";
+import {
+  ConnectedCaseRefSchema,
   DatasetWorkspaceBeginVersionSchema,
   DatasetWorkspaceListQuerySchema,
   DatasetWorkspaceListSchema,
@@ -7,30 +11,38 @@ import {
   DatasetWorkspaceValidationSchema,
   DatasetWorkspaceVersionsSchema,
   DatasetWorkspaceWriteSchema
-} from "./chunk-4IWDOYKR.js";
+} from "./chunk-ILXO64IV.js";
 import {
   compileTasksetDraftWorkspace
-} from "./chunk-AQGFJLIV.js";
+} from "./chunk-NFLEPINR.js";
 import {
+  TasksetDraftSchema,
+  createTasksetDraft,
+  createTasksetDraftFile,
+  createTasksetDraftWorkspace,
+  decodeTasksetDraftFileContent,
   validateTasksetDraftWorkspace
-} from "./chunk-LQ5Q35IF.js";
+} from "./chunk-NA7PNRQZ.js";
 import {
   TasksetCatalogReleaseRefSchema
 } from "./chunk-K3JCP4FO.js";
-import "./chunk-PXNHL3SH.js";
-import "./chunk-FDHIL2CV.js";
-import "./chunk-Z4OLAEPL.js";
+import "./chunk-IPWCUGDN.js";
+import "./chunk-IS3P4OOW.js";
+import {
+  TaskDataRecordSchema,
+  TasksetSourceRefSchema
+} from "./chunk-OLHLJ2X3.js";
 import "./chunk-2U54EOXJ.js";
-import "./chunk-XYVPLV6Z.js";
-import "./chunk-5GMY4TTF.js";
-import "./chunk-35OVUYPI.js";
-import "./chunk-JOKRT4CK.js";
+import "./chunk-TTAFUUHZ.js";
+import "./chunk-OEPYLZXK.js";
+import "./chunk-YSKUXQ2N.js";
+import "./chunk-KV6JXPQH.js";
 import "./chunk-KAE7AMYE.js";
 import {
   ExperimentGraderPinSchema
-} from "./chunk-HAOPRFYQ.js";
-import "./chunk-WTHJ3H4M.js";
-import "./chunk-DUJXF7YI.js";
+} from "./chunk-L5PQPAU6.js";
+import "./chunk-7WUJBFCH.js";
+import "./chunk-CK3ONRRC.js";
 import "./chunk-TCHAWJMB.js";
 import "./chunk-3KXDH6OB.js";
 import {
@@ -48,6 +60,676 @@ var DatasetWorkspaceOperationResultSchema = z.object({ operationId: z.string().t
   if (kind !== actualKind) context.addIssue({ code: "custom", message: "Operation recovery kind differs from its retained lifecycle." });
 });
 
+// src/dataset-preparation-client.ts
+import { z as z3 } from "zod";
+
+// src/dataset-preparation-contracts.ts
+import { z as z2 } from "zod";
+var Id = z2.string().trim().min(1).max(240);
+var Hash = z2.string().regex(/^[a-f0-9]{64}$/);
+var Timestamp = z2.iso.datetime();
+var Count = z2.number().int().nonnegative();
+var MicroUsd = z2.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+var DatasetPreparationGrantCreateSchema = z2.object({
+  id: Id,
+  projectId: Id,
+  maximumMicroUsd: MicroUsd.positive(),
+  maximumSandboxSeconds: Count.max(10800)
+}).strict();
+var DatasetPreparationGrantSchema = z2.object({
+  schemaVersion: z2.literal("openpond.datasetPreparationGrant.v1"),
+  id: Id,
+  teamId: Id,
+  ownerUserId: Id,
+  projectId: Id,
+  maximumMicroUsd: MicroUsd,
+  maximumSandboxSeconds: Count,
+  settledMicroUsd: MicroUsd,
+  heldMicroUsd: MicroUsd,
+  sandboxSeconds: Count,
+  heldSandboxSeconds: Count,
+  unresolvedCalls: Count,
+  cleanupPending: Count,
+  createdAt: Timestamp,
+  updatedAt: Timestamp
+}).strict();
+var DatasetPreparationTaskClassSchema = z2.enum([
+  "coding_change",
+  "debugging",
+  "code_explanation",
+  "structured_text",
+  "artifact_work"
+]);
+var DatasetPreparationStageSchema = z2.enum([
+  "inventory",
+  "preview",
+  "reconstruction",
+  "grader_authoring",
+  "qualification",
+  "release"
+]);
+var DatasetPreparationStatusSchema = z2.enum([
+  "draft",
+  "running",
+  "pausing",
+  "paused",
+  "needs_attention",
+  "preview_ready",
+  "ready",
+  "releasing",
+  "completed",
+  "insufficient_data",
+  "budget_exhausted",
+  "cancelling",
+  "cancelled",
+  "failed"
+]);
+var DatasetPreparationSourceSchema = z2.object({
+  projectId: Id,
+  from: Timestamp,
+  to: Timestamp,
+  importCutoff: Timestamp,
+  connections: z2.array(Id).min(1).max(50)
+}).strict().superRefine((value, ctx) => {
+  if (Date.parse(value.from) >= Date.parse(value.to))
+    ctx.addIssue({
+      code: "custom",
+      message: "Source event-time window must be nonempty."
+    });
+  if (new Set(value.connections).size !== value.connections.length)
+    ctx.addIssue({
+      code: "custom",
+      message: "Source connections must be unique."
+    });
+});
+var DatasetPreparationPolicySchema = z2.object({
+  source: DatasetPreparationSourceSchema,
+  taskClasses: z2.array(DatasetPreparationTaskClassSchema).min(1).max(5),
+  limits: z2.object({
+    maximumConversations: z2.number().int().min(1).max(1e4),
+    maximumCandidates: z2.number().int().min(1).max(1e4),
+    acceptedTarget: z2.number().int().min(1).max(1e4),
+    maximumRepairsPerCandidate: z2.number().int().min(0).max(5),
+    maximumEvidenceBytesPerConversation: z2.number().int().min(1024).max(2e6)
+  }).strict(),
+  researcher: z2.object({
+    modelId: Id,
+    maximumOutputTokens: z2.number().int().min(1).max(32768)
+  }).strict(),
+  grading: z2.discriminatedUnion("mode", [
+    z2.object({ mode: z2.literal("auto") }).strict(),
+    z2.object({ mode: z2.literal("existing_only") }).strict(),
+    z2.object({
+      mode: z2.literal("manual"),
+      releases: z2.array(TasksetCatalogReleaseRefSchema).min(1).max(100)
+    }).strict()
+  ]),
+  budget: z2.object({
+    grantId: Id,
+    maximumMicroUsd: MicroUsd.positive(),
+    previewMaximumMicroUsd: MicroUsd,
+    qualificationMaximumMicroUsdPerCandidate: MicroUsd,
+    maximumSandboxSeconds: Count.max(10800)
+  }).strict(),
+  finish: z2.enum(["stop_ready", "create_private_version"]),
+  execution: z2.enum(["preview_only", "prepare"]),
+  allowPartialVersion: z2.boolean(),
+  // Pilot-inspected material is development data. Protected study preparation
+  // uses a separate authorization and cannot inherit this inspection policy.
+  population: z2.literal("development")
+}).strict().superRefine((value, ctx) => {
+  if (value.limits.acceptedTarget > value.limits.maximumCandidates)
+    ctx.addIssue({
+      code: "custom",
+      message: "Accepted target exceeds candidate scan limit."
+    });
+  if (value.budget.previewMaximumMicroUsd > value.budget.maximumMicroUsd)
+    ctx.addIssue({
+      code: "custom",
+      message: "Preview allowance exceeds the shared preparation ceiling."
+    });
+  if (new Set(value.taskClasses).size !== value.taskClasses.length)
+    ctx.addIssue({ code: "custom", message: "Task classes must be unique." });
+});
+var DatasetPreparationCreateSchema = z2.object({
+  operationId: Id,
+  expectedDatasetRevision: z2.number().int().positive(),
+  policy: DatasetPreparationPolicySchema
+}).strict();
+var DatasetPreparationCommandSchema = z2.discriminatedUnion("action", [
+  z2.object({
+    action: z2.enum(["start", "pause", "resume", "cancel", "release"]),
+    operationId: Id,
+    expectedRevision: z2.number().int().positive()
+  }).strict(),
+  z2.object({
+    action: z2.literal("resolve"),
+    operationId: Id,
+    expectedRevision: z2.number().int().positive(),
+    candidateId: Id,
+    decision: z2.enum(["retry", "exclude"]),
+    reason: z2.string().trim().min(1).max(5e3)
+  }).strict()
+]);
+var DatasetPreparationCoverageSchema = z2.object({
+  conversations: Count,
+  importedTurns: Count,
+  selectedTurns: Count,
+  queuedSnapshots: Count.nullable(),
+  failedSessions: Count.nullable(),
+  skippedSessions: Count.nullable(),
+  lastAdmissionAt: Timestamp.nullable(),
+  complete: z2.boolean(),
+  reasons: z2.array(
+    z2.object({ code: Id, message: z2.string().trim().min(1).max(2e3) }).strict()
+  ).max(100),
+  sourceInventoryHash: Hash
+}).strict();
+var DatasetPreparationAccountingSchema = z2.object({
+  maximumMicroUsd: MicroUsd,
+  settledMicroUsd: MicroUsd,
+  heldMicroUsd: MicroUsd,
+  unresolvedCalls: Count,
+  sandboxSeconds: Count,
+  cleanupPending: Count,
+  complete: z2.boolean()
+}).strict();
+var DatasetPreparationPreviewSchema = z2.object({
+  sampleConversations: Count,
+  sampleTurns: Count,
+  candidateCount: Count,
+  modelId: Id,
+  modelConfigurationHash: Hash,
+  callReceiptIds: z2.array(Id).max(2e3),
+  inputTokens: Count.nullable(),
+  outputTokens: Count.nullable(),
+  classes: z2.array(
+    z2.object({
+      taskClass: DatasetPreparationTaskClassSchema,
+      candidates: Count,
+      assessment: z2.enum([
+        "executable",
+        "calibrated_judge",
+        "unsupported"
+      ]),
+      requirements: z2.array(z2.string().trim().min(1).max(5e3)).max(20)
+    }).strict()
+  ).max(5),
+  exclusions: z2.array(
+    z2.object({
+      code: Id,
+      count: Count,
+      reason: z2.string().trim().min(1).max(5e3)
+    }).strict()
+  ).max(100),
+  estimates: z2.array(
+    z2.object({
+      stage: DatasetPreparationStageSchema,
+      minimumMicroUsd: MicroUsd,
+      maximumMicroUsd: MicroUsd,
+      assumptions: z2.array(z2.string().trim().min(1).max(2e3)).min(1).max(20)
+    }).strict().refine(
+      (value) => value.minimumMicroUsd <= value.maximumMicroUsd,
+      "Estimate range is reversed."
+    )
+  ).max(6),
+  createdAt: Timestamp
+}).strict();
+var DatasetPreparationRunSchema = z2.object({
+  schemaVersion: z2.literal("openpond.datasetPreparationRun.v1"),
+  id: Id,
+  operationId: Id,
+  teamId: Id,
+  ownerUserId: Id,
+  datasetId: Id,
+  datasetRevision: z2.number().int().positive(),
+  revision: z2.number().int().positive(),
+  requestHash: Hash,
+  policy: DatasetPreparationPolicySchema,
+  status: DatasetPreparationStatusSchema,
+  stage: DatasetPreparationStageSchema,
+  coverage: DatasetPreparationCoverageSchema.nullable(),
+  preview: DatasetPreparationPreviewSchema.nullable(),
+  counts: z2.object({
+    scannedConversations: Count,
+    scannedTurns: Count,
+    candidates: Count,
+    reconstructed: Count,
+    qualifying: Count,
+    qualified: Count,
+    excluded: Count,
+    needsAttention: Count
+  }).strict(),
+  accounting: DatasetPreparationAccountingSchema,
+  publication: z2.object({
+    datasetId: Id,
+    workspaceRevision: z2.number().int().positive(),
+    release: TasksetCatalogReleaseRefSchema
+  }).strict().nullable(),
+  error: z2.object({ code: Id, message: z2.string().trim().min(1).max(5e3) }).strict().nullable(),
+  createdAt: Timestamp,
+  updatedAt: Timestamp
+}).strict().superRefine((value, ctx) => {
+  if (value.accounting.maximumMicroUsd !== value.policy.budget.maximumMicroUsd)
+    ctx.addIssue({
+      code: "custom",
+      message: "Accounting authority differs from the saved preparation policy."
+    });
+  if (value.counts.qualified + value.counts.excluded + value.counts.needsAttention > value.counts.candidates)
+    ctx.addIssue({
+      code: "custom",
+      message: "Preparation outcomes exceed the candidate population."
+    });
+  if (value.status === "preview_ready" && (value.policy.execution !== "preview_only" || value.stage !== "preview" || !value.preview || !value.coverage?.complete || !value.accounting.complete)) ctx.addIssue({ code: "custom", message: "Preview readiness requires a preview-only policy, reconciled source coverage and settled preview calls." });
+  if (["ready", "releasing", "completed"].includes(value.status) && (value.counts.qualified === 0 || !value.policy.allowPartialVersion && value.counts.qualified < value.policy.limits.acceptedTarget))
+    ctx.addIssue({
+      code: "custom",
+      message: "Preparation cannot report readiness below its accepted target."
+    });
+  if (["ready", "releasing", "completed"].includes(value.status) && (value.policy.execution !== "prepare" || !value.preview || !value.coverage?.complete || !value.accounting.complete))
+    ctx.addIssue({ code: "custom", message: "Dataset readiness requires full preparation authority, reconciled source coverage, preview and final accounting." });
+  if (value.status === "completed" && (!value.publication || !value.accounting.complete))
+    ctx.addIssue({
+      code: "custom",
+      message: "Completed preparation requires publication and reconciled accounting."
+    });
+  if (value.status === "cancelled" && (!value.accounting.complete || value.accounting.cleanupPending > 0))
+    ctx.addIssue({
+      code: "custom",
+      message: "Cancellation requires settled resource obligations."
+    });
+});
+var DatasetPreparationListSchema = z2.object({
+  teamId: Id,
+  datasetId: Id,
+  runs: z2.array(DatasetPreparationRunSchema).max(50),
+  nextCursor: Id.nullable()
+}).strict();
+var PreparedTaskEvidenceSpanSchema = z2.object({
+  source: ConnectedCaseRefSchema,
+  startSequence: Count,
+  endSequence: Count,
+  role: z2.enum([
+    "requirement",
+    "initial_context",
+    "outcome",
+    "correction",
+    "verification"
+  ])
+}).strict().superRefine((value, ctx) => {
+  if (value.endSequence < value.startSequence)
+    ctx.addIssue({
+      code: "custom",
+      message: "Evidence span must be ordered."
+    });
+});
+var PreparedTaskProvenanceSchema = z2.object({
+  schemaVersion: z2.literal("openpond.preparedTaskProvenance.v1"),
+  candidateId: Id,
+  preparationId: Id,
+  familyKey: Id,
+  sourceSpans: z2.array(PreparedTaskEvidenceSpanSchema).min(1).max(200),
+  firstAvailableAt: Timestamp,
+  initialInputHash: Hash,
+  initialEnvironmentHash: Hash,
+  sourceScopeHash: Hash
+}).strict().superRefine((value, ctx) => {
+  if (!value.sourceSpans.some((span) => span.role === "requirement"))
+    ctx.addIssue({
+      code: "custom",
+      message: "A reconstructed task needs a source requirement."
+    });
+  const seen = /* @__PURE__ */ new Set();
+  for (const span of value.sourceSpans) {
+    if (value.sourceSpans.some((other) => other !== span && other.source.id === span.source.id && other.source.snapshotHash === span.source.snapshotHash && other.role !== span.role && span.startSequence <= other.endSequence && other.startSequence <= span.endSequence))
+      ctx.addIssue({ code: "custom", message: "Evidence offsets cannot have conflicting roles." });
+    const key = JSON.stringify([
+      span.source,
+      span.startSequence,
+      span.endSequence
+    ]);
+    if (seen.has(key))
+      ctx.addIssue({
+        code: "custom",
+        message: "Evidence span is duplicated or crosses public/private roles."
+      });
+    seen.add(key);
+  }
+});
+var PreparedTaskQualificationSchema = z2.object({
+  schemaVersion: z2.literal("openpond.preparedTaskQualification.v1"),
+  id: Id,
+  candidateId: Id,
+  preparationId: Id,
+  taskHash: Hash,
+  environmentHash: Hash,
+  packageHash: Hash,
+  graderBindings: z2.array(
+    z2.object({
+      id: Id,
+      version: Id,
+      contentHash: Hash,
+      origin: z2.enum(["reused", "adapted", "authored"])
+    }).strict()
+  ).min(1).max(100),
+  checks: z2.array(
+    z2.object({
+      id: Id,
+      label: z2.enum([
+        "positive",
+        "incorrect",
+        "incomplete",
+        "adversarial",
+        "clean_reset"
+      ]),
+      executionReceiptId: Id,
+      expectedPassed: z2.boolean(),
+      observedPassed: z2.boolean().nullable(),
+      infrastructureError: Id.nullable()
+    }).strict()
+  ).min(5).max(500),
+  independentEvidenceRefs: z2.array(Id).min(1).max(100),
+  judgeCalibration: z2.enum(["not_applicable", "passed", "failed", "pending"]),
+  cleanup: z2.enum(["completed", "pending"]),
+  passed: z2.boolean(),
+  createdAt: Timestamp
+}).strict().superRefine((value, ctx) => {
+  if (!value.passed) return;
+  const labels = new Set(value.checks.map((check) => check.label));
+  if ([
+    "positive",
+    "incorrect",
+    "incomplete",
+    "adversarial",
+    "clean_reset"
+  ].some(
+    (label) => !labels.has(label)
+  ))
+    ctx.addIssue({
+      code: "custom",
+      message: "Qualified tasks require positive, negative, adversarial and clean-reset evidence."
+    });
+  if (value.cleanup !== "completed" || ["pending", "failed"].includes(value.judgeCalibration) || value.checks.some(
+    (check) => check.infrastructureError !== null || check.observedPassed !== check.expectedPassed
+  ))
+    ctx.addIssue({
+      code: "custom",
+      message: "Failed, uncalibrated or uncleared checks cannot qualify a task."
+    });
+  if (value.checks.some(
+    (check) => check.expectedPassed !== ["positive", "clean_reset"].includes(check.label)
+  ))
+    ctx.addIssue({
+      code: "custom",
+      message: "Qualification witnesses must pass positives/resets and reject incorrect, incomplete and adversarial outputs."
+    });
+});
+var DatasetPreparationCandidateSchema = z2.object({
+  id: Id,
+  runId: Id,
+  revision: z2.number().int().positive(),
+  taskClass: DatasetPreparationTaskClassSchema,
+  status: z2.enum([
+    "discovered",
+    "reconstructing",
+    "authoring",
+    "qualifying",
+    "qualified",
+    "excluded",
+    "needs_attention"
+  ]),
+  objective: z2.string().trim().min(1).max(2e4),
+  provenance: PreparedTaskProvenanceSchema.nullable(),
+  qualification: PreparedTaskQualificationSchema.nullable(),
+  reason: z2.object({ code: Id, message: z2.string().trim().min(1).max(5e3) }).strict().nullable(),
+  attempts: Count.max(6)
+}).strict().superRefine((value, ctx) => {
+  if (value.status === "qualified" && (!value.provenance || !value.qualification?.passed))
+    ctx.addIssue({
+      code: "custom",
+      message: "Candidate admission requires reconstruction and qualification receipts."
+    });
+  if (value.provenance && (value.provenance.candidateId !== value.id || value.provenance.preparationId !== value.runId))
+    ctx.addIssue({
+      code: "custom",
+      message: "Candidate provenance identity mismatch."
+    });
+  if (value.qualification && (value.qualification.candidateId !== value.id || value.qualification.preparationId !== value.runId))
+    ctx.addIssue({
+      code: "custom",
+      message: "Candidate qualification identity mismatch."
+    });
+});
+
+// src/dataset-preparation-client.ts
+var Id2 = z3.string().trim().min(1).max(240);
+var CandidatePage = z3.object({
+  teamId: Id2,
+  datasetId: Id2,
+  runId: Id2,
+  candidates: z3.array(DatasetPreparationCandidateSchema).max(50),
+  nextCursor: Id2.nullable()
+}).strict();
+var DatasetPreparationRequestError = class extends Error {
+  constructor(status, code, message) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.name = "DatasetPreparationRequestError";
+  }
+  status;
+  code;
+};
+var OpenPondDatasetPreparationClient = class {
+  constructor(options) {
+    this.options = options;
+    const url = new URL(options.baseUrl);
+    if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.search || url.hash || !options.apiKey.trim() || !options.teamId.trim())
+      throw new Error(
+        "A clean API origin and workspace credentials are required."
+      );
+    this.baseUrl = url.toString().replace(/\/+$/, "");
+  }
+  options;
+  baseUrl;
+  async create(datasetId, input, signal) {
+    const request = DatasetPreparationCreateSchema.parse(input);
+    const result = this.readRun(
+      await this.request(datasetId, "", "POST", request, signal),
+      datasetId
+    );
+    if (result.operationId !== request.operationId || result.requestHash !== contentHash(request) || result.datasetRevision !== request.expectedDatasetRevision)
+      throw new Error(
+        "Preparation creation receipt differs from the saved intent."
+      );
+    return result;
+  }
+  async createGrant(datasetId, input, signal) {
+    const request = DatasetPreparationGrantCreateSchema.parse(input);
+    const grant = this.readGrant(
+      await this.request(datasetId, "/grants", "POST", request, signal)
+    );
+    if (grant.id !== request.id || grant.projectId !== request.projectId || grant.maximumMicroUsd !== request.maximumMicroUsd || grant.maximumSandboxSeconds !== request.maximumSandboxSeconds)
+      throw new Error(
+        "Preparation grant receipt differs from the saved limits."
+      );
+    return grant;
+  }
+  async getGrant(datasetId, grantId, signal) {
+    const grant = this.readGrant(
+      await this.request(
+        datasetId,
+        `/grants/${encodeURIComponent(Id2.parse(grantId))}`,
+        "GET",
+        void 0,
+        signal
+      )
+    );
+    if (grant.id !== grantId)
+      throw new Error("Preparation grant identity mismatch.");
+    return grant;
+  }
+  readGrant(value) {
+    const grant = DatasetPreparationGrantSchema.parse(value);
+    if (grant.teamId !== this.options.teamId)
+      throw new Error("Preparation grant workspace mismatch.");
+    return grant;
+  }
+  async get(datasetId, runId, signal) {
+    return this.readRun(
+      await this.request(
+        datasetId,
+        `/${encodeURIComponent(Id2.parse(runId))}`,
+        "GET",
+        void 0,
+        signal
+      ),
+      datasetId,
+      runId
+    );
+  }
+  async list(datasetId, options = {}) {
+    const query = new URLSearchParams(
+      options.cursor ? { cursor: Id2.parse(options.cursor) } : {}
+    );
+    const result = DatasetPreparationListSchema.parse(
+      await this.request(
+        datasetId,
+        `?${query}`,
+        "GET",
+        void 0,
+        options.signal
+      )
+    );
+    if (result.teamId !== this.options.teamId || result.datasetId !== datasetId || result.runs.some(
+      (run) => run.teamId !== result.teamId || run.datasetId !== datasetId
+    ) || new Set(result.runs.map((run) => run.id)).size !== result.runs.length)
+      throw new Error("Preparation list scope/identity mismatch.");
+    return result;
+  }
+  async command(datasetId, runId, input, signal) {
+    const request = DatasetPreparationCommandSchema.parse(input);
+    const result = this.readRun(
+      await this.request(
+        datasetId,
+        `/${encodeURIComponent(Id2.parse(runId))}/commands`,
+        "POST",
+        request,
+        signal
+      ),
+      datasetId,
+      runId
+    );
+    if (result.revision < request.expectedRevision + 1)
+      throw new Error(
+        "Preparation command did not advance the expected revision."
+      );
+    return result;
+  }
+  async operationResult(datasetId, operationId, signal) {
+    const result = await this.request(
+      datasetId,
+      `/operations/${encodeURIComponent(Id2.parse(operationId))}`,
+      "GET",
+      void 0,
+      signal
+    );
+    if (result === null) return null;
+    const receipt = z3.object({
+      operationId: Id2,
+      requestHash: z3.string().regex(/^[a-f0-9]{64}$/),
+      run: DatasetPreparationRunSchema
+    }).strict().parse(result);
+    if (receipt.operationId !== operationId)
+      throw new Error("Preparation operation recovery identity mismatch.");
+    this.readRun(receipt.run, datasetId);
+    return receipt;
+  }
+  async candidates(datasetId, runId, options = {}) {
+    const query = new URLSearchParams(
+      options.cursor ? { cursor: Id2.parse(options.cursor) } : {}
+    );
+    const result = CandidatePage.parse(
+      await this.request(
+        datasetId,
+        `/${encodeURIComponent(Id2.parse(runId))}/candidates?${query}`,
+        "GET",
+        void 0,
+        options.signal
+      )
+    );
+    if (result.teamId !== this.options.teamId || result.datasetId !== datasetId || result.runId !== runId || result.candidates.some((candidate) => candidate.runId !== runId) || new Set(result.candidates.map((candidate) => candidate.id)).size !== result.candidates.length)
+      throw new Error("Preparation candidate page scope/identity mismatch.");
+    return result;
+  }
+  readRun(value, datasetId, runId) {
+    const result = DatasetPreparationRunSchema.parse(value);
+    if (result.teamId !== this.options.teamId || result.datasetId !== datasetId || runId && result.id !== runId)
+      throw new Error("Preparation run scope/identity mismatch.");
+    return result;
+  }
+  async request(datasetId, path, method, body, signal) {
+    const response = await (this.options.fetch ?? fetch)(
+      `${this.baseUrl}/v1/dataset-workspaces/${encodeURIComponent(Id2.parse(datasetId))}/preparations${path}`,
+      {
+        method,
+        signal,
+        redirect: "error",
+        headers: {
+          Authorization: `Bearer ${this.options.apiKey}`,
+          "X-OpenPond-Team-Id": this.options.teamId,
+          "Content-Type": "application/json"
+        },
+        ...body === void 0 ? {} : { body: JSON.stringify(body) }
+      }
+    );
+    if (!response.body) {
+      if (!response.ok)
+        throw new DatasetPreparationRequestError(
+          response.status,
+          "dataset_preparation_request_failed",
+          `Dataset preparation request failed (${response.status}).`
+        );
+      throw new Error("Preparation response is empty.");
+    }
+    const reader = response.body.getReader(), chunks = [];
+    let length = 0;
+    try {
+      while (true) {
+        const part = await reader.read();
+        if (part.done) break;
+        length += part.value.byteLength;
+        if (length > (response.ok ? 8 * 1024 * 1024 : 64 * 1024))
+          throw new Error("Preparation response exceeds its bounded page.");
+        chunks.push(part.value);
+      }
+    } finally {
+      await reader.cancel();
+    }
+    const bytes = new Uint8Array(length);
+    let offset = 0;
+    for (const chunk of chunks) {
+      bytes.set(chunk, offset);
+      offset += chunk.length;
+    }
+    const raw = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    if (!response.ok) {
+      let value = null;
+      try {
+        value = JSON.parse(raw);
+      } catch {
+      }
+      const error = z3.object({ code: z3.string().max(240), message: z3.string().max(5e3) }).safeParse(value);
+      throw new DatasetPreparationRequestError(
+        response.status,
+        error.success ? error.data.code : "dataset_preparation_request_failed",
+        error.success ? error.data.message : `Dataset preparation request failed (${response.status}).`
+      );
+    }
+    return JSON.parse(raw);
+  }
+};
+
 // src/dataset-workspace-client.ts
 var OpenPondDatasetWorkspaceClient = class {
   constructor(options) {
@@ -55,9 +737,11 @@ var OpenPondDatasetWorkspaceClient = class {
     const url = new URL(options.baseUrl);
     if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.search || url.hash || !options.apiKey.trim() || !options.teamId.trim()) throw new Error("A clean API origin and workspace credentials are required.");
     this.baseUrl = url.toString().replace(/\/+$/, "");
+    this.preparations = new OpenPondDatasetPreparationClient(options);
   }
   options;
   baseUrl;
+  preparations;
   async list(options = {}) {
     const { signal, ...input } = options;
     const query = DatasetWorkspaceListQuerySchema.parse(input);
@@ -164,33 +848,33 @@ var OpenPondDatasetWorkspaceClient = class {
 
 // src/dataset-population.ts
 import { TaskSplitSchema, TaskRecordSchema } from "@openpond/evals/tasksets";
-import { z as z2 } from "zod";
-var Id = z2.string().trim().min(1).max(500);
-var Hash = z2.string().regex(/^[a-f0-9]{64}$/);
-var DatasetPopulationQuerySchema = z2.object({
+import { z as z4 } from "zod";
+var Id3 = z4.string().trim().min(1).max(500);
+var Hash2 = z4.string().regex(/^[a-f0-9]{64}$/);
+var DatasetPopulationQuerySchema = z4.object({
   release: TasksetCatalogReleaseRefSchema,
-  afterId: Id.optional(),
-  limit: z2.number().int().min(1).max(1e4).default(100),
-  view: z2.enum(["ids", "policy"]).default("ids")
+  afterId: Id3.optional(),
+  limit: z4.number().int().min(1).max(1e4).default(100),
+  view: z4.enum(["ids", "policy"]).default("ids")
 }).strict().superRefine((query, context) => {
   if (query.view === "policy" && query.limit > 100) context.addIssue({ code: "custom", path: ["limit"], message: "Policy previews are bounded to 100 tasks." });
 });
-var TaskIdentity = z2.object({ id: TaskRecordSchema.shape.id, split: TaskSplitSchema }).strict();
+var TaskIdentity = z4.object({ id: TaskRecordSchema.shape.id, split: TaskSplitSchema }).strict();
 var PolicyTask = TaskIdentity.extend({
-  input: z2.record(z2.string(), z2.unknown()),
-  policyVisibleContext: z2.record(z2.string(), z2.unknown()),
-  artifacts: z2.array(z2.object({ id: Id, path: z2.string(), mediaType: z2.string(), sizeBytes: z2.number().int().nonnegative() }).strict()).max(1e3)
+  input: z4.record(z4.string(), z4.unknown()),
+  policyVisibleContext: z4.record(z4.string(), z4.unknown()),
+  artifacts: z4.array(z4.object({ id: Id3, path: z4.string(), mediaType: z4.string(), sizeBytes: z4.number().int().nonnegative() }).strict()).max(1e3)
 }).strict();
-var DatasetPopulationPageSchema = z2.object({
-  schemaVersion: z2.literal("openpond.datasetPopulationPage.v1"),
-  teamId: Id,
+var DatasetPopulationPageSchema = z4.object({
+  schemaVersion: z4.literal("openpond.datasetPopulationPage.v1"),
+  teamId: Id3,
   release: TasksetCatalogReleaseRefSchema,
   view: DatasetPopulationQuerySchema.shape.view,
-  taskCount: z2.number().int().nonnegative(),
-  items: z2.array(z2.union([TaskIdentity, PolicyTask])).max(1e4),
-  graders: z2.array(ExperimentGraderPinSchema).max(1e3),
-  nextCursor: Id.nullable(),
-  contentHash: Hash
+  taskCount: z4.number().int().nonnegative(),
+  items: z4.array(z4.union([TaskIdentity, PolicyTask])).max(1e4),
+  graders: z4.array(ExperimentGraderPinSchema).max(1e3),
+  nextCursor: Id3.nullable(),
+  contentHash: Hash2
 }).strict().superRefine((page, context) => {
   if (page.view === "policy" && page.items.length > 100) context.addIssue({ code: "custom", message: "Policy preview exceeded its task bound." });
   if (page.items.some((item) => "input" in item !== (page.view === "policy"))) context.addIssue({ code: "custom", message: "Dataset task view differs from the requested projection." });
@@ -227,16 +911,153 @@ var OpenPondDatasetPopulationClient = class {
       reader.releaseLock();
     }
     const raw = JSON.parse(source);
-    if (!response.ok) throw new Error(z2.object({ message: z2.string() }).passthrough().parse(raw).message);
+    if (!response.ok) throw new Error(z4.object({ message: z4.string() }).passthrough().parse(raw).message);
     const page = DatasetPopulationPageSchema.parse(raw);
     const { contentHash: hash, ...content } = page;
     if (page.teamId !== this.options.teamId || contentHash(page.release) !== contentHash(query.release) || page.view !== query.view || page.items.length > query.limit || contentHash(content) !== hash || page.items.some((item, index) => query.afterId !== void 0 && item.id <= query.afterId || index > 0 && item.id <= page.items[index - 1].id) || page.nextCursor !== null && page.nextCursor !== page.items.at(-1)?.id) throw new Error("Dataset population identity, hash, order or bounds mismatch.");
     return page;
   }
 };
+
+// src/dataset-preparation-research-contracts.ts
+import { z as z5 } from "zod";
+var Id4 = z5.string().trim().min(1).max(240);
+var Text = z5.string().trim().min(1).max(5e3);
+var DatasetPreparationResearchCandidateSchema = z5.object({
+  taskClass: DatasetPreparationTaskClassSchema,
+  objective: z5.string().trim().min(1).max(2e4),
+  sourceSpans: z5.array(PreparedTaskEvidenceSpanSchema).min(1).max(200),
+  firstAvailableAt: z5.iso.datetime(),
+  reconstruction: z5.object({
+    kind: z5.enum(["text_only", "pinned_repository", "pinned_artifact", "unsupported"]),
+    requiredAssets: z5.array(z5.object({ reference: Text, evidence: PreparedTaskEvidenceSpanSchema }).strict()).max(100),
+    missingEvidence: z5.array(Text).max(20)
+  }).strict(),
+  assessment: z5.object({
+    kind: z5.enum(["executable", "calibrated_judge", "unsupported"]),
+    requirements: z5.array(z5.object({ criterion: Text, evidence: PreparedTaskEvidenceSpanSchema }).strict()).min(1).max(20),
+    limitations: z5.array(Text).max(20)
+  }).strict()
+}).strict().superRefine((value, ctx) => {
+  if (!value.sourceSpans.some((span) => span.role === "requirement"))
+    ctx.addIssue({ code: "custom", message: "A research candidate requires independently retained user requirements." });
+  if (value.assessment.requirements.some((item) => item.evidence.role !== "requirement"))
+    ctx.addIssue({ code: "custom", message: "Assessment criteria must cite user requirements, not historical answers." });
+});
+var DatasetPreparationResearchDecisionSchema = z5.object({
+  schemaVersion: z5.literal("openpond.datasetPreparationResearchDecision.v1"),
+  sourceId: Id4,
+  snapshotHash: z5.string().regex(/^[a-f0-9]{64}$/),
+  candidates: z5.array(DatasetPreparationResearchCandidateSchema).max(100),
+  exclusions: z5.array(z5.object({ code: Id4, reason: Text, sourceSpans: z5.array(PreparedTaskEvidenceSpanSchema).max(200) }).strict()).max(100),
+  contextSummary: z5.string().max(2e4)
+}).strict();
+
+// src/dataset-preparation-workspace.ts
+function createPreparedTaskAuthoringWorkspace(input) {
+  const provenance = PreparedTaskProvenanceSchema.parse(input.provenance);
+  const proposal = TaskDesignProposalSchema.parse(input.proposal);
+  const sources = input.sources.map((source) => TasksetSourceRefSchema.parse(source));
+  const environment = TasksetDraftSchema.shape.environment.parse(input.initialEnvironment);
+  if (contentHash(input.initialInput) !== provenance.initialInputHash || contentHash(environment) !== provenance.initialEnvironmentHash)
+    throw new Error("Prepared Taskset input or starting environment differs from its reconstruction.");
+  if (environment.kind !== "chat" || environment.stateful || environment.toolNames.length || (environment.resources?.length ?? 0) || proposal.taskKind !== "chat" || proposal.diagnosis.requiredTools.length)
+    throw new Error("Text preparation cannot silently add tools, state or starting assets.");
+  const sourceIds = new Set(sources.map((source) => source.id));
+  if (!sources.length || sourceIds.size !== sources.length || proposal.sourceIds.some((id) => !sourceIds.has(id)) || proposal.proposedExamples.length !== 1 || proposal.proposedExamples.some((example) => !sourceIds.has(example.sourceId)))
+    throw new Error("Prepared Taskset authoring must retain exactly one reconstructed task and its authorized evidence.");
+  if (!/^[a-f0-9]{64}$/.test(input.skillHash) || !input.modelId.trim() || !Number.isSafeInteger(input.attempt) || input.attempt < 1 || input.attempt > 6)
+    throw new Error("Prepared Taskset authoring provenance is invalid.");
+  if (!proposal.proposedGraders.length || new Set(proposal.proposedGraders.map((grader) => grader.id)).size !== proposal.proposedGraders.length)
+    throw new Error("Prepared Taskset needs distinct outcome graders.");
+  if (proposal.generatedFiles.some((file) => file.role === "environment"))
+    throw new Error("Generated code cannot replace the fixed initial text environment.");
+  if (proposal.graderFixtures.some((fixture) => fixture.taskIndex !== 0 || fixture.metadata.substituteExpectedOutput === true))
+    throw new Error("Prepared fixtures cannot refer to another task or substitute a historical answer.");
+  const draft = createTasksetDraft({
+    profileId: input.teamId,
+    id: `${provenance.candidateId}-attempt-${input.attempt}-draft`,
+    name: proposal.name,
+    now: input.createdAt
+  });
+  draft.objective = proposal.objective;
+  draft.sourceRefs = sources;
+  draft.environment = environment;
+  draft.graders = proposal.proposedGraders.map((grader) => ({
+    ...grader,
+    privileged: true,
+    ...grader.kind === "model_judge" ? { rewardEligible: false, calibrationStatus: "pending" } : {},
+    metadata: { ...grader.metadata, preparedTask: provenance.candidateId, authoringSkillHash: input.skillHash }
+  }));
+  draft.policy = {
+    policyVisibleFields: ["input"],
+    privilegedFields: ["expectedOutput"],
+    hiddenGraderRefs: draft.graders.map((grader) => grader.id),
+    connectedAppScopes: []
+  };
+  draft.tasks = [TaskDataRecordSchema.parse({
+    schemaVersion: "openpond.taskData.v1",
+    id: provenance.candidateId,
+    clusterKey: provenance.familyKey,
+    split: "validation",
+    input: input.initialInput,
+    expectedOutput: null,
+    policyVisibleContext: {},
+    privilegedContextRef: null,
+    sourceRefs: [...sourceIds],
+    tags: ["prepared-task", "development-exposed"],
+    metadata: { preparedTask: provenance, qualificationStatus: "pending" }
+  })];
+  draft.graderFixtures = proposal.graderFixtures.map(({ taskIndex: _index, ...fixture }) => ({
+    ...fixture,
+    taskId: provenance.candidateId,
+    metadata: { ...fixture.metadata, witnessOrigin: "authoring_proposal", independentlyQualified: false }
+  }));
+  draft.metadata = { datasetPreparation: {
+    schemaVersion: "openpond.datasetPreparationAuthoring.v1",
+    provenance,
+    modelId: input.modelId,
+    skillHash: input.skillHash,
+    proposalHash: contentHash(proposal),
+    attempt: input.attempt,
+    qualification: "pending",
+    exposure: "development"
+  } };
+  return createTasksetDraftWorkspace({
+    schemaVersion: "openpond.tasksetDraftWorkspace.v1",
+    draft,
+    files: proposal.generatedFiles.map((generated) => {
+      const file = createTasksetDraftFile(generated.path, new TextEncoder().encode(generated.content));
+      return {
+        path: file.path,
+        contentHash: file.contentHash,
+        sizeBytes: file.sizeBytes,
+        base64: Buffer.from(decodeTasksetDraftFileContent(file.content)).toString("base64")
+      };
+    })
+  });
+}
 export {
   DatasetPopulationPageSchema,
   DatasetPopulationQuerySchema,
+  DatasetPreparationAccountingSchema,
+  DatasetPreparationCandidateSchema,
+  DatasetPreparationCommandSchema,
+  DatasetPreparationCoverageSchema,
+  DatasetPreparationCreateSchema,
+  DatasetPreparationGrantCreateSchema,
+  DatasetPreparationGrantSchema,
+  DatasetPreparationListSchema,
+  DatasetPreparationPolicySchema,
+  DatasetPreparationPreviewSchema,
+  DatasetPreparationRequestError,
+  DatasetPreparationResearchCandidateSchema,
+  DatasetPreparationResearchDecisionSchema,
+  DatasetPreparationRunSchema,
+  DatasetPreparationSourceSchema,
+  DatasetPreparationStageSchema,
+  DatasetPreparationStatusSchema,
+  DatasetPreparationTaskClassSchema,
   DatasetWorkspaceBeginVersionSchema,
   DatasetWorkspaceListQuerySchema,
   DatasetWorkspaceListSchema,
@@ -248,7 +1069,12 @@ export {
   DatasetWorkspaceVersionsSchema,
   DatasetWorkspaceWriteSchema,
   OpenPondDatasetPopulationClient,
+  OpenPondDatasetPreparationClient,
   OpenPondDatasetWorkspaceClient,
-  compileTasksetDraftWorkspace
+  PreparedTaskEvidenceSpanSchema,
+  PreparedTaskProvenanceSchema,
+  PreparedTaskQualificationSchema,
+  compileTasksetDraftWorkspace,
+  createPreparedTaskAuthoringWorkspace
 };
 //# sourceMappingURL=dataset-workspaces.js.map