module

type Module struct {
	// Name is the module's namespace: its events are prefixed with it, so an
	// event name says which module emitted it. Permissions are named after the
	// resource they guard, not after the module, because a permission outlives
	// the module that first defined it.
	Name string

	// Permissions are the permission keys this module defines, "<resource>:<action>".
	Permissions []Permission

	// Events are the event names this module emits, "<name>.<event>". Every
	// event a rest.Spec would publish has to appear here, or the app refuses to
	// start: a module that emits something it never promised is an integration
	// nobody can find.
	Events []string

	// Subscriptions are the events this module handles. The worker role
	// subscribes each one; the name has to be an event some module emits.
	Subscriptions []events.Subscription

	// SubscribeAll says this module handles every event the application emits,
	// whichever module emits it: the kernel expands the one subscription above
	// into one per declared event, after every manifest has been read.
	//
	// There is one such module, modules/audit, and the field exists because the
	// alternative failed quietly. main used to compute the list and hand it over
	// as a dependency, which was correct only while audit was composed last: a
	// module listed after it was a module nothing recorded, and nothing said so.
	//
	// A manifest that sets it declares exactly one subscription, with no Name:
	// the name is what the kernel fills in, once per event.
	SubscribeAll bool

	// Jobs are this module's periodic work. The worker role schedules each one,
	// and exactly one instance in the cluster runs it per tick.
	Jobs []jobs.Job

	// Nav is where this module appears in navigation.
	Nav []NavEntry

	// Migrations is this module's SQL, with the files at the root of the given
	// fs.FS. Every module in this repository leaves it nil and puts its SQL in
	// migrations/ instead, which is where ARCHITECTURE.md says SQL lives; the
	// field is the door for a module that ships its own, and the files it
	// carries are still numbered uniquely across the whole application, because
	// there is one ledger. app.Run refuses a collision.
	Migrations fs.FS

	// Routes registers this module's operations, each with its authorization.
	Routes func(api *httpx.API)
}

type NavEntry struct {
	Label      string
	Path       string
	Permission string
}

type Permission struct {
	Key string

	// Operator says this permission belongs to the installation rather than to
	// a customer: only the operator's own tenant may exercise it at all, and no
	// wildcard satisfies it — a role has to name it.
	//
	// It is a field on the manifest as well as a route declaration
	// (httpx.OperatorPermission) because the two have to agree, and a check
	// needs both sides to read. kit/app refuses to start when a route and the
	// manifest that defines its permission disagree, naming both: a control
	// plane route that declared the ordinary kind would be reachable by every
	// customer's administrator, and an ordinary route that declared this one
	// would be reachable by nobody but the operator.
	Operator bool
}