model

package
v0.59.0 Latest Latest
Warning

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

 Go to latest Published: Nov 3, 2026 License: MIT Imports: 2 Imported by: 0

README

model

import "github.com/kitsunium/sdk/framework/model"

Package model is the Product Graph: the one data shape every part of the framework agrees on. The runtime serves it, a static analyzer produces it, a CLI prints it, a Studio draws it, and an AI agent or an editor extension reads it.

A graph is a projection: of the code for what runs, and — since the platform's ADR 0010 — of the design (a product's design/ directory) for what its structure must be. The design, not the graph, is authoritative on structure; the graph shows what the code is and where it differs from the design. Every node says where it was declared (Source) and every edge says how it is known: declared by construction (Edge.Declared), found in a handler body by a static analyzer (Edge.Static), or seen at runtime (Edge.Observed). A diagram that cannot say why an arrow exists is a drawing; this one can.

Identity

Every node has an ID, and the grammar of IDs is written here once — as patterns a schema generator can read (IDPattern, SegmentPattern, NamePattern) and as a parser (ParseID):

todos                              a service
moderation.intake                  a module's service
todos/endpoint/Create              a node of a service
todos/endpoint/GET /todos/{id}     an endpoint named by its route
binary:statusline                  a binary
binary:statusline/role/daemon      one of its process roles
library:textwidth                  a library shared between components
external                           the world outside the product

The runtime, the analyzer, the design files and the generator derive names with the same functions (NodeID, QualifiedService, RoleID), so two sides never disagree about what a declaration is called.

A contract

The JSON shape is a contract: Version is bumped on any change an older reader would misread.

Index

Constants

const AccessAnyUser string = "any-user"

AccessAnyUser is app.AnyUser(): any signed-in user may run it — the operation asks for one.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.AccessAnyUser.

const AccessAnyone string = "anyone"

AccessAnyone is app.Anyone(): whoever reaches the route may run the operation.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.AccessAnyone.

const AuthOptional string = "optional"

AuthOptional endpoints run the auth handler when credentials are present, and serve anonymous callers too.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.AuthOptional.

const AuthRequired string = "required"

AuthRequired endpoints run only for an authenticated caller; the others are answered 401 before the handler runs.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.AuthRequired.

const BinaryScope string = "binary:"

BinaryScope prefixes the ID of a binary and of its roles.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.BinaryScope.

const BlockCase string = "case"

The kinds of CodeBlock.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.BlockCase.

const BlockDefer string = "defer"

The kinds of CodeBlock.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.BlockDefer.

const BlockElse string = "else"

The kinds of CodeBlock.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.BlockElse.

const BlockElseIf string = "else-if"

The kinds of CodeBlock.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.BlockElseIf.

const BlockFunc string = "func"

The kinds of CodeBlock.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.BlockFunc.

const BlockGo string = "go"

The kinds of CodeBlock.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.BlockGo.

const BlockIf string = "if"

The kinds of CodeBlock.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.BlockIf.

const BlockLoop string = "loop"

The kinds of CodeBlock.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.BlockLoop.

const BlockTransaction string = "transaction"

BlockTransaction is the function an app.Transact runs: its steps run in one transaction, and the effects they make leave at its commit.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.BlockTransaction.

const BootComponents string = "components"

Boot steps, in the order kit takes them.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.BootComponents.

const BootConfig string = "config"

Boot steps, in the order kit takes them.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.BootConfig.

const BootData string = "data"

Boot steps, in the order kit takes them.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.BootData.

const BootDeclarations string = "declarations"

Boot steps, in the order kit takes them.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.BootDeclarations.

const BootHandler string = "handler"

Boot steps, in the order kit takes them.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.BootHandler.

const BootMount string = "mount"

Boot steps, in the order kit takes them.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.BootMount.

const BootRoutes string = "routes"

Boot steps, in the order kit takes them.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.BootRoutes.

const BootServing string = "serving"

Boot steps, in the order kit takes them.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.BootServing.

const ClassPersonal string = "personal"

ClassPersonal holds data about an identifiable person: a name, an address, a message a person wrote.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ClassPersonal.

const ClassPublic string = "public"

ClassPublic holds nothing personal and nothing secret: the question was asked.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ClassPublic.

const ClassSecret string = "secret"

ClassSecret holds a credential: a password's hash, a token's digest.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ClassSecret.

const ClassSpecial string = "special"

ClassSpecial holds the special categories of GDPR art. 9(1), or criminal convictions (art. 10).

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ClassSpecial.

const CodeInvalidID errs.Code = 262401

CodeInvalidID identifies an ID the grammar of IDPattern does not match.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.CodeInvalidID.

Code 0.4.1.1

const ComponentDown string = "down"

Component states.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ComponentDown.

const ComponentFailed string = "failed"

Component states.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ComponentFailed.

const ComponentPending string = "pending"

Component states.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ComponentPending.

const ComponentStarting string = "starting"

Component states.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ComponentStarting.

const ComponentStopping string = "stopping"

Component states.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ComponentStopping.

const ComponentUp string = "up"

Component states.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ComponentUp.

const ConnectorData ConnectorKind = "data"

ConnectorData is where it keeps its data: stores, databases.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ConnectorData.

const ConnectorDatabase string = "database"

ConnectorDatabase is brought by a store a database keeps (ADR 0004): app.Database declares the database, an engine module reaches it.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ConnectorDatabase.

const ConnectorHTTP string = "http"

The connectors kit ships.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ConnectorHTTP.

const ConnectorMail string = "mail"

The connectors kit ships.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ConnectorMail.

const ConnectorMessaging ConnectorKind = "messaging"

ConnectorMessaging is what it sends and receives: mail, queues.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ConnectorMessaging.

const ConnectorQueue string = "queue"

The connectors kit ships.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ConnectorQueue.

const ConnectorStore string = "store"

The connectors kit ships.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ConnectorStore.

const ConnectorTransport ConnectorKind = "transport"

ConnectorTransport is how the product is reached: HTTP.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ConnectorTransport.

const ContainerDatabase string = "database"

ContainerDatabase is a database the app declares (app.Database): "container:database:<name>", drawn as a cylinder.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ContainerDatabase.

const ContainerMemory string = "memory"

Container kinds.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ContainerMemory.

const ContainerProcess string = "process"

Container kinds.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ContainerProcess.

const ContainerSPA string = "spa"

Container kinds.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ContainerSPA.

const ContainerVolume string = "volume"

Container kinds.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ContainerVolume.

const ContractPattern string = "[a-z][a-z0-9-]{0,62}/v[1-9][0-9]{0,3}"

ContractPattern is the versioned contract an EdgeContracts edge carries: "render/v1".

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ContractPattern.

const DatabaseClosed string = "closed"

DatabaseClosed: not opened yet, or closed by the stop.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.DatabaseClosed.

const DatabaseFailed string = "failed"

DatabaseFailed: the start could not open it, migrate it or reach it.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.DatabaseFailed.

const DatabaseMemory string = "memory"

DatabaseMemory: the app keeps its data in memory (app.InMemory): nothing is opened, no URL is read.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.DatabaseMemory.

const DatabaseOpen string = "open"

DatabaseOpen: the pool is open, its migrations ran, it answered its check at start.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.DatabaseOpen.

const DatabaseUnset string = "unset"

DatabaseUnset: no URL, in dev. Its stores stay in the data directory and nothing is opened.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.DatabaseUnset.

const EdgeAsks EdgeKind = "asks"

EdgeAsks targets a query: the source asks it. From an endpoint that exposes the query, or from a port bound to it, it is declared.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.EdgeAsks.

const EdgeCalls EdgeKind = "calls"

EdgeCalls targets an endpoint or a port. From a port, it is the port's binding — what the port calls — and it is declared.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.EdgeCalls.

const EdgeContracts EdgeKind = "contracts"

EdgeContracts goes from one process role to another it talks to — through a socket, a pipe, a command line —, and names the versioned contract they share in Edge.Contract. It is the only edge between two roles (D22). Declared.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.EdgeContracts.

const EdgeDelivers EdgeKind = "delivers"

EdgeDelivers goes from a topic to each of its subscriptions, and from a store to each watch it feeds (ADR 0008). Declared.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.EdgeDelivers.

const EdgeDispatches EdgeKind = "dispatches"

EdgeDispatches targets a command: the source dispatches it. From an endpoint that exposes the command, or from a port bound to it, it is declared.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.EdgeDispatches.

const EdgeImports EdgeKind = "imports"

EdgeImports goes from a component to a library it may import (D19). Declared.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.EdgeImports.

const EdgePersists EdgeKind = "persists"

EdgePersists goes from a workflow to the store it lives in. Declared.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.EdgePersists.

const EdgePublishes EdgeKind = "publishes"

EdgePublishes targets a topic.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.EdgePublishes.

const EdgeReads EdgeKind = "reads"

EdgeReads targets a store the source reads from.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.EdgeReads.

const EdgeRenders EdgeKind = "renders"

EdgeRenders goes from a presentation to what it renders. Declared.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.EdgeRenders.

const EdgeRuns EdgeKind = "runs"

EdgeRuns goes from a role to what it runs: a CLI command, a listener, an endpoint's server, a loop. Declared.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.EdgeRuns.

const EdgeSends EdgeKind = "sends"

EdgeSends targets a mailer: the source puts a message in its outbox.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.EdgeSends.

const EdgeTransitions EdgeKind = "transitions"

EdgeTransitions targets a workflow; Label carries the event.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.EdgeTransitions.

const EdgeUses EdgeKind = "uses"

EdgeUses targets a secret whose value or keys the source uses.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.EdgeUses.

const EdgeWakes EdgeKind = "wakes"

EdgeWakes goes from a topic to a declared loop it wakes. Declared.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.EdgeWakes.

const EdgeWrites EdgeKind = "writes"

EdgeWrites targets a store the source writes to.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.EdgeWrites.

const EngineMySQL string = "mysql"

The engines a database runs on (ADR 0004): one module each in kit's repository, the only code that imports its driver.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.EngineMySQL.

const EnginePostgres string = "postgres"

The engines a database runs on (ADR 0004): one module each in kit's repository, the only code that imports its driver.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.EnginePostgres.

const EngineSQLite string = "sqlite"

The engines a database runs on (ADR 0004): one module each in kit's repository, the only code that imports its driver.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.EngineSQLite.

const EventCensus EventType = "census"

EventCensus reports a workflow's population per state.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.EventCensus.

const EventGraph EventType = "graph"

EventGraph reports that the graph structure changed.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.EventGraph.

const EventHello EventType = "hello"

EventHello opens every stream and carries the graph revision.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.EventHello.

const EventLifecycle EventType = "lifecycle"

EventLifecycle reports a lifecycle component moving, or the process changing phase.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.EventLifecycle.

const EventLog EventType = "log"

EventLog reports a log record written by product code, in dev.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.EventLog.

const EventLoop EventType = "loop"

EventLoop reports a loop run.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.EventLoop.

const EventMail EventType = "mail"

EventMail reports a mail entering the outbox or changing status.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.EventMail.

const EventSpan EventType = "span"

EventSpan reports one unit of work that finished on a node.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.EventSpan.

const EventTransition EventType = "transition"

EventTransition reports a workflow instance changing state.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.EventTransition.

const ExportOff string = "off"

ExportOff: the export sends nothing — no endpoint and no sender of the product's, a CLI command, or a process not started.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ExportOff.

const ExportRunning string = "running"

ExportRunning: the export's loop sends.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ExportRunning.

const ExportStopped string = "stopped"

ExportStopped: its loop ended while the process runs — a queue's storage failed —: nothing is sent until the next start.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ExportStopped.

const ExposePrivate string = "private"

ExposePrivate endpoints have no route: the implementation of a port (Service.Implement), reached in process through its port. A graph kit made before its operations were internal by default also marks so an endpoint it kept off the listener.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ExposePrivate.

const ExposePublic string = "public"

ExposePublic endpoints are routed on the product's HTTP listener.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ExposePublic.

const ExternalID string = "external"

ExternalID is the id of the node standing for the outside world.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ExternalID.

const GapPurpose string = "purpose"

The gaps a register lists for a store that keeps personal data.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.GapPurpose.

const GapRetention string = "retention"

The gaps a register lists for a store that keeps personal data.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.GapRetention.

const GapSubject string = "subject"

The gaps a register lists for a store that keeps personal data.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.GapSubject.

const JournalContinue string = "continue"

The operations of the privacy journal.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.JournalContinue.

const JournalDelete string = "delete"

The operations of the privacy journal.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.JournalDelete.

const JournalErase string = "erase"

The operations of the privacy journal.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.JournalErase.

const JournalEraseFields string = "erase-fields"

The operations of the privacy journal.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.JournalEraseFields.

const JournalExport string = "export"

The operations of the privacy journal.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.JournalExport.

const JournalHold string = "hold"

The operations of the privacy journal.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.JournalHold.

const JournalList string = "list"

The operations of the privacy journal.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.JournalList.

const JournalRead string = "read"

The operations of the privacy journal.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.JournalRead.

const JournalRelease string = "release"

The operations of the privacy journal.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.JournalRelease.

const JournalShred string = "shred"

The operations of the privacy journal.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.JournalShred.

const KindAuth NodeKind = "auth"

KindAuth is the app's authentication handler: it turns a request's credentials into a user, in front of every endpoint that asks for one.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.KindAuth.

const KindBinary NodeKind = "binary"

KindBinary is one executable the product ships. It holds process roles; its ID is "binary:<name>".

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.KindBinary.

const KindCLI NodeKind = "cli"

KindCLI is a short command-line command: it parses its arguments, runs once and exits with a typed status.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.KindCLI.

const KindCommand NodeKind = "command"

KindCommand is an operation that changes something: a typed input, a typed result, one handler, the pipeline of its kind. It is dispatched, on its caller's goroutine or through its own queue.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.KindCommand.

const KindEndpoint NodeKind = "endpoint"

KindEndpoint is an HTTP endpoint with typed request and response.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.KindEndpoint.

const KindExternal NodeKind = "external"

KindExternal stands for everything outside the product.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.KindExternal.

const KindFrontend NodeKind = "frontend"

KindFrontend is static assets served by the product.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.KindFrontend.

const KindJob NodeKind = "job"

KindJob is scheduled work: a fixed interval or a cron expression.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.KindJob.

const KindLibrary NodeKind = "library"

KindLibrary is a package shared between components, declared so the components that use it are allowed to import it. Its ID is "library:<name>".

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.KindLibrary.

const KindListener NodeKind = "listener"

KindListener accepts connections that are not HTTP: a private Unix socket, a named pipe. It is an inbound port like an endpoint.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.KindListener.

const KindLoop NodeKind = "loop"

KindLoop is a long-running loop of the daemon: declared (kit owns the wait, the product the work) or hand-written (a goroutine kit supervises).

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.KindLoop.

const KindMailer NodeKind = "mailer"

KindMailer is outbound mail: a durable outbox, and the transport that empties it — SMTP, or the capture of dev and tests.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.KindMailer.

const KindPort NodeKind = "port"

KindPort is an operation a service needs and does not implement: a typed request, a typed response, a name. What it calls — another service's endpoint, the app's binding, its own fallback — is decided when the app starts, and drawn as a declared edge from the port.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.KindPort.

const KindPresentation NodeKind = "presentation"

KindPresentation turns a service's results into what a reader sees: a rendered line, a page, a report.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.KindPresentation.

const KindQuery NodeKind = "query"

KindQuery is an operation that reads and changes nothing: a typed input, a typed result, one handler. It is asked.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.KindQuery.

const KindRole NodeKind = "role"

KindRole is one process role of a binary — "statusline" and "statusline daemon" are two roles of one binary. Its root package is generated wiring; two roles talk through their contract only. Its ID is "binary:<binary>/role/<name>".

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.KindRole.

const KindSecret NodeKind = "secret"

KindSecret is a secret the product declares: provided by the operator, or generated by kit and rotated on a schedule. Its value is never in a graph.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.KindSecret.

const KindService NodeKind = "service"

KindService groups the nodes of one bounded context.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.KindService.

const KindStore NodeKind = "store"

KindStore is a typed, keyed collection of entities.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.KindStore.

const KindSubscription NodeKind = "subscription"

KindSubscription consumes one topic.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.KindSubscription.

const KindTopic NodeKind = "topic"

KindTopic is an asynchronous, at-least-once message channel.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.KindTopic.

const KindWorkflow NodeKind = "workflow"

KindWorkflow is a state machine over the entities of one store.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.KindWorkflow.

const LibraryScope string = "library:"

LibraryScope prefixes the ID of a library.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.LibraryScope.

const LoopConsumer string = "consumer"

Loop kinds.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.LoopConsumer.

const LoopDeclared string = "declared"

LoopDeclared is Service.Loop: kit owns the wait — the wake sources are data, so the diagram draws them — and the product owns the work.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.LoopDeclared.

const LoopGoroutine string = "goroutine"

LoopGoroutine is Service.Go: the product wrote the whole loop; kit starts it, stops it, restarts it after a failure, and reads its select statements to draw what it waits on.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.LoopGoroutine.

const LoopHTTP string = "http"

Loop kinds.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.LoopHTTP.

const LoopJob string = "job"

Loop kinds.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.LoopJob.

const LoopRestarting string = "restarting"

Loop states.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.LoopRestarting.

const LoopRetention string = "retention"

Loop kinds.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.LoopRetention.

const LoopRotation string = "rotation"

Loop kinds.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.LoopRotation.

const LoopRoutine string = "goroutine"

Loop kinds.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.LoopRoutine.

const LoopRunning string = "running"

Loop states.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.LoopRunning.

const LoopScheduler string = "scheduler"

Loop kinds.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.LoopScheduler.

const LoopStopped string = "stopped"

Loop states.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.LoopStopped.

const LoopTimer string = "timer"

Loop kinds.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.LoopTimer.

const LoopWaiting string = "waiting"

Loop states.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.LoopWaiting.

const LoopWake string = "wake"

Loop kinds.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.LoopWake.

const MailDead string = "dead"

Mail statuses.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.MailDead.

const MailExhausted string = "exhausted"

Why a dead mail was given up.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.MailExhausted.

const MailExpired string = "expired"

Why a dead mail was given up.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.MailExpired.

const MailQueued string = "queued"

Mail statuses.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.MailQueued.

const MailRejected string = "rejected"

Why a dead mail was given up.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.MailRejected.

const MailRetrying string = "retrying"

Mail statuses.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.MailRetrying.

const MailSent string = "sent"

Mail statuses.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.MailSent.

const MaxTableLen int = 58

MaxTableLen is the longest table name a store on a database takes, in bytes: the SDK's document store over SQL keeps its index rows in the table named after it with "___ix", within PostgreSQL's 63.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.MaxTableLen.

const MeasureHolds string = "legal-holds"

MeasureHolds: a legal hold stops erasure and deletion.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.MeasureHolds.

const MeasureJournal string = "journal"

MeasureJournal: every export, erasure, deletion and hold is journaled, each entry chained to the previous one by SHA-256.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.MeasureJournal.

const MeasureNotSealed string = "not-sealed"

MeasureNotSealed: the store's classified members are in clear: it is kept in memory, where nothing is at rest, or its members are plain.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.MeasureNotSealed.

const MeasureRedacted string = "redacted"

MeasureRedacted: the Studio, the spans and the logs never show a personal, special or secret value.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.MeasureRedacted.

const MeasureSealed string = "sealed"

MeasureSealed: its classified members are sealed at rest, AES-256-GCM under per-subject data keys a person's erasure destroys (ADR 0006 §4).

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.MeasureSealed.

const MockReplace string = "replace"

MockReplace is the one mode a Mock has: a test's app.Replace, a typed function run in place of an operation's handler — or of what a port calls — while the rest of its pipeline still runs. The Studio sets none (D13): it shows the application, it does not act on it, so the respond, fail and delay modes of the platform's kit have no representation here.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.MockReplace.

const ModeQueued string = "queued"

ModeQueued is sent to the background (app.Queued): Dispatch returns once the command's own queue accepted it, and a consumer handles it, retried and dead-lettered.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ModeQueued.

const ModeSync string = "sync"

ModeSync is handled on its caller's goroutine: Dispatch returns the handler's result.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ModeSync.

const NamePattern string = "[A-Za-z][A-Za-z0-9_.-]{0,62}"

NamePattern is a node's name within its service and kind.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.NamePattern.

const NetworkLocal string = "local"

NetworkLocal is NetworkUnix where there is one, NetworkPipe on Windows: what a product declares when it does not care which.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.NetworkLocal.

const NetworkPipe string = "pipe"

NetworkPipe is a Windows named pipe, its DACL granting its owner only.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.NetworkPipe.

const NetworkUnix string = "unix"

NetworkUnix is a Unix-domain socket, private to its owner.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.NetworkUnix.

const OpAsk string = "ask"

Span operations.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.OpAsk.

const OpAuth string = "auth"

Span operations.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.OpAuth.

const OpCLI string = "cli"

Span operations.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.OpCLI.

const OpCall string = "call"

Span operations.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.OpCall.

const OpConnect string = "connect"

Span operations.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.OpConnect.

const OpDeliver string = "deliver"

Span operations.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.OpDeliver.

const OpDeliverMail string = "deliver-mail"

Span operations.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.OpDeliverMail.

const OpDispatch string = "dispatch"

Span operations.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.OpDispatch.

const OpHandle string = "handle"

Span operations.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.OpHandle.

const OpPublish string = "publish"

Span operations.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.OpPublish.

const OpRead string = "read"

Span operations.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.OpRead.

const OpRequest string = "request"

Span operations.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.OpRequest.

const OpRun string = "run"

Span operations.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.OpRun.

const OpSecret string = "secret"

Span operations.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.OpSecret.

const OpSend string = "send"

Span operations.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.OpSend.

const OpTransaction string = "transaction"

OpTransaction is a unit of work (app.Transact, a command's, a workflow's transition): its attrs say the database it belongs to — "database", and "backend" as a store says it —, its "outcome", the effects it held ("effects"), and "savepoint" for one nested in another.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.OpTransaction.

const OpTransition string = "transition"

Span operations.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.OpTransition.

const OpWrite string = "write"

Span operations.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.OpWrite.

const OutcomeCommit string = "commit"

OutcomeCommit is a transaction that committed: its effects left.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.OutcomeCommit.

const OutcomeRollback string = "rollback"

OutcomeRollback is a transaction whose writes were undone: its effects were dropped.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.OutcomeRollback.

const PhaseDraining string = "draining"

Process phases, in the order a process goes through them.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.PhaseDraining.

const PhaseFailed string = "failed"

Process phases, in the order a process goes through them.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.PhaseFailed.

const PhaseServing string = "serving"

Process phases, in the order a process goes through them.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.PhaseServing.

const PhaseStarting string = "starting"

Process phases, in the order a process goes through them.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.PhaseStarting.

const PhaseStopped string = "stopped"

Process phases, in the order a process goes through them.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.PhaseStopped.

const PortOwnerApp string = "app"

PortOwnerApp is the framework's own listener: the health probes, the Studio in dev, and the product's HTTP when it declares any.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.PortOwnerApp.

const ProfileCLI string = "cli"

ProfileCLI parses its arguments, runs once and exits with a typed status. It starts no listener and no loop outlives it.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ProfileCLI.

const ProfileCPU string = "cpu"

Profile kinds.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ProfileCPU.

const ProfileDaemon string = "daemon"

ProfileDaemon runs until it is stopped, or until it has been idle for its declared time, and serves no HTTP: it answers on its listeners — a private socket, a pipe — and runs its loops.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ProfileDaemon.

const ProfileHeap string = "heap"

Profile kinds.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ProfileHeap.

const ProfileServer string = "server"

ProfileServer serves HTTP until it is stopped: the platform's kit product, and the only profile that opens a TCP listener.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ProfileServer.

const ProvenanceApp string = "app"

ProvenanceApp loops are written by the framework for a declaration: a workflow's sweep, a declared loop's wake cycle.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ProvenanceApp.

const ProvenanceLibrary string = "library"

ProvenanceLibrary loops are written by a library: net/http's accept loop, the SDK scheduler, the SDK queue consumer.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ProvenanceLibrary.

const ProvenanceProduct string = "product"

ProvenanceProduct loops are written by hand in the product: Service.Go.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ProvenanceProduct.

const RetentionDryRun string = "dry-run"

RetentionDryRun journals what the retention would do and changes nothing: how a new retention is deployed over old data.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.RetentionDryRun.

const RetentionOff string = "off"

RetentionOff runs no retention, warned of at every start outside dev.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.RetentionOff.

const RetentionOn string = "on"

RetentionOn erases and deletes what is due: the default.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.RetentionOn.

const RoleInbound string = "inbound"

The roles of a connector, against the process boundary.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.RoleInbound.

const RoleOutbound string = "outbound"

The roles of a connector, against the process boundary.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.RoleOutbound.

const RoleStorage string = "storage"

The roles of a connector, against the process boundary.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.RoleStorage.

const RoutePattern string = "[A-Z]+ /[^\\s]*"

RoutePattern is the name of an endpoint declared without one: its route, "GET /tasks/{id}".

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.RoutePattern.

const SealedPlaceholder string = "[sealed]"

SealedPlaceholder is what the Studio receives in place of a value kit keeps sealed at rest — a record's member in the data browser, a former value —: never the value, nor its box (ADR 0006 §9). A value it opens and may not show is "[redacted]".

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.SealedPlaceholder.

const SecretFromEnv string = "env"

SecretFromEnv is the environment: the variable, or the file its _FILE form names.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.SecretFromEnv.

const SecretFromFile string = "file"

SecretFromFile is the framework's encrypted file store: <PRODUCT>_SECRETS=file:<dir>, or the data directory's .secrets in dev.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.SecretFromFile.

const SecretFromMemory string = "memory"

SecretFromMemory is a store in the process's memory: a test, or <PRODUCT>_SECRETS=memory. A generated secret is made again at every start.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.SecretFromMemory.

const SecretFromStore string = "store"

SecretFromStore is a store the product's code gave kit.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.SecretFromStore.

const SecretGenerated string = "generated"

SecretGenerated is made by kit and rotated on a schedule: a signing or sealing key.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.SecretGenerated.

const SecretProvided string = "provided"

SecretProvided is given by the operator: an SMTP URL, an API token.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.SecretProvided.

const SegmentPattern string = "[a-z][a-z0-9-]{0,62}"

SegmentPattern is a service, module, binary, role or library name.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.SegmentPattern.

const SelectDefault string = "default"

Select case kinds.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.SelectDefault.

const SelectDone string = "done"

Select case kinds.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.SelectDone.

const SelectReceive string = "receive"

Select case kinds.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.SelectReceive.

const SelectSend string = "send"

Select case kinds.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.SelectSend.

const SelectTimer string = "timer"

Select case kinds.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.SelectTimer.

const ServesHTTP string = "http"

What a port serves.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ServesHTTP.

const ServesHealth string = "health"

What a port serves.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ServesHealth.

const ServesStudio string = "studio"

What a port serves.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ServesStudio.

const SettingAppDev string = "appdev"

Where a setting's value comes from.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.SettingAppDev.

const SettingDefault string = "default"

Where a setting's value comes from.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.SettingDefault.

const SettingEnv string = "env"

Where a setting's value comes from.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.SettingEnv.

const SettingFile string = "file"

Where a setting's value comes from.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.SettingFile.

const SettingOption string = "option"

Where a setting's value comes from.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.SettingOption.

const SettingStore string = "store"

Where a setting's value comes from.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.SettingStore.

const StatusError string = "error"

Span statuses.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.StatusError.

const StatusOK string = "ok"

Span statuses.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.StatusOK.

const TransportCapture string = "capture"

TransportCapture keeps every message for the Studio's mailbox and delivers nothing: the transport of dev and tests.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.TransportCapture.

const TransportSMTP string = "smtp"

TransportSMTP delivers to an SMTP relay.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.TransportSMTP.

const TriggerCreate string = "create"

TriggerCreate is the entry of a new instance into the initial state.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.TriggerCreate.

const TriggerEvent string = "event"

TriggerEvent is a transition fired by code, naming an event.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.TriggerEvent.

const TriggerGuard string = "guard"

TriggerGuard is a transition fired when a condition on the entity holds, checked each time the entity is written.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.TriggerGuard.

const TriggerTimer string = "timer"

TriggerTimer is a transition fired after a duration in a state, or at an instant the entity carries.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.TriggerTimer.

const VarAddr string = "ADDR"

The settings the framework reads, by the variable that sets each. The framework's own are named under the product's prefix — its name upper-cased, every other character an underscore —, so a constant holds the name after it: VarDataDir is TODO_DATA_DIR for the product "todo" (ADR 0180 §3). VarStudio, VarStudioRemote, VarAnalyze and VarDevForced are the tool's, set by it and read whole by the Studio subsystem alone.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.VarAddr.

const VarAllowedHosts string = "ALLOWED_HOSTS"

The settings the framework reads, by the variable that sets each. The framework's own are named under the product's prefix — its name upper-cased, every other character an underscore —, so a constant holds the name after it: VarDataDir is TODO_DATA_DIR for the product "todo" (ADR 0180 §3). VarStudio, VarStudioRemote, VarAnalyze and VarDevForced are the tool's, set by it and read whole by the Studio subsystem alone.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.VarAllowedHosts.

const VarAnalyze string = "KIT_ANALYZE"

The settings the framework reads, by the variable that sets each. The framework's own are named under the product's prefix — its name upper-cased, every other character an underscore —, so a constant holds the name after it: VarDataDir is TODO_DATA_DIR for the product "todo" (ADR 0180 §3). VarStudio, VarStudioRemote, VarAnalyze and VarDevForced are the tool's, set by it and read whole by the Studio subsystem alone.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.VarAnalyze.

const VarDataDir string = "DATA_DIR"

The settings the framework reads, by the variable that sets each. The framework's own are named under the product's prefix — its name upper-cased, every other character an underscore —, so a constant holds the name after it: VarDataDir is TODO_DATA_DIR for the product "todo" (ADR 0180 §3). VarStudio, VarStudioRemote, VarAnalyze and VarDevForced are the tool's, set by it and read whole by the Studio subsystem alone.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.VarDataDir.

const VarDevForced string = "KIT_DEV_FORCED"

VarDevForced is how kit dev tells the product which of the variables above it set itself for this launch: their origin is kit dev.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.VarDevForced.

const VarEnv string = "ENV"

The settings the framework reads, by the variable that sets each. The framework's own are named under the product's prefix — its name upper-cased, every other character an underscore —, so a constant holds the name after it: VarDataDir is TODO_DATA_DIR for the product "todo" (ADR 0180 §3). VarStudio, VarStudioRemote, VarAnalyze and VarDevForced are the tool's, set by it and read whole by the Studio subsystem alone.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.VarEnv.

const VarLogLevel string = "LOG_LEVEL"

The settings the framework reads, by the variable that sets each. The framework's own are named under the product's prefix — its name upper-cased, every other character an underscore —, so a constant holds the name after it: VarDataDir is TODO_DATA_DIR for the product "todo" (ADR 0180 §3). VarStudio, VarStudioRemote, VarAnalyze and VarDevForced are the tool's, set by it and read whole by the Studio subsystem alone.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.VarLogLevel.

const VarRetention string = "RETENTION"

VarRetention sets what the stores' retention loops do: on, dry-run or off (ADR 0006).

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.VarRetention.

const VarSMTPURL string = "SMTP_URL"

The settings the framework reads, by the variable that sets each. The framework's own are named under the product's prefix — its name upper-cased, every other character an underscore —, so a constant holds the name after it: VarDataDir is TODO_DATA_DIR for the product "todo" (ADR 0180 §3). VarStudio, VarStudioRemote, VarAnalyze and VarDevForced are the tool's, set by it and read whole by the Studio subsystem alone.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.VarSMTPURL.

const VarStudio string = "KIT_STUDIO"

The settings the framework reads, by the variable that sets each. The framework's own are named under the product's prefix — its name upper-cased, every other character an underscore —, so a constant holds the name after it: VarDataDir is TODO_DATA_DIR for the product "todo" (ADR 0180 §3). VarStudio, VarStudioRemote, VarAnalyze and VarDevForced are the tool's, set by it and read whole by the Studio subsystem alone.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.VarStudio.

const VarStudioRemote string = "KIT_STUDIO_REMOTE"

The settings the framework reads, by the variable that sets each. The framework's own are named under the product's prefix — its name upper-cased, every other character an underscore —, so a constant holds the name after it: VarDataDir is TODO_DATA_DIR for the product "todo" (ADR 0180 §3). VarStudio, VarStudioRemote, VarAnalyze and VarDevForced are the tool's, set by it and read whole by the Studio subsystem alone.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.VarStudioRemote.

const VarTrustProxy string = "TRUST_PROXY"

The settings the framework reads, by the variable that sets each. The framework's own are named under the product's prefix — its name upper-cased, every other character an underscore —, so a constant holds the name after it: VarDataDir is TODO_DATA_DIR for the product "todo" (ADR 0180 §3). VarStudio, VarStudioRemote, VarAnalyze and VarDevForced are the tool's, set by it and read whole by the Studio subsystem alone.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.VarTrustProxy.

const Version int = 6

Version is the schema version of every document in this package.

Version 2 adds the auth, mailer and loop kinds, the sends and wakes edges, the code level of every node (CodeInfo), the C4 context and containers (Architecture) and the daemon's own machinery (Runtime).

Version 3 adds the secret kind (SecretInfo), the uses edge, the secret span operation, the rotation loop and the store origin of a setting.

Version 4 is the one bump the decisions of issue #17 share. It adds the port kind (PortInfo) and its binding, a declared edge from the port to what it calls; the endpoint that implements a port (EndpointInfo.Implements), which has no method and no path; and the replace mock mode (MockReplace). ADR 0004 adds the databases: the store's database (StoreInfo.Database), the database container, the database connector and its adapters, Runtime.Databases and Setting.Database. ADR 0008 adds the modules the app mounts (Graph.Modules), the module of a node (Node.Module) and the Go module of a position outside the product's (Source.GoModule); and the watch, a subscription fed by stores: its mark and the stores that feed it (SubscriptionInfo.Mark, SubscriptionInfo.Stores), each drawing a declared delivers edge to it. ADR 0005 adds the command and query kinds (CommandInfo, QueryInfo), the dispatches and asks edges, the endpoint that exposes one (EndpointInfo.Exposes), the read model (StoreInfo.ReadModel), the dispatch, ask and handle span operations and the dispatch and ask controls.

Version 5 is the first the SDK's framework publishes (ADR 0147). It adds what a product is made of beyond its services: the binary (KindBinary) and its process roles (KindRole), the short CLI command (KindCLI), the listener that is not HTTP (KindListener), the library shared between components (KindLibrary) and the presentation (KindPresentation); the edge between two roles of a product, which carries a versioned contract (EdgeContracts, Edge.Contract); and the grammar every ID follows, written once (ID, ParseID). It removes what the Studio no longer does (D13): the respond, fail and delay mock modes, the control event and its payload — a Mock is a test's replacement only.

Version 6 renames the runtime framework (ADR 0180): its packages are framework/app and framework/internal/app, so a source position the document gives in the framework's code names those paths, and the constants of the framework's own provenance, port owner and setting origin are ProvenanceApp, PortOwnerApp and SettingAppDev; since ADR 0180's step 4 their values are "app" and "appdev", the build's and the graph's version of the framework are their field "app", and the variable a framework setting names carries the product's prefix.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.Version.

const ViaBind string = "bind"

ViaBind is the app's app.Bind.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ViaBind.

const ViaFallback string = "fallback"

ViaFallback is the port's own app.Fallback.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ViaFallback.

const ViaImplement string = "implement"

ViaImplement is the one Service.Implement among the mounted services.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ViaImplement.

const ViaReplace string = "replace"

ViaReplace is a test's app.Replace: a function answers in place of whatever the port would call, and nothing is bound.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.ViaReplace.

const WakeChange string = "change"

Wake source kinds of a declared loop, and why a loop of kit's ran.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.WakeChange.

const WakeDeadline string = "deadline"

Wake source kinds of a declared loop, and why a loop of kit's ran.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.WakeDeadline.

const WakeInterval string = "interval"

Wake source kinds of a declared loop, and why a loop of kit's ran.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.WakeInterval.

const WakeManual string = "manual"

Wake source kinds of a declared loop, and why a loop of kit's ran.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.WakeManual.

const WakeStart string = "start"

Wake source kinds of a declared loop, and why a loop of kit's ran.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.WakeStart.

const WakeTopic string = "topic"

Wake source kinds of a declared loop, and why a loop of kit's ran.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.WakeTopic.

Variables

var IDPattern string

IDPattern is the whole grammar as one regular expression, anchored — the one the design files' JSON Schema publishes for an ID. Only an endpoint may be named by its route.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.IDPattern.

var InvalidID *errs.Error

InvalidID is returned by ParseID for a string the ID grammar does not match. Its "part" field names what failed — the kind, the service name, the node name —, never the input.

Initialised with github.com/kitsunium/sdk/framework/model/internal/core.InvalidID.

Code 0.4.1.1 · reason INVALID_ID · public "The node identifier is not valid"

func BinaryID

func BinaryID(binary string) string

BinaryID is the ID of a binary.

func CompareSource

func CompareSource(a Source, b Source) int

CompareSource orders sources by root, file, then line.

func ConnectorCatalog

func ConnectorCatalog() []ConnectorInfo

ConnectorCatalog is every connector kit ships, sorted by ID: what a product may plug into.

func ConnectorsOf

func ConnectorsOf(nodes []Node) []Connector

ConnectorsOf derives the connectors a product uses from its nodes: an endpoint, a frontend or an auth handler means HTTP, a mailer mail, a store stores — and a database when one keeps it —, a topic, a subscription or a queued command queues. Sorted by ID.

func EdgeID

func EdgeID(from string, kind EdgeKind, to string, label string) string

EdgeID builds the ID of an edge. The label is part of the identity: two transitions of one workflow fired from one endpoint are two edges.

func IsEngine

func IsEngine(backend string) bool

IsEngine reports whether backend names an engine a database runs on.

func LibraryID

func LibraryID(library string) string

LibraryID is the ID of a library.

func Merge

func Merge(base *Graph, extra *Graph) *Graph

Merge enriches a graph with what another description of the same product knows. base is authoritative on which nodes exist — a runtime graph describes what the process actually serves —, on the modules it mounts, on what each of its ports calls and on which stores feed each of its watches: the app chose them when it started, where the analysis only reads the same rules over the whole module. extra, typically the static analysis, contributes documentation, handler ranges — an authorization function's too —, transition callers and the edges it found. Nodes only extra knows about are dropped: code that is compiled but not mounted in this app is not part of this product — save a node of a module's service the base mounts, which a package the binary does not link declares: a warning says so.

func Mermaid

func Mermaid(g *Graph) string

Mermaid renders the architecture of a graph as a Mermaid flowchart: one subgraph per service — a module's inside the module's own, ADR 0008 —, one arrow per edge. GitHub renders it in Markdown, which makes a product's README carry its own, always regenerable, diagram.

Each kind has its shape: an endpoint a box (marked "auth" when it asks for a user; an implementation of a port by its name), a store a cylinder, a topic a flag, a subscription a parallelogram (a watch, ADR 0008, marked with the mark it watches — its stores' arrows say where from), a workflow a hexagon, a job a stadium, the auth handler a trapezoid — a gate —, a mailer a subroutine box, a declared loop a circle, a hand-written loop a double circle, a port an inverted trapezoid — a socket, UML's required interface —, a command a parallelogram leaning back — a subscription's leans forward —, marked "queued" when it waits in its queue, and a query a rhombus, a question. An arrow is solid when it exists by construction or was observed, dotted when only the code says so — or when it is a port's binding to its own fallback, the default the app may replace, as the Studio draws it.

func ModulePrefix

func ModulePrefix(name string) string

ModulePrefix is a module's default mount prefix: "/<name>/".

func NodeID

func NodeID(service string, kind NodeKind, name string) string

NodeID builds the ID of a node declared in a service. A service's own ID is its name.

func ParseID

func ParseID(s string) (ID, error)

ParseID reads an ID. It refuses anything IDPattern does not match, with InvalidID; the refusal never quotes the input, which may be anything a caller sent.

func QualifiedService

func QualifiedService(module string, service string) string

QualifiedService is the name a module gives a service it lists: the module's own name for the service named like it, "<module>.<service>" otherwise. The runtime and the analyzer both qualify with it.

func RoleID

func RoleID(binary string, role string) string

RoleID is the ID of one process role of a binary.

func ServiceOf

func ServiceOf(id string) string

ServiceOf returns the service part of a node ID.

func SplitDoc

func SplitDoc(text string) (string, map[string]string)

SplitDoc splits a description into its default text and its translations.

A product documents a building block once, in Go, in its default language; a paragraph that starts with a language tag and a colon — "fr: Le cycle de vie d'un compte…" — is the same description in that language, until the next tag or the end:

// AccountLifecycle is the life of an account…
//
// fr: AccountLifecycle est la vie d'un compte…

It keeps Go's convention (the comment still starts with the name) and go doc prints both. Each text is joined into one line. A description whose only tagged paragraph is "en" uses it as the default.

func TableName

func TableName(service string, node string, suffix string) string

TableName is the table a database keeps a kit table in (ADR 0004): the service's name — qualified, for a module's —, two underscores and the node's name, then suffix, '-' and '.' written '_', lower case — "moderation.intake"'s store "cases" is moderation_intake__cases. A name the rule cannot keep as it is — upper case, longer than MaxTableLen, three underscores in a row, SQLite's own prefix — is cut and ends with a digest of the whole, so it stays one table's. The runtime and the analyzer name tables with it.

func UnderPrefix

func UnderPrefix(prefix string, path string) string

UnderPrefix is a route declared at path, served under a module's mount prefix: "/reports" under "/moderation/" is "/moderation/reports", and under "/" it stays "/reports".

func ValidContract

func ValidContract(s string) bool

ValidContract reports whether s names a versioned contract: "render/v1".

func ValidName

func ValidName(s string) bool

ValidName reports whether s is a legal node name. An endpoint named by its route is legal as an ID but is not a name a declaration may give.

func ValidSegment

func ValidSegment(s string) bool

ValidSegment reports whether s is a legal service, module, binary, role or library name.

type Adapter

Adapter is a module a connector plugs a product in through: an engine, imported by the product's main to reach a database, and the only code of the product that imports its driver.

type Adapter = core.AdapterMessage

Adapter is an alias of github.com/kitsunium/sdk/framework/model/internal/core.AdapterMessage, declared as:

type Adapter struct {
	// ID names it as the graph does: "postgres".
	ID     string `json:"id"`
	// Name is what a reader calls what it reaches: "PostgreSQL".
	Name   string `json:"name"`
	// Import is the package the product's main imports:
	// "github.com/kitsunium/sdk/framework/connectors/postgres".
	Import string `json:"import"`
	// Driver is the Go driver it links: "github.com/jackc/pgx/v5".
	Driver string `json:"driver,omitempty"`
}

type Analysis

Analysis reports the status of static analysis. It says whether the analyzer ran, how long it took, and the error that stopped it.

type Analysis = core.AnalysisResult

Analysis is an alias of github.com/kitsunium/sdk/framework/model/internal/core.AnalysisResult, declared as:

type Analysis struct {
	// Status is "pending", "running", "ok", "failed" or "unavailable".
	Status   string     `json:"status"`
	// Error explains a failed or unavailable analysis.
	Error    string     `json:"error,omitempty"`
	// At is when the analysis finished.
	At       *time.Time `json:"at,omitempty"`
	// Packages is how many packages were analyzed.
	Packages int        `json:"packages,omitempty"`
	// TookMs is how long it took.
	TookMs   float64    `json:"tookMs,omitempty"`
}

type App

App identifies the product and the machine that described it. It names the module, the environment and the build the graph was taken from.

type App = core.AppMessage

App is an alias of github.com/kitsunium/sdk/framework/model/internal/core.AppMessage, declared as:

type App struct {
	// Name is the product name given to app.NewApp.
	Name      string        `json:"name"`
	// Module is the Go module path of the product.
	Module    string        `json:"module,omitempty"`
	// Root is the absolute module root on the machine that produced the
	// graph. Present in dev only: it is what an editor link needs, and what a
	// production graph must not leak.
	Root      string        `json:"root,omitempty"`
	// Env is "dev" or "production".
	Env       string        `json:"env,omitempty"`
	// App is the version of the framework that produced the graph.
	App       string        `json:"app,omitempty"`
	// Go is the Go version the product was built with.
	Go        string        `json:"go,omitempty"`
	// StartedAt is when the process started, for a runtime graph.
	StartedAt *time.Time    `json:"startedAt,omitempty"`
	// Build says what the binary was built from: the product, the framework
	// and the SDK the framework depends on.
	Build     *BuildMessage `json:"build,omitempty"`
}

type Architecture

Architecture is the product at the two outer levels of the C4 model.

Context (level 1) is the product as one box, the people who use it and the systems it depends on. Containers (level 2) is what the product is deployed as: the process, the frontend its browser runs, the volume its data lives on. Components (level 3) are the nodes, grouped by service; code (level 4) is each node's CodeInfo.

kit derives all of it from the declarations — a frontend implies a person with a browser, a mailer an SMTP relay, a data directory a volume, a database its own container — so it is exactly as true as the rest of the graph.

type Architecture = core.ArchitectureMessage

Architecture is an alias of github.com/kitsunium/sdk/framework/model/internal/core.ArchitectureMessage, declared as:

type Architecture struct {
	// People are the humans the product serves.
	People     []PersonMessage    `json:"people"`
	// Systems are the software systems outside the product it talks to, or
	// that talk to it.
	Systems    []SystemMessage    `json:"systems"`
	// Containers are the product's runnable and storage units.
	Containers []ContainerMessage `json:"containers"`
	// Links are the relationships between people, systems and containers.
	Links      []LinkMessage      `json:"links"`
}

type AuthInfo

AuthInfo describes the app's authentication handler. Credentials says what it reads from a request; Endpoints are the ones behind it.

type AuthInfo = core.AuthSpec

AuthInfo is an alias of github.com/kitsunium/sdk/framework/model/internal/core.AuthSpec, declared as:

type AuthInfo struct {
	// Credentials is the type the handler reads: its fields are tagged
	// cookie:"…" or header:"…".
	Credentials *SchemaMessage `json:"credentials,omitempty"`
	// Data is the type of what the handler says about the caller, which
	// endpoints read with app.AuthData.
	Data        *SchemaMessage `json:"data,omitempty"`
	// Endpoints counts the endpoints that ask for authentication.
	Endpoints   int            `json:"endpoints"`
}

type BinaryInfo

BinaryInfo is one executable the product ships: the Node.Binary of a KindBinary node, naming its roles.

type BinaryInfo = core.BinarySpec

BinaryInfo is an alias of github.com/kitsunium/sdk/framework/model/internal/core.BinarySpec, declared as:

type BinaryInfo struct {
	// Package is the Go package of its main.
	Package string   `json:"package,omitempty"`
	// Roles are the IDs of its process roles, in declaration order; the
	// first is the one it runs with no role argument.
	Roles   []string `json:"roles"`
}

type BootStep

BootStep is one step of the start, as it ran. It carries when it began, how long it took and, when it failed, its error.

type BootStep = core.BootStepMessage

BootStep is an alias of github.com/kitsunium/sdk/framework/model/internal/core.BootStepMessage, declared as:

type BootStep struct {
	// Name is one of the Boot constants.
	Name   string    `json:"name"`
	// Count is how many it went through: settings, warnings, services,
	// routes, components.
	Count  int       `json:"count,omitempty"`
	// Value is what it used: the data directory, in dev.
	Value  string    `json:"value,omitempty"`
	// Begun is when it began.
	Begun  time.Time `json:"begun"`
	// TookMs is how long it took.
	TookMs float64   `json:"tookMs"`
	// Error is the public message of a failure.
	Error  string    `json:"error,omitempty"`
}

type Build

Build is what a binary was built from, at its three levels. Its three levels are the Go toolchain, the main module and the modules it depends on.

type Build = core.BuildMessage

Build is an alias of github.com/kitsunium/sdk/framework/model/internal/core.BuildMessage, declared as:

type Build struct {
	// Product is the product's own module.
	Product ModuleVersionMessage `json:"product"`
	// App is the framework: since ADR 0162 the SDK module,
	// github.com/kitsunium/sdk, which holds it.
	App     ModuleVersionMessage `json:"app"`
	// SDK is the SDK the framework is built on — the same module as App
	// since ADR 0162, so the two say the same version.
	SDK     ModuleVersionMessage `json:"sdk"`
}

type CLIInfo

CLIInfo is a short command-line command: the Node.CLI of a KindCLI node, the words that run it.

type CLIInfo = core.CLISpec

CLIInfo is an alias of github.com/kitsunium/sdk/framework/model/internal/core.CLISpec, declared as:

type CLIInfo struct {
	// Path is the command's words after the binary's name: ["status"],
	// ["daemon", "stop"].
	Path []string `json:"path"`
	// Role is the ID of the role that runs it.
	Role string   `json:"role,omitempty"`
}

type Census

Census is a workflow's population per state. It counts the instances in each state when the census was taken.

type Census = core.CensusMessage

Census is an alias of github.com/kitsunium/sdk/framework/model/internal/core.CensusMessage, declared as:

type Census struct {
	// Workflow is the workflow node ID.
	Workflow string         `json:"workflow"`
	// Counts maps each state to its number of instances.
	Counts   map[string]int `json:"counts"`
}

type CodeBlock

CodeBlock is a block of a function that decides whether, or how many times, the steps under it run.

type CodeBlock = core.CodeBlockMessage

CodeBlock is an alias of github.com/kitsunium/sdk/framework/model/internal/core.CodeBlockMessage, declared as:

type CodeBlock struct {
	// Kind is one of the Block constants.
	Kind   string `json:"kind"`
	// Label is the condition or the clause, as written: "err != nil",
	// `case "done"`, "range ids"; bounded.
	Label  string `json:"label,omitempty"`
	// Line is the 1-based line where the block starts.
	Line   int    `json:"line"`
	// Group is the line of the statement the block is a branch of: an
	// if/else chain, a switch, a select. Blocks with one group are its
	// alternatives.
	Group  int    `json:"group,omitempty"`
	// Parent is the enclosing block: its index in Blocks, plus one; 0 for
	// the function's body.
	Parent int    `json:"parent,omitempty"`
}

type CodeEffect

CodeEffect is one call on a building block, inside a function. It names the node it reaches and the edge kind that call draws.

type CodeEffect = core.CodeEffectMessage

CodeEffect is an alias of github.com/kitsunium/sdk/framework/model/internal/core.CodeEffectMessage, declared as:

type CodeEffect struct {
	// Kind is the edge the call makes: reads, writes, publishes…
	Kind   EdgeKind `json:"kind"`
	// Target is the node the call reaches.
	Target string   `json:"target"`
	// Label refines Kind like an edge's label: the event of a transition.
	Label  string   `json:"label,omitempty"`
	// Op is the method called: "Get", "Insert", "Fire", "Send".
	Op     string   `json:"op"`
	// Line is the 1-based line of the call, in the function's file.
	Line   int      `json:"line"`
}

type CodeFunc

CodeFunc is one function of the module a node's code reaches. Its steps are listed in the order they run, under the blocks that guard them.

type CodeFunc = core.CodeFuncMessage

CodeFunc is an alias of github.com/kitsunium/sdk/framework/model/internal/core.CodeFuncMessage, declared as:

type CodeFunc struct {
	// Func is the qualified name: "github.com/kitsunium/todo/tasks.Create".
	Func    string              `json:"func"`
	// Name is the short name a developer reads: "Create", "(*Store).visible".
	Name    string              `json:"name"`
	// Source is the function's range.
	Source  *SourceMessage      `json:"source,omitempty"`
	// Calls are the qualified names of the module functions it calls, in
	// source order, deduplicated.
	Calls   []string            `json:"calls,omitempty"`
	// Effects are its calls on building blocks, in source order.
	Effects []CodeEffectMessage `json:"effects,omitempty"`
	// Steps are what it does, in the order it does it: its calls to module
	// functions, on building blocks and into the SDK, arguments before the
	// call they are passed to. A sequence diagram is drawn from them.
	Steps   []CodeStepMessage   `json:"steps,omitempty"`
	// Blocks are its blocks that decide whether, or how many times, the
	// steps under them run: an if's branches, a switch's cases, a loop.
	Blocks  []CodeBlockMessage  `json:"blocks,omitempty"`
}

type CodeInfo

CodeInfo is the code a node runs, as the static analysis read it: the fourth and innermost level of the C4 model. The entry is the function the node runs — an endpoint's handler, a subscription's, a loop's — and Funcs are the functions of the module it reaches, each with what it calls and what it does to other nodes.

type CodeInfo = core.CodeResult

CodeInfo is an alias of github.com/kitsunium/sdk/framework/model/internal/core.CodeResult, declared as:

type CodeInfo struct {
	// Entry is the qualified name of the function the node runs first.
	Entry     string            `json:"entry,omitempty"`
	// Funcs are the module's functions reachable from the entry, entry
	// first, then in the order the walk met them.
	Funcs     []CodeFuncMessage `json:"funcs,omitempty"`
	// Uses are the SDK functions the code calls: the mechanics it composes
	// rather than implements.
	Uses      []CodeUseMessage  `json:"uses,omitempty"`
	// Truncated is set when the walk stopped at its depth or size bound.
	Truncated bool              `json:"truncated,omitempty"`
}

type CodeStep

CodeStep is one thing a function does: a call to another function of the module, a call on a building block, or a call into the SDK — under the innermost block that guards it.

type CodeStep = core.CodeStepMessage

CodeStep is an alias of github.com/kitsunium/sdk/framework/model/internal/core.CodeStepMessage, declared as:

type CodeStep struct {
	// Line is the 1-based line of the call, in the function's file.
	Line   int    `json:"line"`
	// Call is the qualified name of the module function it calls.
	Call   string `json:"call,omitempty"`
	// Effect is its call on a building block: the index in Effects, plus one.
	Effect int    `json:"effect,omitempty"`
	// Use is the SDK function it calls, from the SDK's version directory:
	// "crypto/password.Hash".
	Use    string `json:"use,omitempty"`
	// Block is the innermost block guarding it: the index in Blocks, plus
	// one; 0 for the function's body.
	Block  int    `json:"block,omitempty"`
}

type CodeUse

CodeUse is one SDK function a node's code calls. Sites are where the node's code calls it, so a reader sees what it leans on.

type CodeUse = core.CodeUseMessage

CodeUse is an alias of github.com/kitsunium/sdk/framework/model/internal/core.CodeUseMessage, declared as:

type CodeUse struct {
	// Package is the SDK package: "github.com/kitsunium/sdk/pkg/v1/crypto/password".
	Package string          `json:"package"`
	// Func is the function or method: "Hash", "(*Composer).Compose".
	Func    string          `json:"func"`
	// Sites are the call sites, sorted.
	Sites   []SourceMessage `json:"sites,omitempty"`
}

type CommandInfo

CommandInfo describes a command: an operation that changes something. It carries its input and result schemas, its handler, its queue and who may dispatch it.

type CommandInfo = core.CommandSpec

CommandInfo is an alias of github.com/kitsunium/sdk/framework/model/internal/core.CommandSpec, declared as:

type CommandInfo struct {
	// Input is the type it is dispatched with.
	Input         *SchemaMessage      `json:"input,omitempty"`
	// Result is the type it answers; Empty for a queued command.
	Result        *SchemaMessage      `json:"result,omitempty"`
	// Mode is [ModeSync] or [ModeQueued].
	Mode          string              `json:"mode"`
	// Auth is [AuthRequired] — implied by a permission —, [AuthOptional],
	// or empty when the command ignores authentication.
	Auth          string              `json:"auth,omitempty"`
	// Pipeline lists the mechanics a dispatch goes through before the
	// handler, in the order they run.
	Pipeline      []MechanicMessage   `json:"pipeline,omitempty"`
	// Permissions are the permissions a caller needs (Allow).
	Permissions   []PermissionMessage `json:"permissions,omitempty"`
	// Authorize locates the function of its Authorize: a rule that needs
	// the data.
	Authorize     *SourceMessage      `json:"authorize,omitempty"`
	// Key is set when the command names the entity it is about (Key): two
	// runs with one key never overlap.
	Key           bool                `json:"key,omitempty"`
	// MaxDeliveries is how many attempts a queued command gets before it is
	// dead-lettered.
	MaxDeliveries int                 `json:"maxDeliveries,omitempty"`
	// Parallelism is how many dispatches of a queued command are handled at
	// once.
	Parallelism   int                 `json:"parallelism,omitempty"`
	// Queue is "memory", "file" or "sql": where a queued command waits — "sql"
	// on the database that keeps its service.
	Queue         string              `json:"queue,omitempty"`
	// DeadLetters is how many dispatches of a queued command were
	// abandoned, on a runtime graph.
	DeadLetters   *int                `json:"deadLetters,omitempty"`
}

type Component

Component is one lifecycle component: brought up in order, taken down in reverse.

type Component = core.ComponentMessage

Component is an alias of github.com/kitsunium/sdk/framework/model/internal/core.ComponentMessage, declared as:

type Component struct {
	// Name is the lifecycle name: "store:todos/store/todos", "http"…
	Name   string     `json:"name"`
	// Node is the node the component belongs to, when there is one.
	Node   string     `json:"node,omitempty"`
	// State is one of the Component constants.
	State  string     `json:"state"`
	// Begun is when the last start or stop call began.
	Begun  *time.Time `json:"begun,omitempty"`
	// TookMs is how long that call took.
	TookMs float64    `json:"tookMs,omitempty"`
	// Error is the public message of a failure.
	Error  string     `json:"error,omitempty"`
}

type Connector

Connector is something a product plugs into, as the product declares it: how it is reached, what it reaches out to, where it keeps its data. The Studio shows a connector's pages and widgets only when the product has one: a command-line tool has no requests to list, a service without a mailer no mailbox.

A connector says what the code declares, never what an environment supplies. The relay a mailer delivers through, the directory a store writes to, the address kit listens on are facts of the running environment — MailerInfo, StoreInfo, the Architecture and Runtime carry those. So a connector is a pure function of the nodes (ConnectorsOf), and never moves a graph's revision.

type Connector = core.ConnectorMessage

Connector is an alias of github.com/kitsunium/sdk/framework/model/internal/core.ConnectorMessage, declared as:

type Connector struct {
	// ID names the connector: [ConnectorHTTP], [ConnectorMail],
	// [ConnectorStore], [ConnectorQueue], [ConnectorDatabase].
	ID       string        `json:"id"`
	// Kind groups connectors by what they are for; kept for older readers,
	// Roles says more.
	Kind     ConnectorKind `json:"kind"`
	// Roles place it against the process boundary: [RoleInbound] (the
	// product is reached through it), [RoleOutbound] (the product reaches out
	// through it), [RoleStorage] (the product keeps data in it). kit's
	// built-in queues run inside the process: storage only.
	Roles    []string      `json:"roles,omitempty"`
	// Protocol is the wire protocol the code fixes, when it does: "http".
	Protocol string        `json:"protocol,omitempty"`
	// Detail is what the product uses, in kit's words: the stores'
	// backends, the mail transport, the queues' brokers.
	Detail   string        `json:"detail,omitempty"`
	// Settings are the settings the connector owns — the ones its page shows
	// with their value. A setting of a resource it uses (the data directory,
	// kit's port) belongs to that resource: [ContainerMessage].
	Settings []string      `json:"settings,omitempty"`
	// Nodes are the nodes the connector brings to the graph, sorted.
	Nodes    []string      `json:"nodes"`
}

type ConnectorInfo

ConnectorInfo is a connector kit can plug a product into, whether the product uses it or not: what it is, and the building blocks that bring it.

type ConnectorInfo = core.ConnectorSpec

ConnectorInfo is an alias of github.com/kitsunium/sdk/framework/model/internal/core.ConnectorSpec, declared as:

type ConnectorInfo struct {
	// ID is the connector's: [ConnectorHTTP]…
	ID       string           `json:"id"`
	// Kind groups it, as [ConnectorMessage.Kind].
	Kind     ConnectorKind    `json:"kind"`
	// Roles place it against the process boundary.
	Roles    []string         `json:"roles"`
	// Protocol is the wire protocol the code fixes, when it does.
	Protocol string           `json:"protocol,omitempty"`
	// Settings are the settings it owns.
	Settings []string         `json:"settings,omitempty"`
	// Declares are the building blocks whose declaration brings it: a
	// command brings the queue connector only when it is queued.
	Declares []NodeKind       `json:"declares"`
	// Adapters are the modules a product imports to plug it into what it
	// reaches: the engines of the database connector.
	Adapters []AdapterMessage `json:"adapters,omitempty"`
}

type ConnectorKind

ConnectorKind groups connectors by what they are for.

type ConnectorKind = core.ConnectorKind

ConnectorKind is an alias of github.com/kitsunium/sdk/framework/model/internal/core.ConnectorKind, declared as:

type ConnectorKind string

type Container

Container is one runnable or storage unit of the product. Its ID starts with "container:"; Nodes are the nodes that live in it.

type Container = core.ContainerMessage

Container is an alias of github.com/kitsunium/sdk/framework/model/internal/core.ContainerMessage, declared as:

type Container struct {
	// ID is unique in the architecture: "container:process".
	ID         string         `json:"id"`
	// Name is what the diagram prints.
	Name       string         `json:"name"`
	// Kind is one of the Container constants.
	Kind       string         `json:"kind"`
	// Technology names what it is built with: "Go 1.27 · kit · net/http".
	Technology string         `json:"technology,omitempty"`
	// Doc says what it does.
	Doc        string         `json:"doc,omitempty"`
	// Location is where it runs or lives: the listen address, the data
	// directory. Present in dev only.
	Location   string         `json:"location,omitempty"`
	// Nodes are the nodes it hosts: services for the process, stores and
	// subscriptions for the volume, frontends for an SPA.
	Nodes      []string       `json:"nodes,omitempty"`
	// Ports are what the process listens on, and whose each port is.
	Ports      []PortMessage  `json:"ports,omitempty"`
	// Settings are the settings that configure it: TODO_DATA_DIR for the
	// data directory; a database's URL and tuning variables for a database.
	Settings   []string       `json:"settings,omitempty"`
	// Engine is a database's engine: "postgres", "mysql", "sqlite".
	Engine     string         `json:"engine,omitempty"`
	// Source is where the code declares the container, when it does: the
	// app for the process, a frontend for its SPA, app.Database for a
	// database. [GraphMessage.Files] allows it.
	Source     *SourceMessage `json:"source,omitempty"`
}

type Database

Database is one database the app declares (app.Database), as the running process found it. Its URL is never shown: where it was found, the engine, the address and the TLS mode are.

type Database = core.DatabaseMessage

Database is an alias of github.com/kitsunium/sdk/framework/model/internal/core.DatabaseMessage, declared as:

type Database struct {
	// Name is the database's, as the app declares it.
	Name       string                `json:"name"`
	// Engine is the engine it runs on: "postgres", "mysql", "sqlite".
	Engine     string                `json:"engine"`
	// State is one of the Database constants.
	State      string                `json:"state"`
	// Ready says whether it answered its last check; CheckedAt says when.
	Ready      bool                  `json:"ready"`
	CheckedAt  *time.Time            `json:"checkedAt,omitempty"`
	// Problem is the public text of its last failure: a start that failed,
	// a check it did not answer.
	Problem    string                `json:"problem,omitempty"`
	// URLFrom is where its URL was found — a Setting constant: env, store,
	// or default for a SQLite file beside the data —, empty when it is set
	// nowhere.
	URLFrom    string                `json:"urlFrom,omitempty"`
	// TLS is the TLS mode its URL writes: "verify-full"; "none" when it is
	// written off; empty when the URL leaves it to the driver, or when the
	// database is a file.
	TLS        string                `json:"tls,omitempty"`
	// Pool is database/sql's own count of its connections, sampled when the
	// graph was built.
	Pool       *Pool                 `json:"pool,omitempty"`
	// Migrations are its sets of migrations, kit's first, as the start —
	// or the last sample — found them.
	Migrations []MigrationSetMessage `json:"migrations,omitempty"`
}

type DevBuild

DevBuild is one build of `kit dev`: when, how long, and why. It lets the Studio say what changed and how long the reload took.

type DevBuild = core.DevBuildMessage

DevBuild is an alias of github.com/kitsunium/sdk/framework/model/internal/core.DevBuildMessage, declared as:

type DevBuild struct {
	// BuiltAt is when the build finished.
	BuiltAt  *time.Time `json:"builtAt,omitempty"`
	// BuildMs is how long it took.
	BuildMs  float64    `json:"buildMs,omitempty"`
	// Rebuilds counts the builds of this kit dev session, this one
	// included: 1 is the first start.
	Rebuilds int        `json:"rebuilds,omitempty"`
	// Changed are the files whose change triggered this build, relative to
	// the module root, at most 20.
	Changed  []string   `json:"changed,omitempty"`
	// More counts the changed files beyond Changed.
	More     int        `json:"more,omitempty"`
}

type Diagnostic

Diagnostic is a problem found while building the graph. It names the node or the file it is about, and how serious it is.

type Diagnostic = core.DiagnosticMessage

Diagnostic is an alias of github.com/kitsunium/sdk/framework/model/internal/core.DiagnosticMessage, declared as:

type Diagnostic struct {
	// Severity is "error" or "warning". An error refuses to start the app.
	Severity string            `json:"severity"`
	// Message says what is wrong and how to fix it, in English.
	Message  string            `json:"message"`
	// Texts is the message in each language kit speaks, by language: "en",
	// and "fr" when the program imports framework/app/studio. The Studio
	// shows its reader's.
	Texts    map[string]string `json:"texts,omitempty"`
	// Node is the node concerned, when there is one.
	Node     string            `json:"node,omitempty"`
	// Source is where the problem is.
	Source   *SourceMessage    `json:"source,omitempty"`
}

type Edge

Edge is one relation, with the evidence for it. Declared, Static and Observed say whether construction, the code or the runtime knows it.

type Edge = core.EdgeMessage

Edge is an alias of github.com/kitsunium/sdk/framework/model/internal/core.EdgeMessage, declared as:

type Edge struct {
	// ID is "<from>|<kind>|<to>" or "<from>|<kind>|<to>|<label>".
	ID       string          `json:"id"`
	// From is the source node ID.
	From     string          `json:"from"`
	// To is the target node ID.
	To       string          `json:"to"`
	// Kind says how the two relate.
	Kind     EdgeKind        `json:"kind"`
	// Label refines the kind: the event of a transition ("create" for a new
	// instance), or "direct" for a call that bypasses an endpoint.
	Label    string          `json:"label,omitempty"`
	// Contract names the versioned contract of an [EdgeContracts] edge:
	// "<name>/v<major>", "render/v1".
	Contract string          `json:"contract,omitempty"`
	// Declared is set when the edge exists by construction.
	Declared bool            `json:"declared,omitempty"`
	// Static lists the call sites the analyzer found, sorted.
	Static   []SourceMessage `json:"static,omitempty"`
	// Observed is present once the edge was seen at runtime.
	Observed *StatsMessage   `json:"observed,omitempty"`
}

type EdgeKind

EdgeKind says how two nodes relate. It is a wire format — the graph's JSON and the Studio's TypeScript unions carry these names —, so it stays a string.

type EdgeKind = core.EdgeKind

EdgeKind is an alias of github.com/kitsunium/sdk/framework/model/internal/core.EdgeKind, declared as:

type EdgeKind string

type Edit

Edit is one change between two versions of a record, in RFC 6902's words: an add, a remove or a replace at a JSON pointer.

type Edit = core.EditMessage

Edit is an alias of github.com/kitsunium/sdk/framework/model/internal/core.EditMessage, declared as:

type Edit struct {
	Op   string          `json:"op"`
	Path string          `json:"path"`
	From json.RawMessage `json:"from,omitempty" app:"personal"`
	To   json.RawMessage `json:"to,omitempty" app:"personal"`
}

type EndpointInfo

EndpointInfo describes an HTTP endpoint, or the implementation of a port. It carries the method and path, the request and response schemas, and its auth.

type EndpointInfo = core.EndpointSpec

EndpointInfo is an alias of github.com/kitsunium/sdk/framework/model/internal/core.EndpointSpec, declared as:

type EndpointInfo struct {
	// Method is the HTTP method, upper case; empty for an implementation.
	Method     string            `json:"method"`
	// Path is the route pattern, with {wildcards}; empty for an
	// implementation.
	Path       string            `json:"path"`
	// Expose is [ExposePublic] or [ExposePrivate].
	Expose     string            `json:"expose"`
	// Auth is [AuthRequired], [AuthOptional], or empty when the endpoint
	// ignores authentication.
	Auth       string            `json:"auth,omitempty"`
	// Request is the input type.
	Request    *SchemaMessage    `json:"request,omitempty"`
	// Response is the output type.
	Response   *SchemaMessage    `json:"response,omitempty"`
	// Pipeline lists the mechanics a request goes through before the
	// handler, in order.
	Pipeline   []MechanicMessage `json:"pipeline,omitempty"`
	// Implements is the node ID of the port this endpoint implements
	// (Service.Implement): an endpoint with no route, reached through the
	// port.
	Implements string            `json:"implements,omitempty"`
	// Exposes is the node ID of the command this endpoint dispatches, or of
	// the query it asks (Command.Expose, Query.Expose): its authentication
	// is the operation's, and the rest of its pipeline — validation, key,
	// authorization — the operation's own.
	Exposes    string            `json:"exposes,omitempty"`
	// Access is how an exposure says its operation is open on purpose —
	// [AccessAnyone] or [AccessAnyUser] —; empty when the operation says who
	// may run it (a permission, a rule), and on any other endpoint.
	Access     string            `json:"access,omitempty"`
}

type Erasure

Erasure is what app.Erase did, store by store. Stores lists, store by store, what the erasure did there.

type Erasure = core.ErasureMessage

Erasure is an alias of github.com/kitsunium/sdk/framework/model/internal/core.ErasureMessage, declared as:

type Erasure struct {
	// Stores are the stores that kept records about the person.
	Stores []StoreErasureMessage `json:"stores"`
}

type Event

Event is one live event. Exactly one of the payload fields matching Type is set.

type Event = core.Event

Event is an alias of github.com/kitsunium/sdk/framework/model/internal/core.Event, declared as:

type Event struct {
	// Seq increases strictly on one stream; a reader drops what it has seen.
	Seq        uint64              `json:"seq"`
	// Type selects the payload.
	Type       EventType           `json:"type"`
	// Time is when it happened.
	Time       time.Time           `json:"time"`
	// Revision is the graph revision, on hello and graph events.
	Revision   string              `json:"revision,omitempty"`
	// StartedAt is when the process's current run started, on hello: a new
	// value means the process restarted, and what the reader knew of the
	// previous run is stale.
	StartedAt  *time.Time          `json:"startedAt,omitempty"`
	// Phase is the process phase, on hello and lifecycle events.
	Phase      string              `json:"phase,omitempty"`
	Span       *SpanMessage        `json:"span,omitempty"`
	Transition *TransitionEvent    `json:"transition,omitempty"`
	Lifecycle  *ComponentMessage   `json:"lifecycle,omitempty"`
	Loop       *LoopMessage        `json:"loop,omitempty"`
	Census     *CensusMessage      `json:"census,omitempty"`
	Log        *LogRecordMessage   `json:"log,omitempty"`
	Mail       *MailSummaryMessage `json:"mail,omitempty"`
}

type EventType

EventType names the kind of a live event. It is a wire format — the graph's JSON and the Studio's TypeScript unions carry these names —, so it stays a string.

type EventType = core.EventType

EventType is an alias of github.com/kitsunium/sdk/framework/model/internal/core.EventType, declared as:

type EventType string

type Export

Export is the product's OTLP export (app.OTLP), as the running process found it: what each signal's queue holds against its bounds, has sent and has lost. Its endpoint and headers are never shown.

type Export = core.ExportMessage

Export is an alias of github.com/kitsunium/sdk/framework/model/internal/core.ExportMessage, declared as:

type Export struct {
	// State is one of the Export constants.
	State   string                `json:"state"`
	// Problem says why it is not healthy, when it is not: its loop ended, or
	// a queue holds more than 80% of either bound.
	Problem string                `json:"problem,omitempty"`
	// Signals are its two queues, traces then metrics; none while it is off.
	Signals []ExportSignalMessage `json:"signals,omitempty"`
}

type ExportSignal

ExportSignal is one signal's queue of the OTLP export, sampled when the runtime state is read; its counters never move a revision.

type ExportSignal = core.ExportSignalMessage

ExportSignal is an alias of github.com/kitsunium/sdk/framework/model/internal/core.ExportSignalMessage, declared as:

type ExportSignal struct {
	// LastRetryAfterAt is when the collector last imposed a delay; nil when
	// it never did.
	LastRetryAfterAt *time.Time `json:"lastRetryAfterAt,omitempty"`
	// Signal is "traces" or "metrics".
	Signal           string     `json:"signal"`
	// Store is where the queue lies: "memory", "directory" — under the data
	// directory — or "database:<name>".
	Store            string     `json:"store"`
	// PendingBytes is the bytes the queue holds.
	PendingBytes     int64      `json:"pendingBytes"`
	// MaxBytes bounds the bytes it holds.
	MaxBytes         int64      `json:"maxBytes"`
	// LastRetryAfterMs is the last delay the collector imposed, in
	// milliseconds.
	LastRetryAfterMs int64      `json:"lastRetryAfterMs,omitempty"`
	// Pending is the batches the queue holds.
	Pending          int        `json:"pending"`
	// MaxBatches bounds the batches it holds.
	MaxBatches       int        `json:"maxBatches"`
	// Sent counts the batches sent since the process started.
	Sent             uint64     `json:"sent"`
	// Retries counts the attempts made again.
	Retries          uint64     `json:"retries"`
	// Dropped counts the batches lost to a bound.
	Dropped          uint64     `json:"dropped"`
	// Expired counts the batches lost to their age.
	Expired          uint64     `json:"expired"`
	// DeadLettered counts the batches the collector refused for good, which
	// `<product> otlp dead-letters` lists.
	DeadLettered     uint64     `json:"deadLettered"`
	// Durable reports whether the queue outlives the process.
	Durable          bool       `json:"durable"`
}

type ExportedVersions

ExportedVersions are the versions of one exported record.

type ExportedVersions = core.ExportedVersionsMessage

ExportedVersions is an alias of github.com/kitsunium/sdk/framework/model/internal/core.ExportedVersionsMessage, declared as:

type ExportedVersions struct {
	// Record is the record's position in its StoreData's Records.
	Record   int                    `json:"record"`
	// Versions are its versions, newest first — the record as it is now
	// first —, each without its secret members.
	Versions []RecordVersionMessage `json:"versions"`
}

type Field

Field is one member of an object schema. It carries the JSON name, the schema of its value and the classes of its data.

type Field = core.FieldMessage

Field is an alias of github.com/kitsunium/sdk/framework/model/internal/core.FieldMessage, declared as:

type Field struct {
	// Name is the wire name.
	Name      string         `json:"name"`
	// In is where a request field is read from: "body", "path", "query",
	// "header" or "cookie". Empty outside requests.
	In        string         `json:"in,omitempty"`
	// Type is the member's schema.
	Type      *SchemaMessage `json:"type"`
	// Optional is set when the member may be absent.
	Optional  bool           `json:"optional,omitempty"`
	// Rules are the validation rules, as written in the validate tag.
	Rules     string         `json:"rules,omitempty"`
	// Doc is the field's comment, when the analyzer found one.
	Doc       string         `json:"doc,omitempty"`
	// Class is what the field holds, as its app tag says (ADR 0006): one of
	// the Class constants, or empty when the field is unclassified. A
	// subject field is personal unless it is special.
	Class     string         `json:"class,omitempty"`
	// Subject marks the field that says whom a record is about.
	Subject   bool           `json:"subject,omitempty"`
	// Moderated marks content others see and a moderator may act on.
	Moderated bool           `json:"moderated,omitempty"`
	// Sealed is set when kit keeps the field sealed at rest (ADR 0006 §4):
	// a personal, special or secret field, or the subject, not plain, of
	// what kit keeps on disk — a store's entity, a topic's message, a queued
	// command's input. A store in memory seals nothing.
	Sealed    bool           `json:"sealed,omitempty"`
	// Erased marks the time kit stamps when it erases the record.
	Erased    bool           `json:"erased,omitempty"`
	// History is how many former values kit keeps of the field (ADR 0007).
	History   int            `json:"history,omitempty"`
}

type File

File is one file a graph points at: its path, relative to its root — the product's module, or the Go module Source.GoModule names.

type File = core.FileMessage

File is an alias of github.com/kitsunium/sdk/framework/model/internal/core.FileMessage, declared as:

type File struct {
	// GoModule is empty for a file of the product's own module.
	GoModule string `json:"goModule,omitempty"`
	File     string `json:"file"`
}

type FlameNode

FlameNode is one frame of a flame graph. Its children are the frames it called; its value is the samples under it.

type FlameNode = core.FlameNodeMessage

FlameNode is an alias of github.com/kitsunium/sdk/framework/model/internal/core.FlameNodeMessage, declared as:

type FlameNode struct {
	// Name is the function.
	Name     string              `json:"name"`
	// Value is its cumulative cost.
	Value    float64             `json:"value"`
	// Node is the node the frame belongs to, when it is a node's code.
	Node     string              `json:"node,omitempty"`
	// Children are its callees, highest first.
	Children []*FlameNodeMessage `json:"children,omitempty"`
}

type Former

Former is one former value of a field that keeps its history: what it was, until when, and who replaced it.

type Former = core.FormerMessage

Former is an alias of github.com/kitsunium/sdk/framework/model/internal/core.FormerMessage, declared as:

type Former struct {
	// Value is the field's value then, as JSON; absent for a secret field,
	// whose former values are never given.
	Value json.RawMessage `json:"value,omitempty" app:"personal"`
	// Until is when it was replaced, on the app's clock.
	Until time.Time       `json:"until"`
	// By is the user who replaced it — app.UserID —, empty for a write
	// with no user: a job's, a loop's, kit's own.
	By    string          `json:"by,omitempty"`
}

type FrontendInfo

FrontendInfo describes static assets served by the product. It carries the path the assets are served under and where they are read from.

type FrontendInfo = core.FrontendSpec

FrontendInfo is an alias of github.com/kitsunium/sdk/framework/model/internal/core.FrontendSpec, declared as:

type FrontendInfo struct {
	// Prefix is the URL path the assets are served under.
	Prefix string `json:"prefix"`
	// Files is how many files are served.
	Files  int    `json:"files,omitempty"`
}

type FuncCost

FuncCost is what one function cost. It carries the flat and cumulative samples of the function and where it lives.

type FuncCost = core.FuncCostMessage

FuncCost is an alias of github.com/kitsunium/sdk/framework/model/internal/core.FuncCostMessage, declared as:

type FuncCost struct {
	// Func is the qualified function name.
	Func   string         `json:"func"`
	// Source locates it, when it is in the product's module.
	Source *SourceMessage `json:"source,omitempty"`
	// Flat is the cost of the function's own code; Cum includes its callees.
	Flat   float64        `json:"flat"`
	Cum    float64        `json:"cum"`
	// Node is the node it was attributed to, when one.
	Node   string         `json:"node,omitempty"`
}

type GoroutineGroup

GoroutineGroup is goroutines doing the same thing. They share one stack; Count says how many run it.

type GoroutineGroup = core.GoroutineGroup

GoroutineGroup is an alias of github.com/kitsunium/sdk/framework/model/internal/core.GoroutineGroup, declared as:

type GoroutineGroup struct {
	// Node is the node they run for, from their pprof label, when any.
	Node  string   `json:"node,omitempty"`
	// Loop is the loop they are, when kit knows: "http accept", a consumer.
	Loop  string   `json:"loop,omitempty"`
	// State is the runtime's word for what they wait on: "running",
	// "select", "chan receive", "IO wait", "sleep", "semacquire"…
	State string   `json:"state"`
	// Count is how many goroutines are in the group.
	Count int      `json:"count"`
	// Top is the innermost frame that is not the runtime's.
	Top   string   `json:"top"`
	// Stack is the group's stack, innermost first, capped.
	Stack []string `json:"stack,omitempty"`
}

type Goroutines

Goroutines is every goroutine of the process, grouped by what it runs. Each group names the node its stack runs in, when one does.

type Goroutines = core.GoroutinesResult

Goroutines is an alias of github.com/kitsunium/sdk/framework/model/internal/core.GoroutinesResult, declared as:

type Goroutines struct {
	// At is when they were counted.
	At     time.Time        `json:"at"`
	// Total is how many goroutines exist.
	Total  int              `json:"total"`
	// Groups are goroutines sharing a node or loop, a state and a top frame,
	// largest first.
	Groups []GoroutineGroup `json:"groups"`
}

type Graph

Graph is the whole product. It is the JSON document the runtime serves and the analyzer writes; Version names its shape.

type Graph = core.GraphMessage

Graph is an alias of github.com/kitsunium/sdk/framework/model/internal/core.GraphMessage, declared as:

type Graph struct {
	// Version is always [Version] for a document this package produced.
	Version          int                  `json:"version"`
	// Revision changes whenever the structure changes (nodes, edges, sources),
	// never when only observed statistics move. A reader caches layout on it.
	Revision         string               `json:"revision"`
	// App identifies the product.
	App              AppMessage           `json:"app"`
	// Nodes are sorted by ID.
	Nodes            []NodeEntity         `json:"nodes"`
	// Edges are sorted by ID.
	Edges            []EdgeMessage        `json:"edges"`
	// Catalog lists the generic mechanics this kit version offers.
	Catalog          []MechanicMessage    `json:"catalog,omitempty"`
	// Diagnostics are problems found while building the graph.
	Diagnostics      []DiagnosticMessage  `json:"diagnostics,omitempty"`
	// Runtime is present when a running process describes itself.
	Runtime          *RuntimeMessage      `json:"runtime,omitempty"`
	// Analysis reports the static analysis that enriched this graph.
	Analysis         *AnalysisResult      `json:"analysis,omitempty"`
	// Architecture is the product at C4's two outer levels: who uses it and
	// what it depends on, and what it is deployed as.
	Architecture     *ArchitectureMessage `json:"architecture,omitempty"`
	// Connectors are what the product plugs into, derived from its nodes by
	// [GraphMessage.Normalize]: the Studio shows their pages and widgets only.
	Connectors       []ConnectorMessage   `json:"connectors,omitempty"`
	// ConnectorCatalog is every connector this kit version ships, used or
	// not: what the product may plug into, and what brings each.
	ConnectorCatalog []ConnectorSpec      `json:"connectorCatalog,omitempty"`
	// Modules are the modules the app mounts (ADR 0008), sorted by name.
	Modules          []ModuleMessage      `json:"modules,omitempty"`
}

func (Graph) Edge
func (*Graph) Edge(id string) *EdgeMessage

Edge returns the edge with the given ID, or nil.

func (Graph) Files
func (*Graph) Files() []FileMessage

Files returns every file the graph points at, each with its root — the product's module, or another Go module: a module's (ADR 0008), a library's —, sorted and deduplicated. It is the complete list of files a reader of this graph may legitimately ask to see, and the source endpoint serves nothing else.

func (Graph) ModuleOf
func (*Graph) ModuleOf(name string) *ModuleMessage

ModuleOf returns the module named name, or nil.

func (Graph) Node
func (*Graph) Node(id string) *NodeEntity

Node returns the node with the given ID, or nil.

func (Graph) Normalize
func (*Graph) Normalize()

Normalize sorts nodes, edges and call sites into their canonical order, fills each workflow transition's callers from the edges, derives the connectors from the nodes, and recomputes Revision. Two graphs describing the same structure normalize to the same bytes, whatever order they were built in.

type HTTPServer

HTTPServer is the product's HTTP server, and whose loop serves it. Its address is the one it listens on; its loop is the node that runs it.

type HTTPServer = core.HTTPServer

HTTPServer is an alias of github.com/kitsunium/sdk/framework/model/internal/core.HTTPServer, declared as:

type HTTPServer struct {
	// Library is the implementation: "sdk/v1/net/server" — the SDK's engine
	// accepting and draining the connections, net/http speaking the protocol.
	Library    string            `json:"library"`
	// Loop says how it serves: one accept loop, one goroutine per
	// connection, written by the library rather than the product.
	Loop       string            `json:"loop"`
	// Addr is the listening address.
	Addr       string            `json:"addr,omitempty"`
	// Middleware is the chain every request goes through before its route,
	// outermost first.
	Middleware []MechanicMessage `json:"middleware,omitempty"`
	// Timeouts are the server's timeouts, as Go durations: "readHeader",
	// "read", "write", "idle".
	Timeouts   map[string]string `json:"timeouts,omitempty"`
	// Conns counts connections: "active" now, "total" ever accepted,
	// "rejected" by the listener's ceiling. Older graphs carry "new", "idle"
	// and "hijacked" too.
	Conns      map[string]int64  `json:"conns,omitempty"`
	// InFlight is how many requests are being served.
	InFlight   int64             `json:"inFlight"`
	// Served counts the requests served since start.
	Served     int64             `json:"served"`
}

type HeldUntil

HeldUntil is the hold a store declares on each of its records, until an instant the record carries.

type HeldUntil = core.HeldUntilSpec

HeldUntil is an alias of github.com/kitsunium/sdk/framework/model/internal/core.HeldUntilSpec, declared as:

type HeldUntil struct {
	// At locates the function that gives the instant.
	At     *SourceMessage `json:"at,omitempty"`
	// Reason is the legal ground the declaration gives: "commercial code:
	// 10 years".
	Reason string         `json:"reason,omitempty"`
}

type Hold

Hold is one record a legal hold keeps. It carries references only: never the record's key, its subject's identity, or the hold's reason, which kit keeps apart.

type Hold = core.HoldEvent

Hold is an alias of github.com/kitsunium/sdk/framework/model/internal/core.HoldEvent, declared as:

type Hold struct {
	// Store is the store's node ID.
	Store   string    `json:"store"`
	// Record is the record's reference.
	Record  string    `json:"record"`
	// Subject is the reference of the person the record is about, when it
	// has one.
	Subject string    `json:"subject,omitempty"`
	// By is who placed it: a user's ID, "cli" or "studio".
	By      string    `json:"by"`
	// At is when.
	At      time.Time `json:"at"`
}

type ID

ID is a node's identity, parsed: the one grammar of IDPattern. Its String is the ID it was parsed from.

type ID = core.IDValue

ID is an alias of github.com/kitsunium/sdk/framework/model/internal/core.IDValue, declared as:

type ID struct {
	// Module qualifies Service when a module lists it; empty for the
	// product's own services, and for a module's service named like it.
	Module  string
	// Service is the service's own name, unqualified; empty for a binary, a
	// role, a library and [ExternalID].
	Service string
	// Scope is the name of the binary of a binary or a role, or of the
	// library of a library; empty otherwise.
	Scope   string
	// Kind is the node's kind.
	Kind    NodeKind
	// Name is the node's name: the service's for a service, the binary's for
	// a binary.
	Name    string
}

func (ID) QualifiedServiceName
func (*ID) QualifiedServiceName() string

QualifiedServiceName is the service's ID segment: the qualification QualifiedService applies.

func (ID) String
func (*ID) String() string

String renders the ID; ParseID(id.String()) is id for every ID ParseID returned.

type IndexInfo

IndexInfo is one secondary index of a store. Its name is unique in the store; Unique says whether two records may share a key.

type IndexInfo = core.IndexSpec

IndexInfo is an alias of github.com/kitsunium/sdk/framework/model/internal/core.IndexSpec, declared as:

type IndexInfo struct {
	// Name is how code asks for the index: Store.Lookup(ctx, name, key).
	Name   string `json:"name"`
	// Unique is set when two entities may not share a key: a write that
	// would is refused with a conflict.
	Unique bool   `json:"unique,omitempty"`
}

type Instance

Instance is one entity's journey through a workflow. It carries the entity's key, its current state and the steps that brought it there.

type Instance = core.InstanceMessage

Instance is an alias of github.com/kitsunium/sdk/framework/model/internal/core.InstanceMessage, declared as:

type Instance struct {
	// ID is the entity key.
	ID        string      `json:"id"`
	// State is the current state.
	State     string      `json:"state"`
	// EnteredAt is when the instance entered its current state.
	EnteredAt time.Time   `json:"enteredAt"`
	// History lists the transitions, oldest first, capped.
	History   []StepEvent `json:"history,omitempty"`
}

type JobInfo

JobInfo describes a scheduled job. It carries the fixed interval or the cron expression that schedules it.

type JobInfo = core.JobSpec

JobInfo is an alias of github.com/kitsunium/sdk/framework/model/internal/core.JobSpec, declared as:

type JobInfo struct {
	// Schedule is "every 10s" or a five-field cron expression.
	Schedule string `json:"schedule"`
	// Kind is "interval" or "cron".
	Kind     string `json:"kind"`
}

type JournalCheck

JournalCheck is what verifying the journal's chain found. A broken chain names the first entry whose hash does not follow.

type JournalCheck = core.JournalCheckMessage

JournalCheck is an alias of github.com/kitsunium/sdk/framework/model/internal/core.JournalCheckMessage, declared as:

type JournalCheck struct {
	// Entries is how many entries the journal holds.
	Entries  int     `json:"entries"`
	// BrokenAt is the sequence number where the chain breaks: an entry
	// changed, or one removed before it, or a JournalContinue entry
	// that does not name the hash of the entry before it. Zero when the
	// chain holds.
	BrokenAt int64   `json:"brokenAt,omitempty"`
	// Closed are the last entries of the journals the journal closed,
	// each followed by the JournalContinue entry that names its hash:
	// the chain holds across them, journal after journal.
	Closed   []int64 `json:"closed,omitempty"`
}

type JournalEntry

JournalEntry is one operation of the privacy journal: what was done, where, by whom and when, with references only — never an identity, a value or a key. Each entry is chained to the previous one by SHA-256.

type JournalEntry = core.JournalEntryEvent

JournalEntry is an alias of github.com/kitsunium/sdk/framework/model/internal/core.JournalEntryEvent, declared as:

type JournalEntry struct {
	// Seq numbers the entries from 1, with no gap.
	Seq     int64     `json:"seq"`
	// At is when, on the app's clock.
	At      time.Time `json:"at"`
	// Op is one of the Journal constants.
	Op      string    `json:"op"`
	// DryRun marks what the retention would have done under
	// <PRODUCT>_RETENTION=dry-run: nothing changed.
	DryRun  bool      `json:"dryRun,omitempty"`
	// Store is the store's node ID.
	Store   string    `json:"store,omitempty"`
	// Record is the record's reference; Subject its subject's.
	Record  string    `json:"record,omitempty"`
	Subject string    `json:"subject,omitempty"`
	// By is who: a user's ID, the node that called, "retention", "cli" or
	// "studio".
	By      string    `json:"by"`
	// Follows is set on a JournalContinue entry alone: the hash of the
	// last entry of the journal it continues, which closed there. Its
	// own chain starts again from it (ADR 0180 step 5c).
	Follows string    `json:"follows,omitempty"`
	// Hash is the entry's link in the chain: SHA-256 of the previous
	// entry's hash and this entry — of nothing and this entry for a
	// JournalContinue entry, which opens a chain.
	Hash    string    `json:"hash"`
}

type LibraryInfo

LibraryInfo is a package shared between components (D19): the Node.Library of a KindLibrary node.

type LibraryInfo = core.LibrarySpec

LibraryInfo is an alias of github.com/kitsunium/sdk/framework/model/internal/core.LibrarySpec, declared as:

type LibraryInfo struct {
	// Package is its Go import path.
	Package string `json:"package"`
}

Link is a relationship between two elements of the architecture. The process's link to a database, "Reads and writes", carries the database connector, and the store connector once stores live on it.

type Link = core.LinkMessage

Link is an alias of github.com/kitsunium/sdk/framework/model/internal/core.LinkMessage, declared as:

type Link struct {
	// From is the ID of a person, system or container.
	From       string   `json:"from"`
	// To is the ID of a person, system or container.
	To         string   `json:"to"`
	// Label says what the relationship is: "Reads and writes".
	Label      string   `json:"label"`
	// Technology says how: "JSON over HTTP", "SMTP", "file I/O".
	Technology string   `json:"technology,omitempty"`
	// Nodes are the nodes whose edges make the link true.
	Nodes      []string `json:"nodes,omitempty"`
	// Connectors are the connectors the link is made of: one link from the
	// process to the data directory carries the stores, the queues and the
	// mail outbox.
	Connectors []string `json:"connectors,omitempty"`
}

type ListenerInfo

ListenerInfo is a listener that is not HTTP: the Node.Listener of a KindListener node — its network, its contract, who may connect.

type ListenerInfo = core.ListenerSpec

ListenerInfo is an alias of github.com/kitsunium/sdk/framework/model/internal/core.ListenerSpec, declared as:

type ListenerInfo struct {
	// Network is one of the Network constants.
	Network  string `json:"network"`
	// Contract is the versioned contract spoken on it: "render/v1".
	Contract string `json:"contract"`
	// Peer says who may connect: "owner" (the process's own user), or the
	// declared list, never "anyone".
	Peer     string `json:"peer"`
	// Role is the ID of the role that runs it.
	Role     string `json:"role,omitempty"`
}

type LogRecord

LogRecord is one log record written by product code through app.Log, kept in dev so the Studio can show a request's logs beside its spans.

type LogRecord = core.LogRecordMessage

LogRecord is an alias of github.com/kitsunium/sdk/framework/model/internal/core.LogRecordMessage, declared as:

type LogRecord struct {
	// Seq orders records; it only increases.
	Seq     uint64            `json:"seq"`
	// Time is when it was written.
	Time    time.Time         `json:"time"`
	// Level is "debug", "info", "warn" or "error".
	Level   string            `json:"level"`
	// Message is the record's message.
	Message string            `json:"message"`
	// Node is the node whose code wrote it.
	Node    string            `json:"node,omitempty"`
	// TraceID and SpanID correlate it with a span.
	TraceID string            `json:"traceId,omitempty"`
	SpanID  string            `json:"spanId,omitempty"`
	// Attrs are the record's attributes, as text, secrets redacted.
	Attrs   map[string]string `json:"attrs,omitempty"`
}

type Loop

Loop is one recurring piece of the daemon's internal loop: a job, a workflow's timer sweep, a subscription's consumer, the HTTP accept loop, a declared or hand-written loop.

type Loop = core.LoopMessage

Loop is an alias of github.com/kitsunium/sdk/framework/model/internal/core.LoopMessage, declared as:

type Loop struct {
	// Name identifies the loop.
	Name       string     `json:"name"`
	// Node is the node the loop drives.
	Node       string     `json:"node,omitempty"`
	// Kind is one of the Loop constants.
	Kind       string     `json:"kind"`
	// Provenance is one of the Provenance constants.
	Provenance string     `json:"provenance,omitempty"`
	// Library names the code that loops, for a library or kit loop:
	// "net/http", "sdk/v1/app/scheduler", "sdk/v1/data/queue",
	// "sdk/v1/app/mail/spool", "sdk/v1/app/statemachine", "app".
	Library    string     `json:"library,omitempty"`
	// State is one of the Loop state constants.
	State      string     `json:"state,omitempty"`
	// LastWake is why the last run started: "interval", "topic",
	// "deadline", "manual", "start".
	LastWake   string     `json:"lastWake,omitempty"`
	// Restarts counts supervised restarts, for a hand-written loop.
	Restarts   int64      `json:"restarts,omitempty"`
	// Schedule is human text: "every 10s", "*/5 * * * *", "on publish · poll 5s".
	Schedule   string     `json:"schedule"`
	// Runs counts completed runs.
	Runs       int64      `json:"runs"`
	// Errors counts failed runs.
	Errors     int64      `json:"errors"`
	// Missed counts due instants dropped because they had already passed.
	Missed     int64      `json:"missed"`
	// Skipped counts fires skipped because the previous run was still going.
	Skipped    int64      `json:"skipped"`
	// LastRun is when the last run started.
	LastRun    *time.Time `json:"lastRun,omitempty"`
	// LastMs is how long the last run took.
	LastMs     float64    `json:"lastMs,omitempty"`
	// NextRun is when the next run is due, when it is known.
	NextRun    *time.Time `json:"nextRun,omitempty"`
	// LastError is the public message of the last failure.
	LastError  string     `json:"lastError,omitempty"`
}

type LoopInfo

LoopInfo describes a loop node. Style says whether it is declared (kit owns the wait) or hand-written.

type LoopInfo = core.LoopSpec

LoopInfo is an alias of github.com/kitsunium/sdk/framework/model/internal/core.LoopSpec, declared as:

type LoopInfo struct {
	// Style is [LoopDeclared] or [LoopGoroutine].
	Style   string              `json:"style"`
	// Wakes are what wakes a declared loop.
	Wakes   []WakeSourceMessage `json:"wakes,omitempty"`
	// Selects are the cases of the select statements a hand-written loop
	// waits in, as the static analysis read them.
	Selects []SelectCaseMessage `json:"selects,omitempty"`
	// Restart is the supervision policy, as text.
	Restart string              `json:"restart,omitempty"`
}

type MailMessage

MailMessage is a whole captured mail, for the Studio's mailbox. It is kept by the capture transport of dev and tests only, never in production.

type MailMessage = core.MailMessage

MailMessage is an alias of github.com/kitsunium/sdk/framework/model/internal/core.MailMessage, declared as:

type MailMessage struct {
	MailSummary
	// Text is the plain text body.
	Text    string            `json:"text,omitempty"`
	// HTML is the HTML body. The Studio renders it in a sandboxed frame
	// that runs no script.
	HTML    string            `json:"html,omitempty"`
	// Headers are the extra headers, rendered.
	Headers map[string]string `json:"headers,omitempty"`
	// Raw is the composed message, as the transport received it.
	Raw     string            `json:"raw,omitempty"`
}

type MailSummary

MailSummary is the name MailMessage embeds its summary under: the field a caller sets and reads is MailMessage.MailSummary, its JSON members promoted beside the body's.

type MailSummary = core.MailSummary

MailSummary is an alias of github.com/kitsunium/sdk/framework/model/internal/core.MailSummaryMessage, declared as:

type MailSummary struct {
	// ID identifies the mail in the outbox.
	ID       string     `json:"id"`
	// Mailer is the mailer node.
	Mailer   string     `json:"mailer"`
	// From and To are addresses, rendered.
	From     string     `json:"from"`
	To       []string   `json:"to"`
	// Subject is the subject.
	Subject  string     `json:"subject"`
	// Status is one of the Mail constants.
	Status   string     `json:"status"`
	// Attempts counts delivery attempts.
	Attempts int        `json:"attempts"`
	// Error is the public message of the last failure.
	Error    string     `json:"error,omitempty"`
	// GivenUp says why a dead mail was given up: [MailRejected],
	// [MailExpired] or [MailExhausted]; empty for any other status.
	GivenUp  string     `json:"givenUp,omitempty"`
	// Reply is the SMTP reply code of the last failure, 550 for instance,
	// when the receiving server answered one; its text is never kept.
	Reply    int        `json:"reply,omitempty"`
	// QueuedAt is when it entered the outbox; SentAt when it left.
	QueuedAt time.Time  `json:"queuedAt"`
	SentAt   *time.Time `json:"sentAt,omitempty"`
	// TraceID is the trace that queued it.
	TraceID  string     `json:"traceId,omitempty"`
	// Node is the node that queued it.
	Node     string     `json:"node,omitempty"`
}

type MailerInfo

MailerInfo describes outbound mail. It carries the transport that empties the outbox and the outbox's counters.

type MailerInfo = core.MailerSpec

MailerInfo is an alias of github.com/kitsunium/sdk/framework/model/internal/core.MailerSpec, declared as:

type MailerInfo struct {
	// Transport is [TransportSMTP] or [TransportCapture].
	Transport   string `json:"transport"`
	// Server is the relay's host:port. Credentials never appear.
	Server      string `json:"server,omitempty"`
	// TLS is "starttls", "implicit" or "none", for SMTP.
	TLS         string `json:"tls,omitempty"`
	// From is the default sender.
	From        string `json:"from,omitempty"`
	// MaxAttempts is how many deliveries a message gets before it is
	// dead-lettered.
	MaxAttempts int    `json:"maxAttempts"`
	// Outbox is "memory", "file" or "sql": where queued messages wait — "sql"
	// on the database that keeps the mailer's service, each message sealed.
	Outbox      string `json:"outbox,omitempty"`
	// Queued is how many messages wait in the outbox, on a runtime graph.
	Queued      *int   `json:"queued,omitempty"`
	// Sent is how many messages the transport accepted, on a runtime graph.
	Sent        *int   `json:"sent,omitempty"`
	// DeadLetters is how many messages were abandoned, on a runtime graph.
	DeadLetters *int   `json:"deadLetters,omitempty"`
}

type Mechanic

Mechanic is a generic building block, backed by an SDK package, that a node composes. The catalog lists every mechanic kit offers; an endpoint's pipeline lists the ones it uses.

type Mechanic = core.MechanicMessage

Mechanic is an alias of github.com/kitsunium/sdk/framework/model/internal/core.MechanicMessage, declared as:

type Mechanic struct {
	// Kind is the stable identifier: "validate", "ratelimit", "timeout"…
	Kind    string            `json:"kind"`
	// Label is a short human rendering of the configuration: "5/s".
	Label   string            `json:"label"`
	// Package is the SDK package that implements it.
	Package string            `json:"package,omitempty"`
	// Doc says what it does, for a catalog.
	Doc     string            `json:"doc,omitempty"`
	// Snippet is the Go code that adds it, for a catalog.
	Snippet string            `json:"snippet,omitempty"`
	// Config is the configuration, as text.
	Config  map[string]string `json:"config,omitempty"`
}

type Migration

Migration is one versioned migration. Its Version orders it among the others; Name says what it does.

type Migration = core.MigrationMessage

Migration is an alias of github.com/kitsunium/sdk/framework/model/internal/core.MigrationMessage, declared as:

type Migration struct {
	// Version orders it: a UTC timestamp by convention, 20260910143000.
	Version uint64 `json:"version"`
	// Name says what it does; empty for a version this build does not carry.
	Name    string `json:"name,omitempty"`
}

type MigrationSet

MigrationSet is one set of migrations on a database — kit's own, the product's (app.Migrations), a module's — with its own version table, and so its own lock.

type MigrationSet = core.MigrationSetMessage

MigrationSet is an alias of github.com/kitsunium/sdk/framework/model/internal/core.MigrationSetMessage, declared as:

type MigrationSet struct {
	// Name is the set's origin: "app", "product", or a module's name.
	Name    string             `json:"name"`
	// Table is its version table: "app_migrations", "schema_migrations".
	Table   string             `json:"table"`
	// Applied are the migrations the database records, and Pending those
	// this build carries that it does not, oldest first.
	Applied []MigrationMessage `json:"applied,omitempty"`
	Pending []MigrationMessage `json:"pending,omitempty"`
	// Problem is why the set could not be read or applied.
	Problem string             `json:"problem,omitempty"`
}

type Mock

Mock is the replacement a test gave the app (MockReplace). It is set by a test only; the Studio shows it and never sets one (D13).

type Mock = core.MockMessage

Mock is an alias of github.com/kitsunium/sdk/framework/model/internal/core.MockMessage, declared as:

type Mock struct {
	// Node is the node it applies to: a port, a command or a query.
	Node string `json:"node"`
	// Mode is [MockReplace].
	Mode string `json:"mode"`
	// Hits counts the runs it changed.
	Hits int64  `json:"hits"`
}

type Module

Module is a module the app mounts: a Go module's services, released and mounted together like a bundle (ADR 0008). Everything a module declares is qualified with its name: its services are "<module>.<service>" — the one named like the module is "<module>" —, so its nodes are "<module>.<service>/<kind>/<name>" and carry Node.Module.

type Module = core.ModuleMessage

Module is an alias of github.com/kitsunium/sdk/framework/model/internal/core.ModuleMessage, declared as:

type Module struct {
	// Name is the name app.NewModule gives it.
	Name       string                `json:"name"`
	// Doc is its description in the product's default language; Docs the
	// same in other languages, by tag, as a node's.
	Doc        string                `json:"doc,omitempty"`
	Docs       map[string]string     `json:"docs,omitempty"`
	// Package is the Go package that declares it: the one a product imports.
	Package    string                `json:"package,omitempty"`
	// Build is the Go module it comes from, and its version.
	Build      *ModuleVersionMessage `json:"build,omitempty"`
	// Services are its services' IDs, in the order it lists them.
	Services   []string              `json:"services"`
	// Requires are the modules it requires (app.Requires), by name.
	Requires   []string              `json:"requires,omitempty"`
	// RequiredBy are the mounted modules that require it, by name, sorted.
	RequiredBy []string              `json:"requiredBy,omitempty"`
	// Prefix is where its routes are served: "/<name>/" unless the mount
	// says otherwise (app.Prefix); "/" shares the product's route space.
	Prefix     string                `json:"prefix"`
	// Source is where app.NewModule declares it.
	Source     *SourceMessage        `json:"source,omitempty"`
	// Mount is where the app mounts it — App.With or app.Mount —; absent
	// when only another module's app.Requires mounted it, at its defaults.
	Mount      *SourceMessage        `json:"mount,omitempty"`
	// Only are the environments its mounts hold in (app.Only), sorted:
	// present when every mount the app gives it names its environments,
	// absent when one holds in every environment, or when only another
	// module's app.Requires mounted it. Added at Version 5: a reader
	// that does not know it reads the graph as before.
	Only       []string              `json:"only,omitempty"`
}

type ModuleVersion

ModuleVersion identifies one module of a build. Local and Modified say when the code that ran is not the published version.

type ModuleVersion = core.ModuleVersionMessage

ModuleVersion is an alias of github.com/kitsunium/sdk/framework/model/internal/core.ModuleVersionMessage, declared as:

type ModuleVersion struct {
	// Module is the module path.
	Module   string     `json:"module"`
	// Version is the published module version, "v0.4.6"; empty for a local
	// directory or a build without module version.
	Version  string     `json:"version,omitempty"`
	// Revision is the VCS commit the module was built from, when known.
	Revision string     `json:"revision,omitempty"`
	// Time is that commit's time.
	Time     *time.Time `json:"time,omitempty"`
	// Modified is set when the build included uncommitted changes.
	Modified bool       `json:"modified,omitempty"`
	// Local is set when the module came from a local directory (a replace
	// or a workspace) rather than a published version.
	Local    bool       `json:"local,omitempty"`
}

type Node

Node is one building block. Its ID is its identity; exactly one of the kind-specific fields matching Kind is set.

type Node = core.NodeEntity

Node is an alias of github.com/kitsunium/sdk/framework/model/internal/core.NodeEntity, declared as:

type Node struct {
	// ID is "<service>/<kind>/<name>", "<service>" for a service,
	// "binary:<name>" for a binary, "binary:<binary>/role/<name>" for a
	// role, "library:<name>" for a library, or [ExternalID]: the grammar of
	// [IDValue].
	ID           string            `json:"id"`
	// Kind says which building block this is.
	Kind         NodeKind          `json:"kind"`
	// Name is unique among the nodes of one kind in one service.
	Name         string            `json:"name"`
	// Service is the owning service ID. Empty for services and external.
	Service      string            `json:"service,omitempty"`
	// Module is the module the node belongs to — a module's service and
	// every node of it —; empty for the product's own.
	Module       string            `json:"module,omitempty"`
	// Doc is the Go doc comment of the declaration or of its handler, in
	// the product's default language.
	Doc          string            `json:"doc,omitempty"`
	// Docs are the same description in other languages, by tag ("fr"),
	// from the comment's tagged paragraphs: see [SplitDoc].
	Docs         map[string]string `json:"docs,omitempty"`
	// Source is where the node is declared.
	Source       *SourceMessage    `json:"source,omitempty"`
	// Handler is the body of the function the node runs, when it has one.
	Handler      *SourceMessage    `json:"handler,omitempty"`
	Endpoint     *EndpointSpec     `json:"endpoint,omitempty"`
	Store        *StoreSpec        `json:"store,omitempty"`
	Topic        *TopicSpec        `json:"topic,omitempty"`
	Subscription *SubscriptionSpec `json:"subscription,omitempty"`
	Workflow     *WorkflowSpec     `json:"workflow,omitempty"`
	Job          *JobSpec          `json:"job,omitempty"`
	Frontend     *FrontendSpec     `json:"frontend,omitempty"`
	Auth         *AuthSpec         `json:"auth,omitempty"`
	Mailer       *MailerSpec       `json:"mailer,omitempty"`
	Loop         *LoopSpec         `json:"loop,omitempty"`
	Secret       *SecretSpec       `json:"secret,omitempty"`
	Port         *PortSpec         `json:"port,omitempty"`
	Command      *CommandSpec      `json:"command,omitempty"`
	Query        *QuerySpec        `json:"query,omitempty"`
	Binary       *BinarySpec       `json:"binary,omitempty"`
	Role         *RoleSpec         `json:"role,omitempty"`
	CLI          *CLISpec          `json:"cli,omitempty"`
	Listener     *ListenerSpec     `json:"listener,omitempty"`
	Library      *LibrarySpec      `json:"library,omitempty"`
	Presentation *PresentationSpec `json:"presentation,omitempty"`
	// Code is the code the node runs, as the static analysis read it: C4's
	// code level.
	Code         *CodeResult       `json:"code,omitempty"`
	// Stats are runtime counters, present on a runtime graph.
	Stats        *StatsMessage     `json:"stats,omitempty"`
}

type NodeCost

NodeCost is what one node cost. It is the share of the profile's samples spent in the node's code.

type NodeCost = core.NodeCostMessage

NodeCost is an alias of github.com/kitsunium/sdk/framework/model/internal/core.NodeCostMessage, declared as:

type NodeCost struct {
	// Node is the node ID.
	Node  string            `json:"node"`
	// Value is the cost, in the profile's unit.
	Value float64           `json:"value"`
	// Share is Value over Total, from 0 to 1.
	Share float64           `json:"share"`
	// Top are the node's costliest functions.
	Top   []FuncCostMessage `json:"top,omitempty"`
}

type NodeKind

NodeKind is the closed set of building blocks a kit product is made of. It is a wire format — the graph's JSON and the Studio's TypeScript unions carry these names —, so it stays a string.

type NodeKind = core.NodeKind

NodeKind is an alias of github.com/kitsunium/sdk/framework/model/internal/core.NodeKind, declared as:

type NodeKind string

type PasswordPolicy

PasswordPolicy is the policy of one secret field that holds a password's hash (Store.Passwords).

type PasswordPolicy = core.PasswordPolicyMessage

PasswordPolicy is an alias of github.com/kitsunium/sdk/framework/model/internal/core.PasswordPolicyMessage, declared as:

type PasswordPolicy struct {
	// Field is the field's JSON pointer: "/password".
	Field     string         `json:"field"`
	// MinLength is the fewest characters a password may have.
	MinLength int            `json:"minLength"`
	// NotReused is how many former passwords it refuses; zero when it
	// refuses none.
	NotReused int            `json:"notReused,omitempty"`
	// NotCommon says it refuses the most common passwords (app.NotCommon),
	// as every policy does.
	NotCommon bool           `json:"notCommon,omitempty"`
	// Source is where the policy is declared.
	Source    *SourceMessage `json:"source,omitempty"`
}

type Payload

Payload is the request and the response of a span, as JSON, in dev only. Every member whose name says it is a secret — password, token, secret, authorization, cookie… — or whose Go field is tagged app:"secret" is replaced by "[redacted]", and each side is cut at 8 KiB.

type Payload = core.Payload

Payload is an alias of github.com/kitsunium/sdk/framework/model/internal/core.Payload, declared as:

type Payload struct {
	// Request is the decoded request, or the message delivered.
	Request   json.RawMessage `json:"request,omitempty"`
	// Response is the response.
	Response  json.RawMessage `json:"response,omitempty"`
	// Truncated is set when a side was cut.
	Truncated bool            `json:"truncated,omitempty"`
}

type Permission

Permission is what a caller needs to dispatch a command or to ask a query: that the app's policy lets it do Action to Resource (Allow).

type Permission = core.PermissionMessage

Permission is an alias of github.com/kitsunium/sdk/framework/model/internal/core.PermissionMessage, declared as:

type Permission struct {
	// Action is what the caller does: "place".
	Action   string `json:"action"`
	// Resource is the kind of thing it does it to: "order".
	Resource string `json:"resource"`
}

type Person

Person is a human user of the product. It is drawn at the edge of the C4 context view, outside every container.

type Person = core.PersonMessage

Person is an alias of github.com/kitsunium/sdk/framework/model/internal/core.PersonMessage, declared as:

type Person struct {
	// ID is unique in the architecture: "person:user".
	ID   string `json:"id"`
	// Name is what the diagram prints: "User".
	Name string `json:"name"`
	// Doc says who they are and what they do with the product.
	Doc  string `json:"doc,omitempty"`
}

type PersonalData

PersonalData is a person's data as app.Export gives it (GDPR art. 15 and 20): their records, store by store, with what art. 15(1) asks beside them.

type PersonalData = core.PersonalDataMessage

PersonalData is an alias of github.com/kitsunium/sdk/framework/model/internal/core.PersonalDataMessage, declared as:

type PersonalData struct {
	// Stores are the stores that keep records about the person.
	Stores []StoreDataMessage `json:"stores"`
}

type PhaseChange

PhaseChange is one step of the daemon's life. It carries the phase entered, when it was entered, and why.

type PhaseChange = core.PhaseChangeEvent

PhaseChange is an alias of github.com/kitsunium/sdk/framework/model/internal/core.PhaseChangeEvent, declared as:

type PhaseChange struct {
	// Phase is the phase entered: one of the Phase constants.
	Phase  string    `json:"phase"`
	// At is when.
	At     time.Time `json:"at"`
	// Reason says why, when it is not the natural next step: "SIGTERM",
	// "a component failed".
	Reason string    `json:"reason,omitempty"`
}

type Pool

Pool is a database's connection pool, as database/sql counts it. It is sampled when the runtime state is read; its counters never move a revision.

type Pool = core.Pool

Pool is an alias of github.com/kitsunium/sdk/framework/model/internal/core.Pool, declared as:

type Pool struct {
	// MaxOpen is its ceiling.
	MaxOpen int     `json:"maxOpen"`
	// Open is how many connections are open: InUse and Idle.
	Open    int     `json:"open"`
	InUse   int     `json:"inUse"`
	Idle    int     `json:"idle"`
	// Waits counts the calls that waited for a connection, and WaitMs how
	// long they waited in all.
	Waits   int64   `json:"waits"`
	WaitMs  float64 `json:"waitMs"`
	// Closed counts the connections closed for being idle too many, idle
	// too long, or too old.
	Closed  int64   `json:"closed,omitempty"`
}

type Port

Port is an address a process listens on. Owner is the container that listens on it; Serves names what is reached through it.

type Port = core.PortMessage

Port is an alias of github.com/kitsunium/sdk/framework/model/internal/core.PortMessage, declared as:

type Port struct {
	// Address is the listen address: "127.0.0.1:4000", ":4000". Present in
	// dev only, like every location.
	Address  string   `json:"address,omitempty"`
	// Owner is [PortOwnerApp], or the ID of the connector that opened it.
	Owner    string   `json:"owner"`
	// Serves says what it answers: the Serves constants.
	Serves   []string `json:"serves"`
	// Settings are the settings that configure it.
	Settings []string `json:"settings,omitempty"`
}

type PortInfo

PortInfo describes a port: an operation a service needs and another implements.

type PortInfo = core.PortSpec

PortInfo is an alias of github.com/kitsunium/sdk/framework/model/internal/core.PortSpec, declared as:

type PortInfo struct {
	// Request is the type the port is called with.
	Request    *SchemaMessage    `json:"request,omitempty"`
	// Response is the type it answers.
	Response   *SchemaMessage    `json:"response,omitempty"`
	// Fallback is the node ID of the operation the port declares for when
	// the app binds nothing else (app.Fallback).
	Fallback   string            `json:"fallback,omitempty"`
	// Bound is the node ID of the operation the port calls, as the start
	// chose it — on a static graph, as the analysis reads the same rule;
	// empty when nothing is bound or a test replaced the port. The graph
	// draws it as a declared edge from the port.
	Bound      string            `json:"bound,omitempty"`
	// Via is how it was chosen: one of the Via constants.
	Via        string            `json:"via,omitempty"`
	// Pipeline are the policies around the port's calls (Port.Guard), the
	// outermost first — retry, hedge, breaker, throttle, timeout —, its
	// retry budget before them, with the values the app runs with.
	Pipeline   []MechanicMessage `json:"pipeline,omitempty"`
	// Idempotent says the port's operation may run more than once for one
	// call (app.Idempotent): what a hedge needs.
	Idempotent bool              `json:"idempotent,omitempty"`
}

type PresentationInfo

PresentationInfo is what turns results into what a reader sees: the Node.Presentation of a KindPresentation node.

type PresentationInfo = core.PresentationSpec

PresentationInfo is an alias of github.com/kitsunium/sdk/framework/model/internal/core.PresentationSpec, declared as:

type PresentationInfo struct {
	// Media is what it renders: "text", "ansi", "html", "json".
	Media string `json:"media"`
}

type Privacy

Privacy is what a running app says of the personal data it keeps. It is the Privacy page's data: the register, the holds and the journal's state.

type Privacy = core.PrivacyMessage

Privacy is an alias of github.com/kitsunium/sdk/framework/model/internal/core.PrivacyMessage, declared as:

type Privacy struct {
	// Retention is <PRODUCT>_RETENTION: one of the Retention constants.
	Retention string              `json:"retention"`
	// Register is the record of processing, as far as the code knows it.
	Register  RegisterMessage     `json:"register"`
	// Holds are the records a legal hold keeps, newest first.
	Holds     []HoldEvent         `json:"holds,omitempty"`
	// Journal is the privacy journal's latest entries, newest first.
	Journal   []JournalEntryEvent `json:"journal,omitempty"`
	// Chain says whether the journal's chain holds.
	Chain     JournalCheckMessage `json:"chain"`
}

type Process

Process is the Go process a product runs in. It carries the runtime's figures — goroutines, heap, GC, CPU — taken at At.

type Process = core.ProcessSpec

Process is an alias of github.com/kitsunium/sdk/framework/model/internal/core.ProcessSpec, declared as:

type Process struct {
	// PID is the process ID.
	PID               int        `json:"pid"`
	// Go is the Go version the binary was built with.
	Go                string     `json:"go"`
	// OS and Arch are GOOS and GOARCH.
	OS                string     `json:"os"`
	Arch              string     `json:"arch"`
	// MaxProcs is GOMAXPROCS; CPUs the logical CPUs the process sees.
	MaxProcs          int        `json:"maxProcs"`
	CPUs              int        `json:"cpus"`
	// Goroutines is how many goroutines exist.
	Goroutines        int        `json:"goroutines"`
	// HeapBytes is the live heap; HeapObjects its object count.
	HeapBytes         uint64     `json:"heapBytes"`
	HeapObjects       uint64     `json:"heapObjects"`
	// HeapGoalBytes is the heap size at which the next collection starts.
	HeapGoalBytes     uint64     `json:"heapGoalBytes,omitempty"`
	// MemoryBytes is all the memory the Go runtime holds from the system:
	// the heap, the stacks, the runtime's own structures.
	MemoryBytes       uint64     `json:"memoryBytes,omitempty"`
	// TotalAllocBytes is every byte ever allocated on the heap.
	TotalAllocBytes   uint64     `json:"totalAllocBytes"`
	// GCCycles counts completed garbage collections.
	GCCycles          uint64     `json:"gcCycles"`
	// LastGC is when the last collection ended; absent before the first.
	LastGC            *time.Time `json:"lastGC,omitempty"`
	// GCPauseP99Ms is the 99th percentile stop-the-world pause.
	GCPauseP99Ms      float64    `json:"gcPauseP99Ms"`
	// SchedLatencyP99Ms is the 99th percentile time a goroutine waited to run.
	SchedLatencyP99Ms float64    `json:"schedLatencyP99Ms"`
	// CPUSeconds is the CPU time the process consumed, user and system.
	CPUSeconds        float64    `json:"cpuSeconds"`
	// UptimeMs is how long the process has run.
	UptimeMs          float64    `json:"uptimeMs"`
	// At is when the sample was taken.
	At                time.Time  `json:"at"`
}

type ProductRetention

ProductRetention is a retention the product keeps itself, as it says it.

type ProductRetention = core.ProductRetentionSpec

ProductRetention is an alias of github.com/kitsunium/sdk/framework/model/internal/core.ProductRetentionSpec, declared as:

type ProductRetention struct {
	// Limits says, in the product's words, how long the records keep their
	// personal data and how they go — the register's time limits, GDPR
	// art. 30(1)(f); empty when it gave none.
	Limits string `json:"limits,omitempty"`
}

type Profile

Profile is a pprof profile of the running product, folded onto its graph: every sample is attributed to the node whose code was running — through the pprof label kit puts on every handler, subscription, job and loop run, or, for the heap, which carries no label, through the node's code functions on the sample's stack.

type Profile = core.ProfileResult

Profile is an alias of github.com/kitsunium/sdk/framework/model/internal/core.ProfileResult, declared as:

type Profile struct {
	// Kind is one of the Profile constants.
	Kind         string            `json:"kind"`
	// At is when the profile ended.
	At           time.Time         `json:"at"`
	// DurationMs is how long a CPU profile sampled.
	DurationMs   float64           `json:"durationMs,omitempty"`
	// Unit is what the values count: "ms" of CPU, "bytes" of heap.
	Unit         string            `json:"unit"`
	// Total is the sum of every sample.
	Total        float64           `json:"total"`
	// Nodes are the costs attributed to nodes, highest first.
	Nodes        []NodeCostMessage `json:"nodes"`
	// Unattributed is the cost outside any node's code: the runtime, the
	// garbage collector, kit itself, idle loops.
	Unattributed float64           `json:"unattributed"`
	// Top are the costliest functions, by flat cost.
	Top          []FuncCostMessage `json:"top"`
	// Flame is the call tree, root first, pruned below 0.5% of Total.
	Flame        *FlameNodeMessage `json:"flame,omitempty"`
}

type QueryInfo

QueryInfo describes a query: an operation that reads and changes nothing.

type QueryInfo = core.QuerySpec

QueryInfo is an alias of github.com/kitsunium/sdk/framework/model/internal/core.QuerySpec, declared as:

type QueryInfo struct {
	// Input is the type it is asked with.
	Input       *SchemaMessage      `json:"input,omitempty"`
	// Result is the type it answers.
	Result      *SchemaMessage      `json:"result,omitempty"`
	// Auth is [AuthRequired] — implied by a permission —, [AuthOptional],
	// or empty when the query ignores authentication.
	Auth        string              `json:"auth,omitempty"`
	// Pipeline lists the mechanics a question goes through before the
	// handler, in the order they run.
	Pipeline    []MechanicMessage   `json:"pipeline,omitempty"`
	// Permissions are the permissions a caller needs (Allow).
	Permissions []PermissionMessage `json:"permissions,omitempty"`
	// Authorize locates the function of its Authorize: a rule that needs
	// the data.
	Authorize   *SourceMessage      `json:"authorize,omitempty"`
}

type RecordFormer

RecordFormer is the former values of one exported record's fields. A personal or special field's former values are redacted, never exported in clear.

type RecordFormer = core.RecordFormerMessage

RecordFormer is an alias of github.com/kitsunium/sdk/framework/model/internal/core.RecordFormerMessage, declared as:

type RecordFormer struct {
	// Record is the record's position in its StoreData's Records.
	Record int                        `json:"record"`
	// Fields are each field's former values, newest first, by the field's
	// JSON pointer. A secret field's are left out.
	Fields map[string][]FormerMessage `json:"fields"`
}

type RecordHistory

RecordHistory is what kit remembers of one record, as the Studio's data view shows it (GET /_app/api/former): each field's former values, newest first, by the field's JSON pointer — a secret field's without their values, a personal or special one's redacted.

type RecordHistory = core.RecordHistoryMessage

RecordHistory is an alias of github.com/kitsunium/sdk/framework/model/internal/core.RecordHistoryMessage, declared as:

type RecordHistory struct {
	Fields map[string][]FormerMessage `json:"fields"`
}

type RecordVersion

RecordVersion is one version of a record whose store keeps revisions (ADR 0007 §3): its number, when the write that made it ran, who made it and which command, and the record as it was.

type RecordVersion = core.RecordVersionMessage

RecordVersion is an alias of github.com/kitsunium/sdk/framework/model/internal/core.RecordVersionMessage, declared as:

type RecordVersion struct {
	Number  uint64          `json:"number"`
	// At is when the write that made it ran, on the app's clock.
	At      time.Time       `json:"at,omitzero"`
	// By is the user who made it — app.UserID —, empty for a write with no
	// user.
	By      string          `json:"by,omitempty"`
	// Command is the node ID of the command that made it, empty outside
	// one.
	Command string          `json:"command,omitempty"`
	// Value is the record as it was: in an export, its secret members left
	// out; in the Studio, as the data browser shows a record.
	Value   json.RawMessage `json:"value,omitempty" app:"personal"`
}

type RecordVersions

RecordVersions is a record's versions as the Studio's data view shows them (GET /_app/api/revisions), and what changed between two.

type RecordVersions = core.RecordVersionsMessage

RecordVersions is an alias of github.com/kitsunium/sdk/framework/model/internal/core.RecordVersionsMessage, declared as:

type RecordVersions struct {
	Versions []RecordVersionMessage `json:"versions"`
	// From and To are the two versions compared, when asked for; Edits what
	// changed between them.
	From     uint64                 `json:"from,omitempty"`
	To       uint64                 `json:"to,omitempty"`
	Edits    []EditMessage          `json:"edits,omitempty"`
}

type Register

Register is the record of processing of GDPR art. 30(1), as far as the code knows it.

type Register = core.RegisterMessage

Register is an alias of github.com/kitsunium/sdk/framework/model/internal/core.RegisterMessage, declared as:

type Register struct {
	// App is the product.
	App        string                 `json:"app"`
	// ToComplete are the points the code cannot know, for a person to
	// write: "a" (the controller and its representatives), "e" (the
	// transfers).
	ToComplete []string               `json:"toComplete,omitempty"`
	// Stores are the stores that keep personal data, by node ID.
	Stores     []RegisterStoreMessage `json:"stores,omitempty"`
}

type RegisterStore

RegisterStore is one store's line in the register. It names the classes the store keeps, their purposes and their retention.

type RegisterStore = core.RegisterStoreMessage

RegisterStore is an alias of github.com/kitsunium/sdk/framework/model/internal/core.RegisterStoreMessage, declared as:

type RegisterStore struct {
	// Store is the store's node ID.
	Store      string                `json:"store"`
	// Purpose is point (b): why the store keeps its records.
	Purpose    string                `json:"purpose,omitempty"`
	// Subject is point (c)'s category of data subjects: the pointer of the
	// field that says whom each record is about.
	Subject    string                `json:"subject,omitempty"`
	// SubjectDoc is that field's comment, when the analyzer read it.
	SubjectDoc string                `json:"subjectDoc,omitempty"`
	// Personal, Special and Secret are point (c)'s categories of personal
	// data: the fields of each class, as JSON pointers. Special fields are
	// art. 9 data; secret ones are credentials.
	Personal   []string              `json:"personal,omitempty"`
	Special    []string              `json:"special,omitempty"`
	Secret     []string              `json:"secret,omitempty"`
	// Recipients are point (d) inside the product: the nodes the graph
	// shows reading the store, and the connectors that carry its data out.
	Recipients []string              `json:"recipients,omitempty"`
	// Erase, Delete and HeldUntil are point (f), the time limits, in words.
	Erase      string                `json:"erase,omitempty"`
	Delete     string                `json:"delete,omitempty"`
	HeldUntil  string                `json:"heldUntil,omitempty"`
	// ByProduct is point (f) when the product keeps the store's retention
	// itself (app.RetentionByProduct), in its own words: no retention gap,
	// and no subject gap either.
	ByProduct  *ProductRetentionSpec `json:"byProduct,omitempty"`
	// Security is point (g): the measures kit takes.
	Security   []string              `json:"security,omitempty"`
	// Gaps are the Gap constants the store lacks.
	Gaps       []string              `json:"gaps,omitempty"`
}

type Retention

Retention is when kit erases or deletes a record: after a delay counted from an instant the record carries (After or Setting, and Since), or at an instant a function gives (At).

type Retention = core.RetentionSpec

Retention is an alias of github.com/kitsunium/sdk/framework/model/internal/core.RetentionSpec, declared as:

type Retention struct {
	// After is the delay, as a Go duration: the declared one, or the
	// setting's value when the graph describes a running app.
	After   string         `json:"after,omitempty"`
	// Setting names the setting of the store's service the delay is read
	// from, when the environment gives it.
	Setting string         `json:"setting,omitempty"`
	// Since locates the function that gives the instant the delay counts
	// from: a record's closing, say.
	Since   *SourceMessage `json:"since,omitempty"`
	// At locates the function that gives the instant itself.
	At      *SourceMessage `json:"at,omitempty"`
}

type RoleInfo

RoleInfo is one process role of a binary: the Node.Role of a KindRole node — its profile, arguments, singleton and idle stop.

type RoleInfo = core.RoleSpec

RoleInfo is an alias of github.com/kitsunium/sdk/framework/model/internal/core.RoleSpec, declared as:

type RoleInfo struct {
	// Binary is the ID of the binary that holds it.
	Binary    string   `json:"binary"`
	// Profile is one of the Profile constants.
	Profile   string   `json:"profile"`
	// Args are the leading arguments that select it — ["daemon"] for
	// "statusline daemon" —; empty for the binary's default role.
	Args      []string `json:"args,omitempty"`
	// Singleton, when set, is the scope of the lock that keeps one process of
	// this role alive at a time: what the lock's name is derived from.
	Singleton string   `json:"singleton,omitempty"`
	// IdleMs is how long a daemon waits without a client before it stops
	// itself; zero means it runs until stopped.
	IdleMs    int64    `json:"idleMs,omitempty"`
}

type Runtime

Runtime is what a running process says about itself: the daemon's own state and its internal loop.

type Runtime = core.RuntimeMessage

Runtime is an alias of github.com/kitsunium/sdk/framework/model/internal/core.RuntimeMessage, declared as:

type Runtime struct {
	// Phase is one of the Phase constants.
	Phase      string             `json:"phase"`
	// StartedAt is when the process started.
	StartedAt  time.Time          `json:"startedAt"`
	// Components are the lifecycle components, in start order.
	Components []ComponentMessage `json:"components"`
	// Loops are the recurring pieces of the internal loop.
	Loops      []LoopMessage      `json:"loops"`
	// History lists the phases the process went through, oldest first: the
	// daemon's own state machine, as it ran.
	History    []PhaseChangeEvent `json:"history,omitempty"`
	// Process is the Go process, sampled when the graph was built; nil when
	// the product imports no framework/app/server, which plugs the sampler
	// in (ADR 0172).
	Process    *ProcessSpec       `json:"process,omitempty"`
	// HTTP is the product's HTTP server.
	HTTP       *HTTPServer        `json:"http,omitempty"`
	// Mocks are the replacements a test gave the app (app.Replace).
	Mocks      []MockMessage      `json:"mocks,omitempty"`
	// Dev describes the build `kit dev` made of this process, when it did.
	Dev        *DevBuildMessage   `json:"dev,omitempty"`
	// Config is how the product was configured when it started: every
	// setting kit read, the value it uses — never a secret's — and where
	// that value came from.
	Config     []SettingMessage   `json:"config,omitempty"`
	// Boot is what kit did to start the product, step by step, as it ran;
	// the lifecycle components it then started are Components.
	Boot       []BootStepMessage  `json:"boot,omitempty"`
	// Databases are the databases the app declares, as this run found them:
	// each one's state, readiness, pool and migrations.
	Databases  []DatabaseMessage  `json:"databases,omitempty"`
	// Export is the product's OTLP export (app.OTLP), as this run found it:
	// its state and each signal's queue; nil when the app declares none.
	Export     *ExportMessage     `json:"export,omitempty"`
}

type Schema

Schema describes a Go type as it appears on the wire. It is a JSON-Schema-like shape: a kind, its fields or elements, and its Go type.

type Schema = core.SchemaMessage

Schema is an alias of github.com/kitsunium/sdk/framework/model/internal/core.SchemaMessage, declared as:

type Schema struct {
	// Type is "object", "array", "map", "string", "integer", "number",
	// "boolean" or "any".
	Type     string         `json:"type"`
	// Name is the qualified Go type name, for named types.
	Name     string         `json:"name,omitempty"`
	// Format refines a scalar: "date-time", "duration", "int64"…
	Format   string         `json:"format,omitempty"`
	// Fields are the members of an object.
	Fields   []FieldMessage `json:"fields,omitempty"`
	// Items is the element type of an array.
	Items    *SchemaMessage `json:"items,omitempty"`
	// Values is the value type of a map.
	Values   *SchemaMessage `json:"values,omitempty"`
	// Enum lists the allowed values, when they are known.
	Enum     []string       `json:"enum,omitempty"`
	// Ref names a type already described higher up, to break a cycle.
	Ref      string         `json:"ref,omitempty"`
	// Nullable says a nil value is written null: a pointer, a slice, a map,
	// an interface — unless its member leaves it out (omitempty, omitzero).
	Nullable bool           `json:"nullable,omitempty"`
}

type SecretInfo

SecretInfo describes a declared secret: how it is made, where it lives, its versions — never its value.

type SecretInfo = core.SecretSpec

SecretInfo is an alias of github.com/kitsunium/sdk/framework/model/internal/core.SecretSpec, declared as:

type SecretInfo struct {
	// Origin is [SecretProvided] or [SecretGenerated].
	Origin       string     `json:"origin"`
	// Variable is the environment variable that provides it, or — for a
	// generated secret — pins it: TODO_SMTP_URL, or TODO_SMTP_URL_FILE naming
	// a file.
	Variable     string     `json:"variable"`
	// Bytes is the size of each version of a generated secret.
	Bytes        int        `json:"bytes,omitempty"`
	// RotateEvery is how often kit makes a new version of a generated
	// secret, as a Go duration.
	RotateEvery  string     `json:"rotateEvery,omitempty"`
	// Keep is how many versions a rotation leaves, the new one included.
	Keep         int        `json:"keep,omitempty"`
	// Optional: a provided secret the product can do without
	// (app.Optional) — found nowhere, it is absent, and the start goes on.
	Optional     bool       `json:"optional,omitempty"`
	// From is where the running app found it: one of the SecretFrom
	// constants, on a runtime graph. Empty when it is found nowhere — for an
	// optional secret, absent.
	From         string     `json:"from,omitempty"`
	// Version is the number of its current version, from 1.
	Version      int        `json:"version,omitempty"`
	// Created is when the current version was made; the environment does
	// not say when a variable was set.
	Created      *time.Time `json:"created,omitempty"`
	// Versions is how many versions are kept.
	Versions     int        `json:"versions,omitempty"`
	// NextRotation is when kit rotates it next. Absent when kit does not
	// rotate it: provided, pinned by the environment, or in a store kit
	// cannot write.
	NextRotation *time.Time `json:"nextRotation,omitempty"`
	// Pinned: a generated secret the environment provides — kit uses it and
	// does not rotate it.
	Pinned       bool       `json:"pinned,omitempty"`
	// Rotations counts the rotations this process made.
	Rotations    int        `json:"rotations,omitempty"`
	// Problem says why it cannot be used, on a runtime graph.
	Problem      string     `json:"problem,omitempty"`
}

type SelectCase

SelectCase is one case of a select statement in a hand-written loop. The analyzer reads it from the loop's body; Kind says what the case waits on.

type SelectCase = core.SelectCaseMessage

SelectCase is an alias of github.com/kitsunium/sdk/framework/model/internal/core.SelectCaseMessage, declared as:

type SelectCase struct {
	// Text is the case as written: "<-ticker.C", "job := <-jobs".
	Text   string         `json:"text"`
	// Kind is one of the Select constants.
	Kind   string         `json:"kind"`
	// Source is where the case is.
	Source *SourceMessage `json:"source,omitempty"`
}

type Setting

Setting is one configuration value kit read when the product started: kit's own, or one a service of the product declares.

type Setting = core.SettingMessage

Setting is an alias of github.com/kitsunium/sdk/framework/model/internal/core.SettingMessage, declared as:

type Setting struct {
	// Name is the environment variable that sets it: "TODO_ADDR",
	// "TODO_BASE_URL".
	Name     string `json:"name"`
	// Value is what kit uses. A secret's is left out: Secret says so.
	Value    string `json:"value,omitempty"`
	// From is one of the Setting constants.
	From     string `json:"from"`
	// Service declared it; empty for kit's own.
	Service  string `json:"service,omitempty"`
	// Key is a declared setting's name, its key in a configuration file:
	// "base-url". A module's is qualified with the module's name,
	// "moderation.tdb-url": app.Set's key, and in a file "tdb-url" under
	// "moderation:" (ADR 0008).
	Key      string `json:"key,omitempty"`
	// Type is what a declared setting holds: text, bool, int, number,
	// duration or list.
	Type     string `json:"type,omitempty"`
	// Detail is the configuration file that gave the value, when From is
	// SettingFile: "config/production.yaml".
	Detail   string `json:"detail,omitempty"`
	// Secret: the value is withheld.
	Secret   bool   `json:"secret,omitempty"`
	// Option is the AppOption that sets it in code, when there is one:
	// "app.Listen". Code wins over the environment.
	Option   string `json:"option,omitempty"`
	// Flag is the kit dev flag that sets it in dev, when there is one:
	// "-addr".
	Flag     string `json:"flag,omitempty"`
	// Database is the database the setting configures, when kit declares it
	// for one (app.Database): its URL, its pool, its timeouts.
	Database string `json:"database,omitempty"`
}

type Snippet

Snippet is source code served to a reader of the graph. Focus and FocusEnd mark the lines a reader asked for, inside the lines served.

type Snippet = core.SnippetMessage

Snippet is an alias of github.com/kitsunium/sdk/framework/model/internal/core.SnippetMessage, declared as:

type Snippet struct {
	// File is relative to App.Root.
	File      string   `json:"file"`
	// StartLine is the 1-based line of Lines[0].
	StartLine int      `json:"startLine"`
	// Focus is the first line of the range asked for.
	Focus     int      `json:"focus"`
	// FocusEnd is the last line of the range asked for.
	FocusEnd  int      `json:"focusEnd,omitempty"`
	// Lines are the file's lines around the focus, without terminators.
	Lines     []string `json:"lines"`
	// Language is the highlighter language: "go", "javascript"…
	Language  string   `json:"language"`
}

type Source

Source locates code. File is relative to its module's root; Line and EndLine bound the declaration.

type Source = core.SourceMessage

Source is an alias of github.com/kitsunium/sdk/framework/model/internal/core.SourceMessage, declared as:

type Source struct {
	// File is relative to App.Root, slash-separated — or, when GoModule is
	// set, to the root of that Go module.
	File     string `json:"file"`
	// Line is 1-based.
	Line     int    `json:"line"`
	// EndLine, when set, closes the range [Line, EndLine].
	EndLine  int    `json:"endLine,omitempty"`
	// Func is the qualified Go function, when the range is a function.
	Func     string `json:"func,omitempty"`
	// GoModule is set on a position outside the product's Go module — a
	// module's (ADR 0008), a library's —: that Go module, "path@version", or
	// its path alone when it is built from a local directory.
	GoModule string `json:"goModule,omitempty"`
}

type Span

Span is a finished unit of work, attributed to a node. Only allow-listed, wire-safe fields travel: no URL, no query string, no private error text.

type Span = core.SpanMessage

Span is an alias of github.com/kitsunium/sdk/framework/model/internal/core.SpanMessage, declared as:

type Span struct {
	// TraceID groups the spans of one causal chain (W3C, hex).
	TraceID  string            `json:"traceId"`
	// SpanID identifies the span (W3C, hex).
	SpanID   string            `json:"spanId"`
	// ParentID is the parent span, absent on a root.
	ParentID string            `json:"parentId,omitempty"`
	// Node is where the work happened.
	Node     string            `json:"node"`
	// From is the node that caused it: the edge this span travelled.
	From     string            `json:"from,omitempty"`
	// Edge is the kind of the edge From → Node.
	Edge     EdgeKind          `json:"edge,omitempty"`
	// Label refines Edge, like the edge's own label.
	Label    string            `json:"label,omitempty"`
	// Op is one of the Op constants.
	Op       string            `json:"op"`
	// Name is a low-cardinality operation name: a route pattern, "Get".
	Name     string            `json:"name"`
	// Start is when the work began.
	Start    time.Time         `json:"start"`
	// Ms is how long it took.
	Ms       float64           `json:"ms"`
	// Status is StatusError when the product failed — what kit answers with
	// a 5xx — and StatusOK otherwise, a refusal the caller has to fix (not
	// found, invalid, conflict, rate limited…) included.
	Status   string            `json:"status"`
	// Code is the error code, when the work ended in one: a failure's, or a
	// refusal's ("not_found").
	Code     string            `json:"code,omitempty"`
	// Error is the wire-safe public message of a failure; a refusal has none.
	Error    string            `json:"error,omitempty"`
	// Attrs are allow-listed attributes: "http.status", "instance"…
	Attrs    map[string]string `json:"attrs,omitempty"`
	// User is the authenticated caller's ID, when there is one.
	User     string            `json:"user,omitempty"`
	// Payload is what went in and out, in dev only, with secrets redacted.
	Payload  *Payload          `json:"payload,omitempty"`
}

type StateInfo

StateInfo is one state of a workflow. Terminal marks a state an instance stays in; Count is how many instances are in it.

type StateInfo = core.StateSpec

StateInfo is an alias of github.com/kitsunium/sdk/framework/model/internal/core.StateSpec, declared as:

type StateInfo struct {
	// Name is the state value, as text.
	Name     string          `json:"name"`
	// Terminal is set when no transition leaves the state.
	Terminal bool            `json:"terminal,omitempty"`
	// Count is how many instances are in the state, on a runtime graph.
	Count    *int            `json:"count,omitempty"`
	// OnEnter lists the hooks run when an instance enters the state.
	OnEnter  []SourceMessage `json:"onEnter,omitempty"`
}

type Stats

Stats are observed counters for a node or an edge. They are counters: they never move a graph's revision.

type Stats = core.StatsMessage

Stats is an alias of github.com/kitsunium/sdk/framework/model/internal/core.StatsMessage, declared as:

type Stats struct {
	// Count is how many times it ran.
	Count  int64      `json:"count"`
	// Errors is how many of those failed.
	Errors int64      `json:"errors"`
	// LastAt is when it last ran.
	LastAt *time.Time `json:"lastAt,omitempty"`
	// AvgMs is the mean duration in milliseconds.
	AvgMs  float64    `json:"avgMs"`
	// MaxMs is the longest duration in milliseconds.
	MaxMs  float64    `json:"maxMs"`
}

type Step

Step is one transition in an instance's history. It carries the event, the states it went from and to, and when it fired.

type Step = core.StepEvent

Step is an alias of github.com/kitsunium/sdk/framework/model/internal/core.StepEvent, declared as:

type Step struct {
	// Event is the transition's event name.
	Event   string    `json:"event"`
	// From is the state left.
	From    string    `json:"from"`
	// To is the state entered.
	To      string    `json:"to"`
	// At is when it happened.
	At      time.Time `json:"at"`
	// Trigger is one of the Trigger constants.
	Trigger string    `json:"trigger"`
	// Caller is the node that fired it, when code did.
	Caller  string    `json:"caller,omitempty"`
}

type StoreData

StoreData is one store's records about a person. It is one part of what app.Export gives a person about themselves.

type StoreData = core.StoreDataMessage

StoreData is an alias of github.com/kitsunium/sdk/framework/model/internal/core.StoreDataMessage, declared as:

type StoreData struct {
	// Store is the store's node ID.
	Store      string                    `json:"store"`
	// Purpose is why the store keeps them.
	Purpose    string                    `json:"purpose,omitempty"`
	// Retention says, in words, how long they keep their personal data.
	Retention  string                    `json:"retention,omitempty"`
	// Recipients are who inside the product reads them, as far as the
	// running app knows.
	Recipients []string                  `json:"recipients,omitempty"`
	// Records are the records, their secret members left out. They hold the
	// person's data, which the Studio and the logs never show.
	Records    []json.RawMessage         `json:"records" app:"personal"`
	// Former are the former values of the records' fields that keep them
	// (ADR 0007), record by record; a secret field's are left out.
	Former     []RecordFormerMessage     `json:"former,omitempty" app:"personal"`
	// Versions are the versions of the records a store with revisions keeps
	// (ADR 0007 §3), record by record, their secret members left out.
	Versions   []ExportedVersionsMessage `json:"versions,omitempty" app:"personal"`
}

type StoreErasure

StoreErasure is one store's part of an erasure: the keys of the records erased, deleted, and held — left in place, as a legal hold asks. A key may be personal data, which the Studio and the logs never show.

type StoreErasure = core.StoreErasureMessage

StoreErasure is an alias of github.com/kitsunium/sdk/framework/model/internal/core.StoreErasureMessage, declared as:

type StoreErasure struct {
	// Store is the store's node ID.
	Store   string   `json:"store"`
	// Erased are the records whose personal data was cleared.
	Erased  []string `json:"erased,omitempty" app:"personal"`
	// Deleted are the records removed.
	Deleted []string `json:"deleted,omitempty" app:"personal"`
	// Held are the records a hold keeps, untouched.
	Held    []string `json:"held,omitempty" app:"personal"`
}

type StoreHistory

StoreHistory is what a store remembers of its records. Fields names the fields it keeps former values of; Kept and Bytes weigh them, and Versions, Trashed and VersionBytes weigh its records' versions.

type StoreHistory = core.StoreHistoryMessage

StoreHistory is an alias of github.com/kitsunium/sdk/framework/model/internal/core.StoreHistoryMessage, declared as:

type StoreHistory struct {
	// Revisions is how many former versions each record keeps
	// (app.Revisions, ADR 0007 §3); zero when it keeps none.
	Revisions    int                     `json:"revisions,omitempty"`
	// Fields are the JSON pointers of the fields that keep their former
	// values: tagged history=N — the schema's Field.History says how many —
	// or read by a password policy that refuses former passwords.
	Fields       []string                `json:"fields,omitempty"`
	// Passwords are the store's password policies.
	Passwords    []PasswordPolicyMessage `json:"passwords,omitempty"`
	// Kept is how many former values the store keeps, and Bytes what its
	// histories weigh, on a runtime graph.
	Kept         *int                    `json:"kept,omitempty"`
	Bytes        *int64                  `json:"bytes,omitempty"`
	// Versions is how many former versions the store's records keep,
	// Trashed how many records are in its trash, and VersionBytes what both
	// weigh — the JSON they hold —, on a runtime graph of a store that keeps
	// revisions (ADR 0007 §5), as the SDK's document store counts them. A
	// record's current version is the record, and counts in none of them.
	Versions     *int                    `json:"versions,omitempty"`
	Trashed      *int                    `json:"trashed,omitempty"`
	VersionBytes *int64                  `json:"versionBytes,omitempty"`
}

type StoreInfo

StoreInfo describes a store. It carries the entity's schema, its backend, its indexes, its privacy and its history.

type StoreInfo = core.StoreSpec

StoreInfo is an alias of github.com/kitsunium/sdk/framework/model/internal/core.StoreSpec, declared as:

type StoreInfo struct {
	// Entity is the stored type.
	Entity    *SchemaMessage       `json:"entity,omitempty"`
	// Backend is where the store's data is: "memory", "file", or the engine
	// of the database that keeps it (ADR 0004): "postgres", "mysql",
	// "sqlite".
	Backend   string               `json:"backend"`
	// Location is where a file backend keeps its data, relative to the data
	// directory.
	Location  string               `json:"location,omitempty"`
	// Database names the database that keeps the store, as the app declares
	// it (app.Database, app.Keeps) — present even while the store's data
	// stays in the data directory, in dev without the database's URL. Its
	// container is "container:database:<name>".
	Database  string               `json:"database,omitempty"`
	// Table is the table the database keeps the store's entities in —
	// "<service>__<store>", '-' and '.' written '_', a digest past the
	// engine's limit —, beside its index rows in "<table>___ix". Present
	// with Database.
	Table     string               `json:"table,omitempty"`
	// Count is how many entities the store holds, on a runtime graph.
	Count     *int                 `json:"count,omitempty"`
	// Indexes are the secondary indexes the store maintains, in declaration
	// order.
	Indexes   []IndexSpec          `json:"indexes,omitempty"`
	// Privacy says what the store does with personal data (ADR 0006): whom
	// its records are about, why it keeps them and for how long. Absent when
	// its entity holds nothing personal and it declares no retention.
	Privacy   *StorePrivacyMessage `json:"privacy,omitempty"`
	// History says what the store remembers of its records (ADR 0007): the
	// fields that keep their former values, its password policies. Absent
	// when it remembers nothing and has no policy.
	History   *StoreHistoryMessage `json:"history,omitempty"`
	// ReadModel is set on a store derived from others (app.ReadModel):
	// written by projections — subscriptions —, read by queries.
	ReadModel bool                 `json:"readModel,omitempty"`
}

type StorePrivacy

StorePrivacy is what a store keeps of people: whom each record is about, why, for how long, and — on a runtime graph — what is held and due.

type StorePrivacy = core.StorePrivacyMessage

StorePrivacy is an alias of github.com/kitsunium/sdk/framework/model/internal/core.StorePrivacyMessage, declared as:

type StorePrivacy struct {
	// Subject is the JSON pointer of the field that says whom each record is
	// about: "/email". Empty when the entity has no subject field.
	Subject         string                `json:"subject,omitempty"`
	// Purpose is why the store keeps its records, as app.Purpose says it.
	Purpose         string                `json:"purpose,omitempty"`
	// Erase says when kit clears a record's personal data; Delete when it
	// removes the record.
	Erase           *RetentionSpec        `json:"erase,omitempty"`
	Delete          *RetentionSpec        `json:"delete,omitempty"`
	// ByProduct is set when the product keeps the store's retention itself
	// (app.RetentionByProduct): kit runs none — Erase and Delete are then
	// absent — and asks for neither a retention nor a subject.
	ByProduct       *ProductRetentionSpec `json:"byProduct,omitempty"`
	// HeldUntil holds each record until an instant it carries: the law's
	// own retention (app.HeldUntil).
	HeldUntil       *HeldUntilSpec        `json:"heldUntil,omitempty"`
	// Anonymise locates the function that says what an erased record keeps,
	// generalised (app.Anonymise).
	Anonymise       *SourceMessage        `json:"anonymise,omitempty"`
	// DeleteOnErasure: a person's erasure deletes the record instead of
	// clearing it (app.DeleteOnErasure).
	DeleteOnErasure bool                  `json:"deleteOnErasure,omitempty"`
	// Held is how many records a hold keeps, on a runtime graph.
	Held            *int                  `json:"held,omitempty"`
	// Due is when the next record is due to be erased or deleted, on a
	// runtime graph; absent when none is.
	Due             *time.Time            `json:"due,omitempty"`
	// Erased and Deleted count what this run erased and deleted, on a
	// runtime graph.
	Erased          *int                  `json:"erased,omitempty"`
	Deleted         *int                  `json:"deleted,omitempty"`
}

type StoreTrash

StoreTrash is a page of a store's trash as the Studio lists it (GET /_app/api/trash), in key order.

type StoreTrash = core.StoreTrashMessage

StoreTrash is an alias of github.com/kitsunium/sdk/framework/model/internal/core.StoreTrashMessage, declared as:

type StoreTrash struct {
	// Store is the store's node ID.
	Store   string                 `json:"store"`
	Total   int                    `json:"total"`
	Records []TrashedRecordMessage `json:"records"`
	Next    int                    `json:"next,omitempty"`
}

type SubscriptionInfo

SubscriptionInfo describes a subscription — or a watch (ADR 0008), a subscription whose deliveries come from stores instead of a topic.

type SubscriptionInfo = core.SubscriptionSpec

SubscriptionInfo is an alias of github.com/kitsunium/sdk/framework/model/internal/core.SubscriptionSpec, declared as:

type SubscriptionInfo struct {
	// Topic is the node ID of the consumed topic; empty for a watch.
	Topic         string   `json:"topic"`
	// Mark is what a watch hears the writes of: "personal", "special" or
	// "moderated", ADR 0006's marks. Empty for a subscription.
	Mark          string   `json:"mark,omitempty"`
	// OwnStores: the watch hears its own module's stores too — the
	// product's own, for a watch of the product's (app.OwnStores) —, never
	// the writes its own handler makes.
	OwnStores     bool     `json:"ownStores,omitempty"`
	// Stores are the node IDs of the stores that feed a watch, sorted: those
	// whose entity holds a field with its mark, but its own module's — the
	// product's own, for a watch of the product's — unless OwnStores. Each
	// draws a declared delivers edge to it.
	Stores        []string `json:"stores,omitempty"`
	// MaxDeliveries is how many attempts a message gets before it is
	// dead-lettered.
	MaxDeliveries int      `json:"maxDeliveries,omitempty"`
	// Parallelism is how many messages are handled concurrently.
	Parallelism   int      `json:"parallelism,omitempty"`
	// DeadLetters is how many messages were abandoned, on a runtime graph.
	DeadLetters   *int     `json:"deadLetters,omitempty"`
}

type System

System is a software system outside the product. Nodes are the product's nodes that talk to it; Technology says what it runs on.

type System = core.SystemMessage

System is an alias of github.com/kitsunium/sdk/framework/model/internal/core.SystemMessage, declared as:

type System struct {
	// ID is unique in the architecture: "system:smtp".
	ID         string   `json:"id"`
	// Name is what the diagram prints: "SMTP relay".
	Name       string   `json:"name"`
	// Doc says what it is to the product.
	Doc        string   `json:"doc,omitempty"`
	// Technology names how it is reached: "SMTP · STARTTLS".
	Technology string   `json:"technology,omitempty"`
	// Location says where, when it is known and not secret: "smtp.example.com:587".
	Location   string   `json:"location,omitempty"`
	// Nodes are the nodes of the product that talk to it.
	Nodes      []string `json:"nodes,omitempty"`
}

type TopicInfo

TopicInfo describes a topic. It carries the message's schema; its subscriptions are the nodes it delivers to.

type TopicInfo = core.TopicSpec

TopicInfo is an alias of github.com/kitsunium/sdk/framework/model/internal/core.TopicSpec, declared as:

type TopicInfo struct {
	// Message is the published type.
	Message  *SchemaMessage `json:"message,omitempty"`
	// Delivery is the guarantee: "at-least-once".
	Delivery string         `json:"delivery"`
	// Broker is "memory", "file" or "sql": where a subscription of the topic's
	// own service waits — "sql" on the database that keeps it.
	Broker   string         `json:"broker,omitempty"`
}

type Trace

Trace is the spans sharing one trace ID, root first. The root span is the one with no parent in the trace; the others follow it.

type Trace = core.TraceMessage

Trace is an alias of github.com/kitsunium/sdk/framework/model/internal/core.TraceMessage, declared as:

type Trace struct {
	// TraceID identifies the trace.
	TraceID string        `json:"traceId"`
	// Root is the node of the root span.
	Root    string        `json:"root"`
	// Name is the root span's name.
	Name    string        `json:"name"`
	// Start is when the root began.
	Start   time.Time     `json:"start"`
	// Ms spans from the first start to the last end.
	Ms      float64       `json:"ms"`
	// Status is StatusError when any span failed.
	Status  string        `json:"status"`
	// Spans are in start order.
	Spans   []SpanMessage `json:"spans"`
}

type TransitionEvent

TransitionEvent is one workflow instance moving between states. It names the workflow, the entity, the event and the states it went from and to.

type TransitionEvent = core.TransitionEvent

TransitionEvent is an alias of github.com/kitsunium/sdk/framework/model/internal/core.TransitionEvent, declared as:

type TransitionEvent struct {
	// Workflow is the workflow node ID.
	Workflow string `json:"workflow"`
	// Instance is the entity key.
	Instance string `json:"instance"`
	// Event is the transition's event name.
	Event    string `json:"event"`
	// From is the state left; empty on creation.
	From     string `json:"from"`
	// To is the state entered.
	To       string `json:"to"`
	// Trigger is one of the Trigger constants.
	Trigger  string `json:"trigger"`
	// Caller is the node that fired it, when code did.
	Caller   string `json:"caller,omitempty"`
}

type TransitionInfo

TransitionInfo is one arrow of a workflow. It names the event that fires it and the states it goes from and to.

type TransitionInfo = core.TransitionSpec

TransitionInfo is an alias of github.com/kitsunium/sdk/framework/model/internal/core.TransitionSpec, declared as:

type TransitionInfo struct {
	// Event names the transition. Timer and guard transitions have one too.
	Event   string         `json:"event"`
	// From is the source state.
	From    string         `json:"from"`
	// To is the target state.
	To      string         `json:"to"`
	// Trigger is [TriggerEvent], [TriggerTimer] or [TriggerGuard].
	Trigger string         `json:"trigger"`
	// After is the delay of a timer transition, as a Go duration string.
	After   string         `json:"after,omitempty"`
	// Setting names the setting of the service the delay is read from, when
	// the environment gives it: "archive-after".
	Setting string         `json:"setting,omitempty"`
	// At locates the function that says when a timer transition declared at
	// an instant is due — a due date, a deadline the entity carries.
	At      *SourceMessage `json:"at,omitempty"`
	// Guard locates the condition of a guard transition.
	Guard   *SourceMessage `json:"guard,omitempty"`
	// Source is where the transition is declared.
	Source  *SourceMessage `json:"source,omitempty"`
	// Callers are the node IDs found to fire this event.
	Callers []string       `json:"callers,omitempty"`
}

type TrashedRecord

TrashedRecord is one record in a store's trash as the Studio lists it (GET /_app/api/trash): its key, when the product deleted it and when kit purges it — never its value.

type TrashedRecord = core.TrashedRecordMessage

TrashedRecord is an alias of github.com/kitsunium/sdk/framework/model/internal/core.TrashedRecordMessage, declared as:

type TrashedRecord struct {
	// Key is the record's key; empty when Hidden.
	Key     string    `json:"key,omitempty"`
	// Hidden says the key reads a personal, special or secret member, or
	// the record no longer opens to tell: the Studio is not given it.
	Hidden  bool      `json:"hidden,omitempty"`
	// At is when the product deleted it.
	At      time.Time `json:"at"`
	// PurgeAt is when kit purges it: its trash's length after At, or its
	// retention's instant when that comes first.
	PurgeAt time.Time `json:"purgeAt"`
}

type WakeSource

WakeSource is one thing that wakes a declared loop. Kind says whether a topic, a period (Every) or a function wakes the loop.

type WakeSource = core.WakeSourceMessage

WakeSource is an alias of github.com/kitsunium/sdk/framework/model/internal/core.WakeSourceMessage, declared as:

type WakeSource struct {
	// Kind is one of the Wake constants.
	Kind  string         `json:"kind"`
	// Every is the period of an interval wake, as a Go duration.
	Every string         `json:"every,omitempty"`
	// Topic is the node ID of a topic wake.
	Topic string         `json:"topic,omitempty"`
	// Func locates the function computing a deadline wake.
	Func  *SourceMessage `json:"func,omitempty"`
}

type WorkflowInfo

WorkflowInfo describes a state machine bound to a store. It carries the states and the transitions between them, and the store it lives in.

type WorkflowInfo = core.WorkflowSpec

WorkflowInfo is an alias of github.com/kitsunium/sdk/framework/model/internal/core.WorkflowSpec, declared as:

type WorkflowInfo struct {
	// Store is the node ID of the store holding the instances.
	Store       string           `json:"store"`
	// Field is the wire name of the entity field holding the state, when the
	// state function points at a field of the entity.
	Field       string           `json:"field,omitempty"`
	// Initial is the state a new instance enters.
	Initial     string           `json:"initial"`
	// States are in declaration order.
	States      []StateSpec      `json:"states"`
	// Transitions are in declaration order.
	Transitions []TransitionSpec `json:"transitions"`
}

Generated from docs/api by tools/genindex.

Documentation

Overview

Package model is the Product Graph: the one data shape every part of the framework agrees on. The runtime serves it, a static analyzer produces it, a CLI prints it, a Studio draws it, and an AI agent or an editor extension reads it.

A graph is a projection: of the code for what runs, and — since the platform's ADR 0010 — of the design (a product's design/ directory) for what its structure must be. The design, not the graph, is authoritative on structure; the graph shows what the code is and where it differs from the design. Every node says where it was declared (Source) and every edge says how it is known: declared by construction (Edge.Declared), found in a handler body by a static analyzer (Edge.Static), or seen at runtime (Edge.Observed). A diagram that cannot say why an arrow exists is a drawing; this one can.

Identity

Every node has an ID, and the grammar of IDs is written here once — as patterns a schema generator can read (IDPattern, SegmentPattern, NamePattern) and as a parser (ParseID): 

todos                              a service
moderation.intake                  a module's service
todos/endpoint/Create              a node of a service
todos/endpoint/GET /todos/{id}     an endpoint named by its route
binary:statusline                  a binary
binary:statusline/role/daemon      one of its process roles
library:textwidth                  a library shared between components
external                           the world outside the product

The runtime, the analyzer, the design files and the generator derive names with the same functions (NodeID, QualifiedService, RoleID), so two sides never disagree about what a declaration is called.

A contract

The JSON shape is a contract: Version is bumped on any change an older reader would misread.

Index

Constants

View Source 
const (
	ContainerProcess string = core.ContainerProcess // the Go binary: every service, one process
	ContainerSPA     string = core.ContainerSPA     // a frontend: served by the process, run by a browser
	ContainerVolume  string = core.ContainerVolume  // the data directory: store files, queue files
	ContainerMemory  string = core.ContainerMemory  // data kept in the process's memory only
	// ContainerDatabase is a database the app declares (app.Database):
	// "container:database:<name>", drawn as a cylinder.
	ContainerDatabase string = core.ContainerDatabase
)

Container kinds.

View Source 
const (
	ServesHealth string = core.ServesHealth // the liveness and readiness probes
	ServesStudio string = core.ServesStudio // the Studio and its API, in dev
	ServesHTTP   string = core.ServesHTTP   // the product's own HTTP entry points
)

What a port serves.

View Source 
const (
	BlockIf     string = core.BlockIf     // an if's first branch
	BlockElseIf string = core.BlockElseIf // an if's else-if branch
	BlockElse   string = core.BlockElse   // an if's last branch
	BlockCase   string = core.BlockCase   // a switch's or a select's case
	BlockLoop   string = core.BlockLoop   // a for or range loop's body
	BlockGo     string = core.BlockGo     // a go statement: runs beside the caller
	BlockDefer  string = core.BlockDefer  // a defer statement: runs when the function returns
	BlockFunc   string = core.BlockFunc   // a function literal: runs when it is called
	// BlockTransaction is the function an app.Transact runs: its steps run in
	// one transaction, and the effects they make leave at its commit.
	BlockTransaction string = core.BlockTransaction
)

The kinds of CodeBlock.

View Source 
const (
	RoleInbound  string = core.RoleInbound
	RoleOutbound string = core.RoleOutbound
	RoleStorage  string = core.RoleStorage
)

The roles of a connector, against the process boundary.

View Source 
const (
	ConnectorHTTP  string = core.ConnectorHTTP
	ConnectorMail  string = core.ConnectorMail
	ConnectorStore string = core.ConnectorStore
	ConnectorQueue string = core.ConnectorQueue
	// ConnectorDatabase is brought by a store a database keeps (ADR 0004):
	// app.Database declares the database, an engine module reaches it.
	ConnectorDatabase string = core.ConnectorDatabase
)

The connectors kit ships.

View Source 
const (
	EnginePostgres string = core.EnginePostgres
	EngineMySQL    string = core.EngineMySQL
	EngineSQLite   string = core.EngineSQLite
)

The engines a database runs on (ADR 0004): one module each in kit's repository, the only code that imports its driver.

View Source 
const (
	MailQueued   string = core.MailQueued   // in the outbox, not yet handed to the transport
	MailSent     string = core.MailSent     // the transport accepted it (capture: kept for the mailbox)
	MailRetrying string = core.MailRetrying // the last attempt failed; another is scheduled
	MailDead     string = core.MailDead     // given up, and kept as a dead letter: GivenUp says why
)

Mail statuses.

View Source 
const (
	MailRejected  string = core.MailRejected  // the receiving server refused it for good: an SMTP 5xx reply
	MailExpired   string = core.MailExpired   // an attempt failed once the mail was older than its mailer's max-age
	MailExhausted string = core.MailExhausted // its last attempt failed
)

Why a dead mail was given up.

View Source 
const (
	// SegmentPattern is a service, module, binary, role or library name.
	SegmentPattern string = core.SegmentPattern
	// NamePattern is a node's name within its service and kind.
	NamePattern string = core.NamePattern
	// RoutePattern is the name of an endpoint declared without one: its
	// route, "GET /tasks/{id}".
	RoutePattern string = core.RoutePattern
	// ContractPattern is the versioned contract an [EdgeContracts] edge
	// carries: "render/v1".
	ContractPattern string = core.ContractPattern
	// BinaryScope prefixes the ID of a binary and of its roles.
	BinaryScope string = core.BinaryScope
	// LibraryScope prefixes the ID of a library.
	LibraryScope string = core.LibraryScope
)

The grammar of every ID a graph carries, written once. The runtime, the analyzer, the design files' JSON Schema and the Studio all read it from here: a second copy is how two sides come to derive different names for the same declaration (invariant 1 of the platform's kit). 

id       = "external"
         | service
         | service "/" kind "/" name
         | "binary:" segment
         | "binary:" segment "/role/" segment
         | "library:" segment
service  = [ segment "." ] segment        ; "<module>.<service>"
segment  = [a-z][a-z0-9-]{0,62}
name     = [A-Za-z][A-Za-z0-9_.-]{0,62}
         | method " " path                 ; an endpoint named by its route

A module's service named like the module is the module's name alone (QualifiedService); every other service of a module is qualified.

View Source 
const (
	// ExposePublic endpoints are routed on the product's HTTP listener.
	ExposePublic string = core.ExposePublic
	// ExposePrivate endpoints have no route: the implementation of a port
	// (Service.Implement), reached in process through its port. A graph kit
	// made before its operations were internal by default also marks so an
	// endpoint it kept off the listener.
	ExposePrivate string = core.ExposePrivate
)

Exposure says who may reach an endpoint.

View Source 
const (
	// AccessAnyone is app.Anyone(): whoever reaches the route may run the
	// operation.
	AccessAnyone string = core.AccessAnyone
	// AccessAnyUser is app.AnyUser(): any signed-in user may run it — the
	// operation asks for one.
	AccessAnyUser string = core.AccessAnyUser
)

How an exposure says it is open on purpose, when its operation declares no permission and no rule (EndpointInfo.Access).

View Source 
const (
	// AuthRequired endpoints run only for an authenticated caller; the others
	// are answered 401 before the handler runs.
	AuthRequired string = core.AuthRequired
	// AuthOptional endpoints run the auth handler when credentials are
	// present, and serve anonymous callers too.
	AuthOptional string = core.AuthOptional
)

Authentication an endpoint asks for.

View Source 
const (
	// TriggerEvent is a transition fired by code, naming an event.
	TriggerEvent string = core.TriggerEvent
	// TriggerTimer is a transition fired after a duration in a state, or at
	// an instant the entity carries.
	TriggerTimer string = core.TriggerTimer
	// TriggerGuard is a transition fired when a condition on the entity
	// holds, checked each time the entity is written.
	TriggerGuard string = core.TriggerGuard
	// TriggerCreate is the entry of a new instance into the initial state.
	TriggerCreate string = core.TriggerCreate
)

Transition triggers.

View Source 
const (
	// ViaBind is the app's app.Bind.
	ViaBind string = core.ViaBind
	// ViaImplement is the one Service.Implement among the mounted services.
	ViaImplement string = core.ViaImplement
	// ViaFallback is the port's own app.Fallback.
	ViaFallback string = core.ViaFallback
	// ViaReplace is a test's app.Replace: a function answers in place of
	// whatever the port would call, and nothing is bound.
	ViaReplace string = core.ViaReplace
)

How the start chose what a port calls: app.Bind, else the one Service.Implement among the services the app mounts, else the port's fallback — or a test replaced the port.

View Source 
const (
	// ModeSync is handled on its caller's goroutine: Dispatch returns the
	// handler's result.
	ModeSync string = core.ModeSync
	// ModeQueued is sent to the background (app.Queued): Dispatch returns
	// once the command's own queue accepted it, and a consumer handles it,
	// retried and dead-lettered.
	ModeQueued string = core.ModeQueued
)

How a command is handled.

View Source 
const (
	// TransportSMTP delivers to an SMTP relay.
	TransportSMTP string = core.TransportSMTP
	// TransportCapture keeps every message for the Studio's mailbox and
	// delivers nothing: the transport of dev and tests.
	TransportCapture string = core.TransportCapture
)

Mail transports.

View Source 
const (
	// SecretProvided is given by the operator: an SMTP URL, an API token.
	SecretProvided string = core.SecretProvided
	// SecretGenerated is made by kit and rotated on a schedule: a signing or
	// sealing key.
	SecretGenerated string = core.SecretGenerated
)

How a secret is made.

View Source 
const (
	// SecretFromEnv is the environment: the variable, or the file its _FILE
	// form names.
	SecretFromEnv string = core.SecretFromEnv
	// SecretFromFile is the framework's encrypted file store: <PRODUCT>_SECRETS=file:<dir>,
	// or the data directory's .secrets in dev.
	SecretFromFile string = core.SecretFromFile
	// SecretFromMemory is a store in the process's memory: a test, or
	// <PRODUCT>_SECRETS=memory. A generated secret is made again at every start.
	SecretFromMemory string = core.SecretFromMemory
	// SecretFromStore is a store the product's code gave kit.
	SecretFromStore string = core.SecretFromStore
)

Where a running app found a secret.

View Source 
const (
	// LoopDeclared is Service.Loop: kit owns the wait — the wake sources are
	// data, so the diagram draws them — and the product owns the work.
	LoopDeclared string = core.LoopDeclared
	// LoopGoroutine is Service.Go: the product wrote the whole loop; kit
	// starts it, stops it, restarts it after a failure, and reads its select
	// statements to draw what it waits on.
	LoopGoroutine string = core.LoopGoroutine
)

Loop styles.

View Source 
const (
	WakeInterval string = core.WakeInterval // a fixed period
	WakeDeadline string = core.WakeDeadline // a time the product computes after every run
	WakeTopic    string = core.WakeTopic    // any publish on a topic
	WakeStart    string = core.WakeStart    // once, when the app starts
	WakeManual   string = core.WakeManual   // Loop.Nudge, or the Studio
	WakeChange   string = core.WakeChange   // a write of the store a workflow runs over, or of one a watch hears
)

Wake source kinds of a declared loop, and why a loop of kit's ran.

View Source 
const (
	SelectTimer   string = core.SelectTimer   // a timer, ticker or time.After channel
	SelectDone    string = core.SelectDone    // ctx.Done(): the loop's way out
	SelectReceive string = core.SelectReceive // any other receive
	SelectSend    string = core.SelectSend    // a send
	SelectDefault string = core.SelectDefault // the default case: the select never blocks
)

Select case kinds.

View Source 
const (
	// ClassPublic holds nothing personal and nothing secret: the question
	// was asked.
	ClassPublic string = core.ClassPublic
	// ClassPersonal holds data about an identifiable person: a name, an
	// address, a message a person wrote.
	ClassPersonal string = core.ClassPersonal
	// ClassSpecial holds the special categories of GDPR art. 9(1), or
	// criminal convictions (art. 10).
	ClassSpecial string = core.ClassSpecial
	// ClassSecret holds a credential: a password's hash, a token's digest.
	ClassSecret string = core.ClassSecret
)

What a field holds: the classes of an app tag (ADR 0006).

View Source 
const (
	// ProfileServer serves HTTP until it is stopped: the platform's kit
	// product, and the only profile that opens a TCP listener.
	ProfileServer string = core.ProfileServer
	// ProfileCLI parses its arguments, runs once and exits with a typed
	// status. It starts no listener and no loop outlives it.
	ProfileCLI string = core.ProfileCLI
	// ProfileDaemon runs until it is stopped, or until it has been idle for
	// its declared time, and serves no HTTP: it answers on its listeners —
	// a private socket, a pipe — and runs its loops.
	ProfileDaemon string = core.ProfileDaemon
)

Process profiles: what a role does with its process.

View Source 
const (
	// NetworkUnix is a Unix-domain socket, private to its owner.
	NetworkUnix string = core.NetworkUnix
	// NetworkPipe is a Windows named pipe, its DACL granting its owner only.
	NetworkPipe string = core.NetworkPipe
	// NetworkLocal is NetworkUnix where there is one, NetworkPipe on
	// Windows: what a product declares when it does not care which.
	NetworkLocal string = core.NetworkLocal
)

Listener networks.

View Source 
const (
	// RetentionOn erases and deletes what is due: the default.
	RetentionOn string = core.RetentionOn
	// RetentionDryRun journals what the retention would do and changes
	// nothing: how a new retention is deployed over old data.
	RetentionDryRun string = core.RetentionDryRun
	// RetentionOff runs no retention, warned of at every start outside dev.
	RetentionOff string = core.RetentionOff
)

The modes of <PRODUCT>_RETENTION.

View Source 
const (
	GapPurpose   string = core.GapPurpose   // no app.Purpose
	GapRetention string = core.GapRetention // no retention, kit's or the product's: its personal data is kept forever
	GapSubject   string = core.GapSubject   // no subject field: no person can have their records
)

The gaps a register lists for a store that keeps personal data.

View Source 
const (
	// MeasureRedacted: the Studio, the spans and the logs never show a
	// personal, special or secret value.
	MeasureRedacted string = core.MeasureRedacted
	// MeasureHolds: a legal hold stops erasure and deletion.
	MeasureHolds string = core.MeasureHolds
	// MeasureJournal: every export, erasure, deletion and hold is journaled,
	// each entry chained to the previous one by SHA-256.
	MeasureJournal string = core.MeasureJournal
	// MeasureNotSealed: the store's classified members are in clear: it is
	// kept in memory, where nothing is at rest, or its members are plain.
	MeasureNotSealed string = core.MeasureNotSealed
	// MeasureSealed: its classified members are sealed at rest, AES-256-GCM
	// under per-subject data keys a person's erasure destroys (ADR 0006 §4).
	MeasureSealed string = core.MeasureSealed
)

The security measures a register lists (point g).

View Source 
const (
	JournalExport      string = core.JournalExport      // a person's records exported
	JournalRead        string = core.JournalRead        // a record read by a module, through app.Records
	JournalList        string = core.JournalList        // a store's keys listed by a module that watches it, through app.Records
	JournalErase       string = core.JournalErase       // a record's personal data cleared
	JournalDelete      string = core.JournalDelete      // a record removed
	JournalEraseFields string = core.JournalEraseFields // some fields of a record cleared, by a module
	JournalHold        string = core.JournalHold        // a hold placed on a record
	JournalRelease     string = core.JournalRelease     // a hold lifted
	JournalShred       string = core.JournalShred       // a subject's data key destroyed (ADR 0006, step 3)
	JournalContinue    string = core.JournalContinue    // a journal opened after the one before it closed, naming its last hash (ADR 0180 step 5c)
)

The operations of the privacy journal.

View Source 
const (
	ProfileCPU  string = core.ProfileCPU  // where CPU time went, sampled for a duration
	ProfileHeap string = core.ProfileHeap // where the live heap was allocated
)

Profile kinds.

View Source 
const (
	PhaseStarting string = core.PhaseStarting
	PhaseServing  string = core.PhaseServing
	PhaseDraining string = core.PhaseDraining
	PhaseStopped  string = core.PhaseStopped
	PhaseFailed   string = core.PhaseFailed
)

Process phases, in the order a process goes through them.

View Source 
const (
	// DatabaseUnset: no URL, in dev. Its stores stay in the data directory
	// and nothing is opened.
	DatabaseUnset string = core.DatabaseUnset
	// DatabaseMemory: the app keeps its data in memory (app.InMemory):
	// nothing is opened, no URL is read.
	DatabaseMemory string = core.DatabaseMemory
	// DatabaseOpen: the pool is open, its migrations ran, it answered its
	// check at start.
	DatabaseOpen string = core.DatabaseOpen
	// DatabaseFailed: the start could not open it, migrate it or reach it.
	DatabaseFailed string = core.DatabaseFailed
	// DatabaseClosed: not opened yet, or closed by the stop.
	DatabaseClosed string = core.DatabaseClosed
)

Database states.

View Source 
const (
	// ExportOff: the export sends nothing — no endpoint and no sender of the
	// product's, a CLI command, or a process not started.
	ExportOff string = core.ExportOff
	// ExportRunning: the export's loop sends.
	ExportRunning string = core.ExportRunning
	// ExportStopped: its loop ended while the process runs — a queue's
	// storage failed —: nothing is sent until the next start.
	ExportStopped string = core.ExportStopped
)

OTLP export states.

View Source 
const (
	SettingEnv     string = core.SettingEnv     // an environment variable
	SettingOption  string = core.SettingOption  // the product's code: an AppOption
	SettingDefault string = core.SettingDefault // kit's default for the environment
	SettingStore   string = core.SettingStore   // the environment's secret store (a secret)
	SettingAppDev  string = core.SettingAppDev  // kit dev set the variable, for this launch
	SettingFile    string = core.SettingFile    // a configuration file of the product (Detail)
)

Where a setting's value comes from.

View Source 
const (
	VarEnv          string = core.VarEnv
	VarAddr         string = core.VarAddr
	VarDataDir      string = core.VarDataDir
	VarStudio       string = core.VarStudio
	VarStudioRemote string = core.VarStudioRemote
	VarAnalyze      string = core.VarAnalyze
	VarTrustProxy   string = core.VarTrustProxy
	VarAllowedHosts string = core.VarAllowedHosts
	VarLogLevel     string = core.VarLogLevel
	VarSMTPURL      string = core.VarSMTPURL
	// VarRetention sets what the stores' retention loops do: on, dry-run
	// or off (ADR 0006).
	VarRetention string = core.VarRetention
	// VarDevForced is how kit dev tells the product which of the variables
	// above it set itself for this launch: their origin is kit dev.
	VarDevForced string = core.VarDevForced
)

The settings the framework reads, by the variable that sets each. The framework's own are named under the product's prefix — its name upper-cased, every other character an underscore —, so a constant holds the name after it: VarDataDir is TODO_DATA_DIR for the product "todo" (ADR 0180 §3). VarStudio, VarStudioRemote, VarAnalyze and VarDevForced are the tool's, set by it and read whole by the Studio subsystem alone.

View Source 
const (
	BootConfig       string = core.BootConfig       // the environment and the options, read
	BootDeclarations string = core.BootDeclarations // what the services declare, checked
	BootMount        string = core.BootMount        // the services bound to the app
	BootRoutes       string = core.BootRoutes       // the routes of endpoints and frontends
	BootData         string = core.BootData         // the data directory, opened
	BootHandler      string = core.BootHandler      // health, the Studio, protection, observation
	BootComponents   string = core.BootComponents   // the lifecycle components, started in order
	BootServing      string = core.BootServing      // ready: the phase is serving
)

Boot steps, in the order kit takes them.

View Source 
const (
	ComponentPending  string = core.ComponentPending
	ComponentStarting string = core.ComponentStarting
	ComponentUp       string = core.ComponentUp
	ComponentStopping string = core.ComponentStopping
	ComponentDown     string = core.ComponentDown
	ComponentFailed   string = core.ComponentFailed
)

Component states.

View Source 
const (
	LoopJob       string = core.LoopJob       // a job, fired by the scheduler
	LoopTimer     string = core.LoopTimer     // a workflow's own loop: its timers and guards, when due
	LoopConsumer  string = core.LoopConsumer  // a subscription's consumer, a queued command's, or a mailer's outbox
	LoopHTTP      string = core.LoopHTTP      // the HTTP server's accept loop
	LoopScheduler string = core.LoopScheduler // the scheduler's own loop, which fires the jobs
	LoopWake      string = core.LoopWake      // a declared loop's wake cycle (Service.Loop)
	LoopRoutine   string = core.LoopRoutine   // a hand-written loop (Service.Go)
	LoopRotation  string = core.LoopRotation  // a generated secret's rotation, on its schedule
	LoopRetention string = core.LoopRetention // a store's retention: erases and deletes what is due (ADR 0006)
)

Loop kinds.

View Source 
const (
	// ProvenanceLibrary loops are written by a library: net/http's accept
	// loop, the SDK scheduler, the SDK queue consumer.
	ProvenanceLibrary string = core.ProvenanceLibrary
	// ProvenanceApp loops are written by the framework for a declaration: a workflow's
	// sweep, a declared loop's wake cycle.
	ProvenanceApp string = core.ProvenanceApp
	// ProvenanceProduct loops are written by hand in the product: Service.Go.
	ProvenanceProduct string = core.ProvenanceProduct
)

Loop provenances: who wrote the code that loops.

View Source 
const (
	LoopWaiting    string = core.LoopWaiting    // blocked until its next wake
	LoopRunning    string = core.LoopRunning    // doing a run
	LoopRestarting string = core.LoopRestarting // failed, waiting out its backoff
	LoopStopped    string = core.LoopStopped
)

Loop states.

View Source 
const (
	OpRequest     string = core.OpRequest     // an HTTP request served by an endpoint
	OpCall        string = core.OpCall        // an in-process call of an endpoint, or of a port
	OpRead        string = core.OpRead        // a store read
	OpWrite       string = core.OpWrite       // a store write
	OpPublish     string = core.OpPublish     // a topic publish
	OpDeliver     string = core.OpDeliver     // a subscription handling one message
	OpTransition  string = core.OpTransition  // a workflow transition
	OpRun         string = core.OpRun         // a job run, a loop run
	OpAuth        string = core.OpAuth        // the auth handler, in front of an endpoint
	OpSend        string = core.OpSend        // a mail put in the outbox
	OpDeliverMail string = core.OpDeliverMail // the outbox handing one mail to the transport
	OpSecret      string = core.OpSecret      // a secret's value or keys used: Value, Seal, Open, Sign, Verify
	OpDispatch    string = core.OpDispatch    // a command dispatched: its run, or its queuing for a queued one
	OpAsk         string = core.OpAsk         // a query asked
	OpHandle      string = core.OpHandle      // a queued command handled by its consumer, in the dispatcher's trace
	OpConnect     string = core.OpConnect     // a connection a listener accepted, handled until it closes
	OpCLI         string = core.OpCLI         // a short command-line command, run once
	// OpTransaction is a unit of work (app.Transact, a command's, a
	// workflow's transition): its attrs say the database it belongs to —
	// "database", and "backend" as a store says it —, its "outcome", the
	// effects it held ("effects"), and "savepoint" for one nested in
	// another.
	OpTransaction string = core.OpTransaction
)

Span operations.

View Source 
const (
	// OutcomeCommit is a transaction that committed: its effects left.
	OutcomeCommit string = core.OutcomeCommit
	// OutcomeRollback is a transaction whose writes were undone: its effects
	// were dropped.
	OutcomeRollback string = core.OutcomeRollback
)

The outcomes of a transaction, as its span's "outcome" attribute says them.

View Source 
const (
	StatusOK    string = core.StatusOK
	StatusError string = core.StatusError
)

Span statuses.

View Source 
const (
	// CodeInvalidID identifies an ID the grammar of [IDPattern] does not match.
	CodeInvalidID errs.Code = core.CodeInvalidID // 0.4.1.1
)
View Source 
const (
	// ExternalID is the id of the node standing for the outside world.
	ExternalID string = core.ExternalID
)
View Source 
const MaxTableLen int = core.MaxTableLen

MaxTableLen is the longest table name a store on a database takes, in bytes: the SDK's document store over SQL keeps its index rows in the table named after it with "___ix", within PostgreSQL's 63.

View Source 
const (
	// MockReplace is the one mode a [Mock] has: a test's app.Replace, a typed
	// function run in place of an operation's handler — or of what a port calls —
	// while the rest of its pipeline still runs. The Studio sets none (D13): it
	// shows the application, it does not act on it, so the respond, fail and
	// delay modes of the platform's kit have no representation here.
	MockReplace string = core.MockReplace
)
View Source 
const (
	// PortOwnerApp is the framework's own listener: the health probes, the Studio in
	// dev, and the product's HTTP when it declares any.
	PortOwnerApp string = core.PortOwnerApp
)
View Source 
const SealedPlaceholder string = core.SealedPlaceholder

SealedPlaceholder is what the Studio receives in place of a value kit keeps sealed at rest — a record's member in the data browser, a former value —: never the value, nor its box (ADR 0006 §9). A value it opens and may not show is "[redacted]".

View Source 
const (
	// Version is the schema version of every document in this package.
	//
	// Version 2 adds the auth, mailer and loop kinds, the sends and wakes edges,
	// the code level of every node ([CodeInfo]), the C4 context and containers
	// ([Architecture]) and the daemon's own machinery ([Runtime]).
	//
	// Version 3 adds the secret kind ([SecretInfo]), the uses edge, the secret
	// span operation, the rotation loop and the store origin of a setting.
	//
	// Version 4 is the one bump the decisions of issue #17 share. It adds the
	// port kind ([PortInfo]) and its binding, a declared edge from the port to
	// what it calls; the endpoint that implements a port
	// ([EndpointInfo].Implements), which has no method and no path; and the
	// replace mock mode ([MockReplace]). ADR 0004 adds the databases: the store's
	// database ([StoreInfo].Database), the database container, the database
	// connector and its adapters, [Runtime].Databases and [Setting].Database.
	// ADR 0008 adds the modules the app mounts ([Graph].Modules), the module of a
	// node ([Node].Module) and the Go module of a position outside the product's
	// ([Source].GoModule); and the watch, a subscription fed by stores: its mark
	// and the stores that feed it ([SubscriptionInfo].Mark,
	// [SubscriptionInfo].Stores), each drawing a declared delivers edge to it.
	// ADR 0005 adds the command and query kinds ([CommandInfo], [QueryInfo]),
	// the dispatches and asks edges, the endpoint that exposes one
	// ([EndpointInfo].Exposes), the read model ([StoreInfo].ReadModel), the
	// dispatch, ask and handle span operations and the dispatch and ask
	// controls.
	//
	// Version 5 is the first the SDK's framework publishes (ADR 0147). It
	// adds what a product is made of beyond its services: the binary
	// ([KindBinary]) and its process roles ([KindRole]), the short CLI command
	// ([KindCLI]), the listener that is not HTTP ([KindListener]), the library
	// shared between components ([KindLibrary]) and the presentation
	// ([KindPresentation]); the edge between two roles of a product, which
	// carries a versioned contract ([EdgeContracts], [Edge].Contract); and the
	// grammar every ID follows, written once ([ID], [ParseID]). It removes what
	// the Studio no longer does (D13): the respond, fail and delay mock modes,
	// the control event and its payload — a [Mock] is a test's replacement only.
	//
	// Version 6 renames the runtime framework (ADR 0180): its packages are
	// framework/app and framework/internal/app, so a source position the
	// document gives in the framework's code names those paths, and the
	// constants of the framework's own provenance, port owner and setting
	// origin are [ProvenanceApp], [PortOwnerApp] and [SettingAppDev]; since
	// ADR 0180's step 4 their values are "app" and "appdev", the build's
	// and the graph's version of the framework are their field "app", and
	// the variable a framework setting names carries the product's prefix.
	Version int = core.Version
)

Variables

View Source 
var IDPattern string = core.IDPattern

IDPattern is the whole grammar as one regular expression, anchored — the one the design files' JSON Schema publishes for an ID. Only an endpoint may be named by its route.

View Source 
var InvalidID *errs.Error = core.InvalidID

InvalidID is returned by ParseID for a string the ID grammar does not match. Its "part" field names what failed — the kind, the service name, the node name —, never the input.

Functions

func BinaryID 

func BinaryID(binary string) string

BinaryID is the ID of a binary.

func CompareSource 

func CompareSource(a, b Source) int

CompareSource orders sources by root, file, then line.

func EdgeID 

func EdgeID(from string, kind EdgeKind, to, label string) string

EdgeID builds the ID of an edge. The label is part of the identity: two transitions of one workflow fired from one endpoint are two edges.

func IsEngine 

func IsEngine(backend string) bool

IsEngine reports whether backend names an engine a database runs on.

func LibraryID 

func LibraryID(library string) string

LibraryID is the ID of a library.

func Mermaid 

func Mermaid(g *Graph) string

Mermaid renders the architecture of a graph as a Mermaid flowchart: one subgraph per service — a module's inside the module's own, ADR 0008 —, one arrow per edge. GitHub renders it in Markdown, which makes a product's README carry its own, always regenerable, diagram.

Each kind has its shape: an endpoint a box (marked "auth" when it asks for a user; an implementation of a port by its name), a store a cylinder, a topic a flag, a subscription a parallelogram (a watch, ADR 0008, marked with the mark it watches — its stores' arrows say where from), a workflow a hexagon, a job a stadium, the auth handler a trapezoid — a gate —, a mailer a subroutine box, a declared loop a circle, a hand-written loop a double circle, a port an inverted trapezoid — a socket, UML's required interface —, a command a parallelogram leaning back — a subscription's leans forward —, marked "queued" when it waits in its queue, and a query a rhombus, a question. An arrow is solid when it exists by construction or was observed, dotted when only the code says so — or when it is a port's binding to its own fallback, the default the app may replace, as the Studio draws it.

func ModulePrefix 

func ModulePrefix(name string) string

ModulePrefix is a module's default mount prefix: "/<name>/".

func NodeID 

func NodeID(service string, kind NodeKind, name string) string

NodeID builds the ID of a node declared in a service. A service's own ID is its name.

func QualifiedService 

func QualifiedService(module, service string) string

QualifiedService is the name a module gives a service it lists: the module's own name for the service named like it, "<module>.<service>" otherwise. The runtime and the analyzer both qualify with it.

func RoleID 

func RoleID(binary, role string) string

RoleID is the ID of one process role of a binary.

func ServiceOf 

func ServiceOf(id string) string

ServiceOf returns the service part of a node ID.

func SplitDoc 

func SplitDoc(text string) (string, map[string]string)

SplitDoc splits a description into its default text and its translations.

A product documents a building block once, in Go, in its default language; a paragraph that starts with a language tag and a colon — "fr: Le cycle de vie d'un compte…" — is the same description in that language, until the next tag or the end: 

// AccountLifecycle is the life of an account…
//
// fr: AccountLifecycle est la vie d'un compte…

It keeps Go's convention (the comment still starts with the name) and go doc prints both. Each text is joined into one line. A description whose only tagged paragraph is "en" uses it as the default.

func TableName 

func TableName(service, node, suffix string) string

TableName is the table a database keeps a kit table in (ADR 0004): the service's name — qualified, for a module's —, two underscores and the node's name, then suffix, '-' and '.' written '_', lower case — "moderation.intake"'s store "cases" is moderation_intake__cases. A name the rule cannot keep as it is — upper case, longer than MaxTableLen, three underscores in a row, SQLite's own prefix — is cut and ends with a digest of the whole, so it stays one table's. The runtime and the analyzer name tables with it.

func UnderPrefix 

func UnderPrefix(prefix, path string) string

UnderPrefix is a route declared at path, served under a module's mount prefix: "/reports" under "/moderation/" is "/moderation/reports", and under "/" it stays "/reports".

func ValidContract 

func ValidContract(s string) bool

ValidContract reports whether s names a versioned contract: "render/v1".

func ValidName 

func ValidName(s string) bool

ValidName reports whether s is a legal node name. An endpoint named by its route is legal as an ID but is not a name a declaration may give.

func ValidSegment 

func ValidSegment(s string) bool

ValidSegment reports whether s is a legal service, module, binary, role or library name.

Types

type Adapter 

type Adapter = core.AdapterMessage

Adapter is a module a connector plugs a product in through: an engine, imported by the product's main to reach a database, and the only code of the product that imports its driver.

type Analysis 

type Analysis = core.AnalysisResult

Analysis reports the status of static analysis. It says whether the analyzer ran, how long it took, and the error that stopped it.

type App 

type App = core.AppMessage

App identifies the product and the machine that described it. It names the module, the environment and the build the graph was taken from.

type Architecture 

type Architecture = core.ArchitectureMessage

Architecture is the product at the two outer levels of the C4 model.

Context (level 1) is the product as one box, the people who use it and the systems it depends on. Containers (level 2) is what the product is deployed as: the process, the frontend its browser runs, the volume its data lives on. Components (level 3) are the nodes, grouped by service; code (level 4) is each node's CodeInfo.

kit derives all of it from the declarations — a frontend implies a person with a browser, a mailer an SMTP relay, a data directory a volume, a database its own container — so it is exactly as true as the rest of the graph.

type AuthInfo 

type AuthInfo = core.AuthSpec

AuthInfo describes the app's authentication handler. Credentials says what it reads from a request; Endpoints are the ones behind it.

type BinaryInfo 

type BinaryInfo = core.BinarySpec

BinaryInfo is one executable the product ships: the Node.Binary of a KindBinary node, naming its roles.

type BootStep 

type BootStep = core.BootStepMessage

BootStep is one step of the start, as it ran. It carries when it began, how long it took and, when it failed, its error.

type Build 

type Build = core.BuildMessage

Build is what a binary was built from, at its three levels. Its three levels are the Go toolchain, the main module and the modules it depends on.

type CLIInfo 

type CLIInfo = core.CLISpec

CLIInfo is a short command-line command: the Node.CLI of a KindCLI node, the words that run it.

type Census 

type Census = core.CensusMessage

Census is a workflow's population per state. It counts the instances in each state when the census was taken.

type CodeBlock 

type CodeBlock = core.CodeBlockMessage

CodeBlock is a block of a function that decides whether, or how many times, the steps under it run.

type CodeEffect 

type CodeEffect = core.CodeEffectMessage

CodeEffect is one call on a building block, inside a function. It names the node it reaches and the edge kind that call draws.

type CodeFunc 

type CodeFunc = core.CodeFuncMessage

CodeFunc is one function of the module a node's code reaches. Its steps are listed in the order they run, under the blocks that guard them.

type CodeInfo 

type CodeInfo = core.CodeResult

CodeInfo is the code a node runs, as the static analysis read it: the fourth and innermost level of the C4 model. The entry is the function the node runs — an endpoint's handler, a subscription's, a loop's — and Funcs are the functions of the module it reaches, each with what it calls and what it does to other nodes.

type CodeStep 

type CodeStep = core.CodeStepMessage

CodeStep is one thing a function does: a call to another function of the module, a call on a building block, or a call into the SDK — under the innermost block that guards it.

type CodeUse 

type CodeUse = core.CodeUseMessage

CodeUse is one SDK function a node's code calls. Sites are where the node's code calls it, so a reader sees what it leans on.

type CommandInfo 

type CommandInfo = core.CommandSpec

CommandInfo describes a command: an operation that changes something. It carries its input and result schemas, its handler, its queue and who may dispatch it.

type Component 

type Component = core.ComponentMessage

Component is one lifecycle component: brought up in order, taken down in reverse.

type Connector 

type Connector = core.ConnectorMessage

Connector is something a product plugs into, as the product declares it: how it is reached, what it reaches out to, where it keeps its data. The Studio shows a connector's pages and widgets only when the product has one: a command-line tool has no requests to list, a service without a mailer no mailbox.

A connector says what the code declares, never what an environment supplies. The relay a mailer delivers through, the directory a store writes to, the address kit listens on are facts of the running environment — MailerInfo, StoreInfo, the Architecture and Runtime carry those. So a connector is a pure function of the nodes (ConnectorsOf), and never moves a graph's revision.

func ConnectorsOf 

func ConnectorsOf(nodes []Node) []Connector

ConnectorsOf derives the connectors a product uses from its nodes: an endpoint, a frontend or an auth handler means HTTP, a mailer mail, a store stores — and a database when one keeps it —, a topic, a subscription or a queued command queues. Sorted by ID.

type ConnectorInfo 

type ConnectorInfo = core.ConnectorSpec

ConnectorInfo is a connector kit can plug a product into, whether the product uses it or not: what it is, and the building blocks that bring it.

func ConnectorCatalog 

func ConnectorCatalog() []ConnectorInfo

ConnectorCatalog is every connector kit ships, sorted by ID: what a product may plug into.

type ConnectorKind 

type ConnectorKind = core.ConnectorKind

ConnectorKind groups connectors by what they are for. 

const (
	// ConnectorTransport is how the product is reached: HTTP.
	ConnectorTransport ConnectorKind = core.ConnectorTransport
	// ConnectorMessaging is what it sends and receives: mail, queues.
	ConnectorMessaging ConnectorKind = core.ConnectorMessaging
	// ConnectorData is where it keeps its data: stores, databases.
	ConnectorData ConnectorKind = core.ConnectorData
)

The kinds of connectors.

type Container 

type Container = core.ContainerMessage

Container is one runnable or storage unit of the product. Its ID starts with "container:"; Nodes are the nodes that live in it.

type Database 

type Database = core.DatabaseMessage

Database is one database the app declares (app.Database), as the running process found it. Its URL is never shown: where it was found, the engine, the address and the TLS mode are.

type DevBuild 

type DevBuild = core.DevBuildMessage

DevBuild is one build of `kit dev`: when, how long, and why. It lets the Studio say what changed and how long the reload took.

type Diagnostic 

type Diagnostic = core.DiagnosticMessage

Diagnostic is a problem found while building the graph. It names the node or the file it is about, and how serious it is.

type Edge 

type Edge = core.EdgeMessage

Edge is one relation, with the evidence for it. Declared, Static and Observed say whether construction, the code or the runtime knows it.

type EdgeKind 

type EdgeKind = core.EdgeKind

EdgeKind says how two nodes relate. It is a wire format — the graph's JSON and the Studio's TypeScript unions carry these names —, so it stays a string. 

const (
	// EdgeCalls targets an endpoint or a port. From a port, it is the port's
	// binding — what the port calls — and it is declared.
	EdgeCalls EdgeKind = core.EdgeCalls
	// EdgeReads targets a store the source reads from.
	EdgeReads EdgeKind = core.EdgeReads
	// EdgeWrites targets a store the source writes to.
	EdgeWrites EdgeKind = core.EdgeWrites
	// EdgePublishes targets a topic.
	EdgePublishes EdgeKind = core.EdgePublishes
	// EdgeDelivers goes from a topic to each of its subscriptions, and from a
	// store to each watch it feeds (ADR 0008). Declared.
	EdgeDelivers EdgeKind = core.EdgeDelivers
	// EdgeTransitions targets a workflow; Label carries the event.
	EdgeTransitions EdgeKind = core.EdgeTransitions
	// EdgePersists goes from a workflow to the store it lives in. Declared.
	EdgePersists EdgeKind = core.EdgePersists
	// EdgeSends targets a mailer: the source puts a message in its outbox.
	EdgeSends EdgeKind = core.EdgeSends
	// EdgeWakes goes from a topic to a declared loop it wakes. Declared.
	EdgeWakes EdgeKind = core.EdgeWakes
	// EdgeUses targets a secret whose value or keys the source uses.
	EdgeUses EdgeKind = core.EdgeUses
	// EdgeDispatches targets a command: the source dispatches it. From an
	// endpoint that exposes the command, or from a port bound to it, it is
	// declared.
	EdgeDispatches EdgeKind = core.EdgeDispatches
	// EdgeAsks targets a query: the source asks it. From an endpoint that
	// exposes the query, or from a port bound to it, it is declared.
	EdgeAsks EdgeKind = core.EdgeAsks
	// EdgeContracts goes from one process role to another it talks to —
	// through a socket, a pipe, a command line —, and names the versioned
	// contract they share in [Edge].Contract. It is the only edge between two
	// roles (D22). Declared.
	EdgeContracts EdgeKind = core.EdgeContracts
	// EdgeRuns goes from a role to what it runs: a CLI command, a listener,
	// an endpoint's server, a loop. Declared.
	EdgeRuns EdgeKind = core.EdgeRuns
	// EdgeImports goes from a component to a library it may import (D19).
	// Declared.
	EdgeImports EdgeKind = core.EdgeImports
	// EdgeRenders goes from a presentation to what it renders. Declared.
	EdgeRenders EdgeKind = core.EdgeRenders
)

The edge kinds.

type Edit 

type Edit = core.EditMessage

Edit is one change between two versions of a record, in RFC 6902's words: an add, a remove or a replace at a JSON pointer.

type EndpointInfo 

type EndpointInfo = core.EndpointSpec

EndpointInfo describes an HTTP endpoint, or the implementation of a port. It carries the method and path, the request and response schemas, and its auth.

type Erasure 

type Erasure = core.ErasureMessage

Erasure is what app.Erase did, store by store. Stores lists, store by store, what the erasure did there.

type Event 

type Event = core.Event

Event is one live event. Exactly one of the payload fields matching Type is set.

type EventType 

type EventType = core.EventType

EventType names the kind of a live event. It is a wire format — the graph's JSON and the Studio's TypeScript unions carry these names —, so it stays a string. 

const (
	// EventHello opens every stream and carries the graph revision.
	EventHello EventType = core.EventHello
	// EventSpan reports one unit of work that finished on a node.
	EventSpan EventType = core.EventSpan
	// EventTransition reports a workflow instance changing state.
	EventTransition EventType = core.EventTransition
	// EventLifecycle reports a lifecycle component moving, or the process
	// changing phase.
	EventLifecycle EventType = core.EventLifecycle
	// EventLoop reports a loop run.
	EventLoop EventType = core.EventLoop
	// EventCensus reports a workflow's population per state.
	EventCensus EventType = core.EventCensus
	// EventGraph reports that the graph structure changed.
	EventGraph EventType = core.EventGraph
	// EventLog reports a log record written by product code, in dev.
	EventLog EventType = core.EventLog
	// EventMail reports a mail entering the outbox or changing status.
	EventMail EventType = core.EventMail
)

The live event types.

type Export added in v0.57.0 

type Export = core.ExportMessage

Export is the product's OTLP export (app.OTLP), as the running process found it: what each signal's queue holds against its bounds, has sent and has lost. Its endpoint and headers are never shown.

type ExportSignal added in v0.57.0 

type ExportSignal = core.ExportSignalMessage

ExportSignal is one signal's queue of the OTLP export, sampled when the runtime state is read; its counters never move a revision.

type ExportedVersions 

type ExportedVersions = core.ExportedVersionsMessage

ExportedVersions are the versions of one exported record.

type Field 

type Field = core.FieldMessage

Field is one member of an object schema. It carries the JSON name, the schema of its value and the classes of its data.

type File 

type File = core.FileMessage

File is one file a graph points at: its path, relative to its root — the product's module, or the Go module Source.GoModule names.

type FlameNode 

type FlameNode = core.FlameNodeMessage

FlameNode is one frame of a flame graph. Its children are the frames it called; its value is the samples under it.

type Former 

type Former = core.FormerMessage

Former is one former value of a field that keeps its history: what it was, until when, and who replaced it.

type FrontendInfo 

type FrontendInfo = core.FrontendSpec

FrontendInfo describes static assets served by the product. It carries the path the assets are served under and where they are read from.

type FuncCost 

type FuncCost = core.FuncCostMessage

FuncCost is what one function cost. It carries the flat and cumulative samples of the function and where it lives.

type GoroutineGroup 

type GoroutineGroup = core.GoroutineGroup

GoroutineGroup is goroutines doing the same thing. They share one stack; Count says how many run it.

type Goroutines 

type Goroutines = core.GoroutinesResult

Goroutines is every goroutine of the process, grouped by what it runs. Each group names the node its stack runs in, when one does.

type Graph 

type Graph = core.GraphMessage

Graph is the whole product. It is the JSON document the runtime serves and the analyzer writes; Version names its shape.

func Merge 

func Merge(base, extra *Graph) *Graph

Merge enriches a graph with what another description of the same product knows. base is authoritative on which nodes exist — a runtime graph describes what the process actually serves —, on the modules it mounts, on what each of its ports calls and on which stores feed each of its watches: the app chose them when it started, where the analysis only reads the same rules over the whole module. extra, typically the static analysis, contributes documentation, handler ranges — an authorization function's too —, transition callers and the edges it found. Nodes only extra knows about are dropped: code that is compiled but not mounted in this app is not part of this product — save a node of a module's service the base mounts, which a package the binary does not link declares: a warning says so.

type HTTPServer 

type HTTPServer = core.HTTPServer

HTTPServer is the product's HTTP server, and whose loop serves it. Its address is the one it listens on; its loop is the node that runs it.

type HeldUntil 

type HeldUntil = core.HeldUntilSpec

HeldUntil is the hold a store declares on each of its records, until an instant the record carries.

type Hold 

type Hold = core.HoldEvent

Hold is one record a legal hold keeps. It carries references only: never the record's key, its subject's identity, or the hold's reason, which kit keeps apart.

type ID 

type ID = core.IDValue

ID is a node's identity, parsed: the one grammar of IDPattern. Its String is the ID it was parsed from.

func ParseID 

func ParseID(s string) (ID, error)

ParseID reads an ID. It refuses anything IDPattern does not match, with InvalidID; the refusal never quotes the input, which may be anything a caller sent.

type IndexInfo 

type IndexInfo = core.IndexSpec

IndexInfo is one secondary index of a store. Its name is unique in the store; Unique says whether two records may share a key.

type Instance 

type Instance = core.InstanceMessage

Instance is one entity's journey through a workflow. It carries the entity's key, its current state and the steps that brought it there.

type JobInfo 

type JobInfo = core.JobSpec

JobInfo describes a scheduled job. It carries the fixed interval or the cron expression that schedules it.

type JournalCheck 

type JournalCheck = core.JournalCheckMessage

JournalCheck is what verifying the journal's chain found. A broken chain names the first entry whose hash does not follow.

type JournalEntry 

type JournalEntry = core.JournalEntryEvent

JournalEntry is one operation of the privacy journal: what was done, where, by whom and when, with references only — never an identity, a value or a key. Each entry is chained to the previous one by SHA-256.

type LibraryInfo 

type LibraryInfo = core.LibrarySpec

LibraryInfo is a package shared between components (D19): the Node.Library of a KindLibrary node. 

type Link = core.LinkMessage

Link is a relationship between two elements of the architecture. The process's link to a database, "Reads and writes", carries the database connector, and the store connector once stores live on it.

type ListenerInfo 

type ListenerInfo = core.ListenerSpec

ListenerInfo is a listener that is not HTTP: the Node.Listener of a KindListener node — its network, its contract, who may connect.

type LogRecord 

type LogRecord = core.LogRecordMessage

LogRecord is one log record written by product code through app.Log, kept in dev so the Studio can show a request's logs beside its spans.

type Loop 

type Loop = core.LoopMessage

Loop is one recurring piece of the daemon's internal loop: a job, a workflow's timer sweep, a subscription's consumer, the HTTP accept loop, a declared or hand-written loop.

type LoopInfo 

type LoopInfo = core.LoopSpec

LoopInfo describes a loop node. Style says whether it is declared (kit owns the wait) or hand-written.

type MailMessage 

type MailMessage = core.MailMessage

MailMessage is a whole captured mail, for the Studio's mailbox. It is kept by the capture transport of dev and tests only, never in production.

type MailSummary 

type MailSummary = core.MailSummary

MailSummary is the name MailMessage embeds its summary under: the field a caller sets and reads is MailMessage.MailSummary, its JSON members promoted beside the body's.

type MailerInfo 

type MailerInfo = core.MailerSpec

MailerInfo describes outbound mail. It carries the transport that empties the outbox and the outbox's counters.

type Mechanic 

type Mechanic = core.MechanicMessage

Mechanic is a generic building block, backed by an SDK package, that a node composes. The catalog lists every mechanic kit offers; an endpoint's pipeline lists the ones it uses.

type Migration 

type Migration = core.MigrationMessage

Migration is one versioned migration. Its Version orders it among the others; Name says what it does.

type MigrationSet 

type MigrationSet = core.MigrationSetMessage

MigrationSet is one set of migrations on a database — kit's own, the product's (app.Migrations), a module's — with its own version table, and so its own lock.

type Mock 

type Mock = core.MockMessage

Mock is the replacement a test gave the app (MockReplace). It is set by a test only; the Studio shows it and never sets one (D13).

type Module 

type Module = core.ModuleMessage

Module is a module the app mounts: a Go module's services, released and mounted together like a bundle (ADR 0008). Everything a module declares is qualified with its name: its services are "<module>.<service>" — the one named like the module is "<module>" —, so its nodes are "<module>.<service>/<kind>/<name>" and carry Node.Module.

type ModuleVersion 

type ModuleVersion = core.ModuleVersionMessage

ModuleVersion identifies one module of a build. Local and Modified say when the code that ran is not the published version.

type Node 

type Node = core.NodeEntity

Node is one building block. Its ID is its identity; exactly one of the kind-specific fields matching Kind is set.

type NodeCost 

type NodeCost = core.NodeCostMessage

NodeCost is what one node cost. It is the share of the profile's samples spent in the node's code.

type NodeKind 

type NodeKind = core.NodeKind

NodeKind is the closed set of building blocks a kit product is made of. It is a wire format — the graph's JSON and the Studio's TypeScript unions carry these names —, so it stays a string. 

const (
	// KindService groups the nodes of one bounded context.
	KindService NodeKind = core.KindService
	// KindEndpoint is an HTTP endpoint with typed request and response.
	KindEndpoint NodeKind = core.KindEndpoint
	// KindStore is a typed, keyed collection of entities.
	KindStore NodeKind = core.KindStore
	// KindTopic is an asynchronous, at-least-once message channel.
	KindTopic NodeKind = core.KindTopic
	// KindSubscription consumes one topic.
	KindSubscription NodeKind = core.KindSubscription
	// KindWorkflow is a state machine over the entities of one store.
	KindWorkflow NodeKind = core.KindWorkflow
	// KindJob is scheduled work: a fixed interval or a cron expression.
	KindJob NodeKind = core.KindJob
	// KindFrontend is static assets served by the product.
	KindFrontend NodeKind = core.KindFrontend
	// KindExternal stands for everything outside the product.
	KindExternal NodeKind = core.KindExternal
	// KindAuth is the app's authentication handler: it turns a request's
	// credentials into a user, in front of every endpoint that asks for one.
	KindAuth NodeKind = core.KindAuth
	// KindMailer is outbound mail: a durable outbox, and the transport that
	// empties it — SMTP, or the capture of dev and tests.
	KindMailer NodeKind = core.KindMailer
	// KindLoop is a long-running loop of the daemon: declared (kit owns the
	// wait, the product the work) or hand-written (a goroutine kit supervises).
	KindLoop NodeKind = core.KindLoop
	// KindSecret is a secret the product declares: provided by the operator,
	// or generated by kit and rotated on a schedule. Its value is never in a
	// graph.
	KindSecret NodeKind = core.KindSecret
	// KindPort is an operation a service needs and does not implement: a
	// typed request, a typed response, a name. What it calls — another
	// service's endpoint, the app's binding, its own fallback — is decided
	// when the app starts, and drawn as a declared edge from the port.
	KindPort NodeKind = core.KindPort
	// KindCommand is an operation that changes something: a typed input, a
	// typed result, one handler, the pipeline of its kind. It is dispatched,
	// on its caller's goroutine or through its own queue.
	KindCommand NodeKind = core.KindCommand
	// KindQuery is an operation that reads and changes nothing: a typed
	// input, a typed result, one handler. It is asked.
	KindQuery NodeKind = core.KindQuery
	// KindBinary is one executable the product ships. It holds process
	// roles; its ID is "binary:<name>".
	KindBinary NodeKind = core.KindBinary
	// KindRole is one process role of a binary — "statusline" and
	// "statusline daemon" are two roles of one binary. Its root package is
	// generated wiring; two roles talk through their contract only. Its ID
	// is "binary:<binary>/role/<name>".
	KindRole NodeKind = core.KindRole
	// KindCLI is a short command-line command: it parses its arguments,
	// runs once and exits with a typed status.
	KindCLI NodeKind = core.KindCLI
	// KindListener accepts connections that are not HTTP: a private Unix
	// socket, a named pipe. It is an inbound port like an endpoint.
	KindListener NodeKind = core.KindListener
	// KindLibrary is a package shared between components, declared so the
	// components that use it are allowed to import it. Its ID is
	// "library:<name>".
	KindLibrary NodeKind = core.KindLibrary
	// KindPresentation turns a service's results into what a reader sees:
	// a rendered line, a page, a report.
	KindPresentation NodeKind = core.KindPresentation
)

The node kinds.

type PasswordPolicy 

type PasswordPolicy = core.PasswordPolicyMessage

PasswordPolicy is the policy of one secret field that holds a password's hash (Store.Passwords).

type Payload 

type Payload = core.Payload

Payload is the request and the response of a span, as JSON, in dev only. Every member whose name says it is a secret — password, token, secret, authorization, cookie… — or whose Go field is tagged app:"secret" is replaced by "[redacted]", and each side is cut at 8 KiB.

type Permission 

type Permission = core.PermissionMessage

Permission is what a caller needs to dispatch a command or to ask a query: that the app's policy lets it do Action to Resource (Allow).

type Person 

type Person = core.PersonMessage

Person is a human user of the product. It is drawn at the edge of the C4 context view, outside every container.

type PersonalData 

type PersonalData = core.PersonalDataMessage

PersonalData is a person's data as app.Export gives it (GDPR art. 15 and 20): their records, store by store, with what art. 15(1) asks beside them.

type PhaseChange 

type PhaseChange = core.PhaseChangeEvent

PhaseChange is one step of the daemon's life. It carries the phase entered, when it was entered, and why.

type Pool 

type Pool = core.Pool

Pool is a database's connection pool, as database/sql counts it. It is sampled when the runtime state is read; its counters never move a revision.

type Port 

type Port = core.PortMessage

Port is an address a process listens on. Owner is the container that listens on it; Serves names what is reached through it.

type PortInfo 

type PortInfo = core.PortSpec

PortInfo describes a port: an operation a service needs and another implements.

type PresentationInfo 

type PresentationInfo = core.PresentationSpec

PresentationInfo is what turns results into what a reader sees: the Node.Presentation of a KindPresentation node.

type Privacy 

type Privacy = core.PrivacyMessage

Privacy is what a running app says of the personal data it keeps. It is the Privacy page's data: the register, the holds and the journal's state.

type Process 

type Process = core.ProcessSpec

Process is the Go process a product runs in. It carries the runtime's figures — goroutines, heap, GC, CPU — taken at At.

type ProductRetention 

type ProductRetention = core.ProductRetentionSpec

ProductRetention is a retention the product keeps itself, as it says it.

type Profile 

type Profile = core.ProfileResult

Profile is a pprof profile of the running product, folded onto its graph: every sample is attributed to the node whose code was running — through the pprof label kit puts on every handler, subscription, job and loop run, or, for the heap, which carries no label, through the node's code functions on the sample's stack.

type QueryInfo 

type QueryInfo = core.QuerySpec

QueryInfo describes a query: an operation that reads and changes nothing.

type RecordFormer 

type RecordFormer = core.RecordFormerMessage

RecordFormer is the former values of one exported record's fields. A personal or special field's former values are redacted, never exported in clear.

type RecordHistory 

type RecordHistory = core.RecordHistoryMessage

RecordHistory is what kit remembers of one record, as the Studio's data view shows it (GET /_app/api/former): each field's former values, newest first, by the field's JSON pointer — a secret field's without their values, a personal or special one's redacted.

type RecordVersion 

type RecordVersion = core.RecordVersionMessage

RecordVersion is one version of a record whose store keeps revisions (ADR 0007 §3): its number, when the write that made it ran, who made it and which command, and the record as it was.

type RecordVersions 

type RecordVersions = core.RecordVersionsMessage

RecordVersions is a record's versions as the Studio's data view shows them (GET /_app/api/revisions), and what changed between two.

type Register 

type Register = core.RegisterMessage

Register is the record of processing of GDPR art. 30(1), as far as the code knows it.

type RegisterStore 

type RegisterStore = core.RegisterStoreMessage

RegisterStore is one store's line in the register. It names the classes the store keeps, their purposes and their retention.

type Retention 

type Retention = core.RetentionSpec

Retention is when kit erases or deletes a record: after a delay counted from an instant the record carries (After or Setting, and Since), or at an instant a function gives (At).

type RoleInfo 

type RoleInfo = core.RoleSpec

RoleInfo is one process role of a binary: the Node.Role of a KindRole node — its profile, arguments, singleton and idle stop.

type Runtime 

type Runtime = core.RuntimeMessage

Runtime is what a running process says about itself: the daemon's own state and its internal loop.

type Schema 

type Schema = core.SchemaMessage

Schema describes a Go type as it appears on the wire. It is a JSON-Schema-like shape: a kind, its fields or elements, and its Go type.

type SecretInfo 

type SecretInfo = core.SecretSpec

SecretInfo describes a declared secret: how it is made, where it lives, its versions — never its value.

type SelectCase 

type SelectCase = core.SelectCaseMessage

SelectCase is one case of a select statement in a hand-written loop. The analyzer reads it from the loop's body; Kind says what the case waits on.

type Setting 

type Setting = core.SettingMessage

Setting is one configuration value kit read when the product started: kit's own, or one a service of the product declares.

type Snippet 

type Snippet = core.SnippetMessage

Snippet is source code served to a reader of the graph. Focus and FocusEnd mark the lines a reader asked for, inside the lines served.

type Source 

type Source = core.SourceMessage

Source locates code. File is relative to its module's root; Line and EndLine bound the declaration.

type Span 

type Span = core.SpanMessage

Span is a finished unit of work, attributed to a node. Only allow-listed, wire-safe fields travel: no URL, no query string, no private error text.

type StateInfo 

type StateInfo = core.StateSpec

StateInfo is one state of a workflow. Terminal marks a state an instance stays in; Count is how many instances are in it.

type Stats 

type Stats = core.StatsMessage

Stats are observed counters for a node or an edge. They are counters: they never move a graph's revision.

type Step 

type Step = core.StepEvent

Step is one transition in an instance's history. It carries the event, the states it went from and to, and when it fired.

type StoreData 

type StoreData = core.StoreDataMessage

StoreData is one store's records about a person. It is one part of what app.Export gives a person about themselves.

type StoreErasure 

type StoreErasure = core.StoreErasureMessage

StoreErasure is one store's part of an erasure: the keys of the records erased, deleted, and held — left in place, as a legal hold asks. A key may be personal data, which the Studio and the logs never show.

type StoreHistory 

type StoreHistory = core.StoreHistoryMessage

StoreHistory is what a store remembers of its records. Fields names the fields it keeps former values of; Kept and Bytes weigh them, and Versions, Trashed and VersionBytes weigh its records' versions.

type StoreInfo 

type StoreInfo = core.StoreSpec

StoreInfo describes a store. It carries the entity's schema, its backend, its indexes, its privacy and its history.

type StorePrivacy 

type StorePrivacy = core.StorePrivacyMessage

StorePrivacy is what a store keeps of people: whom each record is about, why, for how long, and — on a runtime graph — what is held and due.

type StoreTrash added in v0.28.0 

type StoreTrash = core.StoreTrashMessage

StoreTrash is a page of a store's trash as the Studio lists it (GET /_app/api/trash), in key order.

type SubscriptionInfo 

type SubscriptionInfo = core.SubscriptionSpec

SubscriptionInfo describes a subscription — or a watch (ADR 0008), a subscription whose deliveries come from stores instead of a topic.

type System 

type System = core.SystemMessage

System is a software system outside the product. Nodes are the product's nodes that talk to it; Technology says what it runs on.

type TopicInfo 

type TopicInfo = core.TopicSpec

TopicInfo describes a topic. It carries the message's schema; its subscriptions are the nodes it delivers to.

type Trace 

type Trace = core.TraceMessage

Trace is the spans sharing one trace ID, root first. The root span is the one with no parent in the trace; the others follow it.

type TransitionEvent 

type TransitionEvent = core.TransitionEvent

TransitionEvent is one workflow instance moving between states. It names the workflow, the entity, the event and the states it went from and to.

type TransitionInfo 

type TransitionInfo = core.TransitionSpec

TransitionInfo is one arrow of a workflow. It names the event that fires it and the states it goes from and to.

type TrashedRecord added in v0.28.0 

type TrashedRecord = core.TrashedRecordMessage

TrashedRecord is one record in a store's trash as the Studio lists it (GET /_app/api/trash): its key, when the product deleted it and when kit purges it — never its value.

type WakeSource 

type WakeSource = core.WakeSourceMessage

WakeSource is one thing that wakes a declared loop. Kind says whether a topic, a period (Every) or a function wakes the loop.

type WorkflowInfo 

type WorkflowInfo = core.WorkflowSpec

WorkflowInfo describes a state machine bound to a store. It carries the states and the transitions between them, and the store it lives in.

Source Files

View all Source files

Directories

Path Synopsis
internal
core
Package core is the Product Graph under the names the role rule asks for: every struct carries its role (NodeEntity, GraphMessage, EndpointSpec, …).
 Package core is the Product Graph under the names the role rule asks for: every struct carries its role (NodeEntity, GraphMessage, EndpointSpec, …).

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.