(causeway) 01/02: CAUSEWAY-4062: propose semantic member span names

[da...@apache.org]

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

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

commit 41dfa69342c1047f255778bb9ffa54c32887e38c
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Fri Oct 9 16:22:26 2026 +0100

    CAUSEWAY-4062: propose semantic member span names
---
 .../port-semantic-member-names/.openspec.yaml      |  2 +
 .../changes/port-semantic-member-names/design.md   | 51 +++++++++++++++
 .../changes/port-semantic-member-names/proposal.md | 28 +++++++++
 .../specs/semantic-member-span-naming/spec.md      | 73 ++++++++++++++++++++++
 .../changes/port-semantic-member-names/tasks.md    | 16 +++++
 .../planned-changes/otel-forward-port-roadmap.md   |  8 ++-
 6 files changed, 177 insertions(+), 1 deletion(-)

diff --git a/openspec/changes/port-semantic-member-names/.openspec.yaml b/openspec/changes/port-semantic-member-names/.openspec.yaml
new file mode 100644
index 00000000000..81264324b05
--- /dev/null
+++ b/openspec/changes/port-semantic-member-names/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-10-09
diff --git a/openspec/changes/port-semantic-member-names/design.md b/openspec/changes/port-semantic-member-names/design.md
new file mode 100644
index 00000000000..a650be5d2dc
--- /dev/null
+++ b/openspec/changes/port-semantic-member-names/design.md
@@ -0,0 +1,51 @@
+## Context
+
+Main already separates operation and contextual names under CAUSEWAY-4096. MemberExecutorServiceDefault currently emits `causeway.member.action`, `Action <invoked identifier>` and `causeway.member.id`. CAUSEWAY-4058 supplies separate invoked/domain-facing action identity; main's InteractionHead is a mixee/mixin record, unlike maintenance's managed head hierarchy.
+
+Maintenance's three source commits also modify Wicket and install a custom tracing handler for its older Micrometer baseline. Neither should be copied wholesale. Main has both Boot-managed and framework-supplied agent bridge configurations and supports application-provided telemetry beans.
+
+## Goals / Non-Goals
+
+**Goals:** domain-facing action/property/collection names; fixed meter categories; full canonical search attributes; case-preserving bounded display names; unchanged execution and trace ownership; demonstrated behavior in both modes.
+
+**Non-Goals:** Wicket rendering/preparation/prompts; table detail/budgets; HTTP/root semantic naming; changing JPA or property-update naming; application span service; new applib APIs; duration filtering; modifying automatic agent HTTP/JDBC names.
+
+## Decisions
+
+### Preserve main's operation identity
+
+Keep `causeway.member.action` for ordinary actions instead of maintenance's `causeway.action.invocation`. Add `causeway.property.access` and `causeway.collection.access` only for safely resolved mixed-in associations. This avoids an unnecessary ordinary-action metric migration while introducing useful distinctions. Emit one observation around the existing execution path, never both old and new spans.
+
+### Derive semantic metadata without changing invocation identity
+
+Reuse the CAUSEWAY-4058 domain-facing action identifier helper. Keep physical receiver, invoked identifier, rule state, argument execution, command/DTO publishing and transaction behavior unchanged. For an ActionInvocationFacetForMixedInPropertyOrCollection, resolve its association from the owning specification using MixedInMember.hasMixinAction, then use the association's feature identifier and singular/plural kind. Do not infer kind from a method name such as prop or coll. Unresolved a [...]
+
+The full canonical domain identifier uses Identifier.getLogicalIdentityString("#"), including declared action parameter signatures; do not copy maintenance's synthetic `()` suffix. Add exactly the applicable semantic key (`causeway.action.id`, `causeway.property.id` or `causeway.collection.id`). Preserve existing generic `causeway.member.id` metadata for compatibility, documenting that the new semantic keys are authoritative for domain-facing searches. Generic property-update metadata re [...]
+
+### Share core display compaction
+
+Introduce a narrowly scoped core naming formatter for logical member display names. Try the full logical type/member string; above 50 characters retry with a namespace-free logical type, then truncate to 50 characters. Preserve static identifier casing. Display names may collide; full category-specific identity attributes distinguish them. The 50-character display budget ports maintenance's explicit contract and is not a metric-cardinality policy or a new configuration setting. Do not br [...]
+
+### Respect main's handlers and registry ownership
+
+Use standard contextual-name APIs with existing registries. Verify actual uppercase/casing and compaction in exported Boot and agent spans. Main's earlier evidence already showed preserved casing; do not add maintenance's custom tracing handler unless a focused reproduction proves it necessary. Any necessary correction must be limited to these Causeway observations and preserve application/custom registry ownership, scope, parentage, tags and errors; do not replace the shared handler pipeline.
+
+### Keep scope and operator guidance explicit
+
+Root Interaction and HTTP names remain unchanged. Existing inner execution/domain-event/JPA/transaction boundaries remain. Integrate action/mixin association examples and Jaeger searches on full semantic identifiers into the existing M3 how-to and userguide, explaining when only compact names are visible and when association fallback remains action-shaped. Present this as new M3 functionality, without a before/after comparison or migration table. Preserve the existing document flow. Use  [...]
+
+## Risks / Trade-offs
+
+- [Risk] Association lookup selects a different contribution → match the actual implementation action via metamodel linkage; cover multiple contributions and missing lookup.
+- [Risk] Short display names collide or lose namespace/signature → retain full canonical semantic attributes and test collision/overload cases.
+- [Risk] Different tracing integrations alter casing → use exported Boot/agent assertions before considering specialized handling.
+- [Risk] Telemetry consumers depend on old names/categories → describe the resulting operation categories and canonical search attributes within the existing guidance, and avoid duplicate legacy spans.
+- [Risk] Introducing new observations changes failure/transaction behavior → keep the current observe boundary and verify original exception, cleanup and parentage.
+
+## Migration Plan
+
+No Java application API or configuration migration is required. Update trace-name searches to act/prop/coll and use the new semantic identifier keys for exact searches; dashboards counting mixed-in accesses as actions must select the new property/collection categories. No rollback data migration is needed. Refresh target main and ensure CAUSEWAY-4058 is present before implementation; no remote verification or runtime validation was performed during proposal creation.
+
+## Open Questions
+
+None requiring user input. Actual sample examples and export-handler behavior are implementation verification tasks, not assumptions of maintenance compatibility.
diff --git a/openspec/changes/port-semantic-member-names/proposal.md b/openspec/changes/port-semantic-member-names/proposal.md
new file mode 100644
index 00000000000..e6c5a079770
--- /dev/null
+++ b/openspec/changes/port-semantic-member-names/proposal.md
@@ -0,0 +1,28 @@
+## Why
+
+Main's member observations expose generic action names and mixin implementation identities. Operators should see the domain action, property or collection being accessed, with stable metric categories and complete identifiers for searching traces.
+
+## What Changes
+
+- Give action spans contextual names `act <logical-type>#<member>`, using contributed domain identity for mixins while preserving main's `causeway.member.action` operation name.
+- Recognize mixed-in property/collection implementations and instrument them as `causeway.property.access` / `causeway.collection.access`, with `prop` / `coll` contextual names.
+- Add full canonical domain identifiers as `causeway.action.id`, `causeway.property.id` or `causeway.collection.id`, retaining parameter signatures for actions.
+- Port compact naming: retain full logical names when they fit, shorten namespaces when needed, then bound display names to 50 characters. Preserve declared casing and complete identity attributes.
+- **BREAKING (telemetry only):** contextual member names change, and resolved mixed-in association accesses move from action meters to their own categories. Avoid duplicate legacy spans.
+- Extend real Boot/agent trace fixtures and merge examples of the new semantic names and identifier searches into the existing M3 how-to content; no before/after comparison is needed.
+
+## Capabilities
+
+### New Capabilities
+
+- `semantic-member-span-naming`: Domain-facing member display names, category-specific canonical attributes, mixed-in association recognition and safe display compaction.
+
+### Modified Capabilities
+
+None. The existing observation-policy contract remains intact: stable operation categories, static metadata and preserved invocation semantics.
+
+## Impact
+
+Core configuration naming helper; metamodel ActionExecutor association lookup; runtime MemberExecutorServiceDefault observation selection; core and exported-trace tests; M3 how-to and observability guide. No applib API additions, configuration flags, new SDK/exporter or dependency pins.
+
+Sources: maintenance `a2ae5877c99`, `d5ecd49a1f3`, `45e01ff6f42`. Extract only core naming and tests; Wicket preparation/prompts/regions remain roadmap step 5, collection rendering detail step 6 and entry trace naming step 7. Planning baseline: local `c04587a7bcc` on CAUSEWAY-4058; refresh main and select a CAUSEWAY-4062 implementation branch before apply.
diff --git a/openspec/changes/port-semantic-member-names/specs/semantic-member-span-naming/spec.md b/openspec/changes/port-semantic-member-names/specs/semantic-member-span-naming/spec.md
new file mode 100644
index 00000000000..132d915bd58
--- /dev/null
+++ b/openspec/changes/port-semantic-member-names/specs/semantic-member-span-naming/spec.md
@@ -0,0 +1,73 @@
+## ADDED Requirements
+
+### Requirement: Action observations use domain-facing contextual names
+
+Causeway SHALL preserve `causeway.member.action` as the main action operation name and assign contextual names `act <logical-type>#<member>` using domain-facing action identity. It SHALL add `causeway.action.id` containing the complete canonical logical action identifier, including declared parameter signatures. Physical receiver, invoked identifier, rule state and publishing/DTO behavior SHALL remain unchanged.
+
+#### Scenario: Declared action
+- **WHEN** a declared action is observed
+- **THEN** its display name begins with act and identifies the domain type/member, while its operation remains causeway.member.action and its semantic attribute retains the complete signature
+
+#### Scenario: Contributed action
+- **WHEN** a mixin implementation method act contributes Customer#updateName
+- **THEN** the contextual name and causeway.action.id identify Customer#updateName rather than the mixin method, without changing the actual invocation identity
+
+### Requirement: Mixed-in association accesses have distinct semantic categories
+
+Causeway SHALL recognize mixed-in property/collection access by facet and metamodel association linkage. Resolved singular access SHALL use `causeway.property.access`, contextual prefix prop and `causeway.property.id`. Resolved collection access SHALL use `causeway.collection.access`, contextual prefix coll and `causeway.collection.id`. Both SHALL use the full domain-facing association identifier. Only the applicable semantic identifier key SHALL be emitted; association spans SHALL NOT b [...]
+
+#### Scenario: Property access through a mixin
+- **WHEN** a mixin implements a domain property's getter
+- **THEN** one prop span identifies the domain property in its property-access category, not as an action invocation
+
+#### Scenario: Collection access through a mixin
+- **WHEN** a mixin implements a domain collection's getter
+- **THEN** one coll span identifies the domain collection in its collection-access category
+
+#### Scenario: Unresolved association
+- **WHEN** the association facet is present but its domain association cannot be recovered safely
+- **THEN** ordinary action observation remains available without inventing association identity or dropping instrumentation
+
+### Requirement: Compact display names preserve canonical identity and privacy
+
+Contextual names SHALL contain only operation prefixes and static logical model identifiers, preserving declared casing. The formatter SHALL retain a full name when it fits within 50 characters, otherwise retry with a namespace-free type name, then truncate to 50 characters if necessary. The semantic identity attribute SHALL retain its complete identifier independently of compaction. Names and semantic attributes SHALL NOT include instance IDs, bookmarks, titles, argument values, usernam [...]
+
+#### Scenario: Short full name
+- **WHEN** an act, prop or coll name fits the display budget
+- **THEN** its complete logical type/member name and casing are retained
+
+#### Scenario: Long name
+- **WHEN** a name exceeds 50 characters
+- **THEN** its namespace is shortened before truncation, while its full semantic identity attribute is unchanged
+
+#### Scenario: Collision or overload
+- **WHEN** different canonical members have the same compact display name or actions have different declared parameter signatures
+- **THEN** their full semantic attributes distinguish them
+
+#### Scenario: Instance-specific inputs
+- **WHEN** the same logical operation runs for different instances or arguments
+- **THEN** display name and semantic attributes remain identical and contain none of those instance-specific values
+
+### Requirement: Both tracing owners preserve lifecycle and semantic names
+
+Semantic naming SHALL work under supported Boot-managed and agent-managed tracing, preserving casing, parentage, scopes, attributes and errors. It SHALL create no competing registry, SDK/exporter or duplicate observations, and inactive observations SHALL remain inert. Root interaction, HTTP, JDBC and unrelated instrumentation boundaries SHALL remain unchanged by this feature.
+
+#### Scenario: Boot and agent exports
+- **WHEN** representative declared/mixed-in action, property and collection work is collected in each mode
+- **THEN** exported spans show the expected contextual names and canonical attributes with existing ancestry and exactly one member observation per invocation
+
+#### Scenario: Failure followed by success
+- **WHEN** observed member work fails and later work succeeds
+- **THEN** the original failure is preserved and the later execution inherits no stale scope or name
+
+#### Scenario: Observation disabled
+- **WHEN** the observation profile is inactive
+- **THEN** invocation behavior is unchanged and no Causeway semantic spans are emitted
+
+### Requirement: Operators can inspect semantic member spans
+
+The M3 how-to and observability guide SHALL integrate the new capability into their existing content, explaining operation versus display identity, action/property/collection categories, canonical attributes and compact-name collisions. They SHALL present the capability as new M3 functionality without before/after comparisons or migration tables. They SHALL identify the Wicket/root-naming features that remain out of scope and SHALL NOT require new naming configuration flags.
+
+#### Scenario: Reader inspects semantic spans
+- **WHEN** a reader follows the updated guide
+- **THEN** they can recognize representative act/prop/coll spans and search by full semantic identifier rather than relying on potentially shortened display names
diff --git a/openspec/changes/port-semantic-member-names/tasks.md b/openspec/changes/port-semantic-member-names/tasks.md
new file mode 100644
index 00000000000..bb1282c2198
--- /dev/null
+++ b/openspec/changes/port-semantic-member-names/tasks.md
@@ -0,0 +1,16 @@
+## 1. Core semantic metadata
+
+- [ ] 1.1 Add the core member-name formatter and tests for casing, full-name retention, namespace shortening, truncation and canonical-name collisions; omit Wicket-only helpers.
+- [ ] 1.2 Resolve mixed-in associations from invocation facet and actual metamodel linkage in ActionExecutor; cover property, collection, multiple contributions and missing lookup.
+- [ ] 1.3 Select semantic observation category/context and full category-specific identifier in MemberExecutorServiceDefault, reusing domain action identity while retaining main action operation and existing generic metadata.
+
+## 2. Behavior and export validation
+
+- [ ] 2.1 Add runtime tests for ordinary/mixed-in actions and associations, complete action parameter signatures, fallback, unchanged invocation/DTO behavior and error cleanup.
+- [ ] 2.2 Extend real exported Boot/agent fixtures for act/prop/coll names, exact identifier attributes, uppercase and long/colliding names, one span per invocation and HTTP/framework/JDBC ancestry.
+- [ ] 2.3 Verify observation inactive, missing exporter, failure-followed-by-success and custom registry/tracer behavior; confirm existing handlers preserve naming before considering any scoped correction.
+
+## 3. Operator guidance and delivery checks
+
+- [ ] 3.1 Merge the new M3 capability into the existing otel-howto and observability guide with verified examples, full-identifier Jaeger searches and operation/context distinctions; omit before/after comparisons and migration tables, retaining the Boot-first then agent structure.
+- [ ] 3.2 Run focused naming/metamodel/runtime checks, relevant interact regressions, exported-trace compatibility suite and documentation rendering; record commands, baseline versions, results and remaining limits in validation.md.
diff --git a/openspec/planned-changes/otel-forward-port-roadmap.md b/openspec/planned-changes/otel-forward-port-roadmap.md
index 5ba7e2995d0..541f3b402b8 100644
--- a/openspec/planned-changes/otel-forward-port-roadmap.md
+++ b/openspec/planned-changes/otel-forward-port-roadmap.md
@@ -14,7 +14,7 @@ Main already contains CAUSEWAY-3975, including instrumentation absent from the s
 | 1b | CAUSEWAY-4096: standardize observation names, metadata and duration-filtering policy | **Archived (2026-10-05):** [standardize observation policy](../changes/archive/2026-10-05-standardize-observation-policy/proposal.md) on branch `CAUSEWAY-4096`. Follow-up to 3975: 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. | Main  [...]
 | 2 | CAUSEWAY-4068 (3975/4068 provenance): classification and correlation | **Archived (2026-10-07):** [classify and correlate observations](../changes/archive/2026-10-07-classify-and-correlate-observations/proposal.md). Foreground/background classification, root interaction ID, fixed execution-mode attribute key. Depends on foundation; adapt to main's interaction layers. | `024bd33128d`, `0325232a3c7`, `3083a51eabd` |
 | 3 | CAUSEWAY-4058: current action context | **Archived (2026-10-09):** [port current action context](../changes/archive/2026-10-09-port-current-action-context/proposal.md). 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` |
+| 4 | CAUSEWAY-4062: semantic member names | **Proposed:** [port semantic member names](../changes/port-semantic-member-names/proposal.md). 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` |
@@ -134,3 +134,9 @@ Planning baseline: `41d8db75a06` on CAUSEWAY-4068-v4. Refresh main and select a
 Current action context implemented on CAUSEWAY-4058 after planning commit `9a250065cfa`. All nine tasks completed; [validation evidence](../changes/archive/2026-10-09-port-current-action-context/validation.md) records 29 focused tests and 77 executed interact regressions (2 existing disabled tests), documentation rendering and main-specific mixin identity adaptation. Implementation is recorded in the checkpoint commit containing this update; the change was subsequently rebased and archiv [...]
 
 Current action context archived on 2026-10-09 after rebase onto main `ce0c8352dee`: rebased planning `5c43e44b085`, implementation `be228adf4ac`. Fresh archive checks passed 29 focused tests and 77 interact regressions (2 existing disabled tests), documentation rendering and strict validation. Requirements are synced to the main specs.
+
+## Semantic member naming proposal (2026-10-09)
+
+Step 4 is promoted into [port-semantic-member-names](../changes/port-semantic-member-names/proposal.md), with design, requirements and implementation tasks. This extracts core naming from `a2ae5877c99`, `d5ecd49a1f3` and `45e01ff6f42`: domain-facing act/prop/coll displays, distinct mixed-in association categories, full canonical semantic attributes and bounded case-preserving display compaction. Main's existing `causeway.member.action` operation is preserved for ordinary actions. Wicket  [...]
+
+Planning baseline is local `c04587a7bcc` on CAUSEWAY-4058, following current-action context archival. Refresh main and select a CAUSEWAY-4062 implementation branch before apply. The M3 how-to and observability guide are implementation tasks; no runtime validation or implementation is claimed by this proposal.