Skip to content
Rukh

6. Runtime View

This view follows interactions between the building blocks during selected operations. Each scenario states its trigger and relevant alternatives; diagrams show the successful path unless stated otherwise. A failed check or accepted cancellation stops subsequent work and follows the defining ADR, rather than continuing through later arrows.

6.1 Loading and updating extensions

Section titled “6.1 Loading and updating extensions”

Trigger: the user or another separately authorized operation requests an extension installation or update.

Discovery, installation, activation and invocation have separate checks. A visible candidate is neither a verified artifact nor permission to execute every command. Catalog delivery is independent of artifact delivery: OCI, HTTPS and Git adapters return a common release to verification. ADR-0005, ADR-0007, ADR-0009

From catalog candidate to active commands
From catalog candidate to active commandsValidate the complete CLI and eligible MCP projections before one atomic profile publication. Installed bytes alone grant neither exposure nor execution.Profile and resource stateApproved artifact sourcesSecurity Broker and action admissionExtension loaderProfile and resource stateApproved artifact sourcesSecurity Broker and action admissionExtension loader1. Discover permitted release references2. Resolve exact release metadata3. Admit declared installation effects4. Fetch, verify and stage immutable artifacts5. Recheck activation after validating the complete candidate6. Publish one profile revision with validated CLI and MCP projectionsFrom catalog candidate to active commandsValidate the complete CLI and eligible MCP projections before one atomic profile publication. Installed bytes alone grant neither exposure nor execution.Profile and resource stateApproved artifact sourcesSecurity Broker and action admissionExtension loaderProfile and resource stateApproved artifact sourcesSecurity Broker and action admissionExtension loader1. Discover permitted release references2. Resolve exact release metadata3. Admit declared installation effects4. Fetch, verify and stage immutable artifacts5. Recheck activation after validating the complete candidate6. Publish one profile revision with validated CLI and MCP projections
Components and decisions

Extension loader · Security Broker and action admission · Profile and resource state · Approved artifact sources

ADR-0005 · ADR-0007 · ADR-0009 · ADR-0012 · ADR-0013

Any failed step stops the path. Updates do not overwrite files used by existing calls. One activeProfileRevision binds owner configuration and command generation. Uncertain commitment is reconciled by operation identity, not repeated blindly; referenced or uncertain resources cannot be collected.

The installation path also covers these alternatives:

EventRequired continuation
A call and an update overlapCapture the committed revision and acquire its references together. The call keeps its release and environment; only later lookups can use the new revision, and current access checks still apply
Two changes start from the same profile revisionCommit only against the expected revision. A conflict does not merge partial command trees or replace the winning configuration
Verification, extraction or capacity checks failPublish no partial release or candidate generation; preserve the current committed profile without extending its validity
The host stops during profile publicationRecover the durable transaction and determine its recorded outcome before another mutation; a missing acknowledgement is not proof that publication failed

These are ADR-0007 storage and publication rules. Installing from Git or OCI does not run publisher build scripts, checkout hooks or containers; an extension needing a build must provide prepared artifacts or a separately authorized build path.

6.2 Executing a command

Section titled “6.2 Executing a command”

Trigger: a caller invokes a declared command from the active profile.

Managed commands receive typed inputs parsed once. Explicit passthrough preserves the argument vector without shell interpretation; unrestricted arguments require authority for the whole target program. Aliases retain one canonical identity and scope. ADR-0002, ADR-0006

The sequence shows a successful managed execute. A failed check or accepted cancellation enters bounded finalization instead of following subsequent arrows.

Managed command invocation
Managed command invocationA managed execute with an optional language environment and one optional core operation. Finalization produces one outcome; failures and cancellation stop the successful path.Core facilitiesExtension processExecutorSecurity Broker and action admissionRuntime providerLifecycle ownerProfile and resource stateCommand model and dispatcherCore facilitiesExtension processExecutorSecurity Broker and action admissionRuntime providerLifecycle ownerProfile and resource stateCommand model and dispatcher1. Pin command, release and profile; normalize declared inputs once2. Create a checked immutable invocation3. If required: resolve an exact environment plan4. If preparation is needed: admit its declared effects5. If required: prepare, verify and acquire the environment6. Verify the required execution profile; start and confirm the managed session7. Dispatch execute once in the confirmed session8. If requested: submit a bound core operation9. Check current scope, task/budget and audit; declared effects use their commitment contract10. For that request: dispatch the admitted operation11. Report completion and termination evidence12. Return execution evidence for finalization13. After bounded cleanup and audit: one immutable outcomeManaged command invocationA managed execute with an optional language environment and one optional core operation. Finalization produces one outcome; failures and cancellation stop the successful path.Core facilitiesExtension processExecutorSecurity Broker and action admissionRuntime providerLifecycle ownerProfile and resource stateCommand model and dispatcherCore facilitiesExtension processExecutorSecurity Broker and action admissionRuntime providerLifecycle ownerProfile and resource stateCommand model and dispatcher1. Pin command, release and profile; normalize declared inputs once2. Create a checked immutable invocation3. If required: resolve an exact environment plan4. If preparation is needed: admit its declared effects5. If required: prepare, verify and acquire the environment6. Verify the required execution profile; start and confirm the managed session7. Dispatch execute once in the confirmed session8. If requested: submit a bound core operation9. Check current scope, task/budget and audit; declared effects use their commitment contract10. For that request: dispatch the admitted operation11. Report completion and termination evidence12. Return execution evidence for finalization13. After bounded cleanup and audit: one immutable outcome
Components and decisions

Command model and dispatcher · Lifecycle owner · Executor · Runtime provider · Security Broker and action admission · Core facilities · Profile and resource state · Extension process

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

Native execution needs no language provider unless its mapping requires an engine. For a ready script environment the provider verifies and acquires a reference; only an absent supported environment takes the authorized preparation path. ADR-0008

If two authorized calls need the same absent environment, the supported provider can share one preparation activity with its own fixed plan and deadline. Each waiter retains its own authorization and deadline; cancelling one does not cancel another’s valid demand. A lost preparation owner leaves incomplete state for reconciliation, not a ready cache entry or an automatic repeated installation. Sharing across core processes requires declared coordinator support; otherwise the competing request receives the defined bounded busy result. ADR-0008

For a managed process on Windows, the launcher must establish the private channel, approved handle inheritance and process supervision before releasing the suspended child. If the selected environment prevents that setup, it stops the child and closes the channel; it cannot switch to unprotected execution, stdout control messages or an unapproved transport. ADR-0003

Caller environmentData and interaction path
Interactive CLIThe core owns the terminal and grants input to the admitted dialog or view; a competing interaction does not take another call’s input
CLI in a pipeline or without a terminalRedirected bytes remain command data, diagnostics stay separate, and EOF is handled by the declared input contract. Required unsupported interaction fails instead of opening a hidden prompt or inventing an answer
MCPProtocol streams belong to the host adapter; the extension receives the declared machine inputs and returns a negotiated result. Its ordinary output is drained under the machine profile, not injected into the agent context as a guessed tool result

The paths share command semantics, but do not share terminal ownership or imply identical stream bindings. ADR-0002, ADR-0010, ADR-0013

6.3 Inspecting command help

Section titled “6.3 Inspecting command help”

Trigger: a caller requests help or static completion. Base help and static completion read declarations without an execution attempt. Optional contextual help is a separate describe invocation with its own permissions, an already ready environment and validated structured output. It never sends execute, installs a runtime or renews credentials. Base-help fallback, cancellation and errors retain ADR-0002 semantics.

6.4 Establishing and invalidating authority

Section titled “6.4 Establishing and invalidating authority”

Triggers: explicit sign-in or sign-out, credential renewal, a protected operation or an observed policy change.

Sign-in establishes a verified authority/subject binding, not a command grant. Token rotation neither replaces that identity nor extends its bound authentication horizon. Logout commits invalidation before cleanup; late renewal cannot restore the session. ADR-0011

Every protected action has a final admission point after slow checks and required audit. Pinned local policy, single-use external decisions and explicitly bounded reuse share this point. Observed revocation blocks new admission; stale replies cannot clear the recorded source barrier. Already admitted external effects cannot be assumed undone. ADR-0012

If required discovery fails, the caller receives an unavailable or incomplete result, not an empty successful catalog. If an access provider fails, new protected work needs evidence permitted by the already selected validity contract; failure cannot enable stale reuse or replace it with local rules. A required credential store that is locked or unavailable also fails explicitly, and a noninteractive call cannot unexpectedly open a store-unlock or sign-in prompt. Denial, inability to establish a decision and explicit authentication-required results retain their different meanings. ADR-0005, ADR-0011, ADR-0012

6.5 Invoking a tool through MCP

Section titled “6.5 Invoking a tool through MCP”

Trigger: an approved client lists the current tools and calls one exact advertised binding.

From MCP discovery to a command result
From MCP discovery to a command resultDiscovery runs no extension code. Exact tool binding and current caller/task authority are checked again for every call.Lifecycle ownerTask authority and shared budgetsCommand model and dispatcherMCP adapterAgent or machine clientLifecycle ownerTask authority and shared budgetsCommand model and dispatcherMCP adapterAgent or machine client1. Request the current authorized tool list2. Read the approved current projection without extension execution3. Return exact binding names and schemas4. Return the bounded tool list5. Call one advertised exact binding with data6. Bind the independent caller authority and task scope7. Reject stale binding; validate the common typed input8. Enter the same checked foreground lifecycle9. After execution and finalization: retain one outcome and optional result10. Return the committed machine result to the adapter11. If this request remains live without accepted client cancellation: map the result without replayFrom MCP discovery to a command resultDiscovery runs no extension code. Exact tool binding and current caller/task authority are checked again for every call.Lifecycle ownerTask authority and shared budgetsCommand model and dispatcherMCP adapterAgent or machine clientLifecycle ownerTask authority and shared budgetsCommand model and dispatcherMCP adapterAgent or machine client1. Request the current authorized tool list2. Read the approved current projection without extension execution3. Return exact binding names and schemas4. Return the bounded tool list5. Call one advertised exact binding with data6. Bind the independent caller authority and task scope7. Reject stale binding; validate the common typed input8. Enter the same checked foreground lifecycle9. After execution and finalization: retain one outcome and optional result10. Return the committed machine result to the adapter11. If this request remains live without accepted client cancellation: map the result without replay
Components and decisions

Command model and dispatcher · Lifecycle owner · Agent or machine client · MCP adapter · Task authority and shared budgets

ADR-0002 · ADR-0004 · ADR-0007 · ADR-0010 · ADR-0013 · ADR-0014

Listing returns the approved current projection without executing extension code. A call resolves its exact tool binding, validates structured inputs and binds the independently established caller and task. It enters the same foreground lifecycle as a CLI call. Connection metadata and model text cannot substitute for authentication. ADR-0013, ADR-0014

A stale binding, insufficient authority or unsupported interaction stops the path. Transport cancellation stops the response as required by the selected MCP transport, while the core still completes bounded finalization and records the outcome. Reconnection does not replay an invocation. A persistent MCP host does not imply detached extension jobs. ADR-0004, ADR-0013

6.6 Committing a consequential action

Section titled “6.6 Committing a consequential action”

Trigger: a command requests an operation governed by the effect contract. The diagram shows successful admission. Rejection, expired consent, cancellation or failed required audit stops the subsequent dispatch. An uncertain result retains its protective state.

A bounded consequential operation
A bounded consequential operationCurrent admission, shared reservation and durable effect state coordinate dispatch. An uncertain external result is observed, never repeated blindly.Protected resourcesCore facilitiesTask authority and shared budgetsSecurity Broker and action admissionProfile and resource stateEffect commitment and reconciliationLifecycle ownerProtected resourcesCore facilitiesTask authority and shared budgetsSecurity Broker and action admissionProfile and resource stateEffect commitment and reconciliationLifecycle owner1. Prepare exact effect and obtain bound authority or consent2. Persist the prepared binding; this does not admit dispatch3. Collect current permission, consent, resource and audit checks for final admission4. Validate task bindings and shared limits as part of the same admission transaction5. Coordinate task and revocation barriers within the same transaction; do not commit separately6. Atomically recheck admission and durably commit permit consumption, task reservation and dispatch intent7. Only after confirmed joint admission: dispatch the exact effect8. Execute under the resource-enforced conditions9. Return authoritative evidence or retain uncertainty10. Settle known costs or retain unknown state and reservations11. Optional separately authorized read-only reconciliation of existing effectA bounded consequential operationCurrent admission, shared reservation and durable effect state coordinate dispatch. An uncertain external result is observed, never repeated blindly.Protected resourcesCore facilitiesTask authority and shared budgetsSecurity Broker and action admissionProfile and resource stateEffect commitment and reconciliationLifecycle ownerProtected resourcesCore facilitiesTask authority and shared budgetsSecurity Broker and action admissionProfile and resource stateEffect commitment and reconciliationLifecycle owner1. Prepare exact effect and obtain bound authority or consent2. Persist the prepared binding; this does not admit dispatch3. Collect current permission, consent, resource and audit checks for final admission4. Validate task bindings and shared limits as part of the same admission transaction5. Coordinate task and revocation barriers within the same transaction; do not commit separately6. Atomically recheck admission and durably commit permit consumption, task reservation and dispatch intent7. Only after confirmed joint admission: dispatch the exact effect8. Execute under the resource-enforced conditions9. Return authoritative evidence or retain uncertainty10. Settle known costs or retain unknown state and reservations11. Optional separately authorized read-only reconciliation of existing effect
Components and decisions

Lifecycle owner · Security Broker and action admission · Core facilities · Profile and resource state · Protected resources · Task authority and shared budgets · Effect commitment and reconciliation

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

Preparation binds concrete resources and inputs; it does not reserve unrestricted future permission. At final admission the core rechecks authority and resource conditions and reserves the applicable shared task budget. Dispatch and reconciliation use a core-owned effect identity, never the transport request ID. ADR-0014, ADR-0016

After a lost response, the resource may already have changed. The core records uncertainty, prevents automatic repetition and uses an authorized read-only status operation where supported. No universal exactly-once or rollback guarantee is implied. Unsupported strict requirements are rejected before the action.

6.7 Cancellation, failure and finalization

Section titled “6.7 Cancellation, failure and finalization”

Triggers: caller cancellation, scope closure, an invocation deadline or a failure during any execution scenario. The lifecycle is Preparing → Starting → Running → Finalizing → Finished; earlier rejection, failure and cancellation also enter finalization. The first accepted cancellation cause wins. Finalization has one non-renewable budget. Outcomes are succeeded, command_failed, rejected, execution_failed or cancelled. Incomplete cleanup and uncertain effects remain explicit; there is no automatic command replay. ADR-0004

Finalization closes admission of new protected work. The core accounts for remaining output, required audit and resource use within the original budget. Later reconciliation may clarify an external effect, but cannot reopen the finished invocation or change its committed outcome. ADR-0002, ADR-0016

Admission capacity can be exhausted before an invocation exists; the host receives an admission error, not a fabricated command outcome or an unbounded queued attempt. During an admitted call, output and observation queues cannot consume the capacity reserved for cancellation and completion. If control cannot progress, the session fails and supervision bounds its stop. Closing the owning application scope stops new calls, finalizes admitted work and then disposes dependent owned instances within the remaining close budget. Unconfirmed cleanup remains reported and retains protective references. ADR-0003, ADR-0010

Diagram

Drag to move · + / − to zoom · 0 to fit · Esc to closeDrag to move and pinch to zoom

100%