mechanisms

Documentation

Overview

Package mechanisms is the curated Mechanism catalogue: a constraint-declared registry that the loop resolves into a deterministic total order (topo-sort with a stable canonical-ID tiebreak — ADR 0003). Each Mechanism declares its hook point, descriptor, and ordering constraints; the hook point is data, not package structure (the package-per-hook layout remains provisional — TDD §6.4).

The catalogue was ported from apogee-sim and A/B-validated, one Mechanism at a time, in Phase 4 (completed 2026-07-04); each Mechanism file registers its constructor and descriptor in its own init().

Index

• func Build(id domain.MechanismID, deps Deps) (domain.Mechanism, error)
• func Descriptors() []domain.MechanismDescriptor
• func KnownIDs() []domain.MechanismID
• type Deps

Functions

func Build

func Build(id domain.MechanismID, deps Deps) (domain.Mechanism, error)

Build constructs the catalogued Mechanism identified by id, injecting deps (D3). It is the seam cmd/apogee/wire.go drives for each enabled `mechanisms:` ID. An id absent from the catalogue is a loud error naming the known IDs and wrapping domain.ErrUnknownMechanism (so callers can match it with errors.Is), so a typo'd config key fails startup rather than silently disabling a Mechanism.

func Descriptors

func Descriptors() []domain.MechanismDescriptor

Descriptors returns every catalogued Mechanism's static descriptor, sorted by canonical ID and duplicate-free — the metadata the public surface (CataloguedMechanisms, ADR 0015 §3) exposes without building a Mechanism. Each returned descriptor is a copy with its slice fields cloned, so a caller cannot mutate the catalogue's rows.

func KnownIDs

func KnownIDs() []domain.MechanismID

KnownIDs returns the canonical IDs of every buildable Mechanism, sorted — the catalogue the config surface (and its unknown-ID error) reports as the valid `mechanisms:` keys.

Types

type Deps

type Deps struct {
	// Library is the confidence-tagged observation store the library observe/inject Mechanism reads
	// and writes (Phase-4 item 14; the store type landed in item 13). It is nil unless the `library`
	// Mechanism is enabled — the engine's buildEnabledMechanisms (internal/agent/loop.go, the single
	// Deps-deriving build path since the ADR 0015 wire.go collapse) constructs and Loads the store under
	// Config.LibraryDir and injects it here only then, so a config without `library` builds no store.
	// newLibrary refuses a nil store (errLibraryStoreRequired).
	Library *library.Store

	// Fingerprint is the resolved model identity the library Mechanism keys its store reads and writes
	// on (D3 — resolved once at wire time from the configured model id via library.ResolveFingerprint,
	// so the inject and observe halves share one identity rather than re-resolving per call). The zero
	// fingerprint (an unidentified model) leaves the Library inert. Only the library Mechanism reads it.
	Fingerprint domain.ModelFingerprint

	// LookPath resolves an executable name against the host PATH (exec.LookPath's contract). A
	// Mechanism that shells out probes its external commands ONCE at construction through this
	// seam and caches the resolved paths (D3 — autofix's formatter table), so fires never probe
	// and a test injects formatter availability without touching the real PATH. nil falls back
	// to exec.LookPath.
	LookPath func(string) (string, error)

	// GrammarConstraint is the D3-injected backend-capability gate for the grammar Mechanism
	// (catalogue Table A/C: grammar is backend-capability gated). It is true only when the
	// configured backend BOTH accepts a json_schema `response_format` constraint AND needs one
	// (the model does not emit native tool calls) — the apogee analog of apogee-sim's gate on
	// llama.cpp WITHOUT native tool-calls (`proxy.go:625-634` @pin). apogee has no such
	// backend-capability probe wired yet, and the provider wire itself carries no
	// `response_format` field yet (`internal/agent/loop.go` toProviderRequest drops SetExtra —
	// "response_format is a Phase-4 concern"), so buildEnabledMechanisms (internal/agent/loop.go — the
	// single Deps-deriving build path since the ADR 0015 wire.go collapse) never populates this and
	// grammar no-ops on every current backend (catalogue Table B: "may no-op on all current apogee
	// backends"). It is an inert forward seam like Library: a future backend probe populates it,
	// and grammar's fire path is exercised today only by tests that inject it true.
	GrammarConstraint bool
}

Deps are the construction-injected collaborators a catalogued Mechanism may need at BUILD time (D3 — a Mechanism's dependencies are injected once when it is constructed, never passed per hook call; hook signatures stay about conversation state). Every field is optional: a Mechanism that needs none ignores them. The set grows as the port waves land — a later wave adds a field here, populates it in cmd/apogee/wire.go, and its constructor reads it. Kept in internal/mechanisms (not domain) because these are host-supplied collaborators the catalogue wires, not part of the loop's construction surface.