composition

package
v0.9.0 Latest Latest
Warning

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

Go to latest
Published: Nov 4, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Overview

ENGMODEL-OWNER-UNIT: FU-SYSTEM-COMPOSITION

ENGMODEL-OWNER-UNIT: FU-SYSTEM-COMPOSITION

ENGMODEL-OWNER-UNIT: FU-SYSTEM-COMPOSITION

ENGMODEL-OWNER-UNIT: FU-SYSTEM-COMPOSITION

ENGMODEL-OWNER-UNIT: FU-SYSTEM-COMPOSITION

Index

Constants

View Source
const (
	// LockModeWrite writes engmod.lock.yml (or the local lock in workspace mode).
	LockModeWrite = "write"
	// LockModeCheck compares the resolved lock with engmod.lock.yml and writes nothing.
	LockModeCheck = "check"
)
View Source
const (
	// ModuleCacheReuse reuses a cached module without contacting the
	// registry. Set explicitly it applies in every lock mode; it is also the
	// default except for lock check mode and lock regeneration (see cacheMode).
	ModuleCacheReuse = "reuse"
	// ModuleCacheRefresh re-fetches every registry dependency.
	ModuleCacheRefresh = "refresh"
)
View Source
const CompositionLocalLockFileName = "engmod.lock.local.yml"

CompositionLocalLockFileName receives the resolved lock while workspace replacements are active, so the committed lock never pins unpublished content.

View Source
const CompositionLockFileName = "engmod.lock.yml"
View Source
const LockEnv = "ENGMOD_LOCK"

LockEnv selects the lock mode: "check" compares with the committed lock and writes nothing; "write" (or unset) writes the lock.

View Source
const ModuleCacheEnv = "ENGMOD_MODULE_CACHE"

ModuleCacheEnv selects the module cache mode: "refresh" re-fetches every registry dependency; "reuse" reuses cached modules offline; unset applies the defaults of cacheMode.

Variables

This section is empty.

Functions

func DelegationsByRequirement

func DelegationsByRequirement(composed CompositionResult) map[string][]MaterializedAllocation

DelegationsByRequirement indexes the composition's allocations by requirement. TRLC-LINKS: REQ-EMG-020, REQ-EMG-066 ENGMODEL-LINKS: FU-ALLOCATION-TRACE

func EnrichBundleFromComposition

func EnrichBundleFromComposition(bundle model.Bundle, domains ...string) (model.Bundle, error)

EnrichBundleFromComposition resolves the bundle's composition and returns a copy enriched with the published entities of the given domains; a bundle without composition is returned unchanged. TRLC-LINKS: REQ-EMG-050, REQ-EMG-051

func HasComposition

func HasComposition(bundle model.Bundle) bool

HasComposition reports whether the model declares any subsystems. TRLC-LINKS: REQ-EMG-016 ENGMODEL-LINKS: FU-SYSTEM-COMPOSITION

func LinkDependencies added in v0.8.0

func LinkDependencies(sys *ComposedSystem) []reqlinks.Dependency

LinkDependencies returns the resolved direct dependencies of a composed system as requirement link evaluation sees them: alias, resolved version, model and the publication each subsystem selects. TRLC-LINKS: REQ-EMG-097 ENGMODEL-LINKS: FU-SYSTEM-COMPOSITION, FU-ALLOCATION-TRACE

func LinkDiagnostics added in v0.8.0

func LinkDiagnostics(system model.Bundle, deps []reqlinks.Dependency) []validate.Diagnostic

LinkDiagnostics evaluates the links and returns the composition-time link diagnostics: link.broken (the item does not exist at the dependency pin) and link.child_unpublished (errors; a child naming an undeclared or uncomposed dependency and a stale pin, link.version_mismatch, are reported by validation) and link.aou_unverified for every published assumption of use of a resolved dependency that no link with evidence covers (error in strict mode, warning in guided mode where the rules apply, see validate.RequirementLinkRules). No item content is compared (decision D23), and a dependency resolved from a workspace replacement raises no link finding: a checkout is work in progress. TRLC-LINKS: REQ-EMG-097, REQ-EMG-098 ENGMODEL-LINKS: FU-ALLOCATION-TRACE, FU-VALIDATION-ENGINE

func PathWithin

func PathWithin(root, path string) bool

PathWithin reports whether path, after resolving symlinks where possible, lies inside root (root itself included). TRLC-LINKS: REQ-EMG-017, REQ-EMG-049

func QualifiedReferenceDiagnostics

func QualifiedReferenceDiagnostics(bundle model.Bundle, result CompositionResult) []validate.Diagnostic

QualifiedReferenceDiagnostics reports every alias::ID reference in the authored model that no selected dependency publication makes visible, once per field path (composition.unpublished_reference). A model without composition has no visible imports, so each of its qualified references is reported. TRLC-LINKS: REQ-EMG-065 ENGMODEL-LINKS: FU-SYSTEM-COMPOSITION, FU-VALIDATION-ENGINE

func ResolutionCount

func ResolutionCount() int64

ResolutionCount returns how many composition resolutions this process has run. Engine tests use it to prove that one generation call composes once. TRLC-LINKS: REQ-EMG-066 ENGMODEL-LINKS: FU-SYSTEM-COMPOSITION

func ResolveCompositionProjection

func ResolveCompositionProjection(bundle model.Bundle) (CompositionProjection, CompositionResult, error)

ResolveCompositionProjection resolves and validates composition for a bundle. TRLC-LINKS: REQ-EMG-050, REQ-EMG-051

func ResolveCompositionProjectionWith

func ResolveCompositionProjectionWith(bundle model.Bundle, options ResolutionOptions) (CompositionProjection, CompositionResult, error)

ResolveCompositionProjectionWith is ResolveCompositionProjection under explicit workspace and lock modes. TRLC-LINKS: REQ-EMG-050, REQ-EMG-051, REQ-EMG-063, REQ-EMG-064

func WriteCompositionLock

func WriteCompositionLock(path string, lock CompositionLockDocument) error

WriteCompositionLock writes deterministic generated dependency state. TRLC-LINKS: REQ-EMG-047, REQ-EMG-048, REQ-EMG-049, REQ-EMG-051

Types

type ComposedSystem

type ComposedSystem struct {
	SubsystemID    string
	Dependency     string
	Publication    string
	ModulePath     string
	Version        string
	Dir            string
	Bundle         model.Bundle
	Requirements   model.RequirementsDocument
	PublishedIDs   map[string]bool
	PublishedFacet map[string]string
	Children       []*ComposedSystem
	// Local is set when the system resolved from a workspace replacement (a
	// checkout), not from the registry.
	Local bool
}

ComposedSystem is a resolved system together with its resolved subsystems. ENGMODEL-LINKS: FU-SYSTEM-COMPOSITION, DO-ARCHITECTURE-MODEL

type CompositionLockDependency

type CompositionLockDependency struct {
	Alias        string   `yaml:"alias"`
	Path         string   `yaml:"path"`
	Version      string   `yaml:"version"`
	Publications []string `yaml:"publications"`
	Digest       string   `yaml:"digest"`
}

type CompositionLockDocument

type CompositionLockDocument struct {
	SchemaVersion int                         `yaml:"schemaVersion"`
	Dependencies  []CompositionLockDependency `yaml:"dependencies"`
}

CompositionLockDocument is deterministic generated dependency state. TRLC-LINKS: REQ-EMG-047, REQ-EMG-048, REQ-EMG-049, REQ-EMG-051

type CompositionProjection

type CompositionProjection struct {
	Publications []PublishedProjection
	Entities     []PublishedProjectionEntity
}

CompositionProjection is the reusable, read-only projection boundary used by every output format. It never mutates an authored bundle. TRLC-LINKS: REQ-EMG-050, REQ-EMG-051

func BuildCompositionProjection

func BuildCompositionProjection(result CompositionResult) CompositionProjection

BuildCompositionProjection materializes only direct, explicitly selected dependency publications. Transitive or unexported child data is not exposed. TRLC-LINKS: REQ-EMG-050, REQ-EMG-051

func (CompositionProjection) Domain

func (projection CompositionProjection) Domain(domain string) []PublishedProjectionEntity

Domain returns published entities from one manifest publication facet. TRLC-LINKS: REQ-EMG-050, REQ-EMG-051

func (CompositionProjection) EnrichBundle

func (projection CompositionProjection) EnrichBundle(bundle model.Bundle, domains ...string) model.Bundle

EnrichBundle returns a projection-only copy containing typed published entities. It is intended for native generators after the authored bundle has been validated; unsupported relationships are omitted rather than flattened. TRLC-LINKS: REQ-EMG-050, REQ-EMG-051, REQ-EMG-065, REQ-EMG-091

type CompositionResult

type CompositionResult struct {
	Root        *ComposedSystem
	Allocations []MaterializedAllocation
	Provenance  []ImportedEntityProvenance
	Lock        CompositionLockDocument
	Diagnostics []validate.Diagnostic
	// Workspace is the workspace root the dependencies resolved from.
	Workspace string
	// contains filtered or unexported fields
}

CompositionResult is the resolved tree plus materialized allocation trace and diagnostics. ENGMODEL-LINKS: FU-SYSTEM-COMPOSITION, FU-ALLOCATION-TRACE

func ComposeForGeneration

func ComposeForGeneration(bundle model.Bundle, given *CompositionResult, options ResolutionOptions) (CompositionResult, error)

ComposeForGeneration returns the composition for a bundle: the caller's result when given, otherwise one fresh resolution with the bundle itself as the root system (so in-memory content, not the files on disk, is checked). A model without composition returns an empty result. TRLC-LINKS: REQ-EMG-066 ENGMODEL-LINKS: FU-ASCIIDOC-GENERATOR, FU-SYSTEM-COMPOSITION

func GenerateCompositionForBundle

func GenerateCompositionForBundle(bundle model.Bundle, options ResolutionOptions) (CompositionResult, error)

GenerateCompositionForBundle resolves the composition of an already loaded bundle: the dependencies are resolved from bundle.ManifestPath's location (workspace, module cache, lock) as in GenerateCompositionFromFileWith, but the root system - its manifest dependencies, composition, contract and every alias::ID reference - is the given bundle, not the files on disk. A caller validating edited content in memory thus gets the diagnostics of that content. TRLC-LINKS: REQ-EMG-065, REQ-EMG-066, REQ-EMG-069 ENGMODEL-LINKS: FU-SYSTEM-COMPOSITION, FU-MODEL-LOADER

func GenerateCompositionFromFile

func GenerateCompositionFromFile(manifestPath string) (CompositionResult, error)

GenerateCompositionFromFile resolves the system-of-systems rooted at engmod.yml with the workspace and lock modes taken from ENGMOD_WORK and ENGMOD_LOCK. TRLC-LINKS: REQ-EMG-016, REQ-EMG-047, REQ-EMG-048, REQ-EMG-049, REQ-EMG-051, REQ-EMG-063, REQ-EMG-064 ENGMODEL-LINKS: FU-SYSTEM-COMPOSITION, FU-MODEL-LOADER, FLOW-MODEL-CHANGE-TO-VERIFIED-ARTIFACTS

func GenerateCompositionFromFileWith

func GenerateCompositionFromFileWith(manifestPath string, options ResolutionOptions) (CompositionResult, error)

GenerateCompositionFromFileWith resolves the system-of-systems rooted at engmod.yml under explicit workspace and lock modes. Lock policy: while workspace replacements are active, engmod.lock.yml is never touched and the resolved lock is written to engmod.lock.local.yml; in check mode nothing is written and, without replacements, the resolved lock is compared with the committed one (composition.lock_missing, lock_invalid, lock_mismatch); otherwise engmod.lock.yml is written. TRLC-LINKS: REQ-EMG-016, REQ-EMG-047, REQ-EMG-048, REQ-EMG-049, REQ-EMG-051, REQ-EMG-063, REQ-EMG-064, REQ-EMG-066 ENGMODEL-LINKS: FU-SYSTEM-COMPOSITION, FU-MODEL-LOADER, FLOW-MODEL-CHANGE-TO-VERIFIED-ARTIFACTS

func (CompositionResult) DisplayDir

func (r CompositionResult) DisplayDir(dir string) string

DisplayDir names a resolved directory for output that may leave the machine (MCP responses): a module cache entry as module@version, a directory under the workspace root relative to it, anything else by its base name. It never returns an absolute path. TRLC-LINKS: REQ-EMG-069, REQ-EMG-066 ENGMODEL-LINKS: FU-SYSTEM-COMPOSITION, CTRL-MCP-PATH-BOUNDARY

type ImportedEntityProvenance

type ImportedEntityProvenance struct {
	QualifiedID string `yaml:"qualifiedId"`
	Alias       string `yaml:"alias"`
	ModulePath  string `yaml:"path"`
	Version     string `yaml:"version"`
	SourceModel string `yaml:"sourceModelId"`
	Publication string `yaml:"publicationId"`
	Domain      string `yaml:"domain"`
	SourceID    string `yaml:"sourceId"`
	ResolvedDir string `yaml:"resolvedDirectory"`
}

ImportedEntityProvenance records where each visible imported identifier came from without leaking composition metadata into generic target properties. TRLC-LINKS: REQ-EMG-047, REQ-EMG-049, REQ-EMG-051

type LinkUse added in v0.8.0

type LinkUse struct {
	Model  string // model id of the using model
	Link   string // its link id
	Parent string // its parent requirement ("" for an evidence link)
	Item   string // this model's contract item (local id)
	Status string // claimed or accepted
}

LinkUse is one requirement link of a using model in the workspace onto a contract item of this model. TRLC-LINKS: REQ-EMG-107 ENGMODEL-LINKS: FU-SYSTEM-COMPOSITION, FU-ALLOCATION-TRACE

func WorkspaceLinkUsers added in v0.8.0

func WorkspaceLinkUsers(bundle model.Bundle, mode string) []LinkUse

WorkspaceLinkUsers finds the workspace of bundle's manifest under mode (empty: ENGMOD_WORK, else search upwards; "off": none) and returns, sorted, every reqLinks entry of a sibling checkout (a replacement other than this module, or the model at the workspace root) whose child names one of this model's published contract items through a dependency on this module path. Without an active workspace it returns nothing; a replacement outside the workspace directory, a sibling whose manifest names a path outside its own directory and a sibling that does not load are skipped. TRLC-LINKS: REQ-EMG-107, REQ-EMG-108 ENGMODEL-LINKS: FU-SYSTEM-COMPOSITION, FU-ALLOCATION-TRACE

type MaterializedAllocation

type MaterializedAllocation struct {
	System            string // owning (parent) system id
	Requirement       string
	Subsystem         string
	Target            string // public id within the subsystem
	TargetRef         string // the subsystem requirement that realizes the target (its contract ref)
	Resolved          bool   // target is published in the subsystem contract
	TargetRefResolved bool   // TargetRef names a requirement that exists in the subsystem
	Note              string
}

MaterializedAllocation is a parent->subsystem allocation with its composed-view resolution status. ENGMODEL-LINKS: FU-ALLOCATION-TRACE, CTRL-TRACEABILITY-COVERAGE

func MaterializeAllocations

func MaterializeAllocations(sys *ComposedSystem) []MaterializedAllocation

MaterializeAllocations walks the tree and produces the parent->subsystem allocation trace, resolving each target against the referenced subsystem's published contract. The subsystem models are never modified. TRLC-LINKS: REQ-EMG-020, REQ-EMG-025 ENGMODEL-LINKS: FU-ALLOCATION-TRACE, CTRL-TRACEABILITY-COVERAGE

type PublishedProjection

type PublishedProjection struct {
	Alias       string
	Publication string
	ModulePath  string
	Version     string
	SourceModel string
	Entities    []PublishedProjectionEntity
}

PublishedProjection groups the entities selected from one dependency publication. TRLC-LINKS: REQ-EMG-050, REQ-EMG-051

type PublishedProjectionEntity

type PublishedProjectionEntity struct {
	QualifiedID string
	SourceID    string
	Domain      string
	Facet       string
	Value       any
	Source      *model.Bundle
	Provenance  ImportedEntityProvenance
}

PublishedProjectionEntity is one explicitly published dependency entity, retaining its typed value, qualified identity, source bundle, and provenance. TRLC-LINKS: REQ-EMG-050, REQ-EMG-051

func (PublishedProjectionEntity) QualifyList

func (entity PublishedProjectionEntity) QualifyList(refs []string) []string

QualifyList qualifies each reference that the entity's publication makes visible with its dependency alias and drops the others. TRLC-LINKS: REQ-EMG-050, REQ-EMG-051

type ResolutionOptions

type ResolutionOptions struct {
	Workspace string
	Lock      string
	// ModuleCache is "refresh" to re-fetch every registry dependency into
	// the module cache, or "reuse"; empty falls back to ENGMOD_MODULE_CACHE.
	ModuleCache string
}

ResolutionOptions overrides the ENGMOD_WORK and ENGMOD_LOCK environment for one call. Empty fields fall back to the environment. Workspace is "off" or a workspace file path; Lock is "check" or "write". TRLC-LINKS: REQ-EMG-063, REQ-EMG-064

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL