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

	// Roles are the people this module is for: a role it can describe without
	// being told, because the grants it needs are its own permissions. "A role a
	// module declares opens that module's screens" is only a rule if the
	// declaration exists somewhere the kernel can read it, and before this field
	// nowhere did: the only roles in an installation were auth's two and whatever
	// the composition happened to list by hand, so nothing could check that a
	// granted role reached the screens its module serves, and an administrator
	// granting "editor" was granting a guess.
	//
	// Seeding is the composition's act, not this manifest's: apps/platformkit
	// builds auth.SeedRoles' defaults from these rows (its seedRoles), and
	// kit/app's Validate refuses a declaration that lies. A module that wants a
	// role nobody should get in every tenant declares nothing and lets the product
	// name it.
	Roles []RoleDecl

	// Events are the events this module emits, by name: "<module>.<event>",
	// inside the module's own namespace. A name is all the kernel needs to
	// refuse a route that would publish what no manifest promised, to name a
	// subscription's subject, and to expand a SubscribeAll module — so a module
	// whose payload it cannot describe (a hand-built document, a type that
	// marshals itself) still gets to emit by naming the event here.
	//
	// Every event a rest.Spec would publish has to appear in this list or in
	// Declared, or the app refuses to start: a module that emits something it
	// never promised is an integration nobody can find. Module.Emits is the one
	// list that says so; nothing reads these two fields separately.
	Events []string

	// Declared names emitted events with their payload types for outbox validation
	// and AsyncAPI. Emits prefers a typed declaration over the same bare Events
	// name; a bare event has no payload validation and is reported as uncovered.
	Declared []events.Declared

	// 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

	// Streams are the events this module lets a live connection watch, and who
	// may. A stream is a notice and never a payload, and an event nothing streams
	// stays exactly as it was: the durable path never reads this list. See Stream.
	Streams []Stream

	// 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
	// Views are immutable custom-screen descriptors, checked again after Routes.
	Views []screen.View

	// Tours is how this module's features teach themselves: instructions
	// anchored to published screens, read by whatever renders them and
	// validated twice — here, as a declaration, and after routes are
	// registered, against what the composition actually published. A
	// composition that selects no tour runner validates them all the same and
	// shows nothing.
	Tours []tour.Tour

	// Migrations is this capability's SQL at the filesystem root. Name owns
	// its append-only history; versions are local to this module. Composition
	// order determines which capability migrates first.
	Migrations fs.FS

	// Adopts is history this module takes over from another owner: the
	// versions another owner's ledger rows carry that are now files of
	// Migrations, under the same numbers. The reference modules declare the
	// files the foundation applied before each module owned its own SQL; a
	// module that never shared an owner declares nothing. See db.Adoption.
	Adopts []db.Adoption

	// RulesFrom is the first version of Migrations the runner's rule table guards,
	// and it travels to the kernel beside the files it describes. Zero guards every
	// file, which is right for a module added after the rules existed; a module
	// whose already-applied files would be refused names the version past the last
	// of them, because a rule cannot be refused on bytes that are immutable. The
	// number is the module's fact and the module states it. See db.MigrationSource.
	RulesFrom int64

	// PersonalData is this module's claim about the person columns in the SQL it
	// owns: which table holds a person's own id, which other columns name a person,
	// which text columns an identifier may have been copied into, and which uuid
	// columns name a row and not a person — or, for a module whose tables carry no
	// such column at all, the reason that is so.
	//
	// The kernel reads it three ways, which is what makes it a declaration and not
	// a comment: Validate refuses it against this module's own migration files
	// (kit/personaldata.Check, on the bytes and with no database), it is the list
	// the per-person erasure re-reads to prove it worked, and it is what the export
	// manifest says it asked. A module that adds a person column and files nothing
	// is refused at boot rather than discovered by a person's request. See ADR 0020.
	PersonalData personaldata.Declaration

	// Routes registers this module's operations, each with its authorization,
	// on the surface the kernel built for it. The module chooses a router —
	// r.Public, r.App, r.Ops — and writes a path relative to it; the prefix, the
	// module segment and the middleware chain are the kernel's to compose and
	// its to refuse. See httpx.Surfaces.
	Routes func(r httpx.Surfaces)

	// SystemAccess declares that this module has work no tenant transaction can
	// do, and what that work is. The kernel mints one cross-tenant credential per
	// module that declares it and hands it out while that module is being wired
	// (httpx.Surfaces.SystemToken); a module that takes one without declaring it
	// is refused at composition, and one that declares it and never takes it is
	// refused too — the declaration is read in both directions. The zero value
	// says the module crosses no tenant boundary, which is the answer for every
	// module but the few this repository holds.
	//
	// It declares a scope and not an authorization: who may make the request that
	// reaches the handler holding the token is that route's own guard, and
	// docs/adr/0006 says why the two are not the same question.
	SystemAccess SystemAccess

	// Moved is the addresses this module used to answer at and where each one
	// lives now. The kernel answers an old address with a redirect and nothing
	// else — 302 for a safe method, 307 for the rest, never cached, never a
	// second mount — by the same rules as its own migration table
	// (kit/httpx/aliases.go). A module that moves a page declares a row here
	// rather than writing a handler for the old address; the surface gate
	// refuses a route mounted at an address a row moves.
	Moved []Move
}

type Move struct {
	From, To string
}

type NavEntry struct {
	Label string
	// Screen is "<module>/<entity>", relative to the workspace: "task/tasks".
	Screen     string
	Permission string
}

type Permission struct {
	Key string

	// Label is the grant in the words of the module that defines it: "read
	// tasks", "manage roles". It is source-language text, the readable fallback
	// handed to the same Locale.Text(key, fallback) seam every other label in
	// this kernel uses, and the tenant's language for it lives under
	// `permission.<key>` in the module's own catalogue file.
	//
	// It exists because a refusal has to tell a person what they lack, and a
	// key does not: "AUTH_DENIED: this operation requires task:read" names a
	// token and leaves the reader to guess whether guessing is safe. Validate
	// refuses a permission with no label, and one labelled with its own key, so
	// the field cannot be filled by copying the thing it explains.
	Label 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
}

type RoleDecl struct {
	// Name is the role as it appears in the tenant's role table and on the
	// roles screen: a lower-case identifier, at most auth's MaxRoleName
	// characters, and not one of the two names auth owns (admin, member), which
	// Validate refuses rather than letting a module shadow.
	Name string

	// Grants are the permission keys this role holds, each one declared by this
	// module and none of them an operator's. An empty list is a role that grants
	// nothing — the shape auth's own member role holds by design, and the reason
	// a module may not declare one.
	Grants []string
}

type Stream struct {
	// Event is an event this module emits, spelled the way Emits spells it.
	Event string
	// Policy names who may watch it. The zero StreamPolicy is refused.
	Policy StreamPolicy
}

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

type SystemAccess struct {
	Reason string
}