capability

type AuthoringSubset struct {
	States           []string `json:"states"`
	InterfaceKinds   []string `json:"interfaceKinds"`
	ResourceKinds    []string `json:"resourceKinds"`
	RealizationKinds []string `json:"realizationKinds"`
	Directions       []string `json:"kpiDirections"`
	SLAScopes        []string `json:"slaScopes"`
	FindingKinds     []string `json:"gapFindingKinds"`
	// KeyPattern is the regular expression a key must match, so a form can refuse a
	// bad key while it is being typed with the same rule the server writes through.
	KeyPattern string `json:"keyPattern"`
	// DefaultHorizonMonths is how long a confirmation stays fresh where an installation
	// has not said otherwise. The horizon actually in force is an installation setting
	// and travels with the answer that applied it, never with this one — the subset
	// says what this build does, not how this server is configured.
	DefaultHorizonMonths int `json:"defaultConfirmationHorizonMonths"`
	// Hierarchy states, in the surface itself, that there is none. A client author
	// looking for a parent field finds the reason instead of assuming an oversight.
	Hierarchy string `json:"hierarchy"`
}

type Call struct {
	CallerProcessID string `json:"callerProcessId"`
	ElementID       string `json:"elementId"`
	CalledProcessID string `json:"calledProcessId"`
	// Resolved says the call would start a child on this server rather than park.
	// An unresolved call is somebody else's finding (the call-activity inventory
	// already reports it), so this area only reads the resolved ones.
	Resolved bool `json:"resolved"`
}

type Capability struct {
	// Key is the identity, everywhere: the URL, the filename, what Requires and a
	// value stream's stages name, and what an export carries. There is deliberately no
	// second local id — a random one would make an exported document unreadable and
	// force an import into another installation to remap it, and the map is meant to
	// travel. The cost is that the key is not renameable in place; see the record.
	Key string `json:"key"`
	// Name is what a person calls it; Summary is the one line a list shows.
	Name    string `json:"name"`
	Summary string `json:"summary,omitempty"`
	// Scope says what this capability is responsible for and — the half that earns
	// the field — what it is not. It is where boundary arguments are settled.
	Scope string `json:"scope,omitempty"`
	// Inputs and Outputs are the interface: what triggers the capability and with
	// what data, and what it hands back.
	Inputs  []Interface `json:"inputs,omitempty"`
	Outputs []Interface `json:"outputs,omitempty"`
	// Owner is the *business* owner, accountable for how the capability performs.
	// Not the application's sharing scope, which decides who may open and change a
	// model; those are regularly different people.
	Owner Owner `json:"owner"`
	// Resources are the teams, systems and other capabilities this one draws on.
	Resources []Resource `json:"resources,omitempty"`
	// Realizations are how it is currently done. Empty is a meaningful state and the
	// single most useful line in the record: it says the work is not automated here.
	Realizations []Realization `json:"realizations,omitempty"`
	// Requires are the capability keys this one depends on, as black boxes.
	Requires []string `json:"requires,omitempty"`
	// KPIs and SLAs are declarations. Nothing in this build computes one, and no read
	// returns a live figure — measurement is a later slice, and saying so here is what
	// stops the field from being read as a number.
	KPIs []KPI `json:"kpis,omitempty"`
	SLAs []SLA `json:"slas,omitempty"`
	// Tags are the only classification there is. A view of the map — by business area,
	// by "implements an end-to-end process", by an imported reference model's level —
	// is a tag query, never a tree walk.
	Tags []string `json:"tags,omitempty"`
	// State is where the capability is in its own life: proposed, active, deprecated.
	// A field somebody sets, not a lifecycle Atlas drives.
	State string `json:"state"`
	// Confirmation is when a person last said this record still describes reality, and
	// who said it. It is set by an explicit confirmation and by no edit — see
	// [Confirmation] and ADR-0304.
	Confirmation Confirmation `json:"confirmation"`
	// Revision is optimistic concurrency: a write against a stale one is refused
	// rather than silently overwriting somebody else's edit.
	Revision  int64  `json:"revision"`
	CreatedAt int64  `json:"createdAt"`
	CreatedBy string `json:"createdBy,omitempty"`
	UpdatedAt int64  `json:"updatedAt"`
	UpdatedBy string `json:"updatedBy,omitempty"`
}

type CapabilitySummary struct {
	Key     string   `json:"key"`
	Name    string   `json:"name"`
	Summary string   `json:"summary,omitempty"`
	Owner   Owner    `json:"owner"`
	State   string   `json:"state"`
	Tags    []string `json:"tags,omitempty"`
	// RealizationCount and Realized answer the one question a list of capabilities is
	// opened to ask: which of these is anybody actually doing anything about.
	RealizationCount int  `json:"realizationCount"`
	Realized         bool `json:"realized"`
	RequiresCount    int  `json:"requiresCount"`
	KPICount         int  `json:"kpiCount"`
	SLACount         int  `json:"slaCount"`
	// ConfirmedAt and Stale are the review half of the row, the twin of Realized: one
	// list answers "what does nobody automate", the other "what has nobody re-read".
	ConfirmedAt int64  `json:"confirmedAt,omitempty"`
	Stale       bool   `json:"stale"`
	Revision    int64  `json:"revision"`
	UpdatedAt   int64  `json:"updatedAt"`
	UpdatedBy   string `json:"updatedBy,omitempty"`
}

type CaseStats struct {
	// Cases is how many finished instances the window held.
	Cases int64 `json:"cases"`
	// MeanSeconds is the arithmetic mean cycle time, 0 when Cases is 0.
	MeanSeconds float64 `json:"meanSeconds"`
	MinSeconds  int64   `json:"minSeconds"`
	MaxSeconds  int64   `json:"maxSeconds"`
}

type Checked struct {
	Capabilities int `json:"capabilities"`
	ValueStreams int `json:"valueStreams"`
	Processes    int `json:"processes"`
	Calls        int `json:"calls"`
}

type Clock func() time.Time

type Confirmation struct {
	// At is unix seconds, zero when the record has never been confirmed. Zero is not
	// "confirmed at the epoch": it is the honest statement that nobody has said this is
	// true since the field existed, and the report distinguishes the two in words.
	At int64 `json:"at,omitempty"`
	// By is the principal who confirmed. Empty on an unconfirmed record, and empty on a
	// confirmation made with auth off, where there is no principal to name.
	By string `json:"by,omitempty"`
	// With names who was *asked*, where that is somebody other than the confirmer.
	// Empty means the confirmer spoke for the record alone — a legitimate confirmation
	// and a weaker one, which this says rather than implying the opposite.
	//
	// It is another claim Atlas cannot verify, and it earns its place for the reason
	// Owner does: the alternative is that who was asked lives only in the head of
	// whoever asked them.
	With string `json:"with,omitempty"`
	// Note is one line saying what the review found, replaced on each confirmation
	// rather than appended. This area is a correlation surface, not a log (ADR-0189).
	Note string `json:"note,omitempty"`
}

type ConfirmationView struct {
	Confirmation
	// HorizonMonths is the interval this answer applied. Published rather than assumed,
	// because it is an installation setting: a reader seeing "not stale" is entitled to
	// know whether that means "confirmed last month" or "the horizon is a century".
	HorizonMonths int `json:"horizonMonths"`
	// Stale is whether the confirmation has lapsed, or was never made.
	Stale bool `json:"stale"`
	// Ever is whether anybody has confirmed this at all. Stale without Ever is a record
	// nobody has ever stood behind, which is different work from one that lapsed.
	Ever bool `json:"ever"`
	// SelfConfirmed is true when the confirmer is also the last person to have edited
	// the record — the map confirming itself.
	//
	// It is shown and never reported. In a four-person installation the architect is
	// the only person who *can* confirm, so a finding here would fire on the normal
	// case, and a report that fires on the normal case stops being read. Shown beside
	// the confirmer and who they asked, it is one of three facts a reader weighs.
	SelfConfirmed bool `json:"selfConfirmed"`
}

type CoverageReport struct {
	Capability Capability `json:"capability"`
	// Realized is whether anything at all currently does this. It is the summary line
	// of the whole read, and it counts a clerk and a purchased system as realizations,
	// because they are.
	Realized     bool                  `json:"realized"`
	Realizations []ResolvedRealization `json:"realizations"`
	// Requires is what this capability depends on, each with the promise it has made.
	// The dependency plus the SLA is the whole interface, which is what lets an
	// end-to-end target be reasoned about without opening any box beneath it.
	Requires []Dependency `json:"requires"`
	// RequiredBy is the reverse: who would notice if this stopped.
	RequiredBy []Dependent `json:"requiredBy"`
	// ValueStreams are the streams whose stages name this capability, with the stages
	// themselves — an end-to-end capability is named by every stage it spans.
	ValueStreams []StreamUse `json:"valueStreams"`
	// Confirmation is the freshness half: when a person last said this record's prose
	// still describes reality, who said it, who they asked, and whether that has
	// lapsed. It sits beside the SLAs it is about — a reader looking at what a
	// capability promised should see, in the same answer, when anybody last stood
	// behind that.
	Confirmation ConfirmationView `json:"confirmation"`
	// Measurement is [MeasurementNotice]. See its comment for why it is on the wire.
	Measurement string `json:"measurement"`
}

type DeletionResult struct {
	Deleted string `json:"deleted"`
	// RequiredBy and Stages are the references now pointing at nothing.
	RequiredBy []string   `json:"requiredBy,omitempty"`
	Stages     []StageRef `json:"stages,omitempty"`
	// ValueStreams names the streams those stages belong to, in the same order.
	ValueStreams []string `json:"valueStreams,omitempty"`
}

type Dependency struct {
	Key string `json:"key"`
	// Known is whether the map has this capability at all. False is a finding the gap
	// report also raises; it is here because the caller of this read is looking at the
	// dependency list and should not have to fetch a second document to learn that one
	// of them names nothing.
	Known    bool   `json:"known"`
	Name     string `json:"name,omitempty"`
	State    string `json:"state,omitempty"`
	Realized bool   `json:"realized"`
	Owner    Owner  `json:"owner,omitempty"`
	SLAs     []SLA  `json:"slas,omitempty"`
}

type Dependent struct {
	Key   string `json:"key"`
	Name  string `json:"name,omitempty"`
	State string `json:"state,omitempty"`
	Owner Owner  `json:"owner,omitempty"`
}

type ElementCount struct {
	ElementID string `json:"elementId"`
	Name      string `json:"name,omitempty"`
	Count     int64  `json:"count"`
}

type Finding struct {
	Kind           string `json:"kind"`
	CapabilityKey  string `json:"capabilityKey,omitempty"`
	RequiredKey    string `json:"requiredKey,omitempty"`
	ValueStreamKey string `json:"valueStreamKey,omitempty"`
	StageKey       string `json:"stageKey,omitempty"`
	ApplicationKey string `json:"applicationKey,omitempty"`
	ProcessID      string `json:"processId,omitempty"`
	ElementID      string `json:"elementId,omitempty"`
	// WorkerRef is the Worker a missing worker realization names. It is a coordinate
	// like the process fields beside it, so a reader in another language can say which
	// Worker is missing without parsing the English detail (ADR-0267).
	WorkerRef string `json:"workerRef,omitempty"`
	// Detail says what to do about it in one sentence. A finding that only names a
	// coordinate makes the reader guess.
	Detail string `json:"detail"`
}

type GapReport struct {
	// Counts carries every kind, including the zeroes. A report that listed only the
	// kinds it happened to find would leave a UI unable to say "nothing wrong here".
	Counts   map[string]int `json:"counts"`
	Findings []Finding      `json:"findings"`
	// HorizonMonths is the confirmation horizon this report applied. Published rather
	// than assumed: it is an installation setting, so a reader seeing no unconfirmed
	// findings is entitled to know whether the map is fresh or the horizon is a century.
	HorizonMonths int `json:"horizonMonths"`
	// Restricted is how many things in the landscape the caller's access hid from this
	// comparison — counted once each, however many ways the comparison met them.
	// Published rather than swallowed: a report that quietly checks less than it
	// claims is worse than one that admits its blind spot.
	Restricted int `json:"restricted"`
	// Checked says what the comparison ran over, so a suspiciously empty report can be
	// told apart from an empty installation.
	Checked Checked `json:"checked"`
}

type HorizonResolver func() (int, error)

type Interface struct {
	Name string `json:"name"`
	// Kind is how it is reached: an API call, an event, a message, or a human being
	// handed something. Manual is a first-class kind because a capability nobody has
	// automated still has an interface, and it is the one worth writing down.
	Kind        string `json:"kind"`
	Description string `json:"description,omitempty"`
}

type KPI struct {
	Name   string `json:"name"`
	Metric string `json:"metric"`
	Goal   string `json:"goal,omitempty"`
	// Direction says which way is better, so a reader knows whether a number moving
	// up is good news. Empty where neither is.
	Direction string `json:"direction,omitempty"`
	Note      string `json:"note,omitempty"`
}

type Landscape struct {
	Processes []Process
	Workers   []Worker
	Calls     []Call
}

type LandscapeResolver func(r *http.Request) (Landscape, error)

type Measurement struct {
	Key  string `json:"key"`
	Name string `json:"name"`
	// Window is what the walked figures cover. The counted ones do not.
	Window     Window `json:"window"`
	WindowDays int    `json:"windowDays"`
	// CountedBasis and WalkedBasis say, in the response itself, which figures rest on
	// what. A client rendering this does not have to have read the ADR to label its
	// own axes honestly.
	CountedBasis string `json:"countedBasis"`
	WalkedBasis  string `json:"walkedBasis"`

	Processes []ProcessMeasurement `json:"processes"`
	// SLAs are the declared commitments that could be measured; NotMeasured names
	// every declared figure that could not, with the reason.
	SLAs        []SLAAttainment `json:"slas"`
	NotMeasured []NotMeasured   `json:"notMeasured"`
	// Unrealizable is true when the capability names no realisation this server runs,
	// so there is nothing to measure and that is a fact about the map rather than a
	// failure of the reading.
	Unrealizable bool `json:"unrealizable,omitempty"`
}

type MeasurementResolver func(r *http.Request, realizations []string, w Window) ([]RecordedProcess, error)

type NotMeasured struct {
	Kind   string `json:"kind"` // "kpi" or "sla"
	Name   string `json:"name"`
	Reason string `json:"reason"`
}

type Owner struct {
	Name    string `json:"name,omitempty"`
	Role    string `json:"role,omitempty"`
	Contact string `json:"contact,omitempty"`
	// Username links the owner to an Atlas account where there is one. Advisory: it
	// grants nothing and is not resolved against the user store, because an owner who
	// leaves must not make the record unreadable.
	Username string `json:"username,omitempty"`
}

type Process struct {
	// ApplicationKey is the portable application key (ADR-0134), empty for a process
	// deployed outside any application. A realization addresses this, never the local
	// application id, so the reference survives the map being moved.
	ApplicationKey  string `json:"applicationKey,omitempty"`
	ApplicationName string `json:"applicationName,omitempty"`
	ProcessID       string `json:"processId"`
	Name            string `json:"name,omitempty"`
	Version         int32  `json:"version"`
	// Inactive marks a deployment an operator has switched off (ADR-0119). It still
	// exists, so it is not a missing realization — a different finding entirely.
	Inactive bool `json:"inactive"`
	// ActiveInstances is the O(1) maintained per-definition counter (ADR-0080), never
	// a scan: this read must not grow with the instance population.
	ActiveInstances int `json:"activeInstances"`
	// CanView is whether the requesting principal may see this process at all. A
	// realization pointing at one they may not see is reported as restricted rather
	// than as missing — the difference between "you cannot see this" and "this is not
	// there" is the whole value of the answer.
	CanView bool `json:"-"`
}

type ProcessMeasurement struct {
	ProcessID string `json:"processId"`
	Name      string `json:"name,omitempty"`
	// Restricted marks a realisation this caller may not see. Its figures are absent
	// rather than zero, for the reason the gap report has the same distinction: zero
	// is a finding and "you may not look" is not.
	Restricted bool `json:"restricted,omitempty"`
	// Deployed is false for a realisation this server does not currently run, which is
	// a fact about the installation rather than about the capability.
	Deployed bool `json:"deployed"`

	// Outcomes and Cancellations are counted, therefore all-time.
	Outcomes      []ElementCount `json:"outcomes"`
	Cancellations []ElementCount `json:"cancellations,omitempty"`
	// Cases is walked, therefore windowed.
	Cases CaseStats `json:"cases"`
}

type Realization struct {
	Kind string `json:"kind"`
	// ApplicationKey and ProcessID address a process realization. The application key
	// is the portable one (ADR-0134), not a local id, so the reference survives the
	// map being moved to another installation.
	ApplicationKey string `json:"applicationKey,omitempty"`
	ProcessID      string `json:"processId,omitempty"`
	// WorkerRef addresses a Worker realization: one configured target and identity of
	// a Worker Type (ADR-0203).
	WorkerRef string `json:"workerRef,omitempty"`
	// Note is what a system or manual realization is, in words. Required for those
	// two kinds, because "a system does it" with no name is not a realization.
	Note string `json:"note,omitempty"`
}

type RecordedProcess struct {
	ProcessID string
	Name      string
	// Restricted: the caller may not see this process. Its numbers are absent, and
	// absent is not zero.
	Restricted bool
	// Deployed: this server currently runs it. A realisation naming a process that is
	// not deployed here is a fact about the installation, and the gap report is where
	// it is a finding; here it only means there is nothing to measure.
	Deployed bool

	// EndEvents and Cancellations are all-time counters (ADR-0080).
	EndEvents     []ElementCount
	Cancellations []ElementCount
	// Durations are the cycle times, in seconds, of the finished instances inside the
	// window — one entry per case.
	//
	// A slice rather than a pre-folded summary because the SLA attainment needs to
	// count against a threshold and the cycle-time summary needs a mean, and folding
	// twice over one slice in memory is cheaper than walking the store twice. The
	// resolver bounds its length by bounding the window, which is the same bound that
	// makes the walk affordable at all.
	Durations []int64
}

type ResolvedRealization struct {
	Realization
	// Resolved says the thing this realization names is here. A system or manual
	// realization is always resolved: Atlas cannot check either, and reporting them
	// as unresolved would read as broken when the truth is only that the work happens
	// somewhere Atlas cannot see.
	Resolved bool `json:"resolved"`
	// Restricted says the caller may not see what this points at. It is not Resolved
	// and it is not missing — asserting either would tell the caller something they
	// have no right to know, or something untrue.
	Restricted bool `json:"restricted"`
	// Name, ApplicationName, Version, Inactive, ActiveInstances are the live facts,
	// resolved now and stored nowhere. All empty on a restricted entry.
	Name            string `json:"name,omitempty"`
	ApplicationName string `json:"applicationName,omitempty"`
	WorkerType      string `json:"workerType,omitempty"`
	Version         int32  `json:"version,omitempty"`
	Inactive        bool   `json:"inactive,omitempty"`
	ActiveInstances int    `json:"activeInstances,omitempty"`
}

type Resource struct {
	Kind string `json:"kind"`
	Name string `json:"name"`
	// Ref points at the thing where Atlas has a name for it — a capability key for
	// kind "capability", a Worker reference or a system identifier otherwise. Free
	// text; a resource is a description of reality, not a foreign key.
	Ref string `json:"ref,omitempty"`
}

type SLA struct {
	Name      string `json:"name"`
	Metric    string `json:"metric"`
	Threshold string `json:"threshold"`
	// ThresholdSeconds is the same threshold as a number, where the author chose to
	// give one. It is optional and deliberately separate from Threshold rather than
	// replacing it: "within five business days" is what the business agreed and what
	// belongs in the record, and no parser should be asked to decide what a business
	// day means here.
	//
	// Supplying it is what makes the SLA measurable — a measurement compares against
	// this and reports nothing when it is absent, rather than guessing. So the record
	// stays writable in prose by somebody who has no number, and rewards the one who
	// does.
	ThresholdSeconds int64  `json:"thresholdSeconds,omitempty"`
	Window           string `json:"window,omitempty"`
	// Scope is internal (a promise between two teams here) or external (a contract or
	// a regulator). The two carry different consequences, so the record keeps them
	// apart rather than leaving it to the wording.
	Scope        string `json:"scope"`
	Counterparty string `json:"counterparty,omitempty"`
	Note         string `json:"note,omitempty"`
}

type SLAAttainment struct {
	Name   string `json:"name"`
	Metric string `json:"metric"`
	// ThresholdSeconds is what was compared against, echoed so the figure can be
	// checked without fetching the record.
	ThresholdSeconds int64 `json:"thresholdSeconds"`
	// Within and Cases are the counts: Within is how many finished cases in the
	// window met the threshold, Cases how many there were.
	Within int64 `json:"within"`
	Cases  int64 `json:"cases"`
	// Share is Within/Cases, 0 when there were no cases. A rate over no cases is not
	// 100% and not 0%; the reader is meant to look at Cases, which is why it is here.
	Share float64 `json:"share"`
}

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 (ADR-0291).
	Limits limits.Limits
	// contains filtered or unexported fields
}

type Stage struct {
	Key          string   `json:"key"`
	Name         string   `json:"name"`
	Description  string   `json:"description,omitempty"`
	Capabilities []string `json:"capabilities,omitempty"`
}

type StageRef struct {
	Key  string `json:"key"`
	Name string `json:"name,omitempty"`
}

type Store struct {
	*sidecar.Store[Capability]
}

type StreamStore struct {
	*sidecar.Store[ValueStream]
}

type StreamUse struct {
	Key    string     `json:"key"`
	Name   string     `json:"name,omitempty"`
	Stages []StageRef `json:"stages"`
}

type ValueStream struct {
	Key         string   `json:"key"`
	Name        string   `json:"name"`
	Description string   `json:"description,omitempty"`
	Owner       Owner    `json:"owner"`
	Stages      []Stage  `json:"stages,omitempty"`
	KPIs        []KPI    `json:"kpis,omitempty"`
	Tags        []string `json:"tags,omitempty"`
	// Confirmation is the same freshness record a capability carries, for the same
	// reason: a stream's owner and KPIs decay exactly as a capability's do.
	Confirmation Confirmation `json:"confirmation"`
	Revision     int64        `json:"revision"`
	CreatedAt    int64        `json:"createdAt"`
	CreatedBy    string       `json:"createdBy,omitempty"`
	UpdatedAt    int64        `json:"updatedAt"`
	UpdatedBy    string       `json:"updatedBy,omitempty"`
}

type ValueStreamSummary struct {
	Key         string   `json:"key"`
	Name        string   `json:"name"`
	Description string   `json:"description,omitempty"`
	Owner       Owner    `json:"owner"`
	Tags        []string `json:"tags,omitempty"`
	StageCount  int      `json:"stageCount"`
	// CapabilityCount is how many distinct capabilities the stages name — the
	// stream's breadth, which the stage count alone does not give.
	CapabilityCount int    `json:"capabilityCount"`
	KPICount        int    `json:"kpiCount"`
	ConfirmedAt     int64  `json:"confirmedAt,omitempty"`
	Stale           bool   `json:"stale"`
	Revision        int64  `json:"revision"`
	UpdatedAt       int64  `json:"updatedAt"`
	UpdatedBy       string `json:"updatedBy,omitempty"`
}

type Window struct {
	From int64 `json:"from"`
	To   int64 `json:"to"`
}

type Worker struct {
	Ref     string `json:"ref"`
	Name    string `json:"name,omitempty"`
	Type    string `json:"type,omitempty"`
	CanView bool   `json:"-"`
}