Documentation
¶
Overview ¶
Package catalog loads a factory catalog (a directory of YAML objects plus prompt and schema assets) into an immutable, validated snapshot, as specified by design/workstreams/dispatcher-core/LLD/catalog.md.
LoadDir reads only through an fs.FS and runs every validation phase, collecting all diagnostics rather than stopping at the first. The package is pure: no network, no processes, no clock. Loading from a git ref lives in the gitsource subpackage.
Index ¶
- Constants
- Variables
- func DefaultCapabilities() []v1alpha1.AdapterCapabilities
- func DefaultKnownModels() map[string][]string
- func HasErrors(errs []Error) bool
- func LoadDir(fsys fs.FS, opts Options) (*Catalog, []Error)
- func ParseCapabilities(data []byte) ([]v1alpha1.AdapterCapabilities, error)
- func ParseKnownModels(data []byte) (map[string][]string, error)
- type Assets
- type Catalog
- type CompiledAction
- type CompiledRuleSet
- type CompiledScope
- type CompiledTaskSpec
- type EffectiveRule
- type Error
- type Harnesses
- type ObjectKey
- type Options
- type Prompt
- type Severity
- type SourcePos
Constants ¶
const ( FeatureStructuredOutput = "structured-output" // output.schema FeatureMCP = "mcp" // effects, through the Effector's MCP server FeaturePlugins = "plugins" // skills, as a plugin dir FeatureSkillsDir = "skills-dir" // skills, as a skills dir )
Harness features a TaskSpec can need (AdapterCapabilities.Features).
const ( // Loading. CodeDuplicate = "CAT001" // two objects with the same (kind, name) CodeNotAnObject = "CAT002" // a document without kind, or a kind that isn't a catalog kind CodeSyntax = "CAT003" // a file that can't be read or isn't valid YAML CodeInvalidAsset = "CAT004" // a prompt or Template body that isn't a valid text/template, or a JSON Schema that doesn't compile // Phase 1, schema. CodeSchema = "CAT100" // the document doesn't match its kind's JSON Schema, or doesn't decode strictly // Phase 2, references. CodeUnknownTaskSpec = "CAT200" // dispatch/cancel names a TaskSpec that doesn't exist CodeUnknownQueue = "CAT201" // dispatch names a Queue that doesn't exist CodeUnknownTemplate = "CAT202" // notify names a Template that doesn't exist CodeUnknownGroup = "CAT203" // notify/trust/pool admission names a Group that doesn't exist CodeUnknownPool = "CAT204" // a Queue names a Pool that doesn't exist CodeUnknownRule = "CAT205" // RuleSet refs/exclude/overrides (or Rule spec.ruleSet) name a missing Rule (RuleSet) CodeUnknownProvider = "CAT206" // Group member, destination, target or pool backend names a Provider that doesn't exist CodeMissingPrompt = "CAT207" // TaskSpec instructions.template isn't a file under prompts/ CodeMissingSchema = "CAT208" // TaskSpec output.schema isn't a file under schemas/ CodeMissingFile = "CAT209" // another referenced file (a Template's Block Kit file) doesn't exist // Phase 3, selection. CodeNoProviders = "CAT300" // a RuleSet's providerSelector matches no Provider CodeNoRules = "CAT301" // a RuleSet's rules.selector matches no Rule CodeProviderMismatch = "CAT302" // a selected rule's providerSelector matches none of the RuleSet's providers CodeBadSelector = "CAT303" // an invalid label selector or scope glob // Phase 4, event vocabulary. CodeNotEmittable = "CAT400" // an `on` type isn't emitted by any of the rule's effective providers CodeFactoryReserved = "CAT401" // a catalog Provider named or typed "factory" (reserved for factory.* events) CodeSchedule = "CAT402" // schedule without on: [factory.schedule.tick] (or the reverse), or a malformed cron // Phase 5, params. CodeUnknownOverride = "CAT500" // an override key isn't a declared param of the rule CodeUnusedDefault = "CAT501" // a RuleSet default no selected rule declares (warning) CodePlaceholder = "CAT502" // a {{ }} placeholder that isn't {{ params.<declared> }}, or a substituted value of the wrong type // Phase 6, CEL. CodeWhere = "CAT600" // a where that doesn't compile to bool CodeExpr = "CAT601" // a "=" value that doesn't compile CodeField = "CAT602" // a selection outside the documented field allow-list CodeCost = "CAT603" // an estimated cost over the evaluation limit CodeNowInWhere = "CAT604" // now in a where without a schedule (warning) // Phase 7, dispatch. CodeInputMissing = "CAT700" // a required TaskSpec input isn't provided CodeInputUnknown = "CAT701" // a dispatch input the TaskSpec doesn't declare CodeInputValue = "CAT702" // a literal input (or input default) of the wrong type or outside its enum CodeRequires = "CAT703" // an invalid dispatch.requires label // Phase 8, harness. CodePattern = "CAT800" // a harness pattern that doesn't compile CodeNotSubsumed = "CAT801" // a request that can never fit its TaskSpec's constraints (harness, known models or efforts) CodeEffort = "CAT802" // an effort outside the normalised set, or one the harness can't map CodeCapability = "CAT803" // a harness without capabilities, or missing a feature the TaskSpec needs CodeDuplicateHarness = "CAT804" // the same harness twice in a TaskSpec's harness.allowed CodeNoHarness = "CAT805" // a TaskSpec with neither harness.allowed nor harness.default // Phase 9, effects. CodeUnknownOp = "CAT900" // an unknown op in a TaskSpec's effects.allow CodeEffectAction = "CAT901" // an effect action with an unknown op or invalid op fields CodeReviewOp = "CAT902" // review.* ops in a TaskSpec whose identity isn't reviewer CodeGitOp = "CAT903" // push-branch/stack.* ops in a TaskSpec without a writable workspace CodeUnsupportedOp = "CAT904" // requestApproval, accepted but unsupported in the PoC (Q18) (warning) // Phase 10, state. CodeStateKey = "CAT1000" // a set key outside the RuleSet's stateKeys CodeStateRead = "CAT1001" // an item.state key read in a where outside the RuleSet's stateKeys (warning) // Phase 11, workspace. CodeWorkspaceRW = "CAT1100" // more than one rw repo in a TaskSpec's workspace CodeWorkspaceExpr = "CAT1101" // a TaskSpec "=" field that uses something other than inputs/task, or an undeclared input // Phase 12, overlap. CodeOverlap = "CAT1200" // two RuleSets select the same rule for overlapping scope and providers (warning) )
Codes are stable: tools, fixtures and the UI match on them. The LLD's table (design/workstreams/dispatcher-core/LLD/catalog.md §Validation phases) gives the ranges; the meaning of each code within its range is fixed here.
Variables ¶
var NormalisedEfforts = []string{"minimal", "low", "medium", "high", "max"}
NormalisedEfforts are the reasoning efforts catalogs write; adapters map them to their harness's own values (AdapterCapabilities.EffortMapping). ADR-0003.
Functions ¶
func DefaultCapabilities ¶
func DefaultCapabilities() []v1alpha1.AdapterCapabilities
DefaultCapabilities returns the embedded capability descriptors.
func DefaultKnownModels ¶
DefaultKnownModels returns the embedded known model ids, by harness.
func LoadDir ¶
LoadDir loads the catalog rooted at fsys and validates it (every phase of the LLD, all diagnostics collected). It returns the snapshot when there are no errors (warnings allowed, unless opts.Strict), nil otherwise; the diagnostics are sorted by file and line.
func ParseCapabilities ¶
func ParseCapabilities(data []byte) ([]v1alpha1.AdapterCapabilities, error)
ParseCapabilities reads a capabilities file (`factory validate --capabilities`): a JSON list of v1alpha1.AdapterCapabilities, or an object with a "capabilities" list (the embedded defaults' format).
Types ¶
type Assets ¶
type Assets struct {
// Prompts are the files under prompts/, parsed as text/template.
Prompts map[string]*Prompt
// Schemas are the *.json files under schemas/, compiled as JSON Schemas (draft 2020-12
// by default). They may $ref the v1alpha1 schemas by their $id, e.g. the base Result.
Schemas map[string]*jsonschema.Schema
// SchemaSources are the raw bytes of Schemas, by the same paths.
SchemaSources map[string][]byte
}
Assets are the non-object files of a catalog, keyed by their path relative to the catalog root (as TaskSpecs reference them: "prompts/implement.md.tmpl").
type Catalog ¶
type Catalog struct {
// SHA is the git commit the catalog was loaded from, or "dir:<sha256>" over the sorted
// file contents of a local directory.
SHA string
Providers map[string]*v1alpha1.Provider
Groups map[string]*v1alpha1.Group
Templates map[string]*v1alpha1.Template
// Rules are the standalone rules by name, and the inline rules by "<ruleset>/<rule>".
// They are as written: RuleSets hold the substituted, compiled versions.
Rules map[string]*v1alpha1.Rule
RuleSets map[string]*CompiledRuleSet
TaskSpecs map[string]*CompiledTaskSpec
Queues map[string]*v1alpha1.Queue
Pools map[string]*v1alpha1.Pool
// Programs holds every compiled "=" value of the catalog (rule actions after params
// substitution, TaskSpec fields), keyed by CEL source, for cel.EvalTree. Where
// expressions are on EffectiveRule.Where.
Programs cel.ProgramIndex
// Sources is where each object's document starts.
Sources map[ObjectKey]SourcePos
Assets Assets
}
Catalog is a validated catalog snapshot. It is immutable after LoadDir: the runtime swaps whole snapshots (atomic pointer) and never modifies one, so it is safe to share between goroutines.
type CompiledAction ¶
type CompiledAction struct {
// Type is the action's member: dispatch, set, notify, requestApproval, cancel, link or
// effect.
Type string
// Action is the typed action, after params substitution.
Action v1alpha1.Action
// Tree is the action's member as a YAML tree (maps, lists, scalars), for cel.EvalTree
// with Catalog.Programs; its "=" leaves are all compiled there.
Tree any
// Harness is the compiled dispatch.harness request, when it is a literal object.
Harness *patterns.Request
}
CompiledAction is one action of an EffectiveRule.
type CompiledRuleSet ¶
type CompiledRuleSet struct {
Spec *v1alpha1.RuleSet
// Providers are the provider instances spec.providerSelector matches, sorted.
Providers []string
Scope CompiledScope
// Rules are the effective rules after selection, exclude, defaults and overrides,
// ordered by priority (highest first), then name.
Rules []*EffectiveRule
}
CompiledRuleSet is a RuleSet with its selection resolved.
type CompiledScope ¶
CompiledScope is a RuleSet scope with its globs compiled. An empty list matches anything.
func (CompiledScope) MatchBranch ¶
func (s CompiledScope) MatchBranch(branch string) bool
MatchBranch reports whether a branch is in scope (Branches empty means any).
func (CompiledScope) MatchChannel ¶
func (s CompiledScope) MatchChannel(channel string) bool
MatchChannel reports whether a channel is in scope (Channels empty means any).
func (CompiledScope) MatchRepo ¶
func (s CompiledScope) MatchRepo(repo string) bool
MatchRepo reports whether repo ("owner/name") is in scope: it matches Repos (or Repos is empty) and no Exclude glob.
type CompiledTaskSpec ¶
type CompiledTaskSpec struct {
Spec *v1alpha1.TaskSpec
// Digest is "sha256:<hex>" of the spec's canonical JSON (Task.spec.taskSpec.digest).
Digest string
// Prompt is instructions.template; OutputSchema is output.schema (nil when unset).
Prompt *Prompt
OutputSchema *jsonschema.Schema
// OutputSchemaDocument is output.schema as one self-contained JSON document, what
// OutputSchema was compiled from: the file's raw bytes, or a compound document embedding
// the catalog schemas it refers to (see bundleSchema). Nil when OutputSchema is.
OutputSchemaDocument []byte
// Expressions are the "=" fields of the spec by field path
// ("spec.workspace.repos[0].ref"); their programs are also in Catalog.Programs.
Expressions map[string]*cel.Program
// Constraints is harness.allowed compiled or, when the TaskSpec has none, one
// constraint derived from harness.default (its harness, model and effort patterns; an
// unset one is "*"), for patterns.Resolve. Default is harness.default compiled (nil when
// unset).
Constraints []patterns.Constraint
Default *patterns.Request
}
CompiledTaskSpec is a TaskSpec with its assets, expressions and harness policy compiled.
func (*CompiledTaskSpec) ValidateInputs ¶
func (t *CompiledTaskSpec) ValidateInputs(inputs map[string]any) []error
ValidateInputs checks fully evaluated dispatch inputs against the declared inputs: every key is declared, required inputs without a default are present, and values have the declared type and are in the enum. It is the "input schema" of the LLD.
type EffectiveRule ¶
type EffectiveRule struct {
// Name is the rule's name ("<ruleset>/<rule>" for an inline rule).
Name string
// Rule is the rule after {{ params }} substitution with this RuleSet's params.
Rule *v1alpha1.Rule
// Params are the rule's params ← the RuleSet's defaults ← the RuleSet's overrides[rule].
Params map[string]any
// Where is the compiled where; an empty where compiles to a program that is always true.
Where *cel.Program
Actions []CompiledAction
// Providers are the RuleSet's providers the rule's providerSelector matches, plus
// v1alpha1.FactoryProvider when `on` has factory.* types; ["factory"] for a
// factory-only rule.
Providers []string
}
EffectiveRule is a rule as one RuleSet runs it.
type Error ¶
type Error struct {
Code string `json:"code"`
Message string `json:"message"`
File string `json:"file"`
Line int `json:"line"`
Object ObjectKey `json:"object,omitzero"`
Severity Severity `json:"severity"`
}
Error is one validation diagnostic. File is relative to the catalog root; Line is 1-based (0 when unknown). Message starts with the field path when there is one.
type Harnesses ¶
type Harnesses struct {
Capabilities []v1alpha1.AdapterCapabilities `json:"capabilities"`
KnownModels map[string][]string `json:"knownModels"`
}
Harnesses is the file format of the embedded defaults: capability descriptors plus the known model ids per harness.
type Options ¶
type Options struct {
// Capabilities are the harness adapters' capability descriptors. Nil means the embedded
// defaults (DefaultCapabilities).
Capabilities []v1alpha1.AdapterCapabilities
// KnownModels are the model ids each harness is known to offer, by harness name, for
// patterns.Subsumes. Nil means the embedded defaults (DefaultKnownModels).
KnownModels map[string][]string
// Strict turns warnings into errors.
Strict bool
// SHA, when set, is the snapshot's SHA instead of the directory hash (the git commit
// for catalogs loaded from git).
SHA string
}
Options configure a load.
type Prompt ¶
type Prompt struct {
Path string
// Text is the template source; Digest is "sha256:<hex>" of it (Task.spec.prompt.digest).
Text string
Digest string
Template *template.Template
}
Prompt is one prompt template.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package gitsource loads a catalog from a git ref: a shallow fetch into a temporary directory with the git CLI, then catalog.LoadDir on the catalog's directory in it, with the commit as the snapshot's SHA (design/workstreams/dispatcher-core/LLD/catalog.md §Loading).
|
Package gitsource loads a catalog from a git ref: a shallow fetch into a temporary directory with the git CLI, then catalog.LoadDir on the catalog's directory in it, with the commit as the snapshot's SHA (design/workstreams/dispatcher-core/LLD/catalog.md §Loading). |