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:21:57 UTC
(causeway) 03/41: CAUSEWAY-4061: proposes mixin introspection prefiltering
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 d6516ae73057dc95c01f9b1c53a6faa6ad6b7810
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Wed Sep 23 14:32:29 2026 +0100
CAUSEWAY-4061: proposes mixin introspection prefiltering
---
.../.openspec.yaml | 2 +
.../design.md | 86 ++++++++++++++++++++++
.../proposal.md | 29 ++++++++
.../specs/mixin-introspection-prefiltering/spec.md | 68 +++++++++++++++++
.../tasks.md | 26 +++++++
5 files changed, 211 insertions(+)
diff --git a/openspec/changes/prefilter-mixins-before-full-introspection/.openspec.yaml b/openspec/changes/prefilter-mixins-before-full-introspection/.openspec.yaml
new file mode 100644
index 00000000000..265da3d94ed
--- /dev/null
+++ b/openspec/changes/prefilter-mixins-before-full-introspection/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-23
diff --git a/openspec/changes/prefilter-mixins-before-full-introspection/design.md b/openspec/changes/prefilter-mixins-before-full-introspection/design.md
new file mode 100644
index 00000000000..8f197a5ef96
--- /dev/null
+++ b/openspec/changes/prefilter-mixins-before-full-introspection/design.md
@@ -0,0 +1,86 @@
+## Context
+
+The diagnostics introduced by `diagnose-metamodel-introspection-recursion` captured the complete chain from a production failure.
+The chain had 395 entries and 395 distinct Java types, proving that the failure was not a cycle but an excessively deep depth-first traversal.
+Of those entries, 201 were loaded by `createMixedInAssociation`, 55 by `createMixedInAction`, and 138 by action element-type resolution.
+
+Almost every candidate was already `TYPE_INTROSPECTED` and was being advanced to `FULLY_INTROSPECTED`.
+Both mixed-in discovery paths currently request full introspection before reading `MixinFacet` and calling `isMixinFor`, even though mixin identity, target type, and main method name are type-level metadata established by `introspectTypeHierarchy`.
+Consequently, an inapplicable candidate can run member postprocessors, resolve action element types, synthesize navigation actions, and recursively scan further mixins before the original caller discards it.
+
+This branch is being decommissioned, so the correction should be narrowly scoped and retain existing member behavior.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Decide mixin applicability before requesting full member introspection.
+- Avoid full introspection of candidates that do not apply to the current target.
+- Apply identical prefiltering semantics to mixed-in actions and mixed-in associations.
+- Preserve contribution behavior, ordering, validation, and deterministic traversal for applicable mixins.
+- Demonstrate a substantial reduction in nested full-introspection requests on a production-shaped fixture.
+
+**Non-Goals:**
+
+- Replace recursive metamodel construction with a general iterative work queue.
+- Guarantee a fixed maximum depth when an application genuinely has a long chain of applicable mixins and element types.
+- Change how `MixinFacet` determines applicability.
+- Change navigation-action synthesis, action element-type derivation, or the public programming model.
+- Remove the diagnostics added by the preceding change.
+
+## Decisions
+
+### Use a two-stage load for every candidate mixin
+
+Each candidate will first be loaded with `IntrospectionState.TYPE_INTROSPECTED`.
+The discovery path will read `MixinFacet`, reject missing or self specifications, and evaluate `isMixinFor` against the target specification's corresponding class.
+Only an applicable candidate will then be loaded or advanced to `IntrospectionState.FULLY_INTROSPECTED` before its declared actions are streamed and converted into mixed-in members.
+
+This directly removes the unnecessary transition identified by the production chain while using the existing specification cache and state machine.
+Checking applicability from registry metadata alone was rejected because `MixinFacet` remains the authoritative implementation of mixin semantics.
+Leaving one discovery path unchanged was rejected because both actions and associations appeared prominently in the captured chain.
+
+### Share the applicability prefilter between action and association discovery
+
+A small internal helper in `ObjectSpecificationAbstract` will perform the common type-stage loading and applicability checks and return the accepted mixin specification together with the `MixinFacet`, or an empty result.
+Action-specific rules, including suppression of `Object_` mixins on contributing domain services, will remain in the action path.
+Member-specific filtering and `_MixedInMemberFactory` construction will remain unchanged after full introspection.
+
+Duplicating the two-stage logic in both paths was rejected because subtle differences could reintroduce eager loading later.
+Moving the behavior into the public `SpecificationLoader` API was rejected because applicability is contextual to the target specification and no public API change is needed.
+
+### Preserve full introspection before member streaming
+
+After a candidate passes the type-level checks, the framework will explicitly advance that same cached specification to `FULLY_INTROSPECTED` before calling `streamActions`.
+This preserves the existing assumption that declared action metadata and postprocessing are complete before a mixed-in action, property, or collection is constructed.
+
+Streaming members from a merely type-introspected specification was rejected because it would alter initialization semantics and risk incomplete facets.
+
+### Verify behavior and depth independently
+
+Functional tests will verify applicable and inapplicable action and association mixins, catch-all mixins, explicit member ordering, and navigation-action synthesis.
+Diagnostic-chain tests will register many inapplicable mixins and assert that evaluating them does not request `FULLY_INTROSPECTED`, while applicable candidates still do.
+The production-shaped full-boot fixture will run with command recording enabled and a constrained JVM stack.
+
+The tests will assert the absence of avoidable full-introspection transitions rather than a brittle exact total depth, because unrelated framework evolution can add legitimate specification loads.
+
+## Risks / Trade-offs
+
+- [Risk] Some `MixinFacet` information might currently be finalized during member introspection. → Add a characterization test proving applicability and main-method metadata are available at `TYPE_INTROSPECTED` before changing discovery.
+- [Risk] Advancing an accepted specification in a second loader call could alter re-entrant state handling. → Reuse the cached specification, retain existing introspection guards, and cover cyclic and cross-type fixtures.
+- [Risk] Invalid mixin declarations may now be fully validated later than before if they never apply to the current target. → Preserve eager metamodel traversal elsewhere and add validation coverage for malformed registered mixins.
+- [Risk] The change reduces but cannot eliminate recursion when many candidates genuinely apply. → Retain diagnostics and treat an iterative metamodel work queue as a separate follow-up if production depth remains excessive.
+- [Risk] A shared helper could accidentally apply action-only exclusions to associations. → Keep only common facet and target checks in the helper and test each member kind separately.
+
+## Migration Plan
+
+No data, configuration, or application-code migration is required.
+Deploy with the existing deterministic mixin ordering and introspection diagnostics enabled by default.
+Re-run the production application using the same command-recording configuration and compare the diagnostic depth if any failure remains.
+Rollback consists of reverting this isolated discovery change; no persisted state is modified.
+
+## Open Questions
+
+- Does every supported mixin declaration style expose a complete `MixinFacet`, including target type and main method name, at `TYPE_INTROSPECTED`?
+- Are malformed but globally registered mixins guaranteed to receive full validation independently of being applicable to a particular target?
+- After prefiltering, what is the maximum observed production chain depth and which remaining transitions dominate it?
diff --git a/openspec/changes/prefilter-mixins-before-full-introspection/proposal.md b/openspec/changes/prefilter-mixins-before-full-introspection/proposal.md
new file mode 100644
index 00000000000..6ac10553c11
--- /dev/null
+++ b/openspec/changes/prefilter-mixins-before-full-introspection/proposal.md
@@ -0,0 +1,29 @@
+## Why
+
+Production diagnostics captured a 395-level metamodel introspection chain containing 395 distinct types, where mixed-in member discovery repeatedly fully introspected candidate mixins before checking whether they applied to the target type.
+The chain is finite but exhausts the JVM stack, so mixin applicability must be determined using type-level metadata before member introspection is requested.
+
+## What Changes
+
+- Load each candidate mixin only through type introspection before reading its `MixinFacet` and evaluating applicability to the target type.
+- Fully introspect a candidate mixin only after it is known to contribute an action, property, or collection to the target type.
+- Apply the same two-stage loading rule to mixed-in action discovery and mixed-in association discovery.
+- Preserve deterministic class-name traversal, existing mixin applicability semantics, member construction, explicit member ordering, and validation behavior.
+- Add regression coverage showing that large sets of inapplicable mixins do not create a deeply nested full-introspection chain while applicable mixins still contribute all expected members.
+- Retain the recently added introspection diagnostics to verify and guard the reduced nesting depth.
+
+## Capabilities
+
+### New Capabilities
+
+- `mixin-introspection-prefiltering`: Determines mixin applicability from type-level metadata before requesting full member introspection, bounding avoidable recursive metamodel loading.
+
+### Modified Capabilities
+
+None.
+
+## Impact
+
+The change affects mixed-in action and association discovery in `ObjectSpecificationAbstract` and the metamodel tests that cover mixin contribution and navigation-action synthesis.
+It introduces no new dependency, configuration property, public API, or domain-programming-model behavior.
+Applicable mixins will still be fully introspected, while inapplicable mixins will remain type-introspected until another legitimate consumer requires their members.
diff --git a/openspec/changes/prefilter-mixins-before-full-introspection/specs/mixin-introspection-prefiltering/spec.md b/openspec/changes/prefilter-mixins-before-full-introspection/specs/mixin-introspection-prefiltering/spec.md
new file mode 100644
index 00000000000..3460bdc9e4b
--- /dev/null
+++ b/openspec/changes/prefilter-mixins-before-full-introspection/specs/mixin-introspection-prefiltering/spec.md
@@ -0,0 +1,68 @@
+## ADDED Requirements
+
+### Requirement: Type-level applicability prefilter
+
+The framework SHALL determine whether a registered mixin applies to a target specification after type introspection and before requesting full member introspection of that mixin.
+The prefilter SHALL use the mixin's authoritative `MixinFacet` semantics.
+
+#### Scenario: Candidate mixin does not apply
+
+- **WHEN** the framework evaluates a registered mixin whose `MixinFacet` does not apply to the target type
+- **THEN** the framework does not request `FULLY_INTROSPECTED` for that candidate as part of mixed-in member discovery
+- **THEN** the candidate contributes no member to the target specification
+
+#### Scenario: Candidate mixin applies
+
+- **WHEN** the framework evaluates a registered mixin whose `MixinFacet` applies to the target type
+- **THEN** the framework advances the cached mixin specification to `FULLY_INTROSPECTED` before streaming its members
+- **THEN** the applicable members are eligible for contribution to the target specification
+
+#### Scenario: Candidate has no mixin facet
+
+- **WHEN** a registered candidate has no usable `MixinFacet` after type introspection
+- **THEN** the framework does not request full introspection merely to evaluate its applicability
+- **THEN** the candidate contributes no member to the target specification
+
+### Requirement: Consistent action and association prefiltering
+
+The framework SHALL apply the same type-level applicability prefilter to mixed-in action discovery and mixed-in association discovery.
+
+#### Scenario: Inapplicable action mixin
+
+- **WHEN** an action mixin does not apply to the target type
+- **THEN** mixed-in action discovery rejects it without full member introspection
+
+#### Scenario: Inapplicable property or collection mixin
+
+- **WHEN** a property or collection mixin does not apply to the target type
+- **THEN** mixed-in association discovery rejects it without full member introspection
+
+### Requirement: Preserved applicable-mixin behavior
+
+Applicable mixins SHALL retain their existing member identity, facets, applicability, explicit ordering, and navigation-action synthesis behavior after prefiltering.
+
+#### Scenario: Applicable mixed-in members are created
+
+- **WHEN** applicable action, property, and collection mixins are discovered
+- **THEN** the target specification contains the same mixed-in members as before prefiltering
+- **THEN** each contributed member retains its existing identifier and facets
+
+#### Scenario: Explicit member order conflicts with traversal order
+
+- **WHEN** applicable mixins declare explicit member ordering that differs from deterministic class-name traversal order
+- **THEN** the resulting members follow the explicit member ordering
+
+#### Scenario: Parented mixed-in collection is applicable
+
+- **WHEN** command recording is enabled and an applicable mixin contributes a parented collection
+- **THEN** navigation-action synthesis still creates the corresponding synthetic navigation action
+
+### Requirement: Avoidable nesting reduction
+
+Mixed-in member discovery SHALL not create nested full-introspection transitions for inapplicable candidates.
+
+#### Scenario: Target is evaluated against many inapplicable mixins
+
+- **WHEN** a target specification is evaluated against a large deterministic sequence of inapplicable mixins
+- **THEN** diagnostics show type-level applicability checks for those candidates without corresponding full-introspection requests from mixed-in action or association discovery
+- **THEN** applicable candidates later in the sequence are still fully introspected and contributed
diff --git a/openspec/changes/prefilter-mixins-before-full-introspection/tasks.md b/openspec/changes/prefilter-mixins-before-full-introspection/tasks.md
new file mode 100644
index 00000000000..67f63f929aa
--- /dev/null
+++ b/openspec/changes/prefilter-mixins-before-full-introspection/tasks.md
@@ -0,0 +1,26 @@
+## 1. Characterize type-stage mixin metadata
+
+- [ ] 1.1 Add tests proving supported action, property, collection, and `@DomainObject` mixin styles expose applicability and main-method metadata at `TYPE_INTROSPECTED`.
+- [ ] 1.2 Add a diagnostic-chain test showing the current production-shaped fixture requests full introspection for inapplicable mixins before the correction.
+- [ ] 1.3 Confirm malformed registered mixins remain covered by metamodel validation independently of contribution to a particular target.
+
+## 2. Implement applicability prefiltering
+
+- [ ] 2.1 Add a shared internal helper that type-introspects a candidate and returns it only when its `MixinFacet` applies to the target specification.
+- [ ] 2.2 Update mixed-in association discovery to fully introspect only candidates accepted by the helper.
+- [ ] 2.3 Update mixed-in action discovery to fully introspect only accepted candidates while preserving the domain-service `Object_` exclusion.
+- [ ] 2.4 Preserve deterministic class-name traversal and existing member filtering and construction after a candidate is accepted.
+
+## 3. Verify functional compatibility
+
+- [ ] 3.1 Add tests proving inapplicable action, property, and collection mixins are not fully introspected or contributed.
+- [ ] 3.2 Add tests proving applicable action, property, and collection mixins are fully introspected and contribute the expected identifiers and facets.
+- [ ] 3.3 Verify explicit member ordering still overrides class-name traversal order.
+- [ ] 3.4 Verify applicable parented mixed-in collections still synthesize navigation actions when command recording is enabled.
+
+## 4. Verify recursion-depth reduction
+
+- [ ] 4.1 Extend the production-shaped fixture with many deterministic inapplicable mixins followed by applicable candidates.
+- [ ] 4.2 Use the introspection diagnostic seam to assert inapplicable candidates receive type-level checks without mixed-in-discovery requests for full introspection.
+- [ ] 4.3 Run focused metamodel and full-boot recording-navigation tests with a constrained `-Xss256k` stack.
+- [ ] 4.4 Document the before-and-after nested full-introspection depth and any remaining dominant recursion path for production verification.