engine

package
v2.10.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 9, 2026 License: Apache-2.0 Imports: 41 Imported by: 0

Documentation

Overview

Package engine is the kind-agnostic manifest engine: it validates manifests against their schema, references and kind rules, stores immutable versions, computes diffs, and indexes cross-manifest references. Adding a kind never changes this package; it changes only contract/schemas and internal/kinds.

Index

Constants

View Source 
const (
	PhaseDefine  = "define"
	PhaseMeasure = "measure"
	PhaseAnalyze = "analyze"
	PhaseImprove = "improve"
	PhaseControl = "control"
)

DMAIC phases, in order.

View Source 
const (
	LineageUpstream   = "upstream"   // a project that produces data this one uses
	LineageSource     = "source"     // a data source this project uses
	LineageProject    = "project"    // the project itself
	LineageOutput     = "output"     // a data source this project produces into
	LineageDownstream = "downstream" // a KPI or a project that reads what it produces
)

Where a node sits in a project's data lineage, from left to right.

View Source 
const (
	LinkProblemGap      = "problem-gap"
	LinkProblemGroup    = "problem-group"
	LinkGapGroup        = "gap-group"
	LinkGapOutcome      = "gap-outcome"
	LinkGoalParent      = "goal-parent"
	LinkGoalContributes = "goal-contributes"
	LinkKPIGap          = "kpi-gap"
	LinkProjectOutcome  = "project-outcome"
	// A project or a programme depends on another (TAXONOMY.md D46).
	LinkProjectComponent   = "project-component"
	LinkProgrammeComponent = "programme-component"
)

A link between two records, as a person draws it: from a node to another. Each kind of link names what it joins and is stored where the record that holds it keeps it.

View Source 
const (
	ProjectStateDraft     = "draft"
	ProjectStateDefined   = "defined"
	ProjectStateHandedOff = "handed off"
	ProjectStateCancelled = "cancelled"
)

ProjectStateDraft and the other project states: draft, defined (set automatically at the first snapshot), handed off, and cancelled.

View Source 
const DefaultLocale = "en"

DefaultLocale is the language guidance falls back to.

Variables

View Source 
var (
	// ErrAgentGrantsOff is a deployment that keeps no access list, so no
	// grants.
	ErrAgentGrantsOff = fmt.Errorf("%w: agent grants need an access list (CARTOGRAPH_AUTHZ=access)", ErrConflict)
	// ErrAgentGrantEnded is a grant that is unknown, revoked, expired, or
	// for someone no longer on the access list.
	ErrAgentGrantEnded = errors.New("the agent grant has ended")
	// ErrAgentGrantReused is a code or refresh token presented twice; the
	// grant is revoked, since one of the two was not its agent's.
	ErrAgentGrantReused = errors.New("the agent grant was used twice and is revoked")
)
View Source 
var (
	// ErrNoChangeSets is a store that keeps no change sets.
	ErrNoChangeSets = errors.New("this deployment's store keeps no change sets")
	// ErrNotOpen refuses a change to a change set no longer open for it.
	ErrNotOpen = fmt.Errorf("%w: the change set is not open", ErrConflict)
	// ErrNotTheirChangeSet refuses work in a change set by anyone but who
	// works in it, or its acceptance by anyone but its person.
	ErrNotTheirChangeSet = fmt.Errorf("%w: this change set is not yours", identity.ErrForbidden)
	// ErrTheirsToPropose refuses an agent proposing a change set it was
	// brought into: its person proposes and accepts their own work.
	ErrTheirsToPropose = fmt.Errorf("%w: this change set is your person's, and they propose it themselves", identity.ErrForbidden)
)
View Source 
var (
	ErrUnknownKind = errors.New("unknown kind")
	ErrNotFound    = errors.New("not found")
	ErrConflict    = errors.New("conflict")
)

Sentinel errors an API or CLI layer can classify with errors.Is.

View Source 
var (
	// ErrProposalStale is a proposal whose manifest changed since: its
	// person reviews it again rather than overwrite what changed.
	ErrProposalStale = errors.New("the manifest has changed since this was proposed")
	// ErrNotTheirs refuses a decision by anyone but the person the
	// proposal was made for.
	ErrNotTheirs = fmt.Errorf("%w: only the person an agent acts for decides its proposals", identity.ErrForbidden)
	// ErrNotAnAgent refuses a proposal from a person, who saves instead.
	ErrNotAnAgent = errors.New("an agent proposes; a person saves")
	// ErrNoProposals is a store that keeps no proposals.
	ErrNoProposals = fmt.Errorf("%w: this store keeps no proposals", ErrNotFound)
)
View Source 
var ErrBadEdit = errors.New("bad draft edit")

ErrBadEdit is a draft edit that names no field it could set: a path that is not a JSON pointer, or that runs through a value holding none.

View Source 
var ErrChangeSetRequired = errors.New("this workspace makes every change in a change set: make it in one, review it, and roll it in")

ErrChangeSetRequired is a direct write in a workspace whose policy sends every change through a change set (docs/adr/0024).

View Source 
var ErrNoLayout = errors.New("no graph layout is configured")

ErrNoLayout is a graph asked of an engine given no layout.

View Source 
var ErrNoSeries = errors.New("no such series")

ErrNoSeries is a series a kind does not have.

View Source 
var ErrNoShared = errors.New("engine: shared drafts are not configured")

ErrNoShared is returned by Shared methods when the engine was built without the three ports shared drafts need.

View Source 
var ErrNoState = errors.New("this store has no state manifest")

ErrNoState is returned by the state methods when the manifest store has no apply gate: every manifest it holds is live, so there is nothing to apply, exclude or recover.

View Source 
var ErrReadOnly = errors.New("engine: the principal may not change this document")

ErrReadOnly is returned when a sync message from a principal who may not write carries changes.

View Source 
var ErrSelf = errors.New("you may not remove your own access")

ErrSelf refuses an administrator's change to their own access that would lock them out.

View Source 
var ErrUnknownLink = fmt.Errorf("unknown link")

ErrUnknownLink is a link kind the engine does not know.

View Source 
var RelevantKinds = []string{"Goal", "KPI", "Gap", "Assumption", "Portfolio", "Programme", "Operation", "Project", "BeneficiaryGroup", "DataSource", "FundingSource", "Resource"}

RelevantKinds are the kinds relevance is asked across when none are named: the work and strategy a piece of work names, and the registers it draws on.

Functions

func AgentFeedOwner added in v2.6.0 

func AgentFeedOwner(kind, id string) (person string, ok bool)

AgentFeedOwner reports whose agent feed a manifest name returned by ManifestFor is, if it is one.

func ChangeSetOf added in v2.10.0 

func ChangeSetOf(ctx context.Context) (string, bool)

ChangeSetOf is the change set a context reads as, if any.

func DocTopic 

func DocTopic(docID string) string

DocTopic is the fan-out topic a document's "changed" hints go to, and EphemeralTopic the one its presence travels on.

func EphemeralTopic 

func EphemeralTopic(docID string) string

func IsPresence 

func IsPresence(kind, id string) bool

IsPresence reports whether a manifest name returned by ManifestFor is the presence document's.

func LeftFor added in v2.9.0 

func LeftFor(ctx context.Context, kind, id, check string) string

LeftFor is the reason a check on a manifest is left for the person, in the change set on ctx, or "".

func MayLeave added in v2.10.0 

func MayLeave(check, asked string) error

MayLeave refuses leaving open, with no person to ask, a check the document answers.

func NewDocumentID 

func NewDocumentID() string

NewDocumentID returns a random automerge-repo document id: sixteen random bytes in base58check, as automerge-repo writes them, so the stock libraries accept it.

func Proposed added in v2.9.0 

func Proposed(ctx context.Context, kind, id string) string

Proposed says how a manifest stands in the change set read on ctx: "new" when the change set creates it, "changed" when it changes one that exists, "" when it is not in the change set or none is read.

func RecordPresenceOf added in v2.10.0 

func RecordPresenceOf(kind, id string) (manifestKind, manifestID string, ok bool)

RecordPresenceOf reports which manifest a presence document is for, given the name ManifestFor returns, if it is a record's.

func RefIsSet 

func RefIsSet(v any) bool

RefIsSet reports whether a reference field names anything.

func RefLabel 

func RefLabel(v any, spec map[string]any) string

RefLabel renders a reference field as the text a document shows, given the spec it lives in so local references can resolve. Exported for the charter renderer, which prints references and lives in its own package. A field that is not a reference at all renders empty rather than guessing, so a stale document shows a gap instead of a wrong name.

func Registers added in v2.7.0 

func Registers() []string

Registers returns the root kinds, in order.

func SetOf added in v2.9.0 

func SetOf(stored string) (set, kind string)

SetOf splits a document's stored kind into the change set it is a draft in and the manifest's kind; set is "" for a manifest's own shared draft.

func StandardUnitIDs 

func StandardUnitIDs() []string

StandardUnitIDs names the units a vault is seeded with, so a test can hold the example instance to the same set.

func WholeFile added in v2.10.0 

func WholeFile(text string, fileSize int) error

WholeFile refuses a document's text that is not its whole file: a summary or an excerpt loses the registers and sections a port is written from, and no later step can tell. The file's size is given beside the text; line endings and a final newline may differ.

func WithHandoff added in v2.9.0 

func WithHandoff(ctx context.Context, f HandoffFunc) context.Context

WithHandoff returns ctx carrying how to hand a project off.

func WrittenFromTheDocument added in v2.10.0 

func WrittenFromTheDocument(check string) bool

WrittenFromTheDocument reports whether a check is on what a document itself states, which a port writes and never waives.

Types

type AcceptResult added in v2.9.0 

type AcceptResult struct {
	Saved   []Version
	Deleted []Ref
	Moved   []Ref
	Kept    []Problem
}

AcceptChangeSet saves every included item of a proposed change set as the person it is for, in one transaction and in the order references need, each still on the version it started from. It is claimed first, so two acceptances never both save it. Items trimmed from it stay, and the change set is open again with them; with none left it is merged. AcceptResult is what rolling a change set in did: the versions it saved, the records it deleted and the projects it moved, and what it could not apply, which stays in the change set.

type Around added in v2.7.0 

type Around struct {
	Kind string `json:"kind"`
	ID   string `json:"id"`
	Name string `json:"name,omitempty"`
	// Link is how it is joined: Holder at Path names the other. Via is
	// that other, where it is not the manifest the work is about: a KPI
	// on the same cycle is joined through the cycle, not to this one.
	Link string `json:"link"`
	Via  string `json:"via,omitempty"`
	// Draft is true while it has no version, or a draft newer than one.
	Draft bool    `json:"draft,omitempty"`
	Open  []Check `json:"open"`
}

Around is one manifest joined to another along the work's links, with what it still lacks.

type Bus 

type Bus interface {
	Publish(ev Event)
	// Subscribe delivers events for one manifest, or for every manifest
	// when kind is empty. A slow subscriber drops events rather than
	// blocking the publisher; it reads the state again when it next needs it.
	Subscribe(ctx context.Context, kind, id string) *Subscription
}

Bus fans events out to subscribers in one process. It is the port a multi-process deployment replaces (the Postgres index's LISTEN/NOTIFY, a broker); the engine only ever calls Publish and Subscribe.

type Candidate added in v2.6.0 

type Candidate struct {
	ID     string `json:"id"`
	Name   string `json:"name"`
	Detail string `json:"detail,omitempty"`
	// Under is a goal's parent, so where it already sits is plain.
	Under string `json:"under,omitempty"`
}

Candidate is an existing record a reference or link may use: reuse one before defining another.

type Change 

type Change struct {
	Path string `json:"path"`
	Op   string `json:"op"` // add, remove, replace
	From any    `json:"from,omitempty"`
	To   any    `json:"to,omitempty"`
}

Change is one difference between two versions of a manifest, at Path (a JSON pointer, or a pointer using an array element's own id in place of its index for arrays of objects that carry one, see diff.go).

type ChangeControl added in v2.9.0 

type ChangeControl struct {
	// ChangeSetsRequired refuses every direct write: each change is made
	// in a change set and rolled in.
	ChangeSetsRequired bool `json:"changeSetsRequired,omitempty" yaml:"changeSetsRequired"`
	// RollIn is what a change set needs before it is rolled in.
	RollIn RollInPolicy `json:"rollIn,omitempty" yaml:"rollIn"`
}

ChangeControl is a workspace's change-control policy.

type ChangeSetItem added in v2.7.0 

type ChangeSetItem struct {
	Item store.ChangeItem
	Name string
	// Proposed is "new" when the change set creates the record, else
	// "changed".
	Proposed string
	Changes  []Change
	Checks   []Check
	// Stale is the version saved since the item started, 0 when none was.
	Stale int
}

ChangeSetItem is one item as a reviewer reads it: what it changes from the version it started from, its checks with the rest of the change set, and whether the record has moved on since.

type ChangeSetView added in v2.7.0 

type ChangeSetView struct {
	ChangeSet store.ChangeSet
	Items     []ChangeSetItem
}

ChangeSetView is a change set and its items.

type Changed 

type Changed struct {
	Replica string `json:"replica"`
	Seq     int64  `json:"seq"`
}

Changed is the hint published on DocTopic after a replica stores a change: which replica, and the chunk it stored.

type Check added in v2.6.0 

type Check struct {
	ID      string `json:"id"`
	State   string `json:"state"`
	Message string `json:"message"`
	Section string `json:"section,omitempty"`
	// Path is the field the check is about, as a JSON pointer, where it is
	// one field: what a record must have before it can be saved as a
	// version.
	Path string `json:"path,omitempty"`
}

Check is one thing a manifest still needs, in a shape every kind shares: what it is, whether it is met, what it says, and the section of the editor where it is fixed. State is ok, warn, or block (a project's blocking checks stop a handoff).

func (Check) Open added in v2.6.0 

func (c Check) Open() bool

Open reports whether a check is not yet met.

type ComponentEdge added in v2.9.0 

type ComponentEdge struct {
	From, To Ref
	Why      string
	Legacy   bool
}

ComponentEdge is one piece of work depending on another (TAXONOMY.md D46). Legacy is true when it is read from an older declaration made on the component (a project's alignment.partOf or alignment.programmes, a programme's programmes).

type ComponentGraph added in v2.9.0 

type ComponentGraph struct {
	Nodes []ComponentNode
	Edges []ComponentEdge
	// Loops are the chains of components that come back to where they
	// started, each in order, starting from its first piece of work by id.
	Loops [][]Ref
	// CriticalPath is the longest chain of components by duration, from the
	// work that depends to the work depended on.
	CriticalPath []Ref
	// CriticalMonths is the critical path's length.
	CriticalMonths int
}

ComponentGraph is the whole graph of components as ctx reads it, and what follows from it.

type ComponentNode added in v2.9.0 

type ComponentNode struct {
	Ref
	Name string
	// Months is how long it takes itself: a project's timeline, summed; a
	// programme takes none of its own.
	Months int
	// Dependents is how many pieces of work depend on it, directly or
	// through others.
	Dependents int
	// MostDependedOn is whether more work depends on it than on any other,
	// and at least two pieces of work do.
	MostDependedOn bool
	// Critical is whether it lies on the critical path.
	Critical bool
	// InLoop is whether it lies on a loop of components.
	InLoop bool
}

ComponentNode is one project or programme in the graph of components.

type CyclePeriod added in v2.9.0 

type CyclePeriod struct {
	End   string
	Start string
	Name  string
	Label string
	Due   string
}

CyclePeriod is one period of a reporting cycle, as every interface lays out a KPI's readings: the month it ends (the key its reading is filed under), the month it starts, its name and label where the cycle names its periods, and the day its reading is due.

type DMAIC added in v2.10.0 

type DMAIC struct {
	Project string       `json:"project"`
	Phases  []DMAICPhase `json:"phases"`
}

DMAIC is a project's readiness for each phase.

type DMAICItem added in v2.10.0 

type DMAICItem struct {
	Phase string `json:"phase"`
	Key   string `json:"key"`
	Met   bool   `json:"met"`
	// What the deliverable is, and where in Cartograph it is held.
	Says  string `json:"says"`
	Field string `json:"field"`
	// Lacking names what is missing, when it is not met.
	Lacking string `json:"lacking,omitempty"`
}

DMAICItem is one deliverable of a phase.

type DMAICPhase added in v2.10.0 

type DMAICPhase struct {
	Phase string      `json:"phase"`
	Met   int         `json:"met"`
	Of    int         `json:"of"`
	Items []DMAICItem `json:"items"`
}

DMAICPhase is a phase's tollgate: its items and how many are met.

type DecisionModel added in v2.9.0 

type DecisionModel struct {
	Configured bool     `json:"configured"`
	Ready      bool     `json:"ready"`
	Off        []string `json:"off,omitempty"`
}

DecisionModel is whether a decision model is configured, and whether it answers now: what an agent asks first, to know whether to lean on it. Off, when it does not answer, says what is not judged meanwhile (docs/adr/0030), which the agent must then judge itself.

type DependencyEdge 

type DependencyEdge struct {
	FromKind string `json:"fromKind"`
	FromID   string `json:"fromId"`
	FromName string `json:"fromName"`
	ToKind   string `json:"toKind"`
	ToID     string `json:"toId"`
	ToName   string `json:"toName"`
	NeedBy   string `json:"needBy,omitempty"`
	Why      string `json:"why,omitempty"`
}

DependencyEdge is one resolved link: who waits, on what, and by when.

type Directory added in v2.2.0 

type Directory struct {
	// Roles names, for each role, the groups that grant it.
	Roles map[string][]string
	// Teams are the groups that are teams, parents before children.
	Teams []DirectoryTeam
	// Agents names the roles whose people may act through an agent
	// (docs/adr/0016). None listed, no agents.
	Agents []string
}

Directory maps an organisation's directory groups onto Cartograph's roles and teams. The composition root reads it from a file; the engine knows no syntax.

type DirectoryTeam added in v2.2.0 

type DirectoryTeam struct {
	// Group is the group's name as the directory reports it.
	Group string
	// Name is the team's name in Cartograph; the group's when empty.
	Name string
	// Parent is the name of the team above it, if any.
	Parent string
}

DirectoryTeam is one group that is a team.

type Draft added in v2.10.0 

type Draft struct {
	Kind, ID string
	Text     []byte
}

Draft is a record a port drafted, as it was saved.

type Engine 

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

Engine is the kind-agnostic manifest engine. Construct with New. It talks to the outside world through ports only: the two stores every deployment has, and the optional ones an adapter may offer (the apply gate, the bundle store). It never touches a file system or a browser itself.

func New 

func New(manifests store.ManifestStore, ops store.OperationalStore, opts ...Option) (*Engine, error)

New builds an Engine over the given stores, with every kind's JSON Schema compiled and its reference rules worked out (once a process: compiledContract). An adapter that offers more than the two required ports is attached with options; a store that satisfies StateStore or BundleStore itself is attached automatically.

func (*Engine) AcceptChangeSet added in v2.7.0 

func (e *Engine) AcceptChangeSet(ctx context.Context, id, reason string) (AcceptResult, error)

func (*Engine) AcceptProposal added in v2.5.0 

func (e *Engine) AcceptProposal(ctx context.Context, id, actor, reason string, handoff Handoff) (store.Proposal, error)

AcceptProposal makes the record a proposal proposed, as the person on ctx, who must be the one it was made for and not an agent. It refuses one whose manifest changed since (ErrProposalStale). handoff does a handoff when the proposal is one.

func (*Engine) AdvanceAgentGrant added in v2.5.0 

func (e *Engine) AdvanceAgentGrant(ctx context.Context, id string, gen int) (int, error)

AdvanceAgentGrant moves a live grant from generation gen to the next, once: a code or refresh token is exchanged for the next. Presented twice, the grant is revoked (ErrAgentGrantReused).

func (*Engine) AgentFeed added in v2.6.0 

func (e *Engine) AgentFeed(ctx context.Context, person string) (string, error)

AgentFeed returns the document a person's agents announce their steps on (docs/adr/0018): the caller's own, or, for an administrator, anyone's. "" is the caller.

func (*Engine) AgentGrantPrincipal added in v2.5.0 

func (e *Engine) AgentGrantPrincipal(ctx context.Context, id string) (identity.Principal, store.AgentGrant, error)

AgentGrantPrincipal is who a grant acts for: its person, with the agent beside them, as the access list has them now. Whether that person may still use an agent is the access policy's question, asked on every request.

func (*Engine) AgentGrants added in v2.5.0 

func (e *Engine) AgentGrants(ctx context.Context, email string) ([]store.AgentGrant, error)

AgentGrants lists grants: the caller's own, or, for an administrator, someone's (email) or everyone's ("*").

func (*Engine) AppendSeriesItem added in v2.3.0 

func (e *Engine) AppendSeriesItem(ctx context.Context, kind, id, series string, item map[string]any, actor, reason string) (Version, error)

AppendSeriesItem records one item of a series and commits the manifest with it, on its latest committed version: a new key in key order, or in place of the item with the same key. The caller sends one item, not the series.

func (*Engine) Apply 

func (e *Engine) Apply(ctx context.Context, refs []string) (State, error)

Apply includes refs ("Kind/id") in the live state, then reloads and reindexes once for the whole batch. A malformed ref, or one the store cannot find, is a ValidationError naming it; nothing is applied then. Applying what is already applied is quiet.

func (*Engine) ApplyDirectory added in v2.2.0 

func (e *Engine) ApplyDirectory(ctx context.Context, actor string) ([]string, error)

ApplyDirectory creates every team the mapping names that does not exist yet, parents first, and returns the names it created. It never changes an existing team. Run it once per deployment, from one place (`cartograph access apply`), so two replicas never both create a team.

func (*Engine) BringSource added in v2.10.0 

func (e *Engine) BringSource(ctx context.Context, set, title, text string) (Source, error)

BringSource keeps a document in a change set, split into sections, and answers with its outline. A second document is kept beside the first.

func (*Engine) Bus 

func (e *Engine) Bus() Bus

Bus returns the event bus.

func (*Engine) ChangeSetText added in v2.7.0 

func (e *Engine) ChangeSetText(ctx context.Context, set, kind, id string) ([]byte, bool, error)

ChangeSetText is a manifest as it stands in a change set: its item, else the record (its latest version), and whether it is in the change set.

func (*Engine) ChangeSets added in v2.7.0 

func (e *Engine) ChangeSets(ctx context.Context, status string, everyone bool) ([]store.ChangeSet, error)

ChangeSets lists change sets: the person's own and their agents', or everyone's for an administrator who asks.

func (*Engine) ChangedFields added in v2.6.0 

func (e *Engine) ChangedFields(before, after []byte, limit int) []string

ChangedFields lists, by JSON pointer, the fields that differ between two texts of a manifest; before may be empty for a new one. At most limit.

func (*Engine) ChecksOf added in v2.6.0 

func (e *Engine) ChecksOf(ctx context.Context, kind, id string, text []byte) ([]Check, error)

ChecksOf computes the checks for a manifest's text, saved or not: every check the kind has, as the editor shows them. Kinds without checks of their own have none; their schema and rules are what validation reports.

func (*Engine) CloseChangeSet added in v2.7.0 

func (e *Engine) CloseChangeSet(ctx context.Context, id, reason string) (store.ChangeSet, error)

CloseChangeSet ends a change set without saving it: its person, or who works in it.

func (*Engine) Codec 

func (e *Engine) Codec() codec.Codec

Codec is the manifest syntax this engine reads and writes, for the drivers that turn a request body into text and back.

func (*Engine) Commit 

func (e *Engine) Commit(ctx context.Context, kind, id string, yamlBytes []byte, actor, reason string) (Version, error)

Commit validates a manifest and, if it is valid, stores it as the next immutable version. The id in the manifest's metadata must match id. actor is recorded as given (see checkActor's own doc comment for why actor validation was removed).

func (*Engine) CommitProject 

func (e *Engine) CommitProject(ctx context.Context, id string, yamlBytes []byte, actor, reason string) (Version, error)

CommitProject validates and stores a new version of a Project, exactly like the generic Commit.

func (*Engine) Components added in v2.9.0 

func (e *Engine) Components(ctx context.Context) (ComponentGraph, error)

Components resolves the graph of components across every project and programme (TAXONOMY.md D46): who depends on whom, the loops, the critical path and how widely each is depended on. Read as ctx reads the workspace, a change set's drafts included.

func (*Engine) ControlChartOf added in v2.10.0 

func (e *Engine) ControlChartOf(ctx context.Context, kpi string) (spc.Chart, error)

ControlChartOf reads a KPI's readings as a control chart.

func (*Engine) CurrentChangeSet added in v2.7.0 

func (e *Engine) CurrentChangeSet(ctx context.Context, id string) (store.ChangeSet, bool, error)

CurrentChangeSet is the change set the principal on ctx reads in now, without opening one: the one named, open or proposed; else their latest open one; else the one they proposed last, whose drafts still stand until it is accepted, so an agent that has proposed can follow its work. found is false when there is none.

func (*Engine) CurrentOfKind added in v2.3.0 

func (e *Engine) CurrentOfKind(ctx context.Context, kind string) ([]Version, error)

CurrentOfKind returns every manifest of a kind as it stands now (a working copy where there is one), in id order, in one read where the store can: what a front door that reads whole kinds needs, a report or an agent.

func (*Engine) CyclePeriods added in v2.9.0 

func (e *Engine) CyclePeriods(ctx context.Context, id, from, to string) ([]CyclePeriod, error)

CyclePeriods derives a cycle's periods that overlap two months (YYYY-MM). Derived here, once, so a web page, a terminal and an agent lay out the same periods (TAXONOMY.md D8, D40).

func (*Engine) DMAICOf added in v2.10.0 

func (e *Engine) DMAICOf(ctx context.Context, id string) (DMAIC, error)

DMAICOf reads a project's readiness for DMAIC, as ctx reads the workspace.

func (*Engine) DecisionModel added in v2.9.0 

func (e *Engine) DecisionModel(ctx context.Context) DecisionModel

DecisionModel reports the decision port's state, whatever is behind it.

func (*Engine) DeclineProposal added in v2.5.0 

func (e *Engine) DeclineProposal(ctx context.Context, id, actor, reason string) (store.Proposal, error)

DeclineProposal declines a proposal, as the person it was made for.

func (*Engine) Delete 

func (e *Engine) Delete(ctx context.Context, kind, id, actor, reason string) error

Delete excludes a manifest from the live state. Allowed only when nothing currently references it (leaf rule). Returns ValidationError listing every referencing manifest when the manifest is not a leaf; ErrNotFound when the manifest does not exist.

func (*Engine) DeleteGoal 

func (e *Engine) DeleteGoal(ctx context.Context, id, actor, reason string) error

DeleteGoal deletes a goal (goals are easily mutable), allowed only when nothing currently references it (a child goal's own parent, a Project/Programme/Operation/KPI's own alignment, or anything else the generic reference index tracks). Refused with a *ValidationError listing every referencing manifest when the goal is not empty of references; ErrNotFound when the goal does not exist. Calls Exclude to remove from vault.yaml while keeping the file.

func (*Engine) DependencyCycles 

func (e *Engine) DependencyCycles(ctx context.Context) ([][]string, error)

DependencyCycles returns every cycle in the graph, each as the ids it runs through, starting from the lowest for a stable reading. Two pieces of work each waiting on the other is a fact neither definition shows.

func (*Engine) DependencyGraph 

func (e *Engine) DependencyGraph(ctx context.Context) ([]DependencyEdge, error)

DependencyGraph reads every edge in the vault, normalised so they all point the same way: from the thing that waits, to the thing waited on. A "neededBy" edge is stored on the far end, so it is turned around here rather than leaving two conventions in one graph.

func (*Engine) DependencyScheduleConflicts 

func (e *Engine) DependencyScheduleConflicts(ctx context.Context) ([]ScheduleConflict, error)

DependencyScheduleConflicts is the check the edge exists for. It needs both ends to carry a timeline, so it is a project-to-project answer today; a programme schedules nothing, and a dependency on one is reported as unschedulable rather than as a conflict.

func (*Engine) Diff 

func (e *Engine) Diff(ctx context.Context, kind, id string, from, to int) ([]Change, error)

Diff computes the structural difference between two versions of a manifest.

func (*Engine) DirectWrite added in v2.9.0 

func (e *Engine) DirectWrite(ctx context.Context) error

DirectWrite answers whether a write may go straight to the record (a version, a working copy, a snapshot, a delete, a project state) or must be made in a change set: ErrChangeSetRequired when the workspace's policy says so.

func (*Engine) DiscardChangeItem added in v2.9.0 

func (e *Engine) DiscardChangeItem(ctx context.Context, set, kind, id string) error

DiscardChangeItem drops a draft from a change set the principal works in, as if it had never been drafted there: a draft saved under the wrong id, or one the work no longer needs. Refused while another draft in the set names it, listing them, since those would then name nothing.

func (*Engine) DiscardWorking 

func (e *Engine) DiscardWorking(ctx context.Context, kind, id string) error

DiscardWorking throws away a staged draft, putting back whatever the store holds as saved. Stores that keep no staging directory have nothing to discard, so this is a no-op for them rather than an error: the caller asked for the draft to be gone, and it is.

func (*Engine) DraftChecks added in v2.6.0 

func (e *Engine) DraftChecks(ctx context.Context, kind, id string) ([]Check, error)

DraftChecks computes the checks for a manifest as it stands: its draft where there is one, else its latest version.

func (*Engine) DraftProblems added in v2.9.0 

func (e *Engine) DraftProblems(ctx context.Context, kind, id string) ([]Problem, error)

DraftProblems validates a manifest as it stands, its draft where there is one, against its schema and rules, reading the other drafts of the change set on ctx as if saved: what a save or a proposal would refuse, said while the draft is being written rather than at the end.

func (*Engine) DropChangeItem added in v2.7.0 

func (e *Engine) DropChangeItem(ctx context.Context, set, kind, id string) error

DropChangeItem takes an item out of a change set altogether.

func (*Engine) EditDraft added in v2.7.0 

func (e *Engine) EditDraft(ctx context.Context, kind, id string, set map[string]any, unset []string, actor string) ([]byte, error)

EditDraft sets and clears single fields of a manifest's draft, by JSON pointer, and returns the draft as it then stands. Saving a whole manifest replaces the draft with the saver's copy, so anything someone else changed since that copy was read would be undone; an edit touches only the fields it names. With shared drafts it is made inside the draft's own lock, so a change a person made a moment before is kept, and the draft returned holds it, for the agent to build on. A manifest with no draft and no version yet starts as one, with only its id.

func (*Engine) EditInChangeSet added in v2.7.0 

func (e *Engine) EditInChangeSet(ctx context.Context, set, kind, id string, put map[string]any, unset []string) ([]byte, error)

EditInChangeSet sets and clears single fields of a change set's draft of a manifest, starting it from the record when the change set has none, and returns the draft as it then stands.

func (*Engine) Events added in v2.3.0 

func (e *Engine) Events(ctx context.Context, after int64, limit int) ([]store.Event, error)

Events returns what happened after a cursor, oldest first, from the store's event log. A store without one has none to give.

func (*Engine) ExportDir 

func (e *Engine) ExportDir(ctx context.Context, dir string) error

ExportDir writes the current version of every manifest to <dir>/<kind>/<id>.yaml, using the exact YAML text that was committed, so export is byte-for-byte reproducible. If the vault is vault-backed, also exports vault.yaml.

func (*Engine) ExportDirAs 

func (e *Engine) ExportDirAs(ctx context.Context, dir string, target codec.Codec) error

ExportDirAs is ExportDir in another syntax: the migration path between codecs. With the engine's own codec the committed text is written byte for byte; with another, every manifest is decoded and re-encoded, so the export opens as a vault of that codec and nothing else changes.

func (*Engine) ExportSemantic added in v2.10.0 

func (e *Engine) ExportSemantic(ctx context.Context, format string) ([]semantic.File, []string, error)

ExportSemantic writes the semantic layer in a syntax, with what the record leaves to defaults or out.

func (*Engine) FieldShapeAt added in v2.10.0 

func (e *Engine) FieldShapeAt(kind, pointer string) (FieldShape, bool)

FieldShapeAt is the shape of the field at a JSON pointer in a kind's manifest; list items are "-" or an index. False when the schema has no such field.

func (*Engine) FlowJSON 

func (e *Engine) FlowJSON(kind string) ([]byte, bool, error)

FlowJSON returns a kind's flow document exactly as written in the contract, or found=false for a kind that is a plain sheet. Served raw for the same reason schemas are: the order of steps and fields is the document's meaning.

func (*Engine) FlowKinds 

func (e *Engine) FlowKinds() []string

FlowKinds lists the kinds that have a flow, in registry order.

func (*Engine) FromIdea added in v2.9.0 

func (e *Engine) FromIdea(ctx context.Context, kind, idea string) ([]IdeaAnswer, bool)

FromIdea reads a rough idea for the questions kind's walk asks (its guidance's fromIdea), and returns, for each it can answer with confidence, the sentence that does. Without a decision model, or for a kind with no questions, it returns none: a guess would be worse than nothing, since the person can read their own idea.

func (*Engine) GapChecks 

func (e *Engine) GapChecks(ctx context.Context, id string) ([]ProgrammeCheck, error)

GapChecks says whether a gap can be used for what a gap register is for.

All advisory, and none of them blocks: every one reads a manifest other than this gap, so a gap that saved yesterday must not be refused today because somebody edited a project.

func (*Engine) GapCoverageFor 

func (e *Engine) GapCoverageFor(ctx context.Context, id string) (GapCoverage, error)

GapCoverageFor reads one gap's scope and everything that cites it.

func (*Engine) Get 

func (e *Engine) Get(ctx context.Context, kind, id string) (Version, error)

Get returns the current version of a manifest.

func (*Engine) GetMany added in v2.3.0 

func (e *Engine) GetMany(ctx context.Context, kind string, ids []string) ([]Version, error)

GetMany returns the current version of each of ids that exists, in id order: Get for a page of a list, in one read where the store can.

func (*Engine) GetProjectState 

func (e *Engine) GetProjectState(ctx context.Context, id string) (ProjectState, error)

GetProjectState returns a project's current state and its history. The project itself must exist (committed or draft-only is not enough: state applies to a committed project).

func (*Engine) GetSettings 

func (e *Engine) GetSettings(ctx context.Context) (Settings, error)

GetSettings returns the current Settings, defaulted where the imported document (if any) leaves a field empty. Its Purpose is the Purpose manifest's where there is one, else what Settings held before 2.7.0 (ADR 0020), so every reader of the vision and mission reads one place.

func (*Engine) GetState 

func (e *Engine) GetState(ctx context.Context) (State, error)

GetState returns the state manifest: its name and its include list.

func (*Engine) GetVersion 

func (e *Engine) GetVersion(ctx context.Context, kind, id string, number int) (Version, error)

GetVersion returns one specific historical version.

func (*Engine) GetWorking 

func (e *Engine) GetWorking(ctx context.Context, kind, id string) ([]byte, bool, error)

GetWorking returns a manifest's working copy (the file on disk that may not yet be versioned). Returns found=false when no working copy exists.

func (*Engine) Glossary added in v2.7.0 

func (e *Engine) Glossary(locale string) ([]GlossaryEntry, error)

Glossary is every word of the taxonomy in locale, in the order of work: the stages from the purpose down, then the registers, then what holds a stage's data.

func (*Engine) GoalChecks 

func (e *Engine) GoalChecks(ctx context.Context, id string) ([]GoalCheck, error)

GoalChecks reports whether a goal can be assessed: a title, a qualitative objective, a goal parent for an objective or an objective parent for an outcome, one to three key results each with a baseline (or an admitted unknown) and a target, scoring evidence, and at least one KPI referencing it. No check mentions a team or a cycle: the goal is the root of the dependency tree and never references a lower component, so nothing here reads spec.team or spec.reviewCycle, both removed from the schema.

func (*Engine) GoalTree 

func (e *Engine) GoalTree(ctx context.Context) (GoalTree, error)

GoalTree computes the goal tree from every current Goal manifest plus the reference index (which counts as aligned to a goal). It reads goals, gaps, indicators and references once each, however many goals there are (docs/adr/0012).

func (*Engine) GrantAgent added in v2.5.0 

func (e *Engine) GrantAgent(ctx context.Context, label string, ttl time.Duration) (store.AgentGrant, error)

GrantAgent records the signed-in person's consent to the agent they label acting for them, for ttl (90 days when 0, at most a year).

func (*Engine) GrantPerson added in v2.2.0 

func (e *Engine) GrantPerson(ctx context.Context, email string, roles, teams []string, agentsOff bool, actor string) (store.Person, error)

GrantPerson lists a person by their address, if they are not listed, and sets the roles and teams an administrator gives them.

func (*Engine) Grants added in v2.2.0 

func (e *Engine) Grants(ctx context.Context, p identity.Principal) (identity.Grants, error)

Grants returns what the access list gives p, recording the sign-in: who they are now and what their directory groups give them. A person not on the list is enrolled when their groups grant a role. A request writes nothing while nothing has changed, but for a refresh of the sign-in time every signInEvery.

func (*Engine) Graph added in v2.7.0 

func (e *Engine) Graph(ctx context.Context, focus *Ref) (Graph, error)

Graph returns every manifest and every reference between them, from the reference index the store already keeps: a list and one reverse lookup per kind, never a manifest read. An edge whose ends are not both in the graph is left out. Every node carries where the layout placed it, and, with a focus, how far it is from that one; the nodes come grouped by kind in the order of work and by id, so the same workspace is always placed alike.

func (*Engine) Guide added in v2.6.0 

func (e *Engine) Guide(ctx context.Context, kind, level, locale string) (Guide, error)

Guide puts a kind's guide together for one level (for a Goal: goal, objective or outcome; "" for every level), in locale, with the organisation's records as candidates.

func (*Engine) Handoff 

func (e *Engine) Handoff(ctx context.Context, projectID, actor string, req HandoffRequest) (HandoffResult, error)

Handoff records a project's handoff and stores the charter bundle through the BundleStore port. It passes HandoffGate first, writes the bundle, then records the state transition with the version and the bundle's location. Refused when nowhere keeps bundles.

func (*Engine) HandoffGate 

func (e *Engine) HandoffGate(ctx context.Context, projectID string) (snapshot int, err error)

HandoffGate is the rule a handoff must pass, and the version it hands off: no blocking check, at least one saved version, and that version not already handed off. Callers that render a document before handing off ask this first, so nothing is rendered for a project that would be refused. Handoff asks it again; the rule lives here once.

func (*Engine) HasAny added in v2.9.0 

func (e *Engine) HasAny(ctx context.Context, kind string) bool

HasAny reports whether the workspace holds a record of kind, saved or drafted in the work on ctx.

func (*Engine) HasState 

func (e *Engine) HasState() bool

HasState reports whether the store offers an apply gate.

func (*Engine) ImportDir 

func (e *Engine) ImportDir(ctx context.Context, dir, actor, reason string) (Report, error)

ImportDir reads every .yaml/.yml file under dir (recursively; a manifest's own kind and metadata.id decide where it goes, not its file path), validates the whole set together so members can reference each other, and if every file is valid commits them all in one transaction. If any file has a problem, nothing is written.

func (*Engine) InChangeSet added in v2.7.0 

func (e *Engine) InChangeSet(ctx context.Context, set string) (context.Context, error)

InChangeSet returns ctx reading the change set's drafts first.

func (*Engine) IncludeChangeItem added in v2.7.0 

func (e *Engine) IncludeChangeItem(ctx context.Context, set, kind, id string, included bool) error

IncludeChangeItem includes an item in the next acceptance, or trims it from it: the person it is for may, while it is open or proposed.

func (*Engine) KeepsAccess added in v2.2.0 

func (e *Engine) KeepsAccess() bool

KeepsAccess reports whether the engine keeps an access list.

func (*Engine) Kinds 

func (e *Engine) Kinds() []KindInfo

Kinds lists every registered kind and how many manifests exist for it. A store failure degrades to a zero count rather than an error, since the kind registry itself never fails and this method has no error return.

func (*Engine) LeaveOpen added in v2.9.0 

func (e *Engine) LeaveOpen(ctx context.Context, set, kind, id, check, reason string, correct bool) error

LeaveOpen records that a check on a draft is left for the person the change set is for, with the reason they will read: something only they can settle (a figure no document gives, a score nobody has made). The order of work then passes it by, and proposing waives it with that reason, so an agent says why once, as it goes, rather than all at the end. An empty reason takes it back; a second reason is added to the first unless correct puts it in its place.

func (*Engine) LineageOf added in v2.10.0 

func (e *Engine) LineageOf(ctx context.Context, id, name string, uses, produces []string) (Lineage, error)

LineageOf draws a project's data lineage from the data it uses and produces as given (the project as it is being edited, which may not be saved yet), and the rest of the workspace as ctx reads it: the projects producing what it uses, and the KPIs and projects reading what it produces. The engine places it, the same way every time.

func (*Engine) LinkCandidates added in v2.9.0 

func (e *Engine) LinkCandidates(ctx context.Context, link, from, problem string) ([]LinkCandidate, error)

LinkCandidates is every record a link of the given kind could reach from the record from (and, for a project's problem, that problem), each marked allowed or not with the reason, read as ctx reads the workspace, a change set's drafts included. The rules are the ones the checks hold (TAXONOMY.md D24, D28, D45), asked before the link is drawn rather than after it is saved.

func (*Engine) List 

func (e *Engine) List(ctx context.Context, kind string, f Filter, includeDrafts bool) ([]Summary, error)

List returns summaries of every manifest of a kind matching f. Sorted by id throughout, the same order ListSummaries's own committed results already use.

func (*Engine) ListAllVersions 

func (e *Engine) ListAllVersions(ctx context.Context, limit int, cursor string) ([]store.Version, string, error)

ListAllVersions returns every version across all kinds, newest first, with pagination.

func (*Engine) ListExcluded 

func (e *Engine) ListExcluded(ctx context.Context) ([]store.Exclusion, error)

ListExcluded lists every excluded manifest, newest first.

func (*Engine) ListFields added in v2.10.0 

func (e *Engine) ListFields(kind string) []string

ListFields are a kind's spec fields that hold lists, as JSON pointers, in the schema's order of names: what a document may give many of.

func (*Engine) ListPage added in v2.3.0 

func (e *Engine) ListPage(ctx context.Context, kind string, f Filter, afterID string, limit int) ([]Summary, bool, error)

ListPage returns one page of List: at most limit summaries with ids after afterID, and whether more follow. A store that pages reads only the page; any other is listed whole and sliced.

func (*Engine) ListUnapplied 

func (e *Engine) ListUnapplied(ctx context.Context) ([]UnappliedRef, error)

ListUnapplied lists every manifest present but not yet included and not excluded. An empty list, never nil.

func (*Engine) MarkInChangeSet added in v2.9.0 

func (e *Engine) MarkInChangeSet(ctx context.Context, set, kind, id, op, to string) error

MarkInChangeSet makes a change set's item of a manifest delete it (store.ItemDelete), or move a project to another state (store.ItemState, to). The item starts from the record as it stands, which must exist; an item the change set already holds keeps its text. Rolling the change set in applies it after the saves (docs/adr/0024).

func (*Engine) MatchExisting added in v2.9.0 

func (e *Engine) MatchExisting(ctx context.Context, kind, level, text string) []Match

MatchExisting returns the existing records of kind (and level) that say what text says, most likely first, as the model judges (docs/adr/0030). Without a model only the exact rule matches: the same name spelt otherwise, or by its initials. Shared words only find whom to ask.

func (*Engine) MayFollow added in v2.6.0 

func (e *Engine) MayFollow(ctx context.Context, person string) bool

MayFollow reports whether the principal on ctx may follow person's agents: their own, or anyone's for an administrator.

func (*Engine) MayWorkInSet added in v2.9.0 

func (e *Engine) MayWorkInSet(ctx context.Context, set string) bool

MayWorkInSet reports whether the principal on ctx may edit a change set's drafts: its owner, the person it is for, or any person while it is open, since change sets are live like every other draft (docs/adr/ 0024). An agent works in its own, and in its person's (docs/adr/0025).

func (*Engine) MergeInChangeSet added in v2.7.0 

func (e *Engine) MergeInChangeSet(ctx context.Context, set, kind, id string, previous, next []byte) ([]byte, error)

MergeInChangeSet applies to a change set's draft what changed between the text a person's editor last had (previous) and what it has now (next), field by field, a list being one field, so whatever the agent changed meanwhile in other fields is kept. With no previous, next replaces the draft.

func (*Engine) NamedRefs added in v2.10.0 

func (e *Engine) NamedRefs(ctx context.Context, set, kind string, fields map[string]any) (map[string]any, []string, error)

NamedRefs resolves, in fields about to be set on a kind's draft, every name given where a reference to a register goes (docs/adr/0027): the record of that kind with that name, in the record or the change set, else a new draft of it in the change set, named so. A small agent porting a document writes "Education Health Services Unit" where a team goes and the team is there, rather than being refused for an id it never had. It answers the fields as they are to be set, and the records it drafted.

func (*Engine) OpenInChangeSet added in v2.9.0 

func (e *Engine) OpenInChangeSet(ctx context.Context, id string) ([]OpenCheck, error)

OpenInChangeSet is every check still open across the drafts a change set would propose, each checked with the others: exactly what ProposeChangeSet refuses on, so an agent asking before it proposes hears the same answer it will get when it does.

func (*Engine) OpenNow added in v2.9.0 

func (e *Engine) OpenNow(ctx context.Context, set string) ([]OpenCheck, error)

OpenNow is what is open across a change set that can be settled now: what propose would refuse, less what is left for the person and what waits on a stage not written yet (an aim's measures before any KPI, an outcome's gap before any gap).

func (*Engine) OperationChecks 

func (e *Engine) OperationChecks(ctx context.Context, id string) ([]ProgrammeCheck, error)

OperationChecks says whether an operation is described well enough to be run and measured, step by step. Advisory only, like a programme's (D6): nothing about how a service is written down should stop anything. A service may be planned, running or retired (TAXONOMY.md D30).

func (*Engine) People added in v2.2.0 

func (e *Engine) People(ctx context.Context) ([]store.Person, error)

People returns the access list.

func (*Engine) Plan added in v2.7.0 

func (e *Engine) Plan(ctx context.Context, kind, level, locale string) ([]PlanItem, error)

Plan is the order of work for defining kind at level: everything the flows say it needs, in the order of work. What it names comes before it (a KPI's source and cycle, a gap's indicator and segments), then the thing itself, then what will name it, each after what it names in turn (for an objective: the outcomes under it, the indicator measuring each, and the gaps each closes). A register asked for on the way is placed just before what asks for it.

func (*Engine) PortFills added in v2.10.0 

func (e *Engine) PortFills(ctx context.Context, set string, work []string) ([]RecordFill, error)

PortFills is what each record of a port still needs, field by field: the checks open on it, each with the field that meets it, what to write and the sections that say it, the fields its schema requires, and the shape of each list or object once. A port writes every record from it in one call.

func (*Engine) PortPieces added in v2.10.0 

func (e *Engine) PortPieces(ctx context.Context, set string, src Source, pieces []structure.Piece) (PortLayout, error)

PortPieces lays out a port's pieces of work in its change set: it classifies them (refusing a workstream of the document's, or a component that is no row of its deliverable register), drafts every record, and writes every register the document has into the main project, a component's own rows into the component.

func (*Engine) PortRecords added in v2.10.0 

func (e *Engine) PortRecords(ctx context.Context, set string, records []PortRecord) ([]PortRecordResult, []RecordFill, error)

PortRecords writes every record of a port, each as one write: the fields the document gives set, the checks it does not answer left open with their reasons. It answers, record by record, what was refused and left, and what every record of the port still needs.

func (*Engine) PortfolioChecks added in v2.9.0 

func (e *Engine) PortfolioChecks(ctx context.Context, id string) ([]ProgrammeCheck, error)

PortfolioChecks reads one portfolio, what names it, and its decisions (TAXONOMY.md D32). Every check advises: each answer is read from other manifests, so, as for a programme (D6), none can stop a save.

func (*Engine) Preview added in v2.9.0 

func (e *Engine) Preview(ctx context.Context, set string) (context.Context, error)

Preview reads as if a change set were accepted: every read on the context it returns sees the change set's drafts in place of the records they change, and the records it creates (docs/adr/0024). ErrNotFound when there is no such change set.

func (*Engine) ProgrammeChecks 

func (e *Engine) ProgrammeChecks(ctx context.Context, id string) ([]ProgrammeCheck, error)

ProgrammeChecks reads one programme and everything that points at it.

func (*Engine) ProjectChecks 

func (e *Engine) ProjectChecks(ctx context.Context, id string, draft bool) (ProjectChecks, error)

ProjectChecks computes every per-section check for a project, evaluating the current committed version. Checks never block a save; they only report, and drive the draft-to-in-review submission gate (Blocking == 0).

func (*Engine) ProjectStates added in v2.3.0 

func (e *Engine) ProjectStates(ctx context.Context, ids []string) (map[string]string, error)

ProjectStates returns the current state of each project given, by id: GetProjectState for a list, without the history. A project with no history is a draft.

func (*Engine) Proposals added in v2.5.0 

func (e *Engine) Proposals(ctx context.Context, f store.ProposalFilter) ([]store.Proposal, error)

Proposals lists proposals. With no manifest named, only the caller's: those made for them, by their agents. With one, every proposal on it, for anyone who may read it.

func (*Engine) ProposeAppend added in v2.5.0 

func (e *Engine) ProposeAppend(ctx context.Context, kind, id, series string, item map[string]any, reason string) (store.Proposal, error)

ProposeAppend proposes recording one item of a series, checked as the manifest with it would be.

func (*Engine) ProposeChangeSet added in v2.7.0 

func (e *Engine) ProposeChangeSet(ctx context.Context, id, reason string, waive map[string]map[string]string) (store.ChangeSet, error)

ProposeChangeSet puts a change set up for its person to accept: every included item checked as one set, as a proposal set is, open checks refused unless waived with a reason (by Kind/id, then check id).

func (*Engine) ProposeSave added in v2.5.0 

func (e *Engine) ProposeSave(ctx context.Context, kind, id string, text []byte, reason string, waive map[string]string) (store.Proposal, error)

ProposeSave proposes committing text as the manifest's next version: ProposeSet with one member, its waivers keyed by check.

func (*Engine) ProposeSet added in v2.6.0 

func (e *Engine) ProposeSet(ctx context.Context, members []SetMember, reason string, waive map[string]map[string]string) ([]store.Proposal, error)

ProposeSet proposes several manifests that stand or fall together, such as a KPI, the gap it measures and the outcome that closes it: they are validated against each other, so one may reference another; accepted together in one transaction, in the order their references need; or declined together. waive is keyed by "Kind/id", then by check.

func (*Engine) ProposeState added in v2.5.0 

func (e *Engine) ProposeState(ctx context.Context, id, to, reason string) (store.Proposal, error)

ProposeState proposes moving a project, checked against the state machine and, for a handoff, its blocking checks.

func (*Engine) PutWorking 

func (e *Engine) PutWorking(ctx context.Context, kind, id string, yamlBytes []byte) error

PutWorking writes a manifest's YAML as the working copy without creating a version. Used for autosave writes that don't create an explicit snapshot. It also re-indexes the manifest's outgoing references.

func (*Engine) ReadSections added in v2.10.0 

func (e *Engine) ReadSections(ctx context.Context, set string, ids []string) ([]SectionText, error)

ReadSections reads sections of the documents in a change set by id ("s4", or "2:s4" for the second document).

func (*Engine) ReconcileSeries added in v2.3.0 

func (e *Engine) ReconcileSeries(ctx context.Context, ids map[string][]string) (int, error)

ReconcileSeries brings the series items of manifests in line with their latest saved versions, recording what the rows lack: the whole series of a manifest saved before its items were kept, and what a replica of an earlier release saved during a rolling upgrade. ids limits it to some manifests of each kind; nil is all of them. It returns how many items it recorded.

func (*Engine) Recover 

func (e *Engine) Recover(ctx context.Context, ref, actor, reason string) (State, error)

Recover re-includes an excluded manifest, then reloads and reindexes.

func (*Engine) References 

func (e *Engine) References(ctx context.Context, kind, id string) (Refs, error)

References returns what a manifest points to (Outgoing) and what points back at it (Incoming).

func (*Engine) ReferencingKind added in v2.3.0 

func (e *Engine) ReferencingKind(ctx context.Context, kind string) (map[string][]Summary, error)

ReferencingKind returns, for every manifest of a kind that something references, what references it, by id: References for a whole kind.

func (*Engine) RegisterInto added in v2.10.0 

func (e *Engine) RegisterInto(ctx context.Context, set, kind, id, section, field string, route map[string]string) (RegisterResult, error)

RegisterInto writes a section's register into a record's list, row by row as an agent's write is applied: the rows the porting map does not port are answered under NotPorted with the reason, a row a component owns (by route, its code to the component) goes into the component, and a row's refused cells are dropped so the rest of it is kept.

func (*Engine) RegisterOf added in v2.10.0 

func (e *Engine) RegisterOf(ctx context.Context, set, section, field string) ([]map[string]any, error)

RegisterOf reads the rows of a section's tables as items of a project's list field (milestones, deliverables, risks, the KPIs it names).

func (*Engine) Reindex 

func (e *Engine) Reindex(ctx context.Context) error

Reindex walks every current manifest and indexes its outgoing references. Called after the vault rehydrates to rebuild the reference index from scratch. Also stores working copies so ListReferencing can find them.

func (*Engine) Relevant added in v2.9.0 

func (e *Engine) Relevant(ctx context.Context, text string, kinds []string, level string, limit int) (Relevance, error)

Relevant ranks the records of kinds (a goal's level, when level is set) by how relevant they are to text, and returns up to limit of each, likeliest first.

func (*Engine) RemovePerson added in v2.2.0 

func (e *Engine) RemovePerson(ctx context.Context, email string) error

RemovePerson takes a person off the access list. An administrator may not remove themselves.

func (*Engine) ReopenChangeSet added in v2.7.0 

func (e *Engine) ReopenChangeSet(ctx context.Context, id, reason string) (store.ChangeSet, error)

ReopenChangeSet takes a proposed change set back to work, as its person asking for changes, or who works in it withdrawing it.

func (*Engine) RepairDocs added in v2.3.0 

func (e *Engine) RepairDocs(ctx context.Context) (int, error)

RepairDocs gives a document to every version and working copy a store holds as text alone, a batch at a time, and returns how many it gave. A store that always has its documents needs nothing, and gets nothing.

func (*Engine) RetitleChangeSet added in v2.7.0 

func (e *Engine) RetitleChangeSet(ctx context.Context, id, title, description string) (store.ChangeSet, error)

RetitleChangeSet changes what a change set says it is.

func (*Engine) RevokeAgentGrant added in v2.5.0 

func (e *Engine) RevokeAgentGrant(ctx context.Context, id string) error

RevokeAgentGrant ends a grant at once: the caller's own, or anyone's for an administrator.

func (*Engine) SaveInChangeSet added in v2.7.0 

func (e *Engine) SaveInChangeSet(ctx context.Context, set, kind, id string, text []byte) error

SaveInChangeSet keeps a whole manifest as a change set's draft of it.

func (*Engine) SaveWorking 

func (e *Engine) SaveWorking(ctx context.Context, kind, id string, text []byte, actor string) error

SaveWorking writes a whole working copy, as an autosave or an import does, and folds it into the manifest's shared draft, so a client that saves whole documents and one that syncs end in the same draft.

func (*Engine) Schedule added in v2.9.0 

func (e *Engine) Schedule(ctx context.Context, id string) ([]ScheduleItem, error)

Schedule places a project's milestones on time, as ctx reads it. Each after-timing takes the month of what it follows plus its lag, in this project or another (TAXONOMY.md D47); a loop leaves the milestones on it unplaced. Nothing is rescheduled: this says what the definition implies.

func (*Engine) Schema 

func (e *Engine) Schema(kind string) (map[string]any, error)

func (*Engine) SchemaDefs added in v2.9.0 

func (e *Engine) SchemaDefs(kind string) (map[string]any, error)

SchemaDefs are the shared definitions a kind's schema points into (common.schema.json's Metadata, Ref, KeyResult and the rest), by name, followed through each other: so whoever reads the schema can see every field without resolving a reference.

func (*Engine) SchemaJSON 

func (e *Engine) SchemaJSON(kind string) ([]byte, error)

Schema returns the raw JSON Schema document for a kind. SchemaJSON returns a kind's schema exactly as it is written on disk.

Schema() decodes into a map, which loses the order the properties were written in; the interface builds a sheet's columns from that order, so serving the decoded map alphabetised every sheet. This serves the file.

func (*Engine) SectionsFor added in v2.10.0 

func (e *Engine) SectionsFor(ctx context.Context, set, field string) []string

SectionsFor are the ids of the sections of a change set's documents most likely to answer a field.

func (*Engine) SeedStandardUnits 

func (e *Engine) SeedStandardUnits(ctx context.Context) ([]string, error)

SeedStandardUnits writes the standard units into a store that holds no Unit at all, and reports which it wrote.

Guarded twice, and the second guard is the one that matters. The first is "none at all" rather than each one, so a vault that has dropped a unit it does not want keeps it dropped. The second refuses to write over a manifest that already exists, because the first guard reads a listing, and a listing is empty for two different reasons: the vault holds no units, or the vault's index has not been built yet. Opening a vault without its (generated, uncommitted) index once took the second for the first and rewrote every one of its unit files, reordering their keys and dropping their quoting, on a read-only visit.

Writes through the ordinary commit path, so a seeded unit is a manifest like any other and can be edited, renamed or deleted.

func (*Engine) SemanticFormats added in v2.10.0 

func (e *Engine) SemanticFormats() []string

SemanticFormats lists the syntaxes the KPIs can be exported in.

func (*Engine) SemanticLayer added in v2.10.0 

func (e *Engine) SemanticLayer(ctx context.Context) (semantic.Layer, []string, error)

SemanticLayer is the record as a semantic layer: each data source a KPI measures from as a semantic model, each KPI with a metric as a metric, in the semantic layer's own terms, read as ctx reads the workspace. The notes say what the record leaves to defaults or out.

func (*Engine) SeriesAsOf added in v2.3.0 

func (e *Engine) SeriesAsOf(ctx context.Context, kind, series string, ids []string, at time.Time) (map[string][]store.SeriesItem, error)

SeriesAsOf returns a manifest's series items as they stood at at (the zero time for now), for every manifest of the kind when ids is nil. On a store without series items, the items are read out of the current manifests, recorded as of their version.

func (*Engine) SeriesKinds added in v2.3.0 

func (e *Engine) SeriesKinds() []string

SeriesKinds are the kinds that have a series.

func (*Engine) Shape 

func (e *Engine) Shape(kind string) crdt.Shape

Shape says how a kind's manifests map onto a CRDT document, read from the kind's schema so the engine and every interface agree without either deciding it by hand:

  • A list of objects is keyed by x-cartograph-list-key when the schema names one, otherwise by "id" when its items have an id. A keyed item keeps its identity when other items move, so an edit inside it is never lost to a reorder.
  • A string is a text, merged character by character, when it is free prose: no enum, const, format, pattern, or x-cartograph-ref. Everything else (an id, a reference, a date, a choice) is a scalar, where the last write wins and a concurrent one is kept as a conflict, because merging two ids character by character would produce an id nobody wrote.

func (*Engine) Shared 

func (e *Engine) Shared() *Shared

Shared returns the shared-draft service, or nil when the engine has no CRDT, document store or fan-out.

func (*Engine) Snapshot 

func (e *Engine) Snapshot(ctx context.Context, kind, id string, yamlBytes []byte, reason, operator string) (Version, error)

Snapshot validates a manifest and, if it is valid, stores it as a new immutable version with the reason and operator as the actor. Similar to Commit but used explicitly for creating snapshots. The manifest's metadata.id must match id. operator is recorded as the actor. For a Project with no state history, appends a "defined" state entry.

func (*Engine) Sources added in v2.10.0 

func (e *Engine) Sources(ctx context.Context, set string) ([]Source, error)

Sources are the documents brought into a change set, with every section's text.

func (*Engine) StartChangeSet added in v2.7.0 

func (e *Engine) StartChangeSet(ctx context.Context, title, description string) (store.ChangeSet, error)

StartChangeSet opens a change set for the principal on ctx to work in.

func (*Engine) StructuralProblems added in v2.10.0 

func (e *Engine) StructuralProblems(_ context.Context, kind string, text []byte) ([]Problem, error)

StructuralProblems are what is built wrong in a manifest, as against what is not finished yet (docs/adr/0027): every failure of the kind's strict profile (its schema with the shapes the discipline refuses, such as a second objective on a project, or a person's name on a role) or of its schema that more writing cannot mend. An agent's draft with any is refused, so an improper structure is never saved, however it is sent.

func (*Engine) Taxonomy added in v2.7.0 

func (e *Engine) Taxonomy(locale string) ([]TaxonomyEntry, error)

Taxonomy is every kind a person defines, in the order of work (the stages from the purpose down, then the registers), with what it is, what it names and what documents call it, so whatever a document says is recorded as the kind it is, by its definition, not by its label, and in an order where everything it names is already there.

func (*Engine) TeamName added in v2.2.0 

func (e *Engine) TeamName(ctx context.Context, id string) string

TeamName returns a team's name, or its id when there is no such team.

func (*Engine) TeamsBeneath added in v2.2.0 

func (e *Engine) TeamsBeneath(ctx context.Context, teams []string) ([]string, error)

TeamsBeneath returns teams and every team below any of them, sorted.

func (*Engine) TransitionProjectState 

func (e *Engine) TransitionProjectState(ctx context.Context, id, to, actor, reason string) (ProjectState, error)

func (*Engine) Understand added in v2.9.0 

func (e *Engine) Understand(ctx context.Context, text, locale string) (Understanding, error)

Understand reads a text a person typed against the record and the order of work: which existing record says the same, and which three flows are likeliest to define it. It never picks a flow for the person: measured, the first was right only half the time.

func (*Engine) UnnamedInChangeSet added in v2.9.0 

func (e *Engine) UnnamedInChangeSet(ctx context.Context, set string) ([]Ref, error)

UnnamedInChangeSet lists the register drafts in a change set that no record and no other draft names: declared, as a document listed them, and then never used. Not wrong in itself, but worth a look before proposing: either something should name it, or it should not be there.

func (*Engine) Validate 

func (e *Engine) Validate(ctx context.Context, kind string, yamlBytes []byte) ([]Problem, error)

Validate checks a manifest's schema, its references and its kind's rules, in that order, against the current store state (no in-flight import batch).

func (*Engine) Versions 

func (e *Engine) Versions(ctx context.Context, kind, id string) ([]Version, error)

Versions returns every version of a manifest, oldest first.

func (*Engine) ViewChangeSet added in v2.7.0 

func (e *Engine) ViewChangeSet(ctx context.Context, id string) (ChangeSetView, error)

ViewChangeSet reads a change set for review.

func (*Engine) ViewProposal added in v2.6.0 

func (e *Engine) ViewProposal(ctx context.Context, id string) (ProposalView, error)

ViewProposal returns a proposal with what each part would change and its checks, the checks seeing the rest of its set. A proposal is read by whoever may read its manifest.

func (*Engine) Work added in v2.7.0 

func (e *Engine) Work(ctx context.Context, work []Ref, locale string) (Worklist, error)

Work lists the open checks of the manifests named and of everything the work joins them to, drafts included and checked as one set, in the order they are best settled.

func (*Engine) WorkAround added in v2.7.0 

func (e *Engine) WorkAround(ctx context.Context, kind, id string, also []Ref) ([]Around, error)

WorkAround returns the manifests joined to kind/id along the links the flows say finish the work, as far as they reach, each with its open checks: so whoever is defining an outcome is told that the gap it closes has no indicator yet. Saved links are read from the index; drafts are read where they are, and also names more manifests to read as drafts (what an agent is defining together), checked as one set.

func (*Engine) WorkingChangeSet added in v2.7.0 

func (e *Engine) WorkingChangeSet(ctx context.Context, id string) (store.ChangeSet, error)

WorkingChangeSet is the change set the principal on ctx works in: id when given (theirs, and open), else their latest open one, else a new one.

func (*Engine) WorksIn added in v2.9.0 

func (e *Engine) WorksIn(ctx context.Context, cs store.ChangeSet) bool

WorksIn reports whether the principal on ctx works in the change set as its own: opened it, rather than was brought into it.

func (*Engine) WorkspaceOrder added in v2.7.0 

func (e *Engine) WorkspaceOrder(ctx context.Context) (Order, error)

WorkspaceOrder says, for the workspace as it stands, how far each stage has got and which comes next: the first stage a plan needs that has no record and is not waiting on one that has none. An empty workspace starts at its purpose.

func (*Engine) WriteFields added in v2.10.0 

func (e *Engine) WriteFields(ctx context.Context, set, kind, id string, put map[string]any, unset []string, merge bool) ([]Problem, []string, error)

WriteFields sets and clears fields on a change set's draft the way an agent's write is applied (docs/adr/0027): a name where a register's reference goes finds or drafts it, a value is read in its field's format, and every field that can be kept is kept (a list item keyed by id is given one, as in every edit). With merge, a list the draft already holds is merged by id or name, never replaced, so what a port wrote into it is never lost to a later write.

It answers the problems refused, field by field, and the records it drafted (with lines cut prefixed "cut: " and names refused prefixed "refused: "). A write that keeps nothing is a ValidationError.

type Event 

type Event struct {
	Type string    `json:"type"` // version, state
	Kind string    `json:"kind,omitempty"`
	ID   string    `json:"id,omitempty"`
	On   time.Time `json:"on"`
	// Seq is the version number for a version event.
	Seq int64 `json:"seq,omitempty"`
	// Actor is who did it.
	Actor string `json:"actor,omitempty"`
	// Field is where, when the event concerns one field.
	Field string `json:"field,omitempty"`
}

Event is one thing that happened to a manifest that an open interface wants to know about without asking: a version saved, its state changed. Interfaces subscribe through the Bus; transports (an SSE stream, an in-process channel) carry what the bus emits. Live edits and presence are not events: they travel on the sync socket.

type FieldShape added in v2.10.0 

type FieldShape struct {
	Example  any      `json:"example"`
	Optional []string `json:"optional,omitempty"`
	// OneOf are the values a fixed choice takes.
	OneOf []string `json:"oneOf,omitempty"`
}

FieldShape is what goes at a field, read from the kind's schema: a minimal example with every required part, and the names of the optional ones, so an agent can write a whole list (every milestone, every risk) in one call without reading the guide for each.

type FileProblems 

type FileProblems struct {
	File     string    `json:"file"`
	Problems []Problem `json:"problems"`
}

type FillItem added in v2.10.0 

type FillItem struct {
	Check string      `json:"check"`
	Do    string      `json:"do"`
	Field string      `json:"field,omitempty"`
	Read  []string    `json:"read,omitempty"`
	Shape *FieldShape `json:"shape,omitempty"`
}

FillItem is one thing a record still needs: the check it meets or the field its schema requires, what to write, and the document's sections that say it.

type Filter 

type Filter struct {
	Q    string
	Refs []Ref
}

Filter narrows List: Q is a case-insensitive substring over id and name; every entry in Refs must match one of the manifest's outgoing references (logical AND).

type GapClaim 

type GapClaim struct {
	Kind string `json:"kind"`
	ID   string `json:"id"`
	Name string `json:"name"`
	// Segments of the gap this work reaches. Empty means the whole gap,
	// which is what an unqualified citation says.
	Segments []string `json:"segments,omitempty"`
	// Whole is true when the citation named no segments.
	Whole bool `json:"whole"`
}

GapClaim is one piece of work addressing one gap.

type GapCoverage 

type GapCoverage struct {
	Gap string `json:"gap"`
	// Segments in the gap's own order, each with the work addressing it.
	Segments []GapSegmentCoverage `json:"segments"`
	// Claims on the gap as a whole: citations that named no segments.
	Whole []GapClaim `json:"whole,omitempty"`
}

GapCoverage is a gap's scope and what reaches each part of it.

type GapSegmentCoverage 

type GapSegmentCoverage struct {
	Segment   string     `json:"segment"`
	Name      string     `json:"name"`
	Addressed []GapClaim `json:"addressedBy,omitempty"`
}

GapSegmentCoverage is one of a gap's segments and who is addressing it.

type GlossaryEntry added in v2.7.0 

type GlossaryEntry struct {
	// Key is the stage's key, or for a register its kind.
	Key   string `json:"key"`
	Kind  string `json:"kind"`
	Level string `json:"level,omitempty"`
	// Summary says what it is, in one plain sentence; Example is one
	// instance of it.
	Summary string `json:"summary"`
	Example string `json:"example,omitempty"`
	// After are the stages it comes after in the order of work.
	After    []string `json:"after,omitempty"`
	Register bool     `json:"register,omitempty"`
}

GlossaryEntry is one word of the taxonomy: a stage of the order of work (a kind, or a Goal at a level) or a register.

type GoalAligned 

type GoalAligned struct {
	Projects   int `json:"projects"`
	Programmes int `json:"programmes"`
	Operations int `json:"operations"`
	KPIs       int `json:"kpis"`
}

GoalAligned is how many manifests of each kind reference a goal, by referencing kind. Anything that references a goal counts as aligned to it; kinds outside this set are not counted here.

type GoalCheck 

type GoalCheck struct {
	ID      string        `json:"id"`
	State   string        `json:"state"` // ok, warn
	Message string        `json:"message"`
	Fix     *GoalCheckFix `json:"fix,omitempty"`
}

GoalCheck is one assessability check on a Goal. Checks never block a save; they only report.

type GoalCheckFix 

type GoalCheckFix struct {
	Section string `json:"section"`
	// Goal is the aim whose editor holds the fix, when it is not the one
	// checked.
	Goal string `json:"goal,omitempty"`
}

GoalCheckFix names which section of the goal editor addresses a check.

type GoalGap 

type GoalGap struct {
	ID      string `json:"id"`
	Name    string `json:"name"`
	Current string `json:"current,omitempty"`
	Desired string `json:"desired,omitempty"`
}

GoalGap is a gap that names this goal as the outcome that closes it. 

type GoalLink struct {
	Goal    string `json:"goal" yaml:"goal"`
	Because string `json:"because,omitempty" yaml:"because"`
}

GoalLink is an outcome leading to a higher objective, and why.

type GoalNode 

type GoalNode struct {
	ID         string      `json:"id"`
	Name       string      `json:"name"`
	Level      string      `json:"level"`
	Parent     string      `json:"parent,omitempty"`
	KeyResults int         `json:"keyResults"`
	Aligned    GoalAligned `json:"aligned"`
	Children   []*GoalNode `json:"children"`
	// What the Strategy view reads (D24): the statement, why it matters,
	// what else it leads to, and the gaps it would close.
	Objective     string     `json:"objective,omitempty"`
	Why           string     `json:"why,omitempty"`
	ContributesTo []GoalLink `json:"contributesTo,omitempty"`
	Gaps          []GoalGap  `json:"gaps,omitempty"`
	// Which SMART letters it meets (D25), for a mark on every card.
	Smart Smart `json:"smart"`
	// The role accountable for it, and the period it covers (its own or
	// its parent's), so every card carries its context (D26).
	Owner   string   `json:"owner,omitempty"`
	Horizon *Horizon `json:"horizon,omitempty"`
	// Proposed is "new" or "changed" when the tree is read as if a change
	// set were accepted and this goal is in it (docs/adr/0024).
	Proposed string `json:"proposed,omitempty"`
}

GoalNode is one record in the tree, with its objectives nested as Children (for a goal) or its outcomes nested as Children (for an objective), or no children (for an outcome).

type GoalTree 

type GoalTree struct {
	Levels []string    `json:"levels"`
	Nodes  []*GoalNode `json:"nodes"`
	// Unplaced are objectives and outcomes with no parent yet (TAXONOMY.md
	// D35), each with what sits under it.
	Unplaced []*GoalNode `json:"unplaced"`
}

GoalTree is the whole tree: every level's display name, and the root goals, each carrying its objectives as Children, and each objective carrying its outcomes as Children.

type Graph added in v2.7.0 

type Graph struct {
	Nodes []GraphNode
	Edges []GraphEdge
}

Graph is every manifest and every reference between them.

type GraphEdge added in v2.7.0 

type GraphEdge struct {
	From, To Ref
}

GraphEdge is one reference: From names To somewhere in its spec, so To comes before From in the order of work.

type GraphNode added in v2.7.0 

type GraphNode struct {
	Kind, ID, Name string
	// Proposed is "new" or "changed" when the graph is read as if a
	// change set were accepted and this manifest is in it.
	Proposed string
	// Level is a goal's level (goal, objective, outcome); empty otherwise.
	Level string
	// Stage is the stage of the order of work it is written in; empty
	// for a register. Layer is its band in the graph: 0 for the
	// registers, then one per stage, so every edge runs to a lower layer
	// or along its own (TAXONOMY.md D28).
	Stage string
	Layer int
	// X and Y are where the layout put it.
	X, Y float64
	// Distance is how many edges, either way, it is from the focus asked
	// for; -1 when nothing joins them or no focus was asked for.
	Distance int
}

GraphNode is one manifest in the workspace graph.

type Guide added in v2.6.0 

type Guide struct {
	Kind       string `json:"kind"`
	Locale     string `json:"locale"`
	Definition string `json:"definition"`
	Level      string `json:"level,omitempty"`
	LevelIs    string `json:"levelIs,omitempty"`
	// Plan is the work around it, in the order of work: what it names,
	// before it, then what will name it (for an objective: its outcomes,
	// the KPI measuring each, then the gaps they close).
	Plan    []PlanItem        `json:"plan,omitempty"`
	Levels  map[string]string `json:"levels,omitempty"`
	Purpose *Purpose          `json:"purpose,omitempty"`
	// Existing is the records of this kind (at this level) already
	// defined: reuse or improve one before defining another.
	Existing []Candidate `json:"existing"`
	// Template is a manifest of this kind with its envelope and required
	// fields, to fill in.
	Template map[string]any    `json:"template"`
	Steps    []GuideStep       `json:"steps"`
	Checks   map[string]string `json:"checks,omitempty"`
	// Vocabulary is words an interface offers for writing a field in this
	// language; never used to judge one.
	Vocabulary map[string][]string `json:"vocabulary,omitempty"`
}

Guide is a kind's guide for one level, in one language, with the organisation's context.

type GuideBundle added in v2.6.0 

type GuideBundle struct {
	Locale     string            `json:"locale"`
	Kind       string            `json:"kind"`
	Summary    string            `json:"summary"`
	Example    string            `json:"example,omitempty"`
	KnownAs    []string          `json:"knownAs,omitempty"`
	Definition string            `json:"definition"`
	Levels     map[string]string `json:"levels,omitempty"`
	// LevelExamples are one instance of each level, as Example is for the
	// kind.
	LevelExamples map[string]string `json:"levelExamples,omitempty"`
	// Terms are other words the kind holds, each defined as the kind is.
	Terms map[string]GuideTerm `json:"terms,omitempty"`
	// Judgements are checks a decision model answers, by check id.
	Judgements map[string]GuideJudgement `json:"judgements,omitempty"`
	// Cues are how a decision model recognises a typed text as this kind,
	// by stage key.
	Cues map[string]string `json:"cues,omitempty"`
	// FromIdea are the questions a rough idea is read for, by name.
	FromIdea   map[string]GuideIdeaQuestion `json:"fromIdea,omitempty"`
	Steps      map[string]GuideStepWords    `json:"steps,omitempty"`
	Fields     map[string]GuideFieldWords   `json:"fields"`
	Links      map[string]GuideLinkWords    `json:"links,omitempty"`
	Checks     map[string]string            `json:"checks,omitempty"`
	Vocabulary map[string][]string          `json:"vocabulary,omitempty"`
}

GuideBundle is a guidance file as written: words only, in one language.

func GuideBundleFor added in v2.6.0 

func GuideBundleFor(kind, locale string) (GuideBundle, bool, error)

GuideBundleFor returns a kind's guidance in locale, or in the default language when there is none in locale.

type GuideField added in v2.6.0 

type GuideField struct {
	Path       string      `json:"path"`
	Control    string      `json:"control"`
	Guide      string      `json:"guide,omitempty"`
	Good       []string    `json:"good,omitempty"`
	Poor       []GuidePoor `json:"poor,omitempty"`
	Checks     []string    `json:"checks,omitempty"`
	References string      `json:"references,omitempty"`
	Candidates []Candidate `json:"candidates,omitempty"`
	// Required says the field must be filled: the schema requires it
	// where it sits, or one of its checks blocks a handoff while it is
	// empty. Every interface marks it the same way, and an agent knows
	// which answers it cannot leave out.
	Required bool `json:"required,omitempty"`
	// MaxLength, Values, Format and Shape are what the schema holds the
	// field to, so an agent writes a value it will take without reading
	// the schema: the longest it may be, the values it may take, how a
	// date is written, and the JSON a reference, a period or a list item
	// is written as.
	MaxLength int    `json:"maxLength,omitempty"`
	Values    []any  `json:"values,omitempty"`
	Format    string `json:"format,omitempty"`
	Shape     string `json:"shape,omitempty"`
}

GuideField is one field: its path, what it asks for with examples, the checks it answers, and for a reference the kind it names and the organisation's records of that kind to choose from.

type GuideFieldWords added in v2.6.0 

type GuideFieldWords struct {
	Guide  string                     `json:"guide"`
	Good   []string                   `json:"good,omitempty"`
	Poor   []GuidePoor                `json:"poor,omitempty"`
	Levels map[string]GuideFieldWords `json:"levels,omitempty"`
}

GuideFieldWords are what a field asks for, with examples.

type GuideIdeaQuestion added in v2.9.0 

type GuideIdeaQuestion struct {
	Question string `json:"question"`
	Field    string `json:"field"`
	Cue      string `json:"cue"`
}

GuideIdeaQuestion is one question a rough idea is read for: the question a step asks, the field it fills, and the cue a sentence is matched against.

type GuideJudgement added in v2.9.0 

type GuideJudgement struct {
	Path   string      `json:"path"`
	Levels []string    `json:"levels,omitempty"`
	Good   GuideOption `json:"good"`
	Poor   GuideOption `json:"poor"`
	Pass   string      `json:"pass"`
	Fail   string      `json:"fail"`
}

GuideJudgement is a check a decision model answers about one field: a contrast between a good option and a poor one, asked good first. 

type GuideLink struct {
	Kind       string      `json:"kind"`
	Path       string      `json:"path"`
	Check      string      `json:"check,omitempty"`
	Ask        string      `json:"ask,omitempty"`
	IfNone     string      `json:"ifNone,omitempty"`
	Candidates []Candidate `json:"candidates,omitempty"`
}

GuideLink is a link held on another kind, naming this manifest: what to ask, what to do when none fits, and that kind's records.

type GuideLinkWords added in v2.6.0 

type GuideLinkWords struct {
	Ask    string `json:"ask"`
	IfNone string `json:"ifNone"`
}

GuideLinkWords are what to ask for a link, and what to do when there is nothing to link to.

type GuideOption added in v2.9.0 

type GuideOption struct {
	Key   string `json:"key"`
	Label string `json:"label"`
}

GuideOption is one side of a judgement's contrast.

type GuidePoor added in v2.6.0 

type GuidePoor struct {
	Text string `json:"text"`
	Why  string `json:"why"`
}

GuidePoor is a plausible wrong value and why it is wrong.

type GuideStep added in v2.6.0 

type GuideStep struct {
	Key    string       `json:"key"`
	Title  string       `json:"title"`
	Guide  string       `json:"guide,omitempty"`
	Fields []GuideField `json:"fields"`
	Links  []GuideLink  `json:"links,omitempty"`
}

GuideStep is one step: what it settles, its fields, and the links it makes on other manifests.

type GuideStepWords added in v2.6.0 

type GuideStepWords struct {
	Title string `json:"title,omitempty"`
	Guide string `json:"guide,omitempty"`
}

GuideStepWords are a step's title and guide in one language.

type GuideTerm added in v2.7.0 

type GuideTerm struct {
	Summary string `json:"summary"`
	Example string `json:"example"`
}

GuideTerm is one word a kind holds besides its own name: a project's component, say.

type Handoff added in v2.5.0 

type Handoff func(ctx context.Context, projectID, reason string) (int, error)

Handoff is how the caller of AcceptProposal hands a project off, which renders and prints a charter the engine does not: it returns the version handed off.

type HandoffFunc added in v2.9.0 

type HandoffFunc func(ctx context.Context, projectID, actor, reason string) error

HandoffFunc hands a project off: renders its charter and records the hand-off (Engine.Handoff). The caller that can render supplies it, on the context a change set is rolled in with (WithHandoff); without one, a change set's hand-off item is kept for later.

type HandoffRequest 

type HandoffRequest struct {
	HtmlBytes []byte // Rendered HTML charter
	JsonBytes []byte // Rendered JSON charter
	PdfBytes  []byte // Rendered PDF charter (optional, can be nil)
}

HandoffRequest carries the rendered charter a handoff stores.

type HandoffResult 

type HandoffResult struct {
	HtmlPath string
	JsonPath string
	PdfPath  string
	Bundle   string // what the state history records: the bundle's location
}

HandoffResult is returned by Handoff on success: where the charter bundle went (HTML, JSON, and PDF when one was printed).

type Horizon 

type Horizon struct {
	Start string `json:"start"`
	End   string `json:"end"`
	// Inherited is true when the aim has none of its own and takes its
	// parent's.
	Inherited bool `json:"inherited,omitempty"`
}

Horizon is the period an aim covers, as "YYYY-MM" at each end.

type IdeaAnswer added in v2.9.0 

type IdeaAnswer struct {
	Key        string  `json:"key"`
	Question   string  `json:"question"`
	Field      string  `json:"field"`
	Sentence   string  `json:"sentence"`
	Likelihood float64 `json:"likelihood"`
}

IdeaAnswer is the sentence of a rough idea that answers one question a walk asks.

type ImportedItem 

type ImportedItem struct {
	Kind    string `json:"kind"`
	ID      string `json:"id"`
	Version int    `json:"version"`
}

type Judged added in v2.10.0 

type Judged struct {
	Holds bool
	Sure  float64
}

Judged is a judgement's answer about one text: whether it holds, and how sure the model is, the averaged probability of yes.

type KindInfo 

type KindInfo struct {
	Kind  string `json:"kind"`
	Count int    `json:"count"`
	// Summary is the kind in one sentence, from its guidance.
	Summary string `json:"summary,omitempty"`
}

KindInfo is one row of GET /api/v1/kinds.

type Lineage added in v2.10.0 

type Lineage struct {
	Nodes []LineageNode
	Edges []GraphEdge
}

Lineage is a project's data lineage: where its data comes from, what it produces, and what reads that, every edge in the direction the data flows.

type LineageNode added in v2.10.0 

type LineageNode struct {
	Kind, ID, Name string
	Role           string
	X, Y           float64
}

LineageNode is one thing in a project's data lineage, placed in its column (X) and its row in that column (Y).

type LinkCandidate added in v2.9.0 

type LinkCandidate struct {
	Kind    string
	ID      string
	Name    string
	Allowed bool
	Linked  bool
	Reason  string
}

LinkCandidate is one record a link could reach from where it starts: whether it may be made, whether it already is, and why not.

type Match added in v2.9.0 

type Match struct {
	Kind   string `json:"kind"`
	ID     string `json:"id"`
	Name   string `json:"name"`
	Level  string `json:"level,omitempty"`
	Detail string `json:"detail,omitempty"`
	// Likelihood is how likely it is to be the same thing, from 0 to 1;
	// By says whether the model judged it or the words the two share did.
	Likelihood float64 `json:"likelihood"`
	By         string  `json:"by"`
}

Match is an existing record that says what a text says.

type Measure added in v2.10.0 

type Measure struct {
	Right, Of int
}

Measure is a question's score on its examples: how many it answered as known, of how many.

type MemoryBus 

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

MemoryBus is the in-process Bus.

func NewMemoryBus 

func NewMemoryBus() *MemoryBus

NewMemoryBus returns an empty bus.

func (*MemoryBus) Publish 

func (b *MemoryBus) Publish(ev Event)

func (*MemoryBus) Subscribe 

func (b *MemoryBus) Subscribe(ctx context.Context, kind, id string) *Subscription

type OpenCheck added in v2.6.0 

type OpenCheck struct {
	Kind, ManifestID string
	Check
	// Left is the reason it is left for the person, where the agent said
	// so as it went.
	Left string
}

OpenCheck is a check still open on one manifest of a proposal.

type OpenChecksError added in v2.6.0 

type OpenChecksError struct {
	Open []OpenCheck
}

OpenChecksError refuses a proposal whose checks are not all met and not all waived: the agent asks its person for what is missing, or names each check it leaves open and why (docs/adr/0016).

func (*OpenChecksError) Error added in v2.6.0 

func (e *OpenChecksError) Error() string

type OpenReason added in v2.10.0 

type OpenReason struct {
	Check  string `json:"check"`
	Reason string `json:"reason"`
}

OpenReason is a check left open, with the reason a person reads.

type Option 

type Option func(*Engine)

Option configures an Engine beyond its two required stores.

func WithAccess added in v2.2.0 

func WithAccess(s store.AccessStore, d Directory) Option

WithAccess keeps the access list in s and enrols people by d.

func WithAuthorizer added in v2.2.0 

func WithAuthorizer(z identity.Authorizer) Option

WithAuthorizer makes the engine ask z at every write, with the change the write makes. The HTTP layer has asked z already, without the content; this is where a policy that decides by content decides.

func WithBundles 

func WithBundles(b store.BundleStore) Option

WithBundles attaches where handoff bundles are kept. Without it, a handoff is refused.

func WithBus 

func WithBus(b Bus) Option

WithBus sets the event bus; the in-process one when none is given.

func WithCRDT 

func WithCRDT(c crdt.Engine) Option

WithCRDT, WithDocStore and WithFanout give the engine what shared drafts need (docs/adr/0007, 0008). All three, or shared drafts are off.

func WithCodec 

func WithCodec(c codec.Codec) Option

WithCodec sets the manifest syntax. Every store carries text in this codec; the engine never parses a syntax itself.

func WithDecider added in v2.9.0 

func WithDecider(d decide.Decider) Option

WithDecider sets the decision model the engine asks. Without one, the engine answers as it always has.

func WithDocCache added in v2.1.0 

func WithDocCache(n int) Option

WithDocCache bounds how many shared documents a replica keeps in memory. A dropped document costs a load from the store when next used, never an edit: the store holds every change.

func WithDocStore 

func WithDocStore(d store.DocStore) Option

func WithFanout 

func WithFanout(f fanout.Bus) Option

func WithLayout added in v2.7.0 

func WithLayout(l layout.Layout) Option

WithLayout sets how the workspace graph is placed for drawing. Without one, Graph answers ErrNoLayout.

func WithSemanticExporters added in v2.10.0 

func WithSemanticExporters(xs ...semantic.Exporter) Option

WithSemanticExporters sets the syntaxes the KPIs can be exported in as a semantic layer (TAXONOMY.md D57). Without one, an export answers semantic.ErrNoFormat.

func WithState 

func WithState(s store.StateStore) Option

WithState attaches the apply gate (store.StateStore) the manifest store offers. Without it, the state endpoints answer ErrNoState.

type Order added in v2.7.0 

type Order struct {
	Stages []StageState `json:"stages"`
	// Next is the key of the stage to write now; empty once every stage a
	// plan needs has a record.
	Next string `json:"next,omitempty"`
	// Registers are the root kinds, each with its count.
	Registers []KindInfo `json:"registers"`
}

Order is the order of work as a workspace stands: each stage, how far it has got, and which to write next.

type PlanItem added in v2.7.0 

type PlanItem struct {
	Kind  string `json:"kind"`
	Level string `json:"level,omitempty"`
	// For is what it is needed for, as Kind or Kind (level), and Link how
	// the two are joined: Holder at Path names the other.
	For  string `json:"for"`
	Link string `json:"link"`
	// Check is the check that says whether the link is made.
	Check string `json:"check,omitempty"`
	// Ask is what to ask the person; IfNone what to do when nothing they
	// have fits.
	Ask    string `json:"ask,omitempty"`
	IfNone string `json:"ifNone,omitempty"`
	// Existing is the organisation's records of that kind (and level) to
	// offer before defining another.
	Existing []Candidate `json:"existing,omitempty"`
	// When is "before" for what the new thing names, which must exist
	// first, and "after" for what will name it, written once it exists.
	When string `json:"when"`
	// Missing is true for a before item no record of which exists yet: it
	// is defined first, or the new thing cannot name it (TAXONOMY.md D31).
	Missing bool `json:"missing,omitempty"`
}

PlanItem is one manifest the work needs besides the one being defined, in the order to settle them.

type PortLayout added in v2.10.0 

type PortLayout struct {
	Structure structure.Result
	Problems  []string
	Drafts    []Draft
	Registers []RegisterResult
	Records   []RecordFill
}

PortLayout is a port's pieces laid out: the structure, or the problems that kept it from being drafted; the records drafted; the registers written; and what each record still needs.

type PortRecord added in v2.10.0 

type PortRecord struct {
	Record string         `json:"record" jsonschema:"the record, as Kind/id"`
	Set    map[string]any `json:"set,omitempty" jsonschema:"every field the document gives, by JSON pointer"`
	Unset  []string       `json:"unset,omitempty" jsonschema:"fields to clear, by JSON pointer"`
	Open   []OpenReason   `json:"open,omitempty" jsonschema:"each check the document does not answer, with the reason your person will read"`
}

PortRecord is one record of a port written in one go: the fields the document gives, those to clear, and the checks it does not answer with their reasons.

type PortRecordResult added in v2.10.0 

type PortRecordResult struct {
	Record  string    `json:"record"`
	Refused []Problem `json:"refused,omitempty"`
	Left    []string  `json:"left,omitempty"`
	NotLeft []string  `json:"notLeft,omitempty"`
	Error   string    `json:"error,omitempty"`
	// Err is the error behind Error, for an adapter to word.
	Err error `json:"-"`
}

PortRecordResult is what writing one record of a port kept and left.

type Problem 

type Problem struct {
	Path    string `json:"path"`
	Message string `json:"message"`
	// Keyword is the JSON Schema keyword that failed, for a schema
	// problem: what tells a draft not finished from one built wrong.
	Keyword string `json:"-"`
}

Problem is one validation failure. Path is a JSON pointer into the manifest.

type ProgrammeCheck 

type ProgrammeCheck struct {
	ID      string `json:"id"`
	Section string `json:"section"`
	State   string `json:"state"`
	Message string `json:"message"`
}

ProgrammeCheck is one advisory line about a programme, and the step of the walk a reader would go to about it.

type ProjectCheckFix 

type ProjectCheckFix struct {
	Phase   string `json:"phase"`
	Section string `json:"section"`
}

ProjectCheckFix names where in the definition journey a check's problem is fixed. It usually matches the check's own Phase/Section, except for a handful of checks (for example the operational owner binding, edited in the People section of Initiation even though the check itself belongs to the Landing phase) where the editable field lives elsewhere.

type ProjectCheckItem 

type ProjectCheckItem struct {
	ID      string          `json:"id"`
	Section string          `json:"section"`
	Phase   string          `json:"phase"`
	State   string          `json:"state"`
	Message string          `json:"message"`
	Fix     ProjectCheckFix `json:"fix"`
}

ProjectCheckItem is one row of GET /manifests/Project/{id}/checks. State block stops submission (draft to in review); warn never does.

type ProjectChecks 

type ProjectChecks struct {
	DerivedEnd string             `json:"derivedEnd,omitempty"`
	Blocking   int                `json:"blocking"`
	Items      []ProjectCheckItem `json:"items"`
}

ProjectChecks is the full result: the derived end month (empty when the timeline cannot be computed), how many items block submission, and every check.

type ProjectState 

type ProjectState struct {
	State   string              `json:"state"`
	History []ProjectStateEntry `json:"history"`
}

ProjectState is the result of GET and POST .../state: the current state (a project with no history is implicitly draft) and its full history, oldest first.

type ProjectStateEntry 

type ProjectStateEntry struct {
	State    string    `json:"state"`
	Actor    string    `json:"actor"`
	Reason   string    `json:"reason,omitempty"`
	On       time.Time `json:"on"`
	Snapshot int       `json:"snapshot,omitempty"`
	Bundle   string    `json:"bundle,omitempty"`
}

ProjectStateEntry is one row of a project's state history.

type ProposalPart added in v2.6.0 

type ProposalPart struct {
	Proposal store.Proposal
	Changes  []Change
	Checks   []Check
}

ProposalPart is one manifest of a proposal as its person reviews it: what it would change against the manifest's latest version, field by field, and the checks on what it proposes.

type ProposalView added in v2.6.0 

type ProposalView struct {
	Proposal store.Proposal
	Parts    []ProposalPart
}

ProposalView is a proposal and every part of it, in the order they would be saved: one part, or one per manifest of its set.

type Purpose 

type Purpose struct {
	// The organisation it is the purpose of, by name (D37).
	Organisation string `json:"organisation,omitempty" yaml:"organisation"`
	Vision       string `json:"vision,omitempty" yaml:"vision"`
	Mission      string `json:"mission,omitempty" yaml:"mission"`
	Source       string `json:"source,omitempty" yaml:"source"`
	Logo string `json:"logo,omitempty" yaml:"logo"`
}

Purpose is the vault's vision and mission, stated once above every goal.

type RecordFill added in v2.10.0 

type RecordFill struct {
	Record string     `json:"record"`
	Name   string     `json:"name,omitempty"`
	Fill   []FillItem `json:"fill"`
}

RecordFill is everything one record of a port still needs.

type Ref 

type Ref struct {
	Kind string `json:"kind"`
	ID   string `json:"id"`
	Path string `json:"path,omitempty"`
}

Ref is one reference between manifests. Used both as a filter (only Kind and ID are read) and as an outgoing reference (Path populated too).

type Refs 

type Refs struct {
	Outgoing []Ref     `json:"outgoing"`
	Incoming []Summary `json:"incoming"`
	// Uses is every incoming reference with where it sits in the manifest
	// that makes it, and what that place means for the target: a
	// governance body or a role confirms a success criterion, receives an
	// escalation or decided a mandate (TAXONOMY.md D43).
	Uses []Use `json:"uses,omitempty"`
}

Refs is the result of References: what a manifest points to, and what points back at it.

type RegisterResult added in v2.10.0 

type RegisterResult struct {
	Section   string    `json:"section"`
	Heading   string    `json:"heading,omitempty"`
	Field     string    `json:"field"`
	Rows      int       `json:"rows"`
	Added     int       `json:"added"`
	Refused   []Problem `json:"refused,omitempty"`
	Drafted   int       `json:"drafted,omitempty"`
	NotPorted []string  `json:"notPorted,omitempty"`
	Error     string    `json:"error,omitempty"`
}

RegisterResult is what a port wrote from one of the document's registers.

type Relevance added in v2.9.0 

type Relevance struct {
	// Available is false when no decision model answered: Matches are
	// then by shared words.
	Available bool    `json:"available"`
	Matches   []Match `json:"matches"`
}

Relevance is what in the workspace is relevant to a text.

type Report 

type Report struct {
	Imported []ImportedItem `json:"imported"`
	Problems []FileProblems `json:"problems"`
	Notes    []FileProblems `json:"notes,omitempty"` // one per file that needed a legacy-field rewrite (see rewriteLegacyFields)
}

Report is the result of ImportDir. When any file has problems, nothing in the batch is written: Imported is empty and Problems lists what to fix.

type RollInPolicy added in v2.9.0 

type RollInPolicy struct {
	ChecksMet       bool `json:"checksMet,omitempty" yaml:"checksMet"`
	NothingLeftOpen bool `json:"nothingLeftOpen,omitempty" yaml:"nothingLeftOpen"`
	SecondReviewer  bool `json:"secondReviewer,omitempty" yaml:"secondReviewer"`
}

RollInPolicy is what a change set needs before it is rolled into the record, for people and agents alike.

type Route added in v2.9.0 

type Route struct {
	Key        string  `json:"key"`
	Kind       string  `json:"kind"`
	Level      string  `json:"level,omitempty"`
	Likelihood float64 `json:"likelihood"`
}

Route is a flow that may define what a person typed: a stage of the order of work, and how likely the model found it.

type ScheduleConflict 

type ScheduleConflict struct {
	Edge     DependencyEdge `json:"edge"`
	NeedByOn string         `json:"needByOn"`
	ReadyOn  string         `json:"readyOn"`
}

ScheduleConflict is a dependency that cannot land in time: the work waiting needs it by a phase that ends before the work it waits on finishes.

type ScheduleItem added in v2.9.0 

type ScheduleItem struct {
	ID        string
	Name      string
	Form      string
	Month     string
	NotBefore string
	NotAfter  string
	WaitsOn   []string
	// Pending is a milestone set once something happens; Late is one whose
	// expected month has passed.
	Pending, Late bool
	Critical      bool
	// Unplaced is a milestone that follows something outside the project,
	// so no month can be worked out for it.
	Unplaced bool
}

ScheduleItem is one milestone placed on time (TAXONOMY.md D48): the month it falls in as far as its timing says, its window, what it waits on, and whether it is on the chain that decides the last date.

type SectionText added in v2.10.0 

type SectionText struct {
	ID, Heading, Text string
}

SectionText is a section's text, for an agent to read.

type SetMember added in v2.6.0 

type SetMember struct {
	Kind, ID string
	Text     []byte
}

SetMember is one manifest of a proposal: its kind, id and text.

type Settings 

type Settings struct {
	GoalLevels       []string `json:"goalLevels"`
	ProjectLevelName string   `json:"projectLevelName"`
	Operator         string   `json:"operator"`
	Chromium         string   `json:"chromium"`
	// Examples a vault supplies per field, in its own words (TAXONOMY.md
	// D20). Empty when the vault supplies none.
	Examples map[string][]string `json:"examples,omitempty"`
	// Why everything below exists: the vision and mission (D24).
	Purpose *Purpose `json:"purpose,omitempty"`
	// How the record may change (docs/adr/0024). Nil: as before 0024,
	// every write path open.
	ChangeControl *ChangeControl `json:"changeControl,omitempty"`
}

Settings is the one singleton configuration manifest (kind Settings, id "default"), read from an optional settings.yaml at an import directory's root. Defaults apply when none was imported.

type Shared 

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

Shared is the shared draft of every manifest: one CRDT document each, held in the DocStore, edited by every interface over the sync protocol, and materialised into the working copy so everything that reads working copies keeps working.

It is stateless in the sense the process model needs. The documents it holds are a cache: before every use it folds in whatever chunks other replicas have stored since, so a request served by any replica sees the same document, and a replica that starts empty, or is killed, loses nothing.

func (*Shared) AgentFeed added in v2.6.0 

func (s *Shared) AgentFeed(ctx context.Context, person string) (string, error)

AgentFeed returns the id of the document person's agents announce their steps on, making it on first use. person is as proposals name them; "" for a vault's operator.

func (*Shared) Conflicts 

func (s *Shared) Conflicts(ctx context.Context, kind, id string) ([]crdt.Conflict, error)

Conflicts returns the fields of a manifest's draft that hold concurrent values: the conflict notes, derived on read, so no replica keeps them.

func (*Shared) DocumentFor 

func (s *Shared) DocumentFor(ctx context.Context, kind, id string) (string, error)

DocumentFor returns the id of a manifest's shared draft, creating it from the working copy or the current version on first use. When the working copy has changed outside the draft (a file edited in a vault, an import), the change is folded in first, so the draft never shows less than the working copy does.

func (*Shared) DocumentInSet added in v2.9.0 

func (s *Shared) DocumentInSet(ctx context.Context, set, kind, id string) (string, error)

DocumentInSet returns the id of a change set's shared draft of a manifest, making it on first use from the change set's item, else from the record (which then starts the item). When the item was changed outside the document (an agent's edit, a whole save), the change is folded in first.

func (*Shared) Forget 

func (s *Shared) Forget(docID string)

Forget drops a document from this replica's cache. Nothing is lost: the next use loads it from the store.

func (*Shared) Generate 

func (s *Shared) Generate(ctx context.Context, docID string, peer crdt.SyncState) ([]byte, bool, error)

Generate returns the next sync message for a peer, after folding in what other replicas stored; ok is false when the peer is up to date.

func (*Shared) ManifestFor 

func (s *Shared) ManifestFor(ctx context.Context, docID string) (kind, id string, err error)

ManifestFor names the manifest a document is the draft of. The presence document answers kind "" and id "presence".

func (*Shared) MayWorkInSet added in v2.9.0 

func (s *Shared) MayWorkInSet(ctx context.Context, set string) bool

MayWorkInSet is Engine.MayWorkInSet, for the sync socket.

func (*Shared) NewSyncState 

func (s *Shared) NewSyncState() (crdt.SyncState, error)

NewSyncState returns the sync state for a new peer of a document.

func (*Shared) PresenceDocument 

func (s *Shared) PresenceDocument(ctx context.Context) (string, error)

PresenceDocument returns the id of the document that routes presence on screens not about one manifest.

func (*Shared) Receive 

func (s *Shared) Receive(ctx context.Context, docID string, peer crdt.SyncState, msg []byte, canWrite bool) (changed bool, err error)

Receive applies a sync message from a peer. A principal who may not write may still sync, to read; a message of theirs that would change the document is refused, and the document is left as it was. The presence document takes no changes from anyone.

func (*Shared) Reconcile 

func (s *Shared) Reconcile(ctx context.Context, kind, id string, content map[string]any, message string) error

Reconcile folds a whole document into a manifest's shared draft as one change: what SaveWorking, an import or a changed file means for the draft. It creates the draft when the manifest has none yet.

func (*Shared) RecordPresence added in v2.10.0 

func (s *Shared) RecordPresence(ctx context.Context, kind, id string) (string, error)

RecordPresence returns the id of a manifest's presence document, making it on first use. Like the presence document it holds no content.

func (*Shared) Replica 

func (s *Shared) Replica() string

Replica is this process's id on the fan-out, so it can tell its own hints from others'.

func (*Shared) Stats added in v2.1.0 

func (s *Shared) Stats() SharedStats

Stats returns the current counters.

func (*Shared) Update added in v2.7.0 

func (s *Shared) Update(ctx context.Context, kind, id string, fn func(map[string]any) error, message string) (map[string]any, error)

Update applies fn to a manifest's shared draft under the draft's lock, as one change, and returns what it then holds. store.ErrNoDocument when the manifest has no shared draft yet.

type SharedStats added in v2.1.0 

type SharedStats struct {
	Cached      int   // documents in this replica's cache
	Stored      int64 // changes appended to the store by this replica
	Compactions int64 // snapshots this replica wrote
	StoreErrors int64 // appends that failed
}

SharedStats are counters for monitoring.

type Smart 

type Smart struct {
	Specific   bool `json:"specific"`
	Measurable bool `json:"measurable"`
	Attainable bool `json:"attainable"`
	Relevant   bool `json:"relevant"`
	TimeBound  bool `json:"timeBound"`
}

Smart is how far one goal, objective or outcome meets the SMART criteria (Doran, "There's a S.M.A.R.T. way to write management's goals and objectives", Management Review, 1981; the current reading, Specific, Measurable, Attainable, Relevant, Time-bound). TAXONOMY.md D25, D26.

Each letter is read from what the record already holds, never typed:

  • Specific: a statement, with the numbers left to the measures.
  • Measurable: at least one measure, a key result of its own or an indicator (KPI) aligned to it, with a target.
  • Attainable: the target can reasonably be reached: every measure has today's figure (or an admitted unknown), dated before its target, and the target moves the way the measure says it should. Cartograph cannot judge ambition; it catches a target that cannot be reached as written.
  • Relevant: it sits under the right level (a goal under the vault's vision and mission) and says why it matters.
  • Time-bound: every target has an end date, inside the aim's horizon when it has one (its own, or its parent's).

type Source added in v2.10.0 

type Source struct {
	Title    string             `json:"title"`
	Sections []document.Section `json:"sections"`
}

Source is a brought document: its title and sections.

type Stage added in v2.7.0 

type Stage struct {
	Key   string `json:"key"`
	Kind  string `json:"kind"`
	Level string `json:"level,omitempty"`
	// After are the stages that need a record before this one can be
	// written well: what it names.
	After []string `json:"after,omitempty"`
	// Optional is a stage a workspace may leave empty: not every plan
	// has a programme, an operation, assumptions or a stakeholder map.
	Optional bool `json:"optional,omitempty"`
}

Stage is one step of the order: a kind, or for a Goal one level of it.

func Stages added in v2.7.0 

func Stages() []Stage

Stages returns the order of work.

type StageState added in v2.7.0 

type StageState struct {
	Stage
	// Count is how many records it has.
	Count int `json:"count"`
	// State is done (it has a record), next (the one to write now), ready
	// (what it names is there) or waiting (what it names is not).
	State string `json:"state"`
	// Waiting are the stages it waits on, while it waits.
	Waiting []string `json:"waiting,omitempty"`
}

StageState is one stage of the order as a workspace stands.

type State 

type State struct {
	Name     string
	Included []string
}

State is the apply gate as the API presents it: the state manifest's id and what it includes.

type Subscription 

type Subscription struct {
	C <-chan Event
	// contains filtered or unexported fields
}

Subscription is one listener on the bus.

func (*Subscription) Close 

func (s *Subscription) Close()

Close stops the subscription.

type Summary 

type Summary = store.Summary

Version and Summary are exactly the records store.ManifestStore and store.OperationalStore persist; the engine re-exports them by alias so callers only need one set of names, and so store adapters (which must be usable without importing the engine) stay the source of truth for their own shapes.

type Task added in v2.7.0 

type Task struct {
	Phase   string `json:"phase"`
	Kind    string `json:"kind"`
	ID      string `json:"id"`
	Name    string `json:"name,omitempty"`
	Check   string `json:"check"`
	State   string `json:"state"`
	Message string `json:"message"`
	// Step is the flow step that settles it, and Do what the guidance says
	// to do about it.
	Step string `json:"step,omitempty"`
	Do   string `json:"do,omitempty"`
	// Field is the field that settles it, as a JSON pointer, where one
	// field does.
	Field string `json:"field,omitempty"`
	// By is the kind written to settle it, where that is another kind (a
	// gap settles an outcome's closes-gap): the stage it waits for.
	By string `json:"by,omitempty"`
	// Choices are the records that already exist to settle it with, where
	// a reference or a link settles it: offered before defining another.
	Choices []Candidate `json:"choices,omitempty"`
}

Task is one open check of one manifest, placed in the order of work.

type TaxonomyEntry added in v2.7.0 

type TaxonomyEntry struct {
	Kind    string            `json:"kind"`
	Summary string            `json:"summary"`
	Example string            `json:"example,omitempty"`
	Levels  map[string]string `json:"levels,omitempty"`
	KnownAs []string          `json:"knownAs,omitempty"`
	// Names are the kinds it may name, which come before it in the order
	// of work; a register names only other registers.
	Names []string `json:"names,omitempty"`
	// Register is true for a root kind, added when a field asks for one.
	Register bool `json:"register,omitempty"`
}

TaxonomyEntry is one kind as a document is mapped onto it: what it is, its levels, and what plans often call it instead.

type UnappliedRef 

type UnappliedRef = store.UnappliedRef

UnappliedRef is one manifest that could be applied.

type Understanding added in v2.9.0 

type Understanding struct {
	// Available is false when no decision model answered: there are
	// then no Matches but a name's exact match, and no Routes.
	Available bool    `json:"available"`
	Matches   []Match `json:"matches"`
	Routes    []Route `json:"routes"`
}

Understanding is what Cartograph makes of a text a person typed: the existing record that says the same, and the flows likeliest to define it.

type Use added in v2.9.0 

type Use struct {
	Kind string `json:"kind"`
	ID   string `json:"id"`
	Name string `json:"name"`
	Path string `json:"path"`
	// As is what the place means: confirms, receives or decided; empty
	// for any other.
	As string `json:"as,omitempty"`
}

Use is one place another manifest references this one.

type ValidationError 

type ValidationError struct {
	Problems []Problem
}

ValidationError carries the problems found by schema, reference or kind rule validation. Commit and Propose return it (wrapped) instead of a separate problems slice, since their public signatures return only a value and an error; an API handler recovers it with errors.As and answers 422 with {problems: [...]}.

func (*ValidationError) Error 

func (e *ValidationError) Error() string

type Version 

type Version = store.Version

Version and Summary are exactly the records store.ManifestStore and store.OperationalStore persist; the engine re-exports them by alias so callers only need one set of names, and so store adapters (which must be usable without importing the engine) stay the source of truth for their own shapes.

type Worklist added in v2.7.0 

type Worklist struct {
	// Tasks are every open check, the first being what to do next.
	Tasks []Task `json:"tasks"`
	// Open counts what is left in each phase.
	Open map[string]int `json:"open"`
}

Worklist is a piece of work's open checks, in order.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.