openpond-sdk 0.12.8 → 0.12.9

package/TRAINING_WORKFLOWS.md

@@ -76,15 +76,46 @@ publication, evidence and feedback, grade/review decisions, batch sealing and
 iteration reserve/cancel/retry. Reuse released resources and exact revision refs;
 the SDK does not execute Python-authored graders or invent another scheduler.
 
-`npx tsx examples/training/continual.ts inspect policy-ref.json inspection.json`
-reads current admission/budget without reserving an iteration. To execute one
-reviewed existing command, use `command command.json response.json`. The input
-must contain its stable operation ID and all schema-required scope-independent
-release references, expected revisions and limits. A reserve command is an
-explicit action, not a side effect of inspection. Retain the resulting iteration
-and job references, observe them through the same public reads, and use existing
-cancel/retry controls for recovery. Neither example changes recurring policy
-settings merely by opening or inspecting them.
+The TS example `examples/training/continual.ts` and native Python example
+`python/openpond-sdk/examples/continual.py` expose the same explicit steps:
+
+1. `inspect policy-ref.json inspection.json` checks the exact released policy.
+   Use existing reviewed source/definition/reward/binding resources and approved
+   evidence; `command command.json response.json` may publish/review/seal only
+   the explicitly supplied typed command. These are writes, and grade/reward
+   checks can incur model cost. They are never inferred from opening a policy.
+2. `reserve reserve-command.json reserved.json` sends one existing
+   `reserve_iteration` command with a stable operationId, pinned policy
+   `{id, revision, contentHash}` and manual trigger `{kind:"manual", identity}`.
+   This is the explicit paid-admission boundary: host workers may dispatch it
+   automatically. The policy must already contain the reviewed configuration,
+   batch/evidence eligibility and finite budget; the example never enables it,
+   changes its limits or accepts/promotes a candidate automatically.
+3. If the reply is lost, `reconcile reserve-command.json reconciled.json` reads
+   that policy's chain and scans at most10 pages of100 reservations for the SAME
+   pinned policy/manual trigger. It never issues another reservation. A missing
+   result is UNKNOWN, not permission to submit a new operation/trigger.
+4. `status reserved.json status.json` reloads the retained iteration, lists only
+   its dispatch, refreshes the iteration once and checks policy/execution identity
+   before reading its training job. Inconsistent snapshots require another read,
+   never a mutation. Reinvoke explicitly
+   with the latest receipt; there is no unbounded polling. `results status.json
+   results.json` requires settled dispatch plus authoritative terminal cleanup
+   receipt, then reads retained training outputs. Only cancellation before initial
+   submission may return a terminal record without a job. A candidate_ready result is not
+   accepted or served, and failed/cancelled terminal records are not success.
+5. For `cancel` or `retry`, add a new stable `operationId` to a retained response.
+   Each reloads current iteration revision; retry additionally requires the SAME
+   blocked dispatch. The host handles cancellation by dispatch identity, including
+   uncertain initial submission. Read status/results until authoritative terminal
+   receipt is observed. Local request abort never claims remote cancellation.
+
+Each invocation has a120-second bound, exclusive private output and retains exact
+iteration/policy/dispatch/job references. Reservation reads cannot manufacture
+proof of actual execution. This declares existing manual-trigger continual
+iterations; schedule/approved-count automation and Python-authored graders are
+not demonstrated by this example. One ordinary external consumer must still run
+the reviewed hosted sequence after platform security qualification.
 
 ## Proof and release
 
@@ -95,4 +126,7 @@ lost-reply reconciliation, pagination and real cancellation/recovery remain
 integration gates. Examples and source/package checks do not establish a real
 GPU result. Actual hosted GRPO/reward-model execution uses a separately bounded
 approved workflow and retains exact version/SHA/input/result/cleanup evidence.
-No package has been published by these changes.
+The original `openpond-sdk@0.12.8` is published and independently verified.
+The source follow-up prepares coordinated SDK/Ponder0.12.9; it does not claim
+that version is published. Ponder npm and Python first-name publication remain separate publisher/bootstrap
+gates; clean packed consumers do not establish registry ownership.

package/examples/training/continual.ts

@@ -1,19 +1,81 @@
 import { readFile, writeFile } from "node:fs/promises";
-import { LearningCommandSchema, LearningRevisionRefSchema, OpenPondLearningClient } from "openpond-sdk/learning";
+import { LearningCommandSchema, LearningIterationSchema, LearningRevisionRefSchema, OpenPondLearningClient } from "openpond-sdk/learning";
+import { createTrainingClient } from "openpond-sdk/training";
 
+// Each invocation performs one explicit transition or one finite read snapshot.
 const [action, inputPath, outputPath] = process.argv.slice(2);
-if (!["inspect", "command"].includes(action ?? "") || !inputPath || !outputPath) throw new Error("Usage: continual.ts <inspect|command> <policy-ref-or-command.json> <new-response.json>");
+if (!["inspect", "command", "reserve", "reconcile", "status", "results", "cancel", "retry"].includes(action ?? "") || !inputPath || !outputPath) throw new Error("Usage: continual.ts <inspect|command|reserve|reconcile|status|results|cancel|retry> <input.json> <new-response.json>");
 const { OPENPOND_API_URL: baseUrl, OPENPOND_API_KEY: apiKey, OPENPOND_TEAM_ID: scope } = process.env;
 if (!baseUrl || !apiKey || !scope) throw new Error("Set OPENPOND_API_URL, OPENPOND_API_KEY and OPENPOND_TEAM_ID.");
 const bytes = await readFile(inputPath);
 if (bytes.byteLength > 16_777_216) throw new Error("Learning input exceeds the protocol limit.");
 const input: unknown = JSON.parse(bytes.toString("utf8"));
 const client = new OpenPondLearningClient({ baseUrl, apiKey, scope });
-const options = { signal: AbortSignal.timeout(120_000) };
-// The same typed command covers existing publish/review/seal/reserve/cancel
-// operations. Preserve operationId and pinned releases on uncertain responses.
-const result = action === "inspect"
-  ? await client.inspectPolicy(LearningRevisionRefSchema.parse(input), options)
-  : await client.command(LearningCommandSchema.parse(input), options);
+const signal = AbortSignal.timeout(120_000);
+const options = { signal };
+const training = createTrainingClient({ baseUrl, headers: { Authorization: `Bearer ${apiKey}`, "X-OpenPond-Team-Id": scope }, fetch: (url, init) => fetch(url, { ...init, signal: init?.signal ? AbortSignal.any([signal, init.signal]) : signal, redirect: "error" }) });
+let result: unknown;
+if (action === "inspect") result = await client.inspectPolicy(LearningRevisionRefSchema.parse(input), options);
+else if (action === "reconcile") {
+  const command = LearningCommandSchema.parse(input);
+  if (command.action !== "reserve_iteration" || command.trigger.kind !== "manual") throw new Error("Reconcile the original manual reservation command.");
+  const triggerIdentity = command.trigger.identity;
+  const inspection = await client.inspectPolicy(command.policy, options);
+  if (!inspection.chain) throw new Error("No chain observed; do not create another reservation automatically.");
+  let afterId: string | undefined;
+  let resultFound = false;
+  const seen = new Set<string>();
+  for (let pageIndex = 0; pageIndex < 10; pageIndex++) {
+    const page = await client.list("reservation", { parentId: inspection.chain.id, limit: 100, ...(afterId ? { afterId } : {}) }, options);
+    const reservation = page.items.find((item) => item.policy.id === command.policy.id && item.policy.revision === command.policy.revision && item.policy.contentHash === command.policy.contentHash && item.trigger.kind === "manual" && item.trigger.identity === triggerIdentity);
+    if (reservation) {
+      const iteration = await client.get("iteration", reservation.iterationId, undefined, options);
+      result = { reservation, iteration }; resultFound = true; break;
+    }
+    if (!page.nextCursor) break;
+    if (seen.has(page.nextCursor)) throw new Error("Repeated reservation cursor.");
+    seen.add(page.nextCursor); afterId = page.nextCursor;
+  }
+  if (!resultFound) throw new Error("Reservation not observed within finite scan; preserve original command and reconcile with operator before any replay.");
+} else if (action === "command" || action === "reserve") {
+  const command = LearningCommandSchema.parse(input);
+  if ((action === "reserve") !== (command.action === "reserve_iteration")) throw new Error("Use explicit reserve for reserve_iteration; command is only for reviewed resource/evidence transitions.");
+  if (command.action === "reserve_iteration" && command.trigger.kind !== "manual") throw new Error("This example declares manual-trigger continual iterations only.");
+  // Reservation may be dispatched automatically by the host and incur compute.
+  // The original policy/trigger/operationId is the lost-reply reconciliation key.
+  const operation = await client.command(command, options);
+  const iteration = operation.resources.find((resource) => resource.schemaVersion === "openpond.learningIteration.v1");
+  result = { operation, ...(iteration ? { iteration } : {}) };
+} else {
+  if (!input || typeof input !== "object" || !("iteration" in input)) throw new Error("Use a retained response containing iteration; never invent a replacement reservation.");
+  const retained = LearningIterationSchema.parse(input.iteration);
+  let iteration = await client.get("iteration", retained.id, undefined, options);
+  if (iteration.id !== retained.id || (iteration.policy.id !== retained.policy.id || iteration.policy.revision !== retained.policy.revision || iteration.policy.contentHash !== retained.policy.contentHash) || iteration.dispatchId !== retained.dispatchId) throw new Error("Iteration binding changed.");
+  if (action === "cancel" || action === "retry") {
+    if (!("operationId" in input) || typeof input.operationId !== "string") throw new Error("Add a new stable control operationId to the retained response before dispatch.");
+    if (action === "retry") {
+      const dispatch = await client.get("dispatch", iteration.dispatchId, undefined, options);
+      if (dispatch.iterationId !== iteration.id || dispatch.state !== "blocked") throw new Error("Only the same blocked dispatch can be retried.");
+    }
+    const command = LearningCommandSchema.parse({ action: action === "cancel" ? "cancel_iteration" : "retry_iteration_dispatch", operationId: input.operationId, iterationId: iteration.id, expectedRevision: iteration.revision });
+    const operation = await client.command(command, options);
+    result = { operation, iteration: operation.resources.find((resource) => resource.schemaVersion === "openpond.learningIteration.v1") ?? iteration };
+  } else {
+    // Empty list is legitimate before the worker creates this dispatch.
+    const page = await client.list("dispatch", { parentId: iteration.id, limit: 2 }, options);
+    if (page.nextCursor || page.items.length > 1 || page.items.some((item) => item.id !== iteration.dispatchId)) throw new Error("Ambiguous dispatch identity.");
+    const dispatch = page.items[0] ?? null;
+    // Separate HTTP reads can straddle the worker's atomic commit. Refresh once.
+    iteration = await client.get("iteration", retained.id, undefined, options);
+    if (iteration.policy.id !== retained.policy.id || iteration.policy.revision !== retained.policy.revision || iteration.policy.contentHash !== retained.policy.contentHash || iteration.dispatchId !== retained.dispatchId) throw new Error("Iteration binding changed.");
+    if (dispatch && (dispatch.iterationId !== iteration.id || dispatch.policy.id !== iteration.policy.id || dispatch.policy.revision !== iteration.policy.revision || dispatch.policy.contentHash !== iteration.policy.contentHash || dispatch.execution?.id !== iteration.trainingJob?.id || dispatch.execution?.contentHash !== iteration.trainingJob?.contentHash)) throw new Error("Snapshot changed; read status again without mutation.");
+    if (!dispatch && iteration.trainingJob) throw new Error("Snapshot changed; read status again.");
+    const job = iteration.trainingJob ? await training.getJob(iteration.trainingJob.id) : null;
+    if (job && (job.id !== iteration.trainingJob?.id || job.submissionHash !== iteration.trainingJob?.contentHash)) throw new Error("Training execution content identity mismatch.");
+    if (action === "results" && (!dispatch || dispatch.state !== "settled" || !dispatch.terminalReceipt)) throw new Error("No settled authoritative execution/cleanup receipt yet; retain status and inspect again.");
+    if (action === "results" && !job && (iteration.status !== "cancelled" || dispatch?.execution)) throw new Error("Terminal job not observed.");
+    result = { iteration, dispatch, job, ...(action === "results" && job ? { outputs: await training.outputs(job.id) } : {}) };
+  }
+}
 await writeFile(outputPath, JSON.stringify(result, null, 2) + "\n", { flag: "wx", mode: 0o600 });
-console.log("Saved the retained learning response. Inspection does not reserve an iteration; command execution uses its explicit existing approval/budget contract.");
+console.log("Saved one retained transition/snapshot. Timeout does not cancel remote work; reconcile the same iteration before any explicit retry.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openpond-sdk",
-  "version": "0.12.8",
+  "version": "0.12.9",
   "description": "Server-side TypeScript SDK for OpenPond sandboxes and agentic work",
   "license": "MIT",
   "type": "module",