registry

Documentation

Overview

Package registry defines the graph-backend adapter contract and a register/resolve surface keyed by adapter name.

It implements the smallest slice of graph-backend-adapter-contract §4 (adapter schema) and §8.2 (namespace tokens) needed to drive the built-in `none` adapter end-to-end: an Adapter interface, the declarative Schema value types, semantic-version ref parsing for refs of the form `dotagents-builtin:graph/<name>@<constraint>`, and a process-wide registry that resolves a ref to a registered adapter.

Index

• func ValidateSchema(s Schema) error
• type Adapter
• type Constraint
  • func ParseConstraint(s string) (Constraint, error)
  • func (c Constraint) Satisfies(v Version) bool
• type EdgeType
• type FieldSpec
• type FieldType
• type ImpactRadius
• type ImpactRequest
• type ImpactResult
• type NoteType
• type Ref
  • func ParseRef(ref string) (Ref, error)
• type Registry
  • func New() *Registry
  • func (r *Registry) Names() []string
  • func (r *Registry) Register(a Adapter) error
  • func (r *Registry) Resolve(ref string) (Adapter, error)
• type Schema
  • func LoadSchema(data []byte) (Schema, error)
• type Version
  • func ParseVersion(s string) (Version, error)
  • func (v Version) String() string

Functions

func ValidateSchema

func ValidateSchema(s Schema) error

ValidateSchema enforces the §4 invariants checkable without a corpus:

• name and version are present and version parses
• impact_radius.query is present and max_depth is non-negative
• every edge_type references declared note types (or none, when the schema declares no note types — the `none` adapter case)

Types

type Adapter

type Adapter interface {
	// Name is the adapter's short name (e.g. "none"). It must match the
	// name in Schema().
	Name() string
	// Schema returns the adapter's declarative schema (spec §4).
	Schema() Schema
	// ImpactRadius runs the adapter's impact-radius operation. The `none`
	// adapter returns the changed ids unchanged.
	ImpactRadius(req ImpactRequest) (ImpactResult, error)
}

Adapter is the contract every graph backend satisfies. The `none` adapter is the minimal conforming implementation: it declares an empty schema and a no-op impact radius.

type Constraint

type Constraint struct {
	// Caret is true for `^x.y.z` ranges; false for exact matches.
	Caret bool
	Base  Version
}

Constraint is a parsed version constraint. Only the caret range (`^x.y.z`) and an exact match are supported in v1 — these are the forms the spec's app-type-profiles use (e.g. `@^1.0`).

func ParseConstraint

func ParseConstraint(s string) (Constraint, error)

ParseConstraint parses a constraint string. A leading `^` selects a caret range; otherwise the string is parsed as an exact version.

func (Constraint) Satisfies

func (c Constraint) Satisfies(v Version) bool

Satisfies reports whether v satisfies the constraint.

• Exact: v equals the base.
• Caret with major >= 1: same major, and v >= base.
• Caret with major 0: same major+minor, and v >= base (npm-style ^0.x).

type EdgeType

type EdgeType struct {
	Name        string `yaml:"name" json:"name"`
	From        string `yaml:"from" json:"from"`
	To          string `yaml:"to" json:"to"`
	Cardinality string `yaml:"cardinality,omitempty" json:"cardinality,omitempty"`
	Signed      bool   `yaml:"signed,omitempty" json:"signed,omitempty"`
	WeightField string `yaml:"weight_field,omitempty" json:"weight_field,omitempty"`
	Derivation  bool   `yaml:"derivation,omitempty" json:"derivation,omitempty"`
}

EdgeType is a declared edge type in an adapter schema (spec §4).

type FieldSpec

type FieldSpec struct {
	Name       string   `yaml:"name" json:"name"`
	Type       string   `yaml:"type" json:"type"`
	Required   bool     `yaml:"required,omitempty" json:"required,omitempty"`
	Values     []string `yaml:"values,omitempty" json:"values,omitempty"`
	Derivation bool     `yaml:"derivation,omitempty" json:"derivation,omitempty"`
}

FieldSpec describes a single field on a note type (spec §4).

type FieldType

type FieldType string

FieldType enumerates the note/edge field types from spec §4.

type ImpactRadius

type ImpactRadius struct {
	Query         string `yaml:"query" json:"query"`
	MaxDepth      int    `yaml:"max_depth" json:"max_depth"`
	AlgorithmHint string `yaml:"algorithm_hint,omitempty" json:"algorithm_hint,omitempty"`
}

ImpactRadius is the required impact-radius declaration (spec §4).

type ImpactRequest

type ImpactRequest struct {
	// ChangedIDs are the node ids whose blast radius is requested. The DSL
	// binds these to the $changed_ids parameter.
	ChangedIDs []string
}

ImpactRequest is the input to an adapter's ImpactRadius operation.

type ImpactResult

type ImpactResult struct {
	// IDs are the impacted node ids. For the `none` adapter this is exactly
	// the input ChangedIDs (max_depth 0, no neighborhood expansion).
	IDs []string
}

ImpactResult is the output of an adapter's ImpactRadius operation. The `none` adapter returns ChangedIDs unchanged (no expansion).

type NoteType

type NoteType struct {
	Name   string      `yaml:"name" json:"name"`
	Fields []FieldSpec `yaml:"fields,omitempty" json:"fields,omitempty"`
}

NoteType is a declared note type in an adapter schema (spec §4).

type Ref

type Ref struct {
	// Name is the adapter's short name (e.g. "none").
	Name string
	// Builtin is true when the ref carried the dotagents-builtin source
	// prefix.
	Builtin bool
	// Constraint is the version constraint, or nil when the ref carried no
	// `@constraint` suffix.
	Constraint *Constraint
}

Ref is a parsed adapter backend reference.

func ParseRef

func ParseRef(ref string) (Ref, error)

ParseRef parses a backend ref. Accepted forms:

dotagents-builtin:graph/none@^1.0   → name=none, builtin, caret 1.0.0
dotagents-builtin:graph/none        → name=none, builtin, no constraint
none@1.0.0                          → name=none, exact constraint
none                                → name=none, no constraint

type Registry

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

Registry is a process-wide map of adapter name to Adapter. The zero value is not usable; construct with New.

func New

func New() *Registry

New returns an empty Registry.

func (*Registry) Names

func (r *Registry) Names() []string

Names returns the registered adapter names in sorted order.

func (*Registry) Register

func (r *Registry) Register(a Adapter) error

Register adds a in the registry keyed by its Name. It returns an error if the adapter is nil, has an empty name, or a name collides with an already-registered adapter.

func (*Registry) Resolve

func (r *Registry) Resolve(ref string) (Adapter, error)

Resolve looks up an adapter by a backend ref string of the form `dotagents-builtin:graph/<name>@<constraint>` (or the bare `<name>`). It returns an error if the ref cannot be parsed, the named adapter is not registered, or the registered adapter's version does not satisfy the ref's constraint.

type Schema

type Schema struct {
	Name             string       `yaml:"name" json:"name"`
	Version          string       `yaml:"version" json:"version"`
	Description      string       `yaml:"description,omitempty" json:"description,omitempty"`
	NoteTypes        []NoteType   `yaml:"note_types" json:"note_types"`
	EdgeTypes        []EdgeType   `yaml:"edge_types" json:"edge_types"`
	ImpactRadius     ImpactRadius `yaml:"impact_radius" json:"impact_radius"`
	StalenessDrivers []string     `yaml:"staleness_drivers,omitempty" json:"staleness_drivers,omitempty"`
}

Schema is the declarative adapter schema (spec §4). It captures only the fields the `none` adapter exercises end-to-end; richer fields (queries, materialized_views, env_predicates, planner hints) are added by later tasks in this plan.

func LoadSchema

func LoadSchema(data []byte) (Schema, error)

LoadSchema parses an adapter schema from its YAML form (spec §4) and validates the fields the contract requires. It is the loader + schema validator the `none` adapter and later adapters share.

type Version

type Version struct {
	Major int
	Minor int
	Patch int
}

Version is a parsed semantic version (major.minor.patch). Pre-release and build metadata are not modeled in v1 — adapter versions are plain triples.

func ParseVersion

func ParseVersion(s string) (Version, error)

ParseVersion parses a "major.minor.patch" string. Missing minor/patch components default to 0 (so "1" and "1.2" are accepted).

func (Version) String

func (v Version) String() string

String renders the version as "major.minor.patch".