authoring

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 16, 2026 License: MIT Imports: 13 Imported by: 0

README

Workflow Authoring Front Ends

authoring is a value-style view over the canonical graph.Graph contract. It does not execute plans or define a second workflow language.

Go callers build an immutable graph and then use the ordinary compiler, dependency inference, validation, definition-resolution, and policy catalogs:

built := authoring.New("release", "v1").
    Authority("project").
    Node(graph.Node{
        ID: "publish", Kind: "http", KindVersion: "v1",
        Effects: graph.EffectSet{graph.EffectMutate},
    })

result := built.Compile(ctx, authoring.CompileOptions{
    Validation: compile.ValidationOptions{StepKinds: kinds},
})

Every builder method returns independently owned graph data. Compile never creates mutable in-flight execution state.

Generated clients

The committed graph schema is the authority for graph DTOs and schema identifiers. A host may use it to generate its transport-specific clients and authoring-envelope preflight. Generated clients should provide equivalents of:

  • createGraphAuthoringEnvelope and createWorkflowSourceAuthoringEnvelope;
  • decodeAuthoringEnvelope, with strict unknown-field, byte, depth, node, edge, and exact schema/version checks;
  • a host-specific client generated from the host's operation map.

Regenerate and verify the engine schema from the repository root:

go generate ./graph
go test ./graph/...

A consuming host is responsible for a byte-for-byte stale-artifact gate for any client it generates.

Agent ingress

A host agent-ingress service should accept a bounded raw authoring.Envelope. It should stage exact material only while its definition resolver validates it, then run contract tests before registry publication. Namespace and definition authorization, step-kind and effects validation, policy hooks, provenance, and exact digests remain mandatory host checks. A request without a contract suite must not mutate the catalog.

Schema identifiers and versions are exact, not negotiated by content sniffing. Legacy registry records with all discriminator fields absent default only to the historical graph-native workflow source contract. A qualified registry name is always <namespace>/<source-local graph ID>; definition resolution removes that single authority namespace before comparing Definition.ID and Graph.ID.

SemanticPlanFingerprint and SemanticPlanDocument exist only for cross-front-end conformance. Runtime ExecutionPlan.Digest and definition digests remain bound to exact source identity.

Documentation

Overview

Package authoring provides immutable views over the canonical workflow graph IR for Go SDKs, UI tools, and agent-produced material. It compiles through workflow/compile and never owns execution or mutable in-flight state.

Index

Constants

View Source 
const (
	// EnvelopeSchemaID is the closed authoring transport contract.
	EnvelopeSchemaID = "https://schemas.hollis-labs.dev/workflow/authoring/v1/envelope.schema.json"
	// EnvelopeSchemaVersion is the compact negotiation version for EnvelopeSchemaID.
	EnvelopeSchemaVersion = "1"
	// WorkflowSourceSchemaID identifies the graph-native YAML source contract.
	WorkflowSourceSchemaID = "https://schemas.hollis-labs.dev/workflow/source/v1/workflow-source"
	// WorkflowSourceSchemaVersion is the supported workflow-source negotiation version.
	WorkflowSourceSchemaVersion = "1"

	FormatGraphIR        MaterialFormat = "graph_ir"
	FormatWorkflowSource MaterialFormat = "workflow_source"

	DefaultMaximumBytes = 2 << 20
	DefaultMaximumDepth = 128
	DefaultMaximumNodes = 512
	DefaultMaximumEdges = 4096

	CodeUnsupportedSchema    diagnostic.Code = "HADR-SOURCE-038"
	CodeInvalidEnvelope      diagnostic.Code = "HADR-SOURCE-039"
	CodeDiagnosticsTruncated diagnostic.Code = "HADR-SOURCE-040"
)

Variables

This section is empty.

Functions

func SourceSchemaFor 

func SourceSchemaFor(format graph.SourceFormat) (id, version string, supported bool)

SourceSchemaFor returns the only accepted material schema for a persisted source discriminator. No caller should infer the format from source bytes.

func ValidatePlanLimits 

func ValidatePlanLimits(plan *compile.ExecutionPlan, limits Limits) []diagnostic.Diagnostic

ValidatePlanLimits applies authoring ingress structural ceilings to the final expanded plan, including bundled child definitions. It does not alter the full compiler diagnostics or execution plan.

Types

type Builder 

type Builder struct {
	// contains filtered or unexported fields
}

Builder is an immutable authoring view over graph.Graph. Every method returns an independently owned value; there is no execution or in-flight plan state.

func New 

func New(id, version string) Builder

New creates an SDK-authored graph with an explicit stable locator.

func (Builder) Authority 

func (b Builder) Authority(value string) Builder

Authority returns a builder with source authority set consistently.

func (Builder) Compile 

func (b Builder) Compile(ctx context.Context, options CompileOptions) Result

Compile delegates to the shared graph compile, dependency inference, and validation path.

func (Builder) Edge 

func (b Builder) Edge(value graph.Edge) Builder

Edge appends one explicit normalized edge.

func (Builder) Envelope 

func (b Builder) Envelope() Envelope

Envelope returns the generated-client transport shape for this graph.

func (Builder) Graph 

func (b Builder) Graph() graph.Graph

Graph returns a defensive copy of the authored canonical IR.

func (Builder) Input 

func (b Builder) Input(value graph.InputSpec) Builder

Input appends one workflow input declaration.

func (Builder) Namespace 

func (b Builder) Namespace(value string) Builder

Namespace returns a builder with the graph namespace set.

func (Builder) Node 

func (b Builder) Node(value graph.Node) Builder

Node appends one executable/control node.

func (Builder) Output 

func (b Builder) Output(value graph.OutputSpec) Builder

Output appends one workflow output declaration.

type CompactDiagnostic 

type CompactDiagnostic struct {
	Severity string   `json:"severity"`
	Code     string   `json:"code"`
	Message  string   `json:"message"`
	Path     []string `json:"path,omitempty"`
	Locator  string   `json:"locator,omitempty"`
	Help     string   `json:"help,omitempty"`
}

CompactDiagnostic is the bounded generated-client projection. Full diagnostics remain available to Go callers.

func CompactDiagnostics 

func CompactDiagnostics(input []diagnostic.Diagnostic) []CompactDiagnostic

CompactDiagnostics returns a deterministic, bounded, presentation-safe projection. A final sentinel makes finding-count omissions explicit; an ellipsis marks truncated fields and path segments.

type CompileOptions 

type CompileOptions struct {
	Compile    compile.CompileOptions
	Dependency compile.DependencyOptions
	Validation compile.ValidationOptions
	Definition graph.DefinitionRef
	Limits     Limits
}

CompileOptions supplies the exact ordinary compiler and validator catalogs.

type Envelope 

type Envelope struct {
	SchemaID              string         `json:"schema_id"`
	SchemaVersion         string         `json:"schema_version"`
	MaterialSchemaID      string         `json:"material_schema_id"`
	MaterialSchemaVersion string         `json:"material_schema_version"`
	Format                MaterialFormat `json:"format"`
	Graph                 *graph.Graph   `json:"graph,omitempty"`
	Source                string         `json:"source,omitempty"`
}

Envelope is the single strict ingress shape shared by generated clients and agent adapters. SchemaID and SchemaVersion identify this envelope; Material fields identify the selected graph/source schema without implicit fallback.

func DecodeEnvelope 

func DecodeEnvelope(data []byte, limits Limits) (Envelope, []diagnostic.Diagnostic)

DecodeEnvelope enforces bounds, JSON shape, schema negotiation, and graph JSON Schema before any compiler work begins.

type Limits 

type Limits struct {
	MaximumBytes int
	MaximumDepth int
	MaximumNodes int
	MaximumEdges int
}

Limits bounds JSON work before compilation or validation.

type MaterialFormat 

type MaterialFormat string

MaterialFormat selects exactly one authoring payload.

func (MaterialFormat) Valid 

func (f MaterialFormat) Valid() bool

type Result 

type Result struct {
	Plan        *compile.ExecutionPlan
	Visibility  compile.ValueVisibilityPlan
	Deferred    []compile.DeferredDependency
	Diagnostics []diagnostic.Diagnostic
}

Result carries either a fully inferred and validated plan or diagnostics.

func CompileEnvelope 

func CompileEnvelope(ctx context.Context, envelope Envelope, sourceFormat graph.SourceFormat, options CompileOptions) Result

CompileEnvelope applies the ordinary compiler, dependency inference, and validator to already decoded material.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.