openpond-sdk 0.12.24 → 0.12.26

package/LEARNING.md

@@ -11,7 +11,7 @@ formats first. The sample uses an input object with `question` and an output
 object with `answer`; adapt the record to your published format. The scripts read
 the source's exact task-definition reference from the server.
 
-Set `OPENPOND_API_KEY`, `OPENPOND_API_URL` and `OPENPOND_LEARNING_SCOPE` in your
+Set `OPENPOND_API_KEY` and `OPENPOND_LEARNING_SCOPE` in your
 shell, then run one of:
 
 ```sh
@@ -19,12 +19,10 @@ node --experimental-strip-types submit.ts SOURCE_ID example.json
 python3 submit.py SOURCE_ID example.json
 ```
 
-Use the URL of the execution owner: a local OpenPond server or the hosted API
-where the learning service is deployed. The server authorizes the requested
-profile/team scope. The SDK and Python example send the selected scope in
-`X-OpenPond-Team-Id` so hosted requests select that team before authorization;
-the local server uses the profile scope in the request body. These variables are example configuration, not arguments
-that should be committed with credentials.
+The SDK connects to OpenPond automatically. The server authorizes the requested
+workspace scope. The SDK and Python example send that scope in
+`X-OpenPond-Team-Id`. Keep credentials in your application's secret configuration.
+Do not commit their values.
 
 Assign stable example/attempt identities and preserve `idempotencyKey`, timestamp
 and content on retries. A different record must use a different key. Submission

package/OPENTELEMETRY.md

@@ -19,7 +19,7 @@ import { OpenPondClient } from "openpond-sdk";
 import { OpenPondSpanExporter } from "openpond-sdk/opentelemetry";
 import { BatchSpanProcessor, TracerProvider } from "@opentelemetry/sdk-trace";
 
-const client = new OpenPondClient({ baseUrl: apiBaseUrl, apiKey, teamId });
+const client = new OpenPondClient({ apiKey, teamId });
 const exporter = new OpenPondSpanExporter({
   client,
   datasetId,

package/PRODUCT_INTEGRATION.md

@@ -0,0 +1,129 @@
+# Use OpenPond in your product
+
+The APIs below target the **0.12.25 source candidate**, which is not published
+yet. Registry version 0.12.24 does not include configured Dataset/named-model
+setup. Use the built candidate package until the coordinated release.
+
+
+Configure one application-owned server client. Bind aliases to exact callable
+Model IDs from your serving destination:
+
+```ts
+import { createOpenPondClient } from "openpond-sdk";
+
+export const openpond = createOpenPondClient({
+  apiKey: process.env.OPENPOND_API_KEY!,
+  teamId: process.env.OPENPOND_TEAM_ID!,
+  datasetId: process.env.OPENPOND_DATASET_ID!,
+  models: { support: process.env.OPENPOND_MODEL_ID! },
+});
+
+const answer = await openpond.models.support.generate({ prompt: "How do I rotate a token?" });
+console.log(answer.text, answer.requestId, answer.usage);
+```
+
+The SDK connects to OpenPond with your API key for task submission and personalized
+inference. Use a key authorized for the selected Dataset and Model. A Dataset-only
+producer key cannot invoke inference. Bind the exact callable Model ID; no
+catalogue default or substitute Model is selected. Naming a Model never activates serving, approves a
+candidate, starts training, or automatically captures inference as a task.
+Decision scorers use their separate typed scoring APIs.
+
+`generate` accepts either `prompt` or text `messages`, plus optional `temperature`,
+`maxTokens` and `signal`. Results include `text`, `requestId`, requested `modelId`,
+server-reported `resolvedModelId`, `finishReason`, nullable `usage`, and nullable
+`systemFingerprint`, plus retained server `evidence` when supplied. Evidence
+presence is not client-side verification. Core handles are text APIs; tools need
+the supported integration and explicit capabilities. The current personalized API
+rejects multimodal and structured-output modes. Aliases are typed TypeScript
+properties; multiple clients remain independent.
+
+```ts
+for await (const event of openpond.models.support.stream({ prompt: "Explain token rotation" })) {
+  if (event.type === "text") process.stdout.write(event.text);
+  else console.log(event.result.usage);
+}
+```
+
+Breaking the iteration cancels the response. An interrupted stream raises
+`ProductModelError` and never emits a successful `finish`. It may already have
+incurred usage; inference is never automatically replayed. `serving.timeoutMs`
+defaults to 60 seconds and accepts at most 300 seconds. Supply a caller abort
+signal to cancel an individual request. Text requests are bounded to 1 MiB and
+results to 8 MiB; individual stream frames to 1 MiB.
+
+Await task delivery separately with `openpond.addTask(...)`. If inference succeeds
+and optional task delivery fails, preserve both outcomes rather than discarding
+the delivery error or pretending the answer failed. See [task ingestion](TASK_INGESTION.md).
+
+## Python sync and async
+
+```python
+from ponder_sdk import AsyncClient
+
+async with AsyncClient(
+    api_key=api_key, team_id=team_id,
+    dataset_id=dataset_id,
+    model_aliases={"support": model_id},
+) as openpond:
+    answer = await openpond.models.support.generate(prompt="How do I rotate a token?")
+    print(answer.text, answer.request_id, answer.usage)
+    await openpond.add_task({"id": event_id, "name": "Token rotation", "input": {"question": question}})
+    async for event in openpond.models.support.stream(prompt="Explain the steps"):
+        if event.type == "text":
+            print(event.text, end="")
+```
+
+`Client` has the same configuration and synchronous calls/iteration. Named aliases
+augment existing Model administration methods; choose aliases that don't collide
+with those methods. Bracket access (`openpond.models["support"]`) is also available.
+Inference shares the existing client's HTTP pool and timeout. Close partially
+consumed iterators (or use `contextlib.closing`/`aclosing`) to release streams
+promptly. Native async cancellation propagates. No SDK queues or flush calls exist.
+
+## Optional Vercel AI SDK 7 integration
+
+Install `ai@^7.0.165` and `@ai-sdk/openai-compatible@^3.0.87` alongside OpenPond.
+Only the `openpond-sdk/ai-sdk` entry point imports the optional provider; task
+submission has no Vercel dependency. This adapter targets LanguageModelV4 and is
+not an upgrade of an application's existing AI SDK 4/5/6 installation.
+
+```ts
+import { generateText, streamText } from "ai";
+import { toAIModel } from "openpond-sdk/ai-sdk";
+import { openpond } from "./openpond.server.js";
+
+const model = toAIModel(openpond.models.support);
+const answer = await generateText({ model, prompt: "Explain token rotation", maxRetries: 0 });
+
+// Inside an authenticated product backend route:
+export async function POST(request: Request) {
+  // Authenticate the product user and validate/limit this payload first.
+  const { prompt } = await request.json();
+  const result = streamText({ model, prompt, abortSignal: request.signal, maxRetries: 0 });
+  return result.toUIMessageStreamResponse();
+}
+```
+
+Use the AI SDK 7 React `useChat`/transport recipe against your own authenticated
+backend. Never place the OpenPond client or secrets in browser code. AI SDK's UI
+stream response is different from raw OpenAI SSE; use
+`toUIMessageStreamResponse()` rather than forwarding raw SSE into `useChat`.
+
+The official compatible provider handles content/usage conversion, tool deltas and
+stream cancellation. OpenPond gates features against the selected binding:
+
+```ts
+models: {
+  support: {
+    id: process.env.OPENPOND_MODEL_ID!,
+    capabilities: { streaming: true, tools: true },
+  },
+}
+```
+
+Only enable tools after checking that exact deployment.
+Defaults are streaming enabled and tools disabled. Structured-output and multimodal
+inputs are rejected. Failed provider calls are surfaced as non-retryable SDK
+errors to prevent implicit replay of billed requests. Explicit `maxRetries: 0`
+also makes that intent visible in application code.

package/README.md

@@ -20,7 +20,7 @@ Node.js 22.14 or newer is required. This package is server-only: never expose an
 
 `OpenPondExperimentsClient` from `openpond-sdk/experiments` admits one run and its
 immutable configuration with `run(configuration)`. It is also available as
-`createOpenPondClient({ apiKey, baseUrl }).experiments(teamId)`. The request includes
+`createOpenPondClient({ apiKey }).experiments(teamId)`. The request includes
 one stable operation ID (also on its nested request), dataset/population,
 target/settings, selected graders and spending cap. Reuse the same operation ID
 after a transport failure; it returns the same Experiment without duplicate work.
@@ -67,7 +67,6 @@ export const maxDuration = 800;
 
 const openpond = createOpenPondClient({
   apiKey: process.env.OPENPOND_API_KEY!,
-  baseUrl: process.env.OPENPOND_API_URL,
 });
 
 export async function POST(request: Request) {
@@ -392,4 +391,15 @@ not implicitly share a spending cap.
 
 ## Add production tasks
 
-Use the flat `client.addTask(datasetId, task)` operation, or bind one destination with `createTaskAdder` and call `addTask(task)`. See [task ingestion](TASK_INGESTION.md) for TypeScript/Python examples, receipt semantics and duplicate-safe retries. Task uploads do not enable training.
+Configure `datasetId` once and await `client.addTask({ id: sourceEventId, name, input })`. Use `client.dataset(otherDatasetId).addTask(task)` for another destination. See [task ingestion](TASK_INGESTION.md) for TypeScript/Python examples, receipt semantics and duplicate-safe retries. Task uploads do not enable training.
+
+Dataset workspace HTTP failures throw `DatasetWorkspaceRequestError` from
+`openpond-sdk/dataset-workspaces`, with `status`, an allowlisted `code`,
+`retryable`, and `outcomeUnknown`. Messages contain fixed recovery guidance;
+raw server diagnostics are discarded. `retryable` does not trigger an automatic
+retry. When `outcomeUnknown` is true, retain the original operation ID and request
+bytes, recover its receipt with `operationResult`, or retry the identical request.
+
+## Add OpenPond to a product
+
+Configure named personalized Model handles with `models` and your API key, then call `client.models.support.generate({ prompt })` or iterate `stream({ prompt })`. See [product integration](PRODUCT_INTEGRATION.md) for TypeScript, Python, React/backend and optional Vercel AI SDK 7 examples. Inference never activates serving or automatically captures tasks.

package/SERVERLESS_SERVING.md

@@ -0,0 +1,37 @@
+# Usage-based saved Model serving
+
+A saved trained Model can be activated when the service returns a compatible
+Serverless price review. Model availability and GPU residency are separate:
+the Model stays callable while unused workers scale down. Cold requests can wait
+for model loading; no fixed cold-start latency is promised.
+
+Read `training.modelServing(modelProjectId, { teamId, versionHash })` for the
+exact saved version. When `serverlessReview` is available, use
+`createServerlessServingApproval(serverlessReview, spendingLimit)` from
+`openpond-sdk/training` and include the result as `serverlessApproval` in the
+normal `training.controlModelServing` activation request. Retain the original
+operation ID and exact request for recovery. The request's idle setting must
+match the review's `workerIdleTimeoutSeconds`.
+
+Activation creates callable configuration. Each inference reserves a finite
+amount of workspace credit before dispatch and settles observed allocated
+execution time. Compatible requests can share a worker; their quantities divide
+the same interval rather than each receiving a full GPU clock. Startup, queue
+and idle time have no separate customer charge. Token usage is still reported,
+with no additional token charge for the same Serverless request.
+
+The optional spending limit bounds the accepted activation's cumulative usage.
+An omitted limit uses available workspace credit. Pending requests retain their
+credit holds until execution release is confirmed. Stop closes new admission
+and requests cancellation while preserving outstanding settlement and cleanup.
+Delayed supplier records do not increase an accepted customer price.
+
+Current usage is returned in `control.serverless`: `chargedUsd`, `reservedUsd`,
+`quantityMicros` and the retained review. Supplier-cost status is separate from
+the customer debit. An unavailable review does not qualify another model or
+modification method automatically.
+
+Python consumers use the same generated request/response contracts and can
+import `create_serverless_serving_approval` from `ponder_sdk.serverless_serving`.
+The official CLI's `hosted-model-serving` and `hosted-control-model-serving`
+operations use these same Model contracts.

package/TASKSETS.md

@@ -8,7 +8,6 @@ optional Model Project attachment filtering before returning records.
 import { OpenPondTasksetCatalogClient } from "openpond-sdk/taskset-catalog";
 
 const tasksets = new OpenPondTasksetCatalogClient({
-  baseUrl: "https://api.openpond.ai",
   apiKey,
   teamId,
 });
@@ -262,7 +261,7 @@ Imported source still requires explicit source review before publication.
 
 `OpenPondTasksetDraftClient` from `openpond-sdk/taskset-drafts` defines the
 scoped `/v1/models/:modelId/taskset-drafts` protocol. Construct it in server code
-with `baseUrl`, `apiKey` and `teamId`. It supports source inspection,
+with `apiKey` and `teamId`. It supports source inspection,
 initialization, listing, document/file reads and edits, explicit Model refresh,
 validation, publication and deletion. Hosting these endpoints requires a server
 implementation; exporting this client alone does not make them available.

package/TASK_INGESTION.md

@@ -1,135 +1,136 @@
 # Add tasks to a Dataset
 
-Task submission uses an authenticated OpenPond API, separate from OpenTelemetry.
-A successful receipt means a structured task was durably saved and is available
-through the ordinary Dataset Tasks reader. It does not start training, publish
-a release, create a Model or enable a collection schedule.
+The APIs below target the **0.12.25 source candidate**, which is not published
+yet. Registry version 0.12.24 does not include configured Dataset/named-model
+setup. Use the built candidate package until the coordinated release.
 
-Create or choose an editable Dataset in Console and copy its ID. Configure the
-server-side SDK with the workspace that owns it:
+
+Configure a client once in your product's server module. Submit one structured
+source event with `await addTask(task)`:
 
 ```ts
 import { createOpenPondClient } from "openpond-sdk";
 
-const client = createOpenPondClient({
+export const openpond = createOpenPondClient({
   apiKey: process.env.OPENPOND_API_KEY!,
   teamId: process.env.OPENPOND_TEAM_ID!,
+  datasetId: process.env.OPENPOND_DATASET_ID!,
 });
 
-const receipt = await client.addTask(process.env.OPENPOND_DATASET_ID!, {
+const receipt = await openpond.addTask({
+  id: sourceEventId,
   name: "Handle an expired API token",
   input: { request: "Fetch the report", observedError: "Token expired" },
-  source: { kind: "production_agent", eventId: "run-123" },
-}, { idempotencyKey: "run-123" });
-
+  source: { kind: "production_agent", eventId: sourceEventId },
+});
 console.log(receipt.taskId, receipt.receivedAt);
 ```
 
-Use a configured `baseUrl` when targeting a different OpenPond API origin.
-Never expose the API key in browser code or logged task content.
-
-## Bind the destination once
+The client connects to OpenPond automatically and keeps its own credentials;
+no mutable global account is used. For an explicit alternate Dataset:
 
 ```ts
-import { createTaskAdder } from "openpond-sdk";
-
-const addTask = createTaskAdder({
-  apiKey: process.env.OPENPOND_API_KEY!,
-  teamId: process.env.OPENPOND_TEAM_ID!,
-  datasetId: process.env.OPENPOND_DATASET_ID!,
-  baseUrl: "https://api.openpond.ai",
-});
-
-await addTask({
+await openpond.dataset(otherDatasetId).addTask({
+  id: sourceEventId,
   name: "Explain a failed agent run",
   input: { request: "Summarize the report", outcome: "incomplete" },
-}, { idempotencyKey: "agent-run-456" });
+});
 ```
 
-The Dataset ID is still included in every request. The helper binds it locally;
-it never uses a global account, last-selected Dataset or implicit Fix-it Model.
+`addTask(datasetId, task)` and the `createTaskAdder` helper remain available.
 
-## Input and receipt
+## Delivery, identity and retries
 
-Every task has a readable `name` and structured `input`. Optional fields are
-`expectedOutput`, `split`, `tags` and `source` (`kind`, `eventId`, `label`,
-`occurredAt`). The default split is `validation`. A `train` split alone does
-not authorize training. Keep a missing correct answer absent rather than
-replacing it with an error message.
+A successful receipt confirms durable storage of the task and its processing
+obligation. It does not wait for indexing, grading or training. Dataset projection
+may lag acknowledgement. Await suspends this async function while the JavaScript
+event loop continues handling other work. There is no SDK background queue,
+flush command or permanent streaming connection.
 
-The complete request is bounded to 128 KiB. The receipt includes workspace,
-Dataset, task and operation identities, server `receivedAt`, saved revision,
-`state: "saved"` and `trainingUseAuthorized: false`. Source occurrence time is
-different from server upload time.
+`id` identifies the source event within the workspace and Dataset. It is separate
+from the server's canonical `receipt.taskId`. Repeating the same source ID and
+content returns the original receipt; changed content conflicts instead of
+silently overwriting. New credentials still need current authorization for that
+exact Dataset. A successful upload grants no training permission.
 
-## Delivery and retries
-
-Retain an explicit stable idempotency key for each source event. Repeating the
-same key and task in the same authorized destination returns the original
-receipt without inserting a duplicate. Reusing a key with different content is
-a conflict. Separate keys add separate tasks, including simultaneous writers.
-
-The SDK makes one request; it does not silently replay arbitrary mutations.
-When a response is lost, `DatasetTaskIngestionError.operationId` retains the
-operation identity and `outcomeUnknown` indicates that persistence could not be
-confirmed. Retry the original task with that same key. Do not generate a new
-key merely because the response was interrupted. A supplied abort signal is
-forwarded to the request; an interrupted response can still have been saved.
+The SDK sends once. It never automatically replays a mutation. Preserve your
+source ID and original content across uncertain outcomes:
 
 ```ts
 import { DatasetTaskIngestionError } from "openpond-sdk";
 
+const task = { id: sourceEventId, name: "Expired token", input: { error: "expired" } };
 try {
-  await addTask(task, { idempotencyKey: sourceEventId });
+  await openpond.addTask(task, { signal: request.signal, timeoutMs: 10_000 });
 } catch (error) {
   if (error instanceof DatasetTaskIngestionError && error.outcomeUnknown) {
-    // Retain task + error.operationId privately for a later exact retry.
+    // Retain task and error.sourceId privately for a later exact retry.
   }
   throw error;
 }
 ```
 
-The underlying route is `POST /v1/dataset-workspaces/{datasetId}/tasks`, with
-`Authorization: Bearer …`, `X-OpenPond-Team-Id` and JSON:
-
-```json
-{
-  "schemaVersion": "openpond.datasetTaskAppend.v1",
-  "operationId": "stable-source-event",
-  "task": {
-    "name": "Handle an expired API token",
-    "input": { "observedError": "Token expired" }
-  }
-}
-```
-
-The server owns authorization, atomic append and revision history. Appending
-does not rewrite fixed Experiment Dataset versions or previously published
-releases. Full authoring still uses the revisioned Dataset workspace API.
+When `id` is omitted the SDK generates one before dispatch. On uncertain delivery,
+`DatasetTaskIngestionError.sourceId` (also `operationId`) retains it. Supply that
+ID in a later retry. Prefer an explicit ID when cancellation or process exit could
+prevent handling the error. An event never transmitted successfully cannot be
+promised durable. `idempotencyKey` is accepted for existing callers; supplying a
+conflicting `task.id` is rejected before dispatch.
+
+Every task has `name` and structured `input`. Optional fields: `expectedOutput`,
+`split`, `tags`, and `source` (`kind`, `eventId`, `label`, `occurredAt`). Default
+split: `validation`; `train` alone grants no learning authority. Requests are
+bounded to 128 KiB. The receipt retains workspace, Dataset, canonical task and
+source identities, first-save `receivedAt`, revision, `state: "saved"` and
+`trainingUseAuthorized: false`. Source occurrence time differs from upload time.
+Existing immutable releases and Experiment inputs retain their own identities.
 
 ## Python
 
-The maintained `ponder-sdk` package exposes the same operation on `Client`
-and `AsyncClient`:
+`ponder-sdk` uses the same configured destination and source ID with its native
+owned connection pool:
 
 ```python
 from ponder_sdk import Client
 
-with Client(base_url=api_origin, api_key=api_key, team_id=team_id) as client:
-    receipt = client.add_task(
-        dataset_id,
-        {"name": "Handle an expired API token", "input": {"error": "Token expired"}},
-        idempotency_key=source_event_id,
-    )
+with Client(api_key=api_key, team_id=team_id,
+            dataset_id=dataset_id) as openpond:
+    receipt = openpond.add_task({
+        "id": source_event_id,
+        "name": "Expired token",
+        "input": {"error": "Token expired"},
+    })
+    # Alternate destination; uses the same pool:
+    # openpond.dataset(other_dataset_id).add_task(task)
 ```
 
-Use `async with AsyncClient(...)` and `await client.add_task(...)` for async
-applications. Both use the existing client connection pool and typed wire
-validation. Retain the caller's key/task across an unknown mutation outcome.
+Sync calls block their calling thread. Async applications use
+`async with AsyncClient(...)` and `await openpond.add_task(task)`. Both validate the
+maintained wire schemas and never replay writes automatically. A `PonderError`
+retains `operation_id` and `outcome_unknown`; cancellation propagates, so retain
+your own source ID before awaiting. Closing the HTTP pool is resource cleanup,
+not delivery flushing.
+
+## HTTP and React
+
+The HTTP operation remains `POST /v1/dataset-workspaces/{datasetId}/tasks` with
+Bearer auth and `X-OpenPond-Team-Id`. The public `task.id` maps to wire
+`operationId`; it is excluded from `task` content:
+
+```json
+{
+  "schemaVersion": "openpond.datasetTaskAppend.v1",
+  "operationId": "stable-source-event",
+  "task": { "name": "Expired token", "input": { "error": "expired" } }
+}
+```
 
-## OpenTelemetry
+React calls your authenticated product backend. The backend selects an authorized
+Dataset and awaits the configured client. Keep OpenPond secrets and destination
+authority server-side; do not accept an arbitrary browser-supplied Dataset ID.
+For named model calls and the optional Vercel integration see
+[product integration](PRODUCT_INTEGRATION.md).
 
-OpenTelemetry is an optional source adapter, not this HTTP request format.
-Its span exporter can project explicitly selected spans into structured tasks
-using the same destination and receipts. It does not make this endpoint an
-OTLP receiver, automatically capture arbitrary logs, or authorize training.
+OpenTelemetry is a separate optional source adapter, not this request format.
+Project explicitly selected spans into structured tasks. This endpoint is not an
+OTLP receiver and does not capture arbitrary logs or authorize training.

package/TRAINING_PROTOCOL.md

@@ -50,8 +50,8 @@ GET  /v1/training/jobs?modelProjectId=&cursor=&limit=
 GET  /v1/training/jobs/{jobId}
 POST /v1/training/jobs/{jobId}/cancel
 POST /v1/training/jobs/{jobId}/stop-after-group
-GET  /v1/training/jobs/{jobId}/events
-GET  /v1/training/jobs/{jobId}/logs
+GET  /v1/training/jobs/{jobId}/events?after=0&limit=50
+GET  /v1/training/jobs/{jobId}/logs?after=0&limit=50
 GET  /v1/training/jobs/{jobId}/outputs
 
 PUT  /v1/model-projects/{portableProjectId}
@@ -205,7 +205,7 @@ and an in-memory asset map without creating a training job or acquiring compute.
 
 The compiler verifies selected release identities and private verifier bytes,
 checks training/evaluation isolation, and rejects missing or unexpected Work
-assets. Callers retain responsibility for authorizing the inputs and staging the
+assets. Callers retain responsibility for authorizing the inputs and preparing the
 result through the training artifact API before job admission. Filesystem cache
 materialization remains a Desktop concern.
 
@@ -328,3 +328,7 @@ It performs no authentication, network upload, tool execution, training, or mode
 activation. Callers must verify authentic durable hosted receipts before
 acknowledging delivery. Import the portable entry in browser code; the Node queue
 is a separate runtime capability.
+
+### Retained evidence pagination
+
+Events and logs return at most 100 records per database-selected page (default 50), plus `nextOffset` or `null`. Use `training.eventsPage(jobId, { after, limit })` and `training.logsPage(...)` to obtain `{ items, nextOffset }`. The SDK validates the returned job, sequence window, count and continuation before exposing records. Offsets address the current ordered snapshot; lifecycle snapshots can change while a run is live. They are not an immutable append-only cursor. Existing `events()`/`logs()` convenience reads follow pages with an aggregate response-byte budget and a 100,000-record ceiling. MCP requests exactly one page.

package/TRAINING_WORKFLOWS.md

@@ -9,8 +9,8 @@ the actual host/account before preparing work.
 
 ## Authentication and lifecycle
 
-Training and Model clients accept `baseUrl`, `headers` (including an async token
-supplier) and an injectable `fetch`. Use the host's normal Bearer credential and
+Training and Model clients connect to OpenPond automatically. They accept
+`headers` (including an async token supplier) and an injectable `fetch`. Use your API key as the Bearer credential and
 `X-OpenPond-Team-Id`; retain server authorization and owner checks. Learning,
 Dataset and taskset-run clients accept their existing `apiKey` and workspace
 scope. Never put credentials in URLs, request identities, fixtures or receipts.
@@ -204,8 +204,7 @@ the job controls and keep its identity.
    explicit `recordCandidateDecision` with its exact artifact reference and CAS.
    `cancel` reconciles the current job version before sending remote cancellation.
 
-The examples require `OPENPOND_API_URL`, `OPENPOND_API_KEY` and
-`OPENPOND_TEAM_ID` from the caller's normal configured account. They use only
+The examples require `OPENPOND_API_KEY` and `OPENPOND_TEAM_ID` from the caller's normal configured account. They use only
 public SDK imports, bound each invocation to two minutes and write new receipt
 files exclusively with mode0600. They do not poll indefinitely or automatically
 retry an uncertain paid start. Keep the original receipt for future reconciliation.
@@ -495,9 +494,9 @@ of `neuron_steering` and `inspect_activations`. `draftSchema` describes the form
 not permission to write or execute.
 
 Each capability observation retains `validationLevel`: `null` when execution is
-unavailable, `source_validated` for an experimental staging runtime, or
+unavailable, `source_validated` for an experimental runtime, or
 `gpu_qualified` after a retained exact-model/runtime GPU run. Source validation
-describes a runtime reviewed for an experimental staging trial; it is not
+describes a runtime reviewed for an experimental trial; it is not
 evidence that training or inference has already succeeded. Read the runtime's retained evidence; neither level
 reserves compute, approves a charge or establishes model quality. Engram,
 Decision, AlphaEdit and neuron-training capabilities use the same distinction.
@@ -669,3 +668,9 @@ optimizer creation and exports a cumulative patch with parent, initial and
 final state hashes. A runtime must explicitly advertise this mode before
 admission; source packaging alone does not establish native qualification or
 old/new held-out retention.
+
+### Managed GRPO sampling support
+
+Use `topP: 1` for managed GRPO. The current qualified trainer replays temperature and the retained required-tool grammar; it cannot replay an independent nucleus filter or separate JSON response grammar. Unsupported generation settings are rejected during preparation, before allocation. Structured Work output uses its supported required-tool path. Existing saved requests retain their explicit settings and are never silently rewritten.
+
+The current managed runtime admits at least two optimizer iterations. A single iteration is not inherently invalid GRPO, but needs explicit support from the selected runtime before it can be prepared. Each iteration accumulates the entire trajectory group before stepping; `gradientAccumulationSteps` does not define separate optimizer windows for GRPO. SFT uses its own true batch accumulation and exact model/image limits. Held-out SFT evaluation does not select optimizer updates.

package/dist/advanced-refiner-evaluations.js

@@ -12,19 +12,20 @@ import {
   sealAdvancedRefinerEvaluationPin,
   sealAdvancedRefinerReviewReceipt,
   verifyAdvancedRefinerEvaluationPin
-} from "./chunk-6EZAGTZG.js";
-import "./chunk-3B5KSH3V.js";
-import "./chunk-H3367ISL.js";
-import "./chunk-QNOCM5JX.js";
-import "./chunk-626JLH4D.js";
+} from "./chunk-X5AT253K.js";
+import "./chunk-D26RJQU7.js";
+import "./chunk-456F3BXD.js";
+import "./chunk-JWEIAEQ6.js";
 import "./chunk-O6FKHAWN.js";
-import "./chunk-GS5HEE4M.js";
-import "./chunk-ZRTNR4U7.js";
-import "./chunk-JMFYNIYZ.js";
-import "./chunk-MVAEE5EI.js";
+import "./chunk-H3367ISL.js";
+import "./chunk-4REK5TTE.js";
+import "./chunk-XWUTYFOU.js";
+import "./chunk-CAOMKM55.js";
+import "./chunk-H5KHLBC5.js";
 import "./chunk-CL3IOOVL.js";
 import "./chunk-B3ZHJ2KK.js";
 import "./chunk-H3JZ3P5T.js";
+import "./chunk-QYWPNNP3.js";
 import "./chunk-YLJ4XMA6.js";
 export {
   AdvancedRefinerEvaluationAccountingSchema,