You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@causeway.apache.org by da...@apache.org on 2026/09/24 16:22:11 UTC

(causeway) 17/41: CAUSEWAY-4063: adds semantic trace display names proposal

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

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

commit c08bb4d611354f15121cafa04ebfffa517eeaa30
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Thu Sep 24 07:28:32 2026 +0100

    CAUSEWAY-4063: adds semantic trace display names proposal
---
 .../.openspec.yaml                                 |   2 +
 .../add-semantic-trace-display-names/design.md     | 127 ++++++++++++++++++
 .../add-semantic-trace-display-names/proposal.md   |  32 +++++
 .../specs/semantic-span-display-naming/spec.md     |  16 +++
 .../specs/semantic-trace-display-naming/spec.md    | 148 +++++++++++++++++++++
 .../add-semantic-trace-display-names/tasks.md      |  43 ++++++
 6 files changed, 368 insertions(+)

diff --git a/openspec/changes/add-semantic-trace-display-names/.openspec.yaml b/openspec/changes/add-semantic-trace-display-names/.openspec.yaml
new file mode 100644
index 00000000000..265da3d94ed
--- /dev/null
+++ b/openspec/changes/add-semantic-trace-display-names/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-23
diff --git a/openspec/changes/add-semantic-trace-display-names/design.md b/openspec/changes/add-semantic-trace-display-names/design.md
new file mode 100644
index 00000000000..e7e9f9cf7cb
--- /dev/null
+++ b/openspec/changes/add-semantic-trace-display-names/design.md
@@ -0,0 +1,127 @@
+## Context
+
+OpenTelemetry has no trace-name field distinct from its spans.
+Jaeger and comparable backends conventionally label a trace using its root span's operation name.
+
+For foreground Causeway requests, the OpenTelemetry Java agent creates and owns the root HTTP server span before Causeway's servlet filter runs.
+Causeway currently classifies that span with `causeway.execution.mode=foreground`, then creates `causeway.root.interaction` and more specific action, prompt, preparation, and render descendants.
+Those descendants now have useful names such as `act demo.Customer#update`, but the trace list still shows a transport name such as `GET /wicket/...`.
+
+The existing `CausewayForegroundTraceFilter` is the earliest and latest Causeway-controlled boundary inside the agent-owned server span.
+It can capture `Span.current()` before delegating and update that same span after downstream Causeway instrumentation has nominated the request's primary semantic outcome.
+
+The supported baseline is OpenTelemetry Java agent 1.31.0.
+The agent must continue to own span creation, context propagation, HTTP and JDBC instrumentation, sampling, and OTLP export.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Give eligible foreground entry spans bounded domain-facing operation names that telemetry backends can use as trace display names.
+- Select one name deterministically from action invocation, action prompt, and entity view evidence collected during the request.
+- Preserve standard HTTP attributes, Causeway execution-mode classification, parentage, sampling, and export.
+- Preserve full canonical Causeway identifiers as attributes when display names are compacted or truncated.
+- Keep all state request-local, transient, and safely cleaned up on successful and failed requests.
+- Remain harmless without the Java agent or with a non-recording current span.
+- Prove final-name behavior against agent 1.31.0 before treating in-process renaming as supported.
+
+**Non-Goals:**
+
+- Introduce a fictional OpenTelemetry trace-name field.
+- Replace the agent-owned HTTP root with a Causeway-created root span.
+- Rename `causeway.root.interaction` or any existing Causeway child observation for the purpose of trace-list presentation.
+- Rename JDBC, outbound HTTP, background Quartz, or unrelated automatic spans.
+- Remove or alter standard HTTP method, route, target, status, or error attributes.
+- Expose semantic trace naming as an application-facing API.
+- Include object-instance identifiers, values, arguments, titles, bookmarks, users, tenants, localized labels, or arbitrary URL data.
+- Guarantee identical trace-list presentation in every telemetry backend.
+
+## Decisions
+
+### Rename the agent-owned foreground entry span in place
+
+`CausewayForegroundTraceFilter` will capture `Span.current()` before invoking the filter chain and will call `Span.updateName(...)` in its `finally` path after downstream processing has completed.
+The update occurs while the captured span is still active and before the Java agent ends it.
+
+This is preferred to adding another Causeway root because an additional span would remain beneath the HTTP span and would not change the backend's trace-list label.
+It is preferred to an application-owned span processor or exporter because those would violate the single telemetry-owner architecture.
+
+The implementation will check that the captured span is recording before installing active nomination state or mutating it.
+No-agent and non-recording cases retain current behavior.
+
+### Coordinate nominations through an internal request scope
+
+Add an internal semantic trace-name coordinator shared by core webapp, runtime action instrumentation, and Wicket instrumentation.
+The filter opens a request scope containing the captured entry span and a selected candidate, and closes that scope in `finally` even when downstream processing throws.
+
+The coordinator will use a stack-safe thread-local scope because runtime action instrumentation must not depend on servlet APIs and Wicket request attributes are not available at every nomination point.
+Nested filter dispatches will restore the previous scope rather than overwriting it.
+Asynchronous servlet continuation and cross-thread propagation are out of scope.
+
+Only framework-internal callers can nominate candidates.
+No applib service or arbitrary string-based application hook will be introduced.
+
+### Use explicit candidate kinds and first-wins ties
+
+Candidates have fixed priorities:
+
+1. `ACTION` produces `act <logical-member-identifier>`.
+2. `PROMPT` produces `prompt <logical-member-identifier>`.
+3. `VIEW` produces `view <logical-type-name>`.
+
+A higher-priority nomination replaces a lower-priority selection.
+The first nomination at an equal priority remains selected, making repeated nominations deterministic by request execution order and preventing later rendering from overwriting the primary operation.
+
+Action instrumentation will nominate only the ordinary domain-facing action corresponding to the request's top-level interaction command.
+It will not nominate mixed-in property or collection access, framework helper invocations, or later nested wrapper invocations as the request's primary action.
+Wicket prompt instrumentation will nominate the prompted action, and entity-page instrumentation will nominate the viewed logical type.
+An action therefore wins over prompt and view candidates produced while rendering the response to that action.
+
+This explicit selector is preferred to last-writer-wins behavior because page rendering normally occurs after invocation and would otherwise hide the action that caused the response.
+
+### Reuse bounded semantic naming and canonical attributes
+
+Candidate display names will use the existing case-preserving `CausewayObservationNaming` policy and its 50-character maximum.
+Action and prompt candidates will use the full logical member identifier, then retry without the logical type namespace, then truncate if necessary.
+View candidates will use the full logical type, then its namespace-free form, then truncate if necessary.
+
+The selected entry span will receive bounded `causeway.trace.name` equal to the selected display name.
+Action and prompt candidates will also attach the complete canonical `causeway.action.id`, and view candidates will attach the complete canonical `causeway.object.type`.
+These values describe static application structure and remain authoritative if the display name is compacted or truncated.
+
+Existing standard HTTP attributes and `causeway.execution.mode=foreground` remain untouched.
+
+### Gate support on an agent-backed exported-span test
+
+The tracing compatibility regression will exercise view-only, prompt-only, action-invocation, priority, unchanged-route, and failed-request cases in child JVMs with agent 1.31.0 attached.
+The collector output must prove that the exported HTTP server span retains the Causeway-selected final name after the filter returns.
+It must also prove that HTTP attributes, trace identity, parentage, and execution-mode classification are unchanged.
+
+If the agent overwrites the name after the filter returns, the in-process rename will not be shipped as effective behavior.
+Causeway will still emit bounded `causeway.trace.name` and canonical attributes, and the operations guide will document a collector transform or supported Java-agent extension as the deployment-specific fallback.
+This fallback is less portable, so the supported in-process path remains contingent on the evidence gate.
+
+## Risks / Trade-offs
+
+- [Risk] The Java agent may update the server span name after Causeway's filter returns. → Make the exported final name an agent-backed compatibility gate and retain attribute-plus-collector transformation as the fallback.
+- [Risk] Renaming changes backend operation-name grouping and can affect dashboards or alerts. → Document the behavior as operationally breaking and direct route-based monitoring to standard HTTP route attributes.
+- [Risk] A request can produce several legitimate semantic operations. → Use explicit priority and first-wins tie handling, and test combined action, prompt, and page-render flows.
+- [Risk] A thread-local scope can leak across reused servlet threads. → Use an `AutoCloseable` stack scope and unconditional `finally` cleanup, with failure and nested-dispatch tests.
+- [Risk] Internal action activity could incorrectly label a page-view request as an action. → Restrict action nomination to the top-level command identity and exclude mixed-in associations and framework or nested helper invocations.
+- [Risk] Ajax requests can have no unambiguous page outcome. → Leave the original route name unless an actual selected action or unambiguous prompt nomination exists.
+- [Trade-off] Semantic names reduce immediate route visibility in the operation-name column. → Preserve every standard HTTP attribute for filtering and diagnosis.
+- [Trade-off] Background traces retain different root naming behavior. → Keep background naming explicitly out of scope rather than presenting a partial abstraction as universal.
+
+## Migration Plan
+
+Deploy the change first in an environment where trace operation-name dashboards and alerts have been inventoried.
+Update transport-oriented grouping to use standard HTTP route and method attributes where semantic entry names would otherwise break it.
+Verify representative view, prompt, action, Ajax, and unmatched requests against the configured backend before broad rollout.
+
+Rollback requires only deployment of the previous framework version or disabling the semantic rename integration if an implementation guard is provided.
+No persisted application data or telemetry backend schema migration is required.
+
+## Open Questions
+
+- The evidence gate must confirm whether agent 1.31.0 preserves `Span.updateName(...)` after the servlet filter returns; this determines whether in-process renaming or collector-side transformation is the supported deployment path.
+- The implementation spike must confirm the most reliable test for matching an action invocation to the current top-level command across declared and mixed-in actions without nominating nested wrapper work.
diff --git a/openspec/changes/add-semantic-trace-display-names/proposal.md b/openspec/changes/add-semantic-trace-display-names/proposal.md
new file mode 100644
index 00000000000..5f02d2ce8d2
--- /dev/null
+++ b/openspec/changes/add-semantic-trace-display-names/proposal.md
@@ -0,0 +1,32 @@
+## Why
+
+Foreground traces are rooted in Java-agent-owned HTTP server spans, so Jaeger and similar backends list them under transport-facing names such as `GET /wicket/...` even when Causeway child spans already expose the domain operation.
+Giving the foreground entry span a bounded semantic operation name makes trace lists searchable and understandable without inventing a trace-level name or replacing agent ownership.
+
+## What Changes
+
+- Treat the Java-agent-created foreground HTTP server span's operation name as the portable approximation of a trace display name.
+- Capture that entry span and request-local naming state in `CausewayForegroundTraceFilter` while the request is active.
+- Allow trusted Causeway action-invocation, action-prompt, and entity-page instrumentation to nominate bounded semantic names without exposing unrestricted trace naming as an application API.
+- Select candidates deterministically with priority `act` over `prompt` over `view`, and retain the first deterministic candidate at equal priority.
+- Rename the captured entry span before the foreground filter returns, while preserving standard HTTP attributes, execution-mode classification, trace parentage, sampling, and export.
+- Leave the agent-provided HTTP operation name unchanged when no supported candidate exists, no Java agent is attached, or the current entry span is non-recording.
+- Reuse the existing case-preserving 50-character naming and canonical-identifier policy without adding instance-specific data.
+- Verify against OpenTelemetry Java agent 1.31.0 that the agent does not overwrite the selected name after the filter returns, with a bounded `causeway.trace.name` attribute and collector-side rename retained only as a documented fallback if that evidence gate fails.
+- **BREAKING**: Foreground HTTP server span operation names, and therefore backend grouping based on those names, can change from transport routes to semantic `act`, `prompt`, or `view` names.
+
+## Capabilities
+
+### New Capabilities
+
+- `semantic-trace-display-naming`: Defines request-local candidate nomination, deterministic selection, bounded entry-span renaming, safe fallback behavior, and preservation of transport telemetry.
+
+### Modified Capabilities
+
+- `semantic-span-display-naming`: Narrows the existing guarantee that automatic HTTP span names remain unchanged so that the selected foreground entry span may be renamed by the dedicated semantic trace-name mechanism while other automatic span naming remains unchanged.
+
+## Impact
+
+The change affects core webapp foreground filtering, internal observation coordination, action invocation instrumentation, Wicket page and prompt instrumentation, contextual naming utilities, tracing compatibility fixtures, and operational documentation.
+Dashboards and alerts that group foreground server spans by operation name may need to use standard HTTP route attributes or the new semantic names instead.
+The OpenTelemetry Java agent remains the owner of span creation, context propagation, HTTP and JDBC instrumentation, sampling, and export, and no application-owned SDK, processor, sampler, or exporter is introduced.
diff --git a/openspec/changes/add-semantic-trace-display-names/specs/semantic-span-display-naming/spec.md b/openspec/changes/add-semantic-trace-display-names/specs/semantic-span-display-naming/spec.md
new file mode 100644
index 00000000000..4747627d686
--- /dev/null
+++ b/openspec/changes/add-semantic-trace-display-names/specs/semantic-span-display-naming/spec.md
@@ -0,0 +1,16 @@
+## MODIFIED Requirements
+
+### Requirement: Case-preserving Causeway trace export
+Causeway SHALL export its semantic observation contextual names without Micrometer's lower-hyphen conversion.
+The specialized observation handling SHALL apply only to Causeway's dedicated observation registry and SHALL preserve existing tracing lifecycle, parentage, tags, errors, and scope behavior.
+The separate semantic trace-display-name mechanism SHALL restrict automatic-span renaming to the selected Java-agent-created foreground HTTP entry span; naming of other automatic Java-agent spans SHALL remain unchanged.
+
+#### Scenario: Logical identifier contains uppercase characters
+- **WHEN** a Causeway contextual name contains a logical identifier such as `isisExtSecMan.ApplicationUser`
+- **THEN** the exported span name retains that exact identifier casing
+- **AND** automatic Java-agent JDBC, outbound HTTP, and non-selected server span naming remains unchanged
+
+#### Scenario: Foreground entry span receives a semantic trace name
+- **WHEN** the dedicated semantic trace-display-name mechanism selects a bounded name for a Java-agent-created foreground HTTP entry span
+- **THEN** Causeway updates that entry span to the selected case-preserving name
+- **AND** this exception does not change naming behavior for other automatic Java-agent spans
diff --git a/openspec/changes/add-semantic-trace-display-names/specs/semantic-trace-display-naming/spec.md b/openspec/changes/add-semantic-trace-display-names/specs/semantic-trace-display-naming/spec.md
new file mode 100644
index 00000000000..272694e7b0a
--- /dev/null
+++ b/openspec/changes/add-semantic-trace-display-names/specs/semantic-trace-display-naming/spec.md
@@ -0,0 +1,148 @@
+## ADDED Requirements
+
+### Requirement: Foreground entry span as semantic trace display name
+Causeway SHALL use the Java-agent-created foreground HTTP server span's operation name as the portable approximation of a trace display name when a supported semantic candidate is selected.
+Causeway SHALL rename that existing span rather than create a replacement root span.
+
+#### Scenario: Supported semantic candidate is selected
+- **WHEN** a foreground request produces a selected action, prompt, or entity-view candidate
+- **THEN** the exported HTTP server span uses the candidate's bounded semantic display name
+- **AND** the trace identity and root-span identity remain those created by the Java agent
+
+#### Scenario: Telemetry backend lists traces by root operation
+- **WHEN** a backend uses the root span operation name as the trace-list label
+- **THEN** an eligible foreground trace is listed under its selected semantic name
+- **AND** Causeway does not claim that OpenTelemetry provides a separate trace-name field
+
+### Requirement: Request-local semantic candidate lifecycle
+Causeway SHALL capture the current foreground entry span and install transient nomination state before delegating through the foreground filter.
+Causeway SHALL select and apply the candidate after downstream request processing and SHALL clean up nomination state whether processing succeeds or fails.
+
+#### Scenario: Request completes successfully
+- **WHEN** downstream request processing nominates one or more candidates and returns normally
+- **THEN** Causeway applies the selected candidate before the foreground filter returns
+- **AND** removes all request-local nomination state
+
+#### Scenario: Request processing fails
+- **WHEN** downstream request processing nominates a candidate and then throws
+- **THEN** Causeway applies the selected candidate while preserving the original failure
+- **AND** removes all request-local nomination state
+
+#### Scenario: Nested filter scope occurs
+- **WHEN** a nested dispatch opens another semantic naming scope on the same thread
+- **THEN** the nested scope does not overwrite the enclosing scope's state
+- **AND** closing the nested scope restores the enclosing scope
+
+### Requirement: Deterministic candidate selection
+Causeway SHALL select candidates in descending priority order of action invocation, action prompt, and entity view.
+A higher-priority candidate SHALL replace a lower-priority candidate, and the first candidate at an equal priority SHALL remain selected.
+
+#### Scenario: Action and response page are both observed
+- **WHEN** a request invokes a domain action and subsequently renders an entity page or action prompt
+- **THEN** the action candidate wins
+- **AND** later page or prompt nominations do not replace it
+
+#### Scenario: Prompt and entity view are both observed
+- **WHEN** a request presents an action prompt without invoking an action and also renders an entity page
+- **THEN** the prompt candidate wins over the view candidate
+
+#### Scenario: Repeated equal-priority nominations occur
+- **WHEN** more than one candidate of the selected priority is nominated during a request
+- **THEN** the first such candidate remains selected
+- **AND** no runtime value is added to distinguish the candidates
+
+### Requirement: Eligible semantic candidates
+Causeway SHALL nominate action candidates only for an ordinary domain-facing action that represents the request's top-level interaction command.
+Causeway SHALL nominate prompt candidates from an unambiguous rendered action prompt and view candidates from an entity page's logical object type.
+Causeway MUST NOT nominate mixed-in association access, nested wrapper work, framework helper invocations, or ambiguous Ajax rendering as the request's primary action or view.
+
+#### Scenario: Top-level action is invoked
+- **WHEN** the request executes a top-level declared or mixed-in domain action
+- **THEN** Causeway nominates `act <logical-member-identifier>` using the domain-facing action identity
+
+#### Scenario: Calculated association is evaluated
+- **WHEN** page preparation evaluates a property or collection implemented by a mixin action
+- **THEN** that evaluation does not nominate an action trace name
+
+#### Scenario: Top-level action invokes nested action
+- **WHEN** the request's domain action invokes another action through wrapper machinery
+- **THEN** the nested invocation does not replace or compete with the top-level action candidate
+
+#### Scenario: Entity action prompt is primary outcome
+- **WHEN** a request renders an unambiguous prompt without invoking the action
+- **THEN** Causeway nominates `prompt <logical-member-identifier>`
+
+#### Scenario: Entity page is viewed
+- **WHEN** an entity page request has no action or prompt candidate
+- **THEN** Causeway nominates `view <logical-type-name>`
+
+#### Scenario: Ajax render has no semantic primary outcome
+- **WHEN** an Ajax request renders regions without an invoked action or unambiguous prompt
+- **THEN** Causeway does not nominate an entity-view candidate solely from those rendered regions
+
+### Requirement: Bounded semantic names and canonical identity
+Causeway SHALL preserve declared logical-identifier casing and limit selected semantic names to 50 characters using the existing full-name, namespace-free, and truncation policy.
+Causeway SHALL attach the selected bounded name as `causeway.trace.name` and SHALL retain the applicable complete canonical identity as an entry-span attribute.
+
+#### Scenario: Action candidate fits in full
+- **WHEN** `act <logical-member-identifier>` does not exceed 50 characters
+- **THEN** Causeway preserves the complete logical member identifier in the selected name
+- **AND** attaches the complete canonical identifier as `causeway.action.id`
+
+#### Scenario: Action or prompt candidate exceeds the limit
+- **WHEN** an action or prompt name using the full logical identifier exceeds 50 characters
+- **THEN** Causeway first retries without the logical type namespace and then truncates only if still necessary
+- **AND** preserves the complete identity in `causeway.action.id`
+
+#### Scenario: View candidate exceeds the limit
+- **WHEN** `view <logical-type-name>` exceeds 50 characters
+- **THEN** Causeway first retries with the namespace-free logical type and then truncates only if still necessary
+- **AND** preserves the complete logical type in `causeway.object.type`
+
+#### Scenario: Instance-specific context exists
+- **WHEN** the selected operation concerns a particular object, user, tenant, or argument set
+- **THEN** the entry-span name and Causeway attributes contain no object identity, title, bookmark, value, argument, user identity, tenancy identity, localized label, or arbitrary URL data
+
+### Requirement: Transport telemetry preservation
+Renaming a foreground entry span SHALL preserve its standard HTTP method, route, target, status, error, and other transport attributes.
+It SHALL also preserve `causeway.execution.mode=foreground`, trace parentage, sampling decisions, and export through the Java agent.
+
+#### Scenario: Entry span is renamed
+- **WHEN** Causeway changes an HTTP server span from a transport-facing operation name to a semantic name
+- **THEN** all previously recorded standard HTTP and Causeway execution-mode attributes remain available
+- **AND** descendants remain in the same trace under the same entry span
+
+#### Scenario: Transport-oriented monitoring is required
+- **WHEN** operators need to group renamed requests by route or method
+- **THEN** the standard HTTP route and method attributes remain authoritative for that grouping
+
+### Requirement: Safe unchanged behavior
+Causeway SHALL leave the agent-provided entry-span operation name unchanged when no supported candidate is selected, no Java agent supplies a recording current span, or the request is outside the supported foreground path.
+Causeway SHALL NOT require an application-owned telemetry SDK, sampler, processor, exporter, or registry.
+
+#### Scenario: No candidate is nominated
+- **WHEN** a foreground request completes without an eligible action, prompt, or view candidate
+- **THEN** the HTTP entry span retains its agent-provided operation name
+
+#### Scenario: Current span is non-recording
+- **WHEN** the foreground filter observes no recording entry span
+- **THEN** candidate coordination and renaming are harmless no-ops
+- **AND** request processing remains unchanged
+
+#### Scenario: Background execution occurs
+- **WHEN** a Quartz or other background entry span is classified as background
+- **THEN** this capability does not rename that span
+
+### Requirement: Supported-agent evidence gate
+Causeway SHALL verify with an exported-span compatibility test that OpenTelemetry Java agent 1.31.0 preserves the final semantic name after the foreground filter returns.
+The compatibility test SHALL also verify unchanged HTTP attributes, execution-mode classification, trace identity, and parentage.
+
+#### Scenario: Agent preserves the filter update
+- **WHEN** the agent-backed compatibility fixture exports a semantically renamed foreground entry span
+- **THEN** the exported operation name equals the selected Causeway name
+- **AND** in-process entry-span renaming is supported for the validated baseline
+
+#### Scenario: Agent overwrites the filter update
+- **WHEN** the exported operation name does not equal the name applied by the foreground filter
+- **THEN** Causeway does not claim in-process semantic renaming as supported
+- **AND** emits bounded `causeway.trace.name` and canonical identity attributes for a documented collector transform or supported agent extension
diff --git a/openspec/changes/add-semantic-trace-display-names/tasks.md b/openspec/changes/add-semantic-trace-display-names/tasks.md
new file mode 100644
index 00000000000..c42c7d281f0
--- /dev/null
+++ b/openspec/changes/add-semantic-trace-display-names/tasks.md
@@ -0,0 +1,43 @@
+## 1. Agent Compatibility Evidence Gate
+
+- [ ] 1.1 Extend the agent-backed tracing fixture with a controlled foreground-filter `Span.updateName(...)` experiment and verify the exported final server-span name under OpenTelemetry Java agent 1.31.0.
+- [ ] 1.2 Verify in the same experiment that HTTP method, route, target, status, execution-mode classification, trace identity, span identity, and child parentage remain unchanged.
+- [ ] 1.3 Record the evidence-gate result; proceed with in-process renaming if the update survives, otherwise constrain implementation to bounded semantic attributes and document the collector-transform or supported-agent-extension fallback.
+
+## 2. Request-Local Selection Infrastructure
+
+- [ ] 2.1 Add internal candidate kinds for action, prompt, and view with explicit priorities and canonical identifier metadata.
+- [ ] 2.2 Implement a stack-safe request-local coordinator that opens and closes nomination scopes, replaces lower-priority candidates, and retains the first equal-priority candidate.
+- [ ] 2.3 Add contextual-name builders for `act`, `prompt`, and `view` candidates using the existing case-preserving 50-character full-name, namespace-free, and truncation policy.
+- [ ] 2.4 Add unit tests for candidate priority, equal-priority determinism, nested-scope restoration, failure cleanup, bounded names, casing, and canonical metadata.
+
+## 3. Foreground Entry-Span Integration
+
+- [ ] 3.1 Update `CausewayForegroundTraceFilter` to capture the current recording span, classify it as foreground, open nomination state before delegation, and finalize and clean up state in `finally`.
+- [ ] 3.2 Apply the selected name and bounded `causeway.trace.name` to the captured entry span, together with complete `causeway.action.id` or `causeway.object.type` metadata as applicable.
+- [ ] 3.3 Preserve downstream exceptions unchanged and make no-agent, non-recording-span, and no-candidate paths harmless no-ops that retain the agent-provided operation name.
+- [ ] 3.4 Extend core webapp tests for successful requests, failed requests, no candidate, non-recording spans, nested dispatch scopes, mutation timing, and unchanged classification behavior.
+
+## 4. Trusted Candidate Nomination
+
+- [ ] 4.1 Nominate action candidates from runtime action instrumentation only when the domain-facing action matches the current top-level interaction command.
+- [ ] 4.2 Exclude mixed-in property and collection access, framework helper invocations, pass-through work, and nested wrapper actions from primary action nomination.
+- [ ] 4.3 Nominate prompt candidates from the enclosing Wicket action-prompt instrumentation using the complete domain-facing action identifier.
+- [ ] 4.4 Nominate view candidates from Wicket entity-page instrumentation using the complete logical object type, while excluding ambiguous Ajax region rendering.
+- [ ] 4.5 Add focused runtime and Wicket tests for declared and mixed-in top-level actions, calculated associations, nested wrapper invocations, prompt-only requests, view-only requests, Ajax requests, and combined action-response rendering.
+
+## 5. End-to-End Regression Coverage
+
+- [ ] 5.1 Extend the tracing compatibility fixture and collector assertions for exported `act`, `prompt`, and `view` entry-span names and their canonical Causeway attributes.
+- [ ] 5.2 Add compatibility scenarios proving action-over-prompt-over-view priority, first-wins ties, and preservation of the original route name for unsupported requests.
+- [ ] 5.3 Assert that renamed entry spans retain standard HTTP attributes, `causeway.execution.mode=foreground`, existing trace parentage, and JDBC descendants.
+- [ ] 5.4 Verify failed requests still export the selected name and error telemetry while preserving application failure behavior.
+- [ ] 5.5 Verify startup and request execution without the Java agent remain safe and do not create an application-owned telemetry SDK, sampler, processor, registry, or exporter.
+
+## 6. Operations Documentation and Verification
+
+- [ ] 6.1 Update the tracing operations guide with semantic trace-list examples, candidate priority, eligibility rules, backend limitations, and unchanged-route fallback behavior.
+- [ ] 6.2 Document the operationally breaking change to server operation-name grouping and advise route-oriented dashboards and alerts to use standard HTTP route and method attributes.
+- [ ] 6.3 Document the validated agent baseline and, if required by the evidence gate, the bounded `causeway.trace.name` collector-transform or supported-agent-extension fallback.
+- [ ] 6.4 Run focused core config, core runtime services, core webapp, Wicket, and tracing compatibility tests on the supported Java and Maven toolchain.
+- [ ] 6.5 Run strict OpenSpec validation and confirm every semantic trace-display-name scenario has automated coverage or an explicit operational verification step.