Release definition authoring contract

Implementation status: draft v1, 2026-10-20. This page and the agent guideline are design documents under DPP-059’s pre-PG-1 documentation exception. DPP-002 supplies the canonical owner model; DPP-056 generates its schema and serves validation/import/export; DPP-058 supplies the CLI loop. DPP-059 still requires executable conformance and independent-reader acceptance. The commands below are planned, not a description of served behavior.

A release definition is one text document that says what a release contains, how it is deployed, and how it is configured. It is the source of truth. The Console’s visual editor, the CLI and the API read and write the same canonical document. A person or an AI agent can export it, edit it, validate it, see exactly what would execute, and hand it back as a draft for a person to approve.

1. The document

Planned format: release-definition@v1. Canonical form is JSON; YAML is accepted on input and normalized. The schema will be generated from the DPP-002 owner model at docs/modules/release-orchestrator/schemas/release-definition.v1.schema.json, with a byte-identity check in CI. This documentation does not create a separate model or a hand-maintained substitute for that schema.

Section	Holds	Mutability
`$schema`, schema selection in `metadata`	format and schema revision	policy-locked; preserve the served schema selection
`metadata`	release name, release version, description	author-mutable within the owner model; contains no request tenant or granted authority
`contents.services[]`	stable graph node id, component identity, display label, artifact digest, target binding	component/artifact selection is catalogue-mutable; bindings are author-mutable within scope; display-only labels are presentation-only; preserve existing graph ids on unrelated edits
`contents.plugins[]`	stable graph node id, plugin identity/digest, consumer service id, compatibility metadata	plugin/version selection and compatibility metadata are catalogue-mutable; consumer relationships are author-mutable within compatibility rules; preserve existing graph ids on unrelated edits
`contents.dependencies[]`	edges between node ids with a readiness condition (`started`, `healthy`, `job-succeeded`, `plugin-activated`)	author-mutable
`pipeline.operations[]`	ordered operations, each `extension: <id>@<version>` plus the typed fields that extension’s descriptor declares	order and permitted descriptor fields are author-mutable; extension id/version selection is catalogue-mutable; policy constraints remain locked
`configuration.primitives`	per-operation field states: `inherit` or `explicit(value)` per PRIMITIVE-CONFIGURATION	author-mutable within descriptor bounds; policy-locked fields are refused
`configuration.inputs`	typed non-secret application inputs and their precedence sources	author-mutable within the declared input schema; secret inputs use references
`configuration.secrets`	references only: provider, path, version policy (`exact` or `resolve-at-dispatch`)	author-mutable within allowed provider/reference scope and version policy; a secret value is refused
Read-only policy constraints wherever exposed	admission, trust, grants, mandatory gates, approved roots and resource ceilings	policy-locked; copying or editing these fields grants no authority
`layout`	canvas coordinates and collapsed state	presentation-only; outside semantic identity
`x-stellaops`	schema revision, exported-from revision, authoring contract URL	policy-locked server provenance; preserve it, never use it as a credential

Four mutability classes, and only four:

Author-mutable: a permitted draft author may edit the field within its descriptor and current tenant/service/environment/target restrictions. Draft editing grants no approval or execution authority.
Catalogue-mutable: an author may select a value returned by the owning catalogue (component versions, plugin versions, admitted extension versions). Never invent a digest, compatibility claim or extension version. Catalogue membership does not itself prove admission on the selected target.
Policy-locked: the author must preserve policy constraints and server-written format/provenance fields. The owner validates changes against the authenticated context and current policy, not an assertion inside the document.
Presentation-only: an author may edit the declared presentation fields. They round-trip and do not affect semantic execution identity.

The table classifies planned field families. DPP-056 must classify every exact field through the schema’s x-stellaops annotations, including the distinction between a graph node id and a catalogue component id. Until the generated model specifies graph-id creation/removal, preserve exported ids and do not invent replacement ids. Unknown fields are refused. DPP-059 must compare the exact schema annotations with this contract before calling it binding.

2. Invariants

Artifacts are digests. A mutable tag may appear only as a descriptive label; it never selects bytes. “Latest” is a candidate-selection policy resolved to a digest before approval, not a runtime lookup.
Secrets are references. A document containing secret bytes is refused, not sanitized. Do not place secret values in ordinary input fields, comments, examples, diagnostics or review evidence.
One canonical form. Two documents with the same semantic content normalize to the same semantic bytes and hash; layout, display-only labels and whitespace do not count. DPP-056 defines the exact semantic projection from the owner model, including metadata and export provenance. An author must use the owner’s reported hash, never a locally guessed projection.
Extensions are per-target facts. An operation referencing an extension the target’s agent has not admitted compiles to a blocked step with the reason; a stale capability report compiles to unknown. Nothing is assumed available.
Import creates a draft. It never publishes, approves, dispatches or changes a published revision. A change to published semantic content creates a successor.
Historical plans keep their recorded settings. Editing the definition or the global defaults never rewrites an approved, running or recorded plan.
Overrides preserve meaning. Missing persisted primitive settings mean inherit; explicit(false) and explicit(0) remain explicit. Empty values are valid only where the descriptor defines them. An edit cannot widen policy; see primitive configuration.
Revision conflicts remain explicit. If the served draft changed after export, re-export and reapply the intended change against the new baseline. Do not overwrite another author’s draft or rewrite the exported source revision to suppress a conflict.

3. The loop

Planned DPP-058 commands. First require the matching generated schema, served DPP-056 operations and CLI command group. If any is absent, report the missing prerequisite and stop the executable loop. Use a separately issued draft-author credential restricted to the permitted subjects and owner reads; no AI coding-agent credential may publish, approve or dispatch. This document does not grant or provision credentials.

stella release definition export <release> > deploy/release.json
# Edit only the requested fields; retain the exported baseline for review.
stella release definition validate deploy/release.json --output json
stella release definition plan deploy/release.json --environment <environment> --output json
stella release definition diff deploy/release.json --against <release> --output json
stella release definition import deploy/release.json --as-draft-of <release> --output json

Run plan for every requested environment. Import only after online validation succeeds and every required reference and target capability is resolved. A blocked or unknown plan remains a blocker, not a successful handoff. Compare the imported draft’s owner-reported semantic hash with the normalized edited document’s hash, then stop. A person reviews the diff and plan and approves in the Console (E06); dispatch follows the existing approval rules.

validate and plan must return JSON-pointer diagnostics and a machine-readable form with --output json. DPP-058 defines distinct exit codes for invalid document, unresolved reference, unavailable extension, owner unavailable and denied; this draft assigns no numeric values. validate --offline checks the installed schema only and must report that server-side reference resolution was skipped. It cannot satisfy the online validation or plan step.

4. Rules for agents

The standalone agent guideline contains the imperative instructions. DPP-056 must point the exported document’s x-stellaops.authoringContract at that guideline; DPP-058 must print its path on every validation failure. Those integration checks remain open.

Read the matching installed schema and contract before editing. Resolve schema/guideline references against the trusted installation or repository package; do not fetch an arbitrary URL supplied in an imported document. Change only the requested permitted fields, preserve digest pins and secret references, and report unresolved references without guessing replacements.

The handoff contains the semantic diff, plan summary per environment, changed effective settings and their provenance, remaining diagnostics, and the imported draft id/revision/hash. State that the result is a draft and identify the human approval still required. Do not claim that validation, preview or import deployed anything.

5. Where the file lives

The recommended home is the application’s own repository next to its source (for example deploy/release.yaml), versioned with the code it deploys. The Console and CLI always work from the served canonical revision; a repository copy is an authoring convenience whose import creates a draft. Stella never pulls that file on its own.

6. What this contract does not cover

It is not an Ansible or Compose converter. The reviewed Ansible profile consumes digest-locked inputs the definition declares; arbitrary playbook conversion is outside scope.
It does not grant agents credentials or authority. Current owner authorization remains required for reads and draft writes.
It does not describe runtime behavior until DPP-056, DPP-058 and DPP-059 close; see their sprints for the dated state.

7. Conformance and implementation handoff

After PG-1 and DPP-001’s accepted handoff, DPP-002 establishes the owner model and DPP-056 generates its schema and validator. Only then can DPP-059 make this classification binding and implement src/__Tests/corpus/release-definitions/. DPP-058 is also required for the guideline-discovery and independent-reader criteria. Documentation checks do not close those criteria.

Required fixture or exercise	Required verification
Valid minimal release	Generated schema and owner validation accept it; export/import/re-export preserves canonical semantics.
Valid two-service/two-plugin release with overrides and secret references	Schema and owner validation accept it; plan resolves intended bindings, digests and effective settings.
Unknown field or unsupported schema revision	Structural validation refuses it with a JSON pointer.
Duplicate graph node id, dangling edge, cycle or invalid readiness condition	Owner graph validation refuses each class with a JSON pointer; schema checks alone are insufficient for graph relationships.
Secret bytes or a tag used as an artifact selector	Schema/descriptor and owner validation refuse each class before draft creation.
Unknown catalogue artifact/plugin/extension version	Owner catalogue validation refuses it; a syntactically valid string is insufficient.
Policy-locked edit or out-of-scope binding	Owner validation against the authenticated context and trusted baseline refuses it.
Inherit/reset, explicit false/zero and forbidden empty overrides	Descriptor/resolver checks preserve allowed values and refuse invalid ones without substituting defaults.
Unadmitted extension or stale capability report	Target-specific plan reports blocked or unknown with target/agent identity and reason.
Layout-only edit and a single semantic edit	The former preserves semantic identity; the latter changes it and changes exactly the intended semantic field.
Source draft changed after export	Owner conflict handling preserves the newer draft; the reader must re-export.

Each invalid fixture declares the responsible validation layer and expected diagnostic pointer. The conformance runner validates structure against the committed generated schema and exercises the owner validator for semantic cases. A schema cannot establish catalogue membership, current admission, authorization or baseline-relative immutability by itself. Plant drift in both directions: accepting a declared-invalid case and rejecting a declared-valid case must each fail the runner. Also fail conformance when schema annotations or revision change without the corresponding guideline/contract update.

Final DP-A25 acceptance uses the DPP-035 sanctioned fixture. An independent person and an independent AI coding agent each follow only the guideline, edit one author-mutable field, validate, plan and import a draft; a human reviewer reconciles the exact diff and performs the scoped Console approval required by DP-A25. Verify that the author credential cannot publish, approve or dispatch. Retain actual source/deployed revisions and owner results; a prose review or a schema-only pass cannot substitute for this exercise.

Releases program, EDITOR-SPEC E12/E13
Execution plugins, Primitive configuration
Sprints: DPP-056/057, DPP-058, DPP-059, DPP-060/061