Skip to content

ADR-0010: Core library and branded CLI composition

Status: Accepted — 2026-09-23. The project owner approved this decision. Acceptance establishes the architectural contract; it does not establish a completed implementation or successful execution of outstanding checks.

English | Русский

Refinement — 2026-09-24: shared CLI/MCP and agent-use additions are accepted under ADR-0013 and ADR-0014–0016. The original acceptance date and historical evidence remain unchanged; the new requirements are not claimed implemented or verified.

ADR-0002 requires an embeddable core that lets a CLI owner supply trusted operations and interface components. A company must be able to assemble its named CLI, common built-in commands and organizational integrations while teams publish ordinary extensions independently. A small team must also be able to ship a useful CLI with one static catalog, explicit local policy and no mandatory sign-in or external service.

The library boundary must distinguish code admitted by the CLI owner from data supplied by an extension, capabilities present in a build from permissions granted at runtime, and the application lifetime from one command invocation. Otherwise configuration can become executable registration, updating a profile can replace a running command’s services, or embedding can weaken terminal and lifecycle rules.

This ADR defines architectural responsibilities and logical API contracts. It does not select the core’s implementation language, package layout, callback signatures, binary ABI or widget toolkit. The Go/Python IPC experiments and Node.js website tools are not a language decision. ADR-0005–0009 and ADR-0011–0012 are accepted companion decisions.

  • One embeddable core for the simple catalog baseline and organizational integrations.
  • A small application boundary with explicit ownership, typed failures and no hidden process termination.
  • Owner-controlled registration with immutable capability and invocation bindings.
  • Validate the complete composition before initializing effects or exposing commands.
  • Preserve one terminal owner, bounded delivery, cancellation and required cleanup.
  • Version the library independently from extension formats, protocols and service contracts.
OptionBenefitLimitation
One configurable executable with every integration includedLittle assembly work for consumersMakes unrelated dependencies mandatory and still needs a clear trust boundary
A separate core fork for each branded CLIFull local controlDivergent contracts and repeated lifecycle/security maintenance
Load arbitrary integration code from runtime profiles or extension packagesEasy late customizationGives ordinary package installation privileged registration authority
Embeddable core with owner-built registrations and validated profilesShared semantics and small baseline with independent integrationsRequires explicit registration, ownership and compatibility contracts

Provide an embeddable core whose trusted implementation catalog is fixed when the owner assembles the application. Runtime profiles select and configure admitted implementations within owner policy. Ordinary extensions consume declared facilities and never register privileged code.

The branded application supplies its name, version, visible identity, approved defaults and host bindings. The core owns command resolution, invocation admission, authorization gates, execution lifecycle and presentation policy. Owner-supplied integrations implement narrowly declared roles behind that core. These are logical modules; this decision requires neither separate packages nor separate processes for each role.

BoundaryResponsibility
Application hostReceives arguments and host cancellation, supplies approved streams/terminal and storage bindings, creates execution scopes, waits for outcomes, maps them to CLI status and disposes the core
Core compositionValidates registrations and dependency graph, selects compatible contracts, creates owned instances and publishes usable capabilities
Command and invocation coreResolves canonical identities, parses once, applies support/access checks, pins bindings and owns ADR-0004 lifecycle transitions
Registered integrationsImplement discovery, identity, authorization, source access, runtime preparation, executors, storage, credential storage, audit or specific core operations under their declared contracts
Presentation coreOwns terminal input, stream routing, dialogs, managed views and versioned trusted component implementations
Built-in commandsOwner-shipped handlers with static declarations and canonical identities, invoked through the same command/admission boundary
Ordinary extensionsVerified release declarations and separately executed handlers under ADR-0001–0004, with no registration or application-host handle

The baseline includes a static catalog reader, explicit local policy, supported process execution, local profile storage and standard presentation. Native extensions need no runtime manager. Identity, remote catalogs, external authorization and custom operations are optional owner additions. Headless embedding can omit interactive presentation and advertise that absence; it cannot claim required interaction support or silently answer prompts. Only capabilities actually usable under the selected build, profile and host binding are advertised.

This selected view identifies authority and dependency boundaries, not a deployment topology.

Accepted composition of a branded CLI
Accepted composition of a branded CLIThe owner assembles trusted implementations into a fixed build catalog. A host creates the core with an approved runtime profile. Built-in commands and ordinary extensions use the same checked invocation boundary. Only trusted implementations can provide services and terminal components.CLI ownerImmutable build capabilitycatalogEmbeddable coreBranded application hostApproved runtime profileDeclared built-in commandsOrdinary extensionsTrusted service and providerinstancesTerminal and standard orowner componentsAdmits implementation codeKnown registrationsArguments, scope and hostbindingsSelects and narrows capabilitiesChecked invocationDeclared requests and captureddataAuthorized scoped dispatchSole interaction ownerAccepted composition of a branded CLIThe owner assembles trusted implementations into a fixed build catalog. A host creates the core with an approved runtime profile. Built-in commands and ordinary extensions use the same checked invocation boundary. Only trusted implementations can provide services and terminal components.CLI ownerImmutable build capabilitycatalogEmbeddable coreBranded application hostApproved runtime profileDeclared built-in commandsOrdinary extensionsTrusted service and providerinstancesTerminal and standard orowner componentsAdmits implementation codeKnown registrationsArguments, scope and hostbindingsSelects and narrows capabilitiesChecked invocationDeclared requests and captureddataAuthorized scoped dispatchSole interaction owner

CLI and agent application hosts — 2026-09-24

Section titled “CLI and agent application hosts — 2026-09-24”

ADR-0013 adds an owner-admitted MCP adapter to the application boundary. It projects already installed and active declarations into tools, derives caller context from its trusted host binding and uses the ordinary core invocation API. It cannot call executor internals or privileged service handlers directly. The same core can support CLI and MCP presentations; neither ordinary extensions nor runtime settings register new adapter code.

The local baseline is a stdio mode of the named CLI, with a local catalog, explicit local policy and an approved task preset. It needs no separate service, database or organization account. MCP protocol streams belong exclusively to the adapter; child command streams are separately routed. A longer-lived MCP host owns multiple bounded foreground scopes under the existing application lifetime, not detached extension work. Closing the host stops admission and finalizes its scopes; transport delivery uncertainty does not cause automatic redispatch.

The fixed build catalog can include trusted task-authority, confinement and effect-coordination implementations from ADR-0014, ADR-0015 and ADR-0016. Profiles select their actually supported guarantees and finite budgets. Optional infrastructure remains optional; a required guarantee cannot be disabled when a provider is missing. A host-trusted native profile is explicit about ambient OS authority. A stricter profile must have verified enforcement; merely exposing a command through MCP adds none.

The core’s canonical invocation preparation now has two trusted input adapters: CLI lexical parsing and typed machine inputs. Both preserve explicit parameter IDs, share semantic validation and pin the same command/profile contracts. Host-created task authority is separate from an extension’s parameters and from ExecutionScope. Delegation and profile administration remain protected owner-defined operations, excluded from general agent tool sets. Model planning and model-provider execution are outside the core’s required responsibilities.

Registration is an application assembly operation available only to the trusted composition code. The owner explicitly includes built-in implementations or linked integration modules. There is no runtime import path, package-manager hook, downloaded library name or executable expression in the profile. New implementation code requires a new approved application build. A new connection profile for already admitted code need not require rebuilding.

Assembly produces an immutable buildCapabilityCatalog, identified by buildCapabilityCatalogDigest over its exact serialized metadata, and a separate buildIdentity for the approved application artifact. The digest describes admitted contracts and implementation identities; by itself it proves neither authenticity nor that the application contains those bytes. The owner’s build/distribution trust establishes that binding. The advertised diagnostic view excludes secrets and private connection settings.

Registration fieldRequired meaning
registrationId, kindUnique owner-qualified ID and one of the known registration kinds; a multi-role adapter declares each role explicitly
implementationIdentityExact owner-admitted module/build identity and version, bound to the application build; display name or mutable package tag is insufficient
providedContractsStable namespaced contract IDs, exact supported versions and features; operation registrations include input/result schemas and trusted action/resource derivation
dependenciesExplicit required and optional registration/contract references with compatible versions and scopes; no dependency inferred from registration order
configurationContractStrict schema, sensitive fields represented as protected references, allowed endpoints/sources and limits controlled by the owner
lifetimeApplication, profile or invocation ownership, concurrency guarantees and whether the core owns the instance or borrows it from the host
initialization, disposalBounded initialization/cleanup behavior, cancellation support, resources created and any supported supervised-helper binding
failureContractTyped safe errors, effect uncertainty, readiness requirements and supported mandatory audit/cleanup guarantees

registrationId uses an owner namespace plus a local identifier under ADR-0006 rules; kinds and contract IDs are validated by the trusted registry. Duplicate IDs, conflicting operation ownership, undeclared dependency edges, unsupported versions and dependency cycles reject assembly. Two implementations of one contract may coexist, but a profile must resolve each required role to one unambiguous binding. There is no last-registration-wins override, implicit union of authorization providers or privileged internal function lookup by string.

Optional dependencies have explicit absence behavior. If an optional provider is not selected, the dependent optional facility is absent from effective capabilities. A required command/service dependency cannot be relabelled optional after a failure. Dependency injection supplies only declared handles in their declared scope; a service does not receive the whole mutable registry. Longer-lived instances cannot retain shorter-lived invocation handles. Application-scoped instances cannot capture a profile’s mutable subject or credentials.

The catalog freezes before the first profile is initialized. Core instances cannot mutate it after startup, including through built-in command callbacks. Runtime profile changes can create new instances of already registered implementations, but cannot append registrations. Plugins that would dynamically load privileged implementation code are outside this decision.

Runtime profile and configuration precedence

Section titled “Runtime profile and configuration precedence”

A runtime profile is validated data selecting catalog entries and their configuration. It binds approved sources, access domains, provider registrations, command mounts, trust, quotas, audit requirements, presentation settings and the explicit local/identity choice. It cannot broaden the owner’s build constraints. A declared feature is supported only by the intersection of build capabilities, selected profile and actual host/platform support; this support result does not grant permission to use it.

InputAuthority and precedence
Owner build constraintsEstablish permitted implementations, mandatory authorities, non-overridable limits and trusted configuration publishers
Approved owner profileSelects registered implementations and exact configuration revisions within those constraints; can impose narrower rules
Owner-delegated local settingsAffect only explicitly delegated fields, such as a permitted locale, an approved profile choice or a narrower resource limit
Environment and CLI flagsOverride delegated presentation/execution preferences in the order defaults, local settings, allowlisted environment, explicit flags; they cannot alter non-delegated security fields
Extension/catalog metadataSupplies declarations and requests under its own schema; it has no owner-configuration precedence

This is field-specific precedence, not a deep merge of arbitrary documents. Each accepted value retains its source for safe diagnostics. Flags or environment variables cannot register a provider, add a trust root or source, replace an access authority, enable undeclared operations, raise an owner limit, suppress required audit or weaken a validity requirement. A forbidden override is a typed configuration error, not silently ignored input. User selection of another approved profile still preserves required authority/source bindings.

An explicitly delegated source/profile administration action may propose new data through the normal authorized configuration transaction. A generic --config path or environment variable is not that authority. In the smallest owner-operated CLI, the owner may deliberately delegate local profile maintenance to the user; the resulting local policy controls core-mediated actions and does not establish trust at a remote corporate service.

ownerConfigRevision identifies the exact immutable owner configuration, including provider selections/settings and the relevant build catalog binding. ADR-0005’s configRevision is its alias. activeProfileRevision is the digest of ADR-0007’s immutable profile record containing both ownerConfigRevision and commandGeneration; it is the only active pointer. The command generation includes built-in and extension declarations, routes, aliases and exact implementation/release bindings. A policy-only update must revalidate the retained generation before committing the pair. New invocations capture one committed pair and protective references through the same storage boundary.

Profile changes never rewrite an existing invocation’s subject, principal binding, command/release, operation contract or service implementation. The same registration ID with different configuration or implementation is a different binding. A changed provider does not silently take over old invocations. Their further protected actions must pass ADR-0012’s current validity/admission check within the original scope. If the current profile no longer admits the pinned bindings, return context_invalidated; retaining an instance for cleanup does not retain revoked authority. Explicitly selecting another account only affects eligible new contexts under ADR-0011.

Startup, dependency validation and profile publication

Section titled “Startup, dependency validation and profile publication”

Composition has a validation phase and an initialization phase. Registration metadata and the complete candidate profile graph are checked before implementation factories or initialization callbacks run. Validation does not create browser sign-in, invoke commands, install runtimes, execute extensions or contact arbitrary provider-selected destinations. A factory has no authority merely because validation is in progress.

  1. Parse bounded trusted inputs and validate the host storage binding. Read and verify existing profile data without repairs or publication; record any required recovery. Corruption never chooses an older policy or an implicit public profile.
  2. Validate catalog identities, schemas, lifetimes, required/optional dependencies, source/authority restrictions and all selected configuration. Compute the dependency order and effective capabilities. Validate the complete candidate command tree, including built-ins and reserved help routes.
  3. Perform any required profile recovery through the validated storage binding, then initialize selected providers in dependency order using scoped handles, a common startup deadline and explicit owner budgets. Only declared initialization effects are allowed: owned local resources and approved connection setup. Sign-in, catalog update, package/runtime installation and protected domain actions require their own explicit operations.
  4. Confirm required readiness and revalidate the expected profile revision before publication. If all requirements hold, publish the configuration/command pair through ADR-0007, or attach to the already committed identical pair without creating a fake update. Only then admit invocations.

Validation is a gate before initialization effects, not a claim that remote availability can be proven without an attempted connection. An unavailable mandatory integration fails startup or candidate application explicitly. A supported lazy provider can defer connection creation until an operation only if its registered contract permits this and all required startup guarantees still hold. There is no fallback to a weaker provider. Base help does not initialize command runtimes or start sign-in; policy-dependent visibility may return a typed unavailable result.

Initialization failure disposes successfully initialized owned instances in reverse dependency order under one bounded cleanup deadline and exposes no candidate commands. An existing active profile remains the current record unless publication is confirmed, but its validity is not extended by the candidate failure. Publication uncertainty follows ADR-0007’s commit_unknown reconciliation, not a false claim of rollback. Borrowed host instances are released according to their explicit lease contract, never implicitly destroyed.

This selected sequence separates validation, initialization effects and usable publication. It applies to startup and to candidate profile application; the existing profile need not stop serving during preparation.

Accepted validated initialization and publication
Accepted validated initialization and publicationThe host supplies a fixed build and candidate profile. The core validates the full dependency graph before initializing selected providers. Failure cleans up owned instances. Successful initialization permits one profile commit before commands become available.Profile storageRegistered providersCore compositionApplication hostProfile storageRegistered providersCore compositionApplication hostalt[Required initialization failed][Ready]alt[Invalid composition][Valid composition]Build catalog, candidate profile and host bindingsValidate graph, authority, contracts and command treeTyped validation error without provider initializationInitialize in dependency order with bounded scopeDispose owned instances in reverse orderInitialization error and cleanup evidenceCompare expected revision and commit complete profileCommitted revision or typed publication resultReady handle only for a confirmed usable profileAccepted validated initialization and publicationThe host supplies a fixed build and candidate profile. The core validates the full dependency graph before initializing selected providers. Failure cleans up owned instances. Successful initialization permits one profile commit before commands become available.Profile storageRegistered providersCore compositionApplication hostProfile storageRegistered providersCore compositionApplication hostalt[Required initialization failed][Ready]alt[Invalid composition][Valid composition]Build catalog, candidate profile and host bindingsValidate graph, authority, contracts and command treeTyped validation error without provider initializationInitialize in dependency order with bounded scopeDispose owned instances in reverse orderInitialization error and cleanup evidenceCompare expected revision and commit complete profileCommitted revision or typed publication resultReady handle only for a confirmed usable profile

Built-in commands and trusted implementation limits

Section titled “Built-in commands and trusted implementation limits”

Built-ins use owner-admitted static declarations equivalent in meaning to ADR-0006 command metadata: canonical owner/package/command identity, built-in build reference, input schema, requirements, aliases and separate execute/describe support. A built-in build reference identifies its exact owner-shipped code; it is not a fabricated extension release envelope. Routing and authorization do not distinguish a built-in through its spelling, installation order or a hidden bypass. Collisions with ordinary extensions reject the candidate tree.

Built-ins receive validated inputs, scoped services and a lifecycle context. They return structured completion evidence to the lifecycle owner; they do not commit their own final outcome. Required access, action/resource derivation, required audit, cancellation, deadlines and cleanup apply as they do for external handlers. Bootstrap commands such as sign-in/configuration inspection have explicitly registered local access actions and bounded disclosures; they do not acquire all organizational permissions to break a dependency cycle. Base help remains data-driven.

Owner-shipped in-process handlers and integrations are trusted code with the application’s process authority. Scoped handles and contract checks structure their intended use; they are not a sandbox against a malicious or defective implementation. Calling them built-ins does not make OS access, memory isolation or forced termination safe. Ordinary extensions cannot promote themselves into this path, register trusted renderers, replace input handling or obtain registry/composition handles.

In-process handlers must cooperate with cancellation, avoid blocking the lifecycle/terminal dispatcher and bound completion and disposal. An implementation that can block indefinitely, retain invocation resources after disposal or run uncooperative native callbacks is unsupported in this binding. Such work requires an explicitly registered supervised helper/executor with verified stopping and effect-reporting semantics. Merely running the callback on another thread does not establish those guarantees. The owner must not advertise hard cancellation guarantees that the selected binding cannot provide. Process supervision retains ADR-0001/0003’s ordinary-process isolation limits.

Logical library surface and application lifetime

Section titled “Logical library surface and application lifetime”

The following are logical operations and result types, not selected method names or language signatures. A language-specific SDK may group them differently while preserving the ownership and failure contracts.

OperationContract
Assemble and validateConsume trusted registrations and candidate data, return an immutable validated composition or bounded diagnostics; no invocation or provider initialization
Initialize/open coreCreate owned instances and attach/publish the verified profile, return a ready CoreRuntime or typed startup failure with cleanup evidence
Inspect help/capabilitiesReturn permitted static information and declared support without executing extensions, preparing runtimes or starting authentication
Begin invocationResolve and pin one command/kind/context under an explicit ExecutionScope, return one InvocationHandle or a pre-admission error
Observe / waitObserve bounded phase information or wait for the same final typed outcome; observation cannot consume the outcome or transfer lifecycle ownership
Request cancellationReturn accepted or too-late acknowledgement; the first accepted cause and final outcome follow ADR-0004
Apply profileValidate and prepare a complete candidate, then use the shared profile transaction; return ADR-0009’s configuration result
Close scope/coreStop new admission, request owner_shutdown for owned active attempts, finalize them, then release owned instances and return cleanup evidence

Beginning an invocation allocates invocationId once an attempt is admitted. A valid request that then fails input/support/pre-launch checks reaches the existing rejected outcome after required cleanup. Malformed library requests, a closing runtime or exceeded admission capacity can fail before an attempt exists. These API errors have no invented invocation outcome. A successfully admitted attempt retains exactly one ADR-0002 outcome, including diagnostic evidence for uncertain effects and incomplete cleanup.

The library returns outcomes and never calls process.exit, terminates the embedding application, mutates global signal handlers or claims process-wide stdin/stdout as an implicit singleton. The host explicitly installs OS cancellation handling, delegates the intended terminal and translates committed outcomes to ADR-0003 CLI exit statuses. The core handles Ctrl-C only for an explicitly delegated active terminal. A host exception or an abandoned observer does not automatically cancel work; an explicit scope close does. Unrecoverable process failure cannot manufacture a committed result.

Every owned resource has one lifetime owner. Invocation resources end during that invocation’s bounded finalization. Profile instances remain retained while referenced by active/protective contexts; retirement stops new binding and waits for confirmed release. Application instances end after dependent profiles and attempts. Shared instances have explicit concurrency and lease contracts. Disposal is idempotent for the same handle and reports already closed without running cleanup twice. A failed or uncertain stop retains protective release/environment references under ADR-0007/0008, even after the core reports incomplete closure.

The host supplies finite startup and close budgets. The baseline defaults are 10 seconds for initialization and 10 seconds for whole-core closure, using monotonic time; these are design defaults, not measured performance. Each invocation keeps its own non-renewable finalization deadline, including ADR-0003’s five-second process shutdown budget, bounded by any earlier parent scope deadline. Repeated close/cancel calls do not renew deadlines. Core closure first closes admission, then settles active attempts concurrently within their budgets, then disposes dependent instances with the remaining core budget. A budget that expires reports incomplete cleanup and uncertain state, never successful disposal by assumption.

This selected lifecycle is for the library instance. It does not replace the phases of each command attempt or introduce background execution.

Accepted core instance ownership
Accepted core instance ownershipA validated composition initializes a core that admits foreground attempts. Closing stops admission and finalizes owned work before disposal. Initialization failure also enters disposal. Closure records cleanup evidence even when incomplete and never reopens the instance.Validated compositionInitializing owned instancesReady to admit invocationsClosing admission and scopesDisposing owned instancesClosed with cleanup evidenceHost opens the coreRequired readiness and profileconfirmedFailure or cancellationHost closes core or its owningscopeAttempts finalized or budgetexhaustedRecord disposal resultAccepted core instance ownershipA validated composition initializes a core that admits foreground attempts. Closing stops admission and finalizes owned work before disposal. Initialization failure also enters disposal. Closure records cleanup evidence even when incomplete and never reopens the instance.Validated compositionInitializing owned instancesReady to admit invocationsClosing admission and scopesDisposing owned instancesClosed with cleanup evidenceHost opens the coreRequired readiness and profileconfirmedFailure or cancellationHost closes core or its owningscopeAttempts finalized or budgetexhaustedRecord disposal result

Concurrency, terminal bindings and event delivery

Section titled “Concurrency, terminal bindings and event delivery”

A CoreRuntime may own several foreground invocation scopes. The host must keep the owning scope alive and await closure; asynchronous library handles are not detach/background support. The baseline admits at most 16 concurrent attempts and retains at most 256 invocation handles, including finished results, per core. There is no implicit wait queue; excess admission returns capacity_exceeded. The host explicitly releases finished handles, which never removes protective resource references needed for uncertain cleanup. An owner may configure other finite supported limits. State transitions and protected-action admission remain serialized by each lifecycle owner, while stream transfer and independent work may proceed concurrently.

A TerminalBinding identifies one host-delegated terminal and has one presentation coordinator and one foreground input owner. The same terminal cannot be independently owned by two core instances. The host must share one coordinator or give them distinct/noninteractive bindings; conflicting ownership returns terminal_in_use. Ordinary command output may be coordinated from concurrent invocations, while redirected stdout remains separate data. Only the active invocation’s approved view/dialog receives interactive input.

These are bounded logical library bindings between the core, host and trusted renderer. They do not define another extension transport or silently add managed-view event encoding to ADR-0003. A process extension can use a UI facility only when an explicitly supported versioned transport mapping provides its required delivery semantics. A missing mapping is unsupported, even if a widget exists inside the build.

ChannelDelivery and baseline bound
Phase observationAt most 64 pending observations per observer and 8 observers per invocation; intermediate phases may be coalesced with an explicit gap marker. The committed result is separately retrievable until the host releases its handle
Managed-view inputOrdered by core-issued sequence with invocation/view/component IDs and state revision. Per view, at most 128 queued events or 256 KiB, whichever is reached first; consequential input is not silently dropped or coalesced
Dialog answerOne typed result for the bound dialog request, never a lossy event. Secret fields follow ADR-0002 and are excluded from general observer streams and persisted view state
Visual state updateReplaceable updates may be coalesced only within the same view/component contract; replacement cannot discard a submission, answer or action requiring acknowledgement
Foreground interaction admissionDefault competing requests return interaction_busy. An owner can enable a queue of at most 8 requests per terminal with bounded request deadlines; no unbounded wait or hidden terminal

The baseline permits 8 managed views per invocation, with at most 1,024 components and 1 MiB of non-secret serialized state per view; smaller negotiated binding limits still apply. Managed-view input delivery has a five-second default acknowledgement deadline, shortened by the interaction/invocation deadline. The logical binding chooses one pull consumer or one serial callback consumer for a view; not both competing for the same event. An acknowledgement means receipt by that consumer, not completion or authorization of the requested domain action. Each event is dispatched to its selected consumer at most once in that binding. If delivery/acknowledgement becomes uncertain, no consequential action is automatically replayed: close the affected interaction with interaction_delivery_failed, invalidate its pending input and retain the invocation’s ordinary outcome rules. Reopening a view creates a new handle/revision context, not a resume stream.

The core reserves independent capacity for cancellation, completion and required control results; a full observation/UI queue cannot block those paths. Callbacks execute outside lifecycle and terminal locks, may not hold a lock while waiting for a core operation, and obey the cooperative implementation contract. If the host cannot maintain delivery, it receives a typed failure rather than an ever-growing queue. These bounds describe the selected logical contract, not measured throughput or a completed renderer.

A child dialog explicitly belongs to the current view. Its parent input is suspended, and the child does not wait behind its own parent’s focus request. Nesting is limited to one child dialog in the baseline. Completion, cancellation or finalization closes the invocation’s interactions, rejects late events and restores only valid remaining focus. Required terminal cleanup failure prevents success under ADR-0002. No view binding exposes raw terminal handles, other invocations’ keystrokes or a way to override core cancellation.

Version boundaryCompatibility rule
Core library APIThe eventual SDK declares a major API version and exact supported contract versions. A breaking ownership, input, error or cancellation change requires a new API major and deliberate host migration
Branded application buildOwner version plus exact build identity and capability catalog binding. A new application version does not imply new extension protocol support
Registration/operation/component contractVersioned independently, with explicit supported versions and mandatory features. A handler/component is selected before invocation, never by guessing the closest version
Extension descriptors, release/profile storage and catalog dataKeep ADR-0006–0009’s separate format versions and migration rules; a library update cannot reinterpret verified bytes in place
Interaction, process transport and executor mappingKeep ADR-0002/0003 version/feature negotiation. SDK source compatibility does not prove protocol interoperability or another executor’s conformance

No cross-language ABI, stable binary plugin interface or shared version number across these boundaries is promised. Exact language signatures, packaging and supported language bindings require a separate implementation decision. Existing compatibility ranges in extension declarations are checked against the advertised core contract/build version, not a website package version.

Composition/startup errors use stable categories invalid_configuration, untrusted_configuration, duplicate_registration, dependency_missing, dependency_cycle, lifetime_mismatch, unsupported_contract, initialization_failed, deadline_exceeded, cancelled and cleanup_incomplete. API admission can additionally return invalid_request, core_closing, capacity_exceeded or terminal_in_use. Existing profile, operation, authorization and invocation errors retain their own contracts; this list does not replace them. Error records include the stage, safe registration/field reference, primary cause and cleanup/effect uncertainty without secrets or raw provider responses. A returned startup error never implies that every initialization effect was undone.

  • A small owner can assemble one catalog, local policy and built-ins, then add organizational providers without changing extension semantics.
  • New privileged implementation code requires an approved build; ordinary profile and catalog changes remain data operations with a shared atomic activation boundary.
  • Embedding gives the host explicit control over scope, streams and exit behavior, at the cost of owning shutdown and terminal delegation correctly.
  • Pinned instances can outlive their active profile for cleanup, so reference accounting and bounded retirement are required. This retention confers no continuing permission.
  • In-process integrations remain trusted and cooperative. Strong stopping guarantees for uncooperative work require an appropriate supervised binding, not an optimistic library timeout.
  • The logical API, default bounds and compatibility rules still require an implementation and SDK-specific design. This ADR supplies no product library or language selection.

The 2026-09-24 refinement checks remain unrun. Verify the shared CLI/MCP path, unsupported result-feature rejection, current profile/task binding, bounded data, absence of replay and channel separation within this ADR’s responsibility. Historical results below do not cover these additions.

The project owner accepted this decision on 2026-09-23. The following list remains required implementation verification, not a claim that these checks passed at acceptance.

For implementation verification, build a focused reference composition and check:

  1. A named CLI with a static catalog, explicit local policy and built-in command works without sign-in, a broker server or runtime manager. Replacing local discovery/access with admitted providers preserves command and extension contracts.
  2. Duplicate/cyclic registrations, lifetime mismatches, route conflicts, unknown contracts and forbidden flag/environment overrides fail before provider initialization or command exposure. Ordinary extension metadata cannot register code or alter owner authority.
  3. Initialization failure disposes only owned instances in reverse dependency order. A profile change publishes one configuration/command pair, preserves pinned invocation identity/implementations and refuses further actions when those bindings cease to be admitted. Uncertain publication is reconciled, not retried blindly.
  4. Concurrent foreground invocations, scope closure, delayed callbacks, full queues and cancellation races retain one typed outcome and fixed deadlines. Competing terminal ownership fails, parent/child focus cannot deadlock, consequential input is not replayed and finalization releases input within its budget.
  5. Embed the core in a host that continues after a failed command. It receives typed results without process termination/global signal changes, reports incomplete cleanup honestly and retains protective references when stopping is uncertain. Demonstrate that an uncooperative callback is refused by the in-process contract or placed behind the declared supervised binding.
  6. Change SDK API, component/service contract and extension protocol versions independently. Unsupported combinations fail explicitly; a matching application or package version does not bypass compatibility checks.

These product behavior checks have not been run for ADR-0010. Document/diagram checks, if performed, establish only the readability and consistency of this decision. The architecture is accepted; choosing a language and implementing an embeddable SDK remain separate work.

Diagram

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

100%