Skip to content

Runtime Terminology

This document defines the architectural terminology used throughout Engineering Runtime.

The terminology described here represents the conceptual model of the Runtime rather than implementation details.

As the Runtime evolves, implementations may change while these architectural concepts remain stable.

Engineering Runtime

Engineering Runtime is a deterministic execution platform for engineering operations.

It provides a consistent execution model that enables Humans, CI/CD systems and AI to execute reusable Engineering Capabilities.

Engineering Runtime integrates engineering platforms rather than replacing them.

Runtime

The Runtime is the core execution platform.

It is responsible for:

  • Runtime Bootstrap
  • Configuration
  • Runtime Home
  • Runtime Lifecycle
  • Engine Lifecycle
  • Capability Lifecycle
  • Deterministic Execution
  • Policy Enforcement
  • Logging
  • Auditing

The Runtime intentionally contains very little engineering-specific logic.

Its responsibility is deterministic execution.

Runtime Context

Runtime Context is the effective execution target resolved for one operation.

It is an observation, not a Runtime-owned profile or session store.

Explicit selectors win. Otherwise, a registered adapter may observe the native context of the provider tool that will execute. If Runtime cannot bind the target, it refuses the operation rather than guessing.

Typical Runtime Context information may include:

  • GitHub Organization
  • Cloud Project
  • Kubernetes Context
  • Kubernetes Namespace
  • Jira Workspace
  • Security Platform Tenant
  • Environment
  • Region

Engineering Runtime does not replace, switch, or persist provider-native contexts.

Example:

Engineering Runtime

↓

Runtime Context

↓

GitHub Context

Cloud Context

Kubernetes Context

↓

Engineering Capability

↓

Runtime Engines

Runtime Context enables deterministic execution across Humans, CI/CD systems and AI by making the effective target visible before policy and execution.

Runtime Context commands are observational or migration-oriented:

runtime context show
runtime context retire

There is no runtime context use. Change context with the provider tool, such as kubectl config use-context, oc project, or gcloud config set project, or pass an explicit selector on the operation.

Runtime Engine

A Runtime Engine is a reusable execution component responsible for deterministic interaction with engineering systems.

Runtime Engines encapsulate platform integrations while exposing consistent execution interfaces to Engineering Capabilities.

Examples include:

  • Auth Engine
  • REST Engine
  • GraphQL Engine
  • Command Engine
  • File Engine

The Runtime architecture remains stable while Runtime Engines continue integrating additional engineering platforms.

Auth Engine

The Auth Engine validates or delegates authentication owned by engineering platforms.

Typical responsibilities include:

  • Explicit credential validation
  • Provider-native session delegation
  • Scoped credential brokering
  • Honest logout or platform guidance

The Auth Engine never creates a second credential store and never initiates an interactive login during an engineering operation. Resolved identities report native_delegated, platform_credential_brokered, or no_auth.

REST Engine

The REST Engine provides deterministic interaction with engineering platform APIs.

Typical responsibilities include:

  • HTTP Requests
  • Authentication Integration
  • Request Validation
  • Response Handling
  • Error Handling

GraphQL Engine

The GraphQL Engine provides deterministic interaction with engineering platform GraphQL APIs.

Typical responsibilities include:

  • Query Execution
  • Variable Binding
  • Authentication Integration
  • Response Handling
  • Error Handling

A Runtime Provider decides per operation whether REST or GraphQL is the right transport. The choice belongs to the provider, never to the Engineering Capability — which is what allows an operation to change transport without breaking any capability that calls it.

Command Engine

The Command Engine provides deterministic execution of engineering command-line tools.

Typical responsibilities include:

  • Command Execution
  • Environment Preparation
  • Output Capture
  • Exit Code Validation
  • Semantic context admission
  • Separate stdout and stderr capture
  • Native text, typed JSON, and raw payload output

Examples include:

  • git
  • gh
  • kubectl
  • terraform
  • docker
  • helm
  • gcloud
  • aws
  • az

An installed or allow-listed binary is not automatically executable. Binary policy, subcommand policy, and semantic context support must all admit the invocation. gh.repo.list is the first reviewed direct gh mode; other gh modes remain unsupported until separately reviewed.

File Engine

The File Engine performs deterministic manipulation of engineering files.

Typical responsibilities include:

  • Read
  • Write
  • Update
  • Validation
  • Structured Editing

The v0.9.4 adapter surface is exact:

  • Text: literal replace, including whole-word and whole-line modes
  • YAML: replace, scalar path set, insert-after, comment-out and uncomment; numeric and keyed sequence selectors
  • JSON: typed RFC 6901 add, replace/set, remove and test
  • Terraform/HCL: selected attribute set, single-line list membership and required-provider/version update
  • Markdown: exact replacement outside fences and heading-section replacement
  • Dockerfile: selected-stage base image/tag and exact replacement
  • CODEOWNERS: exact-pattern owner membership and structural validation

Every edit uses one exact file or a bounded recursive directory selection. --dry-run performs the complete preflight without writing; omitting it applies local atomic per-file replacements after every selected target has validated. The default text output includes the file table, counts and diffs. JSON includes typed per-file status and before/after digests.

File Engine does not clone repositories, stage or push Git changes, open pull requests, or invoke formatters and validators. Capabilities compose those as separately governed steps.

Engineering Capability

An Engineering Capability is reusable engineering knowledge expressed as executable Runtime logic.

Engineering Capabilities compose one or more Runtime Engines to solve engineering problems.

Examples include:

  • Create Repository
  • Configure Branch Protection
  • Bootstrap Cloud Project
  • Restart Deployment
  • Upgrade Infrastructure

Engineering Capabilities focus on engineering workflows rather than platform implementation.

Capability Registry

The Capability Registry manages Engineering Capabilities.

Responsibilities include:

  • Discovery
  • Installation
  • Versioning
  • Updates
  • Metadata

The Capability Registry enables reusable engineering knowledge.

Runtime Command

Runtime Commands provide the stable public interface exposed by Engineering Runtime.

Example:

runtime auth login github

runtime capability list

runtime capability execute github/repository/create

Runtime Commands should remain stable whenever possible.

Runtime Home

Runtime Home is the local workspace used by Engineering Runtime.

Example:

~/.engineering-runtime/

Typical contents include:

  • Configuration
  • Runtime-owned specifications and command references
  • Capability source configuration
  • Runtime Metadata
  • Logs
  • Cache

Runtime Bootstrap

Runtime Bootstrap prepares Engineering Runtime before execution.

Typical responsibilities include:

  • Initialize Runtime
  • Load Configuration
  • Load Runtime Home
  • Initialize Runtime Engines
  • Load Engineering Capabilities
  • Validate Runtime

Runtime Lifecycle

The Runtime Lifecycle defines how Engineering Runtime executes.

Initialize

↓

Load Configuration

↓

Load Runtime Home

↓

Initialize Runtime Engines

↓

Resolve Effective Context

↓

Load Engineering Capabilities

↓

Validate Policy

↓

Authenticate

↓

Execute

↓

Audit

↓

Exit

Engine Lifecycle

Runtime Engines follow a consistent lifecycle.

Initialize

↓

Configure

↓

Validate

↓

Execute

↓

Return Result

Every Runtime Engine should behave consistently regardless of the engineering platform being integrated.

Capability Lifecycle

Engineering Capabilities evolve independently from the Runtime.

Create

↓

Validate

↓

Package

↓

Publish

↓

Install

↓

Execute

↓

Version

↓

Deprecate

Deterministic Execution

Deterministic Execution is the foundational principle of Engineering Runtime.

Execution should produce predictable, repeatable and auditable outcomes regardless of whether execution is initiated by:

  • Human Engineers
  • CI/CD Pipelines
  • AI Agents

Engineering Systems

Engineering Systems are external engineering platforms integrated through Runtime Engines.

Examples include:

  • GitHub
  • GitLab
  • Kubernetes
  • Docker
  • Terraform
  • AWS
  • Azure
  • Google Cloud
  • Jira
  • Checkmarx

Engineering Runtime integrates engineering platforms rather than replacing them.

Engineering Intent

Engineering Intent describes what the user wants to accomplish.

Examples include:

  • Create Repository
  • Deploy Application
  • Upgrade Infrastructure
  • Rotate Secrets

AI reasons about Engineering Intent.

Runtime Context determines where Engineering Intent executes.

Engineering Runtime executes Engineering Intent deterministically.

Engineering Knowledge

Engineering Knowledge consists of reusable engineering experience, patterns and workflows.

Engineering Runtime transforms Engineering Knowledge into reusable Engineering Capabilities.

AI Skills

AI Skills represent reasoning and knowledge provided by AI models.

AI uses Skills to understand Engineering Intent.

Engineering Runtime does not execute AI Skills.

Control Plane

The Control Plane is the optional governance layer above a fleet of Engineering Runtimes.

It is responsible for:

  • Publishing a single policy version to every Runtime
  • Collecting audit produced by every Runtime
  • Reporting which Runtimes are active and which policy version each one holds
  • Presenting the Provider and Engineering Capability catalog of an organization

The Control Plane distributes governance.

It does not execute engineering operations, and no Engineering Capability addresses it.

Policy is pulled from the Control Plane, cached in Runtime Home, and evaluated locally.

Audit is written locally first and forwarded to the Control Plane afterwards.

An unavailable Control Plane therefore cannot change the outcome of an engineering operation.

The Engineering Runtime is complete without a Control Plane.

Data Plane

The Data Plane is the Engineering Runtime executing engineering operations.

Authentication, Runtime Context resolution, policy evaluation, execution and audit all occur in the Data Plane.

Every Runtime is a Data Plane instance, whether or not a Control Plane exists.

Runtime Philosophy

Engineering Runtime follows several core principles.

  • AI abstracts knowledge through Skills.
  • Runtime Context abstracts execution state.
  • Engineering Runtime abstracts engineering execution.
  • Runtime Engines integrate engineering platforms.
  • Engineering Capabilities compose Runtime Engines.
  • AI reasons about Engineering Intent.
  • Runtime Context determines where Engineering Intent executes.
  • Engineering Runtime executes Engineering Intent deterministically.
  • Existing engineering platforms are integrated rather than replaced.
  • Engineering knowledge becomes reusable Engineering Capabilities.

AI and Engineering Runtime

Engineering Runtime is designed to complement AI rather than replace it.

AI abstracts knowledge through Skills.

Runtime Context abstracts execution state.

Engineering Runtime abstracts engineering execution through reusable Engineering Capabilities.

AI reasons about Engineering Intent.

Runtime Context determines where Engineering Intent executes.

Engineering Runtime executes Engineering Intent deterministically.

Together they separate reasoning, execution state and execution while allowing Humans, CI/CD systems and AI to collaborate through reusable Engineering Capabilities.

This separation allows Engineering Runtime to remain AI independent while providing a stable, governed and deterministic execution platform regardless of which AI model is used.

Long-Term Evolution

Engineering Runtime evolves by expanding Runtime Engines and Engineering Capabilities.

The Runtime architecture intentionally remains stable.

As new engineering platforms emerge:

  • Runtime Engines integrate additional engineering platforms.
  • Engineering Capabilities compose those Runtime Engines into reusable engineering workflows.

The architecture evolves without redesigning the Runtime.

Guiding Principle

Engineering Runtime is a deterministic execution platform.

Runtime Context provides deterministic execution state.

The Runtime remains stable.

Runtime Engines continue integrating engineering platforms.

Engineering Capabilities continue expanding reusable engineering knowledge.

Together they provide a consistent execution model for Humans, CI/CD systems and AI.

Version

This terminology document applies to Engineering Runtime v1.

Future Runtime releases may introduce additional concepts while preserving the existing architectural terminology whenever possible.