@openpond/evals 0.10.1 → 0.10.2

package/LEARNING.md

@@ -148,3 +148,73 @@ Policy and iteration contracts distinguish training parent, optional teacher and
 upstream trigger. The contracts themselves do not launch training, schedule jobs,
 qualify a model, accept a candidate or promote a serving endpoint. Hosts must
 implement those transitions and record actual execution/evaluation receipts.
+
+`reserve_iteration` is the shared reviewer-authorized reservation operation for
+manual and scheduled triggers. It pins the current enabled policy, checks the
+Model's active chain and cooldown, discovers approved training evidence across
+all source pages, and atomically seals a batch, records consumption, reserves
+spend and creates the iteration. It does not submit a training Job. The current
+approved-batch methods are SFT, GRPO and PPO with human admission; qualified
+automatic admission and automatic acceptance/serving are rejected until their
+execution paths are implemented.
+
+Manual triggers carry a stable `identity`; scheduled triggers carry a concrete
+`scheduledAt`. Equivalent timestamp offsets denote the same fire. A manual
+trigger can use a policy with a saved schedule without editing that policy.
+Retries, including another reviewer or a restarted host, resolve the same fire
+and dispatch identity. New events cannot bypass an active chain by editing the
+policy. Waiting for data/review records a zero-budget result and consumes no
+examples; a later event discovers newly approved evidence.
+
+The `chain`, `consumption` and `reservation` resources are stored through the same
+atomic repository interface. Consumption keys include the Model chain and exact
+evidence revision; decision identity is retained alongside it. Reapproval or a
+policy edit does not make consumed evidence new. Corrections create new evidence
+revisions. Numeric source watermarks remain empty because existing evidence has
+no ordered ingress sequence; hashed resource pagination is never a consumption
+watermark. Outstanding reserved spend carries across midnight and is counted
+alongside spend settled in the current UTC day.
+
+`cancel_iteration_reservation` releases only an undispatched reservation and
+requires its current revision. Consumption history remains intact. Once an
+execution owner claims the iteration, it must persist an executing status before
+making a network submission; local reservation cancellation then refuses to
+release its budget. Submitted-job cancellation and cost settlement belong to the
+execution reconciler and require authoritative provider state.
+
+### Durable iteration dispatch
+
+`createLearningIterationWorker` claims one reserved iteration with a persisted,
+expiring lease and generation fence. It resolves the pinned policy and batch,
+asks a host executor to prepare a compute-free submission, and persists that
+exact protocol payload and hash before any provider submission. The preparation
+state is `dispatching`; only a provider observation establishes `training` or
+`evaluating`. A paused policy stops new submissions while existing executions
+continue to be observed.
+
+The executor must deduplicate `submit` by `dispatch.id`, verify observation
+identity and provider receipts, and use `reconcile` to recover an existing Job
+after a lost reply. An unreachable owner is an error, never proof of absence.
+Submission payloads contain immutable inputs, not credentials or temporary URLs.
+All provider calls occur outside repository transactions and have bounded
+request timeouts. Expired lease owners cannot write results over a newer claim.
+
+`cancel_iteration` persists cancellation intent and preserves a live lease.
+Before submission starts, cancellation can settle at zero spend locally. Once
+submission may have begun, the executor's cancellation must fence late submits
+under the same dispatch identity and return authoritative terminal cleanup,
+including when the original submission reply was lost. Merely aborting an HTTP
+request is insufficient. Reserved spend is retained through uncertainty and
+released only when terminal spend and cleanup are recorded atomically. Executors
+must enforce the configured bounds; settlement records actual spend without
+silently clipping a provider overrun.
+
+Consecutive transport/preparation failures exhaust the policy retry limit into
+a blocked dispatch without releasing its budget or consuming another batch.
+Reviewer-only `retry_iteration_dispatch` resumes that same dispatch; cancellation
+also remains available. A successful execution with an evaluated adapter becomes
+`candidate_ready`, retaining the active chain for explicit candidate review.
+A successful execution without an adapter becomes `completed_without_candidate`;
+it does not fabricate a version or an improvement. Provider adapters, timers,
+candidate-decision reconciliation and product controls must be connected by the
+host; this shared worker alone does not enable hosted scheduling.

package/dist/learning/batch-service.js

@@ -0,0 +1,44 @@
+import { resolveBoundRewards } from "../rewards.js";
+import { compileTaskBatch, sealTaskBatch, taskFamilyReservations } from "./admission.js";
+import { learningRef, sameLearningRef } from "./contracts.js";
+import { LearningDomainError } from "./errors.js";
+import { requireLearningRelease, requireLearningResource } from "./repository.js";
+export async function sealLearningBatch(transaction, input, actorId, timestamp) {
+    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) => requireCurrentLearningEvidence(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: timestamp });
+    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)];
+}
+export async function requireCurrentLearningEvidence(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;
+}
+function pointer(kind, resource) { return { kind, id: resource.id, revision: resource.revision }; }

package/dist/learning/contracts.js

@@ -216,7 +216,7 @@ export const LearningPolicyContentSchema = z.object({
         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 LearningIterationStatusSchema = z.enum(["waiting_for_data", "waiting_for_review", "ready", "dispatching", "training", "evaluating", "candidate_ready", "accepted", "rejected", "paused", "failed", "cancelling", "cancelled", "completed_without_candidate"]);
 export const LearningIterationSchema = z.object({
     schemaVersion: z.literal("openpond.learningIteration.v1"),
     id: ReleaseIdSchema,

package/dist/learning/index.js

@@ -12,3 +12,6 @@ export * from "./reward-authoring.js";
 export * from "./reward-checks.js";
 export * from "./reward-check-worker.js";
 export * from "./reward-fixture-executor.js";
+export * from "./iteration-reservation-contracts.js";
+export * from "./iteration-dispatch-contracts.js";
+export * from "./iteration-dispatch-worker.js";

package/dist/learning/iteration-dispatch-commands.js

@@ -0,0 +1,31 @@
+import { LearningIterationSchema } from "./contracts.js";
+import { LearningDomainError } from "./errors.js";
+import { LearningIterationDispatchSchema } from "./iteration-dispatch-contracts.js";
+import { cancelLearningIterationReservation } from "./iteration-reservation-cancellation.js";
+import { LearningConflictError, requireLearningResource } from "./repository.js";
+export async function commandLearningIterationDispatch(tx, input, now) {
+    const iteration = await requireLearningResource(tx, "iteration", input.iterationId);
+    if (iteration.revision !== input.expectedRevision)
+        throw new LearningConflictError("iteration", iteration.id, input.expectedRevision, iteration.revision);
+    const dispatch = await tx.get("dispatch", iteration.dispatchId);
+    if (input.action === "cancel_iteration" && !dispatch)
+        return cancelLearningIterationReservation(tx, { ...input, action: "cancel_iteration_reservation" }, now);
+    if (!dispatch)
+        throw new LearningDomainError("learning_dispatch_not_started", 409);
+    if (dispatch.state === "settled")
+        throw new LearningDomainError("learning_execution_already_terminal", 409);
+    if (input.action === "retry_iteration_dispatch" && dispatch.state !== "blocked")
+        throw new LearningDomainError("learning_dispatch_not_blocked", 409);
+    const cancelling = input.action === "cancel_iteration" || Boolean(dispatch.cancelRequestedAt);
+    const updated = LearningIterationSchema.parse({ ...iteration, revision: iteration.revision + 1,
+        status: cancelling ? "cancelling" : iteration.status, failure: null, updatedAt: now });
+    const resumed = LearningIterationDispatchSchema.parse({ ...dispatch, revision: dispatch.revision + 1,
+        state: dispatch.execution ? "submitted" : dispatch.submission ? "prepared" : "preparing",
+        cancelRequestedAt: cancelling ? dispatch.cancelRequestedAt ?? now : null,
+        consecutiveFailures: 0, nextAttemptAt: null, lastError: null, updatedAt: now });
+    // Preserve an in-flight lease. Its owner observes cancellation on the next
+    // transition, and a replacement worker may claim only after that lease ends.
+    await tx.put("dispatch", resumed, dispatch.revision, { parentId: iteration.id, status: resumed.state });
+    await tx.put("iteration", updated, iteration.revision, { parentId: dispatch.chainId, status: updated.status });
+    return [{ kind: "iteration", id: updated.id, revision: updated.revision }, { kind: "dispatch", id: resumed.id, revision: resumed.revision }];
+}

package/dist/learning/iteration-dispatch-contracts.js

@@ -0,0 +1,73 @@
+import { z } from "zod";
+import { contentHash, ImmutableReleaseRefSchema, ReleaseIdSchema, ReleaseTimestampSchema } from "@openpond/harness";
+import { LearningJsonObjectSchema, LearningRevisionRefSchema } from "./contracts.js";
+/** The executor validates its protocol payload before returning this snapshot.
+ * Credentials and expiring transport URLs belong to the executor, not payload. */
+export const LearningIterationSubmissionSchema = z.object({
+    provider: ReleaseIdSchema,
+    protocol: ReleaseIdSchema,
+    payload: LearningJsonObjectSchema,
+}).strict();
+export const LearningIterationDispatchSchema = z.object({
+    schemaVersion: z.literal("openpond.learningIterationDispatch.v1"),
+    id: ReleaseIdSchema,
+    revision: z.number().int().positive(),
+    iterationId: ReleaseIdSchema,
+    chainId: ReleaseIdSchema,
+    policy: LearningRevisionRefSchema,
+    batch: LearningRevisionRefSchema,
+    state: z.enum(["preparing", "prepared", "submitted", "settled", "blocked"]),
+    submission: LearningIterationSubmissionSchema.nullable(),
+    submissionHash: z.string().regex(/^[a-f0-9]{64}$/).nullable(),
+    submissionStartedAt: ReleaseTimestampSchema.nullable(),
+    execution: ImmutableReleaseRefSchema.nullable(),
+    terminalReceipt: ImmutableReleaseRefSchema.nullable(),
+    cancelRequestedAt: ReleaseTimestampSchema.nullable(),
+    leaseOwner: ReleaseIdSchema.nullable(),
+    leaseGeneration: z.number().int().nonnegative(),
+    leaseExpiresAt: ReleaseTimestampSchema.nullable(),
+    consecutiveFailures: z.number().int().nonnegative(),
+    nextAttemptAt: ReleaseTimestampSchema.nullable(),
+    lastError: z.string().max(20_000).nullable(),
+    createdAt: ReleaseTimestampSchema,
+    updatedAt: ReleaseTimestampSchema,
+}).strict().superRefine((value, context) => {
+    if (Boolean(value.submission) !== Boolean(value.submissionHash) || (value.submission && contentHash(value.submission) !== value.submissionHash)) {
+        context.addIssue({ code: "custom", path: ["submissionHash"], message: "Dispatch submission identity changed." });
+    }
+    if (value.submissionStartedAt && !value.submission)
+        context.addIssue({ code: "custom", path: ["submission"], message: "A started dispatch requires its persisted submission." });
+    if (value.execution && !value.submissionStartedAt)
+        context.addIssue({ code: "custom", path: ["execution"], message: "An execution requires a started dispatch." });
+    if (["prepared", "submitted"].includes(value.state) && !value.submission)
+        context.addIssue({ code: "custom", path: ["state"], message: "A prepared dispatch requires its immutable submission." });
+    if (value.state === "submitted" && !value.execution)
+        context.addIssue({ code: "custom", path: ["execution"], message: "A submitted dispatch requires an observed execution." });
+    if (value.state === "settled" && value.submissionStartedAt && !value.terminalReceipt)
+        context.addIssue({ code: "custom", path: ["terminalReceipt"], message: "A started dispatch requires terminal receipt evidence before settlement." });
+    if (Boolean(value.leaseOwner) !== Boolean(value.leaseExpiresAt))
+        context.addIssue({ code: "custom", path: ["leaseOwner"], message: "Dispatch lease owner and expiration must be recorded together." });
+});
+/** Terminal cleanup includes fencing future submission under this dispatch ID.
+ * The execution adapter verifies its authoritative provider receipt. */
+export const LearningIterationObservationSchema = z.object({
+    scope: ReleaseIdSchema,
+    dispatchId: ReleaseIdSchema,
+    submissionHash: z.string().regex(/^[a-f0-9]{64}$/),
+    execution: ImmutableReleaseRefSchema.nullable(),
+    status: z.enum(["running", "evaluating", "succeeded", "failed", "cancelled"]),
+    spendUsd: z.number().nonnegative(),
+    cleanupComplete: z.boolean(),
+    receipt: ImmutableReleaseRefSchema.nullable(),
+    evaluation: ImmutableReleaseRefSchema.nullable(),
+    candidate: ImmutableReleaseRefSchema.nullable(),
+    failure: z.string().max(20_000).nullable(),
+}).strict().superRefine((value, context) => {
+    if (["succeeded", "failed", "cancelled"].includes(value.status) && (!value.cleanupComplete || !value.receipt)) {
+        context.addIssue({ code: "custom", path: ["receipt"], message: "Terminal execution requires an authoritative cleanup receipt." });
+    }
+    if (value.status !== "cancelled" && !value.execution)
+        context.addIssue({ code: "custom", path: ["execution"], message: "The execution identity is required." });
+    if (value.candidate && (value.status !== "succeeded" || !value.evaluation))
+        context.addIssue({ code: "custom", path: ["candidate"], message: "A candidate requires successful retained evaluation." });
+});

package/dist/learning/iteration-dispatch-worker.js

@@ -0,0 +1,178 @@
+import { contentHash } from "@openpond/harness";
+import { LearningIterationSchema } from "./contracts.js";
+import { LearningDomainError } from "./errors.js";
+import { LearningChainSchema, LearningIterationReservationSchema } from "./iteration-reservation-contracts.js";
+import { LearningIterationDispatchSchema, LearningIterationObservationSchema, LearningIterationSubmissionSchema, } from "./iteration-dispatch-contracts.js";
+import { requireLearningRelease, requireLearningResource } from "./repository.js";
+const closed = new Set(["accepted", "rejected", "failed", "cancelled", "completed_without_candidate"]);
+export function createLearningIterationWorker(repository, executor, options) {
+    const now = options.now ?? (() => new Date().toISOString());
+    const leaseMs = options.leaseMs ?? 60_000;
+    const requestTimeoutMs = options.requestTimeoutMs ?? 45_000;
+    if (!Number.isFinite(leaseMs) || !Number.isFinite(requestTimeoutMs) || requestTimeoutMs < 1 || leaseMs <= requestTimeoutMs)
+        throw new Error("Iteration lease must exceed its bounded request timeout.");
+    async function claim(scope, id) {
+        return repository.transaction(scope, async (tx) => {
+            const iteration = await requireLearningResource(tx, "iteration", id);
+            if (closed.has(iteration.status) || iteration.status === "candidate_ready" || !iteration.batch)
+                return null;
+            const current = await tx.get("dispatch", iteration.dispatchId);
+            const stamp = now();
+            if (current?.state === "settled" || (current?.state === "blocked" && !current.cancelRequestedAt)
+                || (current?.leaseExpiresAt && Date.parse(current.leaseExpiresAt) > Date.parse(stamp))
+                || (current?.nextAttemptAt && Date.parse(current.nextAttemptAt) > Date.parse(stamp)))
+                return null;
+            const policy = await requireLearningRelease(tx, "policy", iteration.policy);
+            if (policy.executionOwner !== options.executionOwner)
+                throw new LearningDomainError("learning_execution_owner_mismatch", 409);
+            const latestPolicy = await requireLearningResource(tx, "policy", policy.id);
+            if (!latestPolicy.enabled && !current?.submissionStartedAt && !current?.cancelRequestedAt)
+                return null;
+            const batch = await requireLearningRelease(tx, "batch", iteration.batch);
+            const reservation = await requireLearningResource(tx, "reservation", id);
+            const chain = await requireLearningResource(tx, "chain", reservation.chainId);
+            if (chain.activeIterationId !== id || reservation.outcome !== "reserved")
+                throw new LearningDomainError("learning_dispatch_reservation_mismatch", 409);
+            const dispatch = LearningIterationDispatchSchema.parse({
+                schemaVersion: "openpond.learningIterationDispatch.v1", id: iteration.dispatchId,
+                iterationId: id, chainId: chain.id, policy: iteration.policy, batch: iteration.batch,
+                state: "preparing", submission: null, submissionHash: null, submissionStartedAt: null,
+                execution: null, terminalReceipt: null, cancelRequestedAt: null,
+                consecutiveFailures: 0, nextAttemptAt: null, lastError: null, createdAt: stamp,
+                ...current, revision: (current?.revision ?? 0) + 1,
+                leaseOwner: options.workerId, leaseGeneration: (current?.leaseGeneration ?? 0) + 1,
+                leaseExpiresAt: new Date(Date.parse(stamp) + leaseMs).toISOString(), updatedAt: stamp,
+            });
+            if (dispatch.iterationId !== id || contentHash(dispatch.policy) !== contentHash(iteration.policy) || contentHash(dispatch.batch) !== contentHash(iteration.batch))
+                throw new LearningDomainError("learning_dispatch_identity_mismatch", 409);
+            await tx.put("dispatch", dispatch, current?.revision ?? 0, { parentId: id, status: dispatch.state });
+            const running = LearningIterationSchema.parse({ ...iteration, revision: iteration.revision + 1,
+                status: iteration.status === "cancelling" ? "cancelling" : current?.submissionStartedAt ? iteration.status : "dispatching", updatedAt: stamp });
+            await tx.put("iteration", running, iteration.revision, { parentId: chain.id, status: running.status });
+            return { dispatch, iteration: running, policy, batch };
+        });
+    }
+    async function fenced(scope, claimed, update) {
+        return repository.transaction(scope, async (tx) => {
+            const current = await requireLearningResource(tx, "dispatch", claimed.id);
+            if (current.leaseOwner !== options.workerId || current.leaseGeneration !== claimed.leaseGeneration
+                || !current.leaseExpiresAt || Date.parse(current.leaseExpiresAt) <= Date.parse(now()) || current.state === "settled")
+                return null;
+            return update(tx, current, await requireLearningResource(tx, "iteration", current.iterationId));
+        });
+    }
+    async function saveDispatch(tx, current, patch) {
+        const updated = LearningIterationDispatchSchema.parse({ ...current, ...patch, revision: current.revision + 1, updatedAt: now() });
+        await tx.put("dispatch", updated, current.revision, { parentId: current.iterationId, status: updated.state });
+        return updated;
+    }
+    async function settle(tx, current, iteration, outcome) {
+        const terminal = !outcome || ["succeeded", "failed", "cancelled"].includes(outcome.status);
+        const status = !outcome ? "cancelled" : outcome.status === "succeeded"
+            ? outcome.candidate ? "candidate_ready" : "completed_without_candidate"
+            : outcome.status === "running" ? current.cancelRequestedAt ? "cancelling" : "training"
+                : outcome.status === "evaluating" ? current.cancelRequestedAt ? "cancelling" : "evaluating" : outcome.status;
+        const updated = LearningIterationSchema.parse({
+            ...iteration, revision: iteration.revision + 1, status, updatedAt: now(),
+            trainingJob: outcome?.execution ?? iteration.trainingJob, evaluationJob: outcome?.evaluation ?? iteration.evaluationJob,
+            candidateVersion: outcome?.candidate ?? iteration.candidateVersion, spendUsd: outcome?.spendUsd ?? iteration.spendUsd,
+            failure: outcome?.failure ? { code: "learning_execution_failed", message: outcome.failure } : null,
+        });
+        await tx.put("iteration", updated, iteration.revision, { parentId: current.chainId, status });
+        await saveDispatch(tx, current, { state: terminal ? "settled" : "submitted", execution: outcome?.execution ?? current.execution,
+            terminalReceipt: outcome?.receipt ?? null, leaseOwner: null, leaseExpiresAt: null,
+            nextAttemptAt: terminal ? null : new Date(Date.parse(now()) + 5_000).toISOString(), consecutiveFailures: 0, lastError: null });
+        if (terminal) {
+            const reservation = await requireLearningResource(tx, "reservation", iteration.id);
+            const settled = LearningIterationReservationSchema.parse({ ...reservation, revision: reservation.revision + 1,
+                budget: { ...reservation.budget, reservedSpendUsd: 0, settledSpendUsd: updated.spendUsd, settledAt: now() }, updatedAt: now() });
+            await tx.put("reservation", settled, reservation.revision, { parentId: current.chainId, status: settled.outcome });
+            if (status !== "candidate_ready") {
+                const chain = await requireLearningResource(tx, "chain", current.chainId);
+                if (chain.activeIterationId === iteration.id)
+                    await tx.put("chain", LearningChainSchema.parse({ ...chain, revision: chain.revision + 1, activeIterationId: null, updatedAt: now() }), chain.revision, { parentId: chain.modelProjectId });
+            }
+        }
+        return updated;
+    }
+    async function run(scope, iterationId) {
+        const acquired = await claim(scope, iterationId);
+        const read = () => repository.transaction(scope, tx => requireLearningResource(tx, "iteration", iterationId));
+        if (!acquired)
+            return read();
+        let dispatch = acquired.dispatch;
+        const bounded = async (operation) => {
+            const controller = new AbortController();
+            let timer;
+            const timeout = new Promise((_, reject) => { timer = setTimeout(() => { const error = new Error("Learning dispatch request timed out; reconcile its existing identity."); controller.abort(error); reject(error); }, requestTimeoutMs); });
+            try {
+                return await Promise.race([operation({ ...structuredClone({ scope, ...acquired, dispatch }), signal: controller.signal }), timeout]);
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        };
+        try {
+            if (dispatch.cancelRequestedAt && !dispatch.submissionStartedAt) {
+                await fenced(scope, dispatch, (tx, current, iteration) => settle(tx, current, iteration, null));
+                return read();
+            }
+            if (!dispatch.submission) {
+                const submission = LearningIterationSubmissionSchema.parse(await bounded(input => executor.prepare(input)));
+                const prepared = await fenced(scope, dispatch, (tx, current) => saveDispatch(tx, current, { submission, submissionHash: contentHash(submission), state: "prepared" }));
+                if (!prepared)
+                    return read();
+                dispatch = prepared;
+            }
+            const starting = await fenced(scope, dispatch, async (tx, current, iteration) => {
+                if (current.cancelRequestedAt && !current.submissionStartedAt) {
+                    await settle(tx, current, iteration, null);
+                    return null;
+                }
+                const policy = await requireLearningResource(tx, "policy", current.policy.id);
+                if (!policy.enabled && !current.submissionStartedAt) {
+                    await saveDispatch(tx, current, { leaseOwner: null, leaseExpiresAt: null });
+                    return null;
+                }
+                return saveDispatch(tx, current, { submissionStartedAt: current.submissionStartedAt ?? now() });
+            });
+            if (!starting)
+                return read();
+            dispatch = starting;
+            let observed = dispatch.cancelRequestedAt ? await bounded(input => executor.cancel(input)) : await bounded(input => executor.reconcile(input));
+            if (!observed) {
+                const refreshed = await fenced(scope, dispatch, (tx, current) => saveDispatch(tx, current, {}));
+                if (!refreshed)
+                    return read();
+                dispatch = refreshed;
+                observed = dispatch.cancelRequestedAt ? await bounded(input => executor.cancel(input)) : await bounded(input => executor.submit(input));
+            }
+            const outcome = LearningIterationObservationSchema.parse(observed);
+            if (outcome.scope !== scope || outcome.dispatchId !== dispatch.id || outcome.submissionHash !== dispatch.submissionHash
+                || (dispatch.execution && contentHash(outcome.execution) !== contentHash(dispatch.execution)))
+                throw new LearningDomainError("learning_execution_identity_mismatch", 409);
+            await fenced(scope, dispatch, async (tx, current, iteration) => {
+                if (outcome.submissionHash !== current.submissionHash || (current.execution && contentHash(outcome.execution) !== contentHash(current.execution)))
+                    throw new LearningDomainError("learning_execution_identity_mismatch", 409);
+                if (outcome.spendUsd < iteration.spendUsd)
+                    throw new LearningDomainError("learning_execution_spend_regressed", 409);
+                return settle(tx, current, iteration, outcome);
+            });
+        }
+        catch (error) {
+            await fenced(scope, dispatch, async (tx, current, iteration) => {
+                const failures = current.consecutiveFailures + 1;
+                const blocked = failures > acquired.policy.limits.maxRetries;
+                const message = (error instanceof Error ? error.message : "Learning dispatch failed.").slice(0, 20_000);
+                await saveDispatch(tx, current, { state: blocked ? "blocked" : current.state, consecutiveFailures: failures,
+                    lastError: message, leaseOwner: null, leaseExpiresAt: null,
+                    nextAttemptAt: blocked ? null : new Date(Date.parse(now()) + Math.min(60_000, 1_000 * 2 ** Math.min(failures, 6))).toISOString() });
+                const updated = LearningIterationSchema.parse({ ...iteration, revision: iteration.revision + 1, retryCount: iteration.retryCount + 1,
+                    failure: { code: blocked ? "learning_dispatch_attention_required" : "learning_dispatch_retry_pending", message }, updatedAt: now() });
+                await tx.put("iteration", updated, iteration.revision, { parentId: current.chainId, status: updated.status });
+            });
+        }
+        return read();
+    }
+    return { run };
+}

package/dist/learning/iteration-eligibility.js

@@ -0,0 +1,76 @@
+import { contentHash } from "@openpond/harness";
+import { assertAdmissionDecision } from "./admission.js";
+import { learningRef, sameLearningRef } from "./contracts.js";
+import { LearningDomainError } from "./errors.js";
+import { requireLearningRelease, requireLearningResource } from "./repository.js";
+export function learningChainId(modelProjectId) {
+    return `chain-${contentHash(modelProjectId)}`;
+}
+export function learningConsumptionId(chainId, evidence) {
+    return `consumption-${contentHash([chainId, evidence.id, evidence.revision])}`;
+}
+export async function inspectIterationEligibility(transaction, policy) {
+    // These are the methods supported by the approved-batch materializer.
+    const purpose = policy.training.method === "sft" ? "supervised_training" : "reward_training";
+    if (!["sft", "grpo", "ppo"].includes(policy.training.method)) {
+        throw new LearningDomainError("learning_batch_method_unsupported", 422);
+    }
+    // Publishing a qualification reference is not proof that an automatic decision
+    // was produced by a qualified executor. That admission operation is separate.
+    if (policy.admission.mode !== "human")
+        throw new LearningDomainError("learning_automatic_admission_not_available", 422);
+    const definition = await requireLearningRelease(transaction, "definition", policy.taskDefinition);
+    if (!sameLearningRef(definition.rewardBinding, policy.rewardBinding))
+        throw new LearningDomainError("learning_policy_binding_mismatch", 422);
+    const counts = { eligible: 0, awaitingReview: 0, excluded: 0, consumed: 0 };
+    const selected = [];
+    const chainId = learningChainId(policy.modelProjectId);
+    const seen = new Set();
+    let backlog = 0;
+    for (const sourceRef of policy.sources) {
+        const source = await requireLearningRelease(transaction, "source", sourceRef);
+        const currentSource = await requireLearningResource(transaction, "source", source.id);
+        if (!source.enabled || !currentSource.enabled)
+            throw new LearningDomainError("learning_source_disabled", 409);
+        if (!sameLearningRef(source.taskDefinition, policy.taskDefinition))
+            throw new LearningDomainError("learning_policy_source_definition_mismatch", 422);
+        let afterId;
+        do {
+            const page = await transaction.list("evidence", { parentId: source.id, limit: 100, ...(afterId ? { afterId } : {}) });
+            for (const evidence of page.items) {
+                if (seen.has(evidence.id))
+                    continue;
+                seen.add(evidence.id);
+                if (!policy.sources.some((allowed) => sameLearningRef(evidence.source, allowed)) || !sameLearningRef(evidence.submission.taskDefinition, policy.taskDefinition) || evidence.submission.split !== "train") {
+                    counts.excluded += 1;
+                    continue;
+                }
+                if (await transaction.get("consumption", learningConsumptionId(chainId, evidence))) {
+                    counts.consumed += 1;
+                    continue;
+                }
+                if (++backlog > policy.limits.maxBacklogExamples)
+                    throw new LearningDomainError("learning_backlog_limit_exceeded", 409);
+                const decision = await transaction.get("decision", `decision-${evidence.id}`);
+                if (!decision || !sameLearningRef(decision.evidence, learningRef(evidence)) || decision.taskAdmissibility === "pending" || decision.actor.kind !== "human") {
+                    counts.awaitingReview += 1;
+                    continue;
+                }
+                try {
+                    assertAdmissionDecision({ decision, evidence, definition, purpose });
+                }
+                catch (error) {
+                    if (!(error instanceof LearningDomainError))
+                        throw error;
+                    counts.excluded += 1;
+                    continue;
+                }
+                counts.eligible += 1;
+                if (selected.length < policy.limits.maxBatchExamples)
+                    selected.push({ evidence, decision });
+            }
+            afterId = page.nextCursor ?? undefined;
+        } while (afterId);
+    }
+    return { counts, selected, purpose };
+}

package/dist/learning/iteration-reservation-cancellation.js

@@ -0,0 +1,31 @@
+import { LearningIterationSchema } from "./contracts.js";
+import { LearningDomainError } from "./errors.js";
+import { LearningChainSchema, LearningIterationReservationSchema } from "./iteration-reservation-contracts.js";
+import { LearningConflictError, requireLearningResource } from "./repository.js";
+/** Only a reservation that has never been dispatched can release spend locally.
+ * Submitted executions require authoritative cancellation and settlement. */
+export async function cancelLearningIterationReservation(transaction, input, now) {
+    const iteration = await requireLearningResource(transaction, "iteration", input.iterationId);
+    if (iteration.revision !== input.expectedRevision)
+        throw new LearningConflictError("iteration", iteration.id, input.expectedRevision, iteration.revision);
+    const reservation = await requireLearningResource(transaction, "reservation", iteration.id);
+    if (iteration.status === "cancelled")
+        return [{ kind: "iteration", id: iteration.id, revision: iteration.revision }];
+    if (iteration.trainingJob || iteration.evaluationJob || !["ready", "waiting_for_data", "waiting_for_review"].includes(iteration.status)) {
+        throw new LearningDomainError("learning_execution_cancellation_required", 409);
+    }
+    const updated = LearningIterationSchema.parse({ ...iteration, revision: iteration.revision + 1, status: "cancelled", updatedAt: now });
+    const released = LearningIterationReservationSchema.parse({
+        ...reservation, revision: reservation.revision + 1,
+        budget: { ...reservation.budget, reservedSpendUsd: 0, settledSpendUsd: 0, settledAt: now }, updatedAt: now,
+    });
+    await transaction.put("iteration", updated, iteration.revision, { parentId: reservation.chainId, status: updated.status });
+    await transaction.put("reservation", released, reservation.revision, { parentId: reservation.chainId, status: reservation.outcome });
+    const chain = await requireLearningResource(transaction, "chain", reservation.chainId);
+    if (chain.activeIterationId === iteration.id) {
+        await transaction.put("chain", LearningChainSchema.parse({ ...chain, revision: chain.revision + 1, activeIterationId: null, updatedAt: now }), chain.revision, { parentId: chain.modelProjectId });
+    }
+    // Consumption is retained. Retry/replay is an explicit operation, never a
+    // side effect of cancelling that silently makes the same examples new again.
+    return [{ kind: "iteration", id: updated.id, revision: updated.revision }, { kind: "reservation", id: released.id, revision: released.revision }];
+}

package/dist/learning/iteration-reservation-contracts.js

@@ -0,0 +1,57 @@
+import { z } from "zod";
+import { ReleaseHashSchema, ReleaseIdSchema, ReleaseTimestampSchema } from "@openpond/harness";
+import { LearningRevisionRefSchema } from "./contracts.js";
+export const LearningIterationTriggerSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("manual"), identity: ReleaseIdSchema }).strict(),
+    z.object({ kind: z.literal("schedule"), scheduledAt: ReleaseTimestampSchema }).strict(),
+]);
+/** Stable across policy edits: a Model owns one learning chain in its scope. */
+export const LearningChainSchema = z.object({
+    schemaVersion: z.literal("openpond.learningChain.v1"),
+    id: ReleaseIdSchema,
+    revision: z.number().int().positive(),
+    modelProjectId: ReleaseIdSchema,
+    activeIterationId: ReleaseIdSchema.nullable(),
+    latestIterationId: ReleaseIdSchema,
+    lastReservedAt: ReleaseTimestampSchema.nullable(),
+    updatedAt: ReleaseTimestampSchema,
+}).strict();
+export const LearningEligibilityCountsSchema = z.object({
+    eligible: z.number().int().nonnegative(),
+    awaitingReview: z.number().int().nonnegative(),
+    excluded: z.number().int().nonnegative(),
+    consumed: z.number().int().nonnegative(),
+}).strict();
+/** Immutable evidence consumption survives rejection and policy revision changes.
+ * A corrected evidence revision is new data; reapproving the same revision isn't. */
+export const LearningConsumptionSchema = z.object({
+    schemaVersion: z.literal("openpond.learningConsumption.v1"),
+    id: ReleaseIdSchema,
+    revision: z.literal(1),
+    chainId: ReleaseIdSchema,
+    iterationId: ReleaseIdSchema,
+    evidence: LearningRevisionRefSchema,
+    decision: LearningRevisionRefSchema,
+    reservedAt: ReleaseTimestampSchema,
+}).strict();
+/** Dispatch must reconcile this reservation, never reserve a second batch on retry. */
+export const LearningIterationReservationSchema = z.object({
+    schemaVersion: z.literal("openpond.learningIterationReservation.v1"),
+    id: ReleaseIdSchema,
+    revision: z.number().int().positive(),
+    chainId: ReleaseIdSchema,
+    iterationId: ReleaseIdSchema,
+    policy: LearningRevisionRefSchema,
+    trigger: LearningIterationTriggerSchema,
+    requestHash: ReleaseHashSchema,
+    outcome: z.enum(["reserved", "waiting_for_data", "waiting_for_review"]),
+    counts: LearningEligibilityCountsSchema,
+    budget: z.object({
+        maximumSpendUsd: z.number().nonnegative(),
+        reservedSpendUsd: z.number().nonnegative(),
+        settledSpendUsd: z.number().nonnegative(),
+        settledAt: ReleaseTimestampSchema.nullable(),
+    }).strict(),
+    createdAt: ReleaseTimestampSchema,
+    updatedAt: ReleaseTimestampSchema,
+}).strict();