openpond-sdk 0.0.13 → 0.0.14

package/README.md

@@ -258,7 +258,10 @@ identity and explicit approval is captured for that submission only.
 `createTrainingClient` reads capabilities and creates or observes immutable
 Jobs, including Project-filtered Run history. These clients require an
 authenticated server-side API context; the schemas themselves contain no
-database, provider, credential, Electron, or UI dependencies.
+database, provider, credential, Electron, or UI dependencies. See
+[TRAINING_PROTOCOL.md](./TRAINING_PROTOCOL.md) for media types, hashing, size
+limits, compatibility rules, provider routes, receipts, and the published
+conformance fixtures.
 
 ## Development
 

package/TRAINING_PROTOCOL.md

@@ -0,0 +1,78 @@
+# OpenPond Training Protocol V2
+
+`openpond-sdk/training` and `openpond-sdk/model-projects` are the portable,
+provider-neutral contract for OpenPond managed training. Providers implement
+these resources without importing the OpenPond application server or exposing
+their placement, worker, lease, credential, or storage internals.
+
+## Compatibility rules
+
+- Send and accept `application/vnd.openpond.training+json;version=2` for
+  Training resources and `application/vnd.openpond.model-project+json;version=2`
+  for Model Project resources. Reject unsupported major versions with a
+  versioned API error and HTTP 406 or 415.
+- Public resource envelopes are strict. Unknown fields are rejected. The two
+  intentionally extensible locations are versioned recipe documents and event
+  `data`; a provider must preserve recipe fields it does not interpret and
+  reject a recipe version it cannot execute.
+- A Training Job submission is at most 1 MiB of canonical JSON. Model Project
+  sync is at most 512 KiB. SDK responses are bounded at 8 MiB. Artifact bytes
+  are not embedded in these documents; they are transferred through immutable,
+  content-addressed artifact references.
+- `contentHash` on `openpond.trainingJobSubmission.v2` is lowercase SHA-256 of
+  the canonical JSON object with the top-level `contentHash` member omitted.
+  Canonical JSON sorts object keys, preserves array order, rejects non-JSON and
+  non-finite values, and encodes UTF-8 bytes.
+- A repeated idempotency key for the same team and identical submission hash
+  returns the original Job. Reusing the key with different bytes is a conflict.
+  Project revisions use optimistic ETags; a stale Project author must refresh
+  before overwriting mutable authoring fields.
+- Jobs, events, outputs, and receipts are immutable history. Cancellation and
+  stop-after-group require the caller's observed Job version. Hosted Job state
+  never overwrites mutable Project authoring fields.
+
+## Required provider routes
+
+```text
+GET  /v1/training/capabilities
+POST /v1/training/jobs
+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}/outputs
+
+PUT  /v1/model-projects/{portableProjectId}
+GET  /v1/model-projects
+GET  /v1/model-projects/{projectId}
+```
+
+Every route is authenticated and team-scoped. The provider stores the exact
+portable Project ID, source revision/hash, Harness/Taskset/Dataset refs,
+submission hash, and approval/budget facts. It resolves those public facts to
+private execution state only after validation and admission.
+
+`GET /outputs` returns `openpond.trainingJobOutputs.v2`, containing immutable
+output refs and a provider-issued execution receipt. The receipt binds the
+submission, manifest, recipe, capability document, runtime release, all input
+and output hashes, duration, spend, issuer, and cleanup result. It attests to
+execution and artifact bytes; OpenPond remains responsible for evaluation,
+qualification, selection, promotion, rejection, and rollback semantics.
+
+## Conformance
+
+Published fixtures live in `fixtures/training/v2`. Providers should:
+
+1. validate `policy-optimize.valid.json` with
+   `parseAndVerifyTrainingJobSubmission`;
+2. reject the published unknown-field mutation;
+3. run the same fixtures through their HTTP admission adapter;
+4. prove authorization, idempotency, stale-version control, terminal outputs,
+   receipt verification, and cleanup in provider-local tests;
+5. compare V1 and V2 only at projection/admission time until a bounded V2
+   canary is explicitly approved—never launch duplicate paid Jobs.
+
+The package's `check` command validates schemas, fixtures, canonical hashes,
+the built entry points, and a clean npm-style consumer install.

package/dist/index.js

@@ -2687,13 +2687,13 @@ function requiredId(value, label) {
   return normalized;
 }
 
-// ../harness/dist/refiner.js
+// ../../node_modules/.pnpm/@openpond+harness@0.2.5/node_modules/@openpond/harness/dist/refiner.js
 import { z as z3 } from "zod";
 
-// ../harness/dist/common.js
+// ../../node_modules/.pnpm/@openpond+harness@0.2.5/node_modules/@openpond/harness/dist/common.js
 import { z } from "zod";
 
-// ../harness/dist/sha256.js
+// ../../node_modules/.pnpm/@openpond+harness@0.2.5/node_modules/@openpond/harness/dist/sha256.js
 var INITIAL_STATE = new Uint32Array([
   1779033703,
   3144134277,
@@ -2832,7 +2832,7 @@ function rotateRight(value, bits) {
   return value >>> bits | value << 32 - bits;
 }
 
-// ../harness/dist/common.js
+// ../../node_modules/.pnpm/@openpond+harness@0.2.5/node_modules/@openpond/harness/dist/common.js
 var MAX_PORTABLE_PATH_BYTES = 2e3;
 var MAX_PORTABLE_ASSET_BYTES = 25e7;
 var ReleaseIdSchema = z.string().trim().min(1).max(240);
@@ -2889,7 +2889,7 @@ function sortValue(value) {
   return Object.fromEntries(Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, child]) => [key, sortValue(child)]));
 }
 
-// ../harness/dist/refiner-profiles.js
+// ../../node_modules/.pnpm/@openpond+harness@0.2.5/node_modules/@openpond/harness/dist/refiner-profiles.js
 import { z as z2 } from "zod";
 var RefinerProposalRouteSchema = z2.enum(["memory", "prompt", "skill", "agent"]);
 var RefinerExternalRouteSchema = z2.enum(["runtime", "product", "taskset", "training"]);
@@ -2998,7 +2998,7 @@ function serializeReviewProfile(profile) {
   return canonicalJson(RefinerReviewProfileSchema.parse(profile));
 }
 
-// ../harness/dist/refiner.js
+// ../../node_modules/.pnpm/@openpond+harness@0.2.5/node_modules/@openpond/harness/dist/refiner.js
 var RefinerNoActionDecisionSchema = z3.object({
   schemaVersion: z3.literal("openpond.localHarnessRefinerDecision.v1"),
   decision: z3.literal("no_action"),