catalog

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Oct 28, 2026 License: AGPL-3.0 Imports: 27 Imported by: 0

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

View Source
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).

View Source
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

View Source
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

func DefaultKnownModels() map[string][]string

DefaultKnownModels returns the embedded known model ids, by harness.

func HasErrors

func HasErrors(errs []Error) bool

HasErrors reports whether any diagnostic is an error (warnings don't count).

func LoadDir

func LoadDir(fsys fs.FS, opts Options) (*Catalog, []Error)

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).

func ParseKnownModels

func ParseKnownModels(data []byte) (map[string][]string, error)

ParseKnownModels reads a known-models file (`factory validate --known-models`): a JSON object of model ids by harness, e.g. {"codex": ["gpt-5-codex"]}.

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

type CompiledScope struct {
	Repos, Exclude, Channels, Branches []patterns.Pattern
}

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.

func (Error) Error

func (e Error) Error() string

Error formats the diagnostic as `file:line: CODE message`, warnings as `file:line: CODE warning: message`.

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 ObjectKey

type ObjectKey struct {
	Kind string `json:"kind"`
	Name string `json:"name"`
}

ObjectKey identifies a catalog object. Inline rules are named "<ruleset>/<rule>".

func (ObjectKey) String

func (k ObjectKey) String() string

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.

type Severity

type Severity string

Severity says whether a diagnostic fails the catalog.

const (
	SeverityError   Severity = "error"
	SeverityWarning Severity = "warning"
)

Severities. Warnings never fail a load unless Options.Strict is set.

type SourcePos

type SourcePos struct {
	File string `json:"file"`
	Line int    `json:"line"`
}

SourcePos is where an object's document starts.

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).

Jump to

Keyboard shortcuts

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