Contract shapes

Fleet uses separate contracts for editable authoring input, immutable content, and Runtime records. The word “TaskSet” appears in all three layers, but the shapes are not interchangeable.

Registry content names its generation with schema; Runtime contracts use schema_version. The generated document's $schema field only identifies the JSON Schema dialect.

Compilation lowers authored input into immutable Fleet content. At execution time, Runtime combines selected content with a RunConfig, records the resolved ExecutionPlan, appends ATOF events, seals a deterministic TraceLog projection, and produces separate immutable verification records.

RunConfig can choose occupant harnesses and models, roster occupancy, completion behavior, tool narrowing, and retry-related options. It cannot replace Task-owned prompts, Environments, Artifacts, captures, or Verifiers. Provider bindings belong to the enclosing Run specification and are recorded in the ExecutionPlan.

The IDs below are the latest supported document generations, not the version every compile writes. The compiler selects compatible Task and TaskSet generations from the content and Task count, then records one closure-wide task_generation that tells readers how to interpret every Task.

Task v1alpha10 adds the opt-in, final-only fs-snapshot.v1capture for a bounded complete filesystem tree. Existing fs-diff.v1captures and older Task generations keep their prior meaning and bytes.

TaskSet, Environment, and Artifact are Rootable and may receive independent Registry Names and tags. A Task is selected from a TaskSet by Task key; it also has a canonical manifest digest and may be a metadata subject, but it cannot receive an independent Registry Name, tag, publication path, or access policy. The Task key behaves like a path in a tree and is not a field of Task content. Prompts, seed-mount declarations, and Verifiers are not independently Rootable.

Standalone Environment YAML compiles into a Rootable Environment. Separately, flt compile-verifier compiles one authored Verifier node and its referenced blobs for re-verification; that Verifier document is not a Registry Root. fleet.lock.v2 is a non-content construction sidecar that expands authored builtin Environments such as terminal@v1 into pinned image IDs, endpoints, and native tool names. Direct image_ref values must already be either a bare sha256:<64-hex> image ID or a named repository@sha256:<64-hex> reference. Fleet deliberately has no general raw-file or directory-to-Artifact authoring shape.

The Runtime CLI exposes ten Draft 2020-12 JSON Schema roots. These are normalized Runtime contracts, not authoring schemas or Registry HTTP envelopes.

fleet-runtime contracts schema taskset
fleet-runtime contracts schema execution_plan
fleet-runtime contracts schema verification_node_result
fleet-runtime contracts schema verification_run

Replace the final name with any row above. Use the installed Runtime version's output for shape discovery and editor tooling for that release, not as an acceptance or rejection oracle.

A Task owns a forest of recursive Verifier nodes. An evaluator leaf runs one declared evaluator against its declared evidence and target access, then applies its decision. Evidence inputs, when declared, select sealed evidence. A composite evaluates child edges, aggregates their scores with weighted_sum, min, all_of, or pinned code, then applies its own decision.

verifiers:
  - id: overall
    type: composite
    children:
      - id: answer
        node:
          id: answer
          type: evaluator
          evaluator:
            kind: builtin.v1
            builtin_id: answer-equals
            params: {expected: "42"}
          evidence:
            inputs:
              - name: submission
                select: {source: submission}
                cardinality: one
                required: true
                expose: {as: ctx}
          target_access: {mode: none, bindings: []}
          metrics:
            - name: answer
              type: decimal
              bounds: {minimum: "0", maximum: "1"}
          objective: {metric: answer, reducer: last}
          decision: {kind: threshold, at_least: "1"}
    aggregation: {kind: all_of, on_child_error: propagate}
    decision: {kind: threshold, at_least: "1"}

Sibling edge IDs are unique. weighted_sum requires every weight and an exact sum of 1; min and all_of forbid weights, and all_of requires a threshold of 1. Trees are limited to 32 levels and 1,000 nodes. Evidence selection, grading subject, target access, bindings, and failure policy are independent parts of the declaration.

verification_node_result mirrors the declaration tree. Each node records its identity, type, execution status, projection status, nullable score and cause, typed facts, explanation, artifacts, effective policy, children, and grading subject. Every child grades the same subject as its parent.

The compact example below shows a completed evaluator whose declared projection produced no score, recorded as unscorable with cause empty. When a metric-bound evaluator completes with a valid readings document, its typed observations appear in facts; a completed measurement-only evaluator has no projection status. Legacy scalar leaves and composite nodes can have empty facts even when scored.

{
  "node_id": "answer",
  "node_digest": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
  "type": "evaluator",
  "kind": "builtin.v1",
  "status": "completed",
  "projection_status": "unscorable",
  "score": null,
  "cause": "empty",
  "facts": [],
  "explanation": "No score was produced.",
  "judge": null,
  "artifacts": [],
  "effective_policy": {
    "decision": {
      "kind": "threshold",
      "at_least": "1",
      "schema_version": "fleet.decision.v1alpha1"
    }
  },
  "children": [],
  "subject": {
    "kind": "attempt",
    "schema_version": "fleet.grading_subject.v1alpha1"
  },
  "schema_version": "fleet.verification_node_result.v1alpha1"
}

The all-zero digest above is an illustrative placeholder. A real result carries the exact digest of the Verifier node that produced it.

verification_run binds one result or execution failure to the exact Attempt, Task, plan, evidence, Verifier, and subject, with the RunConfig digest carried where that identity is available. Re-verification appends another immutable run; supersedes links lineage without rewriting the prior result. A referenced verification_transcript is the applicable grader's audit trail, not the rollout agent's transcript.

Authoring, TaskSet, Task, Environment, Artifact, and Runtime-record versions advance independently. minimum_task_generation is a floor the compiler resolves for the complete closure, not a request to pin every document to one displayed version. Older immutable bytes keep their original identities and remain read through explicit compatibility rules.

This reference deliberately excludes worker leases and fencing, credential leases, Run-store database rows, pools, provisioning, OCI descriptors, and Cloud Runner state. Those are internal or operator contracts. Continue with verification concepts, traces and evidence,scores and metrics, or the Runtime CLI reference for the surrounding workflows.