5. Building Block View

This view describes the named application from outside, then opens its logical boundaries. The blocks are responsibilities defined by accepted ADRs, not prescribed packages, processes or separate servers.

5.1 External contract of the named CLI

As a black box, the application lets people and approved agent clients discover and invoke the same declared commands. The CLI owner supplies trusted implementations and configuration; extension authors supply independently verified releases. People and external services are participants and dependencies, not internal components. ADR-0007, ADR-0010, ADR-0013

Boundary	Externally visible responsibility
CLI and optional MCP	Present approved commands, validate input and return the finalized outcome through the selected interface
Extension supply	Discover approved releases, verify their declarations and artifacts, and activate a complete command generation
Identity and protected resources	Use selected owner integrations and current authority; installation and listing do not grant access to every action
Execution	Own each foreground call, its declared environment and supported restrictions, cancellation and cleanup

These responsibilities are common to the local baseline and integrated configurations. They do not require every optional provider or a separate MCP server for each extension. ADR-0004, ADR-0005, ADR-0009, ADR-0013

5.2 Internal decomposition

The white-box view separates the application entry points from the embedded core’s command, execution and access responsibilities. It omits individual stores and providers to keep control boundaries visible. Arrows are logical dependencies, not a new protocol. Detailed implementation packages are not selected by this view.

Components and decisions

Command model and dispatcher · Extension loader · Lifecycle owner · Executor · Runtime provider · Security Broker and action admission · Credentials and sign-in sessions · Core facilities · Profile and resource state

ADR-0001 · ADR-0002 · ADR-0003 · ADR-0004 · ADR-0005 · ADR-0007 · ADR-0008 · ADR-0009 · ADR-0010 · ADR-0011 · ADR-0012 · ADR-0013 · ADR-0014 · ADR-0015 · ADR-0016

Component contracts and dependencies

The directory is generated from the same model as the diagrams. It distinguishes internal blocks, environment/resources and participants; each entry gives its responsibility, relationships and defining ADRs. An external participant listed here does not become part of the core.

CLI and core

Named CLI application named-cli

Owner-built application embedding Rukh, a CLI entry point and an optional MCP host; local stdio needs no separate service.

Defined by: ADR-0010 · ADR-0013

Relationships

Contains: Rukh core library, CLI adapter, MCP adapter
CLI owner → Named CLI application
Trusted composition
CLI user → Named CLI application
Commands and interaction

Rukh core library rukh-core

Embeddable command, lifecycle, access and resource responsibilities shared by human and machine callers.

Defined by: ADR-0001 · ADR-0002 · ADR-0010 · ADR-0013 · ADR-0014 · ADR-0015 · ADR-0016

Relationships

Command model and dispatcher command-model

Validated canonical commands and common typed inputs/results, projected into CLI routes and owner-approved MCP tools from one committed generation.

Defined by: ADR-0002 · ADR-0006 · ADR-0013

Relationships

Part of: Rukh core library
Command model and dispatcher → Profile and resource state
Pinned command and release
Command model and dispatcher → Lifecycle owner
Immutable invocation
CLI adapter → Command model and dispatcher
CLI view and common invocation
MCP adapter → Command model and dispatcher
MCP view and common invocation

Extension loader extension-loader

Permitted discovery, release verification, immutable installation and atomic publication of owner configuration, CLI routes and eligible MCP projections.

Defined by: ADR-0005 · ADR-0007 · ADR-0009 · ADR-0013

Relationships

Part of: Rukh core library
Extension loader → Approved artifact sources
Resolve and verify artifacts
Extension loader → Security Broker and action admission
Discovery and admission
Extension loader → Profile and resource state
Atomic profile publication

Lifecycle owner lifecycle-owner

Logical in-core owner of invocation ordering, cancellation, admission and one final outcome.

Defined by: ADR-0002 · ADR-0004

Relationships

Part of: Rukh core library
Command model and dispatcher → Lifecycle owner
Immutable invocation
Lifecycle owner → Runtime provider
Exact verified environment
Lifecycle owner → Executor
Launch, supervision, finalization
Extension process → Lifecycle owner
Bound operation request
Lifecycle owner → Security Broker and action admission
Current action admission
Lifecycle owner → Effect commitment and reconciliation
Bound consequential operation

Executor executor

Registered foreground execution with private managed IPC and an explicit host-trusted or verified confined profile; mandatory unsupported restrictions reject launch.

Defined by: ADR-0001 · ADR-0003 · ADR-0004 · ADR-0015

Relationships

Part of: Rukh core library
Lifecycle owner → Executor
Launch, supervision, finalization
Executor → Extension process
Streams and private control IPC
Executor → Protected resources
Declared execution boundary

Runtime provider runtime-provider

Trusted integration for exact environment resolution, authorized preparation and held references; not a mandatory external manager.

Defined by: ADR-0008 · ADR-0010

Relationships

Part of: Rukh core library
Lifecycle owner → Runtime provider
Exact verified environment
Runtime provider → Profile and resource state
Protect environment references

Security Broker and action admission security-broker

In-core identity, authorization, permitted discovery and final admission intersecting current rights with task authority and required effect checks; no broker server is mandatory.

Defined by: ADR-0005 · ADR-0009 · ADR-0012 · ADR-0014 · ADR-0016

Relationships

Part of: Rukh core library
Extension loader → Security Broker and action admission
Discovery and admission
Security Broker and action admission → Approved catalogs and local rules
Selected catalogs and rules
Security Broker and action admission → External identity service
Optional identity integration
Security Broker and action admission → External permission service
Optional permission integration
Security Broker and action admission → Credentials and sign-in sessions
Bound identity and credentials
Lifecycle owner → Security Broker and action admission
Current action admission
Security Broker and action admission → Core facilities
Admitted core operation
Security Broker and action admission → Profile and resource state
Permission validity coordination
Security Broker and action admission → Task authority and shared budgets
Scope, revocation and budget reservation
Effect commitment and reconciliation → Security Broker and action admission
Recheck before effect dispatch

Credentials and sign-in sessions credentials

Core-owned protected credential use, verified subject binding, coordinated renewal and logout when identity is required.

Defined by: ADR-0011

Relationships

Part of: Rukh core library
Security Broker and action admission → Credentials and sign-in sessions
Bound identity and credentials
Credentials and sign-in sessions → Profile and resource state
Session and logout coordination

Core facilities core-facilities

Trusted registered operations, core-owned presentation, typed results, logs and audit; consequential operations declare effect and reconciliation support.

Defined by: ADR-0002 · ADR-0010 · ADR-0013 · ADR-0016

Relationships

Part of: Rukh core library
Security Broker and action admission → Core facilities
Admitted core operation
Core facilities → Protected resources
Resource-side enforcement remains
Effect commitment and reconciliation → Core facilities
Registered reconciliation query

CLI adapter cli-adapter

Projects canonical commands into routes, parses terminal arguments into the shared input record and presents committed results.

Defined by: ADR-0002 · ADR-0013

Relationships

Part of: Named CLI application
CLI user → CLI adapter
CLI arguments and presentation
CLI adapter → Command model and dispatcher
CLI view and common invocation

MCP adapter mcp-adapter

Trusted host adapter exposing approved tools from the current generation, validating exact tool bindings and returning bounded machine results through the common invocation path.

Defined by: ADR-0010 · ADR-0013

Relationships

Part of: Named CLI application
Agent or machine client → MCP adapter
Discover and call tools
MCP adapter → Command model and dispatcher
MCP view and common invocation
MCP adapter → Task authority and shared budgets
Bind caller and task scope

Task authority and shared budgets task-authority

Core-owned issuer and coordinator of local or integrated task grants, attenuated delegation, revocation and shared measurable reservations. It does not plan agent work.

Defined by: ADR-0014

Relationships

Part of: Rukh core library
CLI owner → Task authority and shared budgets
Approved policy or authorized consent
MCP adapter → Task authority and shared budgets
Bind caller and task scope
Security Broker and action admission → Task authority and shared budgets
Scope, revocation and budget reservation
Task authority and shared budgets → Profile and resource state
Shared task and budget state

Effect commitment and reconciliation effect-coordinator

Coordinates trusted effect preparation, exact request/resource binding, required authorization or approval, durable dispatch state and authorized reconciliation of uncertain outcomes without repeating the effect.

Defined by: ADR-0016

Relationships

Part of: Rukh core library
Lifecycle owner → Effect commitment and reconciliation
Bound consequential operation
Effect commitment and reconciliation → Security Broker and action admission
Recheck before effect dispatch
Effect commitment and reconciliation → Profile and resource state
Effect intent and observed outcome
Effect commitment and reconciliation → Core facilities
Registered reconciliation query

Environment and resources

Profile and resource state profile-state

Owner-controlled profile revisions, artifact/environment references, invalidation metadata and coordinated task/budget/effect records. Local durable storage is the baseline, not a database service.

Defined by: ADR-0007 · ADR-0008 · ADR-0009 · ADR-0011 · ADR-0012 · ADR-0013 · ADR-0014 · ADR-0016

Relationships

Extension loader → Profile and resource state
Atomic profile publication
Command model and dispatcher → Profile and resource state
Pinned command and release
Credentials and sign-in sessions → Profile and resource state
Session and logout coordination
Security Broker and action admission → Profile and resource state
Permission validity coordination
Runtime provider → Profile and resource state
Protect environment references
Task authority and shared budgets → Profile and resource state
Shared task and budget state
Effect commitment and reconciliation → Profile and resource state
Effect intent and observed outcome

Extension process extension-process

Native or script command instance supervised under the selected execution profile. Host-trusted retains ambient OS authority; confinement is claimed only for enforced declared dimensions.

Defined by: ADR-0001 · ADR-0003 · ADR-0004 · ADR-0015

Relationships

Executor → Extension process
Streams and private control IPC
Extension process → Lifecycle owner
Bound operation request

Approved artifact sources artifact-sources

Configured OCI, hosted HTTPS, Git or approved local delivery bindings supplying release bytes.

Defined by: ADR-0007

Relationships

Extension author → Approved artifact sources
Declared releases
Extension loader → Approved artifact sources
Resolve and verify artifacts

Approved catalogs and local rules catalog-rules

Owner-authored validated declarations; one static catalog and explicit local policy form the baseline.

Defined by: ADR-0009

Relationships

Security Broker and action admission → Approved catalogs and local rules
Selected catalogs and rules

External identity service identity-service

Optional approved standard, domain or custom identity integration; only selected configurations require it.

Defined by: ADR-0005 · ADR-0011

Relationships

Security Broker and action admission → External identity service
Optional identity integration

External permission service permission-service

Optional authoritative AuthZEN or custom provider; local rules may instead be selected deliberately.

Defined by: ADR-0005 · ADR-0009 · ADR-0012

Relationships

Security Broker and action admission → External permission service
Optional permission integration

Protected resources protected-resources

Resources reached by admitted trusted core operations, retaining their own access enforcement.

Defined by: ADR-0002 · ADR-0005 · ADR-0012

Relationships

Core facilities → Protected resources
Resource-side enforcement remains
Executor → Protected resources
Declared execution boundary

Participants

CLI owner cli-owner

Assembles trusted implementations and controls profile authority.

Defined by: ADR-0010

Relationships

CLI owner → Named CLI application
Trusted composition
CLI owner → Task authority and shared budgets
Approved policy or authorized consent

CLI user cli-user

Discovers, installs and invokes commands within the selected policy.

Defined by: ADR-0002 · ADR-0007 · ADR-0009

Relationships

CLI user → Named CLI application
Commands and interaction
CLI user → CLI adapter
CLI arguments and presentation

Extension author extension-author

Publishes declared commands and immutable release artifacts.

Defined by: ADR-0006 · ADR-0007

Relationships

Extension author → Approved artifact sources
Declared releases

Agent or machine client agent-client

Calls the named CLI through MCP with independently bound authority; model output and client-provided names do not establish identity or consent.

Defined by: ADR-0013 · ADR-0014

Relationships

Agent or machine client → MCP adapter
Discover and call tools

5.3 Trusted integration boundaries

Built-in handlers and owner adapters are trusted code with cooperative cancellation requirements. Ordinary extensions cannot promote themselves to this path. User configuration can narrow constraints or change explicitly delegated preferences, but cannot expand the set of trusted implementations. ADR-0010

Security Broker selects identity, authorization and discovery independently. Standard integrations use OIDC/OAuth for sign-in and AuthZEN for permission evaluation; domain or proprietary services use owner-registered adapters or protocol bridges. Local catalogs and rules implement the same boundaries without remote services. ADR-0005, ADR-0009

The host, core and adapters have distinct operational obligations. Embedding the library does not transfer ownership of the application’s lifetime to Rukh.

Boundary	Obligation of the owning implementation
Host → core	Delegate streams, one terminal coordinator and OS cancellation explicitly; keep invocation scopes alive, close them and release finished handles. The library returns results instead of exiting the application or taking global signal handlers
Core → trusted provider	Validate dependency and lifetime compatibility before initialization; initialize admitted providers in order and dispose only owned instances in reverse order on failure. Sign-in and package/runtime installation are separate operations, not hidden startup work
Loader/runtime provider → state storage	Coordinate publication, references and collection through the same supported storage boundary; do not treat a partial directory or a missing numeric process identifier as proof of readiness or safe deletion
Core → in-process handler	Require cooperative cancellation and bounded completion. An uncooperative callback needs a declared supervised binding; moving it to another thread does not provide forced cleanup

These obligations are defined by ADR-0007, ADR-0008 and ADR-0010. Operational limits belong to those contracts, not to a presumed separate administrator or server component.

5.4 Task and effect boundaries

Components and decisions

CLI owner · Lifecycle owner · Security Broker and action admission · Profile and resource state · MCP adapter · Task authority and shared budgets · Effect commitment and reconciliation

ADR-0002 · ADR-0005 · ADR-0012 · ADR-0013 · ADR-0014 · ADR-0016

Command adapters normalize inputs; task authority constrains what a caller may request; Security Broker resolves current identity and permission decisions; final admission coordinates those decisions with shared reservations. A purpose string is diagnostic data, not a grant. ADR-0013, ADR-0014

The effect coordinator binds a consequential action to its exact implementation, resource and payload, then records dispatch and the observed result. It reuses final admission and protected local state rather than requiring a new service. An unknown result retains protective records and reservations until justified reconciliation. ADR-0016

The executor enforces only the guarantees declared by a verified execution profile. Direct OS activity in a host-trusted process is outside mediated core checks. ADR-0015