jpie 2.0.2 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1477d2959b9a77a44758b503d4ef674cc72c8bc024fc533673ed699768e2e5a7
-  data.tar.gz: 0db30ba17f5bc3d70f1a531062fc0162ba3bcfe9347c5ec48aebcc1b796ba3a9
+  metadata.gz: b40ba16f3f137fa6f71b5f03a5aae566168c602ecab473c8804991a5b37ed70f
+  data.tar.gz: ea9ba44be05ef07e7306ff0772377277f8f25eab9c199fbe2d3f7be7fc2477ac
 SHA512:
-  metadata.gz: d927ad5ed8efe663829590f423b7f940578afa76a15d0e4ac64cbef89b615a57a6eaa8d4d46140cffe399e4b7c1a067f8e7d1d8a19981b037f0d9bee9f29f050
-  data.tar.gz: 1d9ca2c4e17a36c220a78d92bbdd9014cd924add0c3d194378fabdb5037bdc0be54461f05ca9a33bf5163ea6b68d7e36b052a6221c20cc9aed6b74d2445e15b1
+  metadata.gz: 216f53ac57192799de8c9864b72d19da9c9284600c4e6b5807ef3c1aca501986411a5a110cfd5ae862066ab033c9b8d85002cb1a1c5a9232129221d2228356d0
+  data.tar.gz: d59596b504c0c69d9783ab590fdf70053ee7728def4ecc38902cb32f70d6313d81bfda425307bb8e0673e47daa808829df37e163cfe97c12767307ab29515ee9

data/.claude/skills/nasa-power-of-ten-ruby/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: NASA Power of Ten (Ruby/Rails)
+description: NASA Power of Ten rules that are highly or partially relevant in modern Ruby/Rails. Use when reviewing or writing Ruby/Rails code for method length, scope of data, return values, assertions, control flow, loop bounds, and deep chains. Rules 3 and 8 (heap allocation, preprocessor) are not applicable.
+---
+
+# NASA Power of Ten (Ruby/Rails)
+
+Use this skill when reviewing or writing Ruby/Rails code for the NASA Power of Ten rules that are **highly** or **partially** relevant. Ignore rules 3 and 8 (heap allocation, preprocessor); treat the rest as below.
+
+---
+
+## Highly relevant
+
+### 4. Limit function length (~60 lines)
+
+- Keep methods short enough to fit on one "page" (~60 lines).
+- Extract steps into private helpers or small service methods.
+- Long methods are a common source of bugs; RuboCop and Rails style favour short methods.
+
+### 5. Assertions / validate assumptions (intent)
+
+- Validate preconditions at entry (e.g. required args, presence).
+- Check invariants after critical steps where it matters.
+- In Rails: use validations, `bang` methods, and explicit checks; avoid silent continuation after failure.
+
+### 6. Minimize scope of data
+
+- Declare variables in the innermost block where they are needed.
+- Prefer method-local and block-local variables over instance variables.
+- Avoid global or broad shared state; keep state as local as possible.
+
+### 7. Check return values
+
+- Use the return value of non-void methods (e.g. `save`, `update`, service calls) or explicitly ignore it.
+- Do not call methods that return success/failure and then ignore the result without a comment or explicit discard (e.g. `_ = ...`).
+- Let failures surface; do not hide them by ignoring return values.
+
+---
+
+## Partially relevant
+
+### 1. Simple control flow
+
+- Prefer iteration over recursion in hot or complex paths.
+- Avoid exotic control flow (e.g. continuations, complex throw/catch) in normal app code.
+- Recursion is acceptable when depth is naturally bounded (e.g. tree walk with limited depth).
+
+### 2. Fixed loop bounds
+
+- For loops that could run over unbounded or very large data (e.g. background jobs, batch processing), use a maximum iteration count or limit.
+- Prefer iterating over bounded collections or ranges; if using `while`/`loop`, add an explicit cap and break.
+
+### 9. Limit deep dereference / long chains
+
+- Avoid long method chains (e.g. `a.b.c.d.e`) that are brittle (nil, N+1, unclear ownership).
+- Prefer one or two steps and named intermediate variables.
+- Avoid dynamic dispatch (e.g. `send`) in critical paths unless simple and well-defined.
+
+---
+
+## Summary
+
+| Rule | Relevance   | Focus |
+|------|-------------|--------|
+| 4    | High        | Short methods; extract helpers. |
+| 5    | High (intent) | Validations; explicit checks. |
+| 6    | High        | Smallest scope; locals over instance/global. |
+| 7    | High        | Use or explicitly ignore return values. |
+| 1    | Partial     | Iteration over recursion; no exotic control flow. |
+| 2    | Partial     | Bounded loops in jobs/large data. |
+| 9    | Partial     | Short chains; named intermediates. |

data/.claude/skills/root-cause-analysis/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: Root Cause Analysis
+description: Systematic investigation to find the true underlying cause of a problem before applying fixes. Use when debugging test or gem behaviour failures, investigating serialization or request/response errors, or when a fix might only address symptoms. Covers problem definition (observable symptom only), evidence gathering, 5 Whys / Fishbone, verification (would fixing this prevent it?), and red flags that indicate skipping investigation. Do NOT use for routine implementation steps or when the cause is already known and verified.
+---
+
+# Root Cause Analysis
+
+**Do not treat symptoms—find and fix the root cause.** Before applying a fix, verify you understand why the failure occurs. Symptom fixes mask underlying issues and waste time.
+
+## When to use this skill
+
+- Debugging RSpec or gem integration failures, or serialization/request errors
+- Investigating "why did X break?" or "why does this spec fail?"
+- Before applying a fix when the cause is unclear or multiple hypotheses exist
+- When the user asks for root cause analysis or systematic debugging
+
+Do NOT use when the cause is already known and verified, or for routine implementation with no failure under investigation.
+
+## Core principle
+
+**Find root cause before attempting fixes.** Quick patches mask underlying issues. If you are trying fixes without understanding why they might work, you are guessing—stop and investigate.
+
+## Problem definition (observable symptom only)
+
+Define the problem in terms of **what is observed**, not assumed cause:
+
+- **What:** Observable symptom (e.g. "RSpec fails with NoMethodError", "JSON:API response missing attribute")
+- **Where:** Class, file, or endpoint affected
+- **When:** Timeline, frequency, or trigger (e.g. "after adding filter X", "only with include Y")
+- **Impact:** What is affected (e.g. "all resource specs", "serialization for type Z")
+
+## Evidence gathering
+
+Gather facts before concluding. Prefer:
+
+- Full error message and stack trace
+- Reproduction steps (exact test or request that fails)
+- Recent changes (git log, new options, caller expectations)
+- Comparison with working cases (what is different: params, include, serializer?)
+
+Do not rely on assumptions. Evidence supports or refutes hypotheses.
+
+## Methodology and verification
+
+- **5 Whys:** State the problem; ask "why?" repeatedly until you reach a cause you can fix. **Verify:** Would fixing this prevent the issue? If not, keep investigating.
+- **One hypothesis at a time:** Form a testable hypothesis, check it with minimal change, then iterate or proceed.
+- **Phased protocol:** Investigation → pattern analysis → hypothesis and test → implementation only after root cause is identified and verified.
+
+## Red flags: you are skipping investigation
+
+| Thought or action | Reality |
+|-------------------|---------|
+| "Let me try this quick fix" | You do not understand the cause |
+| "Maybe if I add a guard here" | Guessing, not debugging |
+| "Let me try a few things" | Random changes waste time |
+
+When you notice these, stop and run through problem definition, evidence, and one hypothesis at a time.
+
+## Integration
+
+- **bias-reviewer** checks for error-masking (fix root cause, not symptom). Use this skill to *do* the investigation before the bias-reviewer runs.
+- For complex failures: consider invoking the **systematic-debugging** sub-agent, which enforces this protocol and returns a diagnosis before any fix.

data/.claude/skills/skills-and-subagents/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: Skills and Sub-agents
+description: How to use and design skills and sub-agents for separation of concerns. Use when creating or updating a skill or sub-agent, when deciding whether to use a rule vs skill vs command, when delegating to a sub-agent, or when structuring a task across multiple capabilities. Covers rules vs skills vs commands, skill description (what/when/do-not), when to use sub-agents vs skills, single responsibility, and description design for discovery. Do NOT use for routine implementation that does not touch skill/agent authoring or task delegation strategy.
+---
+
+# Skills and Sub-agents
+
+Guidance for separation of concerns: when to use rules vs skills vs commands, how to scope skills and sub-agents, and when to delegate.
+
+## Rules vs skills vs commands
+
+| | Rules | Skills | Commands |
+|--|--------|--------|----------|
+| **Role** | Guide behaviour | Give a capability (workflows, procedures) | Trigger a saved prompt |
+| **Activation** | Always on, or agent decides, or file match, or manual | Agent decides or user invokes `/skill` | User invokes only (agent never auto-runs) |
+| **Content** | Flat instructions | SKILL.md + optional resources | Single Markdown prompt |
+| **Use for** | Standards, conventions, guardrails | Multi-step workflows, domain knowledge | Quick, repeatable one-shot prompts |
+
+- **Rules** — "How the agent should behave." No procedures.
+- **Skills** — "How to do something." Loaded on demand.
+- **Commands** — "A prompt you retype often." User-triggered only.
+
+Do not put multi-step procedures in rules; use a skill. Do not put always-on behaviour in a skill; use a rule.
+
+## Skill scope and description
+
+Each skill should have **one clear responsibility**. The description is used for discovery (name + description first; full content when relevant).
+
+### Description pattern: what + when + do-not
+
+- **What** — What the skill does and what it produces.
+- **When** — Trigger conditions and terms users actually use.
+- **Do NOT** — Explicit out-of-scope to avoid mis-triggering.
+
+Write in **third person**. Be concrete; vague descriptions reduce correct triggering.
+
+## When to use sub-agents vs skills
+
+| Use **sub-agents** when… | Use **skills** when… |
+|--------------------------|------------------------|
+| Context isolation (long or noisy work) | Single-purpose task |
+| Parallel workstreams | Quick, repeatable action |
+| Specialized expertise over many steps | Task completes in one shot |
+| Independent verification | No separate context needed |
+
+Sub-agents run in their own context and return a result to the parent. Skills are procedures the main agent follows.
+
+## Sub-agent responsibility
+
+- **One clear responsibility per sub-agent.** Avoid generic "helper" agents.
+- **Description drives delegation.** Include "when to use" (and "use proactively when…" if appropriate).
+- **Orchestrator vs specialist.** Parent routes and synthesizes; sub-agents execute and return a result.
+
+When creating or updating a skill or sub-agent, ensure the description clearly states what it does, when to use it, and what it does not do.

data/.cursor/agents/bias-reviewer.md

@@ -0,0 +1,58 @@
+---
+name: bias-reviewer
+description: Expert reviewer for AI code biases: add-code bias (prefer delete/reduce/DRY), defensive code (no rescue/guards, let exceptions bubble), error-masking (fix root cause), and dead code (unreachable branches, disconnected call chains). Use proactively after writing or modifying code to catch these biases before merge.
+---
+
+You are a bias-focused code reviewer. Your only job is to find four specific AI biases in code: add-code bias, defensive-code bias, error-masking bias, and dead-code bias. You are not a general code reviewer; you focus solely on these biases.
+
+## When invoked
+
+1. Run `git diff` (or equivalent) to see recent changes.
+2. Focus on the changed files and any new code paths.
+3. Apply the checklist below and report findings.
+
+## Checklist (four biases)
+
+### Add-code bias
+
+- Could this have been done by **deleting** code? (e.g. removing redundant logic, commented-out code, or dead code?)
+- Could the logic be **reduced** or simplified? (fewer branches, fewer lines, fewer abstractions?)
+- Could this be a **refactor** of existing code instead of a new layer on top?
+- Is there **duplication** that should be DRYed? (shared methods, scopes, concerns, or existing utilities?)
+
+Ask for every change: "Could this have been achieved by deleting, reducing, or refactoring instead of adding?"
+
+### Defensive-code bias
+
+- Any `rescue`, `rescue Exception`, `rescue StandardError`, try/catch, or equivalent that catches and swallows or "handles" broadly?
+- Redundant nil/valid-input guards that paper over callers passing invalid data?
+- Log-and-continue or catch-and-return-default that hides the real failure?
+
+Rule: Prefer exposing the real, upstream error. Do not add defensive rescues or guards that hide bugs. Let errors bubble so callers see the actual failure.
+
+### Error-masking bias
+
+- Does the change **fix the root cause** of a bug, or only hide the symptom? (e.g. extra checks, fallbacks, early returns, or different behavior when something is "wrong"?)
+- Are tests or callers being adjusted to "accept" a failure instead of fixing the underlying bug?
+
+Rule: Fix the root cause or let the error propagate. Do not mask errors; masking makes debugging harder and hides real problems.
+
+### Dead-code bias
+
+- **Unreachable or unlikely branches**: Is there a branch (e.g. `else`, a condition, or a case arm) that can never run or is effectively unreachable given earlier returns/raises or impossible conditions? Is there code after a guaranteed return or in a branch that is never taken in practice?
+- **Disconnected call chains**: Is part of a call chain no longer connected? (e.g. a method that is never called, a class/module that is never referenced, or a middle step that was removed so that callers now skip a layer or callees are never reached.) Trace from entry points (controllers, resources, serialization, specs) and from tests: are there methods or classes that nothing calls anymore?
+
+Rule: Remove unreachable code and reconnect or remove orphaned parts of call chains. Dead code adds noise and can mislead future changes.
+
+## Output format
+
+- Group findings by bias: **Add-code**, **Defensive-code**, **Error-masking**, **Dead-code**.
+- For each finding give: file and location, what is wrong, and a concrete suggestion (e.g. "Remove this rescue and let the exception bubble", "Replace this duplication with a call to X", or "This branch is unreachable because …; remove it or fix the condition").
+- Severity per finding:
+  - **Must fix** — Clearly violates project rules, masks bugs, or is definite dead code.
+  - **Should fix** — Likely bias; should be rechecked or simplified.
+  - **Consider** — Possible simplification or cleanup.
+
+## References
+
+You enforce code reduction bias (delete/reduce/refactor/DRY), no defensive programming (let exceptions bubble), fix root cause (no error masking), and removal of dead code (unreachable branches, disconnected call chains). Do not suggest adding defensive code or workarounds; suggest removing or simplifying so the true behavior (and true errors) are visible.

data/.cursor/agents/lint-format.md

@@ -0,0 +1,58 @@
+---
+name: lint-format
+description: Runs RuboCop on the JPie (json_api) codebase and fixes all violations by correcting the code. Never adds rubocop:disable directives, changes .rubocop.yml, or skips cops to pass. Use after writing or modifying Ruby/Rails code to ensure it meets the project's style standards.
+---
+
+You are a lint enforcement agent for the JPie project (json_api gem, Ruby 3.4 + Rails 8+). Your job is to make all code comply with the project's RuboCop configuration by **fixing the code itself** — never by disabling cops, suppressing offenses inline, or changing config files.
+
+## Rules you must never break
+
+- **Never add `# rubocop:disable`, `# rubocop:enable`, or any inline cop suppression comments.**
+- **Never modify `.rubocop.yml` or any RuboCop config file to make violations go away.**
+- **Never use `rubocop --except`, `--only`, or other flags to skip cops during the fix pass.**
+- Fix violations by correcting the code, not by silencing the tool.
+
+## When invoked
+
+1. Run `bundle exec rubocop` (check only, no auto-correct) to see all current offenses.
+2. Fix all offenses by editing the code directly. For mechanical/formatting fixes you may run `bundle exec rubocop -a` (safe auto-correct only) to handle Layout and simple Style cops, then review the remaining offenses.
+3. Re-run `bundle exec rubocop` to confirm zero offenses.
+4. If offenses remain, continue fixing until the output is clean.
+
+**Do not run `bundle exec rubocop -A` (unsafe auto-correct) without explicit user approval**, as it can make semantic changes.
+
+## How to fix common offense categories
+
+### Layout cops
+These are purely whitespace/indentation. Safe to auto-correct with `-a`.
+- Indentation, trailing whitespace, empty lines, dot position, brace spacing, etc.
+
+### Style cops
+- `Style/StringLiterals`: use double quotes (`"`) — the project enforces `double_quotes`.
+- `Style/FrozenStringLiteralComment`: the project enforces `always` — keep `# frozen_string_literal: true` at the top of Ruby files.
+- `Style/HashSyntax`: use shorthand or consistent syntax per `.rubocop.yml` (`EnforcedShorthandSyntax: either`).
+- `Style/TrailingComma*`: the project uses `consistent_comma` for multiline arrays/hashes/arguments — add trailing commas.
+- `Style/RedundantReturn`: remove explicit `return` at the end of a method.
+- `Style/RedundantSelf`: remove unnecessary `self.` prefix.
+- Other Style cops: fix the code to match the enforced style; do not disable the cop.
+
+### Lint cops
+- `Lint/UselessAssignment`: remove or use the variable.
+- `Lint/UnreachableCode`: remove the dead code.
+- `Lint/Debugger`: remove any `byebug`, `binding.pry`, `debugger` calls.
+- Other Lint cops: fix the underlying issue.
+
+### RSpec cops
+- `RSpec/ExampleLength`: shorten the example; extract shared setup into `let`/`before`.
+- `RSpec/MultipleExpectations`: split into focused examples or use `aggregate_failures`.
+- Fix the spec logic; do not exclude files from the cop unless they are already listed in `.rubocop.yml`.
+
+### Rails cops
+- Fix the Rails-specific issue (e.g. use `pluck` where appropriate, correct `find`/`find_by!` usage, etc.).
+
+## Output format
+
+After each fix pass, report:
+- Which files were changed and what was fixed.
+- The final output of `bundle exec rubocop` (offense count and summary line).
+- Confirm zero offenses, or explain any remaining offense that requires a human decision (e.g. a genuine design choice that conflicts with a cop — in that case, surface it and let the developer decide, do not silently disable).

data/.cursor/agents/nasa-power-of-ten-reviewer.md

@@ -0,0 +1,38 @@
+---
+name: nasa-power-of-ten-reviewer
+description: Code reviewer for NASA Power of Ten rules relevant to Ruby/Rails. Checks method length, scope of data, return values, assertions, control flow, loop bounds, and deep chains. Use for PR review, refactor planning, or auditing a file/namespace.
+---
+
+You are a NASA Power of Ten code reviewer for Ruby and Rails. Your only job is to check code against the NASA Power of Ten rules that are **highly** or **partially** relevant in modern Ruby/Rails. You are not a general code reviewer; you focus solely on these rules.
+
+## When invoked
+
+1. **Read the NASA Power of Ten skill** (`.claude/skills/nasa-power-of-ten-ruby/SKILL.md`) before reviewing.
+2. **Review only** the files or diff provided; do not change code unless the user explicitly asks for edits.
+3. For each rule (4, 5, 6, 7, 1, 2, 9), report:
+   - **Compliant** / **Violation** / **N/A**
+   - File and line(s) or method name where relevant.
+   - One-line suggestion for violations.
+4. **Prioritise** violations of highly relevant rules (4, 5, 6, 7) over partially relevant (1, 2, 9).
+5. Keep the report concise: bullet list per rule, then a short summary.
+
+## Rules checked
+
+- **4** — Method length (~60 lines); extract helpers.
+- **5** — Assertions / validate assumptions (preconditions, invariants).
+- **6** — Minimize scope of data (locals, block scope).
+- **7** — Check return values; use or explicitly ignore.
+- **1** — Simple control flow (iteration over recursion; no exotic control flow).
+- **2** — Fixed loop bounds for jobs/unbounded loops.
+- **9** — Limit deep chains; named intermediates.
+
+## Output format
+
+- Start with: **## NASA Power of Ten review**
+- One subsection per rule checked (e.g. **### 4. Method length**).
+- For each: Compliant / Violation / N/A, plus file/location and (for violations) one-line suggestion.
+- End with **### Summary**: compliant count, violation count, top 1–3 recommended fixes.
+
+## References
+
+The skill at `.claude/skills/nasa-power-of-ten-ruby/SKILL.md` is the source of truth for what each rule means in Ruby/Rails. Do not suggest adding defensive code or workarounds; suggest changes that align with the rules (shorter methods, smaller scope, checked return values, bounded loops, shorter chains).

data/.cursor/agents/systematic-debugging.md

@@ -0,0 +1,52 @@
+---
+name: systematic-debugging
+description: Enforces root-cause-before-fix debugging for the json_api (JPie) gem. Use when investigating test or serialization/request failures where the cause is unclear. Runs the four-phase protocol (investigation, pattern analysis, hypothesis and test, recommendation) and returns a diagnosis and minimal fix recommendation. Do NOT use for simple one-line fixes or when the root cause is already known and verified.
+---
+
+You are a systematic debugging specialist for the json_api gem (JPie). Your only job is to find the root cause of a failure before any fix is applied. You do not implement fixes until you have identified and verified the root cause. You return your diagnosis and a minimal fix recommendation to the parent agent.
+
+## Core rule
+
+**ALWAYS find root cause before attempting fixes.** Symptom fixes are failure. Quick patches mask underlying issues. If you are trying fixes without understanding why they might work, you are guessing—stop and investigate.
+
+## Four phases (complete in order)
+
+### Phase 1: Investigation
+
+- Read the full error (message, type, stack trace).
+- Reproduce consistently (exact test or request that fails).
+- Review recent changes (git log, options, caller expectations).
+- Gather evidence (params, include, serializer path, input data).
+- Trace backwards from the failure to where correct behaviour diverges.
+
+### Phase 2: Pattern analysis
+
+- Find similar working code or passing specs.
+- Identify what is different (params, include, resource type, configuration).
+
+### Phase 3: Hypothesis and test
+
+- Form a single, testable hypothesis.
+- Design a minimal check to confirm or refute it.
+- Observe; iterate or proceed to Phase 4.
+
+### Phase 4: Recommendation
+
+Only after root cause is identified and verified.
+
+- Summarize: root cause, evidence, and why fixing it prevents the failure.
+- Recommend a minimal fix. Do not implement multiple fixes; the parent may implement.
+
+## Output format
+
+1. **Problem** — Observable symptom (What/Where/When/Impact).
+2. **Evidence** — What you gathered.
+3. **Root cause** — The underlying cause and why it explains the symptom.
+4. **Verification** — How you confirmed.
+5. **Recommendation** — Minimal fix for the parent to apply.
+
+If you cannot reproduce or evidence is insufficient, say so and list what is needed.
+
+## References
+
+Read the **root-cause-analysis** skill (`.claude/skills/root-cause-analysis/SKILL.md`) for problem definition, evidence gathering, 5 Whys, and verification. This sub-agent enforces that protocol and returns a structured diagnosis and fix recommendation to the parent.

data/Gemfile.lock

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

data/README.md

@@ -15,6 +15,7 @@ A Rails 8+ gem that provides JSON:API compliant routing DSL and generic JSON:API
 - Content negotiation with Accept and Content-Type headers
 - Support for polymorphic and STI relationships
 - Namespace support for API versioning and modular organization
+- Sideposting: create primary and related resources in one request using `included` and local identifiers (`lid`)
 
 ## Installation
 
@@ -1191,6 +1192,119 @@ The gem validates relationship data:
 - Invalid polymorphic type (class doesn't exist) returns `400 Bad Request`
 - Attempting to unset linkage that cannot be nullified (e.g., foreign key has NOT NULL constraint) returns `400 Bad Request`
 
+## Sideposting
+
+Sideposting lets you create a primary resource and related resources that do not yet exist in a single POST request. The client sends the primary resource in `data` and full resource objects in `included`. Relationships on the primary can reference included resources by **local identifier** (`lid`) instead of `id`. By default the server creates the **primary** first, then creates included resources and updates the primary with resolved relationship ids (**primary-first**). You can optionally use **included-first** (create included resources first, then the primary) via a controller macro.
+
+This follows the JSON:API 1.1 [Local Identity](https://jsonapi.org/format/1.1/#document-resource-object-identification) convention: `lid` is a client-chosen temporary identifier for the request only; it is not stored.
+
+### Sidepost order
+
+Controllers use **primary-first** by default: the primary resource is saved first (without lid-based relationships), then included resources are created, then the primary is updated with the resolved relationship ids. This supports flows such as signup where the user must exist before the account links to them.
+
+To use the legacy **included-first** order (create included resources first, then the primary), set the macro in your controller:
+
+```ruby
+class SomeController < JSONAPI::ResourcesController
+  sidepost_order :included_first
+end
+```
+
+Valid values are `:primary_first` (default) and `:included_first`. Any other value raises `ArgumentError` at class load time.
+
+### Custom create strategy
+
+For included resources, the default creation is `model_class.new(params).save`. You can override this per resource type by defining a class method **`sidepost_create`** on the resource class. It receives `params:` (the deserialized model attributes hash) and `controller:` and must return a persisted record or `nil`. If it returns a record, that record is used and the default create path is skipped; if it returns `nil`, the default create runs.
+
+Example: use a service to create the related resource instead of a bare `new`/`save`:
+
+```ruby
+class AccountResource < JSONAPI::Resource
+  def self.sidepost_create(params:, controller:)
+    CreateAccountService.call(
+      name: params["name"],
+      domain: params["domain"],
+      creator: Current.user
+    ).account
+  end
+end
+```
+
+Use **primary-first** (default) plus `sidepost_create` on the related resource when the primary must exist first and the related resource needs custom creation logic.
+
+### Request format
+
+- **`data`**: The primary resource. In `relationships`, use `type` and `lid` (no `id`) to reference an item in `included`.
+- **`included`**: Array of full resource objects. Each can have `type`, `lid`, and `attributes` (and optionally `relationships` with further `lid` references). Order of creation is the order of `included`; a later item may reference an earlier item’s `lid`.
+
+Example: create a user and a new profile in one request:
+
+```http
+POST /users HTTP/1.1
+Content-Type: application/vnd.api+json
+Accept: application/vnd.api+json
+
+{
+  "data": {
+    "type": "users",
+    "attributes": {
+      "name": "Jane Doe",
+      "email": "jane@example.com"
+    },
+    "relationships": {
+      "profile": {
+        "data": { "type": "customer_profiles", "lid": "temp-profile" }
+      }
+    }
+  },
+  "included": [
+    {
+      "type": "customer_profiles",
+      "lid": "temp-profile",
+      "attributes": {
+        "company_name": "Acme Inc",
+        "industry": "Tech"
+      }
+    }
+  ]
+}
+```
+
+With the default **primary-first** order, the server creates the user first, then creates the `customer_profiles` resource and assigns it an `id`, then updates the user's `profile` relationship to point to that new profile. The `lid` `"temp-profile"` is only used to match the relationship to the included object.
+
+### Response
+
+On success the response is `201 Created` with the primary resource in `data` and the created related resources in `included`, each with a real `id`:
+
+```json
+{
+  "jsonapi": { "version": "1.1" },
+  "data": {
+    "type": "users",
+    "id": "123",
+    "attributes": { "name": "Jane Doe", "email": "jane@example.com" },
+    "relationships": {
+      "profile": { "data": { "type": "customer_profiles", "id": "456" } }
+    }
+  },
+  "included": [
+    {
+      "type": "customer_profiles",
+      "id": "456",
+      "attributes": { "company_name": "Acme Inc", "industry": "Tech" }
+    }
+  ]
+}
+```
+
+### Validation and rollback
+
+Creation runs in a single transaction. If any included resource fails validation, the entire request is rolled back: no primary or included resources are created. The response is `422 Unprocessable Entity` with errors that point to the failing included resource (e.g. `source.pointer` to the relevant `included` index or attribute).
+
+### When sideposting is used
+
+Sideposting is applied when the create request includes a top-level `included` array. If `included` is present, the controller uses the configured **sidepost order** (primary-first by default, or included-first if `sidepost_order :included_first` is set). With primary-first, it creates the primary resource first (without lid-based relationships), creates included resources, resolves `lid` references to new `id`s, updates the primary with those relationships, then returns the primary and `included` in the response. With included-first, it creates included resources first, resolves `lid`s, then creates the primary and returns it with `included`.
+
 ## Relationship Endpoint Details
 
 The gem provides dedicated endpoints for managing relationships independently of the main resource:

data/lib/json_api/controllers/concerns/controller_helpers/error_rendering.rb

@@ -43,6 +43,24 @@ module JSONAPI
         render json: { errors: }, status: :unprocessable_content
       end
 
+      def render_sidepost_validation_errors(sidepost_error)
+        errors = sidepost_validation_errors(sidepost_error)
+        render json: { errors: }, status: :unprocessable_content
+      end
+
+      def sidepost_validation_errors(sidepost_error)
+        index = sidepost_error.included_index
+        sidepost_error.record.errors.map do |error|
+          pointer = "/included/#{index}/attributes/#{error.attribute}"
+          {
+            status: "422",
+            title: "Validation Error",
+            detail: error.full_message,
+            source: { pointer: pointer },
+          }
+        end
+      end
+
       def render_parameter_not_allowed_error(error)
         error_params = error.respond_to?(:params) ? error.params : []
         detail = error_params.present? ? error_params.join(", ") : "Relationship or attribute is read-only"

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

@@ -15,6 +15,14 @@ module JSONAPI
         [hash, attachments]
       end
 
+      def prepare_create_params_from_data(sti_class, data)
+        hash = deserialize_params(:create, model_class: sti_class, data:)
+        attachments = extract_active_storage_params_from_hash(hash, sti_class)
+        clean_params(hash, attachments)
+        apply_sti_type(sti_class, hash)
+        [hash, attachments]
+      end
+
       def prepare_update_params
         hash = deserialize_params(:update)
         attachments = extract_active_storage_params_from_hash(hash, model_class)
@@ -45,6 +53,15 @@ module JSONAPI
         render json: serialize_resource(resource), status: :created, location: resource_url(resource)
       end
 
+      def save_created_with_sidepost(resource, sideposted_records)
+        raise JSONAPI::Sideposting::PrimaryValidationError, resource unless resource.save
+
+        emit_resource_event(:created, resource)
+        render json: serialize_resource_with_sidepost(resource, sideposted_records),
+               status: :created,
+               location: resource_url(resource)
+      end
+
       def save_updated(params_hash, attachments)
         return render_validation_errors(@resource) unless @resource.update(params_hash)
 

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

@@ -51,9 +51,10 @@ module JSONAPI
         JSONAPI::ParamHelpers.deep_symbolize_params(data)
       end
 
-      def deserialize_params(action = :update, model_class: nil)
+      def deserialize_params(action = :update, model_class: nil, data: nil)
         target = model_class || self.model_class
-        JSONAPI::Deserializer.new(raw_jsonapi_data, model_class: target, action:).to_model_attributes
+        payload = data.nil? ? raw_jsonapi_data : symbolize_data(data)
+        JSONAPI::Deserializer.new(payload, model_class: target, action:).to_model_attributes
       end
 
       def resource_url(resource)

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

@@ -14,6 +14,19 @@ module JSONAPI
         )
       end
 
+      def serialize_resource_with_sidepost(resource, sideposted_records)
+        result = serialize_resource(resource)
+        return result if sideposted_records.empty?
+
+        fields = parse_fields_param
+        sideposted_objects = sideposted_records.map do |rec|
+          JSONAPI::Serializer.new(rec).to_hash(include: [], fields:, document_meta: nil)[:data]
+        end
+        all_included = (result[:included] || []) + sideposted_objects
+        result[:included] = deduplicate_included(all_included)
+        result
+      end
+
       def serialize_collection(resources)
         includes = parse_include_param
         fields = parse_fields_param
@@ -59,6 +72,17 @@ module JSONAPI
         processed.add(key)
       end
 
+      def deduplicate_included(included_array)
+        processed = Set.new
+        included_array.each_with_object([]) do |inc, out|
+          key = "#{inc[:type]}-#{inc[:id]}"
+          next if processed.include?(key)
+
+          out << inc
+          processed.add(key)
+        end
+      end
+
       def build_collection_response(data, all_included)
         result = { jsonapi: JSONAPI::Serializer.jsonapi_object, data: }
         result[:included] = all_included if all_included.any?