@openpond/harness 0.1.0

package/CONTRACT.md

@@ -0,0 +1,31 @@
+# Harness package boundary
+
+`@openpond/harness` owns portable, host-neutral Harness identities and state
+transitions. Host applications own persistence, model streaming, provider
+sessions, authorization, credential leases, local processes, and artifact
+bytes.
+
+## Dependency direction
+
+`@openpond/evals` may depend on and re-export `@openpond/harness`.
+`@openpond/harness` must never import `@openpond/evals` or an application
+package. This keeps Harness releases usable without installing an evaluation
+runner.
+
+## Compatibility
+
+- Package semver and schema-version literals are independent.
+- Immutable content never contains secrets, mutable database identifiers,
+  provider handles, UI state, or process handles.
+- Changing a required field or content-hash identity requires a new schema
+  literal or an explicit normalizer.
+- The initial support target is Node.js ESM on Node 22.14 through Node 24.
+- Portable paths are at most 2,000 characters and individual portable assets
+  are at most 250 MB.
+
+## Runtime ownership
+
+The package describes Agent snapshots, releases, workspaces, overlays,
+improvement evidence, tools, model identities, and traces. Evaluation execution
+interfaces that bind a Harness to a Taskset and emit attempt receipts belong to
+`@openpond/evals`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenPond
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# `@openpond/harness`
+
+Portable contracts and pure helpers for OpenPond's mutable Harness:
+
+- immutable Agent snapshots and Harness releases;
+- content-addressed assets, artifacts, releases, and hashes;
+- tool declarations and model identities;
+- Harness workspaces, pinned run overlays, proposals, validation, advancement,
+  rollback, and merge receipts;
+- improvement observations, Refiner outcomes, and apply receipts;
+- model actions, tool observations, lifecycle events, and Harness traces.
+
+```ts
+import {
+  HarnessReleaseSchema,
+  HarnessRunOverlaySchema,
+  ImprovementObservationSchema,
+  contentHash,
+} from "@openpond/harness";
+```
+
+Subpath exports are available at `/harness`, `/harness-improvements`,
+`/harness-workspaces`, `/models`, and `/tools`.
+
+This package does not run evaluations, grade outputs, persist product state,
+execute a desktop or hosted session, or resolve credentials. Evaluation
+Tasksets, runners, receipts, graders, and Work-evidence eligibility live in
+`@openpond/evals`, which depends on this package.
+
+## Verification
+
+```bash
+pnpm --dir packages/harness run check
+```
+
+The check typechecks, tests, builds, scans the public dependency boundary,
+installs the packed tarball into a clean consumer, verifies runtime and
+TypeScript imports, and dry-run packs the public artifact.

package/RELEASING.md

@@ -0,0 +1,44 @@
+# Releasing `@openpond/harness`
+
+The package version is independent from OpenPond application and schema
+versions. Version `0.1.0` is the initial public Harness release and supports
+these initial schema literals:
+
+- `openpond.agentSnapshot.v2`
+- `openpond.harnessRelease.v2`
+- `openpond.harnessTrace.v1`
+
+## Trusted publishing
+
+This package name is not published yet. Its first publication is a one-time npm
+bootstrap after the Local branch is accepted and merged. The automated workflow
+intentionally refuses to publish until the npm package exists. Complete the
+organization's bootstrap procedure, configure `release-harness.yml` as
+the trusted publisher, and verify package integrity and provenance before using
+the normal release helper below. Do not bootstrap from a local feature branch.
+
+To inspect an already-published version:
+
+```bash
+pnpm harness:check
+npm trust list @openpond/harness
+npm view @openpond/harness version dist.integrity dist.attestations
+```
+
+## Later releases
+
+For releases that do not already carry an intentional version bump, merge
+feature work without changing the package version. When the intended package
+changes are on `master`, prepare a separate release from a clean current
+`master` checkout:
+
+```bash
+pnpm release:harness:patch
+# or release:harness:minor / release:harness:major
+```
+
+The release helper creates a Harness-only release PR and updates the package
+version and lockfile. Merging it triggers trusted publishing with provenance,
+registry verification, and a package-specific tag. Record the registry
+integrity/provenance evidence and merge commit in the release notes after
+publication.

package/dist/common.js

@@ -0,0 +1,67 @@
+import { z } from "zod";
+import { sha256Hex } from "./sha256.js";
+export const MAX_PORTABLE_PATH_BYTES = 2_000;
+export const MAX_PORTABLE_ASSET_BYTES = 250_000_000;
+export const ReleaseIdSchema = z.string().trim().min(1).max(240);
+export const ReleaseHashSchema = z.string().regex(/^[a-f0-9]{64}$/);
+export const ReleaseTimestampSchema = z.string().datetime({ offset: true });
+export const MetadataSchema = z.record(z.string(), z.unknown()).default({});
+export const ImmutableReleaseRefSchema = z.object({
+    id: ReleaseIdSchema,
+    contentHash: ReleaseHashSchema,
+}).strict();
+export const ImmutableAssetRefSchema = z.object({
+    id: ReleaseIdSchema,
+    path: z.string().trim().min(1).max(MAX_PORTABLE_PATH_BYTES).refine(safeRelativePath),
+    contentHash: ReleaseHashSchema,
+    sizeBytes: z.number().int().nonnegative().max(MAX_PORTABLE_ASSET_BYTES),
+    mediaType: z.string().trim().min(1).max(200),
+    visibility: z.enum(["policy", "verifier", "host_private"]),
+}).strict();
+export const ImmutableArtifactRefSchema = z.object({
+    id: ReleaseIdSchema,
+    contentHash: ReleaseHashSchema,
+    mediaType: z.string().trim().min(1).max(200).nullable().default(null),
+    sizeBytes: z.number().int().nonnegative().max(MAX_PORTABLE_ASSET_BYTES).nullable().default(null),
+}).strict();
+export const FailureClassSchema = z.enum([
+    "policy_failure",
+    "grader_failure",
+    "environment_failure",
+    "infrastructure_failure",
+    "timeout",
+    "cancelled",
+]);
+export function canonicalJson(value) {
+    return `${JSON.stringify(sortValue(value), null, 2)}\n`;
+}
+export function sha256(value) {
+    return sha256Hex(value);
+}
+export function contentHash(value) {
+    return sha256(canonicalJson(value));
+}
+export function withContentHash(value) {
+    return { ...value, contentHash: contentHash(value) };
+}
+export function assertContentHash(value, label) {
+    const { contentHash: actual, ...hashable } = value;
+    const expected = contentHash(hashable);
+    if (actual !== expected)
+        throw new Error(`${label} contentHash is ${actual}; expected ${expected}.`);
+}
+function safeRelativePath(value) {
+    const normalized = value.replaceAll("\\", "/");
+    if (!normalized || normalized.startsWith("/") || normalized.includes("\0"))
+        return false;
+    return !normalized.split("/").some((part) => !part || part === "." || part === "..");
+}
+function sortValue(value) {
+    if (Array.isArray(value))
+        return value.map(sortValue);
+    if (!value || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, child]) => [key, sortValue(child)]));
+}

package/dist/harness-improvements.js

@@ -0,0 +1,331 @@
+import { z } from "zod";
+import { HarnessImprovementRouteSchema, HarnessOverlaySnapshotRefSchema, } from "./harness-workspaces.js";
+import { contentHash, ImmutableReleaseRefSchema, ReleaseHashSchema, ReleaseIdSchema, ReleaseTimestampSchema, } from "./common.js";
+const BoundedTextSchema = z.string().trim().min(1).max(100_000);
+const MetadataSchema = z.record(z.string(), z.unknown()).default({});
+export const ImprovementSafeBoundaryKindSchema = z.enum([
+    "completed_tool_batch",
+    "before_model_step",
+    "turn_completed",
+    "turn_paused",
+]);
+export const ImprovementSafeBoundarySchema = z
+    .object({
+    kind: ImprovementSafeBoundaryKindSchema,
+    eventSequence: z.number().int().nonnegative(),
+    occurredAt: ReleaseTimestampSchema,
+})
+    .strict();
+export const ImprovementEventRefSchema = z
+    .object({
+    id: ReleaseIdSchema,
+    sequence: z.number().int().nonnegative().nullable(),
+    contentHash: ReleaseHashSchema,
+})
+    .strict();
+export const ImprovementObservationKindSchema = z.enum([
+    "tool_failure",
+    "retry",
+    "recovery",
+    "validation",
+    "user_turn",
+    "reusable_success",
+    "completion_detour",
+]);
+export const ImprovementObservationStateSchema = z.enum([
+    "open",
+    "recovered",
+    "terminal",
+]);
+export const ImprovementToolIdentitySchema = z
+    .object({
+    name: z.string().trim().min(1).max(500),
+    invocationKey: ReleaseHashSchema,
+})
+    .strict();
+export const ImprovementObservationContentSchema = z
+    .object({
+    schemaVersion: z.literal("openpond.improvementObservation.v1"),
+    id: ReleaseIdSchema,
+    runRef: ReleaseIdSchema,
+    turnId: ReleaseIdSchema,
+    harnessRelease: ImmutableReleaseRefSchema,
+    overlay: HarnessOverlaySnapshotRefSchema.nullable(),
+    eventRefs: z.array(ImprovementEventRefSchema).min(1).max(100),
+    kind: ImprovementObservationKindSchema,
+    state: ImprovementObservationStateSchema,
+    tool: ImprovementToolIdentitySchema.nullable(),
+    deterministicClass: z.string().trim().min(1).max(500).nullable(),
+    summary: BoundedTextSchema,
+    createdAt: ReleaseTimestampSchema,
+    metadata: MetadataSchema,
+})
+    .strict()
+    .superRefine((observation, context) => {
+    if (new Set(observation.eventRefs.map((reference) => reference.id)).size !==
+        observation.eventRefs.length) {
+        context.addIssue({
+            code: "custom",
+            message: "observation event refs must be unique",
+            path: ["eventRefs"],
+        });
+    }
+    if (["tool_failure", "retry", "recovery", "completion_detour"].includes(observation.kind) &&
+        observation.tool === null) {
+        context.addIssue({
+            code: "custom",
+            message: `${observation.kind} observations require a tool identity`,
+            path: ["tool"],
+        });
+    }
+});
+export const ImprovementObservationSchema = ImprovementObservationContentSchema.extend({
+    contentHash: ReleaseHashSchema,
+}).strict();
+export const RefinementTriggerPolicySchema = z
+    .object({
+    schemaVersion: z.literal("openpond.refinementTriggerPolicy.v1"),
+    maxEstimatedCostUsd: z.number().finite().nonnegative(),
+    cooldownMs: z.number().int().nonnegative(),
+    maxPendingPlans: z.number().int().min(1).max(100),
+    maxEvidenceEvents: z.number().int().min(1).max(1_000),
+    maxProposalEdits: z.number().int().min(1).max(1_000),
+    maxProposalBytes: z.number().int().min(1).max(10_000_000),
+})
+    .strict();
+export const RefinementTriggerDecisionKindSchema = z.enum([
+    "no_action",
+    "route_deterministically",
+    "queue_refiner",
+]);
+export const RefinementTriggerDecisionContentSchema = z
+    .object({
+    schemaVersion: z.literal("openpond.refinementTriggerDecision.v1"),
+    id: ReleaseIdSchema,
+    runRef: ReleaseIdSchema,
+    turnId: ReleaseIdSchema,
+    harnessRelease: ImmutableReleaseRefSchema,
+    overlay: HarnessOverlaySnapshotRefSchema.nullable(),
+    observations: z.array(ImmutableReleaseRefSchema).max(100),
+    decision: RefinementTriggerDecisionKindSchema,
+    deterministicRoute: HarnessImprovementRouteSchema.nullable(),
+    suggestedRoutes: z.array(HarnessImprovementRouteSchema).max(8),
+    reason: BoundedTextSchema,
+    deduplicationKey: ReleaseHashSchema,
+    policy: RefinementTriggerPolicySchema,
+    estimatedMaxCostUsd: z.number().finite().nonnegative(),
+    pendingPlanCount: z.number().int().nonnegative(),
+    boundary: ImprovementSafeBoundarySchema,
+    cooldownUntil: ReleaseTimestampSchema.nullable(),
+    createdAt: ReleaseTimestampSchema,
+    metadata: MetadataSchema,
+})
+    .strict()
+    .superRefine((trigger, context) => {
+    if (trigger.estimatedMaxCostUsd > trigger.policy.maxEstimatedCostUsd) {
+        context.addIssue({
+            code: "custom",
+            message: "estimated Refiner cost exceeds the trigger policy budget",
+            path: ["estimatedMaxCostUsd"],
+        });
+    }
+    if (trigger.pendingPlanCount > trigger.policy.maxPendingPlans) {
+        context.addIssue({
+            code: "custom",
+            message: "pending plan count exceeds the trigger policy limit",
+            path: ["pendingPlanCount"],
+        });
+    }
+    if (trigger.observations.length > trigger.policy.maxEvidenceEvents) {
+        context.addIssue({
+            code: "custom",
+            message: "trigger observations exceed the evidence budget",
+            path: ["observations"],
+        });
+    }
+    if (trigger.decision === "route_deterministically" &&
+        trigger.deterministicRoute === null) {
+        context.addIssue({
+            code: "custom",
+            message: "deterministic decisions require a route",
+            path: ["deterministicRoute"],
+        });
+    }
+    if (trigger.decision !== "route_deterministically" &&
+        trigger.deterministicRoute !== null) {
+        context.addIssue({
+            code: "custom",
+            message: "only deterministic decisions may declare a deterministic route",
+            path: ["deterministicRoute"],
+        });
+    }
+    if (trigger.decision === "no_action" && trigger.suggestedRoutes.length > 0) {
+        context.addIssue({
+            code: "custom",
+            message: "no-action decisions cannot suggest routes",
+            path: ["suggestedRoutes"],
+        });
+    }
+    if (trigger.decision !== "no_action" && trigger.observations.length === 0) {
+        context.addIssue({
+            code: "custom",
+            message: "actionable trigger decisions require observations",
+            path: ["observations"],
+        });
+    }
+});
+export const RefinementTriggerDecisionSchema = RefinementTriggerDecisionContentSchema.extend({
+    contentHash: ReleaseHashSchema,
+}).strict();
+export const ImprovementRouteAuthoritySchema = z.enum([
+    "runtime_service",
+    "refiner_model",
+    "human_review",
+    "evaluation_system",
+    "training_system",
+]);
+export const ImprovementRouteDecisionContentSchema = z
+    .object({
+    schemaVersion: z.literal("openpond.improvementRouteDecision.v1"),
+    id: ReleaseIdSchema,
+    trigger: ImmutableReleaseRefSchema,
+    route: HarnessImprovementRouteSchema,
+    authority: ImprovementRouteAuthoritySchema,
+    automatic: z.boolean(),
+    reason: BoundedTextSchema,
+    createdAt: ReleaseTimestampSchema,
+    metadata: MetadataSchema,
+})
+    .strict()
+    .superRefine((decision, context) => {
+    if (decision.automatic &&
+        ["human_review", "evaluation_system", "training_system"].includes(decision.authority)) {
+        context.addIssue({
+            code: "custom",
+            message: `${decision.authority} routes cannot be marked automatic`,
+            path: ["automatic"],
+        });
+    }
+    if (decision.route === "training" &&
+        decision.automatic &&
+        decision.authority !== "training_system") {
+        context.addIssue({
+            code: "custom",
+            message: "automatic training routes require training-system authority",
+            path: ["authority"],
+        });
+    }
+});
+export const ImprovementRouteDecisionSchema = ImprovementRouteDecisionContentSchema.extend({
+    contentHash: ReleaseHashSchema,
+}).strict();
+export const HarnessRefinerOutcomeContentSchema = z
+    .object({
+    schemaVersion: z.literal("openpond.harnessRefinerOutcome.v1"),
+    id: ReleaseIdSchema,
+    trigger: ImmutableReleaseRefSchema,
+    decision: z.enum(["no_action", "proposed"]),
+    proposal: ImmutableReleaseRefSchema.nullable(),
+    reason: BoundedTextSchema,
+    evidenceRefs: z.array(ImmutableReleaseRefSchema).max(100),
+    estimatedCostUsd: z.number().finite().nonnegative(),
+    createdAt: ReleaseTimestampSchema,
+    metadata: MetadataSchema,
+})
+    .strict()
+    .superRefine((outcome, context) => {
+    if ((outcome.decision === "proposed") !== (outcome.proposal !== null)) {
+        context.addIssue({
+            code: "custom",
+            message: "proposed Refiner outcomes require a proposal; no-action outcomes cannot include one",
+            path: ["proposal"],
+        });
+    }
+});
+export const HarnessRefinerOutcomeSchema = HarnessRefinerOutcomeContentSchema.extend({
+    contentHash: ReleaseHashSchema,
+}).strict();
+export const ImprovementApplyDecisionSchema = z.enum([
+    "applied",
+    "retained",
+    "declined",
+    "conflict",
+    "rolled_back",
+]);
+export const ImprovementApplyReceiptContentSchema = z
+    .object({
+    schemaVersion: z.literal("openpond.improvementApplyReceipt.v1"),
+    id: ReleaseIdSchema,
+    proposal: ImmutableReleaseRefSchema,
+    beforeOverlay: HarnessOverlaySnapshotRefSchema,
+    afterOverlay: HarnessOverlaySnapshotRefSchema.nullable(),
+    decision: ImprovementApplyDecisionSchema,
+    boundary: ImprovementSafeBoundarySchema,
+    validationRefs: z.array(ImmutableReleaseRefSchema).max(100),
+    outcomeEvidenceRefs: z.array(ImprovementEventRefSchema).max(1_000),
+    rollbackOf: ImmutableReleaseRefSchema.nullable(),
+    createdAt: ReleaseTimestampSchema,
+    metadata: MetadataSchema,
+})
+    .strict()
+    .superRefine((receipt, context) => {
+    if ((receipt.decision === "applied") !== (receipt.afterOverlay !== null)) {
+        context.addIssue({
+            code: "custom",
+            message: "applied receipts require an after-overlay; other decisions cannot include one",
+            path: ["afterOverlay"],
+        });
+    }
+    if ((receipt.decision === "rolled_back") !== (receipt.rollbackOf !== null)) {
+        context.addIssue({
+            code: "custom",
+            message: "only rollback receipts require rollbackOf",
+            path: ["rollbackOf"],
+        });
+    }
+});
+export const ImprovementApplyReceiptSchema = ImprovementApplyReceiptContentSchema.extend({
+    contentHash: ReleaseHashSchema,
+}).strict();
+function createHashedContract(input) {
+    const parsed = input.contentSchema.parse(input.content);
+    return input.resultSchema.parse({
+        ...parsed,
+        contentHash: contentHash(parsed),
+    });
+}
+export function createImprovementObservation(content) {
+    return createHashedContract({
+        content,
+        contentSchema: ImprovementObservationContentSchema,
+        resultSchema: ImprovementObservationSchema,
+    });
+}
+export function createRefinementTriggerDecision(content) {
+    return createHashedContract({
+        content,
+        contentSchema: RefinementTriggerDecisionContentSchema,
+        resultSchema: RefinementTriggerDecisionSchema,
+    });
+}
+export function createImprovementRouteDecision(content) {
+    return createHashedContract({
+        content,
+        contentSchema: ImprovementRouteDecisionContentSchema,
+        resultSchema: ImprovementRouteDecisionSchema,
+    });
+}
+export function createHarnessRefinerOutcome(content) {
+    return createHashedContract({
+        content,
+        contentSchema: HarnessRefinerOutcomeContentSchema,
+        resultSchema: HarnessRefinerOutcomeSchema,
+    });
+}
+export function createImprovementApplyReceipt(content) {
+    return createHashedContract({
+        content,
+        contentSchema: ImprovementApplyReceiptContentSchema,
+        resultSchema: ImprovementApplyReceiptSchema,
+    });
+}