deploy

Documentation

Overview

Package deploy builds and hydrates immutable, content-addressed deployment snapshots (issue #207, design doc §14). A snapshot roots the resolved configuration a run executes under — the resolved graph (policy, tools, agents, models) and the capability manifest — so a run can resume under the exact authority it started with, even after an intervening apply. Positions and other diagnostic-only metadata are excluded from artifact payloads (json:"-" on Pos), so two serializations of the same semantic graph with different source positions are byte-identical and share a digest.

Index

• Constants
• Variables
• func BuildAndPersist(ctx context.Context, store state.ArtifactStore, g *spec.ProjectGraph, ...) (digest string, warnings []string, err error)
• func CollectSchemas(g *spec.ProjectGraph, projectRoot string) (map[string]string, []string, error)
• func MarkSupersededRuns(ctx context.Context, store state.ArtifactStore, records []statejson.RunRecord)
• func MarshalGraph(g *spec.ProjectGraph) ([]byte, error)
• func MarshalManifest(g *spec.ProjectGraph) ([]byte, error)
• func MarshalSchemaBundle(schemas map[string]string) ([]byte, error)
• func Persist(ctx context.Context, store state.ArtifactStore, b Built) (string, error)
• func ScanLiteralSecrets(g *spec.ProjectGraph) []string
• func UnmarshalGraph(payload []byte) (*spec.ProjectGraph, error)
• func UnmarshalSchemaBundle(payload []byte) (map[string]string, error)
• type Built
  • func Build(g *spec.ProjectGraph, environment, compilerVersion string, ...) (Built, error)
• type Hydrated
  • func HydrateGraph(ctx context.Context, store state.ArtifactStore, snapshotDigest string) (*Hydrated, error)

Constants

const (
	FormatSnapshotV1     = "agentic.dev/snapshot/v1"
	FormatGraphV1        = "agentic.dev/graph/v1"
	FormatManifestV1     = "agentic.dev/manifest/v1"
	FormatSchemaBundleV1 = "agentic.dev/schemabundle/v1"
)

Format versions. FormatVersion says how to decode a payload; an unknown value must fail loudly rather than be reinterpreted. Bump when a payload's encoding changes incompatibly.

Variables

var ErrUnsupportedFormat = errors.New("deploy: unsupported artifact format version")

ErrUnsupportedFormat is returned when an artifact or snapshot format_version is not decodable by this runtime. Never reinterpret an unknown format.

Functions

func BuildAndPersist

func BuildAndPersist(ctx context.Context, store state.ArtifactStore, g *spec.ProjectGraph, environment, compilerVersion, projectRoot string) (digest string, warnings []string, err error)

BuildAndPersist collects schemas under projectRoot, builds the snapshot for g, and persists it, returning the snapshot digest and any warnings. Both run-start pinning and apply use this. An empty projectRoot skips schema capture (no schemas pinned).

func CollectSchemas

func CollectSchemas(g *spec.ProjectGraph, projectRoot string) (map[string]string, []string, error)

CollectSchemas reads every JSON Schema file the graph references (workflow input, agent input and output) and returns a map keyed by the raw schema ref string (as the engine looks it up at validation time) to file content. This is authoring-time I/O (apply / run-start), where reading project files is legitimate; the captured content is pinned into the deployment snapshot so a resumed run validates against the schema it started with, never a re-read of a changed file (ADR 001 / issue #207). A referenced file that is missing or unreadable is skipped with a warning (schemas are gradual — absent means allowed), never fatal.

func MarkSupersededRuns

func MarkSupersededRuns(ctx context.Context, store state.ArtifactStore, records []statejson.RunRecord)

MarkSupersededRuns flags run records that are executing a deployment snapshot no longer current for their environment (issue #207): an apply has landed since the run started. It resolves the latest snapshot per distinct environment once, then delegates to statejson.MarkSuperseded. A nil store or a lookup error leaves records unmarked (advisory, never fatal).

func MarshalGraph

func MarshalGraph(g *spec.ProjectGraph) ([]byte, error)

MarshalGraph returns the canonical payload for a resolved graph artifact. Source positions are json:"-" and so excluded; Imports (a loading detail, not runtime identity) are cleared so the same semantic graph serializes identically regardless of file layout.

func MarshalManifest

func MarshalManifest(g *spec.ProjectGraph) ([]byte, error)

MarshalManifest returns the canonical payload for the capability-manifest artifact: every Tool's derived manifest, sorted by tool name. This is a projection of the graph, retained separately so the pinned authority boundary is independently auditable.

func MarshalSchemaBundle

func MarshalSchemaBundle(schemas map[string]string) ([]byte, error)

MarshalSchemaBundle returns the canonical payload for the schema-bundle artifact: the ref→content map as JSON with sorted keys (encoding/json sorts map keys), so identical bundles dedupe.

func Persist

func Persist(ctx context.Context, store state.ArtifactStore, b Built) (string, error)

Persist writes a built snapshot and its artifacts, deduped by content, and returns the snapshot digest. Re-persisting an identical snapshot is a no-op (content-addressed, immutable).

func ScanLiteralSecrets

func ScanLiteralSecrets(g *spec.ProjectGraph) []string

ScanLiteralSecrets reports header values that look like an inlined literal secret in a snapshot-persisted field (ToolHTTP.Headers, ToolMCP.Headers). Snapshots are immutable and retained forever, so a literal secret becomes a permanent record. The convention is env: token references, which are resolved at request time and therefore safe to persist verbatim; a non-env: value on a sensitive header is flagged so the author can switch to a reference. Values are never rewritten or redacted (that would make the snapshot unusable for resume).

func UnmarshalGraph

func UnmarshalGraph(payload []byte) (*spec.ProjectGraph, error)

UnmarshalGraph decodes a resolved-graph payload back into a ProjectGraph for resume. Diagnostic fields (positions, compiled schema docs) are not reconstructed; they are not runtime authority.

func UnmarshalSchemaBundle

func UnmarshalSchemaBundle(payload []byte) (map[string]string, error)

UnmarshalSchemaBundle decodes a schema-bundle payload into the ref→content map.

Types

type Built

type Built struct {
	Snapshot  state.DeploymentSnapshot
	Artifacts []state.DeploymentArtifact
	Warnings  []string
}

Built is the result of building a snapshot: the snapshot row plus the artifacts it references, ready to persist, and any advisory warnings (e.g. literal secrets in snapshot-persisted fields).

func Build

func Build(g *spec.ProjectGraph, environment, compilerVersion string, schemas map[string]string) (Built, error)

Build assembles the deployment snapshot and its artifacts for a resolved graph. It is pure (no I/O): callers collect schemas with CollectSchemas (authoring-time I/O) and pass them here. compilerVersion is provenance for the compilation as a whole.

type Hydrated

type Hydrated struct {
	Graph    *spec.ProjectGraph
	Snapshot *state.DeploymentSnapshot
	// Schemas maps a schema ref (as the engine looks it up) to the JSON Schema content captured at
	// run start. A pinned resume validates against these rather than re-reading files on disk. Nil
	// or empty when the run captured no schemas.
	Schemas map[string]string
}

Hydrated is the configuration reconstructed from a pinned deployment snapshot.

func HydrateGraph

func HydrateGraph(ctx context.Context, store state.ArtifactStore, snapshotDigest string) (*Hydrated, error)

HydrateGraph reconstructs the resolved graph a run pinned at start from its deployment snapshot, checking format versions and failing loudly (never reinterpreting) on an unsupported format. This is how resume obtains authority: from the run's pinned snapshot, not from re-resolved current config, so an intervening apply cannot widen an in-flight run's authority.