ARCH-29 policy-owning provider microkernel

Decision status: Accepted

Implementation status: Target architecture; this record does not implement it.

ARCH-29 supplements ARCH-23 native runtime and governed CLI tools through ARCH-27 governed specialist CLI skills. Tyrum's native runtime remains the only conversation-turn executor. Typed providers may supply bounded strategies and effects, but they do not replace the turn state machine or Tyrum's governance loop.

Quick orientation

• Read this if: you are designing provider contracts, process confinement, memory, context assembly, or another replaceable runtime seam.
• Skip this if: you only need the current process.run mechanics; use ARCH-24 governed process capability.
• Go deeper: use Memory, Context, Compaction, and Pruning, Gateway plugins, and Sandbox and policy.

Decision snapshot

Tyrum will use a small policy-owning microkernel with typed provider-kind contracts. Provider implementations perform specialized operations. The kernel retains canonical semantics, selection, governance, and externally visible state transitions.

There is no universal operational Provider interface. Provider kinds share control-plane semantics but retain deliberately different typed domain contracts.

Current and target truth

Boundary	Current implementation	Target architecture
Conversation turns	The native Tyrum runtime owns turn execution and governance.	Unchanged. The complete turn executor is not a provider.
Process execution	process.run invokes runLocalProcess; background execution independently resolves the same local_spawn baseline. Hardened confinement is unavailable.	Existing process tools resolve one operator-selected isolation provider behind their current public contracts.
Memory	Stable MCP-native memory tools and pre-turn hydration expose provider-like behavior, while built-in storage and runtime paths remain concrete.	One typed primary-memory binding per selection scope, with current behavior represented as a built-in provider.
Context	Prompt assembly, pruning, and compaction are concrete kernel paths.	Ordered typed context strategies contribute bounded material; the kernel owns final assembly and safety.
Extensibility	Plugins, MCP servers, model configuration, secrets, and other modules each use local extension patterns.	Shared control-plane mechanics are extracted only where accepted provider-kind contracts prove they are common.

Decision

1. Tyrum remains the policy-owning kernel. It owns canonical identifiers, scopes, requests, outcomes, state transitions, provider bindings, identity propagation, authorization, policy, approvals, deadlines, cancellation, shutdown, and canonical audit-event creation.
2. Provider kinds have typed domain contracts. Isolation, primary memory, and context are different contracts with different cardinality, lifecycle, consistency, and failure semantics.
3. Built-ins and external implementations use the same path. Built-in defaults must pass the same registration, validation, compatibility, resolution, binding, health, lifecycle, and conformance rules as external providers.
4. Bindings are explicit and stable. The kernel resolves a compatible provider before an operation starts and keeps that binding immutable for the operation. A provider cannot select itself or rewrite the binding.
5. Cardinality is part of each contract. Every provider kind declares whether it is exclusive, additive, ordered-many, fan-out, or capability-routed. Composition is never inferred from implementation count.
6. Contracts precede framework code. Tyrum first defines the isolation, primary-memory, and context contracts. It then extracts only the shared provider substrate those three contracts demonstrably require.
7. Governance is not delegated. A provider may calculate a recommendation, perform a specialized operation, or create an external effect. It cannot own Tyrum's enforcement invariants or externally visible state-machine guarantees.

Kernel and provider ownership

Kernel-owned	Provider-owned within its typed contract
Canonical provider-kind, implementation, binding, operation, and resource identifiers	Specialized strategy or external effect
Canonical request, result, error, and state-transition types	Domain-specific resource handles and internal mechanics
Provider catalog, compatibility admission, configuration binding, and immutable operation binding	Resource acquisition and release after admission
Identity propagation, authorization, policy, approval, and secret-reference resolution	Use of only the explicitly projected identity, configuration, and secret material
Deadlines, cancellation intent, shutdown coordination, and final settlement rules	Timely cancellation, cleanup, and shutdown behavior required by the contract
Canonical audit-event creation and externally visible observability	Domain telemetry and safe diagnostic details consumed by the kernel
Final prompt assembly, tool exposure, and native turn state machine	Bounded context or operation output; never direct mutation of kernel-owned state

Providers must not create alternate policy paths, approval stores, audit authorities, identity systems, or turn state machines. An integration for policy, identity, approvals, secrets, or audit may itself be replaceable, but Tyrum still performs the enforcement step and owns the canonical outcome.

Shared provider control plane

The anchor contracts are expected to require a small common control plane:

• provider-kind and implementation descriptors;
• built-in and external registration through one catalog path;
• configuration schemas and secret references without resolved secret values;
• compatibility and contract-version admission before activation;
• trust and deployment-mode declaration;
• deterministic selection and immutable operation bindings;
• installed, configured, ready, healthy, and capable state reporting;
• lifecycle, deadline, cancellation, and shutdown coordination;
• canonical error translation, observability, and audit correlation;
• provider-kind conformance suites.

This list defines required semantics, not a pre-approved generic framework or storage schema. Shared types and machinery may be introduced only after the three anchor contracts show identical meaning. A similarly named field with different lifecycle or trust semantics remains domain-specific.

Plugins are a packaging and trusted-code-loading mechanism, not the provider contract. A provider may later be delivered by a plugin, built into the gateway, or hosted out of process, but every delivery form must enter through the provider kind's own admission and conformance path. MCP is likewise a transport or capability boundary, not a universal provider type.

Contract definition requirements

Every provider-kind decision must define the following before implementation begins:

Contract field	Required decision
Purpose and exclusions	The replaceable behavior and what remains outside the provider.
Ownership	Kernel-owned and provider-owned state, decisions, and effects.
Cardinality	Exclusive, additive, ordered-many, fan-out, or capability-routed.
Selection scope	Deployment, tenant, workspace, agent, conversation, profile, operation, or another explicit scope.
Trust and deployment mode	In-process trusted code, local out-of-process service, remote service, or another admitted mode.
Operations	Required and optional operations with typed inputs and outputs.
Canonical types	Stable identifiers, requests, outcomes, states, and resource handles.
Lifecycle	Construction, readiness, resource ownership, cancellation, shutdown, and cleanup.
Configuration and secrets	Schema, validation, secret references, projection, and update behavior.
Capability state	The meaning of installed, configured, ready, healthy, capable, and degraded.
Errors and retries	Canonical error taxonomy, retryability, backoff ownership, and terminal failures.
Time bounds	Deadlines, cancellation acknowledgement, hard settlement, and shutdown bounds.
Invocation semantics	Idempotency, concurrency, ordering, duplicate requests, and replay behavior.
Persistence	Source of truth, consistency, transaction boundary, retention, and recovery.
Observability and audit	Correlation, safe metrics/logs, canonical events, and prohibited sensitive output.
Versioning	Contract version, implementation compatibility range, upgrade, and rejection behavior.
Degraded behavior	Explicit fallback, fail-closed behavior, partial availability, and recovery.
Built-in default	Default implementation and its truthful capability posture.
Conformance	Provider-kind tests and acceptance evidence required for activation.

A provider kind is not accepted while any material row is left to implementation convention.

Cardinality vocabulary

Cardinality	Meaning
Exclusive	Exactly one implementation is bound for the selection scope.
Additive	Every admitted implementation may contribute independently; order is not semantically significant.
Ordered-many	Multiple implementations run in a deterministic kernel-owned order with explicit merge rules.
Fan-out	The kernel invokes a defined set and aggregates typed outcomes.
Capability-routed	The kernel chooses a compatible implementation from declared capabilities for each operation.

Anchor contract 1: process isolation

The isolation provider supplies the execution boundary behind existing process tools. It does not replace process admission or governance.

• Cardinality: exclusive for the resolved process profile.
• Selection: operator-authored deployment and execution-profile configuration. The model cannot name, choose, or downgrade the provider through process.run or process.start arguments.
• Public compatibility: existing model-facing process tool IDs, request schemas, result schemas, policy targets, approval identity, and audit semantics remain stable unless a separate contract change is accepted.
• Kernel ownership: request validation, workspace admission, tool exposure, policy, approval, secret projection, canonical lifecycle state, deadlines, cancellation intent, bounded evidence, and audit.
• Provider ownership: creation of the actual execution boundary, process start/attach/terminate mechanics, stream transport, resource cleanup, and truthful capability evidence.
• Built-in default: current local_spawn behavior becomes the built-in baseline provider. It must continue to report that hardened confinement is unavailable.
• Confined implementation: the first confined implementation must enforce at least one accepted hardened profile and prove every claimed filesystem, network, process, resource, and daemon boundary with provider-specific acceptance evidence.
• Failure behavior: when a profile requires confinement the selected provider cannot supply, admission fails closed. There is no silent fallback from a confined provider to local_spawn.
• Lifecycle consistency: foreground and durable-background tools must use the same resolved provider semantics. Background reconciliation cannot reconstruct a different provider binding after restart.

The first implementation slice preserves process.run, process.start, process.get, process.logs, and process.cancel as the model-visible capability family. Node placement is not required for confinement; an isolation provider may be local or remote only when its contract and deployment mode explicitly support that topology.

Anchor contract 2: primary memory

The primary-memory provider backs stable memory semantics without making provider storage or retrieval authoritative policy.

• Cardinality: exclusive for the resolved agent memory scope.
• Selection: operator-authored deployment, tenant, or agent configuration; the exact supported scopes are fixed by the contract before implementation.
• Public compatibility: stable memory.seed, memory.search, and memory.write behavior and pre-turn hydration remain the runtime-facing capability.
• Kernel ownership: agent scope, canonical request and outcome types, budgets, provenance requirements, secret exclusion, tool exposure, policy, final prompt use, and audit.
• Provider ownership: storage and retrieval mechanics, provider-native indexing, consolidation operations admitted by the contract, and persistence recovery within declared consistency semantics.
• Built-in default: current built-in memory behavior enters through the same primary-memory binding and conformance path as any external implementation.
• Failure behavior: best-effort recall may degrade to explicitly attributed empty recall when the contract permits it. Writes must report failure and must not silently switch to another source of truth.
• Migration: existing canonical data remains readable throughout an incremental adapter migration. Any later source-of-truth move requires its own data migration and rollback contract.

Anchor contract 3: context strategies

Context providers contribute bounded context material or compaction proposals. Tyrum retains final prompt authority.

• Cardinality: ordered-many with deterministic kernel-owned order and merge rules.
• Selection: operator-authored runtime or agent profile.
• Kernel ownership: context budget, source precedence, prompt roles, policy and instruction integrity, safety filtering, final assembly, pruning, compaction state transitions, and context reports.
• Provider ownership: producing a typed, bounded, attributed contribution or compaction proposal from the inputs explicitly supplied by the kernel.
• Built-in default: current system-prompt, conversation-state, transcript-tail, memory, work, attachment, pruning, and compaction behavior is decomposed only where a real strategy boundary exists; unchanged behavior remains the default.
• Failure behavior: optional contributions may be skipped only under declared deterministic degraded behavior. A provider cannot replace system policy, grant tools, mutate transcript truth, or commit compaction state directly.
• Ordering: provider order and duplicate-source handling are configuration owned by the kernel, not discovery order or provider self-priority.

Admission rule for additional provider kinds

The provider microkernel is not a mandate to providerize every module. A new provider kind is admitted only when all of the following are true:

1. there is a real substitution, trust, deployment, lifecycle, or ownership boundary;
2. at least one built-in default and one credible alternate implementation or operational requirement can be described;
3. kernel-owned invariants and provider-owned work can be separated without duplicating governance;
4. cardinality, selection scope, failure behavior, persistence, and conformance are accepted in a typed contract;
5. the provider path is simpler than a direct integration at the observed scale.

Potential later seams include model routing and transport, browser/computer execution, channels, media, search and extraction, state and artifacts, queues and scheduling, identity and policy integrations, approvals, secrets, audit, and telemetry. This list is a discovery queue, not an implementation commitment. Each item must pass the admission rule independently.

Adoption dependency graph

The graph is the authoritative dependency source. The work ledger below expands its nodes but adds no dependencies.

Work ledger

ID	Status	Output	Depends on	Acceptance criterion
D0	Accepted	This decision, ownership boundary, contract checklist, and DAG.	None	Decision and implementation status are explicit.
D1	Accepted	Kernel invariants and provider control-plane contract.	D0	Every invariant has one kernel owner and observable enforcement point.
I0	Accepted	Typed isolation-provider contract.	D1	Contract requirements are complete; operator-only selection and fail-closed downgrade behavior are explicit.
M0	Planned	Typed exclusive primary-memory contract.	D1	Source-of-truth, consistency, migration, and degraded read/write behavior are explicit.
C0	Planned	Typed ordered-many context-strategy contract.	D1	Ordering, merge, budget, authority, and failure rules are explicit.
S0	Planned	Only the shared descriptor, catalog, configuration, compatibility, binding, lifecycle, health, and audit substrate proven by I0/M0/C0.	I0, M0, C0	No universal domain interface or speculative registry machinery is introduced.
B0	Planned	Built-in and external implementations use one registration, validation, resolution, and binding path.	S0	A built-in cannot bypass a check required of an external implementation.
T0	Planned	Provider-kind conformance harness and activation gates.	S0	Incompatible or non-conforming implementations are rejected before use.
I1	Planned	Current local_spawn represented as the built-in baseline isolation provider.	I0, B0, T0	Existing behavior remains compatible and truthfully reports no hardened confinement.
I2	Planned	One provider enforcing an accepted hardened confinement profile.	I1	Every claimed boundary has real acceptance evidence; cleanup and cancellation are bounded.
I3	Planned	process.run uses the immutable selected provider binding.	I2	Public tool behavior remains compatible; required confinement fails closed.
I4	Planned	Durable process lifecycle uses and recovers the same provider binding.	I3	Restart, reconciliation, logs, cancellation, and terminal outcomes cannot switch provider identity.
G0	Planned	First complete confined-process product slice.	I4	Existing process tools run through the selected provider with no model-selectable downgrade.
M1	Planned	Existing memory behavior represented as the built-in primary-memory provider.	M0, B0, T0	Stable memory tools and pre-turn hydration remain compatible.
M2	Planned	Incremental migration of memory call sites and, only if separately accepted, provider data.	M1	No split source of truth or silent write fallback exists.
C1	Planned	Existing context behavior represented through built-in typed strategies where justified.	C0, B0, T0	Final prompt authority and current default behavior remain kernel-owned.
C2	Planned	Incremental migration of context assembly and compaction seams.	C1	Ordering, budgets, reports, and durable compaction transitions remain deterministic.
F0	Planned	Contract-first evaluation of additional seams.	G0, M1, C1	Each candidate independently passes the admission rule before implementation planning.

The graph encodes dependency, not team assignment or calendar order. Independent branches may proceed in parallel after their dependencies are accepted.

First process-slice acceptance

The first implementation slice is complete only when all of the following are true:

• the model-facing process tool IDs and request/result contracts remain unchanged unless separately approved;
• local_spawn and the confined implementation use the same provider admission and binding path;
• the selected provider is operator-controlled through a process or execution profile and is absent from model-supplied arguments;
• one genuinely confined provider proves the exact hardened profile it claims;
• foreground and durable-background operations retain one provider identity across lifecycle and recovery;
• required confinement fails closed with no silent downgrade;
• canonical policy, approval, secret projection, audit, timeout, cancellation, output, and settlement behavior remains kernel-owned;
• provider-kind conformance and existing process contract tests pass with non-vacuous evidence.

Compatibility, rollout, and rollback

• Existing built-in behavior remains the default until an operator explicitly configures another admitted provider.
• Contract and implementation versions are checked before binding. Incompatible providers are unavailable rather than discovered optimistically and failed during an operation.
• Provider bindings are immutable for an operation. Dynamic hot reload is outside this decision.
• Rolling back the provider substrate restores the built-in path only where the active profile permits baseline execution. A profile requiring hardened confinement remains unavailable rather than downgrading.
• The first process slice requires no new provider marketplace, distributed registry, or database migration family. Configuration persistence uses existing owned configuration surfaces unless a later accepted contract proves that insufficient.
• Memory or context source-of-truth changes require separate migration and rollback evidence; this decision alone authorizes neither.

Non-goals

• no universal operational Provider interface
• no alternate conversation-turn executor
• no model-selected provider, isolation mode, or security downgrade
• no provider-owned authorization, policy enforcement, approval, or canonical audit authority
• no requirement for dedicated remote node placement to obtain local confinement
• no provider marketplace, dynamic hot reload, distributed lifecycle, or fleet registry
• no new database registry or migration family without a concrete accepted requirement
• no framework built from a speculative inventory of future providers
• no assumption that plugins, MCP servers, nodes, or model-provider profiles are interchangeable provider kinds

Consequences

• Tyrum can replace specialized strategies and execution boundaries without duplicating its governance model.
• Built-in defaults remain simple to operate but lose privileged implementation shortcuts.
• Provider-kind contracts become more deliberate because lifecycle, persistence, failure, and composition cannot be hidden behind one generic interface.
• The first implementation spends design effort on three different anchors before extracting shared code. This is intentional evidence against an over-general framework.
• Additional provider seams remain possible, but they are not pre-approved work merely because the control plane exists.

Related docs

• Architecture overview
• D1 kernel invariants and provider control-plane contract
• ARCH-23 native runtime and governed CLI tools
• ARCH-24 governed process capability
• ARCH-25 process-family governance and truthful posture
• ARCH-26 durable background process lifecycle
• ARCH-27 governed specialist CLI skills
• Memory
• Context, Compaction, and Pruning
• Gateway plugins
• Sandbox and policy