jpie 3.7.0 → 3.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7afd23e7e9ffb26be73d59ec5776b05d0a1375edc172c8faf8ee8675c1a9e681
-  data.tar.gz: d0b2ac2e8bb3035829524faabc24d2eb787cb0f716e66e3f008043b42a3c31fb
+  metadata.gz: d9e7099c27c6aec0de41a095baa563dbc63eb934b44ab8195a9e3a51f5152c4e
+  data.tar.gz: 86ee7fbdc3cf8414d9829bbf4f42ac7e016603f8a884a0b674d8e9b869cf1b8d
 SHA512:
-  metadata.gz: de7034c8a695bb8a27501f8c00129a8b4465c3ac7963da3a3327c634b5c85064b29dfbd232841a27a84e15c1b2ef477e1ecf24bae4752ab704f8b76919dba806
-  data.tar.gz: b3474c65fcd26816af5f8f02766f8a52e850112919e29f14b1deff31f5bbc785bbf12dd24d331af4cc321f086f45c06d7ed47b068fd90158d3765b0eda5a631f
+  metadata.gz: a013761543aba53b56e575f8b2f51d3004d1cae53e53570bf506bd744cb2d38891e43a5188ad11ee338923aacdd5c8bc4cf107e1772f5cb73173aafb590d1859
+  data.tar.gz: 105cbbcb454083ebbfae7db54d9fbec5e76c39d3c1d1823c16b34de071abeae47e4cdf5923aadeb3224e609ee85c07712ed37651caa1122719501ac1c479ae07

data/.rubocop.yml

@@ -47,6 +47,10 @@ Metrics/BlockLength:
 
 Metrics/ParameterLists:
   CountKeywordArgs: false
+  Exclude:
+    # Seed helpers thread id pools positionally; a params object would add
+    # indirection to throwaway scaffolding.
+    - "spec/benchmarks/**/*"
 
 # Naming - allow DSL methods
 Naming/PredicatePrefix:
@@ -95,6 +99,9 @@ Lint/UnusedBlockArgument:
     # Security PoC specs configure authorization handlers via keyword lambdas
     # that intentionally ignore some of the required keyword arguments.
     - "spec/requests/regression/*_spec.rb"
+    # The benchmark suite and filter-batching specs configure the same hooks.
+    - "spec/benchmarks/**/*"
+    - "spec/jsonapi_spec/query_parameters/include_filter_batching_spec.rb"
 
 # Security PoC regression specs read as a single sequential narrative
 # (sanity check -> attack -> assert), so a handful of expectations per example
@@ -102,10 +109,61 @@ Lint/UnusedBlockArgument:
 RSpec/MultipleExpectations:
   Exclude:
     - "spec/requests/regression/*_spec.rb"
+    - "spec/benchmarks/**/*"
 
 RSpec/ExampleLength:
   Exclude:
     - "spec/requests/regression/*_spec.rb"
+    - "spec/benchmarks/**/*"
+
+# The benchmark suite reads as data tables (seed rows, scenario matrices,
+# result formatting). Splitting those methods obscures the data shapes, and
+# the suite is measurement scaffolding, not library code.
+Metrics/MethodLength:
+  Exclude:
+    - "spec/benchmarks/**/*"
+
+Metrics/AbcSize:
+  Exclude:
+    - "spec/benchmarks/**/*"
+    # Mirrors a production resource: meta computes several version lookups.
+    - "spec/dummy/app/resources/assignment_resource.rb"
+
+Metrics/ModuleLength:
+  Exclude:
+    - "spec/benchmarks/**/*"
+
+Metrics/CyclomaticComplexity:
+  Exclude:
+    - "spec/benchmarks/**/*"
+
+Metrics/PerceivedComplexity:
+  Exclude:
+    - "spec/benchmarks/**/*"
+
+Style/FormatStringToken:
+  Exclude:
+    - "spec/benchmarks/**/*"
+
+# Benchmark seeds load once per size context; per-example transactions are
+# deliberately off there.
+RSpec/BeforeAfterAll:
+  Exclude:
+    - "spec/benchmarks/**/*"
+
+RSpec/InstanceVariable:
+  Exclude:
+    - "spec/benchmarks/**/*"
+
+# Include-tree constants in the benchmark spec document the production
+# request shapes; they never leak outside the suite run.
+Lint/ConstantDefinitionInBlock:
+  Exclude:
+    - "spec/benchmarks/**/*"
+
+RSpec/LeakyConstantDeclaration:
+  Exclude:
+    - "spec/benchmarks/**/*"
 
 # RSpec - file-specific exclusions
 RSpec/DescribedClass:

data/Gemfile

@@ -11,6 +11,7 @@ group :development, :test do
   gem "appraisal", "~> 2.4"
   gem "bundler", "~> 2.0"
   gem "json_schemer", "~> 2.4"
+  gem "memory_profiler", "~> 1.1"
   gem "pundit", "~> 2.3"
   gem "rake", "~> 13.0"
   gem "rspec", "~> 3.12"

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    jpie (3.6.0)
+    jpie (3.8.1)
       actionpack (~> 8.1, >= 8.1.0)
       pg_query (>= 4)
       prosopite (>= 1)
@@ -151,6 +151,7 @@ GEM
       net-pop
       net-smtp
     marcel (1.1.0)
+    memory_profiler (1.1.0)
     mini_mime (1.1.5)
     minitest (5.26.2)
     net-imap (0.5.12)
@@ -340,6 +341,7 @@ DEPENDENCIES
   bundler (~> 2.0)
   jpie!
   json_schemer (~> 2.4)
+  memory_profiler (~> 1.1)
   pundit (~> 2.3)
   rake (~> 13.0)
   rspec (~> 3.12)

data/PERFORMANCE_BASELINE.md

@@ -1,102 +1,261 @@
-# jpie Performance Baseline
-
-This document outlines the performance metrics for key operations within the `jpie` gem, comparing the initial baseline with the results after implementing all optimizations.
-
-## Performance Comparison
-
-| Metric | Original Baseline | After Optimizations | Improvement |
-|--------|-------------------|---------------------|-------------|
-| `resource_loader_find_avg_ms` | 0.0182 | 0.0003 | **60x faster** |
-| `resource_loader_find_for_model_avg_ms` | 0.036 | 0.0003 | **120x faster** |
-| `jsonapi_object_avg_ms` | 0.0003 | 0.0001 | **3x faster** |
-| `serialize_single_user_avg_ms` | 0.2168 | 0.0982 | **2.2x faster** |
-| `serialize_10_users_avg_ms` | 1.4318 | 0.975 | **1.5x faster** |
-| `serialize_single_user_query_count` | 4 | 4 | N/A |
-| `serialize_10_users_query_count` | 40 | 40 | N/A |
-| `serialize_single_user_allocations` | 997 | 977 | **2% reduction** |
-| `serialize_10_users_allocations` | 9934 | 9716 | **2% reduction** |
-| `relationship_definitions_avg_ms` | 0.0036 | 0.0002 | **18x faster** |
-| `resource_instantiation_avg_ms` | 0.0003 | 0.0004 | Similar |
-
-## Implemented Optimizations
-
-### 1. ResourceLoader Caching (Phase 4)
-- Thread-safe caching for `find` and `find_for_model` methods
-- Eliminates repeated `constantize` calls
-- **60-120x improvement** in resource class lookups
-
-### 2. jsonapi_object Memoization (Phase 5)
-- Memoized the static JSON:API object
-- Returns frozen object to prevent mutations
-- **3x improvement** in object generation
-
-### 3. Relationship Definitions Caching (Phase 6)
-- Memoized `relationship_definitions` computation
-- Returns frozen array to prevent mutations
-- **18x improvement** in relationship metadata access
-
-### 4. Optional Count Query (Phase 7)
-- `total_count` only computed when pagination is applied
-- Avoids unnecessary COUNT queries for non-paginated requests
-- Reduces database load
-
-### 5. Eager Loading DSL (Phase 8)
-- New `eager_load` class method for resources
-- Automatically included in preloading without explicit `include` param
-- Helps eliminate N+1 queries at the resource level
-
-### 6. Preload for Serialization Hook (Phase 9)
-- New `preload_for_serialization` class method
-- Called before serialization with all records
-- Enables batch-loading of data needed by `meta` methods
-- Thread-local storage for preloaded data
-
-## Usage Examples
-
-### Eager Loading DSL
-
-```ruby
-class WorkstreamResource < ApplicationResource
-  eager_load :conversation, :owners
-
-  # These associations will be automatically eager-loaded
-  # even without an explicit ?include= param
-end
-```
+# jpie performance baseline: N+1 queries and memory bloat
+
+This document records the measured baseline for the request-level performance
+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
+`/evidence_checks` with a 45-id batch filter and files at depth 3 (~1,250
+queries).
+
+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
+top findings empirically with probe specs. Every mechanism below carries a
+measured probe result, not an estimate.
 
-### Preload for Serialization Hook
-
-```ruby
-class WorkstreamResource < ApplicationResource
-  def self.preload_for_serialization(records, context = {})
-    # Batch-load stats for all records
-    stats = Preloaders::StatsPreloader.call(records: records)
-    stats  # Store in preloaded_data for access in meta
-  end
-
-  def meta(...)
-    stats = self.class.preloaded_data[record.id] || record.loading_stats
-    super.merge(loading: stats)
-  end
-end
+## How to run
+
+```bash
+rake benchmark
 ```
 
-## Metric Interpretation
-
-- **`resource_loader_find_avg_ms`**: Average time to find a resource class by type
-- **`resource_loader_find_for_model_avg_ms`**: Average time to find a resource class by model
-- **`jsonapi_object_avg_ms`**: Average time to generate the static `jsonapi` object
-- **`serialize_single_user_avg_ms`**: Average time to serialize a single `User` record
-- **`serialize_10_users_avg_ms`**: Average time to serialize a collection of 10 `User` records
-- **`serialize_single_user_query_count`**: Number of SQL queries for single `User` serialization
-- **`serialize_10_users_query_count`**: Number of SQL queries for 10 `User` records serialization
-- **`serialize_single_user_allocations`**: Object allocations for single `User` serialization
-- **`serialize_10_users_allocations`**: Object allocations for 10 `User` records serialization
-- **`relationship_definitions_avg_ms`**: Average time to compute relationship definitions
-- **`resource_instantiation_avg_ms`**: Average time to instantiate a resource
-
-## Notes
-
-- Query counts remain the same in benchmarks as they test the serializer directly
-- Real-world N+1 reduction comes from the `eager_load` DSL and `preload_for_serialization` hook
-- Allocation reduction is modest but consistent across serialization
+This runs `spec/benchmarks/` with `PERFORMANCE=1`, prints a results table, and
+writes `tmp/request_benchmark_results.json` (per-scenario query counts, query
+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
+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).
+
+## Baseline (large dataset, sqlite, 2026-08-14)
+
+The seeds sit above the worst production reports on purpose: a 600-remark AI
+conversation, 40 editions with ~64KB document bodies, ~4KB remark bodies,
+fanout 10 on subject inspections plus link-owned inspections. The heaviest
+scenarios overshoot the observed ceilings (600MB allocated, 1,250 queries) so
+the bottleneck curves stay visible past them.
+
+| Scenario | Primary | Included | Queries | ms (median) | Alloc MB | Retained MB |
+|---|---|---|---|---|---|---|
+| assignments_full (page 10, 25 paths) | 10 | 2,701 | 782 | 1,499 | 133.9 | 14.1 |
+| assignments_full + authz hook | 10 | 2,701 | 3,403 | 2,200 | 168.2 | 14.6 |
+| assignments_single_conversation (page 1, 17 paths) | 1 | 2,191 | 1,728 | 1,376 | 147.4 | 24.6 |
+| assignments_single_conversation + authz hook | 1 | 2,191 | 4,029 | 2,079 | 176.8 | 25.0 |
+| gadgets_evidence_shape (45-id batch, 9 paths) | 45 | 1,656 | 2,550 | 1,386 | 132.3 | 8.1 |
+| assignments page 1 / 25 / 50 / 100 (fixed tree) | 1-100 | 1,317-16,382 | 345/1,502/2,702/5,102 | 634-11,148 | 60.0/257.2/466.9/884.5 | 6.9-102.1 |
+| assignments tree depth 1 / 2 / full (fixed page 10) | 10 | 67/1,470/2,701 | 129/1,294/782 | 66/639/1,499 | 8.4/64.5/133.9 | 1.7/13.7/14.1 |
+| users_deep_include (control: clean resources) | 20 | 400 | 3 | 97 | 12.0 | 1.6 |
+
+The reproduction exceeds every production report. Queries: 782 at the
+`/workstreams` page-10 shape, 2,550 at the `/evidence_checks` shape (vs 1,250
+observed), 1,728 for ONE primary record at the `/policies` shape, 5,102 at
+page 100. Memory: 884.5MB allocated at page 100 (vs ~600MB observed), 133.9MB
+at page 10. The authorization-hook variants add a narrowing Pundit-style scope
+on every model; production sits between the plain and authz numbers because
+only some models carry narrowing scopes. The control scenario shows the same
+serializer doing 400 included records in 3 queries when no mechanism below is
+active — the domain shape alone is not the problem.
+
+## Verified mechanisms
+
+### N+1 query drivers
+
+1. **Per-visit authorization re-check — FIXED** (with mechanism 2, see
+   "Optimizations landed"). The include walk runs the
+   `authorization_scope` hook once per parent record, per hop, per include path.
+   When the hook changes the scope's SQL, each visit fires one filter query.
+   Probe: 10 posts, `include=comments,comments.author`: 3 queries without a
+   hook, 73 with a narrowing hook. No memoization: 10 distinct users were
+   re-authorized 50 times. Shared prefixes multiply visits (each path re-visits
+   its whole prefix). Scaling: queries ≈ parents × path-visits.
+   Anchors: `include_filtering.rb` (`filter_loaded_records`, `narrowed?`),
+   `includes_serialization.rb`.
+   Baseline signature: 1,170× single-row authorization plucks in
+   `assignments_full_authz`.
+
+2. **Narrowing resource-default scopes re-check per visit — FIXED** (same
+   change as mechanism 1). A resource whose
+   `records` narrows the model scope (production: `MessageResource.records =
+   super.client_visible`) triggers the same per-visit re-check without any
+   authorization hook.
+   Baseline signature: 570× `SELECT remarks.id WHERE body IS NOT NULL AND id = ?`
+   in `assignments_full`; 3,270× at page 100.
+
+3. **ActiveStorage includes never preload — FIXED.** `filter_includable` kept
+   only include keys with an AR reflection; `has_many_attached :files` defines
+   `files_attachments`, not `files`, so the key dropped silently. Serialization
+   then probed attachments per record (2N+1 queries; 2,340 of the 2,550
+   queries in `gadgets_evidence_shape`). The fix maps the attachment key to
+   `{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
+   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
+   sort; the primary SELECT has no LIMIT. Not in the sample production requests,
+   but a cliff any client can trigger.
+
+### Memory drivers
+
+Measured attribution for `assignments_full` (133.9MB allocated): the top
+allocation sites are ActiveSupport inflector string churn (24.9MB, driven by
+uncached type-name inflection and `ResourceLoader` resolution per record and per
+identifier), the include walk itself (`includes_serialization.rb`, 10.9MB), and
+row materialization. At page 100 (884.5MB) the inflector alone allocates
+163MB and the include walk 68MB.
+
+1. **Shared included records serialize once per primary.** The dedupe by
+   `type-id` runs after full serialization, so a page of 50 primaries sharing
+   one included record serializes it 50 times and discards 49. Probe: the
+   shared-record request allocates 90% of what 50 distinct records allocate,
+   with 1 record in `included`. Multiplies every other per-record cost by page
+   size on shared subtrees.
+
+2. **`record.attributes` churn.** Exactly 3 fresh full-column hash
+   materializations per model-backed attribute per serialized record
+   (`model_has_attribute?` twice, value read once). Probe: 420 serialized
+   records produced 1,680 `#attributes` calls; the AR attribute machinery
+   accounts for ~21% of request allocations.
+
+3. **Uncached name resolution.** `ResourceLoader.find_for_model` and type-name
+   inflection run per record, per identifier, and per include-hop visit —
+   thousands of calls per request; the inflector is the single largest
+   allocation site in every heavy scenario.
+
+4. **Full-column AR materialization.** Fat text columns (document bodies,
+   remark bodies) load for every included record and dominate retained-during-
+   request memory; the response then holds the document again, and meta can hold
+   it a third time (production `PolicyVersionResource` serializes `html` in
+   attributes and meta; `PolicyResource#meta` adds a `preview` copy).
+
+Retained-after-request memory stays under ~102MB in every scenario (25MB
+outside the page-100 stress point): the bloat is
+transient garbage plus heap high-water marks, not a leak.
+
+### Checked and cleared
+
+The evaluation also refuted several suspicions, with measurements: pagination
+LIMIT does not break include batching (the count query costs 1); the
+`preload`-vs-`includes` decision is query-neutral; polymorphic and STI hops
+batch correctly at load time; the meta resource instance is cheap (~2MB); the
+attribute-transform dup chain never runs on GET; query tracking retains only
+per-request SQL references and is off in production.
+
+## Optimizations applied
+
+- **Name-resolution caching** (`ResourceLoader` + `TypeConversion`): memory
+  driver 3 above. Allocations drop 15-22% and median wall time drops 40-55%
+  across every scenario, with identical query counts. Page 100: 884.5MB ->
+  694.1MB and 11.1s -> 5.2s. The inflector leaves the top allocation sites;
+  the include walk is now the largest jpie-owned allocator.
+- **Shared include context** (dedupe before serialization): memory driver 1
+  above. A record reached from several primaries serializes once, not once per
+  primary. Allocations drop 4-10% on multi-primary pages (page 100: 884.5MB ->
+  797.4MB) and stay flat on single-primary scenarios, where nothing is shared.
+  Query counts are identical. Pages with heavy cross-primary overlap (many
+  primaries sharing the same reference records) gain far more: the probe case
+  of 50 primaries sharing one record cut its included-serialization work 50x.
+  These figures come from the 884.5MB baseline, before name-resolution caching
+  landed. Re-run the benchmark on top of that change for the combined number.
+
+## Reading the numbers
+
+- Query count is the primary regression metric. It transfers from sqlite to
+  postgres; wall time does not (sqlite has near-zero per-query latency, so the
+  same request is far slower against production postgres).
+- `allocated_mb` (memory_profiler) is the primary memory metric. RSS deltas are
+  indicative only.
+- The scaling scenarios pin the shape: queries and bytes grow linearly with
+  page size at a fixed tree, and with tree size at a fixed page. Cost ≈
+  parents × path-visits × per-visit mechanisms.
+
+## Optimizations landed
+
+### 1. Preload attachment includes (mechanism 3)
+
+`filter_includable` now maps an attachment include key to the association pair
+ActiveStorage defines for it, and `blobs_for` reads blobs through the loaded
+associations. Regression spec: `spec/jsonapi_spec/query_parameters/`
+`attachment_include_preload_spec.rb` pins `GET /users?include=avatar` at 3
+queries for any record count (was 2N+1).
+
+Before/after (large dataset; scenarios without attachment includes are
+query-identical, confirming no behavior change outside the mechanism):
+
+| Scenario | Queries before | Queries after | Alloc MB before | Alloc MB after |
+|---|---|---|---|---|
+| gadgets_evidence_shape | 2,550 | 146 (−94%) | 132.3 | 89.5 |
+| assignments_single_conversation | 1,728 | 330 (−81%) | 147.4 | 119.5 |
+| assignments_single_conversation + authz | 4,029 | 2,631 | 176.8 | 148.9 |
+| assignments_full (no attachment path) | 782 | 782 | 133.8 | 133.8 |
+
+The 330 remaining queries in the `/policies` shape are mostly the narrowing
+resource-scope re-check (mechanism 2) — the next target.
+
+### 2. Vet include-filter verdicts once per request (mechanisms 1 and 2)
+
+A request-scoped `IncludeFilterCache` computes each related class's filter
+scopes once, gives each record id one verdict per (class, scope kind), and is
+warmed from the already-loaded include tree: one vetting query per class
+instead of one per parent record per path visit. Pure memoization — the
+allowed set is identical, id for id; the IDOR regression specs hold
+unchanged. Regression spec: `include_filter_batching_spec.rb`.
+
+#### First recording (2026-08-14, base: the attachment-preload branch)
+
+Measured before the dedupe-included change (#66) landed on main. Kept for the
+record — the query counts still hold, the allocation figures do not.
+
+| Scenario | Queries before | Queries after | Alloc MB before | Alloc MB after |
+|---|---|---|---|---|
+| assignments_full | 782 | 153 (−80%) | 133.8 | 111.8 |
+| assignments_full + authz | 3,403 | 176 (−95%) | 168.2 | 114.0 |
+| assignments_single_conversation | 330 | 22 (−93%) | 119.5 | 102.8 |
+| assignments_single_conversation + authz | 2,631 | 34 (−99%) | 148.9 | 104.7 |
+| assignments_page_100 | 5,102 | 1,233 (−76%) | 884.5 | 741.0 |
+| gadgets_evidence_shape (no narrowed scope — control) | 146 | 146 | 89.5 | 79.2 |
+
+#### Second recording (2026-08-17, base: main at 8bff12d, after #64 and #66)
+
+Re-measured after the rebase onto main. Both columns come from one sequential
+run of `rake benchmark` on the same machine, large dataset.
+
+| Scenario | Queries before | Queries after | Alloc MB before | Alloc MB after | ms(med) before | ms(med) after |
+|---|---|---|---|---|---|---|
+| assignments_full | 782 | 153 (−80%) | 98.8 | 80.4 | 708.6 | 522.3 |
+| assignments_full + authz | 3,403 | 176 (−95%) | 133.6 | 82.8 | 1,208.1 | 473.9 |
+| assignments_single_conversation | 330 | 22 (−93%) | 92.6 | 79.6 | 534.1 | 376.4 |
+| assignments_single_conversation + authz | 2,631 | 34 (−99%) | 122.4 | 81.6 | 997.8 | 402.4 |
+| assignments_page_100 | 5,102 | 1,233 (−76%) | 632.2 | 512.3 | 4,800.1 | 3,128.2 |
+| gadgets_evidence_shape (no narrowed scope — control) | 146 | 146 | 64.9 | 57.9 | 443.6 | 340.2 |
+
+Every query count reproduces the first recording exactly, which confirms #66
+changed no query counts in these scenarios. The allocation figures dropped on
+both sides, because #66 cut allocations independently — so the earlier "before"
+column overstated the saving this change alone delivers.
+
+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).

data/README.md

@@ -532,7 +532,7 @@ end
 
 ### Resource-Level Meta
 
-Resource-level meta appears within each resource object. By default, the gem automatically includes `created_at` and `updated_at` timestamps in ISO8601 format if the model responds to these methods.
+Resource-level meta appears within each resource object. By default, the gem automatically includes `created_at` and `updated_at` timestamps if the model responds to these methods. The gem passes the raw `Time` to the JSON encoder, so Rails renders ISO8601 at the precision `ActiveSupport::JSON::Encoding.time_precision` sets — three sub-second digits by default. A timestamp you also expose as an attribute therefore reads the same in both places.
 
 You can also define custom meta in two ways:
 
@@ -578,8 +578,8 @@ The instance method has access to the model instance via `resource`. Custom meta
       "email": "john@example.com"
     },
     "meta": {
-      "created_at": "2024-01-15T10:30:00Z",
-      "updated_at": "2024-01-15T10:30:00Z",
+      "created_at": "2024-01-15T10:30:00.000Z",
+      "updated_at": "2024-01-15T10:30:00.000Z",
       "name_length": 8,
       "custom_field": "value"
     },

data/Rakefile

@@ -7,6 +7,11 @@ RSpec::Core::RakeTask.new(:spec)
 
 task default: :spec
 
+desc "Run the performance benchmark suite (writes tmp/request_benchmark_results.json)"
+task :benchmark do
+  sh({ "PERFORMANCE" => "1" }, "bundle", "exec", "rspec", "spec/benchmarks", "--format", "progress")
+end
+
 # Override release task to require OTP code
 # Usage: GEM_HOST_OTP_CODE=123456 rake release
 Rake::Task["release"].enhance do

data/lib/json_api/active_storage/serialization.rb

@@ -11,19 +11,36 @@ module JSONAPI
         attachment = record.public_send(attachment_name)
         return nil unless attachment.respond_to?(:attached?)
 
-        attachment.attached? ? serialize_attached(attachment) : empty_attachment_value(attachment)
+        blobs = blobs_for(attachment_name, record)
+        return blobs.map { |blob| serialize_blob_identifier(blob) } if attachment.is_a?(::ActiveStorage::Attached::Many)
+
+        blobs.first ? serialize_blob_identifier(blobs.first) : nil
       end
 
-      def serialize_attached(attachment)
+      # Blobs for an attachment. Reads through the ActiveStorage associations
+      # when the include preloader loaded them (zero queries); otherwise falls
+      # back to the probing reader (attached? + blobs, one query each).
+      def blobs_for(attachment_name, record)
+        attachment = record.public_send(attachment_name)
+        return [] unless attachment.respond_to?(:attached?)
+
         if attachment.is_a?(::ActiveStorage::Attached::Many)
-          return attachment.blobs.map { |blob| serialize_blob_identifier(blob) }
+          many_blobs(attachment, record.association(:"#{attachment_name}_attachments"))
+        else
+          one_blob(attachment, record.association(:"#{attachment_name}_attachment"))
         end
+      end
+
+      def many_blobs(attachment, association)
+        return association.target.filter_map(&:blob) if association.loaded?
 
-        serialize_blob_identifier(attachment.blob)
+        attachment.attached? ? attachment.blobs.to_a : []
       end
 
-      def empty_attachment_value(attachment)
-        attachment.is_a?(::ActiveStorage::Attached::Many) ? [] : nil
+      def one_blob(attachment, association)
+        return [association.target&.blob].compact if association.loaded?
+
+        attachment.attached? ? [attachment.blob].compact : []
       end
 
       def serialize_blob_identifier(blob)

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

@@ -38,7 +38,8 @@ module JSONAPI
 
         related_model_class = type_value.constantize
         related_resource_class = JSONAPI::ResourceLoader.find_for_model(related_model_class)
-        record = related_resource_class.records.find(id_value)
+        base = apply_relationship_authorization(related_resource_class.records, related_model_class)
+        record = base.find(id_value)
 
         association.collection? ? Array(record) : record
       end
@@ -52,17 +53,31 @@ module JSONAPI
       def fetch_polymorphic_has_many_through_resource_records(association)
         association_instance = @resource.association(@relationship_name)
         related_resource_class = JSONAPI::ResourceLoader.find_for_model(association.klass)
-        related_resource_class.records.merge(association_instance.scope)
+        base = apply_relationship_authorization(related_resource_class.records, association.klass)
+        association_instance.scope.merge(base)
       end
 
       def fetch_non_polymorphic_related_through_resource_records(association)
         association_instance = @resource.association(@relationship_name)
         related_resource_class = JSONAPI::ResourceLoader.find_for_model(association.klass)
-        scope = related_resource_class.records.merge(association_instance.scope)
+        base = apply_relationship_authorization(related_resource_class.records, association.klass)
+        scope = association_instance.scope.merge(base)
 
         association.collection? ? scope : scope.first
       end
 
+      # A relationships response (`/:type/:id/relationships/:rel`) lists the related
+      # records identified by linkage. Route the related base scope through the
+      # configured authorization_scope hook, exactly as the primary collection and
+      # `?include=` sideloads already do, so linkage never names a record the reader
+      # cannot fetch. No configured hook leaves the scope untouched.
+      def apply_relationship_authorization(scope, model_class)
+        handler = JSONAPI.configuration.authorization_scope
+        return scope unless handler
+
+        handler.call(controller: self, scope:, action: :index, model_class:)
+      end
+
       def serialize_related(related, association)
         return serialize_collection_relationship(related, association) if association.collection?
 

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

@@ -32,12 +32,27 @@ module JSONAPI
       def filter_includable(hash, klass)
         hash.each_with_object({}) do |(key, value), filtered|
           assoc = klass.reflect_on_association(key)
-          next unless assoc
-
-          filtered[key] = value.empty? || assoc.polymorphic? ? value : filter_includable(value, assoc.klass)
+          if assoc
+            filtered[key] = value.empty? || assoc.polymorphic? ? value : filter_includable(value, assoc.klass)
+          elsif (attachment_assoc = attachment_association_name(klass, key))
+            # An attachment include carries no AR reflection under its own name
+            # (has_many_attached :files defines files_attachments, not files).
+            # Preload the association pair ActiveStorage defines for it, so the
+            # serializer reads blobs without one probe query per record.
+            filtered[attachment_assoc] = { blob: {} }
+          end
         end
       end
 
+      def attachment_association_name(klass, key)
+        return nil unless defined?(::ActiveStorage) && klass.respond_to?(:reflect_on_attachment)
+
+        reflection = klass.reflect_on_attachment(key)
+        return nil unless reflection
+
+        reflection.macro == :has_one_attached ? :"#{key}_attachment" : :"#{key}_attachments"
+      end
+
       def preload_required?(hash, klass)
         hash.any? do |key, value|
           assoc = klass.reflect_on_association(key)

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

@@ -7,8 +7,10 @@ module JSONAPI
       include IncludePreloading
 
       def serialize_resource(resource)
-        JSONAPI::Serializer.new(resource, authorization_context: self).to_hash(
-          include: parse_include_param,
+        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,
         )
@@ -28,28 +30,68 @@ module JSONAPI
 
       private
 
+      # One IncludeContext spans the whole page, so a record reached from
+      # several primaries serializes once, not once per primary. The final
+      # type-id pass keeps the response contract: it drops the rare collision
+      # where two model classes serialize to the same type and id.
       def serialize_resources_with_includes(resources, includes, fields)
-        all_included = []
-        processed = Set.new
+        shared_context = JSONAPI::Serialization::IncludeContext.new(
+          fields: fields, included_records: [], processed: Set.new, all_includes: nil,
+        )
+        cache = build_include_filter_cache(resources, includes)
 
         data = resources.map do |r|
-          result = serialize_single(r, includes, fields)
-          collect_included(result, all_included, processed)
-          result[:data]
+          serialize_single(r, includes, fields, shared_context, cache)[:data]
         end
 
-        [data, all_included]
+        [data, dedupe_included(shared_context.included_records)]
       end
 
-      def serialize_single(resource, includes, fields)
-        JSONAPI::Serializer.new(resource, authorization_context: self).to_hash(include: includes, fields:,
-                                                                               document_meta: nil,)
+      def serialize_single(resource, includes, fields, include_context = nil, cache = nil)
+        JSONAPI::Serializer.new(resource, authorization_context: self, include_filter_cache: cache)
+          .to_hash(include: includes, fields:, document_meta: nil, include_context:)
       end
 
-      def collect_included(result, all_included, processed)
-        (result[:included] || []).each do |inc|
+      # One filter cache per request, warmed from the loaded include tree:
+      # 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)
+        includes.each do |path|
+          current = resources
+          path.split(".").each do |part|
+            current = warm_include_level(cache, current, part.to_sym)
+            break if current.empty?
+          end
+        end
+        cache
+      end
+
+      def warm_include_level(cache, records, association_name)
+        targets = records.flat_map { |record| loaded_association_targets(record, association_name) }
+        targets.group_by(&:class).each { |klass, recs| cache.warm(klass, recs.filter_map(&:id)) }
+        targets
+      end
+
+      # Attachment names carry no AR reflection, and unloaded associations go
+      # through the scoped-relation fallback instead of filtering: both skip.
+      def loaded_association_targets(record, association_name)
+        return [] unless record.class.reflect_on_association(association_name)
+
+        association = record.association(association_name)
+        return [] unless association.loaded?
+
+        target = association.target
+        target.respond_to?(:to_a) ? target.to_a.compact : Array(target).compact
+      end
+
+      def dedupe_included(included_records)
+        all_included = []
+        processed = Set.new
+        included_records.each do |inc|
           add_unique_included(inc, all_included, processed)
         end
+        all_included
       end
 
       def add_unique_included(inc, all_included, processed)

data/lib/json_api/railtie.rb

@@ -100,8 +100,13 @@ module JSONAPI
     #    before app controllers are available, causing FrozenError or NameError
     # 3. We register with reloader.to_prepare for code reloading in development
     config.after_initialize do |app|
-      # Register for code reloading in development
+      # Register for code reloading in development. Clear the name-keyed
+      # resolution caches first so reloaded classes re-resolve; applications
+      # that pre-populate ResourceLoader caches in their own to_prepare blocks
+      # run after this and re-apply their entries.
       app.reloader.to_prepare do
+        JSONAPI::ResourceLoader.reset_cache!
+        JSONAPI::TypeConversion.reset_cache!
         Railtie.setup_base_controllers
       end
 

data/lib/json_api/resources/resource_loader.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "concurrent/map"
+
 module JSONAPI
   class ResourceLoader
     class MissingResourceClass < JSONAPI::Error
@@ -16,7 +18,30 @@ module JSONAPI
       end
     end
 
+    # Resolution runs the inflector and safe_constantize on every call, and the
+    # serializer calls it once per record, per identifier, and per include-hop
+    # visit. Cache by name, never by class object, so a reloaded class cannot be
+    # retained. Only successful resolutions are cached. The railtie clears both
+    # caches on code reload.
+    @find_cache = Concurrent::Map.new
+    @model_cache = Concurrent::Map.new
+
+    def self.reset_cache!
+      @find_cache.clear
+      @model_cache.clear
+    end
+
     def self.find(resource_type, namespace: nil)
+      key = "#{namespace}|#{resource_type}|#{JSONAPI.configuration.namespace_fallback ? 1 : 0}"
+      cached = @find_cache[key]
+      return cached if cached
+
+      klass = resolve(find_candidates(resource_type, namespace)) ||
+              raise(MissingResourceClass.new(resource_type, namespace:))
+      @find_cache[key] = klass
+    end
+
+    def self.find_candidates(resource_type, namespace)
       candidates = []
 
       # Namespaced resource, e.g. "widgets" with namespace "api/v1" → API::V1::WidgetResource
@@ -28,16 +53,24 @@ module JSONAPI
                                                 nil,)
       end
 
-      resolve(candidates) || raise(MissingResourceClass.new(resource_type, namespace:))
+      candidates
     end
 
     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}"
+      cached = @model_cache[key]
+      return cached if cached
+
       effective_namespace = namespace || extract_namespace_from_model(model_class)
       candidates = model_candidates(model_class, effective_namespace)
 
-      resolve(candidates) || raise(MissingResourceClass.new(model_class.name, namespace: effective_namespace))
+      klass = resolve(candidates) ||
+              raise(MissingResourceClass.new(model_class.name, namespace: effective_namespace))
+      @model_cache[key] = klass
     end
 
     def self.build_resource_class_name(resource_type, namespace)

data/lib/json_api/routing.rb

@@ -8,6 +8,7 @@ module JSONAPI
       controller ||= detect_controller(resource_name, namespace)
       defaults = build_jsonapi_defaults(defaults, resource_name, namespace)
       options[:only] = :index if sti
+      options = without_form_actions(options)
 
       JSONAPI::ResourceLoader.find(resource_name, namespace:)
       define_resource_routes(resource, controller, defaults, options, &)
@@ -20,6 +21,15 @@ module JSONAPI
 
     private
 
+    # `new` and `edit` render the HTML forms of a scaffold. A JSON:API endpoint
+    # answers neither, so the routes only pad the route table and any document
+    # generated from it. A caller that names `only:` keeps full control.
+    def without_form_actions(options)
+      return options if options.key?(:only)
+
+      options.merge(except: Array(options[:except]) | %i[new edit])
+    end
+
     def extract_namespace_from_scope
       @scope[:module]&.to_s.presence
     end

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

@@ -3,51 +3,17 @@
 module JSONAPI
   module Serialization
     module IncludeFiltering
+      # When the authorization_scope hook or the resource's records scope
+      # narrows the relation, the eager-loaded set — preloaded through
+      # acts_as_tenant alone — must be re-checked against the narrowed scope,
+      # so a relationship never surfaces a record the related endpoint
+      # denies. The request-scoped cache memoizes the scopes and the per-id
+      # verdicts, so each record is vetted at most once per request.
       def filter_loaded_records(association, related_klass)
         loaded_array = association.target.respond_to?(:to_a) ? association.target.to_a : Array(association.target)
         return [] if loaded_array.empty?
 
-        base_scope = ResourceLoader.find_for_model(related_klass).records
-        authorized_scope = apply_include_authorization(base_scope, related_klass)
-
-        # When the authorization_scope hook narrows the relation (joins/subqueries a
-        # where-hash can't express), the eager-loaded set — preloaded through acts_as_tenant
-        # alone — must be re-checked against the authorized scope in the database, so a
-        # relationship never surfaces a record the related endpoint denies. An unchanged
-        # scope keeps the in-memory, query-free records-only filtering.
-        return filter_by_query(loaded_array, authorized_scope) if narrowed?(base_scope, authorized_scope)
-        return loaded_array if base_scope.where_clause.empty?
-
-        filter_by_where_hash(loaded_array, base_scope, related_klass)
-      end
-
-      def narrowed?(base_scope, authorized_scope)
-        authorized_scope.to_sql != base_scope.to_sql
-      end
-
-      def filter_by_where_hash(loaded_array, resource_scope, related_klass)
-        hash = where_values_hash_for_scope(resource_scope, related_klass)
-        return filter_by_query(loaded_array, resource_scope) if hash.blank?
-
-        loaded_array.select { |r| record_matches_where_hash?(r, hash) }
-      end
-
-      def where_values_hash_for_scope(resource_scope, related_klass)
-        resource_scope.where_values_hash(related_klass.table_name)
-      rescue StandardError
-        {}
-      end
-
-      def record_matches_where_hash?(record, hash)
-        hash.all? do |attr, val|
-          r_val = record.read_attribute(attr)
-          val.is_a?(Array) ? val.include?(r_val) : r_val == val
-        end
-      end
-
-      def filter_by_query(loaded_array, resource_scope)
-        valid_ids = resource_scope.where(id: loaded_array.filter_map(&:id)).pluck(:id).to_set
-        loaded_array.select { |r| valid_ids.include?(r.id) }
+        include_filter_cache.filter(loaded_array, related_klass)
       end
     end
   end

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

@@ -13,22 +13,18 @@ module JSONAPI
       include IncludePathHelpers
       include IncludeFiltering
 
-      def serialize_included(includes, fields = {})
+      def serialize_included(includes, fields = {}, context: nil)
         all_includes = normalize_include_paths(includes)
-        return [] if all_includes.empty?
+        return context&.included_records || [] if all_includes.empty?
 
-        ctx = build_include_context(fields, all_includes)
+        ctx = context || build_include_context(fields, all_includes)
+        ctx.all_includes ||= all_includes
         all_includes.each { |path| serialize_include_path(record, path, ctx, path_from_root: "") }
         ctx.included_records
       end
 
       def build_include_context(fields, all_includes)
-        IncludeContext.new(
-          fields: fields,
-          included_records: [],
-          processed: Set.new,
-          all_includes: all_includes,
-        )
+        IncludeContext.new(fields:, included_records: [], processed: Set.new, all_includes:)
       end
 
       private
@@ -116,11 +112,7 @@ module JSONAPI
       end
 
       def get_active_storage_records(current_record, association_name)
-        attachment = current_record.public_send(association_name)
-        return [] unless attachment.respond_to?(:attached?) && attachment.attached?
-        return attachment.blobs.to_a if attachment.is_a?(::ActiveStorage::Attached::Many)
-
-        [attachment.blob].compact
+        JSONAPI::ActiveStorage::Serialization.blobs_for(association_name, current_record)
       end
 
       def serialize_and_process_record(related_record, path_to_record, ctx, parent_record: nil, association_name: nil)
@@ -128,7 +120,7 @@ module JSONAPI
 
         requested = include_paths_to_relationship_names(ctx.all_includes, path_to_record)
         serializer = self.class.new(related_record, parent_record:, association_name:,
-                                                    authorization_context:,)
+                                                    authorization_context:, include_filter_cache:,)
         ctx.included_records << serializer.serialize_record(ctx.fields, requested_relationships: requested)
         ctx.processed.add(build_record_key(related_record))
       end

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

@@ -44,16 +44,19 @@ module JSONAPI
 
       def default_timestamp_meta
         {}.tap do |meta|
-          meta[:created_at] = format_timestamp(:created_at)
-          meta[:updated_at] = format_timestamp(:updated_at)
+          meta[:created_at] = timestamp(:created_at)
+          meta[:updated_at] = timestamp(:updated_at)
         end.compact
       end
 
-      def format_timestamp(attr)
+      # Returns the raw Time so the JSON encoder formats it. Formatting here with
+      # `iso8601` drops the sub-second digits the encoder keeps, which puts two
+      # spellings of one instant in a single document whenever a resource also
+      # exposes the timestamp as an attribute.
+      def timestamp(attr)
         return unless record.respond_to?(attr)
 
-        value = record.public_send(attr)
-        value&.iso8601
+        record.public_send(attr)
       end
     end
   end

data/lib/json_api/serialization/include_filter_cache.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module Serialization
+    # Request-scoped memoization for include filtering.
+    #
+    # The include walk re-checks the related resource's scope (and the
+    # authorization hook) against the loaded records once per parent record,
+    # per hop, per include path. Within one request those verdicts cannot
+    # change: the scopes are functions of the related class and the
+    # controller. So compute each class's filter data once, and vet each
+    # record id at most once. Pure memoization — the allowed set is
+    # identical, id for id, to the per-visit filtering it replaces.
+    class IncludeFilterCache
+      Entry = Struct.new(:base_scope, :authorized_scope, :narrowed, :where_clause_empty, :where_hash,
+                         keyword_init: true,)
+
+      def initialize(authorization_context: nil)
+        @authorization_context = authorization_context
+        @entries = {}
+        @verdicts = {}
+      end
+
+      # Filters loaded records with the same rules as the per-visit filtering:
+      # a narrowed authorization scope vets ids in the database; a resource
+      # scope with no where clause keeps everything; a where-hash-expressible
+      # scope matches in memory; anything else vets ids in the database
+      # against the resource scope.
+      def filter(records, klass)
+        entry = entry_for(klass)
+        return filter_by_ids(records, klass, :authorized, entry.authorized_scope) if entry.narrowed
+        return records if entry.where_clause_empty
+        return filter_by_ids(records, klass, :base, entry.base_scope) if entry.where_hash.blank?
+
+        records.select { |record| matches_where_hash?(record, entry.where_hash) }
+      end
+
+      # Vets ids ahead of the walk, one query per class, so the per-visit
+      # checks answer from memory. Safe to skip: #filter queries lazily.
+      def warm(klass, ids)
+        entry = entry_for(klass)
+        if entry.narrowed
+          vet_ids(klass, :authorized, entry.authorized_scope, ids)
+        elsif !entry.where_clause_empty && entry.where_hash.blank?
+          vet_ids(klass, :base, entry.base_scope, ids)
+        end
+      end
+
+      private
+
+      def entry_for(klass)
+        @entries[klass] ||= build_entry(klass)
+      end
+
+      def build_entry(klass)
+        base_scope = ResourceLoader.find_for_model(klass).records
+        authorized_scope = apply_authorization(base_scope, klass)
+        Entry.new(
+          base_scope: base_scope,
+          authorized_scope: authorized_scope,
+          narrowed: authorized_scope.to_sql != base_scope.to_sql,
+          where_clause_empty: base_scope.where_clause.empty?,
+          where_hash: where_hash_for(base_scope, klass),
+        )
+      end
+
+      # Mirrors the serializer's include authorization: no context (serializer
+      # used outside a request) or no configured hook leaves the scope untouched.
+      def apply_authorization(scope, klass)
+        return scope unless @authorization_context
+
+        handler = JSONAPI.configuration.authorization_scope
+        return scope unless handler
+
+        handler.call(controller: @authorization_context, scope:, action: :index, model_class: klass)
+      end
+
+      def where_hash_for(scope, klass)
+        scope.where_values_hash(klass.table_name)
+      rescue StandardError
+        {}
+      end
+
+      def matches_where_hash?(record, hash)
+        hash.all? do |attr, val|
+          r_val = record.read_attribute(attr)
+          val.is_a?(Array) ? val.include?(r_val) : r_val == val
+        end
+      end
+
+      def filter_by_ids(records, klass, kind, scope)
+        allowed = vet_ids(klass, kind, scope, records.filter_map(&:id))
+        records.select { |record| allowed.include?(record.id) }
+      end
+
+      # One verdict per id per (class, scope kind). Queries only ids that have
+      # no verdict yet; repeats answer from memory.
+      def vet_ids(klass, kind, scope, ids)
+        verdicts = (@verdicts[[klass, kind]] ||= {})
+        record_new_verdicts(verdicts, scope, ids)
+        ids.each_with_object(Set.new) { |id, set| set << id if verdicts[id] }
+      end
+
+      def record_new_verdicts(verdicts, scope, ids)
+        unseen = ids.reject { |id| verdicts.key?(id) }
+        return if unseen.empty?
+
+        valid = scope.where(id: unseen).pluck(:id).to_set
+        unseen.each { |id| verdicts[id] = valid.include?(id) }
+      end
+    end
+  end
+end

data/lib/json_api/serialization/serializer.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "include_filter_cache"
 require_relative "concerns/attributes_serialization"
 require_relative "concerns/relationships_serialization"
 require_relative "concerns/links_serialization"
@@ -35,23 +36,28 @@ module JSONAPI
     end
 
     def initialize(record, definition: nil, base_definition: nil, parent_record: nil, association_name: nil,
-                   authorization_context: nil)
+                   authorization_context: nil, include_filter_cache: nil)
       @record = record
       @definition = definition || ResourceLoader.find_for_model(record.class)
       @base_definition = base_definition
       @parent_record = parent_record
       @association_name = association_name
       @authorization_context = authorization_context
+      @include_filter_cache = include_filter_cache
       @sti_subclass = nil
     end
 
-    def to_hash(include: [], fields: {}, document_meta: nil)
+    # include_context shares one IncludeContext across a whole collection: a
+    # record reached from several primaries then serializes once instead of
+    # once per primary. Callers that pass it read the accumulated records from
+    # the context, not from each result's :included.
+    def to_hash(include: [], fields: {}, document_meta: nil, include_context: nil)
       include_paths = normalize_include_paths(include)
       top_level_relationships = include_paths_to_relationship_names(include_paths, "")
       {
         jsonapi: jsonapi_object,
         data: serialize_record(fields, requested_relationships: top_level_relationships),
-        included: serialize_included(include_paths, fields),
+        included: serialize_included(include_paths, fields, context: include_context),
         meta: document_meta,
       }.compact
     end
@@ -71,6 +77,12 @@ module JSONAPI
 
     attr_reader :record, :definition, :parent_record, :association_name, :authorization_context
 
+    # 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)
+    end
+
     def base_definition
       @base_definition ||= definition
     end

data/lib/json_api/support/type_conversion.rb

@@ -1,7 +1,23 @@
 # frozen_string_literal: true
 
+require "concurrent/map"
+
 module JSONAPI
   module TypeConversion
+    # Type names derive only from a class name plus a resolved format, so the
+    # serializer re-computes identical strings once per record and per
+    # relationship identifier. Cache frozen results keyed by name and format.
+    # The railtie clears the cache on code reload.
+    @type_name_cache = Concurrent::Map.new
+
+    def self.reset_cache!
+      @type_name_cache.clear
+    end
+
+    def self.type_name_cache
+      @type_name_cache
+    end
+
     module_function
 
     def type_to_class_name(type, namespace: nil)
@@ -19,18 +35,20 @@ module JSONAPI
 
     def model_type_name(model_class, format: nil)
       format ||= JSONAPI.configuration.namespace_type_format
+      name = model_class.name
+      return format_type_name(name.underscore.pluralize, format) if name.nil?
 
-      full_name = model_class.name.underscore.pluralize
-
-      format_type_name(full_name, format)
+      cache = TypeConversion.type_name_cache
+      cache["m|#{name}|#{format}"] ||= format_type_name(name.underscore.pluralize, format).freeze
     end
 
     def resource_type_name(definition_class, format: nil)
       format ||= resolve_type_format(definition_class)
+      name = definition_class.name
+      return format_type_name(name.sub(/Resource$/, "").underscore.pluralize, format) if name.nil?
 
-      full_name = definition_class.name.sub(/Resource$/, "").underscore.pluralize
-
-      format_type_name(full_name, format)
+      cache = TypeConversion.type_name_cache
+      cache["r|#{name}|#{format}"] ||= format_type_name(name.sub(/Resource$/, "").underscore.pluralize, format).freeze
     end
 
     def format_type_name(full_name, format)

data/lib/json_api/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jpie
 version: !ruby/object:Gem::Version
-  version: 3.7.0
+  version: 3.8.1
 platform: ruby
 authors:
 - Emil Kampp
@@ -166,6 +166,7 @@ files:
 - lib/json_api/serialization/concerns/relationships_deserialization.rb
 - lib/json_api/serialization/concerns/relationships_serialization.rb
 - lib/json_api/serialization/deserializer.rb
+- lib/json_api/serialization/include_filter_cache.rb
 - lib/json_api/serialization/include_path_helpers.rb
 - lib/json_api/serialization/serializer.rb
 - lib/json_api/support/active_storage_support.rb