Scope the null-padding index hint to analytics event writes

[stopachka]

An observed analytics event write scans the attribute/value index during indexed-null checks. Add a default-off primary-key hint for app 5ff3d22e-183a-4657-bd8f-e86316f983cb and its exact eight-field, single-entity batch. Different schemas, batch shapes, value kinds, and options keep normal planning. Existing app gates are unchanged.

This PR is stacked on #2911. It uses the existing hint-only SQL path, preserving parameters, writes, validation, and transaction order.

Validation: 22 PostgreSQL tests and 1,843 assertions passed across the combined scoped-write suites. Both builders preserve storage/results, UUID/date handling, no-op behavior, fallback cases, and rollback after invalid-date writes. Lint and independent review passed. Plan-only Aurora checks using synthetic values confirmed the intended index change.

Deployed and enabled for this app on September 16 at 21:39 UTC. In the following eight-minute archive window, 21 observed eight-step transactions selected the guarded branch. Their 21 parent-contained insert SQL spans averaged 17.9 ms, compared with 1,544 ms across 273 baseline spans. The stricter branch-contained subset comprised 19 SQL spans averaging 16.8 ms. No error or timeout signals appeared in the observed target cohort. The same existing server also improved from 1,557 ms to 16.9 ms per insert.

These are observed cohorts, not a controlled load test. Archive-observed transaction counts and overall database commit throughput decreased; CPU had also started declining before activation. Whole-database CPU remains variable, so the global reduction cannot be assigned entirely to this change. The per-app flag can disable this hint without a code rollback.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Advanced

Run ID: d6b4a5d8-dccf-4039-b628-7ae380d752b3

📥 Commits

Reviewing files that changed from the base of the PR and between 1bedb7c and adfaf2a.

📒 Files selected for processing (3)

• server/src/instant/db/scoped_write_plans.clj
• server/test/instant/db/analytics_events_write_plan_test.clj
• server/test/instant/db/scoped_write_plans_test.clj

Included review availability: Your plan provides up to 10 included reviews per hour; 8 remain after this review.

---

📝 Walkthrough

Walkthrough

The PR adds a measured :5ff-analytics-events scoped write plan. It validates the exact eight-attribute shape, gates selection by feature flags and options, preserves the existing A749 path, and adds query and transaction coverage for both insert builders.

Changes

Analytics events scoped write plan

Layer / File(s)	Summary
Plan contract and triple validation server/src/instant/db/scoped_write_plans.clj, server/test/instant/db/scoped_write_plans_test.clj	Defines the eight analytics-event attributes and validates entity, attribute, value, option, namespace, and schema requirements. Tests cover valid batches and fallback cases.
Scoped plan dispatch server/src/instant/db/scoped_write_plans.clj, server/test/instant/db/scoped_write_plans_test.clj	Updates null-padding-shape to select the analytics-events plan when the flag, schema, options, and triples match. The A749 path remains available.
Transaction and query coverage server/test/instant/db/analytics_events_write_plan_test.clj	Tests query hints and transaction behavior for both triple/insert-multi builders, including replays, duplicates, updates, sparse entities, invalid dates, storage, and rollback behavior.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant triple/insert-multi
  participant null-padding-shape
  participant analytics-events-triples?
  participant SQL planner
  triple/insert-multi->>null-padding-shape: provide normalized triples and options
  null-padding-shape->>analytics-events-triples?: validate the analytics-events batch
  analytics-events-triples?-->>null-padding-shape: return matching shape
  null-padding-shape->>SQL planner: apply triples_pkey index-scan hint
  SQL planner-->>triple/insert-multi: execute the analytics-events write query

Loading

Merge Risk: ⚪ Minimal · up to adfaf

The feature-gated analytics-event hint is narrowly scoped and does not leave a concrete correctness, transaction, or availability risk requiring changes before merge.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly identifies the main change: limiting the null-padding index hint to analytics event writes.
Description check	✅ Passed	The description directly explains the scoped hint, its exact gating conditions, preserved behavior, validation, and observed results. It is directly related to the changeset.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}