@openpond/evals 0.6.0 → 0.7.0

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]);
+}

package/dist/learning/service.js

@@ -0,0 +1,367 @@
+import { LearningDomainError } from "./errors.js";
+import { contentHash } from "@openpond/harness";
+import { createRewardBinding, createRewardRelease, resolveBoundRewards } from "../rewards.js";
+import { assertBoundedTaskJson, validateTaskValue } from "../task-schema.js";
+import { assertAdmissionDecision, assertGradeIdentity, compileTaskBatch, inspectTaskEvidence, sealTaskBatch, taskFamilyReservations } from "./admission.js";
+import { learningRef, LearningSourceSchema, LearningPolicySchema, sameLearningRef, sealLearningContent, TaskAdmissionDecisionContentSchema, TaskAdmissionDecisionSchema, TaskDefinitionSchema, TaskEvidenceContentSchema, TaskEvidenceSchema, TaskFeedbackSchema, TaskGradeRunSchema } from "./contracts.js";
+import { LearningCommandSchema } from "./operations.js";
+import { LearningConflictError, learningEvidenceId, learningOperationId, requireLearningRelease, requireLearningResource } from "./repository.js";
+import { validateSourceSubmission } from "./admission.js";
+import { LearningTextAssetSchema, verifyLearningTextAsset } from "./assets.js";
+export function createLearningService(repository, options = {}) {
+    const now = options.now ?? (() => new Date().toISOString());
+    async function command(context, raw) {
+        assertBoundedTaskJson(raw, 16_777_216);
+        const input = LearningCommandSchema.parse(raw);
+        authorize(context, input);
+        const producer = input.action === "submit_example" ? input.example : input.action === "submit_feedback" ? input.feedback : null;
+        const operationId = producer ? contentHash([input.action, producer.sourceId, producer.idempotencyKey]) : learningOperationId(context.actor.id, input.operationId);
+        const requestHash = contentHash(producer ? { action: input.action, value: producer } : input);
+        return repository.transaction(context.scope, async (transaction) => {
+            const previous = await transaction.operation(operationId);
+            if (previous) {
+                if (previous.requestHash !== requestHash)
+                    throw new LearningDomainError("learning_idempotency_conflict", 409);
+                return { operationId: input.operationId, resources: await Promise.all(previous.resources.map((pointer) => requireLearningResource(transaction, pointer.kind, pointer.id, pointer.revision))) };
+            }
+            let pointers;
+            switch (input.action) {
+                case "publish":
+                    pointers = [await publish(transaction, input)];
+                    break;
+                case "publish_resources": {
+                    pointers = [];
+                    for (const resource of input.resources)
+                        pointers.push(await publish(transaction, { ...resource, action: "publish", operationId: input.operationId }));
+                    break;
+                }
+                case "submit_example":
+                    pointers = [await submit(transaction, input)];
+                    break;
+                case "submit_feedback":
+                    pointers = [await feedback(transaction, input)];
+                    break;
+                case "apply_correction":
+                    pointers = await correct(transaction, input, context.actor.id);
+                    break;
+                case "resolve_feedback":
+                    pointers = [await resolveFeedback(transaction, input, context.actor.id)];
+                    break;
+                case "queue_grade":
+                    pointers = [await queueGrade(transaction, input, operationId)];
+                    break;
+                case "cancel_grade":
+                    pointers = [await cancelGrade(transaction, input)];
+                    break;
+                case "review":
+                    pointers = [await review(transaction, input, context.actor.id)];
+                    break;
+                case "seal_batch":
+                    pointers = await seal(transaction, input, context.actor.id);
+                    break;
+            }
+            await transaction.saveOperation(operationId, { requestHash, resources: pointers });
+            return { operationId: input.operationId, resources: await Promise.all(pointers.map((pointer) => requireLearningResource(transaction, pointer.kind, pointer.id, pointer.revision))) };
+        });
+    }
+    async function publish(transaction, input) {
+        if (input.content.revision !== input.expectedRevision + 1)
+            throw new LearningDomainError("learning_publication_revision_invalid", 422);
+        let resource;
+        switch (input.kind) {
+            case "asset": {
+                resource = LearningTextAssetSchema.parse(sealLearningContent(input.content));
+                const existing = await transaction.get("asset", resource.id, 1);
+                if (existing?.contentHash === resource.contentHash)
+                    return pointer("asset", existing);
+                break;
+            }
+            case "reward": {
+                resource = createRewardRelease(input.content);
+                const implementation = input.content.implementation;
+                const references = [
+                    ...input.content.assets,
+                    ...("verifierRef" in implementation ? [implementation.verifierRef] : []),
+                    ...("rubricRef" in implementation ? [implementation.rubricRef] : []),
+                    ...("inputContract" in implementation ? [implementation.inputContract] : []),
+                ];
+                for (const reference of references) {
+                    const asset = await requireLearningResource(transaction, "asset", reference.id, 1);
+                    verifyLearningTextAsset(asset, reference);
+                    if (reference.visibility === "policy")
+                        throw new LearningDomainError("reward_asset_visibility_invalid", 422, "Reward source and rubrics must be private to the evaluator.");
+                }
+                break;
+            }
+            case "binding": {
+                if (input.content.recipeRef)
+                    await requireLearningRelease(transaction, "binding", input.content.recipeRef);
+                const rewards = await Promise.all(input.content.sources.map((source) => requireLearningRelease(transaction, "reward", source.reward)));
+                resource = createRewardBinding(input.content, rewards);
+                break;
+            }
+            case "definition": {
+                await requireLearningRelease(transaction, "binding", input.content.rewardBinding);
+                resource = TaskDefinitionSchema.parse(sealLearningContent(input.content));
+                break;
+            }
+            case "source": {
+                await requireLearningRelease(transaction, "definition", input.content.taskDefinition);
+                resource = LearningSourceSchema.parse(sealLearningContent(input.content));
+                break;
+            }
+            case "policy": {
+                const definition = await requireLearningRelease(transaction, "definition", input.content.taskDefinition);
+                if (!sameLearningRef(definition.rewardBinding, input.content.rewardBinding))
+                    throw new LearningDomainError("learning_policy_binding_mismatch", 422);
+                for (const source of input.content.sources) {
+                    const resource = await requireLearningRelease(transaction, "source", source);
+                    if (!sameLearningRef(resource.taskDefinition, input.content.taskDefinition))
+                        throw new LearningDomainError("learning_policy_source_definition_mismatch", 422);
+                }
+                resource = LearningPolicySchema.parse(sealLearningContent(input.content));
+                break;
+            }
+        }
+        await transaction.put(input.kind, resource, input.expectedRevision);
+        return pointer(input.kind, resource);
+    }
+    async function submit(transaction, input) {
+        const source = await requireLearningResource(transaction, "source", input.example.sourceId);
+        const submission = validateSourceSubmission(source, input.example);
+        await requireLearningRelease(transaction, "definition", submission.taskDefinition);
+        const id = learningEvidenceId(submission.sourceId, submission.exampleId, submission.attemptId);
+        const existing = await transaction.get("evidence", id, 1);
+        if (existing) {
+            const { idempotencyKey: _oldKey, ...oldPayload } = existing.submission;
+            const { idempotencyKey: _newKey, ...newPayload } = submission;
+            if (contentHash(oldPayload) !== contentHash(newPayload))
+                throw new LearningDomainError("task_evidence_identity_conflict", 409);
+            return pointer("evidence", existing);
+        }
+        const evidence = TaskEvidenceSchema.parse(sealLearningContent(TaskEvidenceContentSchema.parse({
+            schemaVersion: "openpond.taskEvidence.v1", id, revision: 1, source: learningRef(source), submission,
+            supersedes: null, correctionFeedbackId: null, receivedAt: now(),
+        })));
+        await transaction.put("evidence", evidence, 0, { parentId: source.id });
+        let afterId;
+        do {
+            const page = await transaction.list("feedback", { parentId: evidence.id, status: "pending_example", limit: 100, ...(afterId ? { afterId } : {}) });
+            for (const feedback of page.items) {
+                const updated = TaskFeedbackSchema.parse({ ...feedback, revision: feedback.revision + 1, status: "pending_review", evidence: learningRef(evidence) });
+                await transaction.put("feedback", updated, feedback.revision, { parentId: evidence.id, status: updated.status });
+            }
+            afterId = page.nextCursor ?? undefined;
+        } while (afterId);
+        return pointer("evidence", evidence);
+    }
+    async function feedback(transaction, input) {
+        const source = await requireLearningResource(transaction, "source", input.feedback.sourceId);
+        if (!source.enabled)
+            throw new LearningDomainError("learning_source_disabled", 409);
+        const evidenceId = learningEvidenceId(source.id, input.feedback.exampleId, input.feedback.attemptId);
+        const evidence = await transaction.get("evidence", evidenceId);
+        const record = TaskFeedbackSchema.parse({
+            schemaVersion: "openpond.taskFeedbackRecord.v1", id: `feedback-${contentHash([source.id, input.feedback.idempotencyKey])}`,
+            submission: input.feedback, status: evidence ? "pending_review" : "pending_example",
+            evidence: evidence ? learningRef(evidence) : null, createdAt: now(), revision: 1,
+        });
+        await transaction.put("feedback", record, 0, { parentId: evidenceId, status: record.status });
+        return pointer("feedback", record);
+    }
+    async function correct(transaction, input, actorId) {
+        const feedback = await requireLearningResource(transaction, "feedback", input.feedbackId);
+        if (["applied", "rejected", "superseded"].includes(feedback.status))
+            throw new LearningDomainError("task_feedback_already_resolved", 409);
+        const evidence = await currentEvidence(transaction, input.evidence);
+        const expectedId = learningEvidenceId(feedback.submission.sourceId, feedback.submission.exampleId, feedback.submission.attemptId);
+        if (expectedId !== evidence.id || (feedback.submission.expectedEvidenceHash !== null && feedback.submission.expectedEvidenceHash !== evidence.contentHash))
+            throw new LearningDomainError("task_feedback_evidence_mismatch", 409);
+        const definition = await requireLearningRelease(transaction, "definition", evidence.submission.taskDefinition);
+        const submission = { ...evidence.submission };
+        const { kind, value } = feedback.submission;
+        if (kind === "ground_truth_correction") {
+            if (!validateTaskValue(definition.outputSchema, value).valid)
+                throw new LearningDomainError("task_corrected_expected_schema_invalid", 422);
+            submission.expected = value;
+        }
+        else if (kind === "input_correction") {
+            if (!validateTaskValue(definition.inputSchema, value).valid)
+                throw new LearningDomainError("task_corrected_input_schema_invalid", 422);
+            submission.input = value;
+        }
+        else if (kind === "family_resolution") {
+            if (typeof value.familyKey !== "string" || !value.familyKey.trim())
+                throw new LearningDomainError("task_family_resolution_invalid", 422);
+            submission.familyKey = value.familyKey;
+        }
+        else
+            throw new LearningDomainError("task_feedback_requires_target_review", 422);
+        const { contentHash: _priorHash, ...priorContent } = evidence;
+        const revised = TaskEvidenceSchema.parse(sealLearningContent(TaskEvidenceContentSchema.parse({
+            ...priorContent, revision: evidence.revision + 1, submission, supersedes: learningRef(evidence), correctionFeedbackId: feedback.id, receivedAt: now(),
+        })));
+        const resolved = TaskFeedbackSchema.parse({ ...feedback, revision: feedback.revision + 1, status: "applied", evidence: learningRef(revised), review: { actorId, decision: null, note: "Applied as a corrected evidence revision.", resolvedAt: now() } });
+        await transaction.put("evidence", revised, evidence.revision, { parentId: submission.sourceId });
+        await transaction.put("feedback", resolved, feedback.revision, { parentId: evidence.id, status: resolved.status });
+        return [pointer("evidence", revised), pointer("feedback", resolved)];
+    }
+    async function resolveFeedback(transaction, input, actorId) {
+        const feedback = await requireLearningResource(transaction, "feedback", input.feedbackId);
+        if (feedback.revision !== input.expectedRevision)
+            throw new LearningConflictError("feedback", feedback.id, input.expectedRevision, feedback.revision);
+        if (["applied", "rejected", "superseded"].includes(feedback.status))
+            throw new LearningDomainError("task_feedback_already_resolved", 409);
+        if (input.disposition === "applied" && !input.decision)
+            throw new LearningDomainError("task_feedback_decision_required");
+        if (input.decision) {
+            const decision = await requireLearningRelease(transaction, "decision", input.decision);
+            const current = await requireLearningResource(transaction, "decision", decision.id);
+            if (!sameLearningRef(learningRef(current), input.decision))
+                throw new LearningDomainError("task_admission_revision_stale", 409);
+            const evidence = await currentEvidence(transaction, decision.evidence);
+            if (learningEvidenceId(feedback.submission.sourceId, feedback.submission.exampleId, feedback.submission.attemptId) !== evidence.id || (feedback.submission.expectedEvidenceHash !== null && feedback.submission.expectedEvidenceHash !== evidence.contentHash))
+                throw new LearningDomainError("task_feedback_evidence_mismatch", 409);
+            if (input.disposition === "applied") {
+                if (decision.taskAdmissibility === "pending")
+                    throw new LearningDomainError("task_feedback_decision_pending");
+                if (feedback.submission.kind === "target_correction") {
+                    if (decision.targetApproval !== "approved" || contentHash(decision.approvedTarget) !== contentHash(feedback.submission.value))
+                        throw new LearningDomainError("task_feedback_target_not_approved");
+                }
+                else if (feedback.submission.kind !== "outcome")
+                    throw new LearningDomainError("task_feedback_requires_evidence_correction");
+            }
+        }
+        const resolved = TaskFeedbackSchema.parse({ ...feedback, revision: feedback.revision + 1, status: input.disposition, review: { actorId, decision: input.decision, note: input.note, resolvedAt: now() } });
+        await transaction.put("feedback", resolved, feedback.revision, { parentId: learningEvidenceId(feedback.submission.sourceId, feedback.submission.exampleId, feedback.submission.attemptId), status: resolved.status });
+        return pointer("feedback", resolved);
+    }
+    async function queueGrade(transaction, input, operationId) {
+        const evidence = await currentEvidence(transaction, input.evidence);
+        const definition = await requireLearningRelease(transaction, "definition", evidence.submission.taskDefinition);
+        if (!inspectTaskEvidence(evidence, definition).taskReady)
+            throw new LearningDomainError("task_evidence_not_ready", 422);
+        const output = input.target === "observed" ? evidence.submission.observedOutput : input.proposedTarget;
+        if (output === null)
+            throw new LearningDomainError("task_grade_output_required", 422);
+        if (input.target === "observed" && input.proposedTarget !== null)
+            throw new LearningDomainError("observed_grade_cannot_replace_output", 422);
+        const grade = TaskGradeRunSchema.parse({
+            schemaVersion: "openpond.taskGradeRun.v1", id: `grade-${operationId}`, revision: 1,
+            evidence: learningRef(evidence), binding: definition.rewardBinding, target: input.target, output,
+            status: "queued", composition: null, leaseOwner: null, leaseExpiresAt: null, attemptCount: 0,
+            timeoutMs: input.timeoutMs, maximumSpendUsd: input.maximumSpendUsd, failure: null, createdAt: now(), updatedAt: now(),
+        });
+        await transaction.put("grade", grade, 0, { parentId: evidence.id, status: grade.status });
+        return pointer("grade", grade);
+    }
+    async function cancelGrade(transaction, input) {
+        const grade = await requireLearningResource(transaction, "grade", input.gradeId);
+        if (grade.revision !== input.expectedRevision)
+            throw new LearningConflictError("grade", grade.id, input.expectedRevision, grade.revision);
+        if (["completed", "failed", "cancelled"].includes(grade.status))
+            return pointer("grade", grade);
+        const updated = TaskGradeRunSchema.parse({ ...grade, revision: grade.revision + 1, status: grade.status === "queued" ? "cancelled" : "cancelling", updatedAt: now() });
+        await transaction.put("grade", updated, grade.revision, { parentId: grade.evidence.id, status: updated.status });
+        return pointer("grade", updated);
+    }
+    async function review(transaction, input, actorId) {
+        const evidence = await currentEvidence(transaction, input.evidence);
+        const definition = await requireLearningRelease(transaction, "definition", evidence.submission.taskDefinition);
+        const inspection = inspectTaskEvidence(evidence, definition);
+        const id = `decision-${evidence.id}`;
+        const previous = await transaction.get("decision", id);
+        const observedGrade = await gradeResult(transaction, input.observedGradeId, evidence, "observed");
+        const targetGrade = await gradeResult(transaction, input.targetGradeId, evidence, "proposed_target");
+        const measured = observedGrade?.training.status === "scored" ? observedGrade.training : observedGrade?.evaluation;
+        const decision = TaskAdmissionDecisionSchema.parse(sealLearningContent(TaskAdmissionDecisionContentSchema.parse({
+            schemaVersion: "openpond.taskAdmissionDecision.v1", id, revision: input.expectedRevision + 1,
+            evidence: learningRef(evidence), supersedes: previous ? learningRef(previous) : null,
+            actor: { kind: "human", id: actorId, policy: null }, evidenceValidity: inspection.evidenceValidity,
+            taskAdmissibility: input.disposition, observedQuality: measured?.status === "scored" ? measured.passed ? "passed" : "failed" : observedGrade ? "unavailable" : "unscored",
+            targetApproval: input.targetApproval, approvedTarget: input.approvedTarget, grade: observedGrade, targetGrade,
+            note: input.note, decidedAt: now(),
+        })));
+        if (input.disposition === "approved")
+            assertAdmissionDecision({ decision, evidence, definition, purpose: input.targetApproval === "approved" ? "supervised_training" : "reward_training" });
+        await transaction.put("decision", decision, input.expectedRevision, { parentId: evidence.id, status: decision.taskAdmissibility });
+        return pointer("decision", decision);
+    }
+    async function seal(transaction, input, actorId) {
+        const definition = await requireLearningRelease(transaction, "definition", input.taskDefinition);
+        const binding = await requireLearningRelease(transaction, "binding", definition.rewardBinding);
+        const rewards = await Promise.all(binding.sources.map((source) => requireLearningRelease(transaction, "reward", source.reward)));
+        resolveBoundRewards(binding, rewards);
+        const evidence = await Promise.all(input.evidence.map((ref) => currentEvidence(transaction, ref)));
+        const decisions = await Promise.all(input.decisions.map(async (ref) => {
+            const decision = await requireLearningRelease(transaction, "decision", ref);
+            const current = await requireLearningResource(transaction, "decision", ref.id);
+            if (!sameLearningRef(learningRef(current), ref))
+                throw new LearningDomainError("task_admission_revision_stale", 409);
+            return decision;
+        }));
+        const priorSplits = [];
+        for (const item of evidence) {
+            for (const reservation of taskFamilyReservations(item, definition)) {
+                const split = await transaction.familySplit(reservation.namespace, reservation.kind, reservation.key);
+                if (split !== null)
+                    priorSplits.push({ ...reservation, split: split });
+            }
+        }
+        const batch = sealTaskBatch({ id: input.batchId, definition, binding, rewards, purpose: input.purpose, evidence, decisions, priorSplits, actorId, now: now() });
+        const release = compileTaskBatch({ batch, definition, binding, rewards, evidence, decisions });
+        for (const item of evidence) {
+            for (const reservation of taskFamilyReservations(item, definition))
+                await transaction.reserveFamilySplit(reservation.namespace, reservation.kind, reservation.key, reservation.split);
+        }
+        await transaction.put("batch", batch, 0, { parentId: definition.id });
+        await transaction.put("package", release, 0, { parentId: batch.id });
+        return [pointer("batch", batch), pointer("package", release)];
+    }
+    return {
+        command,
+        async get(context, kind, id, revision) {
+            authorizeRead(context);
+            return repository.transaction(context.scope, (transaction) => requireLearningResource(transaction, kind, id, revision));
+        },
+        async list(context, kind, query = {}) {
+            authorizeRead(context);
+            const limit = Math.max(1, Math.min(100, Math.trunc(query.limit ?? 50)));
+            return repository.transaction(context.scope, (transaction) => transaction.list(kind, { ...query, limit }));
+        },
+    };
+}
+async function currentEvidence(transaction, ref) {
+    const evidence = await requireLearningRelease(transaction, "evidence", ref);
+    const current = await requireLearningResource(transaction, "evidence", ref.id);
+    if (!sameLearningRef(learningRef(current), ref))
+        throw new LearningDomainError("task_evidence_revision_stale", 409);
+    return evidence;
+}
+async function gradeResult(transaction, id, evidence, target) {
+    if (id === null)
+        return null;
+    const grade = await requireLearningResource(transaction, "grade", id);
+    if (grade.status !== "completed" || !grade.composition || grade.target !== target || !sameLearningRef(grade.evidence, learningRef(evidence)))
+        throw new LearningDomainError("task_grade_not_applicable", 422);
+    const definition = await requireLearningRelease(transaction, "definition", evidence.submission.taskDefinition);
+    assertGradeIdentity(grade.composition, evidence, definition, grade.output);
+    return grade.composition;
+}
+function pointer(kind, resource) { return { kind, id: resource.id, revision: resource.revision }; }
+function authorizeRead(context) {
+    if (!context.scope.trim() || !context.actor.id.trim() || context.actor.role === "source")
+        throw new LearningDomainError("learning_read_not_authorized", 403);
+}
+function authorize(context, input) {
+    if (!context.scope.trim() || !context.actor.id.trim())
+        throw new LearningDomainError("learning_scope_required", 400);
+    if (context.actor.role === "source") {
+        const sourceId = input.action === "submit_example" ? input.example.sourceId : input.action === "submit_feedback" ? input.feedback.sourceId : null;
+        if (!sourceId || sourceId !== context.actor.sourceId)
+            throw new LearningDomainError("learning_source_not_authorized", 403);
+    }
+    if (["review", "apply_correction", "resolve_feedback", "seal_batch"].includes(input.action) && context.actor.role !== "reviewer")
+        throw new LearningDomainError("learning_review_not_authorized", 403);
+}

package/dist/learning/transport.js

@@ -0,0 +1,25 @@
+import { z } from "zod";
+import { ReleaseIdSchema } from "@openpond/harness";
+import { LearningCommandSchema } from "./operations.js";
+import { LearningResourceKindSchema, learningResourceSchemas } from "./repository.js";
+import { assertBoundedTaskJson } from "../task-schema.js";
+import { LearningDomainError } from "./errors.js";
+/** Run before recursive schema parsing, including for non-TypeScript producers. */
+export function assertLearningRequestJson(raw) {
+    try {
+        assertBoundedTaskJson(raw, 16_777_216);
+    }
+    catch (error) {
+        throw new LearningDomainError("learning_json_invalid", 400, error instanceof Error ? error.message : "Expected bounded JSON.");
+    }
+}
+/** Scope selection is never authorization; each host resolves its authenticated owner. */
+export const LearningCommandRequestSchema = z.object({ scope: ReleaseIdSchema, command: LearningCommandSchema }).strict();
+export const LearningReadRequestSchema = z.discriminatedUnion("action", [
+    z.object({ action: z.literal("get"), scope: ReleaseIdSchema, kind: LearningResourceKindSchema, id: ReleaseIdSchema, revision: z.number().int().positive().optional() }).strict(),
+    z.object({ action: z.literal("list"), scope: ReleaseIdSchema, kind: LearningResourceKindSchema, parentId: ReleaseIdSchema.optional(), status: z.string().min(1).max(200).optional(), afterId: ReleaseIdSchema.optional(), limit: z.number().int().min(1).max(100).default(50) }).strict(),
+]);
+export const LearningOperationResultSchema = z.object({
+    operationId: ReleaseIdSchema,
+    resources: z.array(z.union(Object.values(learningResourceSchemas))).max(100),
+}).strict();