Design process-wide lifecycle and dynamic configuration contract for continuous profiling

[eftiquar]

Feature Request

Context

The OpAMP runtime-configuration work in #5312 has exposed a broader architectural requirement in the continuous-profiler service.

The service was originally designed around a start-once, seed-once lifecycle. Dynamic configuration introduces additional requirements:

• enabling and disabling profiling features at runtime;
• changing CPU, selective-thread, and allocation-sampling settings atomically;
• preserving process-wide configuration across .NET Framework AppDomain initialization and unload;
• defining precedence between startup Seed and ControlPlane configuration;
• preventing multiple AppDomain-local exporters from competing for process-wide native samples;
• recovering the managed exporter and canary after their owning AppDomain unloads;
• preserving compatibility between different managed and native package versions.

These are process-wide service semantics and should be established independently of the OpAMP transport and managed exporter implementation.

Proposed direction

Define a protocol-neutral native runtime-service contract that provides:

• one-time, source-neutral bootstrap;
• complete atomic runtime-configuration application;
• ControlPlane > Seed > None authority precedence;
• last-known-good behavior for invalid or stale updates;
• lazy producer activation and safe quiescence;
• explicit capture, disable, and terminal-shutdown boundaries;
• opaque managed-host ownership tokens;
• AppDomain-unload revocation and demand-driven host recovery;

Managed code would remain responsible for interpreting and merging OpAMP configuration, constructing the exporter pipeline and canary, and invoking this native contract.

Although the proposed contract is comprehensive, much of that complexity already exists in the runtime environment and is currently implicit. This is particularly true on .NET Framework, where process-wide native profiling state must coexist with managed components whose AppDomains can arrive and depart independently. Exporter ownership, AppDomain unload, canary recruitment and invalidation, competing initialization attempts, and recovery after owner loss all require defined semantics. The purpose of this design is to make those lifecycle rules explicit, deterministic, and independently testable before dynamic OpAMP integration depends on them.

Proposed delivery

Split delivery horizontally:

1. Implement and test the native runtime-service lifecycle and interop contract.
2. Connect the managed OpAMP control plane and exporter pipeline to that contract.

This allows native concurrency, ownership, authority, and lifecycle semantics to be reviewed and tested independently before adding managed protocol integration.

Design draft

The attached document is a working design proposal intended to support discussion and refinement.

dynamic-profiling-service-design-proposal

Decisions requested

• Do the proposed authority, lifecycle, AppDomain ownership, and compatibility semantics provide an appropriate basis for implementation?
• Do we agree with the native/managed responsibility boundary?
• Which parts require discussion or approval in a SIG meeting?

Is this complexity justified?

In my view, yes. Much of the complexity is inherent—particularly in .NET Framework AppDomain arrival, departure, exporter ownership, and canary lifecycle scenarios. This contract makes those semantics explicit and contains them at the native service boundary, allowing the managed OpAMP and exporter integration to remain comparatively simple.

[eftiquar]

Continuous Profiler Native Runtime Service Contract

Status: Under review

Date: 2026-08-12

Scope: Native process-wide profiling lifecycle and configuration contract

1. Decision

The continuous profiler will be redesigned as a process-wide native service that
supports dynamic configuration independently of any managed configuration source or
exporter implementation.

The native service will:

• bootstrap once into a source-neutral, non-producing state;
• accept only complete runtime configuration snapshots;
• validate and apply each snapshot atomically;
• enforce the authority order ControlPlane > Seed > None;
• retain the last successfully committed configuration after any rejected update;
• own CPU, selective-thread, and allocation-sampling lifecycles;
• coordinate one process-wide managed profiling host without owning serialization
  or HTTP transport;
• define disable, capture, flush-barrier, and terminal-shutdown semantics.

The upper managed layer will parse and merge OpAMP configuration, construct exporters,
and submit a complete configuration to native code. Native code will not parse OpAMP,
merge partial documents, or model managed exporter construction.

This is a horizontal split at the ownership boundary, not a vertical split by
profiling feature. CPU, selective-thread, and allocation sampling remain together in
the native contract.

2. Motivation

The profiler was originally designed for a start-once, seed-once model. Dynamic
control introduces requirements that the original model did not need to address:

• managed initialization may occur in multiple .NET Framework AppDomains;
• startup configuration and control-plane configuration may race;
• a service initially disabled at startup may be enabled later;
• enabled services may be disabled and re-enabled repeatedly;
• CPU and selective-thread intervals must change as one valid pair;
• allocation sampling has a separate, fallible EventPipe lifecycle;
• disabling during capture requires an explicit safe boundary;
• shutdown must drain or discard work according to its representability.

Removing a one-time guard and making startup configuration mutable cannot provide
these semantics. Bootstrap, policy, and authority must be separate concepts.

The central design principle is:

Bootstrap establishes capability, not policy. Policy is supplied later as a
complete configuration and is committed according to authority.

3. Architectural boundary

3.1 Native responsibilities

Native code owns:

• process-wide bootstrap and terminal shutdown;
• configuration normalization and validation;
• authority and revision enforcement;
• atomic immutable-snapshot publication;
• the shared CPU/selective sampling worker;
• allocation EventPipe session creation and teardown;
• concurrency control and safe-boundary acknowledgement;
• complete-stack-only publication;
• native buffers and producer-side back pressure.
• transport-neutral claim, readiness, revocation, and Activity-driven recovery of
  the process-wide managed profiling host.

3.2 Managed responsibilities

Managed code owns:

• reading startup/plugin configuration;
• receiving OpAMP remote configuration;
• interpreting OpAMP files, sections, hashes, and content types;
• merging partial or incremental control-plane documents;
• producing one complete native configuration snapshot;
• assigning an ordered process-local control-plane revision;
• preparing the required exporters before enabling native production;
• installing a lightweight Activity/context bridge in every eligible AppDomain;
• constructing the exporter reader and, on .NET Framework, the canary only in the
  AppDomain that holds the current native-issued host token;
• draining and exporting native buffers after producer disable;
• reporting OpAMP applying, applied, or failed status;
• reporting the effective configuration to the control plane.

The native configuration API has no exporter object, managed-host field, or
OpAMP-specific payload. The separate claim API prepares a managed host before the
first enabling configuration is submitted. Configuration authority and host
ownership remain independent state. A valid configuration update is not rejected
merely because another AppDomain already owns the managed host.

3.3 Integration precondition

Before submitting an initially enabling configuration, managed code ensures one
managed profiling host has confirmed readiness. The caller attempting the update may
claim a vacant host, but no ownership preference is part of the contract: another
eligible AppDomain may win a concurrent claim and satisfy the precondition. Native
then commits and activates the complete configuration atomically. Native does not
inspect how the host serializes or exports data.

After an active host is lost, the already-committed configuration and its authority
remain valid while production is quiescent. In that recovery case, a replacement
host confirms readiness first and native reactivates the retained configuration.

4. Glossary

Capitalization is significant in this document. Control plane names an
architectural role; ControlPlane names a value in the native authority state
machine.

• Accepted revision: The highest successfully accepted ControlPlane revision.
  It orders dynamic requests independently of whether a request changes effective
  values or publishes a new runtime generation. Rejected requests do not advance it.
• Active configuration: The complete normalized configuration currently
  governing native producers. It is the configuration in the authoritative native
  state, even when every feature is disabled.
• Apply: The process-wide interop operation that submits one complete candidate
  to the native controller and returns both a result and the authoritative resulting
  state.
• Authority: The precedence class of the successfully committed configuration.
  Authority answers which source may replace the active configuration; it does not
  identify an AppDomain, thread, exporter, or object owner. A candidate carries a
  proposed authority, but native authority changes only after successful commit.
• Authority precedence: The irreversible ordering
  ControlPlane > Seed > None for one profiler process lifetime. Higher authority
  may replace lower authority; lower authority cannot replace higher authority.
• Authority withdrawal: An explicit operation that would relinquish an
  established authority. This contract defines no withdrawal operation. Silence,
  disconnect, invalid input, and an all-disabled configuration are not withdrawal.
• Authoritative state: The coherent native tuple of active configuration,
  authority, accepted ControlPlane revision, and runtime generation returned by
  Apply or GetState. Managed code reconciles to this state rather than assuming its
  submitted candidate became effective.
• Bootstrap: One-time, source-neutral construction of native controller
  capability and synchronization state. Bootstrap establishes the ability to apply
  policy; it neither establishes authority nor starts a producer by itself.
• Candidate: A complete configuration snapshot plus authority, revision, and—
  for ControlPlane—the expected runtime generation, submitted for possible commit.
• Commit: The atomic point at which a validated and prepared candidate becomes
  the active configuration and establishes or retains its authority. Arrival,
  parsing, validation, or resource preparation alone is not a commit.
• Committed Seed: The complete normalized startup configuration native actually
  accepted with Seed authority. It may enable features or be explicitly
  all-disabled. Native returns this value so managed OpAMP processing can use the
  actual Seed—not an attempted or cached value—as a merge base.
• Complete configuration snapshot: One value containing CPU, selective-thread,
  and allocation-sampling settings together. Native accepts only complete snapshots;
  omission, patching, and per-field merge have no meaning at the interop boundary.
• Control plane: The management path that determines desired runtime behavior,
  distinct from the profiling data path that captures, buffers, and exports samples.
  In this design the control plane runs in managed code, interprets OpAMP input, and
  invokes a protocol-neutral native service contract.
• ControlPlane authority: The native authority assigned to a successfully
  committed dynamic configuration. OpAMP is the first producer of such candidates,
  but native code does not know the OpAMP protocol. Once established,
  ControlPlane authority remains until terminal profiler shutdown.
• Data plane: The producer-consumer path that captures stacks or allocations,
  publishes complete samples, drains native buffers, and exports profiling data. It
  obeys the active configuration but does not determine configuration precedence.
• Dormant worker: The CPU/selective sampling worker has never been created. An
  initially disabled process remains dormant and pays no worker-thread cost.
• Expected runtime generation: The generation of the authoritative state over
  which managed code produced a complete ControlPlane candidate. Native compares
  it during Apply to prevent a Seed or newer ControlPlane commit from being lost in
  a query/merge/apply race.
• Generation barrier: Native acknowledgement that producers have crossed the
  safe boundary for a committed runtime generation. After a disable barrier returns,
  managed code may perform its final drain without a disabled producer publishing
  additional samples for that generation.
• GetState: A read-only interop operation returning authoritative native state.
  It does not bootstrap, establish authority, start a worker, or create an EventPipe
  session.
• Last known good configuration: The most recent successfully committed active
  configuration. Invalid, stale, conflicting, raced, or operationally failed
  candidates leave it in force.
• Merge base: The complete authoritative native configuration over which managed
  code applies a partial OpAMP update. It is the committed ControlPlane value, the
  committed Seed, or the canonical all-disabled None value.
• None authority: The initial native authority before any valid Seed or
  ControlPlane candidate commits. Its canonical configuration is all-disabled,
  revision is 0, and generation is 0. It is distinct from an explicitly
  committed all-disabled Seed or ControlPlane configuration.
• Normalization: Conversion of the ABI representation into one canonical native
  value, including interpreting numeric zero as feature disabled. Validation and
  equality comparisons operate on normalized values.
• OpAMP: The Open Agent Management Protocol used by the managed control plane to
  receive remote configuration and report application status. OpAMP documents,
  hashes, merge rules, and transport state do not cross the native ABI.
• Producer: A native component that creates profiling samples: the shared
  CPU/selective sampling worker or the allocation EventPipe path.
• Consumer: The managed exporter pipeline that reads native samples, converts or
  batches them as needed, and exports them. A consumer is prepared before its
  producer is enabled and drained after native acknowledges disablement.
• Activity recovery bridge: Lightweight AppDomain-local managed infrastructure
  that observes business Activity context transitions and forwards them to native
  code independently of exporter-reader ownership. It creates no polling or standby
  exporter thread.
• Host registration generation: A native-only monotonic counter advanced for
  every successful managed-host claim. It prevents an earlier ownership term from
  being mistaken for a later one, even if the same AppDomain constructs another host.
  It is not exposed as an ordering primitive across the ABI.
• Host token: An opaque, nonzero value minted by native for one managed-host
  ownership term. Managed code must only retain and echo it; it must not inspect,
  compare, order, synthesize, or persist it. Native binds the token to the claiming
  CLR AppDomainID and validates it on every host-scoped operation. A token becomes
  permanently invalid when its claim is released, revoked, superseded, or the
  profiler enters terminal shutdown. It is independent of runtime configuration
  generation and is not a security credential.
• Host required: Operational state in which committed configuration requests
  profiling but no ready managed profiling host exists. Native producers remain
  quiescent while authority and configuration are retained.
• Managed profiling host: The one AppDomain-local managed unit allowed to drain
  native buffers. It contains the exporter reader and transport and, on .NET
  Framework when thread capture is required, the canary thread. Its identity is the
  native tuple {AppDomainID, hostToken}.
• Quiescent worker: A previously created CPU/selective sampling worker retained
  in a non-producing wait state. Re-enabling wakes it; terminal shutdown joins it.
• Reconciliation: Managed adoption of the authoritative state returned by native.
  On RejectedBaseGeneration, reconciliation also means re-merging the same OpAMP
  document over the returned winning state and performing the bounded retry.
• Runtime generation: A native counter identifying publication of a distinct
  effective configuration snapshot. It is also used as the compare-and-apply token
  and producer barrier. It is separate from the managed ControlPlane revision.
• Safe boundary: A lifecycle-defined point at which configuration may take
  effect without publishing semantically invalid work. Ordinary feature disable uses
  a thread boundary; terminal shutdown may abort at a stack-frame boundary and
  discards the incomplete stack.
• Seed: The complete startup configuration submitted with Seed authority and
  revision 0, normally derived from managed plugin/environment configuration. The
  first valid Seed may commit; later AppDomain Seed attempts cannot overwrite an
  established Seed or ControlPlane value. If startup submits no Seed, authority
  remains None and ControlPlane may commit directly.
• Selective-thread sampling: Stack sampling restricted to threads selected for
  targeted capture and configured with its own interval. It shares the native worker
  with CPU sampling. Snapshot sampling is an alternate name, avoided here where
  it could be confused with immutable configuration snapshots.

5. System invariants

The implementation must preserve these invariants:

1. The native continuous profiler is process-wide. No AppDomain owns it.
2. Foundational CLR profiler capability is selected during profiler initialization
   when it cannot safely be deferred.
3. Service bootstrap is source-neutral, guarded by std::call_once, and performed at
   most once.
4. Bootstrap does not start a sampling worker or allocation EventPipe session.
5. Native accepts only a complete configuration; it never merges partial updates.
6. Authority is ordered ControlPlane > Seed > None.
7. Authority changes only after a candidate is successfully committed.
8. Once a valid control-plane configuration is committed, native never falls back to
   seed during that process lifetime.
9. Invalid, stale, conflicting, or unapplied candidates do not change the active
   configuration, authority, accepted revision, or generation.
10. Workers observe either the complete old configuration or the complete new one.
    They never observe a mixture of revisions.
11. Numeric zero means that the corresponding feature is disabled.
12. CPU and selective-thread sampling share at most one native sampling worker.
13. That worker is created only on first use. Ordinary disable quiesces it; only
    terminal shutdown joins it.
14. Allocation sampling owns a separate EventPipe-session lifecycle and releases the
    session while disabled.
15. Disable and shutdown preserve every complete, representable sample. An incomplete
    stack is never exported as an ordinary pprof sample.
16. Runtime configuration failures are bounded, logged, and returned as protocol
    results; they never escape into the host application.
17. At most one managed host token may remove samples from process-wide native
    buffers at a time.
18. Configuration authority and managed-host ownership are independent state
    machines: losing an AppDomain host never withdraws Seed or ControlPlane
    authority.
19. Committed enabled policy without a ready managed host places native producers in
    HostRequired; it never permits unconsumed production.
20. Host recovery is demand-driven by Activity/context traffic or another explicit
    managed control call. No standby exporter thread or default-AppDomain watchdog is
    required for correctness.
21. In the token protocol, AppDomain initialization failure, host construction
    failure, and host release can quiesce or revoke only AppDomain-local managed
    resources. Only process-level CLR profiler shutdown may enter native terminal
    shutdown; an AppDomain must never call it as rollback for its own failure or
    unload. The legacy-mode compatibility exception is defined in Section 10.7.1.

6. Bootstrap contract

CLR event-mask capabilities required for deferred stack capture are selected in
CorProfiler::Initialize, before any managed seed or control-plane call. In
particular, stack-snapshot capability cannot depend on a later AppDomain callback.

The source-neutral bootstrap operation, named conceptually
EnsureContinuousProfilerBootstrapped, performs only process-level construction:

• construct the native controller and synchronization state;
• construct and connect the runtime-specific stack walker;
• publish callback targets only after callback-visible objects are valid;
• initialize the disabled immutable configuration;
• do not create the sampling worker;
• do not start an allocation EventPipe session;
• do not assign configuration authority.

Bootstrap is guarded by std::call_once. Its result is retained so every caller
observes the same outcome. A bootstrap failure is terminal for continuous profiling
in that profiler lifetime; later configuration calls return BootstrapFailed and do
not operate on partially initialized resources.

A seed or control-plane caller may be the first caller to request bootstrap. The
source of that request has no effect on the bootstrapped state.

7. Complete configuration model

The logical native value is RuntimeSamplerConfiguration:

struct RuntimeSamplerConfiguration
{
    std::optional<std::chrono::milliseconds> cpuSamplingInterval;
    std::optional<std::chrono::milliseconds> selectiveThreadSamplingInterval;
    std::optional<uint32_t> maxAllocationSamplesPerMinute;
};

An engaged value means enabled; std::nullopt means disabled. The exported C ABI
uses a versioned, fixed-width, C-compatible payload:

struct RuntimeSamplerConfigurationV1
{
    uint32_t structureSize;
    uint32_t schemaVersion;
    uint32_t cpuSamplingIntervalMilliseconds;
    uint32_t selectiveThreadSamplingIntervalMilliseconds;
    uint32_t maxAllocationSamplesPerMinute;
};

The boundary normalizes zero as disabled:

cpu_sampling_interval_ms == 0        => CPU sampling disabled
selective_sampling_interval_ms == 0  => selective-thread sampling disabled
max_allocation_samples_per_min == 0  => allocation sampling disabled

There are no separate enable flags that can contradict numeric values. Internal
consumers query feature state through the normalized value and do not repeat
zero-value checks.

structureSize and schemaVersion protect the ABI from managed/native distribution
mismatch. Native rejects an unsupported layout before reading fields not guaranteed
by the declared structure.

7.1 Full-snapshot rule

Every application request contains all three feature values. Omission and merge have
no meaning at the native boundary.

For example, if startup enabled only CPU profiling and an OpAMP document later adds
allocation profiling, managed code performs the merge:

Seed input:              CPU=1000 ms, selective=off, allocation=off
OpAMP partial document:  allocation=6000/min

Managed effective value:
                         CPU=1000 ms, selective=off, allocation=6000/min

Native input:            the complete managed effective value

Native validates and commits that complete value as one transaction.

7.2 Complete-candidate validation

Validation is performed once over the normalized candidate:

• enabled intervals and rates satisfy defined range and overflow constraints;
• when CPU and selective-thread sampling are both enabled, the CPU interval is
  greater than and an exact multiple of the selective interval;
• allocation sampling is not enabled on an unsupported runtime;
• the required native profiler capability is available;
• the ABI structure and schema versions are supported.

Complete validation permits transitions that ordered per-field setters cannot
express. For example:

old: CPU=1000 ms, selective=250 ms
new: CPU= 900 ms, selective=300 ms

Both complete configurations are valid, but either per-field setter may reject its
intermediate combination with the other old value. A full candidate has no invalid
intermediate state.

8. Authority state machine

Authority is a property of the last successfully committed configuration, not of the
latest attempted call.

                 valid Seed
       None --------------------> Seed
         |                          |
         | valid ControlPlane       | valid ControlPlane
         v                          v
     ControlPlane <------------ ControlPlane
           valid newer ControlPlane revision

There is no ControlPlane -> Seed transition and no authority-withdrawal operation
in this contract.

8.1 Normative transition table

Current authority	Candidate	Outcome
None	invalid Seed	Reject; remain None
None	invalid ControlPlane	Reject; remain None
None	valid Seed	Commit; become Seed
None	valid ControlPlane	Commit; become ControlPlane
Seed	any later Seed	Ignore as seed already established; retain first committed Seed
Seed	invalid ControlPlane	Reject; retain committed Seed
Seed	valid ControlPlane	Commit; become ControlPlane
ControlPlane	any Seed	Ignore as lower authority
ControlPlane	invalid ControlPlane	Reject; retain last valid ControlPlane configuration
ControlPlane	stale ControlPlane revision	Reject; retain last valid ControlPlane configuration
ControlPlane	same ControlPlane revision and identical value	Return NoChange; retain state
ControlPlane	same ControlPlane revision and different value	Reject as a revision conflict; retain state
ControlPlane	valid newer revision with identical effective value	Accept the revision; perform no lifecycle work; remain ControlPlane
ControlPlane	valid newer revision with different effective value	Commit replacement; remain ControlPlane

Before evaluating a ControlPlane row, native compares the candidate's expected base
generation with the current runtime generation as specified in Section 10.3. A
mismatch returns RejectedBaseGeneration and the current state without changing
authority or revision.

8.2 Commit, not arrival, establishes authority

An invalid control-plane candidate never claims control-plane authority. Therefore:

None + invalid ControlPlane
    -> authority remains None
    -> a later valid Seed is still eligible

Seed + invalid ControlPlane
    -> Seed remains active

Seed + valid ControlPlane
    -> ControlPlane becomes authoritative only after successful commit

Once a valid control-plane candidate commits, the transition is permanent for the
process lifetime:

ControlPlane + invalid later ControlPlane
    -> reject candidate
    -> preserve last committed ControlPlane configuration
    -> preserve ControlPlane authority

ControlPlane + disconnected management transport
    -> no native configuration event
    -> preserve last committed ControlPlane configuration

ControlPlane + complete all-disabled configuration
    -> commit disabled state
    -> preserve ControlPlane authority

There is no implicit fallback to seed after malformed input, transport loss, an
all-disabled update, or a missing profiling section. If a future product requirement
needs authority withdrawal, it requires a separate explicit protocol and design.

8.3 Revision rule

The upper layer serializes control-plane processing and assigns monotonically
increasing process-local revisions. A Seed request uses revision 0. A ControlPlane
request uses a non-zero revision. Native records the highest successfully accepted
ControlPlane revision.

• Rejected candidates do not advance the accepted revision.
• A later valid revision greater than the accepted revision remains eligible even
  if an intervening higher attempted revision was invalid.
• A candidate older than the accepted revision cannot overwrite the committed
  configuration.
• Reuse of the accepted revision is idempotent only when the normalized value is
  identical. The same revision with a different value is rejected as a conflict.
• A newer valid revision with the same normalized value advances the accepted
  revision, but does not publish a new runtime generation or perform lifecycle work.
• The OpAMP configuration hash remains a managed protocol concern. It may be logged
  or reported by managed code, but native does not interpret or order hashes.

This protects against an older parse or callback completing after a newer valid
configuration has already committed.

9. Native apply contract

The internal native controller operation is protocol-neutral:

ApplyResult RuntimeSamplerController::Apply(
    const RuntimeSamplerConfigurationV1& configuration,
    ConfigurationAuthority authority,
    uint64_t revision,
    uint64_t expectedRuntimeGeneration,
    RuntimeSamplerState& resultingState);

ConfigurationAuthority contains only:

enum class ConfigurationAuthority : int32_t
{
    Seed = 1,
    ControlPlane = 2
};

This operation subsumes the existing ConfigureContinuousProfiler entry point. Seed
and ControlPlane configuration must not remain as independent native paths. During
migration, the existing entry point may exist only as a compatibility shim that
constructs a complete Seed request with revision 0 and delegates to the new apply
operation. It owns no call_once, configuration, authority, worker, or EventPipe
state of its own. After all managed startup callers migrate, the shim can be removed.

9.1 Result contract

enum class ApplyResult : int32_t
{
    Applied = 0,
    NoChange = 1,
    IgnoredSeedAlreadyEstablished = 2,
    IgnoredLowerAuthority = 3,
    RejectedInvalid = 4,
    RejectedStaleRevision = 5,
    RejectedRevisionConflict = 6,
    RejectedBaseGeneration = 7,
    BootstrapFailed = 8,
    ActivationFailed = 9,
    ShuttingDown = 10,
    LegacyProtocolActive = 11
};

NoChange, IgnoredSeedAlreadyEstablished, IgnoredLowerAuthority, and
RejectedStaleRevision are expected protocol outcomes. RejectedBaseGeneration is
an expected optimistic-reconciliation outcome for a ControlPlane race. A revision
conflict, invalid data, and activation failures produce warnings. All outcomes are
returned without throwing into managed or application code.

LegacyProtocolActive is returned only when a new versioned Apply operation reaches
a process whose compatibility shim already selected Legacy consumer mode. The
candidate is not committed. This prevents new control-plane policy from driving a
consumer whose old managed implementation cannot honor the host-token lifecycle.

10. Managed OpAMP control-plane integration and interop contract

The interop surface connects managed startup and control-plane orchestration to the
protocol-neutral native service. It exposes configuration and authoritative state;
it does not expose OpAMP documents, exporter objects, AppDomain identity, or native
worker implementation details.

10.1 Versioned interop payloads

The conceptual C ABI uses fixed-width, versioned request and state structures:

struct RuntimeSamplerApplyRequestV1
{
    uint32_t structureSize;
    uint32_t schemaVersion;
    uint64_t revision;
    uint64_t expectedRuntimeGeneration;
    RuntimeSamplerConfigurationV1 configuration;
    int32_t authority;
    uint32_t reserved0;
    uint32_t reserved1;
};

struct RuntimeSamplerStateV1
{
    uint32_t structureSize;
    uint32_t schemaVersion;
    uint64_t acceptedControlPlaneRevision;
    uint64_t runtimeGeneration;
    RuntimeSamplerConfigurationV1 activeConfiguration;
    int32_t activeAuthority;
    uint32_t reserved0;
    uint32_t reserved1;
};

activeAuthority uses None = 0, Seed = 1, and ControlPlane = 2. When authority
is None, the active configuration is the canonical all-disabled value, accepted
revision is 0, and runtime generation is 0.

The exported operations are conceptually:

ApplyResult ApplyRuntimeSamplerConfigurationV1(
    const RuntimeSamplerApplyRequestV1* request,
    RuntimeSamplerStateV1* state);

StateQueryResult GetRuntimeSamplerStateV1(
    RuntimeSamplerStateV1* state);

The query result is deliberately small:

enum class StateQueryResult : int32_t
{
    Succeeded = 0,
    InvalidArgument = 1,
    UnsupportedSchema = 2
};

The concrete export names may follow repository conventions, but their semantics are
normative. ABI decoding validates pointers, sizes, versions, reserved fields,
authority values, and revision rules before reading optional layout or changing
state.

The ABI contains no C++ bool, std::optional, string, object reference, or
platform-width integer. Eight-byte fields begin at explicit eight-byte offsets, and
reserved trailing fields make both V1 structures exactly 56 bytes. Native
compile-time assertions and managed interop tests must
verify every structure size and field offset on supported architectures. Managed
callers zero reserved fields and initialize output structureSize and
schemaVersion before each call.

P/Invoke details are contained behind one managed adapter rather than exposed to the
OpAMP coordinator:

internal interface IRuntimeSamplerInterop
{
    RuntimeSamplerApplyOutcome Apply(
        CompleteRuntimeSamplerConfiguration configuration,
        ConfigurationAuthority authority,
        ulong revision,
        ulong expectedRuntimeGeneration);

    RuntimeSamplerState GetState();
}

The adapter owns marshaling, ABI-version checks, native result conversion, and
exception containment. The coordinator depends on this managed interface and can be
tested with a deterministic fake native service.

10.2 Apply response semantics

For every ABI-valid request, Apply populates state with the authoritative native
state that exists when the operation returns, including when the candidate is
ignored or rejected. This lets managed code distinguish the attempted configuration
from the configuration that remains effective.

Apply is process-wide, thread-safe, and synchronous with respect to its result:

• Applied returns the committed configuration, authority, accepted revision, and
  acknowledged runtime generation;
• an applied Seed returns the complete normalized Seed that native actually
  committed, so it can become the managed merge base;
• NoChange returns the already effective configuration and current metadata;
• an ignored Seed returns the authority and configuration that defeated it;
• a ControlPlane request whose merge-base generation is no longer current returns
  RejectedBaseGeneration and the actual complete state that won the race;
• a rejected stale, conflicting, invalid, or failed candidate returns the unchanged
  last known good state;
• a disable result is not returned until the native producer reaches the generation
  barrier defined in Section 14.

Native code must not call managed code while holding the controller lock. Managed
code must not infer native state from its submitted value; the returned state is the
authority for reconciliation and status reporting.

10.3 Compare-and-apply reconciliation

A ControlPlane candidate may have been produced by merging a partial OpAMP document
over a native state obtained moments earlier. The request therefore carries
expectedRuntimeGeneration, identifying that merge base. Under the controller lock,
native compares it with the current generation before applying the candidate.

If they differ, native returns RejectedBaseGeneration without bootstrapping,
validating feature values, changing authority, accepting the request revision, or
performing lifecycle work. The returned state contains the actual complete
configuration, authority, accepted revision, and generation that won the race. In
particular, when startup Seed won, native returns the normalized Seed that was
actually committed—not the AppDomain caller's attempted value and not a managed
cached copy.

Managed code then merges the same OpAMP document over that returned configuration,
reconciles any prepared consumers, assigns a fresh ControlPlane revision, and retries
once with the returned generation as its expected base. Under the contract's single
logical OpAMP coordinator, one retry resolves the only independent startup race. A
second base-generation rejection indicates a coordinator/integration defect and is
reported as failed rather than retried without bound.

Seed requests use revision 0; their expectedRuntimeGeneration is reserved and
must be 0. Seed does not use compare-and-apply because native authority rules—not a
managed merge—decide whether the first Seed commits or is ignored.

10.4 State-query semantics

GetRuntimeSamplerStateV1 is read-only. It does not bootstrap the service, create a
worker, start EventPipe, change authority, or advance a revision or generation. It
returns one coherent committed-state snapshot and can be called from any AppDomain.
Before bootstrap or the first accepted configuration, it returns the canonical
all-disabled configuration with None authority, revision 0, and generation 0.

The query supports three cases:

1. a managed coordinator initializes after an earlier AppDomain has submitted Seed;
2. managed state is rebuilt after an exception or uncertain interop outcome;
3. OpAMP effective-configuration reporting needs the native authoritative value.

The state payload intentionally omits worker handles, thread identifiers, EventPipe
session identifiers, exporter readiness, and transport state. Those are not part of
the configuration contract.

10.5 Managed OpAMP coordinator

Managed code owns one logical process-wide sequence of control-plane updates. It
serializes OpAMP callbacks before parsing, merging, revision assignment, exporter
coordination, and interop. Concurrent callbacks must not independently race through
those steps.

For each profiler-related OpAMP update, managed code:

1. receives and retains the OpAMP configuration hash for protocol reporting;
2. parses the profiler-specific document without changing native state;
3. obtains the authoritative native state and selects its complete configuration as
   the merge base: committed ControlPlane, committed Seed, or canonical all-disabled
   when authority is None;
4. applies the managed schema's patch or replacement semantics;
5. produces and validates one complete configuration snapshot;
6. ensures that one managed profiling host is ready before an initially enabling
   candidate is submitted, using the separate host-token protocol;
7. assigns a new non-zero, monotonically increasing process-local revision;
8. calls ApplyRuntimeSamplerConfigurationV1 with ControlPlane authority and the
   merge base's runtime generation;
9. on RejectedBaseGeneration, re-merges over the returned authoritative state and
   performs the single bounded retry defined in Section 10.3;
10. reconciles its effective state from the returned native state;
11. drains or quiesces the managed host after a successful native disable barrier;
12. reports applying, applied, or failed status against the original OpAMP hash.

Schema parsing and merge failures are reported without calling native code. A
native validation or activation rejection is reported as failed while the returned
last known good state remains effective. Revision gaps are valid: a revision assigned
to a rejected candidate is never reused.

A missing profiler document, transport disconnect, or replacement of unrelated
OpAMP content does not mean Seed fallback or authority withdrawal. Managed code does
not submit a configuration for those events unless the profiler schema explicitly
defines a complete new desired value. Explicitly disabling all three features is a
valid complete ControlPlane configuration and retains ControlPlane authority.

10.6 Startup and AppDomain integration

Managed startup reads the exporter/plugin seed configuration, normalizes it into the
same complete payload, and invokes ApplyRuntimeSamplerConfigurationV1 with Seed
authority and revision 0.

Every .NET Framework AppDomain may execute this startup path, but no AppDomain owns
the native service. The first valid Seed may commit. Later Seed calls receive
IgnoredSeedAlreadyEstablished, or IgnoredLowerAuthority after ControlPlane has
committed, and reconcile from the returned state. AppDomain unload does not withdraw
configuration or stop the process-wide service.

On .NET, the agent-load path uses the identical Seed operation. There is no separate
startup-only native configuration mechanism.

The startup race has three normative outcomes:

1. Seed wins: Seed commits first. A ControlPlane candidate merged over an earlier
   generation is rejected with RejectedBaseGeneration; native returns the actual
   committed Seed, and managed re-merges and retries. The valid retry supersedes
   Seed.
2. ControlPlane wins: ControlPlane commits directly from None. Any concurrent or
   later AppDomain Seed is ignored as lower authority and receives the committed
   ControlPlane state.
3. No Seed: Startup is disabled and submits no Seed. ControlPlane merges over the
   canonical all-disabled None state and may commit directly as the first authority.

An explicitly submitted all-disabled Seed is distinct from no Seed: it commits Seed
authority even though it starts no native producer. ControlPlane may subsequently
supersede it through the normal compare-and-apply path.

10.6.1 Startup transition diagram

All startup paths converge on the same process-wide native controller. G0 is the
canonical None state at generation 0; Gs is the generation created by a
committed Seed.

sequenceDiagram
    autonumber
    participant CLR as CLR profiler initialization
    participant Startup as Managed startup / AppDomain
    participant OpAMP as Managed OpAMP coordinator
    participant Native as Native runtime sampler controller

    CLR->>Native: Establish non-deferrable CLR capabilities
    Note over Native: Authority=None, generation=G0<br/>all features disabled, no producer started

    par Parallel: startup path
        Startup->>Startup: Read and normalize complete Seed
    and Control-plane path
        OpAMP->>Native: GetState()
        Native-->>OpAMP: G0, authority=None, all-disabled
        OpAMP->>OpAMP: Merge OpAMP document over G0<br/>prepare required consumers
    end

    alt Alternative: Seed commits first
        Startup->>Native: Apply(Seed, revision=0)
        Native-->>Startup: Applied<br/>actual normalized Seed, generation=Gs
        OpAMP->>Native: Apply(ControlPlane, expected=G0)
        Native-->>OpAMP: RejectedBaseGeneration<br/>actual Seed, generation=Gs
        OpAMP->>OpAMP: Re-merge same document over actual Seed<br/>assign fresh revision
        OpAMP->>Native: Apply(ControlPlane, expected=Gs)
        Native-->>OpAMP: Applied<br/>ControlPlane is authoritative
    else Alternative: ControlPlane commits first
        OpAMP->>Native: Apply(ControlPlane, expected=G0)
        Native-->>OpAMP: Applied<br/>ControlPlane is authoritative
        Startup->>Native: Apply(Seed, revision=0)
        Native-->>Startup: IgnoredLowerAuthority<br/>return authoritative ControlPlane state
    else Alternative: Startup submits no Seed
        Note over Startup: Startup profiling is disabled<br/>no Seed call is made
        OpAMP->>Native: Apply(ControlPlane, expected=G0)
        Native-->>OpAMP: Applied directly from None<br/>ControlPlane is authoritative
    end

Loading

The diagram shows ordering, not thread affinity. Multiple AppDomains may execute the
Startup participant, and their calls may overlap the OpAMP path. The controller lock,
authority rules, and expected-generation comparison determine the outcome; callback
arrival order alone does not bypass the contract.

10.7 Process-wide managed profiling host

On .NET Framework, each application AppDomain contains its own managed agent,
Splunk-provided exporter configuration, and static managed state. Native producers
and buffers are process-wide, but no AppDomain-local exporter is guaranteed to
survive AppDomain unload. Moving HTTP export into native code would introduce
transport and TLS dependencies outside the native profiler's responsibility.

Native therefore coordinates one process-wide managed profiling host. The host
co-locates resources whose usefulness and lifetime coincide:

• the production FIFO reader and configured exporter transport;
• on .NET Framework, the canary required for safe thread stack capture.

The host is a fixed lifetime bundle, not a reflection of whichever features happen
to be enabled at claim time. On .NET Framework, readiness always requires both the
reader/exporter and canary registrations, including when the first policy enables
allocation sampling only. The canary may remain dormant, but a later atomic
configuration that enables CPU or selective sampling needs no second host-preparation
protocol. On modern .NET, readiness requires only the reader/exporter because native
stack capture has no canary dependency.

The host is identified internally by {AppDomainID, hostToken}. Native derives the
AppDomainID from an incoming managed call with GetCurrentThreadID followed by
GetThreadAppDomain; managed AppDomain.Id is not used as an ownership identity.
For each granted claim, native increments its private host registration generation
and mints an opaque, nonzero token unique within the profiler process lifetime. The
token may encode that generation or index native registration state, but its
representation is deliberately outside the ABI contract.

At the C ABI, HostTokenV1 is represented by a fixed-width uint64_t; zero is always
invalid. Its bit pattern has no managed meaning. All token-bearing operations use new
versioned export names, preserving the signatures of existing read and configuration
exports for mixed managed/native package compatibility.

Conceptually, the interop contract is:

enum class HostClaimResult : int32_t
{
    ClaimGranted = 0,
    HostReady = 1,
    ClaimInProgress = 2,
    BootstrapFailed = 3,
    ProcessShuttingDown = 4,
    TokenExhausted = 5,
    LegacyProtocolActive = 6
};

enum class HostOperationResult : int32_t
{
    Succeeded = 0,
    InvalidOrRevokedHostToken = 1,
    WrongAppDomain = 2,
    RequiredComponentMissing = 3,
    ProcessShuttingDown = 4
};

enum class HostAvailabilityResult : int32_t
{
    HostReady = 0,
    HostAbsent = 1,
    TimedOut = 2,
    ProcessShuttingDown = 3
};

enum class NativeContextResult : int32_t
{
    HostHealthy = 0,
    HostClaimGranted = 1,
    HostClaimInProgress = 2,
    ProfilingPolicyDisabled = 3,
    LegacyProtocolActive = 4,
    ProcessShuttingDown = 5
};

HostClaimResult ClaimManagedProfilingHostV1(uint64_t* hostToken);
HostOperationResult RegisterProfilingCanaryV1(uint64_t hostToken);
HostOperationResult ConfirmManagedProfilingHostReadyV1(uint64_t hostToken);
HostOperationResult ReleaseManagedProfilingHostV1(uint64_t hostToken);
HostAvailabilityResult WaitForManagedProfilingHostV1(uint32_t timeoutMilliseconds);
NativeContextResult ContinuousProfilerSetNativeContextVNext(
    uint64_t traceIdHigh, uint64_t traceIdLow, uint64_t spanId,
    uint64_t* grantedHostToken);

// Each process-wide FIFO has a new token-bearing read export.
int32_t ContinuousProfilerReadThreadSamplesVNext(
    uint64_t hostToken, int32_t len, unsigned char* buffer, uint32_t* interval);
int32_t ContinuousProfilerReadAllocationSamplesVNext(
    uint64_t hostToken, int32_t len, unsigned char* buffer);
int32_t SelectiveSamplerReadThreadSamplesVNext(
    uint64_t hostToken, int32_t len, unsigned char* buffer);

The concrete VNext suffix is chosen when the implementation audits existing export
versions; no existing export is renamed or given a new signature. A token-bearing
read returns a distinct negative status for invalid/revoked token or wrong AppDomain,
zero for no data, and a positive byte count for data. Exact numeric values are fixed
in the implementation header and mirrored by the managed adapter. Every pointer and
length is validated before use. RegisterProfilingCanaryV1 is invoked by the canary
thread itself, allowing native to associate both its current CLR thread and AppDomain
with the ownership term.

HostReady means another ownership term already satisfies the precondition;
ClaimInProgress means its bundle is still being constructed. Configuration paths
may call WaitForManagedProfilingHostV1 with a bounded timeout. Native waits on the
controller condition variable until that claim becomes ready, absent, or terminal;
lease expiry bounds an abandoned claim even when the requested timeout is longer.
On HostAbsent, managed may retry the claim. Activity/context paths never call the
wait operation: they either receive a token and queue construction, or return
immediately after observing another claim in progress.

The managed adapter keeps these details out of the OpAMP coordinator and exporter:

internal interface IManagedProfilingHostInterop
{
    HostClaimOutcome TryClaim();
    HostAvailability WaitForAvailability(TimeSpan timeout);
    HostOperationResult RegisterCanary(HostToken token);
    HostOperationResult ConfirmReady(HostToken token);
    NativeContextOutcome SetNativeContext(ActivityContext context);
    int Read(HostToken token, SampleType type, byte[] buffer, out uint interval);
    HostOperationResult Release(HostToken token);
}

HostToken is a managed value type that supports equality only so the bridge can
associate a completion with its own asynchronous construction. It exposes no numeric
value or ordering to callers. The adapter owns P/Invoke names, status-code mapping,
exception containment, and disposal of local resources after token revocation.

The token is an opaque capability handle, not an epoch visible to managed policy.
Managed code stores the exact value returned by ClaimGranted, supplies it to every
host-scoped operation, and discards it after any invalid-or-revoked result. A claim
cannot be transferred between AppDomains. Native rejects a valid token presented by
the wrong calling AppDomain. Native never reissues a token during the process
lifetime; counter wrap is handled by refusing a new claim rather than risking reuse.

A granted but unconfirmed claim has a 30-second lease. Managed code should explicitly
release the token if asynchronous construction fails. As a fail-safe, native checks
the lease before processing every configuration, claim, context, readiness, canary,
read, or release operation. An expired claim is revoked before that operation
continues, allowing the same call to observe or claim HostAbsent. This requires no
timer or polling thread. A late construction task receives
InvalidOrRevokedHostToken and disposes its local resources. Tests use an injected
clock rather than sleeping.

10.7.1 Legacy and token interop modes

Native preserves every existing export and signature for an old managed runtime
loaded with a new native package. Compatibility cannot, however, permit an untokened
legacy reader to bypass a token-selected owner. Native therefore selects exactly one
managed-consumer protocol for the process lifetime:

• Unselected is the initial mode;
• the legacy ConfigureContinuousProfiler compatibility shim selects Legacy;
• the first successful ClaimManagedProfilingHostV1 selects Token;
• after selection, a request from the other protocol cannot switch the mode.

In Legacy, existing configuration and read exports preserve their prior behavior;
the stronger host-token ownership and recovery guarantees do not apply. In Token,
legacy destructive-read exports return no data and emit a rate-limited compatibility
warning, while all removal occurs through token-bearing reads. An attempted token
claim in Legacy returns a distinct LegacyProtocolActive result; an attempted
legacy configuration in Token is ignored as a lower-capability compatibility call
and logged. New managed code detects LegacyProtocolActive, avoids starting another
reader, and reports that dynamic managed-host adoption is unavailable for that
process. Mixed protocol versions across AppDomains are thus fail-closed rather than
allowed to create competing consumers.

The existing exported ShutdownContinuousProfiler operation is likewise honored
only in Legacy mode for compatibility. In Token mode it returns failure and emits
a rate-limited warning. New managed code never requests terminal native shutdown;
the CLR profiler's process-level shutdown callback invokes the internal controller
shutdown directly.

The inverse package mismatch is also explicit. If new managed code cannot resolve the
V1 configuration and host-token exports in an older native package, its interop
adapter falls back to the unchanged legacy startup contract for the process. It does
not attempt OpAMP runtime reconfiguration or host succession, and reports those
capabilities unavailable. Missing-entrypoint detection is contained in the adapter
and is never performed repeatedly on Activity or exporter hot paths.

Before an initially enabling Seed or ControlPlane call, managed code ensures that a
host is ready through the separate claim protocol. The configuration caller may own
that host, but no affinity between configuration authority and host ownership is
required. A configuration update remains valid when another AppDomain owns the host:
native commits the configuration according to authority and the current host
continues or reconciles as required. Host ownership never determines configuration
precedence.

The explicit claim operation is allowed while the committed policy is disabled so a
host can be prepared for deferred enablement. Managed startup does not call it for an
all-disabled Seed, preserving zero first-use cost. Native Apply independently enforces
that a transition enabling any producer has a ready host; otherwise it returns
ActivationFailed without committing the candidate. SetNativeContextVNext is more
selective: it offers a recovery claim only when committed policy is enabled and the
host is absent.

Every eligible AppDomain installs a lightweight Activity recovery bridge independent
of the heavyweight reader. When business Activity causes a context transition, the
bridge calls a versioned context operation. Besides recording context, native returns
the managed-host disposition:

SetNativeContextVNext(...)
    -> HostHealthy
    -> HostClaimGranted(hostToken)
    -> HostClaimInProgress
    -> ProfilingPolicyDisabled

The winning application thread does not construct the host synchronously. It queues
managed initialization, returns to business work, constructs the exporter reader and
canary together, and calls ConfirmManagedProfilingHostReadyV1. Native resumes the
committed producers only after that confirmation. Host construction failure releases
the claim and leaves the service in HostRequired. Configuration may change while
construction is in flight. Readiness confirmation therefore reconciles against the
configuration current at confirmation time: the host becomes HostReady, then native
runs only the currently enabled producers or remains quiescent if policy has become
all-disabled. Ready never promises that production was resumed.

10.7.2 Managed-host state machine

stateDiagram-v2
    [*] --> HostAbsent
    HostAbsent --> HostClaimed: Claim granted and token minted
    HostClaimed --> HostReady: Required bundle registered and readiness confirmed
    HostClaimed --> HostAbsent: Failure, lease expiry, or release
    HostReady --> HostAbsent: Owner unload or voluntary release
    HostAbsent --> Terminal: Profiler shutdown
    HostClaimed --> Terminal: Profiler shutdown
    HostReady --> Terminal: Profiler shutdown

Loading

HostAbsent and HostClaimed are producer-quiescent whenever committed policy asks
for profiling; together they satisfy the operational predicate HostRequired.
Entering HostClaimed mints a fresh host token. Every transition out of
HostClaimed or HostReady permanently revokes that token before another claim can
be granted. HostReady permits production according to the independently committed
runtime configuration; it does not itself enable any profiling feature.

Native overrides AppDomainShutdownStarted(AppDomainID) and performs only bounded,
non-blocking coordination in that callback:

1. if the unloading AppDomain owns the host, revoke its token;
2. invalidate its registered canary immediately rather than waiting for
   ThreadDestroyed;
3. request CPU/selective producer quiescence and asynchronous allocation-session
   teardown;
4. preserve configuration, authority, accepted revision, and runtime generation;
5. publish HostRequired and return without waiting for managed cleanup.

AppDomainShutdownFinished performs residual bookkeeping but is too late to be the
primary revocation signal. Managed release during ordinary disposal is useful but
best-effort; correctness does not depend on a managed DomainUnload handler making a
P/Invoke while unload is in progress.

Every destructive read supplies the current host token. Native validates both the
token and calling AppDomainID under the same controller lock used for revocation.
The read's authorization and removal of the batch are one serialized operation, so
the old AppDomain cannot remove another batch after ownership has been revoked.

This contract provides single-consumer ordering, not exactly-once network delivery.
Once a complete batch has been removed from native storage and handed to managed code,
the batch may be lost if that AppDomain disappears during serialization or HTTP
export. Avoiding that loss would require a separate reservation-and-acknowledgement
protocol and is outside the initial contract. Subsequent consumers continue with
future queued batches.

On modern .NET there is one AppDomain and no canary requirement, but the same host
contract keeps integration uniform.

10.7.3 Scope limitation: recovery during complete silence

Activity is the natural recovery vehicle because it represents the business work for
which profiling is useful. When a surviving AppDomain next observes an Activity
transition, it can recover the missing host before native resumes sample production.

If the process produces no subsequent managed Activity or control traffic after the
owner unloads, the service remains safely quiescent in HostRequired. Complete
silence may mean legitimate idleness, absence of a surviving application AppDomain,
or application deadlock; this contract does not attempt to distinguish those cases.
Deadlock detection and liveness reporting are broader diagnostic concerns and are
explicitly outside the current PR scope. This limitation is no worse than the current
behavior, in which unloading the sole exporter owner also leaves no functioning
consumer or automatic recovery path.

10.7.4 AppDomain failure is not process shutdown

In the token protocol, terminal native shutdown belongs only to process-level CLR
profiler shutdown. A managed initialization rollback, exporter failure, canary
failure, or DomainUnload handler may release its own host token and dispose its
local resources, but must not invoke terminal shutdown. Native remains bootstrapped,
preserves its committed configuration and authority, and permits a surviving
AppDomain to claim a replacement host. This removes any need for AppDomain
initialization-owner reference counting as a condition for native service survival.
The legacy-mode exception exists only to preserve an old managed runtime's behavior.

10.8 Producer-consumer transaction ordering

Managed consumer transitions and native producer transitions form an ordered
protocol, not a distributed atomic transaction:

Enable producer:
    parse and merge
    -> if no ready host, attempt separate native host claim
    -> claim winner asynchronously constructs reader/exporter and canary bundle
    -> confirm host readiness
    -> apply complete native configuration
    -> native atomically commits and activates the configuration
    -> on rejection, reconcile; retain or quiesce the already-ready host

Disable producer:
    apply complete native configuration
    -> wait for returned native generation barrier
    -> drain and flush complete buffered samples
    -> quiesce the managed host while retaining its token

An exporter-prepared flag is therefore unnecessary in the native configuration.
Host readiness is a separate precondition for an initially enabling Apply. A
committed enabled policy may coexist with HostRequired only after later host loss;
its replacement host reactivates that retained policy on readiness confirmation. The
native generation barrier is the managed precondition for final drain and host
quiescence.

10.9 OpAMP result mapping

Managed code maps native outcomes to the control plane while preserving native
detail in logs and diagnostics:

Native outcome	Managed OpAMP disposition
Applied	Applied; report returned effective configuration
NoChange	Applied; report returned effective configuration
RejectedInvalid	Failed; retain and report last known good state
RejectedStaleRevision	Failed as stale local ordering; reconcile returned state
RejectedRevisionConflict	Failed as coordinator/protocol defect; reconcile returned state
RejectedBaseGeneration	Re-merge and retry once; fail if the retry also races
BootstrapFailed	Failed; profiling remains unavailable
ActivationFailed	Failed; retain and report last known good state
ShuttingDown	Failed or terminal, without retry during profiler shutdown
LegacyProtocolActive	Failed as incompatible process mode; do not retry or start a reader

IgnoredSeedAlreadyEstablished and IgnoredLowerAuthority are startup outcomes, not
normal ControlPlane results. Seeing either for an OpAMP submission indicates an
incorrect authority value or integration defect.

The OpAMP hash is never passed to native code. The managed coordinator correlates the
hash, assigned revision, returned native generation, result, and effective state for
diagnostics and protocol reporting.

11. Atomic application

One controller mutex serializes seed, control-plane, and terminal-shutdown commands.
The active configuration is published as an immutable snapshot with an increasing
native generation.

Application follows a prepare/commit protocol:

1. Decode and normalize the complete ABI value.
2. Under the controller lock, compare the ControlPlane expected base generation and
   return the current state immediately if it has changed.
3. Validate configuration, authority, and revision without changing state.
4. Ensure source-neutral bootstrap.
5. If the candidate transitions any producer from disabled to enabled, require one
   ready managed host; otherwise return ActivationFailed without committing.
6. Prepare native resources required by newly enabled features while keeping them
   gated.
7. Reach the defined safe boundary for producers being disabled or changed.
8. If preparation or safe-boundary transition fails, release newly prepared
   resources, restore any temporarily paused producer, and retain the committed
   configuration, authority, revision, and generation.
9. Publish the complete immutable snapshot and increment the native generation.
10. Record authority and accepted control-plane revision as part of the same commit.
11. Wake or activate producers required by the new snapshot.
12. Return the committed generation after the relevant producer boundary has been
    acknowledged.

Atomicity means observers see a coherent desired configuration. External CLR
operations are not intrinsically transactional, so fallible resource preparation is
completed and safely gated before publication.

12. Native producer lifecycles

12.1 CPU and selective-thread sampling

CPU and selective-thread sampling share one worker:

Dormant --first enable--> Running <--> Quiescent --shutdown--> Stopped

• Dormant: bootstrap is complete, but no sampling worker exists.
• Running: at least one thread-sampling feature is enabled.
• Quiescent: the worker exists and waits for configuration or shutdown.
• Stopped: terminal state; the worker cannot restart.

This is a cold-until-first-use, then warm-for-process-lifetime policy. A feature that
is never enabled pays no worker-thread cost. After first activation, ordinary disable
retains one inexpensive waiting thread. Re-enable is a wake operation rather than a
thread create/join maneuver.

Configuration publication wakes the worker immediately. An interval change does not
wait for the previous interval to expire. When both thread-sampling features are
disabled, the worker acknowledges the generation and waits without polling.

At the beginning of a cycle, the worker acquires one immutable configuration
snapshot. A produced batch records the CPU interval actually used for that batch.

12.2 Allocation sampling

Allocation sampling has an independent lifecycle:

NoSession <--> EventPipeSessionActive --shutdown--> Stopped

• Enabling lazily starts an EventPipe session with the required provider and keyword.
• Updating only the allocation rate replaces the subsampler without duplicating the
  EventPipe session.
• Disabling stops the EventPipe session, waits for protected in-flight writers, and
  releases allocation-specific resources.
• Re-enabling establishes a new session.
• Enabling is rejected on runtimes without the required EventPipe profiler API.

EventPipe teardown is intentional because an inactive session has meaningful runtime
cost. This differs from retaining one quiescent sampling worker.

13. Capture and cancellation boundaries

Disable and shutdown use cooperative cancellation with different urgency.

13.1 Feature disable: thread boundary

If a committed configuration disables the sampling mode currently capturing:

1. finish the complete stack for the current thread;
2. observe cancellation before starting the next thread;
3. resume the runtime or release per-thread suspension through the normal guard path;
4. publish all completely captured thread stacks;
5. acknowledge the committed configuration generation;
6. enter quiescence if no thread-sampling mode remains enabled.

The resulting capture may cover only a subset of the originally enumerated threads,
but every exported pprof sample is a complete stack. A partial cohort is valid; a
partial stack is not.

An interval-only update does not cancel an in-progress capture. It changes scheduling
after the current safe boundary. If one thread-sampling mode is disabled while the
other remains enabled, only work made obsolete by the new configuration is curtailed.

13.2 Terminal shutdown: frame boundary

Terminal shutdown may abort the current stack walk at a frame boundary. The stack
callback records the current frame, reads a lock-free shutdown flag, and returns the
CLR-defined abort result when shutdown is requested.

No logging, allocation, mutex acquisition, loader call, or unsafe profiler API call
may be added to this callback path.

Because pprof has no ordinary partial-stack representation, the incomplete current
thread is discarded. Previously completed thread stacks remain valid and are
published when safe.

The governing rule is:

Preserve all semantically valid completed work; discard work that cannot be
represented truthfully.

14. Producer-consumer and flush protocol

Native controls producers; managed controls consumers. The ordering protocol is:

Enable:
    managed materializes and starts the consumer
    -> managed submits the complete native configuration
    -> native commits and activates the producer

Disable:
    managed submits the complete native configuration
    -> native reaches and acknowledges the producer safe boundary
    -> managed drains and exports complete native buffers
    -> managed quiesces the consumer

Native acknowledgement is a generation barrier: after acknowledgement, no new sample
for a disabled generation will be published.

Managed performs a bounded final drain analogous to flushing a writer before
quiescence. Export timeout or exception may discard remaining buffered data after a
warning, but it must not reactivate the producer, roll back native disablement, hang
the application indefinitely, or throw into user code.

Transport disconnection is not a native lifecycle signal. It neither disables
profiling nor changes authority.

15. Pull-request decomposition

15.1 PR 1: native dynamic-service contract

The first PR contains the complete native behavior for all three features:

• foundational capability selection during profiler initialization;
• source-neutral bootstrap guarded by std::call_once;
• the full versioned configuration payload;
• the versioned Apply and GetState interop operations;
• compare-and-apply reconciliation against the native runtime generation;
• migration of ConfigureContinuousProfiler to a delegating Seed shim;
• generic Seed and ControlPlane authority;
• the normative authority state machine and revision checks;
• complete validation and immutable-snapshot publication;
• dormant/running/quiescent/stopped shared-worker behavior;
• allocation EventPipe enable, update, disable, and shutdown;
• thread-level disable and frame-level terminal cancellation;
• generation acknowledgement and complete-stack publication;
• native managed-host claim, readiness, token validation, AppDomain-unload
  revocation, canary invalidation, and Activity-driven recovery;
• legacy startup compatibility mapped to Seed;
• native unit and contract tests.

No OpAMP parsing, remote-config merging, managed exporter construction, or public
plugin redesign belongs in this PR.

15.2 PR 2: managed control-plane adoption

The follow-up PR:

• consumes OpAMP AgentConfigMap and configuration hashes;
• defines the profiler-specific remote configuration schema;
• merges partial remote documents into a complete effective configuration;
• assigns ordered control-plane revisions;
• prepares consumers before native enablement;
• installs an Activity recovery bridge in every eligible AppDomain;
• constructs the exporter reader and .NET Framework canary only while holding the
  current native-issued host token;
• consumes the Apply and GetState operations through one managed interop adapter;
• submits only complete configurations;
• interprets every ApplyResult;
• reports remote and effective configuration status;
• drains and quiesces consumers after native acknowledgement;
• adds managed and end-to-end integration tests.

Tests that span OpAMP transport, managed merge, native production, and export belong
in the follow-up PR. Their end-to-end nature does not require the native lifecycle and
managed control-plane implementation to be reviewed as one change.

16. Native test contract

The native PR must test the following without timing sleeps where deterministic
barriers or fakes can be used.

16.1 Bootstrap

1. Concurrent Seed and ControlPlane calls execute bootstrap once.
2. Bootstrap publishes valid callback state before callback gates open.
3. An all-disabled first configuration creates no worker or EventPipe session.
4. Bootstrap failure is retained and later calls fail closed.

16.2 Authority

1. Invalid Seed from None leaves authority None.
2. Invalid ControlPlane from None leaves authority None, allowing a later valid
   Seed.
3. First valid Seed commits; later AppDomain-equivalent Seed calls are ignored.
4. Invalid ControlPlane over Seed preserves Seed.
5. Valid ControlPlane over Seed commits and permanently establishes ControlPlane
   authority.
6. Seed after ControlPlane is ignored.
7. Invalid ControlPlane after a valid ControlPlane preserves the last good
   configuration, authority, revision, and generation.
8. An all-disabled ControlPlane configuration remains authoritative.
9. No disconnect or absence of update causes fallback to Seed.
10. A stale ControlPlane revision cannot overwrite a newer accepted revision.
11. A rejected candidate does not advance the accepted revision.
12. Reuse of an accepted revision with a different value is rejected as a conflict.
13. A newer revision with identical effective values advances the accepted revision
    without publishing a new runtime generation or performing lifecycle work.
14. Concurrent candidates publish only one complete configuration at a time.

16.3 Interop ABI

1. Native and managed structure sizes and field offsets match for the V1 payloads.
2. Unsupported sizes, schemas, reserved values, authorities, and revision forms are
   rejected without reading beyond the declared structure or changing state.
3. Apply returns the authoritative state after applied, unchanged, ignored, and
   rejected outcomes.
   A successful Seed response contains the complete normalized Seed committed by
   native.
4. GetState returns one coherent snapshot and causes no bootstrap or lifecycle side
   effect.
5. Concurrent Apply and GetState calls never expose a mixed configuration or
   metadata generation.
6. The compatibility ConfigureContinuousProfiler shim constructs one complete
   Seed request and delegates to the same controller; it owns no independent guard
   or mutable state.
7. A ControlPlane request with a stale expected generation returns
   RejectedBaseGeneration and the actual coherent state without accepting its
   revision or performing lifecycle work.
8. A Seed request requires expected generation 0 and remains governed solely by
   authority precedence.
9. New token-bearing host and read exports use distinct versioned names; all existing
   export signatures and calling conventions remain byte-for-byte compatible.
10. Managed/native package mismatch selects one process-wide interop mode: old
    managed code remains functional in Legacy, while Token mode rejects
    untokened destructive reads and Legacy mode rejects new claims.
11. New managed code paired with an older native package detects missing V1 exports
    once, falls back to unchanged legacy startup behavior, and disables dynamic
    reconfiguration and host succession without repeated hot-path exceptions.

16.4 Configuration atomicity

1. Cross-related CPU/selective interval changes commit as one valid transition.
2. Invalid range or interval relationships leave the old snapshot unchanged.
3. Workers observe only old or new complete generations.
4. A failed resource preparation leaves the committed state unchanged.
5. An identical candidate returns NoChange without unnecessary lifecycle work.

16.5 Shared sampling worker

1. First CPU or selective enable creates exactly one worker.
2. Enabling both features still uses one worker.
3. Disabling the last feature quiesces rather than joins the worker.
4. Re-enable wakes the retained worker.
5. A configuration change interrupts a long wait immediately.
6. Terminal shutdown joins the worker exactly once and prevents restart.

16.6 Allocation sampling

1. Enable starts one EventPipe session.
2. Rate update does not duplicate the session.
3. Disable stops the session and drains protected writers.
4. Re-enable establishes a new valid session.
5. Unsupported-runtime enable is rejected without changing committed state.
6. EventPipe start or stop failure preserves a coherent last-known-good state.

16.7 Capture and shutdown

1. Disable during capture finishes the current thread and skips remaining threads.
2. Completed stacks are published; no incomplete stack is published.
3. Native acknowledgement occurs only after the disabled-generation publication
   boundary.
4. Shutdown during a stack walk aborts at frame granularity.
5. The incomplete current stack is discarded while earlier complete stacks survive.
6. Configuration racing with shutdown cannot recreate resources or restart a
   producer.

16.8 Managed-host ownership and Activity-driven recovery

1. Concurrent claims yield exactly one active host token.
2. A non-owner cannot destructively read any process-wide sample buffer.
3. Enabling configuration does not start native production until the claimed host
   confirms all required components ready.
4. On .NET Framework thread sampling, readiness requires native confirmation of the
   canary in the same AppDomain and ownership term.
5. AppDomainShutdownStarted revokes an unloading owner's host token and invalidates
   its canary without waiting for managed cleanup or ThreadDestroyed.
6. Host loss quiesces producers but preserves configuration authority, accepted
   ControlPlane revision, and runtime generation.
7. A read carrying a revoked host token cannot remove data.
8. The first eligible Activity/context transition after host loss grants at most one
   new host claim; concurrent transitions observe that a claim is in progress.
9. Host construction occurs asynchronously outside the business Activity callback.
10. Successful exporter-and-canary readiness resumes the committed configuration;
    failed construction returns to HostRequired.
11. No Activity after host loss leaves production quiescent; no polling or deadlock
    inference is required by this contract.
12. Profiler terminal shutdown revokes the host and rejects further claims.
13. A host token presented from an AppDomain other than its claimant is rejected.
14. Releasing and reclaiming the host in the same AppDomain produces a different
    token; late operations from the earlier host remain invalid.
15. Managed code can treat the token only as opaque: no test or implementation relies
    on its numeric ordering or representation.
16. Native host-registration-generation exhaustion cannot cause token reuse; a new
    claim is rejected and producers remain safely quiescent.
17. A claim made while policy is disabled may prepare a host, but an all-disabled
    startup does not claim one automatically and preserves zero first-use cost.
18. An enabling Apply without a ready host returns ActivationFailed and preserves
    the last-known-good configuration and authority.
19. An unconfirmed claim released explicitly or expired by the injected clock revokes
    its token and permits a later claim without a polling thread.
20. A readiness confirmation racing with an all-disabled configuration leaves the
    host ready and producers quiescent; Ready does not imply production.
21. Existing exported symbols retain their original names, signatures, calling
    conventions, and legacy behavior when the process selects Legacy mode.
22. The first successful new host claim selects Token mode; token-bearing reads then
    work and every untokened legacy destructive read returns no data.
23. If legacy configuration selects Legacy first, a new token claim returns
    LegacyProtocolActive and no second reader is started.
24. Concurrent legacy configuration and token claim select exactly one process mode;
    the losing protocol fails closed without changing the selected mode.
25. AppDomain-local initialization or host-construction rollback never invokes native
    terminal shutdown; it releases only that domain's token and managed resources.
26. In Token mode, terminal shutdown is accepted only from the process-level CLR
    profiler shutdown path and remains idempotent.
27. A configuration path observing ClaimInProgress waits on the native condition
    variable with a bounded timeout and can retry after claim release or lease expiry;
    an Activity path never waits.
28. The legacy shutdown export cannot terminate the service after Token mode is
    selected.

17. Managed integration test contract

The follow-up managed PR must demonstrate:

1. startup configuration is translated into one complete Seed snapshot;
2. an all-disabled startup creates no native or managed worker;
3. partial OpAMP data is merged in managed code into a complete effective snapshot;
4. ControlPlane can commit directly from None or override Seed;
5. consumers are ready before native producers are enabled;
6. invalid remote configuration is reported as failed and leaves the last good state
   active;
7. after the first valid ControlPlane commit, later Seed calls cannot overwrite it;
8. OpAMP disconnection leaves the last committed ControlPlane configuration active;
9. disable waits for the native generation barrier, drains buffers, and quiesces the
   consumer;
10. re-enable wakes retained workers without duplication;
11. exporter failure is bounded and does not escape into the application;
12. .NET Framework multi-AppDomain startup cannot overwrite process configuration.
13. a first partial ControlPlane update merges over authoritative Seed, or over the
    all-disabled value when authority is None, before submitting a complete value;
14. serialized OpAMP callbacks preserve revision order and allow revision gaps after
    rejected candidates;
15. Apply results are reconciled from returned native state rather than the attempted
    managed value;
16. GetState can rebuild coordinator state without bootstrapping or activating a
    native producer;
17. an enable rejection disposes only newly prepared consumers, while a successful
    disable drains consumers only after the native generation barrier;
18. the OpAMP hash remains correlated with managed revision, native generation,
    result, and effective configuration without crossing the native ABI.
19. when Seed wins between GetState and ControlPlane Apply, managed re-merges the
    same OpAMP document over the actual Seed returned by native and succeeds on one
    bounded retry;
20. when ControlPlane wins from None, a concurrent AppDomain Seed is ignored and
    reconciles to the returned ControlPlane state;
21. when startup submits no Seed, ControlPlane can commit directly from the
    canonical all-disabled None state;
22. an explicitly committed all-disabled Seed remains distinguishable from None
    and is a valid merge base for a later ControlPlane update.
23. multiple .NET Framework AppDomains may forward Activity context, but only the
    holder of the native-selected host token performs reads and export;
24. unloading a non-owner does not affect the current managed host;
25. unloading the owner moves the service to HostRequired, invalidates its canary,
    and quiesces production without changing committed runtime configuration;
26. the next Activity transition in a surviving AppDomain grants one asynchronous
    recovery claim and resumes only after exporter-and-canary readiness;
27. no post-unload Activity leaves the service quiescent and is documented as an
    accepted limitation rather than interpreted as proof of deadlock;
28. a revoked host cannot perform a late destructive read.

18. Why the horizontal split simplifies implementation

The native PR establishes one process-wide state machine before managed startup and
OpAMP integration are layered on top of it. Every configuration trigger therefore
uses the same contract and produces a deterministic result:

• repeated AppDomain startup calls are Seed candidates, so they cannot overwrite an
  established Seed or ControlPlane configuration;
• a valid ControlPlane configuration supersedes Seed only when its complete snapshot
  commits successfully;
• stale revisions, conflicting revision reuse, and invalid configurations are
  rejected without disturbing the last known good state;
• an all-disabled ControlPlane configuration remains authoritative and does not
  imply fallback to Seed;
• source-neutral bootstrap remains idempotent regardless of whether Seed or
  ControlPlane arrives first;
• producer activation, quiescence, EventPipe teardown, capture boundaries, and
  terminal shutdown can be tested without an OpAMP transport or exporter pipeline.

With those semantics owned by native code, the managed PR has a narrower role. It
interprets OpAMP documents, merges partial input into a complete effective
configuration, assigns ordered revisions, coordinates exporter readiness and drain,
and invokes the native contract. It does not need to reproduce native lifecycle or
authority decisions.

This separation reduces the number of concurrent concerns in each change. Native
tests establish service correctness under configuration and lifecycle races;
managed tests establish protocol translation and producer-consumer ordering. The
end-to-end tests then verify composition of two already-defined contracts rather
than being the only place where their semantics emerge.

[zacharycmontoya]

SIG: Suggest that we split the contracts separately to define continuous profiler sampling/semantics and OpAmp. We can first tackle the continuous profiler definition with a PR to update our docs with a shared definition, then build on the OpAmp interaction later