catalog

type Action struct {
	// Key is the contract: what the portal, the order and a later requirement or
	// capability name. Lower-case letters, digits and dashes; unique per product.
	Key string `json:"key"`
	// Message is the message the lifecycle process starts or waits at for this
	// action — the process's business, so renaming it changes the mapping and not
	// what an order asks for. Unique per product.
	Message string `json:"message"`
	// Effect is what the action does to the position; one of the Effect constants.
	Effect string `json:"effect"`
	// Triggers says who may ask for it; Trigger constants. The order starts the
	// provision action, so it names none.
	Triggers []string `json:"triggers,omitempty"`
	// Labels is what a button says, per language. A missing one is a reported
	// translation gap, never a refusal (ADR-0414).
	Labels map[string]string `json:"labels,omitempty"`
	// Form names an Atlas form for what the action needs — the new size, the reason
	// (ADR-0358). Like a product's configuration form, it is not resolved here.
	Form string `json:"form,omitempty"`
	// Outcomes maps an outcome to the event type it is published under. An outcome
	// it does not name is published as <message>.<outcome> (ADR-0429 §3).
	Outcomes map[string]string `json:"outcomes,omitempty"`
}

type Approval struct {
	Kind ApprovalKind `json:"kind"`
	// Ref names the principal for KindFixed or the group for KindRole. It is empty
	// for the kinds that need no target, and Publish refuses a rule that needs one
	// and has none.
	Ref string `json:"ref,omitempty"`
}

type ApprovalKind string

type ApproverLookup interface {
	// Account reports whether this names an account that can hold a task. Matched
	// the way an assignee is matched: by username, ignoring case.
	Account(username string) bool
	// Group reports whether this names a group, by id or by name, ignoring case —
	// which is the order and the tolerance candidate groups are matched with.
	Group(ref string) bool
}

type ApproverProblem struct {
	ItemID string `json:"itemId"`
	// HomeCatalog is where the product is maintained, because that is where the
	// reader has to go to correct it.
	HomeCatalog string `json:"homeCatalog"`
	Kind        string `json:"kind"`
	// Ref is what the rule names, echoed exactly. A reference that differs from
	// what its author believes they typed is the ordinary case here, so the report
	// shows the stored string rather than a tidied one.
	Ref string `json:"ref"`
	// Why is written for the person who has to fix it, and names the thing that
	// does not exist rather than the rule that is invalid.
	Why string `json:"why"`
}

type ApproverReport struct {
	// Checked is how many products were examined, so an empty Problems list can be
	// read as "none of 240" rather than as "nothing was looked at".
	Checked  int               `json:"checked"`
	Problems []ApproverProblem `json:"problems"`
}

type Baselines interface {
	ImportBaselines() (map[string]string, error)
	RecordImportBaselines(hashes map[string]string) error
}

type Binding struct {
	Process string `json:"process"`
	Message string `json:"message,omitempty"`
}

type Catalog struct {
	ID    string            `json:"id"`
	Texts map[string]string `json:"texts"`
	// Rank resolves the one-catalogue-per-user rule against directory group
	// membership, which is many-to-many: the highest rank a user reaches wins.
	// Ranks are unique across catalogues, and Publish refuses a tie rather than
	// falling back to an id nobody chose.
	Rank int `json:"rank"`
	// Languages are the language tags this catalogue offers. A release proves every
	// item it carries has a text for each, and a companion record forbids declaring
	// one the portal interface does not have.
	Languages []string `json:"languages"`
	// Items are the item ids this catalogue offers, whatever their home.
	Items []string `json:"items"`
	// Groups are the directory or Atlas groups whose members reach this catalogue.
	Groups []string `json:"groups,omitempty"`
	// Members are the object axis (ADR-0071/0180/0278): the role says a caller may
	// maintain catalogues at all, this says which ones. Without it a product
	// manager can rebuild and publish every customer's catalogue, with nothing in
	// the way but not knowing an id — which ADR-0278 states plainly is not an
	// access control.
	Members []Member `json:"members,omitempty"`
	// Theme is this catalogue's appearance, empty for the instance's own. Set by
	// an administrator rather than by whoever maintains the catalogue
	// (decision 12).
	Theme Theme `json:"theme,omitempty"`
	// Edges are the structure and precedence between the items this catalogue
	// offers. They belong to the catalogue rather than to the items because they
	// are what its release is computed from, and because the same two products can
	// relate differently in two catalogues.
	Edges []Edge `json:"edges,omitempty"`
	// OwnerID is whoever created it, because creation is the one moment where
	// there is nobody to ask. The owner may always read, write and share.
	OwnerID string `json:"ownerId,omitempty"`
	// Revision is optimistic concurrency, the same field and the same rule
	// [Item.Revision] and the capability map carry.
	//
	// A catalogue's patch is partial, so it cannot clear a field nobody mentioned
	// the way a product's full replace could. What it can still lose is a list:
	// Items, Edges and Members are replaced whole when sent, and the surfaces that
	// send them compute the new value from a snapshot — adding one product posts
	// every product plus that one. Two maintainers adding a product a second apart,
	// and the second write is the first one's disappearance, with no error and no
	// trace.
	//
	// Zero in a patch means the caller stated no precondition and the write is
	// unconditional, which is right for a form whose every field is on the screen
	// in front of somebody. The caller holding a snapshot is the one that should
	// say so. A catalogue itself is never at zero: it is created at one, so there
	// is always a revision to hold on to.
	//
	// Every writer advances it, and that is not a detail — a path that changes a
	// catalogue without advancing it is a path whose changes a stale caller
	// overwrites in silence. TestEveryWriterAdvancesTheRevision names them all.
	Revision  int64 `json:"revision"`
	CreatedAt int64 `json:"createdAt"`
	UpdatedAt int64 `json:"updatedAt"`
}

type CatchPoint struct {
	Element    string
	Message    string
	Correlated bool
}

type ChildRef struct {
	Ref      string   `json:"ref"`
	Version  int      `json:"version"`
	Title    string   `json:"title,omitempty"`
	Passages []string `json:"passages,omitempty"`
}

type ContentSource struct {
	// Source is the configured source's id.
	Source string `json:"source"`
	// Primary is the language whose page names the pictures.
	Primary string `json:"primary"`
	// Pages are the bound pages by language tag.
	Pages map[string]PageRef `json:"pages"`
}

type ContentSources interface {
	Sources() ([]contentsource.Source, error)
	Open(id string) (contentsource.Source, contentsource.Adapter, error)
}

type ContentState struct {
	ItemID string `json:"itemId"`
	Source string `json:"source,omitempty"`
	// LastChecked is when the recheck last ran for it, and LastPassed when it
	// last passed, in the server's Unix nanoseconds.
	LastChecked int64 `json:"lastChecked,omitempty"`
	LastPassed  int64 `json:"lastPassed,omitempty"`
	// Quarantine is set from the first failed recheck until a refresh passes.
	// A recheck that passes again on its own does not lift it: the content
	// Atlas holds is the content that was in question.
	Quarantine *Quarantine `json:"quarantine,omitempty"`
	// Distrusted is the start of the latest quarantine a refresh lifted. Content
	// copied before it is the content that was in question, and it stays
	// withheld wherever it still is — in the releases published before the
	// refresh — while the refreshed copy, taken after, is shown.
	Distrusted int64 `json:"distrusted,omitempty"`
	// Own is what the product carried before it was first bound: the product
	// manager's own description, keywords and picture, which the bound content
	// replaced. An unlink puts it back (§ 6, amended), so unbinding a product
	// returns it to how it was rather than leaving it described by pages that no
	// longer supply it. Nil for a binding made before this was kept, which an
	// unlink then treats as before: the last copy stays.
	//
	// Kept here and not on the item, because it is no part of what the shop is
	// offered: a release never carries it, and a quarantine never withholds it.
	Own *OwnContent `json:"own,omitempty"`
}

type Document struct {
	Catalogs []Catalog `json:"catalogs"`
	Products []Item    `json:"products"`
	// Publish asks for a release of every catalogue in the document once it is
	// written, validated before anything is.
	Publish bool `json:"publish,omitempty"`
	// Edges are the structure and precedence between the document's products when
	// it carries products alone (ADR-0451). Edges belong to a
	// catalogue, so these land in the catalogue the products are imported into
	// (?into=), and a document carrying them is refused without one.
	Edges []Edge `json:"edges,omitempty"`
	// Processes are the BPMN models the products are bound to, deployed by the
	// import before the catalogues are written (ADR-0451).
	Processes []Process `json:"processes,omitempty"`
	// MissingProcesses names the processes an export was asked to carry and could
	// not, because the exporting server has none deployed under that id. An import
	// reads nothing from it; it is there for the person holding the file.
	MissingProcesses []string `json:"missingProcesses,omitempty"`
}

type DocumentProblem struct {
	// Subject is "catalog:<id>" or "product:<id>", or "document" for the whole.
	Subject string `json:"subject"`
	Problem string `json:"problem"`
}

type DocumentResult struct {
	// DryRun says nothing was written: the answer is the plan.
	DryRun  bool     `json:"dryRun,omitempty"`
	Created []string `json:"created"`
	Updated []string `json:"updated"`
	// Artifacts is every catalogue, product and process of the document, with how
	// it compares to this server's and what the import did with it, or would.
	Artifacts []importplan.Artifact `json:"artifacts,omitempty"`
	Releases  []Release             `json:"releases,omitempty"`
	// Warnings are what the releases leave exposed (AnswerWarnings), by product.
	Warnings []DocumentProblem `json:"warnings,omitempty"`
	// Deployed names the document's processes this import deployed, and Unchanged
	// those whose newest deployed version already was the document's model.
	Deployed  []string `json:"deployed,omitempty"`
	Unchanged []string `json:"unchanged,omitempty"`
}

type Edge struct {
	From string   `json:"from"`
	To   string   `json:"to"`
	Kind EdgeKind `json:"kind"`
}

type EdgeKind string

type EntryPointLookup interface {
	// EntryPoints returns the message names of the process's root message start
	// events, whether it has a none start, and whether any version is deployed.
	EntryPoints(processID string) (messages []string, hasNone bool, deployed bool)
}

type ExportChoice struct {
	ID    string            `json:"id"`
	Texts map[string]string `json:"texts"`
	Bound bool              `json:"bound"`
}

type FormField struct {
	Key string
	// NotPersonal is the form author's word that this answer names nobody: the
	// custom property personal=false on the field. It quiets
	// [AnswerWarnings] for this field; nothing else reads it.
	NotPersonal bool
}

type FormFieldLookup interface {
	FormFields(formID string) (fields []FormField, found bool)
}

type FulfilmentProblem struct {
	// ItemID and HomeCatalog are empty for a problem on the shared path, which
	// belongs to no single product and stops every order alike.
	ItemID      string `json:"itemId,omitempty"`
	HomeCatalog string `json:"homeCatalog,omitempty"`
	// Stage says where on the path this sits: "order", "approval", "provision" or
	// "deprovision". It is what tells a reader whether nothing can be ordered at
	// all or only this one service cannot be given back.
	Stage string `json:"stage"`
	// ProcessID is the process the binding names, echoed exactly.
	ProcessID string `json:"processId"`
	// JobType is set where the process is deployed and one of its job types is
	// unserved. Empty where the process itself is missing.
	JobType string `json:"jobType,omitempty"`
	// Why is written for the person who has to fix it and names the thing that is
	// absent, not the binding that is invalid.
	Why string `json:"why"`
}

type FulfilmentReport struct {
	// Checked is how many offered services were examined, so an empty Problems
	// list reads as "none of 10" rather than as "nothing was looked at".
	Checked int `json:"checked"`
	// Releases names the releases the products came from, so a reader can tell
	// whether the report is about what they just published.
	Releases []string            `json:"releases"`
	Problems []FulfilmentProblem `json:"problems"`
	// Remainder is, for each product converted to a lifecycle process, how many
	// order lines still start one of the processes it bound before (ADR-0427) — the
	// count that says when those processes may be retired. Empty where nothing was
	// converted or nothing is left.
	Remainder []Remainder `json:"remainder"`
}

type Import struct {
	Items []Item `json:"items"`
	Edges []Edge `json:"edges"`
	// Skipped names what was left out and why, in the model's own words where it
	// has them.
	Skipped []string `json:"skipped"`
}

type Input struct {
	// CatalogID names the catalogue this publish is *of*. Everything computed
	// below — the schedule, the structure, the standing lists — is that one
	// catalogue's, and [Items] and [Edges] are its own.
	//
	// The other catalogues are here for one question, and only one: a rank is
	// unique across the set, so a tie can only be seen against everybody else. It
	// was easy to miss that the rest of the set is not the subject, and missing it
	// cost a real defect — every other catalogue's products were resolved against
	// *this* catalogue's item list, so every one of them came back "unknown item",
	// and a catalogue could be published only while every other catalogue was
	// empty. Publishing A blamed B, publishing B blamed A, and neither message
	// named the catalogue the caller had asked to publish.
	//
	// Empty means "there is no other catalogue to be", which is true of a single
	// one and of nothing else — see [Publish], which refuses the ambiguous case
	// rather than picking a reading.
	CatalogID string
	Catalogs  []Catalog
	Items     []Item
	Edges     []Edge
}

type Item struct {
	ID string `json:"id"`
	// HomeCatalog is the catalogue whose scope governs editing this item. An item
	// is referenced by catalogues rather than owned by one — it legitimately appears
	// in several — so scope cannot be inherited from "the catalogue it is in", and a
	// per-item member list is the per-artifact ACL ADR-0071 refused. One home, and
	// every other catalogue includes it read-only.
	HomeCatalog string `json:"homeCatalog"`
	State       State  `json:"state"`
	// Texts holds the item's name per language tag. A release proves it carries one
	// for every language its catalogue declares.
	Texts map[string]string `json:"texts"`
	// Descriptions is what this product *is*, per language tag, beside the name
	// Texts carries. Empty is the ordinary state for a product whose name says
	// enough, and means no description anywhere rather than an empty one.
	//
	// # Why per language and not one string
	//
	// Every other text a person reads off a product is per locale, and this is the
	// one somebody reads when the name was not enough — which is exactly when not
	// being able to read it matters. A catalogue declaring German and French could
	// otherwise translate the name of a thing and not the sentence explaining it.
	//
	// It is deliberately not Keywords, which is flat for the opposite reason:
	// keywords are for *finding* and a searcher's language is not the catalogue's,
	// while a description is for *showing* and is read in the language the portal
	// is being read in.
	//
	// # What a release demands of it
	//
	// Nothing, until there is one. A product with no description publishes, because
	// not every product needs a paragraph. A product with a description in one of
	// the catalogue's declared languages and not another does not, because that is
	// a portal where one audience is told what the thing is and the other is shown
	// an empty panel — the half-translated catalogue the name check already
	// refuses, in the field a reader turns to second.
	Descriptions map[string]string `json:"descriptions,omitempty"`
	// Rich is the description as its content source lays it out, per language
	// tag — headings, lists, tables, panels, images, embedded items — beside the
	// plain Descriptions a search and a reader without it use (ADR-0491, amendment
	// of 2026-10-28). Only a link or a refresh writes it; a save never does.
	Rich      map[string][]contentsource.Rich `json:"rich,omitempty"`
	Lifecycle Lifecycle                       `json:"lifecycle,omitempty"`
	Variants  []Variant                       `json:"variants,omitempty"`
	Approval  Approval                        `json:"approval"`
	// ProvisionProcess and DeprovisionProcess are the BPMN process ids bound to this
	// item. Both are required to publish: a catalogue that can only grant is not a
	// lifecycle, and the day somebody must revoke at scale is the wrong day to find
	// the process was never written.
	ProvisionProcess   string `json:"provisionProcess"`
	DeprovisionProcess string `json:"deprovisionProcess"`
	// LifecycleProcess binds ONE process for the whole of this item's lifecycle, in
	// place of the two ids above (ADR-0425). Each operation is a message start event
	// of it, named in Operations: provision and deprovision are required, change is
	// optional. An item carries either the two ids or this, never both.
	//
	// The operation is the contract and the message name the process's own
	// business, the way a published interface maps an entry-point name to an
	// element (ADR-0373): renaming a start event changes the mapping, not what an
	// order asks for.
	LifecycleProcess string            `json:"lifecycleProcess,omitempty"`
	Operations       map[string]string `json:"operations,omitempty"`
	// LifecycleForm says how the lifecycle process runs: "per-operation" (the
	// default, and what empty means) starts an instance for every operation;
	// "per-position" starts one instance per order position at provisioning and
	// delivers every later operation to it
	// (ADR-0428). Declared
	// rather than read off the diagram, so a catch event somebody adds to a model
	// cannot silently change how a product is returned.
	LifecycleForm string `json:"lifecycleForm,omitempty"`
	// Actions is the product's open list of actions, in place of Operations
	// (ADR-0429): every thing that can be asked of a position, each with an
	// effect the order interprets, the triggers that may ask for it, and the
	// message the lifecycle process starts or waits at. An item carries either
	// Operations or Actions, never both; one that still carries Operations is
	// read as the actions they mean (ActionList), so nothing is migrated.
	Actions []Action `json:"actions,omitempty"`
	// CommandedBy names, by their portable keys (ADR-0134), the process applications
	// whose processes may issue this product's actions with a shop command task
	// (ADR-0429 §10, decision 1) — an HR leaver process returning a right, a
	// maintenance process resetting a password. Only an action an operator or a
	// system may ask for can be issued so. Empty, which is the default, means no
	// process may command it.
	//
	// It is read from the newest release at the moment a task commands, not frozen
	// on the order: it says which automation the operator trusts with what somebody
	// holds, and taking an application off the list must stop it for every right
	// already held, not only for the ones ordered afterwards.
	CommandedBy []string `json:"commandedBy,omitempty"`
	// MultipleAllowed says whether a principal may hold this item more than once —
	// two licences, two mailboxes. Where it is false the basket marks an item the
	// orderer already holds as held, and skips it.
	MultipleAllowed bool `json:"multipleAllowed,omitempty"`
	// Targets is what this item is called in the systems that actually hold it, and
	// it is what lets a commissioning load attribute a right it found to this item
	// (ADR-0333). Empty is the ordinary state for an
	// item nothing outside Atlas grants, and it means no load will ever name it.
	//
	// Several are allowed: one service is legitimately two groups. The same ref
	// twice is not, and [Publish] refuses it — an observation matching two items
	// cannot be attributed, and guessing between them would write evidence Atlas
	// invented.
	Targets []TargetRef `json:"targets,omitempty"`
	// MaxDays is how long a right this product grants may last, in days, or zero
	// for one that does not end (ADR-0344). It is a
	// **ceiling declared as policy** — nobody holds this for more than ninety days
	// — and not a date somebody chose; an order cannot yet name a shorter end
	// within it.
	//
	// It reaches a grant through the release, like the bindings and the approval
	// rule beside it: a ceiling relaxed in the catalogue next week must not lengthen
	// a right granted this week under the stricter one.
	//
	// It never applies to an adopted or legacy right. A commissioning load records
	// a found right's start as the moment it was found, so a ceiling measured from
	// it would schedule an entire estate to expire on the anniversary of the day
	// somebody switched the portal on.
	MaxDays int `json:"maxDays,omitempty"`
	// Eligible narrows the catalogue's audience for this one product: the group ids
	// whose members may **receive** it. Empty is the ordinary case and means no
	// narrowing (ADR-0347).
	//
	// # Why an item needs this when a catalogue already has an audience
	//
	// Because a person sees exactly one catalogue — the highest-ranked one their
	// groups reach — so "put it in a narrower catalogue" is not a workaround. A
	// second catalogue does not give anybody a second shop; it is simply hidden
	// behind the one they already reach. A product that should be available to part
	// of a catalogue's audience could not be expressed at all.
	//
	// # Why empty is not fail-open
	//
	// [Catalog.ReachedBy] is fail-closed and stays the gate: nothing here is
	// reachable by somebody outside the catalogue's audience, whatever this says.
	// This only ever *narrows* that, so an empty list inherits a restriction rather
	// than removing one — the opposite of a catalogue with no groups, which would
	// otherwise be a shop open to everybody while somebody is still filling it.
	//
	// # Who is checked
	//
	// The **recipient**, never the orderer. A manager ordering a workplace for a
	// new hire is the ordinary case and must keep working; the question this
	// answers is who may end up holding the thing, and that is the person it is
	// for. It reaches an order through the release like the ceiling and the
	// approval rule beside it, so a restriction relaxed next week cannot retroact
	// on an order placed this week and a restriction *added* next week cannot
	// invalidate one already approved.
	Eligible []string `json:"eligible,omitempty"`
	// Keywords are the words somebody might search for that are not the product's
	// name: synonyms, the vendor's own term, the abbreviation everybody uses, the
	// thing it replaced (ADR-0355).
	//
	// # Why this exists rather than searching the name alone
	//
	// The story it serves names the case exactly: find a service *when the exact
	// product name is not known*. A search over names answers only for somebody who
	// already knows what the thing is called, which is the person who least needs
	// a search.
	//
	// # Why one flat list and not one per language
	//
	// Every other text on an item is per locale, and this deliberately is not. A
	// synonym list is for **finding**, not for displaying, and a searcher's language
	// is not the catalogue's: somebody reading a German catalogue types "laptop" as
	// readily as "Notebook", and an abbreviation like "M365" belongs to no language
	// at all. Splitting the list by locale would hide a term from exactly the person
	// who needed it, and would ask a product manager to maintain in two places what
	// they think of once.
	//
	// It travels into the release like everything else here, so a term added next
	// week does not change what an order placed this week was placed against — which
	// matters less for a search than for a rule, and is still the property that
	// makes a release a release.
	Keywords []string `json:"keywords,omitempty"`
	// ConfigForm names the Atlas form somebody fills in when they order this
	// product: the cost centre, the site, the employee number — whatever this one
	// product needs that its name does not say
	// (ADR-0358). Empty is the
	// ordinary case and means the product is fully described by what it is.
	//
	// # Why a form id and not a field list of its own
	//
	// Atlas already has forms: a definition with an id, an editor, a renderer, a
	// generator, and two surfaces rendering them. A second way to declare "these
	// are the fields somebody fills in" would be a second thing to author, a second
	// thing to render, and a second set of field types to keep level with the
	// first. The catalogue names an id and interprets nothing.
	//
	// # What the catalogue does *not* do with it
	//
	// It never resolves it. The form store is the `api` package's and this package
	// cannot see it, exactly as it cannot see which processes are deployed — and
	// for the same reason the two provisioning bindings are stored as plain ids.
	// The authoring screen offers only forms that exist, which is where that check
	// belongs: at the moment somebody chooses, not at the moment somebody orders.
	//
	// # Why the release freezes the id and not the form
	//
	// A release freezes what an order was placed against, and the reason is always
	// the same: a rule relaxed next week must not change what somebody was held to
	// this week. That argument is about *rules*. A form is a set of questions, and
	// what has to survive is the **answers** — which the order line carries, with
	// their field keys, for as long as the order exists. "Cost centre 4711" stays
	// true whatever the form does afterwards.
	//
	// The honest cost is stated in the record: a form that gains a field next week
	// leaves every earlier order without a value for it, and a provisioning process
	// that reads it finds nothing. That is true of every variable a process reads
	// and is the process's business; copying a form-js document into every release
	// would put a rendering artifact inside a design-time model that has kept
	// rendering out of itself on purpose, and would send it to every browser that
	// opens the portal.
	ConfigForm string `json:"configForm,omitempty"`
	// Price is what this product costs, written as the catalogue's maintainer wants
	// it read — "CHF 1'200.–", "49.– / Monat", "im Grundpaket enthalten"
	// (ADR-0361). Empty is the ordinary case
	// and means the catalogue says nothing about cost.
	//
	// # Why a string and not a number with a currency
	//
	// Because it is **displayed and never computed**. A number invites a total, a
	// total invites two products in different currencies, and that invites a rate
	// and a date — a money model, decided by an installation's finance rules and not
	// by this package. Everything that makes a price *arithmetic* is absent on
	// purpose, and a string is the honest shape of "this is what it says on the
	// shelf".
	//
	// The cost of that is stated rather than hidden: nothing can add these up. The
	// surface that needs a figure most is the approval, and an approval decides one
	// line — so the one number it shows is the one number it needs. A basket total
	// would need the money model above, and that is a different measure.
	//
	// # Why it is frozen into the release like a rule
	//
	// It is not a rule, and it travels like one anyway. An approver saw a figure and
	// decided on it; a catalogue edit next week must not make the record show a
	// different figure than the one that was approved. That is the same sentence as
	// the approval rule's and the ceiling's, and it is the reason this is on the
	// line as well as in the release.
	Price string `json:"price,omitempty"`
	// Category is the heading this product sits under in the portal — "Arbeitsplatz",
	// "Kommunikation", "Fachanwendungen" (ADR-0360).
	// Empty is the ordinary case and puts the product under the heading the portal
	// names for products that have none.
	//
	// # Why a field and not an entity
	//
	// Because it is **a heading and nothing else**. An entity would carry its own
	// texts, its own ordering, its own visibility and its own lifecycle, and each of
	// those is a thing to publish, migrate and get wrong. A heading has none of them:
	// it is the word above a column.
	//
	// The costs are real and stated rather than hidden. A category has **no ordering
	// of its own** — there is nothing on a string to sort by, and inventing a rank
	// here would be the entity arriving through the back door, so the portal sorts
	// alphabetically. And two spellings are two categories, with nothing to notice
	// that "Arbeitsplatz" and "Arbeitsplätze" were meant as one.
	//
	// If either of those turns out to matter, the answer is the entity, and this
	// field is what it would be migrated from.
	//
	// # What this string is, now that the heading is translatable
	// (ADR-0412)
	//
	// The third cost ADR-0360 recorded was that a heading has no translation. It has
	// one now, in [Item.CategoryTexts] below — and this field did not become it. It
	// is **the key**: what the portal groups by, what a search hit sets to open the
	// cascade at the right column, and what an already published release already
	// holds. The translations are how it is *rendered*.
	//
	// That split is the whole of the decision, and it is what makes the change
	// additive. Had the string become a map, two products would be one category when
	// their German agreed and two when their French did not — a heading that splits
	// in a language nobody publishing it reads. Grouping by one value that no reader
	// ever has to see keeps "same category" a fact about the catalogue rather than
	// about the reader.
	//
	// Where translations are present the key never has to be a word: a stable slug
	// survives the maintainer deciding the German wording was wrong. Where they are
	// absent — every product written before the field existed, every single-language
	// catalogue — the key is the word, and it is what every language renders. That
	// is the old behaviour exactly, which is why no stored record had to be migrated.
	Category string `json:"category,omitempty"`
	// CategoryTexts is [Item.Category] per language tag: the heading as the reader
	// of this portal reads it, where the key above is what everything groups by.
	//
	// Empty is the ordinary state and means the key renders in every language — the
	// state of every product written before this field and of every catalogue that
	// declares one language.
	//
	// # What a release demands of it
	//
	// The rule [Item.Descriptions] follows, for the same reason: optional as a
	// whole, all-or-nothing once there is one. A heading translated into German and
	// not French is a portal where one audience reads its own column head and the
	// other reads somebody else's, and nothing says so, because the fallback renders
	// and looks deliberate.
	//
	// Beside that, a translation without a key is refused. It would put the product
	// in the bucket for products carrying no heading — under a column head reading
	// "Ohne Kategorie", while holding the word for one in four languages.
	CategoryTexts map[string]string `json:"categoryTexts,omitempty"`
	// ProductGroup is the group this product sits in, one level below its category:
	// the portal's cascade reads Kategorie > Produktgruppe > Produkt > Services.
	//
	// A string on the product, exactly like [Item.Category] above, and for the same
	// reasons — see the paragraph there, which applies word for word. What is worth
	// adding is what the pairing means, because "a chain" sounds like more than this
	// is: the group has no record and therefore **no category of its own**. The
	// product carries both strings and the chain is assembled per product — this
	// product is in category X, group Y — so the group→category relation is only
	// ever read off the products that carry both.
	//
	// Two consequences, and neither is an error state. A group whose products sit
	// in two categories appears under both, because nothing anywhere claims a group
	// belongs to one. And a group with no products does not exist, exactly as a
	// category with none does not.
	ProductGroup string `json:"productGroup,omitempty"`
	// ProductGroupTexts is [Item.ProductGroup] per language tag, exactly as
	// [Item.CategoryTexts] is the heading's — same split into a key that groups and
	// texts that render, same all-or-nothing rule at publication, same reason. See
	// the paragraphs there.
	ProductGroupTexts map[string]string `json:"productGroupTexts,omitempty"`
	// ContentSource binds this product's description, keywords and picture to
	// one page per language of an external source
	// (ADR-0491). Nil — the ordinary
	// state, and the only one on an installation with no source configured — means
	// the product manager writes them, exactly as before.
	//
	// While it is set, the fields it supplies are the source's: a save may not
	// change them, and only the link, refresh and unlink routes write it. It is
	// frozen into a release like every other field, so a release says which pages
	// its content was copied from and when.
	ContentSource *ContentSource `json:"contentSource,omitempty"`
	// Revision is optimistic concurrency, the same field and the same rule the
	// capability map uses: a write that states a revision is refused when the
	// stored record has moved past it, rather than silently overwriting somebody
	// else's edit (ADR-0376).
	//
	// # Why this and not the timestamp beside it
	//
	// Because a caller has to be able to send it back unchanged, and
	// [Item.UpdatedAt] is Unix nanoseconds — around 1.8e18, past the 2^53 where a
	// float64 stops representing integers exactly. Every JSON client that decodes
	// numbers as doubles, which is most of them and every MCP client, would return
	// a value a few hundred nanoseconds off and be told its write was stale. A
	// revision counts in ones, so it stays exact for more writes than a catalogue
	// will ever see.
	//
	// Zero means the caller stated no precondition and the write is unconditional,
	// which is what the Console sends: it renders every field and posts every
	// field, so the record it overwrites is the record on the screen in front of
	// somebody. A product stored before this field existed also reads zero, so its
	// first write is unconditional and every write after it can be guarded.
	Revision  int64 `json:"revision"`
	CreatedAt int64 `json:"createdAt"`
	UpdatedAt int64 `json:"updatedAt"`
}

type Lifecycle struct {
	From  int64 `json:"from,omitempty"`
	Until int64 `json:"until,omitempty"`
}

type Member struct {
	Ref  PrincipalRef `json:"ref"`
	Role MemberRole   `json:"role"`
}

type MemberRole string

type OwnContent struct {
	Descriptions map[string]string `json:"descriptions,omitempty"`
	Keywords     []string          `json:"keywords,omitempty"`
	// Picture says whether a picture was set aside beside the product's picture
	// (the store's own-picture file), to be put back on unlink.
	Picture bool `json:"picture,omitempty"`
}

type PageRef struct {
	// Ref is the page's stable id — never what was typed. A key changes when a
	// page moves between spaces; an id does not.
	Ref string `json:"ref"`
	// Version is the page's version when it was copied, and FetchedAt when, in
	// the server's Unix nanoseconds.
	Version   int    `json:"version"`
	FetchedAt int64  `json:"fetchedAt"`
	URL       string `json:"url,omitempty"`
	Title     string `json:"title,omitempty"`
	// Passages are the protected passages removed from the copy, so a recheck
	// can tell a passage protected after the copy was taken.
	Passages []string `json:"passages,omitempty"`
	// Labels are the page's labels the keywords were taken from, after the
	// source's exclusions — what lets an unlinked slot take its keywords with it
	// without asking the source.
	Labels []string `json:"labels,omitempty"`
	// Children are the child pages whose text the description holds, depth
	// first in sibling order; they are rechecked like the page.
	Children []ChildRef `json:"children,omitempty"`
	// Embeds are the items embedded anywhere in the description and taken;
	// they are rechecked like the page.
	Embeds []ChildRef `json:"embeds,omitempty"`
}

type PersonalLookup interface {
	PersonalVariables(processID string) (names []string, deployed bool)
}

type PrincipalRef struct {
	Type string `json:"type"`
	ID   string `json:"id"`
}

type Problem struct {
	// Catalog and Item name where the problem is, either or both empty when it
	// belongs to the whole input (a cycle, a rank tie).
	Catalog string `json:"catalog,omitempty"`
	Item    string `json:"item,omitempty"`
	Message string `json:"message"`
}

type Process struct {
	ID  string `json:"id"`
	XML string `json:"xml"`
}

type ProcessDeployer interface {
	// CheckProcesses reports, without deploying anything, every process the
	// caller may not deploy and every one that would not deploy. A refusal for
	// want of the role is ProblemMayNotDeploy.
	CheckProcesses(r *http.Request, procs []Process) []DocumentProblem
	// DeployProcesses deploys every process whose newest deployed version is not
	// already the document's model, through the same door a single deploy takes,
	// and names which it deployed and which it left unchanged.
	DeployProcesses(r *http.Request, procs []Process) (deployed, unchanged []string, problems []DocumentProblem, err error)
}

type ProcessLookup interface {
	// JobTypesOf returns the job types the tasks of this process id carry, and
	// whether any executable definition carries that id at all. The newest
	// deployed version answers, because that is the one an instance starts on.
	JobTypesOf(processID string) (jobTypes []string, deployed bool)
	// Served reports whether anything works that job type: the engine itself, a
	// worker seen pulling it, or — for a user task — a person.
	Served(jobType string) bool
}

type ProcessSource interface {
	ProcessXML(processID string) (xml []byte, deployed bool)
}

type Quarantine struct {
	Since  int64  `json:"since"`
	Reason string `json:"reason"`
}

type Release struct {
	// ID, CatalogID and CreatedAt identify the release. They are assigned by
	// whoever publishes it; [Publish] computes the rest.
	ID        string `json:"id,omitempty"`
	CatalogID string `json:"catalogId,omitempty"`
	CreatedAt int64  `json:"createdAt,omitempty"`
	// Items are the item definitions as they stood when this was published, sorted
	// by id, and they are copies rather than references.
	//
	// This is the whole of the snapshot rule. An order names one release; if the
	// release pointed at rows that keep changing, an approval pending for a week
	// could be approving something else by the time it is granted. Only value data
	// is copied, so an edit to the catalogue afterwards cannot reach in here.
	Items []Item `json:"items,omitempty"`
	// Waves is every item in the input, grouped into rounds: nothing in a wave
	// depends on anything in the same wave, and everything it does depend on is in
	// an earlier one. An order names one release and follows this schedule; it
	// never recomputes it.
	//
	// A flat sequence was the first shape and could not carry the failure
	// behaviour the shop requires: a failing line must stop only the lines that
	// depend on it, and a list has already discarded the reason each item sits
	// where it does. Waves keep it — a failure stops its own successors, and the
	// rest of its wave and every independent branch continue.
	Waves [][]string `json:"waves"`
	// Requires holds each item's direct preconditions, sorted, with no entry for an
	// item that has none.
	//
	// Waves are the right unit to *run* in and the wrong unit to *start on*. At a
	// wave boundary all that is known is "the previous wave is done", which cannot
	// distinguish a line whose precondition failed from one whose precondition is
	// in the same wave and succeeded — so a wave-wide barrier either starts a line
	// whose precondition is missing, or holds one whose preconditions are all
	// there. Both are wrong, so the edges travel with the schedule and [Blocked] is
	// what the fulfilment process asks when a line fails.
	Requires map[string][]string `json:"requires,omitempty"`
	// Excludes is what must never be held together with what
	// (ADR-0342), sorted, with no entry for an item that
	// excludes nothing.
	//
	// **Every pair appears under both ids.** EdgeExcludes is the only symmetric
	// edge kind, and a release recording one direction would make each reader
	// responsible for knowing which — a reader that got it wrong would find half
	// the violations and report the estate as half clean.
	Excludes map[string][]string `json:"excludes,omitempty"`
	// Includes and Options are the structure: what a product is made of, and what
	// is offered alongside it. Both are direct edges, sorted, with no entry for a
	// product made of nothing.
	//
	// They are kept apart because they mean opposite things to a basket. An
	// inclusion is a consequence of ordering the whole — integral, never
	// deselectable — and an option is an offer. Merging them would order a second
	// screen for everybody who orders a workplace.
	Includes map[string][]string `json:"includes,omitempty"`
	Options  map[string][]string `json:"options,omitempty"`
	// WithoutApproval names every item orderable with no approval at all, sorted.
	// It is a standing list rather than a report somebody has to think to run,
	// because the role that defines approval rules is the role that publishes them.
	WithoutApproval []string `json:"withoutApproval"`
}

type Remainder struct {
	ItemID  string `json:"itemId"`
	Process string `json:"process"`
	Lines   int    `json:"lines"`
}

type RemainderLookup interface {
	Remainder(items []Item) ([]Remainder, error)
}

type Service struct {

	// Limits are the installation's resource budgets. New sets them to
	// [limits.Default]; the server overwrites them with its own once it has read
	// the environment.
	Limits limits.Limits

	// Approvers resolves an approval rule's reference to somebody, for the report
	// in approverreport.go. It is a settable field for the reason Limits is: the
	// accounts and the groups belong to the server, which builds this service
	// before it has them.
	//
	// Nil is a real state and not a bug — a Service built by a test that does not
	// care about approvals has none — so the report refuses rather than guessing.
	// Both guesses are available and both are worse than a refusal: every
	// reference unresolvable reports the whole catalogue as broken, and every one
	// resolvable reports a clean estate nobody checked.
	Approvers ApproverLookup

	// Processes answers what is deployed and what is worked, for the report in
	// fulfilmentreport.go. Settable for Approvers' reason and nil for Approvers'
	// reason: the deployments and the workers belong to the server, and a Service
	// built without them refuses the report rather than guessing at it.
	Processes ProcessLookup

	// EntryPoints answers which start events a deployed process has, so publishing
	// can refuse a lifecycle binding that names one it does not (ADR-0425). Nil
	// skips that check, for the reason Processes may be nil.
	EntryPoints EntryPointLookup

	// Forms answers which fields a configuration form has, so publishing can refuse
	// one that names a field after a variable the order sets itself
	// (ADR-0441). Nil skips that check.
	Forms FormFieldLookup

	// Personal answers which variables a deployed process declares personal data,
	// so publishing can warn about an answer that would reach it in the clear
	// (AnswerWarnings). Nil skips the warning.
	Personal PersonalLookup

	// Models answers the BPMN a process id was deployed from, for an export that
	// carries the processes its products are bound to (export.go). Nil refuses
	// such an export rather than leaving the processes out unannounced.
	Models ProcessSource

	// Deployer deploys the processes an imported document carries (export.go).
	// Nil refuses such a document.
	Deployer ProcessDeployer

	// Baselines remembers what the last import of a document brought, so an import
	// tells a record edited here from one the document moved on (documentplan.go).
	// Nil remembers nothing: every difference is then a question.
	Baselines Baselines

	// Remainders counts the order lines a converted product left on its old
	// processes, for the fulfilment report (ADR-0427). Nil leaves the report's
	// remainder empty.
	Remainders RemainderLookup

	// Content reaches the configured content sources
	// (ADR-0491). Nil is an
	// installation with none, and it is the ordinary state: every route of the
	// binding then answers that none is configured, and nothing else changes.
	Content ContentSources

	// BindingChanged is told the source of a binding that was linked, refreshed
	// or removed, so the recheck watches the pages it now holds — and stops
	// watching the ones nothing holds any more — at once rather than at its next
	// sweep. Nil does nothing.
	BindingChanged func(source string)
	// contains filtered or unexported fields
}

type ShapeLookup interface {
	// CatchPoints returns the newest deployed version's message catch points: for
	// each, the message it waits for and whether it declares a correlation key.
	CatchPoints(processID string) []CatchPoint
	// WaitlessCycle returns the elements of a cycle in the newest deployed version
	// that waits for nothing outside the token, or nil.
	WaitlessCycle(processID string) []string
}

type ShopLookup interface {
	ShopOutcomes(processID string) []ShopOutcome
}

type ShopOutcome struct {
	Element string
	Action  string
	Outcome string
}

type State string

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

type TargetRef struct {
	// System is the target system's name in the installation's own vocabulary —
	// "entra", "ad", "jira". Atlas never interprets it; it only requires that an
	// observation and the item it should match agree on the spelling.
	System string `json:"system"`
	// Ref is the right as that system reports it. Compared literally, case and all:
	// a distinguished name differing only in case is two different strings to the
	// directory that issued them, and normalising here would attribute a right to
	// an item on a similarity Atlas invented.
	Ref string `json:"ref"`
}

type Theme struct {
	// Accent is the source brand colour as #rgb or #rrggbb, lower case.
	Accent string `json:"accent,omitempty"`
	// Typeface names one of [Typefaces]. It is a choice from a list rather than a
	// URL on purpose: a web-font URL would reach a third party on every portal
	// page load, carrying the visitor's address there — an outbound dependency on
	// pages that must render when nothing else is reachable, and a data flow an
	// operator in public administration cannot accept on a customer-facing
	// surface.
	Typeface string `json:"typeface,omitempty"`
}

type TranslationReport struct {
	// Checked is how many products were looked at, so a quiet report can be told
	// from an empty one.
	Checked int `json:"checked"`
	// Catalogs are the ids this report covers, sorted: the ones the caller may
	// maintain. A caller who maintains none gets an empty list rather than a 403,
	// because having nothing to maintain is not a refusal.
	Catalogs []string `json:"catalogs"`
	// Gaps is every place a product says something in one declared language and
	// not in another, each naming the catalogue and the product it is about.
	Gaps []Problem `json:"gaps"`
}

type Unpublished struct {
	// Released reports whether a release exists, and the two fields after it
	// identify the newest one.
	Released  bool   `json:"released"`
	ReleaseID string `json:"releaseId,omitempty"`
	// ReleasedAt is when it was published, in the server's own seconds.
	ReleasedAt int64 `json:"releasedAt,omitempty"`

	// Added is offered now and absent from the release: publishing puts it in front
	// of people.
	Added []UnpublishedItem `json:"added"`
	// Removed is in the release and no longer offered: **the portal is still
	// offering it**, and publishing is what takes it away. This is the one a
	// maintainer cannot otherwise see, because it is gone from every screen they
	// have and present on the one they do not.
	Removed []UnpublishedItem `json:"removed"`
	// Changed is offered in both and edited since: the portal is showing an older
	// name, price, state or description than the catalogue holds.
	Changed []UnpublishedItem `json:"changed"`
}

type UnpublishedItem struct {
	ID string `json:"id"`
	// Texts is the item's name per language. For a removed product it is the
	// **frozen** copy's, because that is the name on the portal right now, and
	// naming it any other way would describe something the reader cannot see.
	Texts map[string]string `json:"texts,omitempty"`
	// State is the live record's, and empty for a removed product whose record is
	// no longer readable here.
	State State `json:"state,omitempty"`
}

type Variant struct {
	ID    string            `json:"id"`
	Texts map[string]string `json:"texts"`
}

type WatchLookup interface {
	WatchedMessages() map[string]bool
}