module

type FieldDecl struct {
	Name string
	Type FieldType

	// Elem describes what a TypeList holds, when the module can say — or, on a
	// TypeMap whose keys are open (no Fields), what EVERY value holds, so a map
	// keyed by names the module cannot enumerate still has its values checked.
	// Ignored for every other type.
	//
	// It exists because the matchers that read a list read inside it:
	//
	//   any(invocations, .bin == "npm" && "--access" in .flags)
	//
	// is the form the spec documents, and it is where a command rule lives.
	// Without an element shape the collection is checked and the predicate
	// body is not, so `.bni` inside that expression would load and never fire —
	// precisely the silence declaring fields exists to prevent, reappearing one
	// level down.
	//
	// A list whose Elem is nil is a list of something unspecified, and a
	// predicate over it is left unchecked rather than refused. That is the
	// honest answer when a module has not said: unlike a map's keys, an
	// element's fields CAN be enumerated, so a module that knows them should
	// declare them and get the check.
	Elem *FieldDecl

	// Fields describes a TypeMap's or a list element's own fields, when the
	// module can enumerate them. Nil means it cannot, and reads of arbitrary
	// keys go unchecked rather than refused.
	Fields []FieldDecl
}

type FieldType string

type Input map[string]any

type KindDecl struct {
	// Name is what happened, and when — "PreFileCreate". It does not say which
	// module produced it: the registry knows that because the module declared
	// it, and it rejects a second module claiming the same name.
	Name string

	// Fields a matcher may read on this kind.
	Fields []FieldDecl
}

type Module interface {
	// Name identifies the module — how the engine reports what produced an
	// event, and how a module is referred to when one is switched off.
	Name() string

	// Kinds are the events this module can produce, with the fields each
	// carries.
	//
	// Declared rather than discovered, so that a matcher naming a field the
	// kind does not have is refused when the guardrail loads. A rule that
	// silently never fires is worse than one that will not load: the first
	// looks like a rule being satisfied.
	Kinds() []KindDecl

	// Extract turns what a harness reported into events. Producing none is
	// ordinary — most of what happens in a session concerns most modules not
	// at all.
	//
	// A module may return events ALONGSIDE a non-nil error, and a caller must
	// not discard them: one input a module could not make sense of is not a
	// reason to drop the events it did produce from the rest.
	Extract(Input) ([]event.Event, error)
}

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