order

type AmendedAnswers struct {
	// Was is what the answers said before this correction.
	Was map[string]string `json:"was"`
	// By is the principal who corrected them and At is when. Both are required,
	// for the reason every settled transition in this package requires them: a
	// change kept forever that says somebody corrected something, without saying
	// who, is a correction nobody made.
	By string `json:"by"`
	At int64  `json:"at"`
	// Reason is optional and usually short — "cost centre was wrong". It is what a
	// reader months later has instead of a phone call.
	Reason string `json:"reason,omitempty"`
}

type Approval struct {
	// Kind is "none", "fixed", "role", "superior", or the name of a registered
	// approval process.
	Kind string `json:"kind,omitempty"`
	// Ref names the principal for "fixed" or the group for "role", empty for the
	// kinds that resolve their approver from the order itself.
	Ref string `json:"ref,omitempty"`
}

type Assignment struct {
	ItemID string `json:"itemId"`
	// Approver is who the approval is with now, as the task names them.
	Approver string `json:"approver"`
	// Original is who it was first assigned to. It survives every escalation,
	// because an approval that travelled must still say where it started — a
	// decision eventually taken by a third deputy reads very differently from one
	// taken by the line manager it was meant for.
	Original string `json:"original"`
	// AssignedAt is when it was first assigned, which is what a deadline measures
	// from.
	AssignedAt  int64        `json:"assignedAt"`
	Escalations []Escalation `json:"escalations,omitempty"`
	// StalledAt is when the chain was found to have nowhere left to go, zero while
	// it has somewhere. A stalled approval is still with whoever last held it —
	// stalling reports a fact, it does not take the task away — but it is now
	// visible, which is the whole point: an approval nobody can escalate and
	// nobody is looking at is how an order waits forever.
	StalledAt int64 `json:"stalledAt,omitempty"`
}

type Escalation struct {
	// From and To identify people the way a *task* does, which is by the username
	// its assignment names (ADR-0042). That is forced rather than chosen: an
	// assignment is written back onto the task it belongs to, so it has to speak
	// the identifier the task is addressed by, and a principal id written there
	// would address nobody.
	//
	// It is not a widening of what the portal holds about a person
	// (ADR-0314): a username is a login identifier the
	// account already carries into every task's assignee field and into the event
	// log with it. What stays out of here is what that record is about — names,
	// mail addresses, departments — which are resolved from the account when
	// something is rendered or sent, and never copied.
	From string `json:"from"`
	To   string `json:"to"`
	At   int64  `json:"at"`
	// By is the principal who moved it, empty when a deadline did. The absence is
	// the record: it distinguishes a hop a clock made from somebody's decision to
	// intervene, and both are kept.
	By string `json:"by,omitempty"`
}

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

type Grant struct {
	// Principal is who holds it — an id, never a name.
	Principal string
	ItemID    string
	VariantID string
	// OrderID is the order that granted it, so a right can be traced back to the
	// request and the approval behind it for as long as both are kept.
	OrderID string
	// At is when it started, read from the server clock by the caller.
	At int64
	// Until is when it was meant to end, or zero for a right that does not end.
	// Computed from the ceiling the release's product declared, frozen into the
	// line when the order was placed (ADR-0344).
	//
	// A promise about when the access should end, not a statement that it has: the
	// record stays held past it, and a modelled process is what actually takes the
	// access away.
	Until int64
	// ApprovedBy is who approved the line, copied from it (Line.ApprovedBy), so the
	// right keeps its approver after retention has deleted the order.
	ApprovedBy string
	// Outcome is the provision's ending, written in the same batch as the grant
	// (ADR-0429 §3).
	Outcome Outcome
}

type Line struct {
	// ItemID is the catalogue item this line orders, as the release named it.
	ItemID string `json:"itemId"`
	// VariantID is the variant the basket resolved, empty where the item has none.
	VariantID string     `json:"variantId,omitempty"`
	Status    LineStatus `json:"status"`
	// ProvisionProcess and DeprovisionProcess are the processes bound to this
	// line's product, copied from the release when the order was placed.
	//
	// They travel with the order for the same reason the schedule does: fulfilment
	// reads one record, and looking the binding up in the catalogue at the moment
	// of provisioning would reintroduce exactly the edit the release was frozen
	// against. The deprovision process travels too, so that revoking what this
	// order granted uses the process that was in force when it was granted.
	ProvisionProcess   string `json:"provisionProcess,omitempty"`
	DeprovisionProcess string `json:"deprovisionProcess,omitempty"`
	// LifecycleProcess and Operations are the one-process form of the same binding
	// (ADR-0425), frozen for the same reason. A line carries one form or the other,
	// as its product did when it was ordered; a line placed before its product was
	// converted keeps the two ids (ADR-0427).
	LifecycleProcess string            `json:"lifecycleProcess,omitempty"`
	Operations       map[string]string `json:"operations,omitempty"`
	// Actions are the product's actions as the release declared them (ADR-0429),
	// frozen for the same reason: what may later be asked of this position is what
	// was offered when it was ordered. A line carries Operations or Actions, as its
	// product did.
	Actions []catalog.Action `json:"actions,omitempty"`
	// LifecycleForm is how the lifecycle process runs for this line, frozen with the
	// binding: a per-position line's later operations are delivered to the instance
	// its provisioning started
	// (ADR-0428).
	LifecycleForm string `json:"lifecycleForm,omitempty"`
	// Rebindings are the moves of this line from the binding it froze to its
	// product's lifecycle process, each with who, when and why (ADR-0427). A list,
	// because a line moved twice has two facts to tell.
	Rebindings []Rebinding `json:"rebindings,omitempty"`
	// MaxDays is the product's ceiling on how long the right this line grants may
	// last, copied from the release for the reason the two processes above are
	// (ADR-0344). A ceiling relaxed in the catalogue
	// after somebody ordered must not lengthen what they were granted under the
	// stricter one — which is the same sentence as the one about the approval rule,
	// and true for the same reason.
	MaxDays int `json:"maxDays,omitempty"`
	// ConfigForm and Config are what somebody filled in when they ordered this
	// product, and the form they filled it in on
	// (ADR-0358).
	//
	// Both or neither: a set of answers with no form is a map of keys nobody can
	// interpret, and a form with no answers on a line that was placed means the
	// question was never asked.
	//
	// The **answers** are what is frozen here, and deliberately not the questions.
	// A release freezes rules — the approval, the ceiling, the bindings — because a
	// rule relaxed next week must not change what somebody was held to this week.
	// A form is not a rule; what has to survive is what was answered, and "cost
	// centre 4711" stays true whatever the form does afterwards. The id says which
	// set of questions it answered.
	// Price is what the release said this product cost when the order was placed
	// (ADR-0361). Frozen here for the reason
	// the approval rule and the ceiling are: an approver saw a figure and decided on
	// it, and a catalogue edit afterwards must not make the record show a different
	// one than the one that was approved.
	//
	// Displayed and never computed — see [catalog.Item.Price].
	Price      string            `json:"price,omitempty"`
	ConfigForm string            `json:"configForm,omitempty"`
	Config     map[string]string `json:"config,omitempty"`
	// Amendments are the corrections made to Config after the recipient already
	// held this line, oldest first
	// (ADR-0359). Empty is the
	// ordinary case, and it is empty too for a line corrected before anything was
	// attempted — there is no delivery for the old answers to have been true of.
	Amendments []AmendedAnswers `json:"amendments,omitempty"`
	// Integral says this line arrived because something else in the order always
	// carries it, rather than because anybody chose it.
	//
	// It is what lets a position be withdrawn on its own without letting somebody
	// take back a part its whole cannot exist without: the basket refuses to
	// deselect one, and a rule enforced when ordering and not afterwards is not a
	// rule. Frozen at placement like everything else on this line, because it is a
	// statement about the release the order was placed against.
	Integral bool `json:"integral,omitempty"`
	// Includes names the parts this line always carries, copied from the release.
	// It is what a per-line withdrawal reads to say *what* carries the part it is
	// refusing to take back, rather than only refusing.
	Includes []string `json:"includes,omitempty"`
	// Approval is the rule this line is approved under, copied from the release
	// like the bindings are. It travels for the same reason: the rule belongs to
	// the catalogue, and reading it when the line is reached would let a product's
	// approval be relaxed after somebody ordered under the stricter one.
	Approval Approval `json:"approval,omitempty"`
	// BlockedBy names the lines whose failure or rejection stopped this one —
	// the *root* causes, not the intermediate blocked lines between.
	//
	// An intermediate line is itself blocked and carries the same causes, so naming
	// it here would make a reader walk the chain to learn what actually happened.
	// "Your VPN is waiting because the laptop was rejected" is the sentence somebody
	// needs; "waiting because the docking station is waiting" is not.
	BlockedBy []string `json:"blockedBy,omitempty"`
	// TerminallyBlocked marks a blocked line that will never run: one of the things
	// it requires was rejected or abandoned, and neither lifts. A decision does not
	// change because an incident was repaired, and an abandoned incident is one
	// nobody is repairing. A line blocked only by live failures is not terminal —
	// somebody can still fix them, and the order waits.
	//
	// It is set by [Propagate] alongside BlockedBy and is meaningless on any other
	// status.
	TerminallyBlocked bool `json:"terminallyBlocked,omitempty"`
	// AbandonedBy and AbandonedAt record who gave up on this line's incident and
	// when. Both are required on an abandoned line and forbidden on any other, so
	// the record can never say a line was given up on without saying by whom.
	//
	// AbandonedBy is a principal id. Never a name — see
	// ADR-0314.
	AbandonedBy string `json:"abandonedBy,omitempty"`
	AbandonedAt int64  `json:"abandonedAt,omitempty"`
	// DecidedBy and DecidedAt record who decided this line's fate and when, and
	// Reason carries their words. All three are required on a rejected line; a
	// cancelled one requires the first two.
	//
	// The two decisions share these fields because they are the same kind of fact —
	// somebody, at a moment, settled this line without it being provisioned — and
	// the status says which kind. A rejection kept forever without an author is a
	// decision nobody made, and one without a reason produces the message that
	// generates a phone call: "your request was declined", and nothing else. A
	// cancellation needs no reason, because the person reading it is the person who
	// made it. DecidedBy is a principal id.
	DecidedBy string `json:"decidedBy,omitempty"`

	// ApprovedBy and ApprovedAt record who approved this line and when, as a
	// principal id and a moment. They are the other half of DecidedBy: a refusal
	// settles a line and keeps its author there, while an approval leaves the line
	// to be provisioned and keeps its author here. Without them the record of an
	// approval offered to a group said only that the line went on, and an access
	// review asks who let it. Empty on a line that needed no approval, and on one
	// approved before this was recorded.
	ApprovedBy string `json:"approvedBy,omitempty"`
	ApprovedAt int64  `json:"approvedAt,omitempty"`

	// ReturnedBy is who asked for this line to be given back, as a principal id.
	//
	// A third actor field beside AbandonedBy and DecidedBy, for the reason those
	// two are apart: they are different decisions. It is recorded when the return
	// is *asked for* rather than when it completes, because that is the only moment
	// a person is present — what finishes a return is a deprovisioning process, and
	// attributing the decision to it would name a robot where a decision was made.
	//
	// It is what the history row carries into the years after this order is deleted
	// (ADR-0346): without it the record can say a right ended
	// and not who ended it, which is half of what an access review asks.
	ReturnedBy string `json:"returnedBy,omitempty"`
	DecidedAt  int64  `json:"decidedAt,omitempty"`
	Reason     string `json:"reason,omitempty"`
	// Instances are the process instances started to work this position, oldest
	// first: its approval, its provisioning, and later its return (ADR-0416).
	//
	// Recorded by the server at the moment it starts one, because that is the only
	// moment the link is certain. Found afterwards it would be a search over every
	// running instance's variables — the walk a large installation does not finish
	// in any time a reader waits — and a guess where two processes carry the same
	// order id. Empty on a line nothing has started for yet, and on every line of an
	// order placed before the server kept the record.
	Instances []LineInstance `json:"instances,omitempty"`
}

type LineInstance struct {
	// Key is the instance's key, which is what its open tasks are found under.
	Key uint64 `json:"key"`
	// ProcessID is the BPMN process id it is an instance of — which of the
	// position's processes this is, without a second read to learn it.
	ProcessID string `json:"processId,omitempty"`
	// StartedAt is when it was started, in Unix nanoseconds.
	StartedAt int64 `json:"startedAt"`
	// Operation is what the instance does for the position — provision, change,
	// deprovision — where the starter knew it (ADR-0425). A lifecycle process is one
	// process id for all of them, so the id alone no longer says which.
	Operation string `json:"operation,omitempty"`
	// CommandID is the command the instance took for the position (ADR-0429): the
	// caller's command id for an action, the attempt id for the order's own
	// provision and return. It is what an outcome report names, so the order can say
	// which action it ends.
	CommandID string `json:"commandId,omitempty"`
}

type LineStatus string

type Notice struct {
	Kind NoticeKind `json:"kind"`
	// OrderID and Recipient say which order and who is told. Recipient is a
	// principal id — the message is addressed by the sender, not by this package,
	// which never holds an address (ADR-0314).
	OrderID   string `json:"orderId"`
	Recipient string `json:"recipient"`
	// ItemID names the line, empty on a settlement notice, which is about the
	// whole order.
	ItemID string `json:"itemId,omitempty"`
	// Reason carries the approver's words on a rejection.
	Reason string `json:"reason,omitempty"`
	// Outcome, Provisioned and NotProvisioned are the settlement notice's content:
	// the closing message is the one place the orderer is told the whole result.
	Outcome        Status   `json:"outcome,omitempty"`
	Provisioned    []string `json:"provisioned,omitempty"`
	NotProvisioned []string `json:"notProvisioned,omitempty"`
}

type NoticeKind string

type Order struct {
	ID string `json:"id"`
	// ReleaseID names the frozen catalogue this order was placed against. It is
	// what makes the order immune to catalogue edits while an approval is pending.
	ReleaseID string `json:"releaseId"`
	// Orderer and Recipient are principal ids. Never names, addresses or anything
	// else about a person — see ADR-0314.
	Orderer   string `json:"orderer"`
	Recipient string `json:"recipient"`
	Lines     []Line `json:"lines"`
	// Waves and Requires are copied from the release when the order is placed, for
	// the lines this order actually carries. The release computed them; the order
	// records them rather than recomputing later against a catalogue that may have
	// moved on, and so that fulfilment reads one record instead of two.
	Waves    [][]string          `json:"waves,omitempty"`
	Requires map[string][]string `json:"requires,omitempty"`
	// Assignments is where each approval sits and every hop it took to get there
	// (assignment.go). There is at most one per line, and only for lines that
	// needed approving.
	//
	// It is written when a deadline first moves an approval and not when the order
	// is placed, because at placement the approver of a "superior" line is not
	// known — the directory has not been asked yet. Until something moves it, the
	// live task's assignee is the whole truth and copying it here would be a second
	// one. What cannot be derived from the task is the *history*: who it started
	// with, every hop, and whether the chain ran out. That is what this holds, and
	// it outlives the task.
	Assignments []Assignment `json:"assignments,omitempty"`
	CreatedAt   int64        `json:"createdAt"`
	UpdatedAt   int64        `json:"updatedAt"`
}

type Outcome struct {
	CommandID   string
	Action      string
	Effect      string
	Outcome     string
	EventType   string
	OrderID     string
	Position    string
	Principal   string
	ItemID      string
	VariantID   string
	InstanceKey uint64
	At          int64
	// Result is a JSON object of scalars, bounded by whoever reports it.
	Result string
}

type Rebinding struct {
	FromProvision   string `json:"fromProvision,omitempty"`
	FromDeprovision string `json:"fromDeprovision,omitempty"`
	ToLifecycle     string `json:"toLifecycle"`
	By              string `json:"by,omitempty"`
	At              int64  `json:"at"`
	Reason          string `json:"reason,omitempty"`
}

type Service struct {

	// Limits are the resource budgets this service enforces. Set after
	// construction, like every other per-area service's, so that the constructor
	// does not grow a thirteenth positional argument for a value the server hands
	// to all of them the same way.
	Limits limits.Limits
	// contains filtered or unexported fields
}

type Status string

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