(causeway) 01/02: CAUSEWAY-3975: proposes main observation foundation and forward-port roadmap

[da...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

danhaywood pushed a commit to branch CAUSEWAY-3975-observation-foundation
in repository https://gitbox.apache.org/repos/asf/causeway.git

commit 13f98006d0876de37322af8f76447b74927fbaa6
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Sun Sep 27 12:15:03 2026 +0100

    CAUSEWAY-3975: proposes main observation foundation and forward-port roadmap
---
 .../.openspec.yaml                                 |   2 +
 .../design.md                                      |  79 +++++++++++++++
 .../proposal.md                                    |  31 ++++++
 .../specs/main-observation-foundation/spec.md      | 109 +++++++++++++++++++++
 .../reconcile-main-observation-foundation/tasks.md |  37 +++++++
 openspec/planned-changes/README.md                 |   8 ++
 .../planned-changes/otel-forward-port-roadmap.md   |  82 ++++++++++++++++
 7 files changed, 348 insertions(+)

diff --git a/openspec/changes/reconcile-main-observation-foundation/.openspec.yaml b/openspec/changes/reconcile-main-observation-foundation/.openspec.yaml
new file mode 100644
index 00000000000..7f2ad572a99
--- /dev/null
+++ b/openspec/changes/reconcile-main-observation-foundation/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-27
diff --git a/openspec/changes/reconcile-main-observation-foundation/design.md b/openspec/changes/reconcile-main-observation-foundation/design.md
new file mode 100644
index 00000000000..0cc53d74313
--- /dev/null
+++ b/openspec/changes/reconcile-main-observation-foundation/design.md
@@ -0,0 +1,79 @@
+## Context
+
+This is the first forward-port change associated with CAUSEWAY-3975. Analysis used maintenance merge `7e799dfd360` (#3813) and recorded `origin/main` at `351eae721d9`. Local `main` was 513 commits behind that remote-tracking ref. These are inspected snapshots, not a claim that the remote was freshly fetched.
+
+Main uses Boot `4.2.0-M1` in the inspected BOM, a commons-level `ObservationClosure`, Boot observation auto-configuration, and its own interaction carrier/layer lifecycle. Maintenance uses Boot 2.7, a core-config closure, and a dedicated observation registry bridged to the Java agent. Main additionally observes property modification, transactions, execution publishing and JPA operations. A replacement with maintenance classes would lose behavior and undo main's architecture.
+
+Confirmed source findings:
+
+- Main's closure does not clear its observation on close; a second close invokes stop again. A throwing scope close prevents stop.
+- Main's error method accepts `Exception`; maintenance's accepts `Throwable`.
+- Main's threshold wrapper returns the delegate from fluent methods and start. This permits callers to escape the wrapper; the effect on existing call sites needs characterization.
+- Main's inactive configuration supplies an unqualified no-op registry while the integration injects an optional registry. Application-registry coexistence needs explicit tests rather than assuming it is safe.
+
+## Goals / Non-Goals
+
+**Goals:** deterministic lifecycle cleanup, explicit opt-in semantics, compatibility with main's existing Boot-managed setup, proven agent context integration, and a reusable main-compatible regression fixture.
+
+**Non-Goals:** wholesale migration to maintenance's registry architecture; new semantic spans or applib APIs; new naming/privacy defaults; Wicket span budgets; asynchronous scope transfer; copying Boot 2.7 or Java 11 constraints.
+
+## Decisions
+
+### 1. Implement against main, with an initial baseline checkpoint
+
+Before implementation, refresh the target refs, inspect target instructions, and record the actual base SHA and BOM/toolchain versions. Use a main-based branch/worktree. Transfer these proposal artifacts there; do not apply production tasks in this maintenance tree. Reconcile any intervening changes in the affected classes and existing specs first.
+
+A fresh branch is preferred to replaying the maintenance merge, whose contents include history pruning and unrelated workspace files. Commit proposal artifacts before `/opsx-apply`, as required by repository instructions.
+
+### 2. Keep one lifecycle helper in main's existing location
+
+Adapt main's `commons/internal/observation/ObservationClosure`, retaining tagging/discard APIs and consumers. Do not introduce a second core-config helper. Clear held state before cleanup, close the scope before stopping the observation, and attempt stop even when scope cleanup fails. Repeated cleanup must not repeat either operation. Reject starting another observation while one is owned; clean up an observation already started if opening its scope fails.
+
+Accept `Throwable` and preserve the original work failure when reporting or cleanup also fails, attaching secondary failures as suppressed where feasible. The helper alone cannot preserve an application failure unless the caller supplies it, so inspect and adapt affected catch/finally consumers too. Preserve an existing `Exception` overload if required for binary linkage rather than silently removing it.
+
+Maintenance provides useful behavior and tests, but its synchronized methods do not make thread-local observation scopes transferable between threads. Cross-thread closing is not introduced by this change.
+
+### 3. Retain Boot-managed wiring by default and prove an agent-compatible configuration
+
+The `observation` profile gates Causeway instrumentation independently of whether an application has its own observation registry. The inactive path must use a no-op Causeway integration without disabling application observations or introducing an ambiguous registry injection. With the profile active, honor a single application-supplied registry or its Spring primary selection; use a fallback only when none exists. Multiple unqualified candidates must produce an actionable configuration  [...]
+
+Keep main's existing Boot configuration as the starting point. Establish two documented configurations in the fixture: the normal Boot-managed tracing setup and a Java-agent setup where framework observations join the agent-owned context. Each configuration must have one exporter/SDK owner for the trace under test. Do not activate independent Boot and agent pipelines and accept disconnected or duplicate traces.
+
+First test the actual target dependency set. If agent compatibility requires a bridge or auto-configuration exclusions, isolate that adaptation behind an explicit configuration and document it; do not make a dedicated agent registry the default as a side effect. If compatibility requires a broader ownership redesign, record the failed evidence and revise this design before expanding implementation scope. Successful agent compatibility remains an exit criterion, not an assumed property of Boot.
+
+### 4. Characterize and repair threshold composition
+
+Exercise the wrapper directly and through the production JPA observation path, including fluent customization and use with `ObservationClosure`. Ensure methods representing mutation/start retain wrapper identity so its stop policy is applied. Successful spans below the existing threshold remain discardable; failures must not be discarded solely because they completed quickly. Preserve the current threshold value in this change.
+
+Test that existing discard/export integration actually enforces the marker for each supported configuration. An exporter predicate registered only in Spring must not be assumed to control an agent-owned exporter. If the agent configuration cannot honor duration discarding without a broader pipeline change, explicitly disable that optimization for that configuration and document that spans are retained; do not claim a marker guarantees suppression.
+
+Duration filtering can leave exported descendants whose parent is absent. Record that limitation and defer a different sampling/volume policy to the metadata/policy follow-up. Wicket's later admission budget is a different mechanism and must not be implemented here.
+
+### 5. Carry evidence, not maintenance dependency pins
+
+Adapt `regressiontests/tracing-compatibility` as a child-process fixture using main's supported Java version and BOM. Preserve bounded startup/shutdown, asynchronous output draining, and useful failure diagnostics from maintenance follow-ups `90512b829c1`, `769f13af9a5`, and `523117e7de4`, without carrying the Java 11 pin.
+
+Use a local OTLP receiver and deterministic sampling for assertions. Prove an inbound HTTP span, framework interaction/action descendants, and JDBC descendants share the expected trace and parent IDs, with one framework span per invocation. Also test profile off, no agent/no exporter, and failure cleanup. Unit tests cover lifecycle fault injection that would be difficult to force reliably through a process fixture.
+
+Inventory existing observation sites before edits and account for them afterward. Attach focused regression evidence for interaction nesting, property changes, transactions and publishing so maintenance's smaller instrumentation surface cannot become an accidental replacement.
+
+## Risks / Trade-offs
+
+- [Target drift] → Refresh and record the main baseline before implementation; regenerate specs if a matching capability now exists.
+- [Boot and agent have different ownership contracts] → Prove both documented configurations and keep any agent adaptation explicit.
+- [Discard predicates may not control agent export] → Assert exported output, and document retained spans where filtering is unsupported.
+- [Cleanup exceptions can mask application failures] → Test primary/suppressed exception precedence at helper and consumer boundaries.
+- [More error spans are exported] → Document the deliberate exception to duration suppression.
+- [Scope expands into privacy or naming redesign] → Track those changes separately in the roadmap.
+
+## Migration Plan
+
+No data migration is required. Deliver the change as a main-targeted PR with focused tests, fixture evidence and configuration guidance. Preserve existing opt-in activation and normal Boot-managed application setup. Document any explicit agent-mode settings separately. Rollback is a code/configuration revert; no persisted schema or application API migration is intended.
+
+## Open Questions
+
+- Which exact Boot/agent versions will be present on the refreshed target, and what wiring joins their context? Resolve in the first compatibility tasks using the target dependencies.
+- Does the current threshold wrapper fail through existing call sites, or only through permitted fluent composition? Characterize before modifying it.
+- Does agent-mode export support the existing discard contract? If not, document the retained-span behavior specified above.
+
+These are bounded implementation investigations. They do not authorize switching the default telemetry owner without updating this proposal.
diff --git a/openspec/changes/reconcile-main-observation-foundation/proposal.md b/openspec/changes/reconcile-main-observation-foundation/proposal.md
new file mode 100644
index 00000000000..8b22a8e48e4
--- /dev/null
+++ b/openspec/changes/reconcile-main-observation-foundation/proposal.md
@@ -0,0 +1,31 @@
+## Why
+
+Main already implements CAUSEWAY-3975, but its observation lifecycle and telemetry wiring differ from the subsequently hardened maintenance implementation. Before forward-porting CAUSEWAY-4058 through CAUSEWAY-4068, main needs a tested foundation that preserves its existing instrumentation and connects framework spans to the intended telemetry pipeline.
+
+## What Changes
+
+- Harden main's observation closure for repeated cleanup, partial initialization, and `Throwable` recording while retaining its tagging and discard support.
+- Preserve main's Boot-managed integration as the default architecture; establish explicit activation and registry selection behavior, including application-provided registries.
+- Adapt the maintenance real-agent fixture to main to verify framework/HTTP/JDBC parentage, inactive behavior, safe operation without an agent, and absence of duplicate framework exports. Document the supported telemetry ownership configuration and any required exclusions.
+- Characterize and correct threshold-wrapper behavior where fluent composition bypasses its lifecycle; preserve failures rather than discarding them solely for short duration.
+- Document the existing observation inventory and a metadata-policy follow-up so subsequent ports do not erase main-only instrumentation.
+
+## Capabilities
+
+### New Capabilities
+
+- `main-observation-foundation`: Lifecycle, opt-in activation, telemetry ownership, threshold behavior, and compatibility evidence required for forward ports. This formalizes existing implementation contracts as well as strengthening them; no corresponding main spec was found in the inspected snapshot.
+
+### Modified Capabilities
+
+None.
+
+## Impact
+
+Implementation targets **main**, not the maintenance working tree in which these planning artifacts were authored. Expected areas are `commons` observation utilities, `core/config` observation integration, their runtime/JPA consumers, and a main-compatible tracing regression fixture. Retain main's BOM-managed dependency versions; do not copy Boot 2.7 pins, Java 11 fixture assumptions, or maintenance's interaction implementation.
+
+No public applib API change is intended. Error-span retention can increase exported short-failure spans. Registry wiring changes require application-registry compatibility tests. The roadmap and source references are in [the forward-port plan](../../planned-changes/otel-forward-port-roadmap.md).
+
+## Non-goals
+
+No Wicket detail, semantic renaming, classification, correlation, priming, application span API, metamodel fix, or wholesale telemetry ownership migration. JPA naming and identity-data policy changes are a separate follow-up. This proposal does not authorize implementing on maintenance or deploying telemetry infrastructure.
diff --git a/openspec/changes/reconcile-main-observation-foundation/specs/main-observation-foundation/spec.md b/openspec/changes/reconcile-main-observation-foundation/specs/main-observation-foundation/spec.md
new file mode 100644
index 00000000000..53680aad70c
--- /dev/null
+++ b/openspec/changes/reconcile-main-observation-foundation/specs/main-observation-foundation/spec.md
@@ -0,0 +1,109 @@
+## ADDED Requirements
+
+### Requirement: Observation ownership has deterministic cleanup
+
+The lifecycle helper SHALL close each successfully opened scope and attempt to stop each owned started observation exactly once, in that order, and SHALL release references even when cleanup fails. It SHALL reject a second start while an observation is active.
+
+#### Scenario: Repeated cleanup
+- **WHEN** a started observation is closed and cleanup is called again
+- **THEN** scope closure and observation stop are each invoked once and no closed observation remains current
+
+#### Scenario: Scope cleanup fails
+- **WHEN** closing the observation scope throws
+- **THEN** observation stop is still attempted and subsequent cleanup does not repeat either operation
+
+#### Scenario: Opening scope fails
+- **WHEN** an observation starts successfully but opening its scope throws
+- **THEN** the failure is recorded where possible, stop is attempted once, held state is cleared, and the original failure propagates
+
+#### Scenario: Duplicate start
+- **WHEN** a second observation is supplied while the helper still owns an active observation
+- **THEN** the helper rejects the attempt without starting the second observation or losing the first
+
+### Requirement: Failures remain attributable to application work
+
+The observation lifecycle SHALL support recording any `Throwable`. Instrumented consumers SHALL preserve the original work failure if observation reporting or cleanup also fails, retaining secondary failures as suppressed where feasible. Existing tag and explicit discard operations SHALL remain available.
+
+#### Scenario: Work throws an Error
+- **WHEN** observed work throws an `Error`
+- **THEN** that failure is reported to the observation and the same failure propagates after cleanup
+
+#### Scenario: Cleanup also fails
+- **WHEN** work throws and observation cleanup subsequently throws
+- **THEN** the work failure remains the primary propagated failure and cleanup is not skipped
+
+#### Scenario: Existing helper consumers
+- **WHEN** an existing main consumer tags or explicitly discards an observation
+- **THEN** those operations remain supported without introducing a second lifecycle helper
+
+### Requirement: Causeway activation is independent of application observations
+
+Causeway framework observations SHALL remain opt-in through the `observation` profile. Inactive Causeway instrumentation SHALL NOT disable an application's own observations. Active integration SHALL use the application's single or primary registry when supplied, otherwise a configured fallback. Unresolved multiple registries SHALL cause an actionable configuration error.
+
+#### Scenario: Inactive profile with application registry
+- **WHEN** the profile is inactive and an application supplies a working observation registry
+- **THEN** Causeway emits no framework spans, application observations still work, and startup has no registry ambiguity introduced by Causeway
+
+#### Scenario: Active profile with custom registry
+- **WHEN** the profile is active and the application supplies one registry or designates a primary registry
+- **THEN** Causeway uses that registry without creating a competing default registry
+
+#### Scenario: No telemetry exporter
+- **WHEN** the profile is active without a Java agent or configured exporter
+- **THEN** application startup and observed work complete safely without requiring an exporter
+
+#### Scenario: Ambiguous application registries
+- **WHEN** the active configuration has multiple registry candidates and no primary selection
+- **THEN** startup reports the ambiguous registry selection rather than choosing arbitrarily
+
+### Requirement: Supported telemetry configurations have one trace owner
+
+The implementation SHALL preserve a supported Boot-managed configuration and document a tested Java-agent-compatible configuration. Each configuration SHALL use a single SDK/export owner for the tested trace. The agent configuration SHALL join framework observations to automatic HTTP and JDBC context without duplicate framework export.
+
+#### Scenario: Agent exports a framework request
+- **WHEN** an HTTP request invokes a framework action that performs JDBC work under the documented agent configuration
+- **THEN** collected spans show the expected HTTP-to-framework-to-JDBC ancestry in one trace and exactly one framework span for each expected invocation
+
+#### Scenario: Boot-managed application
+- **WHEN** a main application uses the documented Boot-managed tracing configuration without an agent
+- **THEN** framework observations export through its configured tracing integration without requiring agent-specific wiring
+
+#### Scenario: Failed request followed by successful request
+- **WHEN** a failing observed request is followed by another request
+- **THEN** the failure is recorded and the later request does not inherit stale observation state
+
+### Requirement: Duration filtering survives observation composition
+
+Threshold observations SHALL retain their stop policy through fluent customization, start and lifecycle-helper use. In configurations supporting duration filtering, successful observations below the threshold SHALL be suppressed and observations at or above it SHALL remain eligible for export. Failed observations SHALL NOT be suppressed solely for short duration. Any agent-mode limitation on discard export SHALL be documented and tested as retained-span behavior rather than silently assu [...]
+
+#### Scenario: Fluent customization before start
+- **WHEN** a threshold observation is customized through its fluent methods and run through the lifecycle helper
+- **THEN** its threshold policy still runs when it stops
+
+#### Scenario: Successful short observation
+- **WHEN** a successful observation completes below the threshold in a configuration supporting duration filtering
+- **THEN** it is discarded from export
+
+#### Scenario: Successful longer observation
+- **WHEN** a successful observation reaches or exceeds the threshold
+- **THEN** duration filtering does not discard it
+
+#### Scenario: Short failed observation
+- **WHEN** an observation fails below the threshold
+- **THEN** duration filtering does not discard the failure
+
+#### Scenario: Agent exporter cannot enforce discard
+- **WHEN** the documented agent configuration cannot apply the existing discard policy
+- **THEN** duration suppression is explicitly disabled for that configuration, collected spans confirm retention, and the configuration guide explains the limitation
+
+### Requirement: Foundation reconciliation preserves main instrumentation
+
+The change SHALL preserve main's existing interaction, action, property modification, transaction, execution-publishing and JPA instrumentation boundaries. It SHALL use main-compatible dependency and toolchain versions rather than maintenance's compatibility pins.
+
+#### Scenario: Existing instrumented operations
+- **WHEN** the foundation change is validated against the recorded main observation inventory
+- **THEN** each existing instrumentation boundary is accounted for and focused regression coverage verifies affected paths
+
+#### Scenario: Main compatibility fixture
+- **WHEN** the tracing fixture runs on the target main toolchain
+- **THEN** it validates production integration with bounded process waits and output draining, without imposing Boot 2.7 or Java 11 on main
diff --git a/openspec/changes/reconcile-main-observation-foundation/tasks.md b/openspec/changes/reconcile-main-observation-foundation/tasks.md
new file mode 100644
index 00000000000..e4b7b2c46f2
--- /dev/null
+++ b/openspec/changes/reconcile-main-observation-foundation/tasks.md
@@ -0,0 +1,37 @@
+## 1. Establish the main implementation baseline
+
+- [ ] 1.1 Refresh target refs, record the actual main SHA and toolchain/BOM versions, and inspect target AGENTS.md and existing observation specs for intervening changes.
+- [ ] 1.2 Prepare a main-based branch/worktree, transfer these planning artifacts, and commit uncommitted proposal artifacts before application. Do not implement in the maintenance checkout.
+- [ ] 1.3 Inventory main observation creation/cleanup sites, registry beans, handlers, exporter predicates and existing tests; record the main-only instrumentation that must be preserved.
+- [ ] 1.4 Characterize the target Boot-managed configuration and agent integration requirements; record a concrete wiring plan with one SDK/export owner per supported configuration. Revise the design before any broader default-ownership migration.
+
+## 2. Harden observation lifecycle
+
+- [ ] 2.1 Add focused main-helper tests for repeated close, duplicate start, scope-open failure, scope-close failure and stop failure, including current-context restoration.
+- [ ] 2.2 Adapt main's existing closure to clear ownership and attempt ordered cleanup once; retain tag/discard support and any necessary binary-compatible error overload.
+- [ ] 2.3 Support Throwable recording and update affected consumers so work failures remain primary when reporting/cleanup also fails; test Error and suppressed-exception behavior.
+
+## 3. Make activation and registry selection explicit
+
+- [ ] 3.1 Add Spring configuration tests for inactive/active profiles with no application registry, one supplied registry, a primary registry and ambiguous candidates.
+- [ ] 3.2 Adjust main's wiring so inactive Causeway observations use no-op integration without disabling application observations, while active integration honors Spring registry selection and a fallback only when absent.
+- [ ] 3.3 Verify active operation without an agent/exporter and normal Boot-managed tracing; implement only the explicit agent adaptation identified in task 1.4.
+
+## 4. Verify threshold and discard behavior
+
+- [ ] 4.1 Reproduce threshold-wrapper behavior directly, through fluent composition and the closure, and through its JPA observation-provider usage; distinguish confirmed defects from suspected ones.
+- [ ] 4.2 Preserve wrapper lifecycle/policy through composition, retain short failures, and test below/at/above threshold behavior without timing-sensitive sleeps where possible.
+- [ ] 4.3 Verify actual discard export behavior for each supported telemetry configuration; where agent export cannot honor it, disable duration suppression explicitly and document/test retained spans.
+
+## 5. Establish exported-trace regression evidence
+
+- [ ] 5.1 Adapt the maintenance child-process/OTLP fixture to main dependencies and Java, retaining output draining, bounded waits and startup diagnostics without copying legacy version pins.
+- [ ] 5.2 Assert HTTP/framework-action/JDBC ancestry and one framework span per expected invocation in the supported agent configuration; exercise the production integration rather than a substitute tracer.
+- [ ] 5.3 Add fixture coverage for profile off, no agent/exporter, failed work and a subsequent request without stale context; verify Boot-managed export separately.
+- [ ] 5.4 Run focused lifecycle/configuration and affected runtime/JPA tests, including interaction nesting, property modification, transactions and publishing; account for every baseline instrumentation boundary.
+
+## 6. Document and prepare review
+
+- [ ] 6.1 Write main-appropriate activation, Boot/agent ownership and compatibility guidance with exact validated versions, supported exclusions, discard limitations and error-retention behavior.
+- [ ] 6.2 Record executed checks and fixture evidence, update roadmap status/source-to-target mapping, and preserve the metadata-policy follow-up as separate work.
+- [ ] 6.3 Validate the OpenSpec change and review the final diff for unrelated maintenance artifacts, legacy dependency pins, accidental instrumentation loss and unplanned public API changes.
diff --git a/openspec/planned-changes/README.md b/openspec/planned-changes/README.md
new file mode 100644
index 00000000000..a79c5aae298
--- /dev/null
+++ b/openspec/planned-changes/README.md
@@ -0,0 +1,8 @@
+# Planned changes
+
+This directory records cross-change roadmaps and investigation notes. Entries are plans, not implemented capabilities or active OpenSpec changes. Promote a feature into `openspec/changes/` when its scope is ready; update its status here as it progresses.
+
+- [Web-component viewer plans](web-component-viewer/)
+- [OpenTelemetry and related maintenance-to-main forward ports](otel-forward-port-roadmap.md)
+
+The first active proposal is [reconcile-main-observation-foundation](../changes/reconcile-main-observation-foundation/proposal.md). Its implementation target is **main**. These artifacts were initially authored on maintenance and transferred to this main worktree for further planning and implementation.
diff --git a/openspec/planned-changes/otel-forward-port-roadmap.md b/openspec/planned-changes/otel-forward-port-roadmap.md
new file mode 100644
index 00000000000..76e60b770df
--- /dev/null
+++ b/openspec/planned-changes/otel-forward-port-roadmap.md
@@ -0,0 +1,82 @@
+# OpenTelemetry and related forward ports to main
+
+## Baseline and purpose
+
+Prepared 2026-09-27 from maintenance merge `7e799dfd360` (PR #3813, CAUSEWAY-4066 branch) and recorded `origin/main` at `351eae721d9`. The planning checkout was maintenance at `b028fca1132`; local `main` was 513 commits behind `origin/main`. No remote freshness verification or runtime testing was performed during exploration. Refresh these references before implementation.
+
+Main already contains CAUSEWAY-3975, including instrumentation absent from the smaller maintenance backport. The task is to reconcile and extend main, not replay the merge or replace its observation implementation. Use feature-sized PRs with the originating ticket as provenance. Numeric ticket order is not a dependency order, and no 4064 implementation was identified in this merge.
+
+## Roadmap
+
+| Sequence | Ticket / feature | Status and proposed scope | Implementation source anchors |
+|---|---|---|---|
+| 1 | 3975: foundation reconciliation | **Proposed:** [active change](../changes/reconcile-main-observation-foundation/proposal.md). Lifecycle cleanup, activation/registry selection, Boot/agent compatibility evidence, threshold behavior, preservation of main instrumentation. | `9b8b66d5b7b`, `e6752f882b5`; compare main's original 3975 implementation |
+| 1b | 3975 follow-up: metadata and observation policy | Planned. Stable operation names vs contextual names; review bookmark/query-description names, identity attributes, hard-coded duration threshold and missing exported parents. Set policy before adding new semantic names. No ticket beyond originating 3975 assigned here. | Main `JpaEntityFacet`, runtime `ia/_Observation`, `CausewayObservationIntegration` |
+| 2 | 3975 + 4068: classification and correlation | Planned. Foreground/background classification, root interaction ID, configurable execution-mode attribute key. Depends on foundation; adapt to main's interaction layers. | `024bd33128d`, `0325232a3c7`, `3083a51eabd` |
+| 3 | 4058: current action context | Planned. Exact-current-action queries and rule-checking state; nested restoration and physical mixin receiver semantics. Can proceed independently of most telemetry work. | `6d037db6609`; account for `f66b8f17a89` |
+| 4 | 4062: semantic member names | Planned. Bounded operation categories with domain-facing contextual names; mixed-in property/collection access distinguished from actions. Depends on foundation and naming policy. | `a2ae5877c99`, `d5ecd49a1f3`, `45e01ff6f42` |
+| 5 | 4059 + relevant 4062: Wicket regions/preparation | Planned. Entity-page preparation, region rendering and action prompts; Ajax ancestry, serialization and failure cleanup. The 4062 source touches Wicket as well as core: extract the relevant portions here rather than blindly applying step 4 commits. | `a8264fd1f9b`, relevant parts of `a2ae5877c99` / `45e01ff6f42` |
+| 6 | 4062 + 4067: collection detail and volume | Planned. Table phases, rows, cells, row actions; deliver detail levels, request budgets and collection aggregates with the new detail. Depends on Wicket regions. | `8e5eaab6145`, `036a28a23c2`, `5a1dc2dd17b` |
+| 7 | 4063: semantic trace display names | Planned. Foreground entry-span naming from prioritized action/prompt/view nominations. Depends on classification, semantic naming and Wicket nominations for Wicket support. | `e17c3088ac2` |
+| 8a | 4059: audit-trail writing | Planned. Observe audit subscriber work, preserving transaction semantics and failures. Depends on foundation only. | `7961910a089` |
+| 8b | 4059: entity-change evaluation | Planned. Observe evaluation in persistence commons, preserving existing main publishing/transaction spans. Depends on foundation only. | `02786054574` |
+| 9 | 4065: application-defined spans | Planned. Public service, nested spans, suffix/name contract, no-op implementation and action identity correction. Depends on foundation, action context and naming policy. | `ea32b739d0f`, `5da64c34b57`, `f66b8f17a89` |
+| 10a | 4066: application priming hooks | Planned. Registrar, startup validation, immutable argument view, action callbacks and once-per-request entity-view callbacks. Useful independently of tracing; adapt to main's metamodel/action/Wicket lifecycles. | `19d2a36d2f9` |
+| 10b | 4066: primer observations | Planned. One span per matching callback, natural parentage, failure propagation. Depends on priming hooks and semantic naming. | `473454f2447` |
+| Separate A | 4060: introspection diagnostics | Planned. Retained introspection chain, overflow diagnostics and stable mixin traversal; assess overhead and preserve behavior. No telemetry dependency. | `fb28fa67e06` |
+| Separate B | 4061: mixin prefilter | Planned. Check applicability using type metadata before requesting full member introspection; preserve applicable contributions and ordering. Follow diagnostics for evidence, but the fix is not conceptually dependent on tracing. | `680ac40ef52` |
+
+## Dependency sketch
+
+```text
+3975 foundation ──┬── classification/correlation ──────────────┐
+                 ├── audit and entity-change observations     │
+                 └── metadata policy → semantic names ────────┤
+                                          │                  │
+                                          ├→ Wicket regions ─┼→ trace display names
+                                          │       └→ collection detail + budgets
+4058 current-action context ────────────────┴→ application spans
+priming hooks ── + foundation/semantic names ─→ primer observations
+
+metamodel diagnostics → mixin applicability prefilter (separate track)
+```
+
+## Foundation findings and decisions to retain
+
+- Main's closure can stop twice and skips stop if scope closing throws; maintenance clears state and uses finally for stop. Port behavior into main's existing helper, not its maintenance package location.
+- Main's threshold wrapper returns its delegate from fluent methods/start. Potential bypass needs a targeted reproduction; no runtime defect was claimed during exploration.
+- Main uses Boot-managed configuration; maintenance constructs a dedicated registry/tracer against agent-owned global context. The first proposal retains main's default and requires evidence for an explicitly supported agent configuration. Do not assume a Spring exporting predicate controls the agent exporter.
+- Main has property editing, transaction, publishing and JPA spans. Preserve these while adapting the maintenance features to main's interaction carrier/layers.
+- Main includes bookmarks/query descriptions in some JPA observation names and username/tenancy attributes on interactions. Maintenance's newer features deliberately use bounded domain-level metadata. Resolve the policy in step 1b, documenting any telemetry naming compatibility changes.
+- 4058 distinguishes the physical action receiver/identifier from the domain-facing identity needed for spans. The later `f66b8f17a89` correction must inform both 4058 and 4065; do not rewrite invoked identifiers to solve display naming.
+- Maintenance's 4067 defaults are `MEMBERS` detail and unlimited budget (`0`) for compatibility. Main can consider different defaults, but that is an explicit feature decision backed by representative traces, not an incidental port change.
+- Priming is an application hook for bulk loading into the current persistence context, not an ORM-specific fetch implementation. Action and view hooks must remain useful with observation disabled.
+- Wicket-only features do not imply equivalent coverage for main's web-component viewers. Extending those viewers requires a separately scoped proposal.
+
+## Tests, tooling and documentation
+
+Carry focused tests and documentation with every feature. Telemetry gates include profile off, missing exporter/agent, success, failure, cleanup and real exported ancestry. Wicket gates additionally include full-page/Ajax, serialization, reduced-detail ancestry and hard budget limits. Public invocation APIs require exact identity, checked/skipped/unknown rule status, nested restoration and mixin coverage. Metamodel fixes require applicable/inapplicable mixins and repeated deterministic i [...]
+
+Adapt the maintenance process fixture early. Sources include `8d3771bb852`, `regressiontests/tracing-compatibility`, and follow-ups `90512b829c1`, `769f13af9a5`, `523117e7de4`. Retain output-draining and bounded process waits; replace the Java 11 constraint and old telemetry pins with target-main-compatible versions. Do not import Boot 2.7's observation/bridge dependency management.
+
+Local tooling/docs sources include `acc65829bbd`, `8628d26fdc3`, `0a02d0b59d1`, `f5a499d50ef`, `d141c96edfb`, `scripts/jaeger-local-*`, `scripts/otel-local-env.sh`, its shell tests, and `adoc/micrometer-tracing-operations.adoc`. Port a main-appropriate runbook and comparison tooling as an early companion to foundation validation; do not copy the Boot 2.7 operating guide verbatim. Integrate the final guidance into main's documentation structure.
+
+## Recovering design evidence
+
+OpenSpec changes/specs were deleted during the maintenance sequence, but remain in Git:
+
+- `473d2c218c4^:openspec/changes/archive/` contains the early Boot 2.7 substrate, tracing and current-action-context designs.
+- `1a9910c3e77^:openspec/changes/archive/` contains Wicket rendering, naming, audit/evaluation, priming, application spans, volume controls and metamodel designs.
+- `1ac42dc5408^:openspec/changes/archive/` contains the later 4068 artifacts.
+
+Inspect with `git ls-tree -r --name-only <ref> openspec` and `git show <ref>:<path>`. Earlier proposals can be superseded by later implementation/fix commits; use the final maintenance code and tests as the behavior reference, with archived designs explaining intent.
+
+## Execution rules
+
+1. Refresh target main and inspect its instructions, specs, toolchain and integration changes before implementing each feature.
+2. Create a main-based branch/worktree and transfer the relevant proposal artifacts. Keep this maintenance tree free of forward-port implementation.
+3. Use source commits as provenance; split mixed-feature changes and include their fixes. Exclude OpenSpec pruning, `.mcp.json`, and unrelated local setup from feature PRs.
+4. Commit uncommitted proposal artifacts before `/opsx-apply`. Prefix implementation/proposal commits with the appropriate branch/Jira key.
+5. Record actual tests, dependency versions, remaining limitations and resulting PR/commit links here. Do not mark planned features complete solely because the maintenance implementation exists.
+
+No new tickets or PRs have been created by this planning work. Sequence numbers indicate a suggested delivery order; independent tracks can be developed separately.