@openpond/evals 0.5.0 → 0.7.0

package/dist/learning/contracts.js

@@ -0,0 +1,267 @@
+import { LearningDomainError } from "./errors.js";
+import { z } from "zod";
+import { ImmutableAssetRefSchema, ImmutableReleaseRefSchema, ReleaseHashSchema, ReleaseIdSchema, ReleaseTimestampSchema, contentHash } from "@openpond/harness";
+import { RewardBindingSchema, RewardCompositionSchema, RewardReleaseRefSchema, RewardReleaseSchema } from "../rewards.js";
+import { TaskSplitSchema, TasksetReleaseContentSchema } from "../tasksets.js";
+import { assertBoundedTaskJson, validateTaskSchema } from "../task-schema.js";
+export const LearningJsonObjectSchema = z.record(z.string(), z.json());
+export const LearningRevisionRefSchema = RewardReleaseRefSchema;
+export const LearningJsonPointerSchema = z.string().max(2_000).refine((value) => value === "" || (value.startsWith("/") && !/~(?![01])/u.test(value)), "Use an RFC 6901 JSON pointer.");
+export const TaskDefinitionContentSchema = z.object({
+    schemaVersion: z.literal("openpond.taskDefinition.v1"),
+    id: ReleaseIdSchema,
+    revision: z.number().int().positive(),
+    name: z.string().trim().min(1).max(500),
+    description: z.string().max(10_000),
+    instructions: z.string().trim().min(1).max(20_000),
+    category: z.enum(["structured", "question_answering", "coding", "tool_workflow", "custom"]),
+    familyNamespace: ReleaseIdSchema,
+    inputSchema: z.record(z.string(), z.unknown()),
+    outputSchema: z.record(z.string(), z.unknown()),
+    rewardBinding: LearningRevisionRefSchema,
+    harness: ImmutableReleaseRefSchema.nullable(),
+    execution: TasksetReleaseContentSchema.pick({ policy: true, environment: true, environmentRelease: true, tools: true, capabilities: true, verifierSetRelease: true }).strict(),
+}).strict().superRefine((definition, context) => {
+    for (const field of ["inputSchema", "outputSchema"]) {
+        const schema = definition[field];
+        if (schema.type !== "object")
+            context.addIssue({ code: "custom", path: [field], message: "Task input/output use object envelopes; declare type: object." });
+        const report = validateTaskSchema(schema);
+        if (!report.valid)
+            context.addIssue({ code: "custom", path: [field], message: report.issues[0].message });
+    }
+    if (Boolean(definition.execution.environmentRelease) !== Boolean(definition.execution.verifierSetRelease))
+        context.addIssue({ code: "custom", path: ["execution"], message: "Bind both the environment and verifier-set releases." });
+});
+export const TaskDefinitionSchema = TaskDefinitionContentSchema.safeExtend({ contentHash: ReleaseHashSchema }).strict();
+export const TaskSourceMappingSchema = z.object({
+    schemaVersion: z.literal("openpond.taskSourceMapping.v1"),
+    exampleId: LearningJsonPointerSchema,
+    attemptId: LearningJsonPointerSchema,
+    occurredAt: LearningJsonPointerSchema,
+    input: LearningJsonPointerSchema,
+    observedOutput: LearningJsonPointerSchema.nullable(),
+    expected: LearningJsonPointerSchema.nullable(),
+    evaluatorContext: LearningJsonPointerSchema.nullable(),
+    familyKey: LearningJsonPointerSchema,
+    split: TaskSplitSchema,
+}).strict();
+export const LearningSourceContentSchema = z.object({
+    schemaVersion: z.literal("openpond.learningSource.v1"),
+    id: ReleaseIdSchema,
+    revision: z.number().int().positive(),
+    name: z.string().trim().min(1).max(500),
+    kind: z.enum(["direct", "benchmark", "work", "opentelemetry", "provider"]),
+    taskDefinition: LearningRevisionRefSchema,
+    enabled: z.boolean(),
+    allowedSplits: z.array(TaskSplitSchema).min(1).max(4),
+    mapping: TaskSourceMappingSchema.nullable(),
+    adapterVersion: z.string().trim().min(1).max(200).nullable(),
+}).strict().superRefine((source, context) => {
+    if (source.kind !== "direct" && !source.mapping)
+        context.addIssue({ code: "custom", path: ["mapping"], message: "Mapped sources require an explicit mapping." });
+    if (source.mapping && !source.allowedSplits.includes(source.mapping.split))
+        context.addIssue({ code: "custom", path: ["allowedSplits"], message: "The mapping split must be allowed by this source." });
+    if (["opentelemetry", "provider"].includes(source.kind) && !source.adapterVersion)
+        context.addIssue({ code: "custom", path: ["adapterVersion"], message: "Trace adapters require a pinned version." });
+});
+export const LearningSourceSchema = LearningSourceContentSchema.safeExtend({ contentHash: ReleaseHashSchema }).strict();
+export const TaskExampleSubmissionSchema = z.object({
+    schemaVersion: z.literal("openpond.taskExample.v1"),
+    sourceId: ReleaseIdSchema,
+    idempotencyKey: ReleaseIdSchema,
+    taskDefinition: LearningRevisionRefSchema,
+    exampleId: ReleaseIdSchema,
+    attemptId: ReleaseIdSchema,
+    occurredAt: ReleaseTimestampSchema,
+    familyKey: ReleaseIdSchema.nullable(),
+    split: TaskSplitSchema,
+    input: LearningJsonObjectSchema,
+    observedOutput: LearningJsonObjectSchema.nullable(),
+    expected: LearningJsonObjectSchema.nullable(),
+    evaluatorContext: LearningJsonObjectSchema.nullable(),
+    assets: z.array(ImmutableAssetRefSchema).max(1_000),
+    provenance: z.object({ sourceRecordRef: z.string().max(2_000).nullable(), mappingHash: ReleaseHashSchema.nullable() }).strict(),
+}).strict();
+export const TaskEvidenceContentSchema = z.object({
+    schemaVersion: z.literal("openpond.taskEvidence.v1"),
+    id: ReleaseIdSchema,
+    revision: z.number().int().positive(),
+    source: LearningRevisionRefSchema,
+    submission: TaskExampleSubmissionSchema,
+    supersedes: LearningRevisionRefSchema.nullable(),
+    correctionFeedbackId: ReleaseIdSchema.nullable(),
+    receivedAt: ReleaseTimestampSchema,
+}).strict();
+export const TaskEvidenceSchema = TaskEvidenceContentSchema.extend({ contentHash: ReleaseHashSchema }).strict();
+export const TaskFeedbackSubmissionSchema = z.object({
+    schemaVersion: z.literal("openpond.taskFeedback.v1"),
+    sourceId: ReleaseIdSchema,
+    idempotencyKey: ReleaseIdSchema,
+    exampleId: ReleaseIdSchema,
+    attemptId: ReleaseIdSchema,
+    expectedEvidenceHash: ReleaseHashSchema.nullable(),
+    occurredAt: ReleaseTimestampSchema,
+    kind: z.enum(["outcome", "target_correction", "ground_truth_correction", "input_correction", "family_resolution"]),
+    value: LearningJsonObjectSchema,
+    note: z.string().max(20_000),
+}).strict();
+export const TaskFeedbackSchema = z.object({
+    schemaVersion: z.literal("openpond.taskFeedbackRecord.v1"),
+    id: ReleaseIdSchema,
+    submission: TaskFeedbackSubmissionSchema,
+    status: z.enum(["pending_example", "pending_review", "applied", "superseded", "rejected"]),
+    evidence: LearningRevisionRefSchema.nullable(),
+    createdAt: ReleaseTimestampSchema,
+    revision: z.number().int().positive(),
+    review: z.object({ actorId: ReleaseIdSchema, decision: LearningRevisionRefSchema.nullable(), note: z.string().max(20_000), resolvedAt: ReleaseTimestampSchema }).strict().nullable().default(null),
+}).strict();
+export const TaskAdmissionDecisionContentSchema = z.object({
+    schemaVersion: z.literal("openpond.taskAdmissionDecision.v1"),
+    id: ReleaseIdSchema,
+    revision: z.number().int().positive(),
+    evidence: LearningRevisionRefSchema,
+    supersedes: LearningRevisionRefSchema.nullable(),
+    actor: z.object({ kind: z.enum(["human", "qualified_policy"]), id: ReleaseIdSchema, policy: LearningRevisionRefSchema.nullable() }).strict(),
+    evidenceValidity: z.enum(["valid", "invalid", "pending"]),
+    taskAdmissibility: z.enum(["approved", "rejected", "pending"]),
+    observedQuality: z.enum(["passed", "failed", "unscored", "unavailable"]),
+    targetApproval: z.enum(["approved", "rejected", "pending", "not_required"]),
+    approvedTarget: LearningJsonObjectSchema.nullable(),
+    grade: RewardCompositionSchema.nullable(),
+    targetGrade: RewardCompositionSchema.nullable(),
+    note: z.string().max(20_000),
+    decidedAt: ReleaseTimestampSchema,
+}).strict().superRefine((decision, context) => {
+    if (decision.targetApproval === "approved" && decision.approvedTarget === null)
+        context.addIssue({ code: "custom", path: ["approvedTarget"], message: "Target approval requires an actual target." });
+    if (decision.targetApproval !== "approved" && decision.approvedTarget !== null)
+        context.addIssue({ code: "custom", path: ["approvedTarget"], message: "Only approved targets may be selected for supervised learning." });
+    if (decision.actor.kind === "qualified_policy" && !decision.actor.policy)
+        context.addIssue({ code: "custom", path: ["actor"], message: "Automatic admission must pin its qualified policy." });
+    if (decision.taskAdmissibility === "approved" && decision.evidenceValidity !== "valid")
+        context.addIssue({ code: "custom", path: ["taskAdmissibility"], message: "Only valid evidence can produce an approved task." });
+});
+export const TaskAdmissionDecisionSchema = TaskAdmissionDecisionContentSchema.safeExtend({ contentHash: ReleaseHashSchema }).strict();
+export const TaskBatchContentSchema = z.object({
+    schemaVersion: z.literal("openpond.taskBatch.v1"),
+    id: ReleaseIdSchema,
+    revision: z.literal(1),
+    taskDefinition: LearningRevisionRefSchema,
+    rewardBinding: LearningRevisionRefSchema,
+    purpose: z.enum(["supervised_training", "reward_training", "evaluation"]),
+    examples: z.array(z.object({ evidence: LearningRevisionRefSchema, decision: LearningRevisionRefSchema, familyKey: ReleaseIdSchema, inputHash: ReleaseHashSchema, split: TaskSplitSchema }).strict()).min(1).max(10_000),
+    sealedAt: ReleaseTimestampSchema,
+    sealedBy: ReleaseIdSchema,
+}).strict().superRefine((batch, context) => {
+    if (new Set(batch.examples.map((entry) => entry.evidence.id)).size !== batch.examples.length)
+        context.addIssue({ code: "custom", path: ["examples"], message: "Each evidence identity can occur only once in a batch." });
+    const splits = new Map();
+    for (const [index, entry] of batch.examples.entries()) {
+        if ((batch.purpose === "evaluation") === (entry.split === "train"))
+            context.addIssue({ code: "custom", path: ["examples", index, "split"], message: "Training uses train examples; evaluation uses held-out examples." });
+        for (const key of [`family:${entry.familyKey}`, `input:${entry.inputHash}`]) {
+            if (splits.has(key) && splits.get(key) !== entry.split)
+                context.addIssue({ code: "custom", path: ["examples", index], message: "A task family or identical input cannot cross splits." });
+            splits.set(key, entry.split);
+        }
+    }
+});
+export const TaskBatchSchema = TaskBatchContentSchema.safeExtend({ contentHash: ReleaseHashSchema }).strict();
+export const LearningPolicyContentSchema = z.object({
+    schemaVersion: z.literal("openpond.learningPolicy.v1"),
+    id: ReleaseIdSchema,
+    revision: z.number().int().positive(),
+    modelProjectId: ReleaseIdSchema,
+    executionOwner: z.enum(["local", "hosted"]),
+    enabled: z.boolean(),
+    sources: z.array(LearningRevisionRefSchema).min(1).max(100),
+    taskDefinition: LearningRevisionRefSchema,
+    rewardBinding: LearningRevisionRefSchema,
+    admission: z.object({ mode: z.enum(["human", "qualified_automatic"]), qualification: ImmutableReleaseRefSchema.nullable(), minimumApprovedExamples: z.number().int().positive().max(100_000) }).strict(),
+    trigger: z.discriminatedUnion("kind", [
+        z.object({ kind: z.literal("manual") }).strict(),
+        z.object({ kind: z.literal("approved_count") }).strict(),
+        z.object({ kind: z.literal("schedule"), intervalSeconds: z.number().int().min(60).max(31_536_000) }).strict(),
+        z.object({ kind: z.literal("upstream_accepted"), modelProjectId: ReleaseIdSchema }).strict(),
+    ]),
+    trainingParent: ImmutableReleaseRefSchema,
+    teacher: ImmutableReleaseRefSchema.nullable(),
+    training: z.object({ method: z.enum(["sft", "dpo", "grpo", "ppo", "sdft", "opd", "opsd", "sdpo"]), recipe: ImmutableReleaseRefSchema, retentionEvaluation: ImmutableReleaseRefSchema, replayBatches: z.array(ImmutableReleaseRefSchema).max(100) }).strict(),
+    limits: z.object({ maxIterationSpendUsd: z.number().positive().max(100_000), maxDailySpendUsd: z.number().positive().max(1_000_000), cooldownSeconds: z.number().int().nonnegative().max(31_536_000), maxRetries: z.number().int().nonnegative().max(10), maxBatchExamples: z.number().int().positive().max(10_000), maxBacklogExamples: z.number().int().positive().max(1_000_000) }).strict(),
+    automation: z.object({ collect: z.boolean(), train: z.boolean(), accept: z.boolean(), serve: z.boolean() }).strict(),
+    acceptance: z.object({ minimumScore: z.number().min(0).max(1), maximumRetentionRegression: z.number().min(0).max(1), requireImprovement: z.boolean(), rollbackVersion: ImmutableReleaseRefSchema.nullable() }).strict(),
+}).strict().superRefine((policy, context) => {
+    if (policy.admission.mode === "qualified_automatic" && !policy.admission.qualification)
+        context.addIssue({ code: "custom", path: ["admission"], message: "Automatic admission requires qualification evidence." });
+    if (policy.automation.serve && !policy.automation.accept)
+        context.addIssue({ code: "custom", path: ["automation"], message: "Automatic serving requires configured acceptance." });
+    if (policy.automation.accept && !policy.acceptance.rollbackVersion)
+        context.addIssue({ code: "custom", path: ["acceptance"], message: "Automatic acceptance requires a rollback version." });
+    if (policy.trigger.kind === "upstream_accepted" && policy.trigger.modelProjectId === policy.modelProjectId)
+        context.addIssue({ code: "custom", path: ["trigger"], message: "A model cannot trigger itself through upstream acceptance." });
+    if (policy.limits.maxBatchExamples < policy.admission.minimumApprovedExamples)
+        context.addIssue({ code: "custom", path: ["limits"], message: "The batch limit must permit the minimum approved example count." });
+    if (policy.limits.maxDailySpendUsd < policy.limits.maxIterationSpendUsd)
+        context.addIssue({ code: "custom", path: ["limits"], message: "Daily spend must permit the iteration budget." });
+});
+export const LearningPolicySchema = LearningPolicyContentSchema.safeExtend({ contentHash: ReleaseHashSchema }).strict();
+export const LearningIterationStatusSchema = z.enum(["waiting_for_data", "waiting_for_review", "ready", "training", "evaluating", "candidate_ready", "accepted", "rejected", "paused", "failed", "cancelling", "cancelled"]);
+export const LearningIterationSchema = z.object({
+    schemaVersion: z.literal("openpond.learningIteration.v1"),
+    id: ReleaseIdSchema,
+    revision: z.number().int().positive(),
+    policy: LearningRevisionRefSchema,
+    status: LearningIterationStatusSchema,
+    triggerIdentity: ReleaseIdSchema,
+    batch: LearningRevisionRefSchema.nullable(),
+    sourceWatermarks: z.record(ReleaseIdSchema, z.number().int().nonnegative()),
+    trainingParent: ImmutableReleaseRefSchema,
+    teacher: ImmutableReleaseRefSchema.nullable(),
+    upstreamEvent: ImmutableReleaseRefSchema.nullable(),
+    trainingJob: ImmutableReleaseRefSchema.nullable(),
+    evaluationJob: ImmutableReleaseRefSchema.nullable(),
+    candidateVersion: ImmutableReleaseRefSchema.nullable(),
+    dispatchId: ReleaseIdSchema,
+    retryCount: z.number().int().nonnegative(),
+    spendUsd: z.number().nonnegative(),
+    failure: z.object({ code: ReleaseIdSchema, message: z.string().max(20_000) }).strict().nullable(),
+    createdAt: ReleaseTimestampSchema,
+    updatedAt: ReleaseTimestampSchema,
+}).strict();
+export const TaskGradeRunSchema = z.object({
+    schemaVersion: z.literal("openpond.taskGradeRun.v1"),
+    id: ReleaseIdSchema,
+    revision: z.number().int().positive(),
+    evidence: LearningRevisionRefSchema,
+    binding: LearningRevisionRefSchema,
+    target: z.enum(["observed", "proposed_target"]),
+    output: LearningJsonObjectSchema,
+    status: z.enum(["queued", "running", "completed", "failed", "cancelling", "cancelled"]),
+    composition: RewardCompositionSchema.nullable(),
+    leaseOwner: ReleaseIdSchema.nullable(),
+    leaseExpiresAt: ReleaseTimestampSchema.nullable(),
+    attemptCount: z.number().int().nonnegative(),
+    timeoutMs: z.number().int().min(100).max(300_000),
+    maximumSpendUsd: z.number().nonnegative().max(1_000),
+    failure: z.string().max(20_000).nullable(),
+    createdAt: ReleaseTimestampSchema,
+    updatedAt: ReleaseTimestampSchema,
+}).strict();
+export const LearningResourceSchema = z.union([TaskDefinitionSchema, RewardReleaseSchema, RewardBindingSchema, LearningSourceSchema, TaskEvidenceSchema, TaskFeedbackSchema, TaskAdmissionDecisionSchema, TaskBatchSchema, LearningPolicySchema, LearningIterationSchema, TaskGradeRunSchema]);
+export function learningRef(resource) {
+    return LearningRevisionRefSchema.parse({ id: resource.id, revision: resource.revision, contentHash: resource.contentHash });
+}
+export function sameLearningRef(left, right) {
+    return left.id === right.id && left.revision === right.revision && left.contentHash === right.contentHash;
+}
+export function sealLearningContent(content) {
+    assertBoundedTaskJson(content, 16_777_216);
+    return { ...content, contentHash: contentHash(content) };
+}
+export function assertLearningContentHash(resource) {
+    const { contentHash: hash, ...content } = resource;
+    assertBoundedTaskJson(content, 16_777_216);
+    if (contentHash(content) !== hash)
+        throw new LearningDomainError("learning_content_hash_mismatch", 422);
+}

package/dist/learning/errors.js

@@ -0,0 +1,12 @@
+/** Stable domain failures that hosts may expose without treating rejected work
+ * as an infrastructure failure. Unexpected exceptions remain server errors. */
+export class LearningDomainError extends Error {
+    code;
+    status;
+    constructor(code, status = 422, description) {
+        super(description ? `${code}: ${description}` : code);
+        this.code = code;
+        this.status = status;
+        this.name = "LearningDomainError";
+    }
+}

package/dist/learning/grade-worker.js

@@ -0,0 +1,99 @@
+import { executeRewardBinding } from "../rewards.js";
+import { assertGradeIdentity, taskAttemptEvidence, taskRecordFromEvidence } from "./admission.js";
+import { TaskGradeRunSchema } from "./contracts.js";
+import { requireLearningRelease, requireLearningResource } from "./repository.js";
+export function createBuiltinTaskGradeExecutor() {
+    return {
+        execute(input) {
+            return executeRewardBinding({ binding: input.binding, rewards: input.rewards, task: taskRecordFromEvidence(input.evidence, input.definition), evidence: taskAttemptEvidence(input.evidence, input.run.output), signal: input.signal });
+        },
+        // This executor allocates no remote compute and runs only bounded portable checks.
+        async cancel() { return true; },
+    };
+}
+export function createTaskGradeWorker(repository, executor, options) {
+    const now = options.now ?? (() => new Date().toISOString());
+    const active = new Map();
+    const key = (scope, id) => JSON.stringify([scope, id]);
+    async function run(scope, gradeId) {
+        const claim = await repository.transaction(scope, async (transaction) => {
+            const current = await requireLearningResource(transaction, "grade", gradeId);
+            if (["completed", "failed", "cancelled"].includes(current.status))
+                return { acquired: false, run: current };
+            if (current.leaseExpiresAt !== null && Date.parse(current.leaseExpiresAt) > Date.parse(now()))
+                return { acquired: false, run: current };
+            const run = TaskGradeRunSchema.parse({
+                ...current, revision: current.revision + 1, status: current.status === "cancelling" ? "cancelling" : "running",
+                leaseOwner: options.workerId, leaseExpiresAt: new Date(Date.parse(now()) + current.timeoutMs + 30_000).toISOString(),
+                attemptCount: current.attemptCount + 1, updatedAt: now(),
+            });
+            await transaction.put("grade", run, current.revision, { parentId: current.evidence.id, status: run.status });
+            return { acquired: true, run };
+        });
+        if (!claim.acquired)
+            return claim.run;
+        if (claim.run.status === "cancelling") {
+            const terminal = await executor.cancel({ scope, run: claim.run });
+            return finish(scope, claim.run, terminal ? { status: "cancelled", composition: null, failure: null } : { status: "cancelling", composition: null, failure: null });
+        }
+        const controller = new AbortController();
+        active.set(key(scope, gradeId), controller);
+        const timer = setTimeout(() => controller.abort(new Error("task_grade_timeout")), claim.run.timeoutMs);
+        try {
+            const resolved = await repository.transaction(scope, async (transaction) => {
+                const evidence = await requireLearningRelease(transaction, "evidence", claim.run.evidence);
+                const definition = await requireLearningRelease(transaction, "definition", evidence.submission.taskDefinition);
+                const binding = await requireLearningRelease(transaction, "binding", claim.run.binding);
+                const rewards = await Promise.all(binding.sources.map((source) => requireLearningRelease(transaction, "reward", source.reward)));
+                return { evidence, definition, binding, rewards };
+            });
+            controller.signal.throwIfAborted();
+            const composition = await executor.execute({ scope, run: claim.run, ...resolved, signal: controller.signal });
+            controller.signal.throwIfAborted();
+            assertGradeIdentity(composition, resolved.evidence, resolved.definition, claim.run.output);
+            return await finish(scope, claim.run, { status: "completed", composition, failure: null });
+        }
+        catch (error) {
+            if (controller.signal.aborted) {
+                const terminal = await executor.cancel({ scope, run: claim.run });
+                if (!terminal)
+                    return finish(scope, claim.run, { status: "cancelling", composition: null, failure: "Execution cancellation is awaiting owner confirmation." });
+                if (controller.signal.reason instanceof Error && controller.signal.reason.message === "task_grade_cancel_requested")
+                    return finish(scope, claim.run, { status: "cancelled", composition: null, failure: null });
+            }
+            return await finish(scope, claim.run, { status: "failed", composition: null, failure: error instanceof Error ? error.message : "Task grading failed." });
+        }
+        finally {
+            clearTimeout(timer);
+            active.delete(key(scope, gradeId));
+        }
+    }
+    async function finish(scope, claimed, outcome) {
+        return repository.transaction(scope, async (transaction) => {
+            const current = await requireLearningResource(transaction, "grade", claimed.id);
+            if (current.leaseOwner !== options.workerId || current.attemptCount !== claimed.attemptCount || ["completed", "failed", "cancelled"].includes(current.status))
+                return current;
+            // A cancellation request does not override the execution owner's result.
+            const status = outcome.status;
+            const updated = TaskGradeRunSchema.parse({ ...current, ...outcome, status, composition: status === "completed" ? outcome.composition : null, revision: current.revision + 1, leaseOwner: null, leaseExpiresAt: status === "cancelling" ? new Date(Date.parse(now()) + 5_000).toISOString() : null, updatedAt: now() });
+            await transaction.put("grade", updated, current.revision, { parentId: current.evidence.id, status: updated.status });
+            return updated;
+        });
+    }
+    return {
+        run,
+        requestCancellation(scope, gradeId) { active.get(key(scope, gradeId))?.abort(new Error("task_grade_cancel_requested")); },
+        async drain(scope, limit = 20) {
+            const candidates = await repository.transaction(scope, async (transaction) => {
+                const rows = [];
+                for (const status of ["queued", "running", "cancelling"])
+                    rows.push(...(await transaction.list("grade", { status, limit: Math.max(1, Math.min(100, limit)) })).items);
+                return rows;
+            });
+            const completed = [];
+            for (const candidate of candidates)
+                completed.push(await run(scope, candidate.id));
+            return completed;
+        },
+    };
+}

package/dist/learning/index.js

@@ -0,0 +1,9 @@
+export * from "./contracts.js";
+export * from "./assets.js";
+export * from "./admission.js";
+export * from "./operations.js";
+export * from "./repository.js";
+export * from "./service.js";
+export * from "./grade-worker.js";
+export * from "./transport.js";
+export * from "./errors.js";

package/dist/learning/operations.js

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import { ReleaseIdSchema } from "@openpond/harness";
+import { LearningJsonObjectSchema, LearningRevisionRefSchema, LearningSourceContentSchema, TaskDefinitionContentSchema, TaskExampleSubmissionSchema, TaskFeedbackSubmissionSchema, LearningPolicyContentSchema } from "./contracts.js";
+import { RewardBindingContentSchema, RewardReleaseContentSchema } from "../rewards.js";
+import { LearningTextAssetContentSchema } from "./assets.js";
+const command = z.object({ operationId: ReleaseIdSchema });
+const publish = command.extend({ action: z.literal("publish"), expectedRevision: z.number().int().nonnegative() });
+export const PublishLearningResourceCommandSchema = z.discriminatedUnion("kind", [
+    publish.extend({ kind: z.literal("asset"), content: LearningTextAssetContentSchema }).strict(),
+    publish.extend({ kind: z.literal("definition"), content: TaskDefinitionContentSchema }).strict(),
+    publish.extend({ kind: z.literal("reward"), content: RewardReleaseContentSchema }).strict(),
+    publish.extend({ kind: z.literal("binding"), content: RewardBindingContentSchema }).strict(),
+    publish.extend({ kind: z.literal("source"), content: LearningSourceContentSchema }).strict(),
+    publish.extend({ kind: z.literal("policy"), content: LearningPolicyContentSchema }).strict(),
+]);
+export const PublishLearningResourcesCommandSchema = command.extend({
+    action: z.literal("publish_resources"),
+    resources: z.array(z.union(PublishLearningResourceCommandSchema.options.map((schema) => schema.omit({ operationId: true, action: true })))).min(1).max(20),
+}).strict();
+export const SubmitTaskExampleCommandSchema = command.extend({ action: z.literal("submit_example"), example: TaskExampleSubmissionSchema }).strict();
+export const SubmitTaskFeedbackCommandSchema = command.extend({ action: z.literal("submit_feedback"), feedback: TaskFeedbackSubmissionSchema }).strict();
+export const ApplyTaskCorrectionCommandSchema = command.extend({ action: z.literal("apply_correction"), feedbackId: ReleaseIdSchema, evidence: LearningRevisionRefSchema }).strict();
+export const ResolveTaskFeedbackCommandSchema = command.extend({ action: z.literal("resolve_feedback"), feedbackId: ReleaseIdSchema, expectedRevision: z.number().int().positive(), disposition: z.enum(["applied", "rejected", "superseded"]), decision: LearningRevisionRefSchema.nullable(), note: z.string().max(20_000) }).strict();
+export const QueueTaskGradeCommandSchema = command.extend({ action: z.literal("queue_grade"), evidence: LearningRevisionRefSchema, target: z.enum(["observed", "proposed_target"]), proposedTarget: LearningJsonObjectSchema.nullable(), timeoutMs: z.number().int().min(100).max(300_000).default(30_000), maximumSpendUsd: z.number().nonnegative().max(1_000).default(0) }).strict();
+export const ReviewTaskEvidenceCommandSchema = command.extend({
+    action: z.literal("review"), evidence: LearningRevisionRefSchema, expectedRevision: z.number().int().nonnegative(),
+    disposition: z.enum(["approved", "rejected", "pending"]), targetApproval: z.enum(["approved", "rejected", "pending", "not_required"]),
+    approvedTarget: LearningJsonObjectSchema.nullable(), observedGradeId: ReleaseIdSchema.nullable(), targetGradeId: ReleaseIdSchema.nullable(),
+    note: z.string().max(20_000),
+}).strict();
+export const SealTaskBatchCommandSchema = command.extend({ action: z.literal("seal_batch"), batchId: ReleaseIdSchema, taskDefinition: LearningRevisionRefSchema, purpose: z.enum(["supervised_training", "reward_training", "evaluation"]), evidence: z.array(LearningRevisionRefSchema).min(1).max(10_000), decisions: z.array(LearningRevisionRefSchema).min(1).max(10_000) }).strict();
+export const CancelTaskGradeCommandSchema = command.extend({ action: z.literal("cancel_grade"), gradeId: ReleaseIdSchema, expectedRevision: z.number().int().positive() }).strict();
+export const LearningCommandSchema = z.union([PublishLearningResourceCommandSchema, PublishLearningResourcesCommandSchema, SubmitTaskExampleCommandSchema, SubmitTaskFeedbackCommandSchema, ApplyTaskCorrectionCommandSchema, ResolveTaskFeedbackCommandSchema, QueueTaskGradeCommandSchema, ReviewTaskEvidenceCommandSchema, SealTaskBatchCommandSchema, CancelTaskGradeCommandSchema]);

package/dist/learning/repository.js

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import { contentHash } from "@openpond/harness";
+import { assertLearningContentHash, LearningSourceSchema, TaskAdmissionDecisionSchema, TaskBatchSchema, TaskDefinitionSchema, TaskEvidenceSchema, TaskFeedbackSchema, TaskGradeRunSchema, LearningPolicySchema, LearningIterationSchema } from "./contracts.js";
+import { RewardBindingSchema, RewardReleaseSchema } from "../rewards.js";
+import { TasksetReleaseSchema } from "../tasksets.js";
+import { LearningDomainError } from "./errors.js";
+import { LearningTextAssetSchema } from "./assets.js";
+export const learningResourceSchemas = {
+    asset: LearningTextAssetSchema,
+    definition: TaskDefinitionSchema, reward: RewardReleaseSchema, binding: RewardBindingSchema,
+    source: LearningSourceSchema, evidence: TaskEvidenceSchema, feedback: TaskFeedbackSchema,
+    decision: TaskAdmissionDecisionSchema, batch: TaskBatchSchema, policy: LearningPolicySchema,
+    iteration: LearningIterationSchema, grade: TaskGradeRunSchema, package: TasksetReleaseSchema,
+};
+export const LearningResourceKindSchema = z.enum(Object.keys(learningResourceSchemas));
+export class LearningConflictError extends LearningDomainError {
+    kind;
+    id;
+    expectedRevision;
+    currentRevision;
+    constructor(kind, id, expectedRevision, currentRevision) {
+        super("learning_revision_conflict", 409, `Revision conflict for ${kind} ${id}: expected ${expectedRevision}, current ${currentRevision}.`);
+        this.kind = kind;
+        this.id = id;
+        this.expectedRevision = expectedRevision;
+        this.currentRevision = currentRevision;
+        this.name = "LearningConflictError";
+    }
+}
+export async function requireLearningResource(transaction, kind, id, revision) {
+    const resource = await transaction.get(kind, id, revision);
+    if (!resource)
+        throw new LearningDomainError("learning_resource_not_found", 404, `${kind}:${id}`);
+    return learningResourceSchemas[kind].parse(resource);
+}
+export async function requireLearningRelease(transaction, kind, ref) {
+    const resource = await requireLearningResource(transaction, kind, ref.id, ref.revision);
+    if (!("contentHash" in resource) || resource.contentHash !== ref.contentHash)
+        throw new LearningDomainError("learning_release_hash_mismatch", 409, `${kind}:${ref.id}`);
+    assertLearningContentHash(resource);
+    return resource;
+}
+export function learningEvidenceId(sourceId, exampleId, attemptId) {
+    return `evidence-${contentHash([sourceId, exampleId, attemptId])}`;
+}
+export function learningOperationId(actorId, operationId) {
+    return contentHash([actorId, operationId]);
+}