jpie 3.5.0 → 3.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c54015e01586dd3a4a6f14430928d231e1e6ce8f1e46a9cefa54ab7c93d45226
-  data.tar.gz: 90f24a271244366daf7ff47dd7a20a79740baf72c037b4f9ff428bd7a69bde33
+  metadata.gz: d9e7099c27c6aec0de41a095baa563dbc63eb934b44ab8195a9e3a51f5152c4e
+  data.tar.gz: 86ee7fbdc3cf8414d9829bbf4f42ac7e016603f8a884a0b674d8e9b869cf1b8d
 SHA512:
-  metadata.gz: bd1e8f0ce88654ca8c594f9b58cb4320ecfeba576d5f21062e0136737c0bbabd24a3aef94f899ad0732a7f363f9115e1e602c9079b930aa7159187b90e834a61
-  data.tar.gz: ba4d97f2a60f0b73ca1480de68cdfb05c992e2434bff55ee6569da74447788c7f1c51e7ac2047126976adca6ba1a88a9b8c4fd6e9e60a7b1cddd7aa26ac379e7
+  metadata.gz: a013761543aba53b56e575f8b2f51d3004d1cae53e53570bf506bd744cb2d38891e43a5188ad11ee338923aacdd5c8bc4cf107e1772f5cb73173aafb590d1859
+  data.tar.gz: 105cbbcb454083ebbfae7db54d9fbec5e76c39d3c1d1823c16b34de071abeae47e4cdf5923aadeb3224e609ee85c07712ed37651caa1122719501ac1c479ae07

data/.claude/skills/writing-discipline/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: writing-discipline
+description: The writing standard for all prose — chat responses, documentation, code comments, commit messages, PR descriptions, Jira and Slack posts. Use BEFORE you write any human-facing text. Enforces ASD-STE100 (Simplified Technical English) plus Orwell's six rules — active voice, short sentences, short everyday words, one instruction per sentence, no idioms, no jargon, cut every word you can.
+---
+
+# Writing discipline
+
+All prose obeys ASD-STE100 (Simplified Technical English) and Orwell's six rules of
+writing. This covers chat responses, documentation, code comments, commit messages,
+PR descriptions, and Jira and Slack posts.
+
+## ASD-STE100
+
+- Use only approved words from the STE dictionary (one word, one meaning). Technical
+  names and technical verbs of this domain are permitted.
+- Write in the active voice. Use the present tense where possible.
+- Keep sentences short: maximum 20 words in an instruction, maximum 25 words in
+  descriptive text.
+- Give one instruction per sentence. Start an instruction with the command form of
+  the verb.
+- Do not make noun clusters of more than three nouns.
+- Do not use slang, idioms, or Latin abbreviations (no "e.g.", "i.e.", "etc.", "via").
+- Use a vertical list when you give more than three facts or steps in sequence.
+- Start a warning or caution with the command, not the explanation.
+
+## Orwell's six rules
+
+1. Never use a metaphor, simile, or other figure of speech which you are used to
+   seeing in print.
+2. Never use a long word where a short one will do.
+3. If it is possible to cut a word out, always cut it out.
+4. Never use the passive where you can use the active.
+5. Never use a foreign phrase, a scientific word, or a jargon word if you can think
+   of an everyday English equivalent.
+6. Break any of these rules sooner than say anything outright barbarous.
+
+## How to apply
+
+- Draft, then cut. Remove every word that does not change the meaning.
+- Break a long sentence at "which", "and", or "but".
+- Prefer a verb to a noun cluster: write "when the job runs", not "at job execution
+  time".
+- Replace idioms with plain statements: write "this shows the cause", not "this is
+  the smoking gun".
+- Replace Latin abbreviations: write "for example", not "e.g."; name the items, or
+  write "and more", instead of "etc.".
+- Keep technical names, commands, and code identifiers as they are. The standard
+  limits prose, not identifiers.
+
+## Self-check before you send
+
+- Is every sentence inside the length limit?
+- Is every verb active?
+- Can any word go?
+- Does a reader who is not an expert know every word that is not a technical name?

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/CLAUDE.md

@@ -0,0 +1,34 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Writing standard: ASD-STE100 + Orwell's six rules
+
+All prose you write — chat responses, documentation, code comments, commit messages,
+PR descriptions, Jira and Slack posts — must obey ASD-STE100 (Simplified Technical
+English) and Orwell's six rules of writing.
+
+ASD-STE100:
+
+- Use only approved words from the STE dictionary (one word, one meaning). Technical
+  names and technical verbs of this domain are permitted.
+- Write in the active voice. Use the present tense where possible.
+- Keep sentences short: maximum 20 words in an instruction, maximum 25 words in
+  descriptive text.
+- Give one instruction per sentence. Start an instruction with the command form of
+  the verb.
+- Do not make noun clusters of more than three nouns.
+- Do not use slang, idioms, or Latin abbreviations (no "e.g.", "i.e.", "etc.", "via").
+- Use a vertical list when you give more than three facts or steps in sequence.
+- Start a warning or caution with the command, not the explanation.
+
+Orwell's six rules:
+
+1. Never use a metaphor, simile, or other figure of speech which you are used to
+   seeing in print.
+2. Never use a long word where a short one will do.
+3. If it is possible to cut a word out, always cut it out.
+4. Never use the passive where you can use the active.
+5. Never use a foreign phrase, a scientific word, or a jargon word if you can think
+   of an everyday English equivalent.
+6. Break any of these rules sooner than say anything outright barbarous.

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.1.6)
+    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)