jpie 3.8.1 → 3.8.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d9e7099c27c6aec0de41a095baa563dbc63eb934b44ab8195a9e3a51f5152c4e
-  data.tar.gz: 86ee7fbdc3cf8414d9829bbf4f42ac7e016603f8a884a0b674d8e9b869cf1b8d
+  metadata.gz: 5fee8d7ae2ce0016c8c6b1d0740cf9448d7b932c9d71fc0f74a553ae5bd15d17
+  data.tar.gz: 8d8151d6323ad4c3538abb0bb95f23347162d047006af7c9e7d03da638d4f955
 SHA512:
-  metadata.gz: a013761543aba53b56e575f8b2f51d3004d1cae53e53570bf506bd744cb2d38891e43a5188ad11ee338923aacdd5c8bc4cf107e1772f5cb73173aafb590d1859
-  data.tar.gz: 105cbbcb454083ebbfae7db54d9fbec5e76c39d3c1d1823c16b34de071abeae47e4cdf5923aadeb3224e609ee85c07712ed37651caa1122719501ac1c479ae07
+  metadata.gz: e8e86875e6b6c582640e9f7c03355a8dd271ecab3c1e96186a304f0927b28cccda7fb5009f013b37bf0bd5c778c280e29a03b765033c2e7fe1babba2bd24576a
+  data.tar.gz: 44feac1f5b20d4cb6c95f05773e06fefedb7cea9b254fb55a98af26a0b58f5dec60dae425f55bda8c10185f57099c7bd2450729a940c7a31eab8636acbdc1348

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    jpie (3.8.1)
+    jpie (3.8.3)
       actionpack (~> 8.1, >= 8.1.0)
       pg_query (>= 4)
       prosopite (>= 1)

data/PERFORMANCE_BASELINE.md

@@ -5,9 +5,12 @@ problem: controller actions with large `include=` trees fire hundreds to
 thousands of SQL queries and allocate hundreds of MB per request. Production
 examples: `/workstreams` with 25 include paths (~300 queries at page 10, up to
 `page[size]=100`), `/policies` with 17 include paths at `page[size]=1` (kills
-the app on AI-conversation data; one index request allocated ~600MB), and
+the app on AI-conversation data; one index request allocated ~600MB),
 `/evidence_checks` with a 45-id batch filter and files at depth 3 (~1,250
-queries).
+queries), `/incidents` with 18 include paths at page 20 (577 ActiveRecord
+calls, 2,794ms), and `/suggested_risk_scenarios` with only two include paths
+(541 ActiveRecord calls, 2,059ms). The last two fail for opposite reasons; see
+"Two shapes, two causes" below.
 
 The numbers come from the benchmark suite in `spec/benchmarks/`. The evaluation
 behind them ran 32 independent code-path analyses; a second wave verified the
@@ -26,15 +29,19 @@ shapes, wall time, allocated/retained bytes, allocation sites, RSS). Diff that
 file against this baseline after any optimization. `DEBUG_QUERIES=1` also dumps
 raw SQL logs to `tmp/benchmarks/query_logs/`.
 
-The suite seeds a stand-in domain (`Assignment`, `Gadget`, `Edition`, `Remark`,
-and others) that copies the production include-tree topology: wide + deep trees,
-polymorphic hops, shared prefixes, STI-free but otherwise faithful. The
-`assignments_full` tree mirrors the production `/workstreams` request
+The suite seeds a stand-in domain (`Assignment`, `Gadget`, `Fault`, `Edition`,
+`Remark`, and others) that copies the production include-tree topology: wide +
+deep trees, polymorphic hops, shared prefixes, STI-free but otherwise faithful.
+The `assignments_full` tree mirrors the production `/workstreams` request
 path-for-path; `assignments_single_conversation` mirrors the `/policies` killer
 (fat document bodies, a 600-remark conversation, ActiveStorage files, per-remark
 children); `gadgets_evidence_shape` mirrors `/evidence_checks` (a 45-id `id_in`
 batch, two branches converging on ActiveStorage files, polymorphic leaves at
-depth 2-3).
+depth 2-3); `faults_index` mirrors `/incidents` (link joins to depth-3 gadget
+and appliance targets whose resources carry resource-default preloads and
+per-record meta, plus a full discussion thread); `suggestions_polymorphic`
+mirrors `/suggested_risk_scenarios` (two depth-1 paths, one of them
+polymorphic, onto target resources that under-declare their preloads).
 
 ## Baseline (large dataset, sqlite, 2026-08-14)
 
@@ -98,18 +105,55 @@ active — the domain shape alone is not the problem.
    `{files_attachments: {blob: {}}}` in the preload hash and reads blobs
    through the loaded associations. See "Optimizations landed" below.
 
-4. **Per-record meta queries, any depth.** Instance `meta` that touches an
-   association or runs a finder fires per serialized record. The batch pass
-   (`preload_included_resource_associations`) only applies resource-default
-   preloads to depth-1 targets, and only from `records` scope values. Probe: 1
-   profile query per serialized user at depth 1 and depth 2; putting the path in
-   `include=` collapses it to one batched query. Production:
-   `PolicyResource#meta` runs 3 version lookups per policy;
-   `PolicyVersionResource#meta` touches `resource.policy` per version.
-   Baseline signature: 40× draft-edition and 40× published-edition lookups in
-   `assignments_full`.
-
-5. **Virtual sort disables everything.** A virtual (resource-method) sort field
+4. **Resource-default preloads reached depth 1 only — FIXED** (see
+   "Optimizations landed" #3). Two separate passes load data, and they did not
+   cover the same ground:
+   - `scope_with_includes` preloads the include tree at **every** depth. It
+     builds one nested hash from all paths, so a 4-level path costs 4 queries,
+     not 4 per record. Control: `users_deep_include` serializes 400 records in
+     3 queries; `assignments_single_conversation` serializes 2,191 records at
+     depth 4 in 22 queries.
+   - `preload_included_resource_associations` applies each resource's own
+     `records` preloads to include targets. It used to read
+     `include_path.split(".").first`, so only **depth-1** targets got them.
+
+   A resource at depth 2 or deeper therefore serialized with its own
+   associations unloaded. Every `meta` method that branches on `loaded?` took
+   the fallback branch and queried per record. Production:
+   `SelectedControlResource.records` preloads `evidence_checks`,
+   `selected_control_checks`, and `framework_criteria`, but `/incidents`
+   reaches `SelectedControl` at depth 2 through
+   `related_controls.selected_control`, so none of the three apply.
+   Anchor: `include_preloading.rb` (`preload_included_resource_associations`).
+   Baseline signature: 390 of 415 queries in `faults_index` are per-record;
+   40× draft-edition and 40× published-edition lookups in `assignments_full`.
+
+   The depth-1 pass itself is sound, including through a polymorphic hop. Probe:
+   `GET /assignments?include=subject` (polymorphic to `Gadget`) batches all five
+   of `GadgetResource`'s declared preloads into one query each, and the count
+   stays flat as records grow. Regression spec:
+   `polymorphic_resource_preload_spec.rb`. Read the two facts together before
+   blaming jpie for an N+1: at depth 1 a declared preload is applied, so a
+   per-record query there means the resource never declared it.
+
+5. **Resources that never declare the preloads their own reads need.** A
+   `meta` method or attribute that walks an association costs one query per
+   serialized record when the resource's `records` scope does not preload it.
+   jpie cannot infer the need; nothing in the include tree names the
+   association. This is an application fault, not a library limit, and it is
+   the whole cost of a shallow request. Production `/suggested_risk_scenarios`
+   sends two depth-1 paths and still runs 541 ActiveRecord calls:
+   `RiskScenarioTemplateResource#meta` walks `inherent_risk_template.category`
+   with no `records` override (2 queries per template);
+   `SelectedControlResource#baseline` reads `control_template`, which its
+   preload list omits; `ComplianceScopeableResource` exposes `in_scope` and
+   `in_scope_justification`, which probe and then load
+   `resource_framework_scopes`, and no resource preloads them.
+   Baseline signature: `suggestions_polymorphic` runs one `baseline_estimates`
+   and one `estimate_categories` query per serialized repair plan, while every
+   association a resource does declare loads in a single batched query.
+
+6. **Virtual sort disables everything.** A virtual (resource-method) sort field
    materializes the whole filtered table as an Array before pagination, and
    `scope_with_includes` bails on Arrays, so nothing preloads. Probe: 10 users,
    `include=posts.comments`: 3 queries with a column sort, 41 with a virtual
@@ -259,3 +303,159 @@ Cumulative against the original baseline: the /policies shape is down from
 1,728 queries to 22; the /evidence_checks shape from 2,550 to 146; page 100
 from 5,102 to 1,233. The remaining residue is mostly mechanism 4 (per-record
 meta lookups: 120 of the 153 queries in assignments_full).
+
+### 3. Apply resource-default preloads at every depth (mechanism 4)
+
+`preload_included_resource_associations` read only the first segment of each
+include path, so a resource reached at depth 2 or deeper never received the
+preloads its own `records` scope declares. It now nests the paths into one tree
+and walks it, applying each target class's preloads at every hop. Shared
+prefixes collapse, so a prefix is visited once however many paths cross it, and
+a polymorphic hop continues once per class present in the loaded targets.
+
+The walk costs no association queries: every hop reads targets that
+`scope_with_includes` already loaded. Pure batching — included counts are
+identical, scenario for scenario, and the whole suite passes unchanged.
+Regression spec: `deep_resource_preload_spec.rb` pins a depth-2 target at a
+flat query count (36 now, 141 before).
+
+Large dataset, before and after:
+
+| Scenario | Queries before | Queries after | Alloc MB before | Alloc MB after |
+|---|---|---|---|---|
+| faults_index | 415 | 81 (−80%) | 117.0 | 114.4 |
+| assignments_full | 292 | 183 (−37%) | 83.7 | 82.4 |
+| assignments_full + authz | 315 | 206 (−35%) | 86.0 | 84.7 |
+| gadgets_single | 87 | 34 (−61%) | 3.09 | 2.57 |
+| assignments_page_1 | 108 | 55 (−49%) | 40.2 | 39.5 |
+| assignments_page_25 | 582 | 385 (−34%) | 156.3 | 154.1 |
+| assignments_page_50 | 1,027 | 693 (−33%) | 280.8 | 277.2 |
+| assignments_page_100 | 1,830 | 1,293 (−29%) | 526.2 | 520.5 |
+| gadgets_evidence_shape (control) | 150 | 150 | 59.2 | 59.3 |
+| assignments_single_conversation (control) | 22 | 22 | 79.7 | 80.0 |
+| suggestions_polymorphic (control) | 84 | 84 | 9.37 | 9.37 |
+| users_deep_include (control) | 3 | 3 | 9.83 | 9.84 |
+
+The controls carry the argument. `suggestions_polymorphic` does not move,
+because its targets already sat at depth 1 — that request's cost is
+mechanism 5, in the application, and no jpie change touches it.
+`gadgets_evidence_shape` and `users_deep_include` do not move either: neither
+reaches a preload-declaring resource below depth 1.
+
+Allocations barely move because the saving is query count, not object count.
+Wall time on sqlite is too noisy between runs to attribute — the same scenario
+varied by 2x across runs with identical query counts. Against production
+postgres, where per-query latency is real, a 334-query drop on `faults_index`
+is the whole point.
+
+## Two shapes, two causes (2026-08-17)
+
+Two staging requests look alike from the outside: both are index pages, both
+spend about 2 seconds, both fire hundreds of ActiveRecord calls. They fail for
+opposite reasons, and the fix for one does nothing for the other.
+
+| | `/incidents` | `/suggested_risk_scenarios` |
+|---|---|---|
+| Include paths | 18, up to depth 3 | 2, both depth 1 |
+| Where targets sit | depth 2-3 | depth 1 |
+| Did jpie apply the target's preloads? | No — depth-1 pass missed them | Yes |
+| Cause | jpie: mechanism 4 | application: mechanism 5 |
+| Fix belongs in | jpie | kiln resources |
+| Benchmark scenario | `faults_index` | `suggestions_polymorphic` |
+| Status | fixed: 415 → 81 queries | open, needs kiln preloads |
+
+### The /incidents shape: mechanism 4
+
+`faults_index` reproduces the production `/incidents` request: 18 include
+paths, `page[size]=20`, `sort=-created_at`, `filter[archived]=false`. Three
+link branches reach `Gadget` and `Appliance` at depth 2-3. Both resources now
+carry what production carries: a `records` scope that preloads what `meta`
+reads, and `meta` methods that fall back to a query when nothing preloaded.
+
+**This change moved the older scenarios too.** `Gadget` and `Appliance` sit in
+the `assignments_full` tree as well, so that scenario went from 153 queries to
+292 on the same code. No optimization regressed; the benchmark domain became
+more faithful. Compare future runs against the table below, not against the
+2026-08-14 recordings.
+
+| Scenario | Primary | Included | Queries | ms (median) | Alloc MB |
+|---|---|---|---|---|---|
+| faults_index (page 20, 18 paths) | 20 | 4,290 | 415 | 2,430 | 117.0 |
+| assignments_full (re-recorded) | 10 | 2,701 | 292 | 1,548 | 83.7 |
+| assignments_full + authz (re-recorded) | 10 | 2,701 | 315 | 1,088 | 86.0 |
+| gadgets_evidence_shape (re-recorded) | 45 | 1,656 | 150 | 767 | 59.2 |
+| assignments_single_conversation (unchanged) | 1 | 2,191 | 22 | 432 | 79.7 |
+| users_deep_include (control) | 20 | 400 | 3 | 95 | 9.8 |
+
+Adding the suggestion domain changed none of these counts. Every scenario above
+reproduced its query count exactly on the run that first measured
+`suggestions_polymorphic`, which confirms the new tables and resources sit
+outside the other include trees.
+
+390 of the 415 `faults_index` queries are per-record. The include tree itself
+costs about 25. The breakdown, against 45 gadgets and 25 appliances reached at
+depth 2-3:
+
+| Count | Query | Source | After the depth fix |
+|---|---|---|---|
+| 70 | `archivals` by owner | `records` preload, unreachable at depth 2 | 2 |
+| 45 | `criteria.id` pluck | `criterium_ids` attribute | 1 |
+| 45 + 45 | `inspections` order-limit, then exists | inspection history in `meta` | 1 |
+| 45 + 45 | `standard_scopes` rows, then exists | scope verdict in `meta` | 1 |
+| 45 | `gadget_checks` exists | checklist verdict in `meta` | 1 |
+| 25 + 25 | `stream_entries` by stream | append-only read, no association | 50 |
+
+Only the last row was beyond jpie's reach: a raw stream read has no association
+for any preloader to batch. Everything above it collapsed to a handful of
+batched queries once resource-default preloads applied at every depth, taking
+the scenario from 415 queries to 81. The 50 stream reads are now the largest
+single item, and they need a change in the application.
+
+### The /suggested_risk_scenarios shape: mechanism 5
+
+`suggestions_polymorphic` reproduces the production request:
+`filter[account_level]=true`, `sort=-priority`, and two include paths —
+`repair_plan` (plain) and `suggestable` (polymorphic, onto `Gadget` and
+`Appliance`). `SuggestionResource.records` copies the production scope, with
+the plain hop on `includes` and the polymorphic hop on `preload`.
+
+Both targets sit at depth 1, so jpie applies their `records` preloads. The
+split in the results is the whole point:
+
+- `Gadget` declares its preloads. All five load in one batched query each,
+  however many gadgets the page holds.
+- `RepairPlan` declares none, and its `meta` walks
+  `baseline_estimate.estimate_category`. That costs two queries per serialized
+  plan — the exact `Risk::InherentRiskTemplate` and `Risk::Category` bands in
+  the staging trace.
+- `Appliance` reads an append-only stream, which has no association to preload
+  at any depth.
+
+| Dataset | Primary | Included | Queries | ms (median) | Alloc MB |
+|---|---|---|---|---|---|
+| small | 5 | 10 | 22 | 14 | - |
+| medium | 25 | 37 | 46 | 31 | 2.9 |
+| large | 100 | 112 | 84 | 203 | 9.4 |
+
+Queries grow far slower than the page, because the repair-plan pool caps at 12
+and only 25 of the 100 suggestables are appliances. Production behaves the same
+way: 18 suggestions reached 13 distinct templates. The large run splits like
+this:
+
+| Count | Query | Verdict |
+|---|---|---|
+| 25 + 25 | `stream_entries` by stream | unfixable by preloading |
+| 12 + 12 | `baseline_estimates`, then `estimate_categories` | resource never declared it |
+| 2 | `archivals` by owner type | correct: one per polymorphic class |
+| 8 | primary, both target classes, plan, declared preloads | correct: batched |
+
+Only 8 of the 84 queries are structural. Every association a resource declares
+is batched, including through the polymorphic hop, and the 24 `RepairPlan`
+queries are the shape a one-line preload removes.
+
+No change to jpie removes the `RepairPlan` queries. The resource has to ask for
+the preload. In production the three to fix are
+`RiskScenarioTemplateResource` (add `inherent_risk_template: :category`),
+`SelectedControlResource` (add `control_template` to its existing preload
+list), and `ComplianceScopeableResource` (add `resource_framework_scopes`,
+which alone accounts for 82 of the 541 calls).

data/README.md

@@ -875,6 +875,13 @@ This will:
 - Load `API::V1::WidgetResource` (falls back to `WidgetResource` if `namespace_fallback: true`)
 - Pass `jsonapi_namespace: "api/v1"` to the controller
 
+The request namespace also selects the resource class during serialization: for
+the attributes, the include filter, the links, and the relationship linkage.
+`GET /portal/posts` serializes with `Portal::PostResource` even when the `Post`
+model is flat. When the namespaced resource does not exist, the loader falls
+back to the model's own namespace, then to the flat resource. Set
+`config.namespace_fallback = false` to refuse the flat fallback.
+
 #### Namespaced Resources
 
 Define resources within namespaces that match your route structure:

data/lib/json_api/controllers/concerns/resource_actions/include_preloading.rb

@@ -8,10 +8,14 @@ module JSONAPI
       private
 
       def includes_to_hash(paths)
-        hash = paths.each_with_object({}) do |path, h|
-          path.split(".").reduce(h) { |cur, part| cur[part.to_sym] ||= {} }
+        filter_includable(includes_to_tree(paths), model_class)
+      end
+
+      # Nests dotted include paths into one tree, collapsing shared prefixes.
+      def includes_to_tree(paths)
+        paths.each_with_object({}) do |path, tree|
+          path.split(".").reduce(tree) { |node, part| node[part.to_sym] ||= {} }
         end
-        filter_includable(hash, model_class)
       end
 
       # Preloads associations from the include param so the serializer avoids N+1 queries
@@ -82,18 +86,45 @@ module JSONAPI
         assoc.polymorphic? || (value.present? && hash_contains_polymorphic?(value, assoc.klass))
       end
 
+      # Applies each included resource's own `records` preloads to the records
+      # of that resource's class. Walks the whole include tree: a resource
+      # reached at depth 3 gets its preloads just as one reached at depth 1.
+      #
+      # The tree collapses shared prefixes, so a prefix is visited once however
+      # many paths run through it. Walking costs no association queries — every
+      # hop reads targets that `scope_with_includes` already loaded. The only
+      # queries are the batched resource-default preloads themselves, each of
+      # which replaces one query per record during serialization.
       def preload_included_resource_associations(resources, includes)
         return if includes.empty? || resources.empty?
 
-        includes.each do |include_path|
-          association_name = include_path.split(".").first.to_sym
-          assoc_reflection = model_class.reflect_on_association(association_name)
-          next unless assoc_reflection
+        preload_resource_tree(resources, model_class, includes_to_tree(includes))
+      end
 
-          targets = collect_include_targets(resources, association_name)
+      def preload_resource_tree(records, klass, tree)
+        tree.each do |association_name, subtree|
+          reflection = klass.reflect_on_association(association_name)
+          next unless reflection
+
+          targets = collect_include_targets(records, association_name)
           next if targets.empty?
 
-          apply_preloads_for_targets(targets, assoc_reflection.polymorphic?)
+          apply_preloads_for_targets(targets, reflection.polymorphic?)
+          next if subtree.empty?
+
+          descend_resource_tree(targets, reflection, subtree)
+        end
+      end
+
+      # A polymorphic hop has no single target class, so continue once per
+      # class actually present in the loaded targets.
+      def descend_resource_tree(targets, reflection, subtree)
+        if reflection.polymorphic?
+          targets.group_by(&:class).each do |target_class, records|
+            preload_resource_tree(records, target_class, subtree)
+          end
+        else
+          preload_resource_tree(targets, reflection.klass, subtree)
         end
       end
 
@@ -116,7 +147,7 @@ module JSONAPI
         return if records.empty?
 
         klass = records.first.class
-        resource_scope = ResourceLoader.find_for_model(klass).records
+        resource_scope = ResourceLoader.find_for_model(klass, namespace: jsonapi_namespace).records
         preload_values = resource_scope.preload_values + resource_scope.includes_values
         return if preload_values.empty?
 

data/lib/json_api/controllers/concerns/resource_actions/serialization.rb

@@ -9,11 +9,9 @@ module JSONAPI
       def serialize_resource(resource)
         includes = parse_include_param
         cache = build_include_filter_cache([resource], includes)
-        JSONAPI::Serializer.new(resource, authorization_context: self, include_filter_cache: cache).to_hash(
-          include: includes,
-          fields: parse_fields_param,
-          document_meta: jsonapi_document_meta,
-        )
+        serializer = JSONAPI::Serializer.new(resource, authorization_context: self, include_filter_cache: cache,
+                                                       namespace: jsonapi_namespace,)
+        serializer.to_hash(include: includes, fields: parse_fields_param, document_meta: jsonapi_document_meta)
       end
 
       def serialize_collection(resources)
@@ -48,7 +46,8 @@ module JSONAPI
       end
 
       def serialize_single(resource, includes, fields, include_context = nil, cache = nil)
-        JSONAPI::Serializer.new(resource, authorization_context: self, include_filter_cache: cache)
+        JSONAPI::Serializer.new(resource, authorization_context: self, include_filter_cache: cache,
+                                          namespace: jsonapi_namespace,)
           .to_hash(include: includes, fields:, document_meta: nil, include_context:)
       end
 
@@ -56,7 +55,8 @@ module JSONAPI
       # every included record gets its scope verdict in one query per class,
       # and the serializers answer their per-visit checks from memory.
       def build_include_filter_cache(resources, includes)
-        cache = JSONAPI::Serialization::IncludeFilterCache.new(authorization_context: self)
+        cache = JSONAPI::Serialization::IncludeFilterCache.new(authorization_context: self,
+                                                               namespace: jsonapi_namespace,)
         includes.each do |path|
           current = resources
           path.split(".").each do |part|

data/lib/json_api/resources/resource_loader.rb

@@ -59,20 +59,42 @@ module JSONAPI
     def self.find_for_model(model_class, namespace: nil)
       return ActiveStorageBlobResource if active_storage_blob?(model_class)
 
-      # Key format "::ModelName" is public-ish: applications pre-populate
-      # @model_cache with these keys to pin STI subclass resources.
-      key = namespace ? "#{namespace}|::#{model_class.name}" : "::#{model_class.name}"
+      key = model_cache_key(model_class, namespace)
       cached = @model_cache[key]
       return cached if cached
 
-      effective_namespace = namespace || extract_namespace_from_model(model_class)
-      candidates = model_candidates(model_class, effective_namespace)
-
-      klass = resolve(candidates) ||
-              raise(MissingResourceClass.new(model_class.name, namespace: effective_namespace))
+      model_namespace = extract_namespace_from_model(model_class)
+      klass = resolve(find_for_model_candidates(model_class, namespace, model_namespace)) ||
+              raise(MissingResourceClass.new(model_class.name, namespace: namespace || model_namespace))
       @model_cache[key] = klass
     end
 
+    def self.find_for_model_candidates(model_class, namespace, model_namespace)
+      return model_candidates(model_class, model_namespace) unless namespace
+
+      request_namespace_candidates(model_class, namespace, model_namespace)
+    end
+
+    # Key format "::ModelName" is public-ish: applications pre-populate
+    # @model_cache with these keys to pin STI subclass resources.
+    def self.model_cache_key(model_class, namespace)
+      return "::#{model_class.name}" unless namespace
+
+      "#{namespace}|::#{model_class.name}|#{JSONAPI.configuration.namespace_fallback ? 1 : 0}"
+    end
+
+    # The request namespace outranks the model's own namespace, which stays a
+    # fallback so a namespaced model still reaches its own resource. The flat
+    # name comes last, and only while the configuration allows the fallback.
+    def self.request_namespace_candidates(model_class, namespace, model_namespace)
+      resource_type = model_class.name.demodulize.underscore.pluralize
+      candidates = [build_resource_class_name(resource_type, namespace)]
+      candidates |= model_candidates(model_class, model_namespace)
+      return candidates if JSONAPI.configuration.namespace_fallback
+
+      candidates - [build_resource_class_name(resource_type, nil)]
+    end
+
     def self.build_resource_class_name(resource_type, namespace)
       base = "#{resource_type.singularize.classify}Resource"
       return base unless namespace.present?

data/lib/json_api/serialization/concerns/includes_serialization.rb

@@ -61,7 +61,7 @@ module JSONAPI
       end
 
       def valid_include_association?(current_record, association_name)
-        current_definition = ResourceLoader.find_for_model(current_record.class)
+        current_definition = ResourceLoader.find_for_model(current_record.class, namespace:)
         relationship_def = RelationshipHelpers.find_relationship_definition(current_definition, association_name)
         return false unless relationship_def
         return true if self.class.active_storage_attachment?(association_name, current_record.class)
@@ -91,7 +91,7 @@ module JSONAPI
       end
 
       def build_scoped_relation(related_klass, association)
-        related_base_scope = ResourceLoader.find_for_model(related_klass).records
+        related_base_scope = ResourceLoader.find_for_model(related_klass, namespace:).records
         association.scope.merge(apply_include_authorization(related_base_scope, related_klass))
       end
 
@@ -119,12 +119,19 @@ module JSONAPI
         return if ctx.processed.include?(build_record_key(related_record))
 
         requested = include_paths_to_relationship_names(ctx.all_includes, path_to_record)
-        serializer = self.class.new(related_record, parent_record:, association_name:,
-                                                    authorization_context:, include_filter_cache:,)
+        serializer = child_serializer(related_record, parent_record:, association_name:)
         ctx.included_records << serializer.serialize_record(ctx.fields, requested_relationships: requested)
         ctx.processed.add(build_record_key(related_record))
       end
 
+      # An included record serializes with the same request context as its
+      # parent: the authorization context, the filter cache, and the namespace
+      # that selects the resource class.
+      def child_serializer(related_record, parent_record:, association_name:)
+        self.class.new(related_record, parent_record:, association_name:,
+                                       authorization_context:, include_filter_cache:, namespace:,)
+      end
+
       def build_record_key(related_record)
         "#{related_record.class.name}-#{related_record.id}"
       end

data/lib/json_api/serialization/concerns/links_serialization.rb

@@ -43,7 +43,7 @@ module JSONAPI
       end
 
       def variant_options_for_parent_association
-        parent_definition = ResourceLoader.find_for_model(parent_record.class)
+        parent_definition = ResourceLoader.find_for_model(parent_record.class, namespace:)
         rel_def = RelationshipHelpers.find_relationship_definition(parent_definition, association_name)
         rel_def&.dig(:options, :variant)
       end

data/lib/json_api/serialization/concerns/relationships_serialization.rb

@@ -74,6 +74,7 @@ module JSONAPI
           resource_class: definition,
           use_instance_class:,
           base_resource_class: base_def_for_related,
+          namespace:,
         )
       end
 

data/lib/json_api/serialization/include_filter_cache.rb

@@ -15,8 +15,9 @@ module JSONAPI
       Entry = Struct.new(:base_scope, :authorized_scope, :narrowed, :where_clause_empty, :where_hash,
                          keyword_init: true,)
 
-      def initialize(authorization_context: nil)
+      def initialize(authorization_context: nil, namespace: nil)
         @authorization_context = authorization_context
+        @namespace = namespace
         @entries = {}
         @verdicts = {}
       end
@@ -53,7 +54,7 @@ module JSONAPI
       end
 
       def build_entry(klass)
-        base_scope = ResourceLoader.find_for_model(klass).records
+        base_scope = ResourceLoader.find_for_model(klass, namespace: @namespace).records
         authorized_scope = apply_authorization(base_scope, klass)
         Entry.new(
           base_scope: base_scope,

data/lib/json_api/serialization/serializer.rb

@@ -35,10 +35,16 @@ module JSONAPI
       @jsonapi_object = nil
     end
 
+    # namespace is the request's JSON:API namespace. A namespaced endpoint over
+    # a flat model (a public portal that re-exposes an internal model) resolves
+    # to its own resource only when the namespace reaches this far: resolution
+    # by model alone derives the namespace from the model, so a flat model can
+    # never reach a namespaced resource.
     def initialize(record, definition: nil, base_definition: nil, parent_record: nil, association_name: nil,
-                   authorization_context: nil, include_filter_cache: nil)
+                   authorization_context: nil, include_filter_cache: nil, namespace: nil)
       @record = record
-      @definition = definition || ResourceLoader.find_for_model(record.class)
+      @namespace = namespace
+      @definition = definition || ResourceLoader.find_for_model(record.class, namespace:)
       @base_definition = base_definition
       @parent_record = parent_record
       @association_name = association_name
@@ -75,12 +81,12 @@ module JSONAPI
 
     private
 
-    attr_reader :record, :definition, :parent_record, :association_name, :authorization_context
+    attr_reader :record, :definition, :parent_record, :association_name, :authorization_context, :namespace
 
     # Shared per request when the controller passes one in; a standalone
     # serializer builds its own, which still dedupes within its own walk.
     def include_filter_cache
-      @include_filter_cache ||= Serialization::IncludeFilterCache.new(authorization_context: authorization_context)
+      @include_filter_cache ||= Serialization::IncludeFilterCache.new(authorization_context:, namespace:)
     end
 
     def base_definition

data/lib/json_api/support/relationship_helpers.rb

@@ -20,7 +20,8 @@ module JSONAPI
     # Delegate to ResourceIdentifier
     # rubocop:disable Lint/UnusedMethodArgument
     def serialize_resource_identifier(
-      record, association: nil, resource_class: nil, use_instance_class: false, base_resource_class: nil
+      record, association: nil, resource_class: nil, use_instance_class: false, base_resource_class: nil,
+      namespace: nil
     )
       # rubocop:enable Lint/UnusedMethodArgument
       ResourceIdentifier.serialize_identifier(
@@ -28,6 +29,7 @@ module JSONAPI
         association:,
         definition: resource_class,
         use_instance_class:,
+        namespace:,
       )
     end
 

data/lib/json_api/support/resource_identifier.rb

@@ -4,10 +4,10 @@ module JSONAPI
   module ResourceIdentifier
     module_function
 
-    def serialize_identifier(record, association:, definition:, use_instance_class: false)
+    def serialize_identifier(record, association:, definition:, use_instance_class: false, namespace: nil)
       model_class = determine_model_class(record, association:, definition:,
                                                   use_instance_class:,)
-      related_definition = JSONAPI::ResourceLoader.find_for_model(model_class)
+      related_definition = JSONAPI::ResourceLoader.find_for_model(model_class, namespace:)
       related_type = TypeConversion.resource_type_name(related_definition)
 
       { type: related_type, id: record.id.to_s }

data/lib/json_api/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JSONAPI
-  VERSION = "3.8.1"
+  VERSION = "3.8.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jpie
 version: !ruby/object:Gem::Version
-  version: 3.8.1
+  version: 3.8.3
 platform: ruby
 authors:
 - Emil Kampp