Glossary
The orun vocabulary, in one place, grouped by the four pillars of platform discipline as code. Terms link to the page that explains them in depth.
1 · Declare
| Term | Definition |
|---|---|
| Intent | The repository-level control document (intent.yaml): environments, groups, policies, discovery roots, trigger bindings, composition sources. Says what, never how. → Intent model |
| Component | A deployable or operable unit declared next to its code in component.yaml: a type, environment subscriptions, typed inputs, dependencies, and catalog metadata. → Intent model |
| Type | A component's contract name (e.g. terraform, helm-chart). Binds the component to the composition that validates and executes it. → Compositions |
| Composition | A versioned execution contract for one component type: input schema, job templates, execution profiles, and declared effects. → Compositions |
| Group (domain) | Defaults shared by every component in a domain, keyed by the domain name and declared in the intent. → Intent model |
| Environment | A named runtime context (dev, staging, production) with its own activation rules, defaults, and policies. → Intent model |
| Policy | A policies map declared on a group, an environment, or an execution profile. Carried onto every component instance but not yet enforced by the planner or runner. → Standards |
| Standard | A declaration the platform reads and checks: a schema, a profile, a rule, an ordering, a pin, a contract. Each is enforced, recorded, or declared only. → Standards |
| Profile | A context overlay on a composition (pull-request, verify, deploy): which jobs, steps, and capabilities run in that context. → Profile rules |
| Trigger binding | A rule mapping an external event (PR, push, tag) to planning context: which environments activate, what scope compiles. → Trigger bindings |
| Dependency rule | Per-trigger policy for whether dependsOn edges are enforced, advisory, or disabled. → Dependency rules |
| Promotion | An ordering constraint between environments (production after staging), compiled into the plan. → Environment promotion |
| Change watch | A component's opt-in (spec.change.watches) to being affected by changes in specific global intent sections. → Change watches |
| Effects | A composition's declaration of what running it contributes to the catalog: integrations, provided Resources, exposed APIs, satisfied scorecard rules. → Service catalog |
2 · Package and evolve
| Term | Definition |
|---|---|
| Stack | How standards travel: compositions (golden paths) and optional intent presets packaged together under a stack.yaml, versioned, and published as an OCI artifact that repositories reference as a composition source. → Stacks |
| Intent preset | Platform rules (environments, trigger bindings, defaults, discovery roots) shipped inside a Stack and inherited by a repository with extends:; presets fill in what the repository leaves out. Not a baseline. → Intent presets |
| Source pin | A digest: on a composition source in intent.yaml. orun plan verifies it and fails if the source resolves to anything else. → Versioning and locking |
| Baseline | A whole product's structure and standards, packaged: a blueprint plus the Stacks and presets it pulls, registered in the baseline registry and rebuilt for a new owner phase by phase by orun baseline new, then upgraded rather than forked. Presets and Stacks are the standards layers inside it; neither is itself a baseline. → Baselines |
| Baseline registry | The catalogue of baselines — id, source repository, pinned tag, tier, visibility, required providers, manifest path. Orunbase-maintained rows live in orun-cloud's baselines.yaml; account rows come from orun baseline register. → orun baseline |
| Blueprint | A kind: Blueprint (orun.dev/v1) document orun new places into a directory: sources, modules, dependency edges, inputs, and phases with hooks. → orun new |
| Blueprint card | blueprint.yaml at a baseline's pinned tag: the integrations it requires, its inputs, a preview of the secrets it mints, the path of its build document, and the URLs a finished build must answer. It carries no tag of its own. → Baselines |
| Build document | The kind: Blueprint a card names in spec.bootstrap.blueprint — what orun actually places, phase by phase, with hooks and gates. → Baselines |
| Provenance lock | .orun/provenance.lock (ScaffoldProvenance): the blueprint and source digests, a secret-free input hash, and each module's mode and target — the base orun new upgrade three-way merges against. → orun new |
| kiox provider | orun's distribution form: an OCI provider artifact (ghcr.io/sourceplane/orun) consumable by the kiox workspace tool. → Use with kiox |
| OCI artifact | The registry format used to distribute both orun itself and composition Stacks. → Stacks |
3 · Ground agents, and the platform
| Term | Definition |
|---|---|
| Agent session | One run of the agent runtime (as_…): an append-only event log with one body and any number of attached heads, sealed on terminal state as an AgentSessionSnapshot and replayable with orun agent replay. → The agent runtime |
| Agent type | An agents/<name>.md file — a capability envelope in frontmatter (harness, model, tools policy, mayAffect, owner) plus a persona body — sealed by orun agent import into a content-addressed AgentTypeSnapshot. → The agent runtime |
| Cockpit v2 | orun tui-next (also orun tui --next): the rebuilt terminal head — Home, Agents, Activity, Catalog, and Events over the same state store as the console. A preview until it becomes the default. → orun tui-next |
| Epic | The programme tasks club under: an epc_… id, an EP-n key, and a slug. Carries milestones and spec docs; its rollup is folded from task verdicts at read time. → The task plane |
| Grounded session | An agent session that starts in a real checkout of a linked repository on a task-keyed branch, with git authenticated through short-lived, repository-scoped tokens minted from the session's own credential. → The agent runtime |
| MCP | orun mcp serve, the one local Model Context Protocol server: the pen plane (pr_open) and the platform plane (the Orunbase API), under one connection; orun mcp tools prints the roster and --read-only drops the platform writes. It is how an agent reads the same catalog and task plane the platform does. → orun mcp |
| Milestone | One phase of an epic, in order, with exit criteria: an mls_… id that implies its epic. → The task plane |
| Object graph | The content-addressed store under .orun/objectmodel/ seen whole — sources, catalogs, plans, executions, agent types, sessions, task nodes — inspected with orun objects. → State model |
| Orunbase | The hosted control plane (app.orunbase.com): workspaces, shared state, the task plane's allocator and derived verdicts, sandboxed agents, the console, and the API the platform MCP plane calls. Formerly "Orun Cloud"; the orun cloud command group keeps the older name. → Workspaces and tenancy |
| Phase | In a Blueprint, a placement barrier with hooks attached — all of phase N is placed before N+1, and phase state is derived from the tree, so --resume is safe. In the task plane, a milestone. → Baselines |
| Provenance pen | orun pr: the branch grammar orun/<KEY>-<slug>, the Orun-Task commit trailer, and the manifest block in the PR body — open writes them, check preflights them, land merges once checks conclude. → The task plane |
| Repository link | Two distinct things: the CLI link orun auth login or orun cloud link caches, which puts a repository on a workspace's allow-list; and the console repl_… link created through the GitHub App, which lets the platform clone, push, and open PRs on the repository. → Workspaces and tenancy |
| Skill | A hosted agent playbook: a content-addressed revision in a registry where a workspace's revisions shadow the Sourceplane defaults by name. orun skills pull writes each as a native SKILL.md carrying its orun-rev. → orun skills |
| Spec doc | Repository-authored markdown annotated to an epic. orun spec push uploads the committed copy with its repo, path, and sha, idempotent by content hash; the platform stores it sealed beside the epic. → orun spec |
| Task | The unit of work: a key issued by the cloud allocator (adopted, derived, or minted), a contract in the repository, and a verdict derived from observations. → The task plane |
| TaskContract | tasks/<KEY>.TaskContract.yaml (orun.io/v1): goal, affects, doneWhen, gates, and related fields, sealed by sha256 over canonical JSON wherever it travels. An explicit gates: [] means merge alone finishes the work. → The task plane |
| Verdict | A task's derived rung — draft → ready → in_progress → in_review → done → released — read from the branch, PR, merge, and gates the platform observed; never typed by anyone. → The task plane |
| Workspace | The tenancy unit every cloud command runs under, named by a ws_… id or a slug (legacy org_…); resolved as --workspace > ORUN_WORKSPACE > intent.yaml > this repo's link > orun workspace use. → Workspaces and tenancy |
| Workspace link | The CLI-side link between a repository and a workspace and project, created by orun auth login or orun cloud link and cached in ~/.orun/config.yaml; the fourth rung of workspace resolution. → orun cloud |
4 · Verify and plan
| Term | Definition |
|---|---|
| Planner / compiler | The six-stage pipeline — load, normalize, expand, bind, resolve, materialize — that turns declarations into a plan. → How orun works |
| Component instance | One cell of the environment × component matrix, with fully merged inputs and resolved policies. → Plan DAG |
| Job instance | An executable DAG node (component.environment.job) with rendered steps and job-level dependency edges. → Plan DAG |
| Plan (plan DAG) | The immutable compiled artifact (plan.json): every job, step, edge, and merged input made explicit. The artifact of record. → Plan DAG |
| Composition lock | .orun/compositions.lock.yaml: a record of the digest each composition source resolved to, written by orun plan and orun compositions lock. orun does not read it back; the enforced pin is a source digest:. → Versioning and locking |
| Scope | Which components/environments a plan covers: full, changed, or explicit --component/--env/--all-envs selection. → Change detection |
| Change detection | The engine classifying which components a file change affects, powering --changed and orun catalog affected. → Change detection |
4 · Execute
| Term | Definition |
|---|---|
| Runner | A swappable execution backend for a plan: local shell, Docker, or GitHub Actions. → Runners |
| Execution (run) | One invocation of a plan: jobs, steps, attempts, logs. Live while running; sealed immutable when terminal. → Execution model |
| Resume | Re-running a plan such that already-succeeded jobs are skipped, with their prior logs carried forward. → Execution model |
| Cockpit | The unified operator surface — orun status, orun logs, and the TUI — all rendering the same view-model with the same design tokens. → Cockpit overview |
4 · Record
| Term | Definition |
|---|---|
| Object model | orun's persistence layer under .orun/objectmodel/: a git-shaped DAG of immutable, content-addressed objects plus named refs. → State model |
| Ref | A named, mutable pointer into the object graph (catalogs/current, executions/latest). → State model |
| Source snapshot | A content-addressed capture of the workspace sources a catalog or plan was resolved from. → State model |
| Catalog | The typed service catalog derived from the sources at a snapshot: entities, relations, ownership, indexes. → Service catalog |
| Entity | A typed catalog object in the shared orun.io/v1 envelope. Kinds: Component, API, Resource, System, Domain, Group, Environment, Composition. → Service catalog |
| Relation graph | The unified typed edge set (relations.json) — dependsOn, partOf, ownedBy, providesApi, consumesApi, runsOn, deployedTo, composedBy — consumed by both catalog reads and change detection. → Service catalog |
| Ownership provenance | Where an entity's owner came from: authored, CODEOWNERS, or inherited. → Service catalog |
| Live plane | Deployment and health state derived on read from execution history — never persisted into catalog blobs. → Service catalog |
| Plan revision | A compiled plan sealed into the object model, pinned to the catalog it was compiled against. → State model |