contract

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Sep 7, 2026 License: Apache-2.0 Imports: 24 Imported by: 0

Documentation

Overview

Package contract derives the cross-job contract graph from authoritative job, trigger, and lineage sources.

Index

Constants

View Source 
const (
	EnforcementModeOff  = ""
	EnforcementModeWarn = "warn"
	EnforcementModeFail = "fail"
)

Variables

View Source 
var (
	ErrContractBreakBlocked = errors.New("contract breaking change blocked")
	ErrInvalidContractAck   = errors.New("invalid contract breaking acknowledgement")
)

Functions

func AliasSet 

func AliasSet(defs []schema.Definition) map[string]struct{}

AliasSet returns the set of job aliases declared by a definition batch. It is the canonical "which jobs is this request about" set shared by apply enforcement and by the lint/check read surfaces that scope findings.

func EdgeInAliasScope 

func EdgeInAliasScope(edge Edge, aliases map[string]struct{}) bool

EdgeInAliasScope reports whether a contract edge touches one of the given job aliases as its producer or consumer endpoint. Every derived edge (declared, inferred, and evidence) is job -> job, so an edge is "about" a linted job exactly when one of its endpoints is that job — which also pulls in the linted job's direct producers and direct consumers on the server.

A nil alias set means "no scope requested" and matches everything, mirroring contractFindingInIncomingScope in enforce.go. An empty (non-nil) set scopes to nothing.

func EnforceApply 

func EnforceApply(ctx context.Context, db *gorm.DB, incoming []schema.Definition, mode string, now time.Time) error

EnforceApply derives the merged contract graph for incoming definitions and applies warn/fail enforcement. Off-mode returns before graph derivation so the apply path is fully inert when CAESIUM_CONTRACT_ENFORCEMENT is unset.

func EvaluateGraph 

func EvaluateGraph(ctx context.Context, db *gorm.DB, graph Graph, mode string, now time.Time) error

EvaluateGraph applies enforcement to an already-derived graph. It is split out so tests and future lint/diff surfaces can reuse the exact digest logic.

func JobNodeID 

func JobNodeID(alias string) string

JobNodeID is the canonical graph node identifier for a job alias. Exported so API layers filtering findings by job stay in sync with the graph's ID convention instead of duplicating the format.

Types

type AllowBreaking 

type AllowBreaking struct {
	Dataset string
	Reason  string
	Actor   string
}

AllowBreaking scopes one intentional break acknowledgement requested by an apply caller. The CLI grammar is --allow-breaking dataset=<subject>, where subject is a declared dataset name or an inferred producer.output.<key> subject.

type ApplyOptions 

type ApplyOptions struct {
	AllowBreaking      *AllowBreaking
	DeprecationWindow  time.Duration
	EventStore         EventAppender
	IncomingAliases    map[string]struct{}
	SuppressAckNoMatch bool
}

ApplyOptions controls acknowledgement creation and warning attribution.

type ConsumedDataset 

type ConsumedDataset struct {
	Name   string
	Schema map[string]any
}

ConsumedDataset is the compact consumes declaration used by the contract graph.

type ContractFinding 

type ContractFinding struct {
	Subject           string `json:"subject"`
	Dataset           string `json:"dataset,omitempty"`
	OutputKey         string `json:"output_key,omitempty"`
	Producer          string `json:"producer"`
	Consumer          string `json:"consumer"`
	ConsumerTeam      string `json:"consumer_team,omitempty"`
	TeamAttribution   string `json:"team_attribution,omitempty"`
	EdgeClass         string `json:"edge_class"`
	Path              string `json:"path"`
	Detail            string `json:"detail"`
	Verdict           string `json:"verdict"`
	EdgeID            string `json:"edge_id"`
	EdgeSetDigest     string `json:"edge_set_digest"`
	Acknowledged      bool   `json:"acknowledged"`
	AcknowledgementID string `json:"acknowledgement_id,omitempty"`
}

ContractFinding names one impacted consumer for a breaking contract edge.

type ContractWarning 

type ContractWarning struct {
	Type              string    `json:"type"`
	Message           string    `json:"message"`
	Subject           string    `json:"subject"`
	Dataset           string    `json:"dataset,omitempty"`
	OutputKey         string    `json:"output_key,omitempty"`
	Producer          string    `json:"producer"`
	Consumer          string    `json:"consumer,omitempty"`
	ConsumerTeam      string    `json:"consumer_team,omitempty"`
	EdgeSetDigest     string    `json:"edge_set_digest"`
	AcknowledgementID string    `json:"acknowledgement_id"`
	DeprecationUntil  time.Time `json:"deprecation_until"`
}

ContractWarning is returned on successful apply calls that rely on an active deprecation acknowledgement.

type DatasetRef 

type DatasetRef struct {
	Namespace string `json:"namespace"`
	Name      string `json:"name"`
}

DatasetRef identifies a dataset by its OpenLineage namespace/name pair.

type DeriveInput 

type DeriveInput struct {
	Jobs                    []Job
	Evidence                []EvidenceRecord
	PreviousProducerSchemas []ProducerSchemaRecord
}

DeriveInput is the pure input surface for graph derivation. Callers that already have the merged job world can use DeriveGraph directly.

type Deriver 

type Deriver struct {
	Jobs            JobReader
	Evidence        EvidenceReader
	ProducerSchemas ProducerSchemaReader
}

Deriver loads authoritative sources and derives a contract graph on demand.

func NewGORMDeriver 

func NewGORMDeriver(db *gorm.DB) Deriver

NewGORMDeriver returns a Deriver backed by the existing GORM catalog tables.

func (Deriver) DeriveGraph 

func (d Deriver) DeriveGraph(ctx context.Context, incoming []schema.Definition) (Graph, error)

DeriveGraph loads the merged job world, lineage evidence, and returns the derived contract graph. Incoming definitions replace persisted jobs with matching aliases, mirroring trigger-chain validation.

type Edge 

type Edge struct {
	ID                     string                 `json:"id"`
	From                   string                 `json:"from"`
	To                     string                 `json:"to"`
	Class                  EdgeClass              `json:"class"`
	Verdict                schemacompat.Verdict   `json:"verdict,omitempty"`
	Findings               []schemacompat.Finding `json:"findings,omitempty"`
	Dataset                *DatasetRef            `json:"dataset,omitempty"`
	ProducerSchema         map[string]any         `json:"producerSchema,omitempty"`
	PreviousProducerSchema map[string]any         `json:"previousProducerSchema,omitempty"`
	ConsumerSchema         map[string]any         `json:"consumerSchema,omitempty"`
	LastSeen               *time.Time             `json:"lastSeen,omitempty"`
}

Edge is a derived relationship between two graph nodes.

type EdgeClass 

type EdgeClass string

EdgeClass identifies how a contract graph edge was derived. 

const (
	// EdgeClassDeclared marks an edge declared through dataset produces/consumes blocks.
	EdgeClassDeclared EdgeClass = "declared"
	// EdgeClassInferred marks an edge inferred from lifecycle trigger chains and paramMapping paths.
	EdgeClassInferred EdgeClass = "inferred"
	// EdgeClassEvidence marks an edge observed from lineage input/output rows.
	EdgeClassEvidence EdgeClass = "evidence"
)

type EnforcementError 

type EnforcementError struct {
	Response EnforcementResponse
}

EnforcementError is returned when fail-mode enforcement sees an unacknowledged breaking edge set.

func (*EnforcementError) Error 

func (e *EnforcementError) Error() string

func (*EnforcementError) Unwrap 

func (e *EnforcementError) Unwrap() error

type EnforcementResponse 

type EnforcementResponse struct {
	Error    string            `json:"error"`
	Message  string            `json:"message"`
	Findings []ContractFinding `json:"findings"`
}

EnforcementResponse is the stable machine-readable 409 payload consumed by CLI, REST, and future UI surfaces.

type EnforcementResult 

type EnforcementResult struct {
	Warnings []ContractWarning
}

EnforcementResult carries non-blocking warnings produced by enforcement.

func EnforceApplyWithOptions 

func EnforceApplyWithOptions(ctx context.Context, db *gorm.DB, incoming []schema.Definition, mode string, now time.Time, opts ApplyOptions) (EnforcementResult, error)

EnforceApplyWithOptions derives the graph and applies enforcement, optionally recording a bounded acknowledgement for one matching breaking subject.

func EvaluateGraphWithOptions 

func EvaluateGraphWithOptions(ctx context.Context, db *gorm.DB, graph Graph, mode string, now time.Time, opts ApplyOptions) (EnforcementResult, error)

EvaluateGraphWithOptions applies enforcement and optionally writes an acknowledgement for a matching breaking subject.

type EventAppender 

type EventAppender interface {
	AppendTx(*gorm.DB, *event.Event) error
}

EventAppender is the transactional subset of internal/event.Store used to persist contract-break notifications without tying tests to the concrete type.

type EvidenceReader 

type EvidenceReader interface {
	ListContractEvidence(ctx context.Context) ([]EvidenceRecord, error)
}

EvidenceReader reads lineage-observed job-level dataset flow edges.

type EvidenceRecord 

type EvidenceRecord struct {
	ProducerJobID    uuid.UUID
	ProducerJobAlias string
	ConsumerJobID    uuid.UUID
	ConsumerJobAlias string
	Dataset          DatasetRef
	LastSeen         time.Time
}

EvidenceRecord is one distinct lineage-observed producer/dataset/consumer edge.

type GORMStore 

type GORMStore struct {
	DB *gorm.DB
}

GORMStore reads contract graph inputs from the existing GORM catalog.

func (GORMStore) ListContractEvidence 

func (s GORMStore) ListContractEvidence(ctx context.Context) ([]EvidenceRecord, error)

ListContractEvidence returns distinct job-level lineage evidence edges.

func (GORMStore) ListContractJobs 

func (s GORMStore) ListContractJobs(ctx context.Context, incoming []schema.Definition) ([]Job, error)

ListContractJobs returns incoming definitions plus persisted jobs not replaced by those definitions.

func (GORMStore) ListContractProducerSchemas 

func (s GORMStore) ListContractProducerSchemas(ctx context.Context, incoming []schema.Definition) ([]ProducerSchemaRecord, error)

ListContractProducerSchemas returns resolved persisted producer schemas for jobs that the incoming batch is replacing.

type Graph 

type Graph struct {
	Nodes []Node `json:"nodes"`
	Edges []Edge `json:"edges"`
}

Graph is the JSON-ready contract graph returned by read surfaces.

func DeriveGraph 

func DeriveGraph(input DeriveInput) (Graph, error)

DeriveGraph derives a contract graph from already-loaded jobs and lineage evidence. It performs no writes and stores no graph state.

func ScopeGraphToAliases 

func ScopeGraphToAliases(graph Graph, aliases map[string]struct{}) Graph

ScopeGraphToAliases narrows a derived contract graph to the edges that touch one of the given job aliases, dropping unrelated producer/consumer pairs that only exist because graph derivation unions the incoming batch with every job already persisted on the server.

Nodes are retained when a kept edge references them, and the alias set's own job nodes are always retained so a scoped graph still names the subject jobs even when they have no contract edges at all.

type Job 

type Job struct {
	ID       uuid.UUID
	Alias    string
	Labels   map[string]string
	Trigger  Trigger
	Steps    []Step
	Incoming bool
}

Job is the compact job definition surface needed to derive contract graph edges.

type JobReader 

type JobReader interface {
	ListContractJobs(ctx context.Context, incoming []schema.Definition) ([]Job, error)
}

JobReader reads the merged job world used to derive contract graph edges.

type Node 

type Node struct {
	ID      string            `json:"id"`
	Kind    NodeKind          `json:"kind"`
	Alias   string            `json:"alias,omitempty"`
	Labels  map[string]string `json:"labels,omitempty"`
	Dataset *DatasetRef       `json:"dataset,omitempty"`
}

Node is a job or dataset graph node.

type NodeKind 

type NodeKind string

NodeKind identifies the kind of graph node. 

const (
	// NodeKindJob is a Caesium job node.
	NodeKindJob NodeKind = "job"
	// NodeKindDataset is an OpenLineage dataset node.
	NodeKindDataset NodeKind = "dataset"
)

type ProducedDataset 

type ProducedDataset struct {
	Name       string
	Schema     map[string]any
	SchemaFrom string
	Version    int
}

ProducedDataset is the compact produces declaration used by the contract graph.

type ProducerSchemaReader 

type ProducerSchemaReader interface {
	ListContractProducerSchemas(ctx context.Context, incoming []schema.Definition) ([]ProducerSchemaRecord, error)
}

ProducerSchemaReader reads persisted producer schemas replaced by an incoming batch.

type ProducerSchemaRecord 

type ProducerSchemaRecord struct {
	JobAlias    string
	StepName    string
	Dataset     DatasetRef
	Schema      map[string]any
	SchemaKnown bool
}

ProducerSchemaRecord captures a persisted producer's resolved dataset schema before an incoming definition replaces it.

type Step 

type Step struct {
	Name         string
	OutputSchema map[string]any
	Produces     []ProducedDataset
	Consumes     []ConsumedDataset
}

Step is the compact step surface needed for output-schema and dataset checks.

type Trigger 

type Trigger struct {
	Type          string
	Configuration map[string]any
}

Trigger is the compact trigger surface needed for trigger-chain inference.

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.