feat: optmize evault CRUD performance by coodos · Pull Request #951 · MetaState-Prototype-Project/prototype

coodos · 2026-04-14T08:32:21Z

Description of change

Added JWKs caching to reduce latency

Issue Number

Type of change

Update (a change which updates existing functionality)

How the change has been tested

Change checklist

I have ensured that the CI Checks pass locally
I have removed any unnecessary logic
My code is well documented
I have signed my commits
My code follows the pattern of the application
I have self reviewed my code

Summary by CodeRabbit

New Features
- Webhooks now deliver the complete post-write state of updated envelopes, preventing receivers from unintentionally overwriting fields with partial data.
Bug Fixes
- Fixed rate-limiting to properly prevent further request handling after rejection.
Performance Improvements
- Added database indexing on envelope identifiers for faster lookups.
- Implemented JWKS caching with configurable TTL for token validation.
- Added performance monitoring and instrumentation across critical operations.

coderabbitai · 2026-04-14T08:32:30Z

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR introduces performance timing instrumentation, refactors database meta-envelope operations to use transactional PATCH semantics with merged payloads, adds Neo4j id-field indexes, implements JWKS caching in authentication, updates GraphQL webhooks to deliver full post-write state, and fixes rate-limiting response handling.

Changes

Database Refactoring & Timing Infrastructure

Layer / File(s)	Summary
Timing Utility `src/core/utils/timing.ts`	New `timed()` async wrapper measures operation duration, logs slow calls (threshold `EVAULT_TIMING_SLOW_MS`), and exposes `newTraceId()` and `timingEnabled()` utilities. Disabled when `EVAULT_TIMING=0`.
Database Query Instrumentation `src/core/db/db.service.ts` (lines 45–53)	`runQueryInternal` wraps session lifecycle in `timed(...)` with Cypher label derived from the first line of the query.
Meta-Envelope Storage `src/core/db/db.service.ts` (lines 81–140)	`storeMetaEnvelope` now wrapped in `timed("db.storeMetaEnvelope", ...)`. ID generation timing and write operations are separately timed.
Meta-Envelope Update Transactional Refactor `src/core/db/db.service.ts` (lines 541–698)	`updateMetaEnvelopeById` refactored to execute full read-modify-write cycle inside a single `session.executeWrite` transaction using `tx.run`. Envelope deduplication now happens within the transaction. PATCH semantics enforced: stale envelopes no longer deleted; `mergedPayload` returned combining pre-existing and newly written envelopes.
Database Type Updates `src/core/db/types.ts`	`StoreMetaEnvelopeResult` gains optional `mergedPayload?: Record<string, any>` field. Documentation clarified: `envelopes` are touched envelopes; `mergedPayload` is the complete post-write meta-envelope state.
Neo4j ID Indexes Migration `src/core/db/migrations/add-id-indexes.ts`	New migration module exports `createIdIndexes(driver)` to create range/point-lookup indexes on `Envelope.id` and `MetaEnvelope.id` with `IF NOT EXISTS` guards.
GraphQL Webhook & Authentication `src/core/protocol/graphql-server.ts`, `src/core/protocol/vault-access-guard.ts`	`deliverWebhooks` now logs single consolidated line per dispatch with stringified payload. `updateMetaEnvelope` and legacy `updateMetaEnvelopeById` webhook data now use `result.mergedPayload ?? input.payload` (full post-write state instead of input diff). `VaultAccessGuard.validateToken` caches JWKS per URL with TTL; `checkAccess` reuses cached `context.tokenPayload`. Both wrapped in `timed()` instrumentation.
Server Initialization & Rate Limiting `src/index.ts`	Added `createIdIndexes` call during eVault startup. Fastify global rate-limiter now `return reply` after 429 response to prevent downstream handler execution.
Tests & Documentation `src/e2e/evault-core.e2e.spec.ts`	Updated `updateMetaEnvelopeById` partial-update test to assert PATCH/merge semantics: fetched payload merges initial data with partial update rather than matching partial update alone.

Sequence Diagram

sequenceDiagram
participant Client
participant GraphQL
participant DBService
participant Neo4j
participant Webhook
Client->>GraphQL: updateMetaEnvelopeById(partialUpdate)
activate GraphQL
GraphQL->>DBService: updateMetaEnvelopeById(partialUpdate)
activate DBService
DBService->>Neo4j: session.executeWrite(tx => {...})
activate Neo4j
Neo4j->>Neo4j: Read existing envelopes
Neo4j->>Neo4j: Deduplicate by ontology
Neo4j->>Neo4j: Delete duplicate nodes (transaction)
Neo4j->>Neo4j: Update/Create envelopes via tx.run
Neo4j-->>DBService: Commit transaction
deactivate Neo4j
DBService->>DBService: Build mergedPayload (pre-existing + newly written)
DBService-->>GraphQL: Return {metaEnvelope, envelopes, mergedPayload}
deactivate DBService
GraphQL->>Webhook: deliverWebhooks(data: mergedPayload)
activate Webhook
Webhook->>Webhook: Log stringified payload with metadata
Webhook-->>GraphQL: Complete
deactivate Webhook
GraphQL-->>Client: Updated envelope with full post-write state
deactivate GraphQL

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

The refactoring involves dense transactional logic with careful state management (deduplication, PATCH semantics, merged payload construction), spans multiple interconnected files (db, types, graphql, auth), introduces new caching behavior, and requires verification that PATCH semantics and transactional integrity are correctly maintained across the read-modify-write cycle.

Possibly related PRs

feat: idiomatic graphql api #769: Modifies the same updateMetaEnvelopeById and StoreMetaEnvelopeResult surfaces with changes to envelope payload handling and merged state delivery.
Fix/emover graphql api #770: Adds storeMetaEnvelopeWithId alongside related changes to meta-envelope storage logic in db.service.ts.
feat: implement envelope operation logging with cursor pagination #764: Updates GraphQL webhook and post-write logging behavior in graphql-server.ts and related envelope state enrichment patterns.

Suggested labels

evault-refactor, database, transactional, performance-instrumentation, breaking-change

Suggested reviewers

sosweetham
xPathin

🐰 Transactional hops through the data warren,
PATCH semantics bloom where once was all-or-nothing,
Timers tick soft in the Neo4j burrow,
Full payloads emerge from the merged state—
A rabbit's reward for clean, careful writes.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description is incomplete. While it mentions JWKs caching (one optimization), it omits major changes: timing instrumentation, atomic transaction refactoring, database indexing, and webhook payload improvements. The 'How the change has been tested' section is blank.	Provide a comprehensive description covering all key changes: JWKs caching, timing instrumentation, atomic transaction refactoring, database indexing, and webhook improvements. Specify how testing was performed.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title focuses on optimizing CRUD performance, which aligns with the primary changes: adding timing instrumentation, JWKs caching, atomic transactions, and database indexing for performance improvements.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch feat/evault-core-perf-optimization

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

_{Review rate limit: 0/1 reviews remaining, refill in 60 minutes.}

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

coodos · 2026-04-14T08:32:21Z

Description of change

Added JWKs caching to reduce latency

Issue Number

Type of change

Update (a change which updates existing functionality)

How the change has been tested

Change checklist

I have ensured that the CI Checks pass locally
I have removed any unnecessary logic
My code is well documented
I have signed my commits
My code follows the pattern of the application
I have self reviewed my code

Summary by CodeRabbit

New Features
- Webhooks now deliver the complete post-write state of updated envelopes, preventing receivers from unintentionally overwriting fields with partial data.
Bug Fixes
- Fixed rate-limiting to properly prevent further request handling after rejection.
Performance Improvements
- Added database indexing on envelope identifiers for faster lookups.
- Implemented JWKS caching with configurable TTL for token validation.
- Added performance monitoring and instrumentation across critical operations.

coderabbitai · 2026-04-14T08:32:30Z

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR introduces performance timing instrumentation, refactors database meta-envelope operations to use transactional PATCH semantics with merged payloads, adds Neo4j id-field indexes, implements JWKS caching in authentication, updates GraphQL webhooks to deliver full post-write state, and fixes rate-limiting response handling.

Changes

Database Refactoring & Timing Infrastructure

Layer / File(s)	Summary
Timing Utility `src/core/utils/timing.ts`	New `timed()` async wrapper measures operation duration, logs slow calls (threshold `EVAULT_TIMING_SLOW_MS`), and exposes `newTraceId()` and `timingEnabled()` utilities. Disabled when `EVAULT_TIMING=0`.
Database Query Instrumentation `src/core/db/db.service.ts` (lines 45–53)	`runQueryInternal` wraps session lifecycle in `timed(...)` with Cypher label derived from the first line of the query.
Meta-Envelope Storage `src/core/db/db.service.ts` (lines 81–140)	`storeMetaEnvelope` now wrapped in `timed("db.storeMetaEnvelope", ...)`. ID generation timing and write operations are separately timed.
Meta-Envelope Update Transactional Refactor `src/core/db/db.service.ts` (lines 541–698)	`updateMetaEnvelopeById` refactored to execute full read-modify-write cycle inside a single `session.executeWrite` transaction using `tx.run`. Envelope deduplication now happens within the transaction. PATCH semantics enforced: stale envelopes no longer deleted; `mergedPayload` returned combining pre-existing and newly written envelopes.
Database Type Updates `src/core/db/types.ts`	`StoreMetaEnvelopeResult` gains optional `mergedPayload?: Record<string, any>` field. Documentation clarified: `envelopes` are touched envelopes; `mergedPayload` is the complete post-write meta-envelope state.
Neo4j ID Indexes Migration `src/core/db/migrations/add-id-indexes.ts`	New migration module exports `createIdIndexes(driver)` to create range/point-lookup indexes on `Envelope.id` and `MetaEnvelope.id` with `IF NOT EXISTS` guards.
GraphQL Webhook & Authentication `src/core/protocol/graphql-server.ts`, `src/core/protocol/vault-access-guard.ts`	`deliverWebhooks` now logs single consolidated line per dispatch with stringified payload. `updateMetaEnvelope` and legacy `updateMetaEnvelopeById` webhook data now use `result.mergedPayload ?? input.payload` (full post-write state instead of input diff). `VaultAccessGuard.validateToken` caches JWKS per URL with TTL; `checkAccess` reuses cached `context.tokenPayload`. Both wrapped in `timed()` instrumentation.
Server Initialization & Rate Limiting `src/index.ts`	Added `createIdIndexes` call during eVault startup. Fastify global rate-limiter now `return reply` after 429 response to prevent downstream handler execution.
Tests & Documentation `src/e2e/evault-core.e2e.spec.ts`	Updated `updateMetaEnvelopeById` partial-update test to assert PATCH/merge semantics: fetched payload merges initial data with partial update rather than matching partial update alone.

Sequence Diagram

sequenceDiagram
participant Client
participant GraphQL
participant DBService
participant Neo4j
participant Webhook
Client->>GraphQL: updateMetaEnvelopeById(partialUpdate)
activate GraphQL
GraphQL->>DBService: updateMetaEnvelopeById(partialUpdate)
activate DBService
DBService->>Neo4j: session.executeWrite(tx => {...})
activate Neo4j
Neo4j->>Neo4j: Read existing envelopes
Neo4j->>Neo4j: Deduplicate by ontology
Neo4j->>Neo4j: Delete duplicate nodes (transaction)
Neo4j->>Neo4j: Update/Create envelopes via tx.run
Neo4j-->>DBService: Commit transaction
deactivate Neo4j
DBService->>DBService: Build mergedPayload (pre-existing + newly written)
DBService-->>GraphQL: Return {metaEnvelope, envelopes, mergedPayload}
deactivate DBService
GraphQL->>Webhook: deliverWebhooks(data: mergedPayload)
activate Webhook
Webhook->>Webhook: Log stringified payload with metadata
Webhook-->>GraphQL: Complete
deactivate Webhook
GraphQL-->>Client: Updated envelope with full post-write state
deactivate GraphQL

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

The refactoring involves dense transactional logic with careful state management (deduplication, PATCH semantics, merged payload construction), spans multiple interconnected files (db, types, graphql, auth), introduces new caching behavior, and requires verification that PATCH semantics and transactional integrity are correctly maintained across the read-modify-write cycle.

Possibly related PRs

feat: idiomatic graphql api #769: Modifies the same updateMetaEnvelopeById and StoreMetaEnvelopeResult surfaces with changes to envelope payload handling and merged state delivery.
Fix/emover graphql api #770: Adds storeMetaEnvelopeWithId alongside related changes to meta-envelope storage logic in db.service.ts.
feat: implement envelope operation logging with cursor pagination #764: Updates GraphQL webhook and post-write logging behavior in graphql-server.ts and related envelope state enrichment patterns.

Suggested labels

evault-refactor, database, transactional, performance-instrumentation, breaking-change

Suggested reviewers

sosweetham
xPathin

🐰 Transactional hops through the data warren,
PATCH semantics bloom where once was all-or-nothing,
Timers tick soft in the Neo4j burrow,
Full payloads emerge from the merged state—
A rabbit's reward for clean, careful writes.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description is incomplete. While it mentions JWKs caching (one optimization), it omits major changes: timing instrumentation, atomic transaction refactoring, database indexing, and webhook payload improvements. The 'How the change has been tested' section is blank.	Provide a comprehensive description covering all key changes: JWKs caching, timing instrumentation, atomic transaction refactoring, database indexing, and webhook improvements. Specify how testing was performed.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title focuses on optimizing CRUD performance, which aligns with the primary changes: adding timing instrumentation, JWKs caching, atomic transactions, and database indexing for performance improvements.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch feat/evault-core-perf-optimization

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

_{Review rate limit: 0/1 reviews remaining, refill in 60 minutes.}

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

coodos · 2026-04-14T08:32:21Z

Description of change

Added JWKs caching to reduce latency

Issue Number

Type of change

Update (a change which updates existing functionality)

How the change has been tested

Change checklist

I have ensured that the CI Checks pass locally
I have removed any unnecessary logic
My code is well documented
I have signed my commits
My code follows the pattern of the application
I have self reviewed my code

Summary by CodeRabbit

New Features
- Webhooks now deliver the complete post-write state of updated envelopes, preventing receivers from unintentionally overwriting fields with partial data.
Bug Fixes
- Fixed rate-limiting to properly prevent further request handling after rejection.
Performance Improvements
- Added database indexing on envelope identifiers for faster lookups.
- Implemented JWKS caching with configurable TTL for token validation.
- Added performance monitoring and instrumentation across critical operations.

coderabbitai · 2026-04-14T08:32:30Z

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR introduces performance timing instrumentation, refactors database meta-envelope operations to use transactional PATCH semantics with merged payloads, adds Neo4j id-field indexes, implements JWKS caching in authentication, updates GraphQL webhooks to deliver full post-write state, and fixes rate-limiting response handling.

Changes

Database Refactoring & Timing Infrastructure

Layer / File(s)	Summary
Timing Utility `src/core/utils/timing.ts`	New `timed()` async wrapper measures operation duration, logs slow calls (threshold `EVAULT_TIMING_SLOW_MS`), and exposes `newTraceId()` and `timingEnabled()` utilities. Disabled when `EVAULT_TIMING=0`.
Database Query Instrumentation `src/core/db/db.service.ts` (lines 45–53)	`runQueryInternal` wraps session lifecycle in `timed(...)` with Cypher label derived from the first line of the query.
Meta-Envelope Storage `src/core/db/db.service.ts` (lines 81–140)	`storeMetaEnvelope` now wrapped in `timed("db.storeMetaEnvelope", ...)`. ID generation timing and write operations are separately timed.
Meta-Envelope Update Transactional Refactor `src/core/db/db.service.ts` (lines 541–698)	`updateMetaEnvelopeById` refactored to execute full read-modify-write cycle inside a single `session.executeWrite` transaction using `tx.run`. Envelope deduplication now happens within the transaction. PATCH semantics enforced: stale envelopes no longer deleted; `mergedPayload` returned combining pre-existing and newly written envelopes.
Database Type Updates `src/core/db/types.ts`	`StoreMetaEnvelopeResult` gains optional `mergedPayload?: Record<string, any>` field. Documentation clarified: `envelopes` are touched envelopes; `mergedPayload` is the complete post-write meta-envelope state.
Neo4j ID Indexes Migration `src/core/db/migrations/add-id-indexes.ts`	New migration module exports `createIdIndexes(driver)` to create range/point-lookup indexes on `Envelope.id` and `MetaEnvelope.id` with `IF NOT EXISTS` guards.
GraphQL Webhook & Authentication `src/core/protocol/graphql-server.ts`, `src/core/protocol/vault-access-guard.ts`	`deliverWebhooks` now logs single consolidated line per dispatch with stringified payload. `updateMetaEnvelope` and legacy `updateMetaEnvelopeById` webhook data now use `result.mergedPayload ?? input.payload` (full post-write state instead of input diff). `VaultAccessGuard.validateToken` caches JWKS per URL with TTL; `checkAccess` reuses cached `context.tokenPayload`. Both wrapped in `timed()` instrumentation.
Server Initialization & Rate Limiting `src/index.ts`	Added `createIdIndexes` call during eVault startup. Fastify global rate-limiter now `return reply` after 429 response to prevent downstream handler execution.
Tests & Documentation `src/e2e/evault-core.e2e.spec.ts`	Updated `updateMetaEnvelopeById` partial-update test to assert PATCH/merge semantics: fetched payload merges initial data with partial update rather than matching partial update alone.

Sequence Diagram

sequenceDiagram
participant Client
participant GraphQL
participant DBService
participant Neo4j
participant Webhook
Client->>GraphQL: updateMetaEnvelopeById(partialUpdate)
activate GraphQL
GraphQL->>DBService: updateMetaEnvelopeById(partialUpdate)
activate DBService
DBService->>Neo4j: session.executeWrite(tx => {...})
activate Neo4j
Neo4j->>Neo4j: Read existing envelopes
Neo4j->>Neo4j: Deduplicate by ontology
Neo4j->>Neo4j: Delete duplicate nodes (transaction)
Neo4j->>Neo4j: Update/Create envelopes via tx.run
Neo4j-->>DBService: Commit transaction
deactivate Neo4j
DBService->>DBService: Build mergedPayload (pre-existing + newly written)
DBService-->>GraphQL: Return {metaEnvelope, envelopes, mergedPayload}
deactivate DBService
GraphQL->>Webhook: deliverWebhooks(data: mergedPayload)
activate Webhook
Webhook->>Webhook: Log stringified payload with metadata
Webhook-->>GraphQL: Complete
deactivate Webhook
GraphQL-->>Client: Updated envelope with full post-write state
deactivate GraphQL

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

The refactoring involves dense transactional logic with careful state management (deduplication, PATCH semantics, merged payload construction), spans multiple interconnected files (db, types, graphql, auth), introduces new caching behavior, and requires verification that PATCH semantics and transactional integrity are correctly maintained across the read-modify-write cycle.

Possibly related PRs

feat: idiomatic graphql api #769: Modifies the same updateMetaEnvelopeById and StoreMetaEnvelopeResult surfaces with changes to envelope payload handling and merged state delivery.
Fix/emover graphql api #770: Adds storeMetaEnvelopeWithId alongside related changes to meta-envelope storage logic in db.service.ts.
feat: implement envelope operation logging with cursor pagination #764: Updates GraphQL webhook and post-write logging behavior in graphql-server.ts and related envelope state enrichment patterns.

Suggested labels

evault-refactor, database, transactional, performance-instrumentation, breaking-change

Suggested reviewers

sosweetham
xPathin

🐰 Transactional hops through the data warren,
PATCH semantics bloom where once was all-or-nothing,
Timers tick soft in the Neo4j burrow,
Full payloads emerge from the merged state—
A rabbit's reward for clean, careful writes.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description is incomplete. While it mentions JWKs caching (one optimization), it omits major changes: timing instrumentation, atomic transaction refactoring, database indexing, and webhook payload improvements. The 'How the change has been tested' section is blank.	Provide a comprehensive description covering all key changes: JWKs caching, timing instrumentation, atomic transaction refactoring, database indexing, and webhook improvements. Specify how testing was performed.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title focuses on optimizing CRUD performance, which aligns with the primary changes: adding timing instrumentation, JWKs caching, atomic transactions, and database indexing for performance improvements.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch feat/evault-core-perf-optimization

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

_{Review rate limit: 0/1 reviews remaining, refill in 60 minutes.}

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

coodos · 2026-04-14T08:32:21Z

Description of change

Added JWKs caching to reduce latency

Issue Number

Type of change

Update (a change which updates existing functionality)

How the change has been tested

Change checklist

I have ensured that the CI Checks pass locally
I have removed any unnecessary logic
My code is well documented
I have signed my commits
My code follows the pattern of the application
I have self reviewed my code

Summary by CodeRabbit

New Features
- Webhooks now deliver the complete post-write state of updated envelopes, preventing receivers from unintentionally overwriting fields with partial data.
Bug Fixes
- Fixed rate-limiting to properly prevent further request handling after rejection.
Performance Improvements
- Added database indexing on envelope identifiers for faster lookups.
- Implemented JWKS caching with configurable TTL for token validation.
- Added performance monitoring and instrumentation across critical operations.

coderabbitai · 2026-04-14T08:32:30Z

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR introduces performance timing instrumentation, refactors database meta-envelope operations to use transactional PATCH semantics with merged payloads, adds Neo4j id-field indexes, implements JWKS caching in authentication, updates GraphQL webhooks to deliver full post-write state, and fixes rate-limiting response handling.

Changes

Database Refactoring & Timing Infrastructure

Layer / File(s)	Summary
Timing Utility `src/core/utils/timing.ts`	New `timed()` async wrapper measures operation duration, logs slow calls (threshold `EVAULT_TIMING_SLOW_MS`), and exposes `newTraceId()` and `timingEnabled()` utilities. Disabled when `EVAULT_TIMING=0`.
Database Query Instrumentation `src/core/db/db.service.ts` (lines 45–53)	`runQueryInternal` wraps session lifecycle in `timed(...)` with Cypher label derived from the first line of the query.
Meta-Envelope Storage `src/core/db/db.service.ts` (lines 81–140)	`storeMetaEnvelope` now wrapped in `timed("db.storeMetaEnvelope", ...)`. ID generation timing and write operations are separately timed.
Meta-Envelope Update Transactional Refactor `src/core/db/db.service.ts` (lines 541–698)	`updateMetaEnvelopeById` refactored to execute full read-modify-write cycle inside a single `session.executeWrite` transaction using `tx.run`. Envelope deduplication now happens within the transaction. PATCH semantics enforced: stale envelopes no longer deleted; `mergedPayload` returned combining pre-existing and newly written envelopes.
Database Type Updates `src/core/db/types.ts`	`StoreMetaEnvelopeResult` gains optional `mergedPayload?: Record<string, any>` field. Documentation clarified: `envelopes` are touched envelopes; `mergedPayload` is the complete post-write meta-envelope state.
Neo4j ID Indexes Migration `src/core/db/migrations/add-id-indexes.ts`	New migration module exports `createIdIndexes(driver)` to create range/point-lookup indexes on `Envelope.id` and `MetaEnvelope.id` with `IF NOT EXISTS` guards.
GraphQL Webhook & Authentication `src/core/protocol/graphql-server.ts`, `src/core/protocol/vault-access-guard.ts`	`deliverWebhooks` now logs single consolidated line per dispatch with stringified payload. `updateMetaEnvelope` and legacy `updateMetaEnvelopeById` webhook data now use `result.mergedPayload ?? input.payload` (full post-write state instead of input diff). `VaultAccessGuard.validateToken` caches JWKS per URL with TTL; `checkAccess` reuses cached `context.tokenPayload`. Both wrapped in `timed()` instrumentation.
Server Initialization & Rate Limiting `src/index.ts`	Added `createIdIndexes` call during eVault startup. Fastify global rate-limiter now `return reply` after 429 response to prevent downstream handler execution.
Tests & Documentation `src/e2e/evault-core.e2e.spec.ts`	Updated `updateMetaEnvelopeById` partial-update test to assert PATCH/merge semantics: fetched payload merges initial data with partial update rather than matching partial update alone.

Sequence Diagram

sequenceDiagram
participant Client
participant GraphQL
participant DBService
participant Neo4j
participant Webhook
Client->>GraphQL: updateMetaEnvelopeById(partialUpdate)
activate GraphQL
GraphQL->>DBService: updateMetaEnvelopeById(partialUpdate)
activate DBService
DBService->>Neo4j: session.executeWrite(tx => {...})
activate Neo4j
Neo4j->>Neo4j: Read existing envelopes
Neo4j->>Neo4j: Deduplicate by ontology
Neo4j->>Neo4j: Delete duplicate nodes (transaction)
Neo4j->>Neo4j: Update/Create envelopes via tx.run
Neo4j-->>DBService: Commit transaction
deactivate Neo4j
DBService->>DBService: Build mergedPayload (pre-existing + newly written)
DBService-->>GraphQL: Return {metaEnvelope, envelopes, mergedPayload}
deactivate DBService
GraphQL->>Webhook: deliverWebhooks(data: mergedPayload)
activate Webhook
Webhook->>Webhook: Log stringified payload with metadata
Webhook-->>GraphQL: Complete
deactivate Webhook
GraphQL-->>Client: Updated envelope with full post-write state
deactivate GraphQL

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

The refactoring involves dense transactional logic with careful state management (deduplication, PATCH semantics, merged payload construction), spans multiple interconnected files (db, types, graphql, auth), introduces new caching behavior, and requires verification that PATCH semantics and transactional integrity are correctly maintained across the read-modify-write cycle.

Possibly related PRs

feat: idiomatic graphql api #769: Modifies the same updateMetaEnvelopeById and StoreMetaEnvelopeResult surfaces with changes to envelope payload handling and merged state delivery.
Fix/emover graphql api #770: Adds storeMetaEnvelopeWithId alongside related changes to meta-envelope storage logic in db.service.ts.
feat: implement envelope operation logging with cursor pagination #764: Updates GraphQL webhook and post-write logging behavior in graphql-server.ts and related envelope state enrichment patterns.

Suggested labels

evault-refactor, database, transactional, performance-instrumentation, breaking-change

Suggested reviewers

sosweetham
xPathin

🐰 Transactional hops through the data warren,
PATCH semantics bloom where once was all-or-nothing,
Timers tick soft in the Neo4j burrow,
Full payloads emerge from the merged state—
A rabbit's reward for clean, careful writes.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description is incomplete. While it mentions JWKs caching (one optimization), it omits major changes: timing instrumentation, atomic transaction refactoring, database indexing, and webhook payload improvements. The 'How the change has been tested' section is blank.	Provide a comprehensive description covering all key changes: JWKs caching, timing instrumentation, atomic transaction refactoring, database indexing, and webhook improvements. Specify how testing was performed.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title focuses on optimizing CRUD performance, which aligns with the primary changes: adding timing instrumentation, JWKs caching, atomic transactions, and database indexing for performance improvements.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch feat/evault-core-perf-optimization

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

_{Review rate limit: 0/1 reviews remaining, refill in 60 minutes.}

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

coodos · 2026-04-14T08:32:21Z

Description of change

Added JWKs caching to reduce latency

Issue Number

Type of change

Update (a change which updates existing functionality)

How the change has been tested

Change checklist

I have ensured that the CI Checks pass locally
I have removed any unnecessary logic
My code is well documented
I have signed my commits
My code follows the pattern of the application
I have self reviewed my code

Summary by CodeRabbit

New Features
- Webhooks now deliver the complete post-write state of updated envelopes, preventing receivers from unintentionally overwriting fields with partial data.
Bug Fixes
- Fixed rate-limiting to properly prevent further request handling after rejection.
Performance Improvements
- Added database indexing on envelope identifiers for faster lookups.
- Implemented JWKS caching with configurable TTL for token validation.
- Added performance monitoring and instrumentation across critical operations.

coderabbitai · 2026-04-14T08:32:30Z

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR introduces performance timing instrumentation, refactors database meta-envelope operations to use transactional PATCH semantics with merged payloads, adds Neo4j id-field indexes, implements JWKS caching in authentication, updates GraphQL webhooks to deliver full post-write state, and fixes rate-limiting response handling.

Changes

Database Refactoring & Timing Infrastructure

Layer / File(s)	Summary
Timing Utility `src/core/utils/timing.ts`	New `timed()` async wrapper measures operation duration, logs slow calls (threshold `EVAULT_TIMING_SLOW_MS`), and exposes `newTraceId()` and `timingEnabled()` utilities. Disabled when `EVAULT_TIMING=0`.
Database Query Instrumentation `src/core/db/db.service.ts` (lines 45–53)	`runQueryInternal` wraps session lifecycle in `timed(...)` with Cypher label derived from the first line of the query.
Meta-Envelope Storage `src/core/db/db.service.ts` (lines 81–140)	`storeMetaEnvelope` now wrapped in `timed("db.storeMetaEnvelope", ...)`. ID generation timing and write operations are separately timed.
Meta-Envelope Update Transactional Refactor `src/core/db/db.service.ts` (lines 541–698)	`updateMetaEnvelopeById` refactored to execute full read-modify-write cycle inside a single `session.executeWrite` transaction using `tx.run`. Envelope deduplication now happens within the transaction. PATCH semantics enforced: stale envelopes no longer deleted; `mergedPayload` returned combining pre-existing and newly written envelopes.
Database Type Updates `src/core/db/types.ts`	`StoreMetaEnvelopeResult` gains optional `mergedPayload?: Record<string, any>` field. Documentation clarified: `envelopes` are touched envelopes; `mergedPayload` is the complete post-write meta-envelope state.
Neo4j ID Indexes Migration `src/core/db/migrations/add-id-indexes.ts`	New migration module exports `createIdIndexes(driver)` to create range/point-lookup indexes on `Envelope.id` and `MetaEnvelope.id` with `IF NOT EXISTS` guards.
GraphQL Webhook & Authentication `src/core/protocol/graphql-server.ts`, `src/core/protocol/vault-access-guard.ts`	`deliverWebhooks` now logs single consolidated line per dispatch with stringified payload. `updateMetaEnvelope` and legacy `updateMetaEnvelopeById` webhook data now use `result.mergedPayload ?? input.payload` (full post-write state instead of input diff). `VaultAccessGuard.validateToken` caches JWKS per URL with TTL; `checkAccess` reuses cached `context.tokenPayload`. Both wrapped in `timed()` instrumentation.
Server Initialization & Rate Limiting `src/index.ts`	Added `createIdIndexes` call during eVault startup. Fastify global rate-limiter now `return reply` after 429 response to prevent downstream handler execution.
Tests & Documentation `src/e2e/evault-core.e2e.spec.ts`	Updated `updateMetaEnvelopeById` partial-update test to assert PATCH/merge semantics: fetched payload merges initial data with partial update rather than matching partial update alone.

Sequence Diagram

sequenceDiagram
participant Client
participant GraphQL
participant DBService
participant Neo4j
participant Webhook
Client->>GraphQL: updateMetaEnvelopeById(partialUpdate)
activate GraphQL
GraphQL->>DBService: updateMetaEnvelopeById(partialUpdate)
activate DBService
DBService->>Neo4j: session.executeWrite(tx => {...})
activate Neo4j
Neo4j->>Neo4j: Read existing envelopes
Neo4j->>Neo4j: Deduplicate by ontology
Neo4j->>Neo4j: Delete duplicate nodes (transaction)
Neo4j->>Neo4j: Update/Create envelopes via tx.run
Neo4j-->>DBService: Commit transaction
deactivate Neo4j
DBService->>DBService: Build mergedPayload (pre-existing + newly written)
DBService-->>GraphQL: Return {metaEnvelope, envelopes, mergedPayload}
deactivate DBService
GraphQL->>Webhook: deliverWebhooks(data: mergedPayload)
activate Webhook
Webhook->>Webhook: Log stringified payload with metadata
Webhook-->>GraphQL: Complete
deactivate Webhook
GraphQL-->>Client: Updated envelope with full post-write state
deactivate GraphQL

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

The refactoring involves dense transactional logic with careful state management (deduplication, PATCH semantics, merged payload construction), spans multiple interconnected files (db, types, graphql, auth), introduces new caching behavior, and requires verification that PATCH semantics and transactional integrity are correctly maintained across the read-modify-write cycle.

Possibly related PRs

feat: idiomatic graphql api #769: Modifies the same updateMetaEnvelopeById and StoreMetaEnvelopeResult surfaces with changes to envelope payload handling and merged state delivery.
Fix/emover graphql api #770: Adds storeMetaEnvelopeWithId alongside related changes to meta-envelope storage logic in db.service.ts.
feat: implement envelope operation logging with cursor pagination #764: Updates GraphQL webhook and post-write logging behavior in graphql-server.ts and related envelope state enrichment patterns.

Suggested labels

evault-refactor, database, transactional, performance-instrumentation, breaking-change

Suggested reviewers

sosweetham
xPathin

🐰 Transactional hops through the data warren,
PATCH semantics bloom where once was all-or-nothing,
Timers tick soft in the Neo4j burrow,
Full payloads emerge from the merged state—
A rabbit's reward for clean, careful writes.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description is incomplete. While it mentions JWKs caching (one optimization), it omits major changes: timing instrumentation, atomic transaction refactoring, database indexing, and webhook payload improvements. The 'How the change has been tested' section is blank.	Provide a comprehensive description covering all key changes: JWKs caching, timing instrumentation, atomic transaction refactoring, database indexing, and webhook improvements. Specify how testing was performed.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title focuses on optimizing CRUD performance, which aligns with the primary changes: adding timing instrumentation, JWKs caching, atomic transactions, and database indexing for performance improvements.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch feat/evault-core-perf-optimization

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

_{Review rate limit: 0/1 reviews remaining, refill in 60 minutes.}

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

coodos · 2026-04-14T08:32:21Z

Description of change

Added JWKs caching to reduce latency

Issue Number

Type of change

Update (a change which updates existing functionality)

How the change has been tested

Change checklist

I have ensured that the CI Checks pass locally
I have removed any unnecessary logic
My code is well documented
I have signed my commits
My code follows the pattern of the application
I have self reviewed my code

Summary by CodeRabbit

New Features
- Webhooks now deliver the complete post-write state of updated envelopes, preventing receivers from unintentionally overwriting fields with partial data.
Bug Fixes
- Fixed rate-limiting to properly prevent further request handling after rejection.
Performance Improvements
- Added database indexing on envelope identifiers for faster lookups.
- Implemented JWKS caching with configurable TTL for token validation.
- Added performance monitoring and instrumentation across critical operations.

coderabbitai · 2026-04-14T08:32:30Z

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR introduces performance timing instrumentation, refactors database meta-envelope operations to use transactional PATCH semantics with merged payloads, adds Neo4j id-field indexes, implements JWKS caching in authentication, updates GraphQL webhooks to deliver full post-write state, and fixes rate-limiting response handling.

Changes

Database Refactoring & Timing Infrastructure

Layer / File(s)	Summary
Timing Utility `src/core/utils/timing.ts`	New `timed()` async wrapper measures operation duration, logs slow calls (threshold `EVAULT_TIMING_SLOW_MS`), and exposes `newTraceId()` and `timingEnabled()` utilities. Disabled when `EVAULT_TIMING=0`.
Database Query Instrumentation `src/core/db/db.service.ts` (lines 45–53)	`runQueryInternal` wraps session lifecycle in `timed(...)` with Cypher label derived from the first line of the query.
Meta-Envelope Storage `src/core/db/db.service.ts` (lines 81–140)	`storeMetaEnvelope` now wrapped in `timed("db.storeMetaEnvelope", ...)`. ID generation timing and write operations are separately timed.
Meta-Envelope Update Transactional Refactor `src/core/db/db.service.ts` (lines 541–698)	`updateMetaEnvelopeById` refactored to execute full read-modify-write cycle inside a single `session.executeWrite` transaction using `tx.run`. Envelope deduplication now happens within the transaction. PATCH semantics enforced: stale envelopes no longer deleted; `mergedPayload` returned combining pre-existing and newly written envelopes.
Database Type Updates `src/core/db/types.ts`	`StoreMetaEnvelopeResult` gains optional `mergedPayload?: Record<string, any>` field. Documentation clarified: `envelopes` are touched envelopes; `mergedPayload` is the complete post-write meta-envelope state.
Neo4j ID Indexes Migration `src/core/db/migrations/add-id-indexes.ts`	New migration module exports `createIdIndexes(driver)` to create range/point-lookup indexes on `Envelope.id` and `MetaEnvelope.id` with `IF NOT EXISTS` guards.
GraphQL Webhook & Authentication `src/core/protocol/graphql-server.ts`, `src/core/protocol/vault-access-guard.ts`	`deliverWebhooks` now logs single consolidated line per dispatch with stringified payload. `updateMetaEnvelope` and legacy `updateMetaEnvelopeById` webhook data now use `result.mergedPayload ?? input.payload` (full post-write state instead of input diff). `VaultAccessGuard.validateToken` caches JWKS per URL with TTL; `checkAccess` reuses cached `context.tokenPayload`. Both wrapped in `timed()` instrumentation.
Server Initialization & Rate Limiting `src/index.ts`	Added `createIdIndexes` call during eVault startup. Fastify global rate-limiter now `return reply` after 429 response to prevent downstream handler execution.
Tests & Documentation `src/e2e/evault-core.e2e.spec.ts`	Updated `updateMetaEnvelopeById` partial-update test to assert PATCH/merge semantics: fetched payload merges initial data with partial update rather than matching partial update alone.

Sequence Diagram

sequenceDiagram
participant Client
participant GraphQL
participant DBService
participant Neo4j
participant Webhook
Client->>GraphQL: updateMetaEnvelopeById(partialUpdate)
activate GraphQL
GraphQL->>DBService: updateMetaEnvelopeById(partialUpdate)
activate DBService
DBService->>Neo4j: session.executeWrite(tx => {...})
activate Neo4j
Neo4j->>Neo4j: Read existing envelopes
Neo4j->>Neo4j: Deduplicate by ontology
Neo4j->>Neo4j: Delete duplicate nodes (transaction)
Neo4j->>Neo4j: Update/Create envelopes via tx.run
Neo4j-->>DBService: Commit transaction
deactivate Neo4j
DBService->>DBService: Build mergedPayload (pre-existing + newly written)
DBService-->>GraphQL: Return {metaEnvelope, envelopes, mergedPayload}
deactivate DBService
GraphQL->>Webhook: deliverWebhooks(data: mergedPayload)
activate Webhook
Webhook->>Webhook: Log stringified payload with metadata
Webhook-->>GraphQL: Complete
deactivate Webhook
GraphQL-->>Client: Updated envelope with full post-write state
deactivate GraphQL

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

The refactoring involves dense transactional logic with careful state management (deduplication, PATCH semantics, merged payload construction), spans multiple interconnected files (db, types, graphql, auth), introduces new caching behavior, and requires verification that PATCH semantics and transactional integrity are correctly maintained across the read-modify-write cycle.

Possibly related PRs

feat: idiomatic graphql api #769: Modifies the same updateMetaEnvelopeById and StoreMetaEnvelopeResult surfaces with changes to envelope payload handling and merged state delivery.
Fix/emover graphql api #770: Adds storeMetaEnvelopeWithId alongside related changes to meta-envelope storage logic in db.service.ts.
feat: implement envelope operation logging with cursor pagination #764: Updates GraphQL webhook and post-write logging behavior in graphql-server.ts and related envelope state enrichment patterns.

Suggested labels

evault-refactor, database, transactional, performance-instrumentation, breaking-change

Suggested reviewers

sosweetham
xPathin

🐰 Transactional hops through the data warren,
PATCH semantics bloom where once was all-or-nothing,
Timers tick soft in the Neo4j burrow,
Full payloads emerge from the merged state—
A rabbit's reward for clean, careful writes.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description is incomplete. While it mentions JWKs caching (one optimization), it omits major changes: timing instrumentation, atomic transaction refactoring, database indexing, and webhook payload improvements. The 'How the change has been tested' section is blank.	Provide a comprehensive description covering all key changes: JWKs caching, timing instrumentation, atomic transaction refactoring, database indexing, and webhook improvements. Specify how testing was performed.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title focuses on optimizing CRUD performance, which aligns with the primary changes: adding timing instrumentation, JWKs caching, atomic transactions, and database indexing for performance improvements.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch feat/evault-core-perf-optimization

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

_{Review rate limit: 0/1 reviews remaining, refill in 60 minutes.}

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

coodos · 2026-04-14T08:32:21Z

Description of change

Added JWKs caching to reduce latency

Issue Number

Type of change

Update (a change which updates existing functionality)

How the change has been tested

Change checklist

I have ensured that the CI Checks pass locally
I have removed any unnecessary logic
My code is well documented
I have signed my commits
My code follows the pattern of the application
I have self reviewed my code

Summary by CodeRabbit

New Features
- Webhooks now deliver the complete post-write state of updated envelopes, preventing receivers from unintentionally overwriting fields with partial data.
Bug Fixes
- Fixed rate-limiting to properly prevent further request handling after rejection.
Performance Improvements
- Added database indexing on envelope identifiers for faster lookups.
- Implemented JWKS caching with configurable TTL for token validation.
- Added performance monitoring and instrumentation across critical operations.

coderabbitai · 2026-04-14T08:32:30Z

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR introduces performance timing instrumentation, refactors database meta-envelope operations to use transactional PATCH semantics with merged payloads, adds Neo4j id-field indexes, implements JWKS caching in authentication, updates GraphQL webhooks to deliver full post-write state, and fixes rate-limiting response handling.

Changes

Database Refactoring & Timing Infrastructure

Layer / File(s)	Summary
Timing Utility `src/core/utils/timing.ts`	New `timed()` async wrapper measures operation duration, logs slow calls (threshold `EVAULT_TIMING_SLOW_MS`), and exposes `newTraceId()` and `timingEnabled()` utilities. Disabled when `EVAULT_TIMING=0`.
Database Query Instrumentation `src/core/db/db.service.ts` (lines 45–53)	`runQueryInternal` wraps session lifecycle in `timed(...)` with Cypher label derived from the first line of the query.
Meta-Envelope Storage `src/core/db/db.service.ts` (lines 81–140)	`storeMetaEnvelope` now wrapped in `timed("db.storeMetaEnvelope", ...)`. ID generation timing and write operations are separately timed.
Meta-Envelope Update Transactional Refactor `src/core/db/db.service.ts` (lines 541–698)	`updateMetaEnvelopeById` refactored to execute full read-modify-write cycle inside a single `session.executeWrite` transaction using `tx.run`. Envelope deduplication now happens within the transaction. PATCH semantics enforced: stale envelopes no longer deleted; `mergedPayload` returned combining pre-existing and newly written envelopes.
Database Type Updates `src/core/db/types.ts`	`StoreMetaEnvelopeResult` gains optional `mergedPayload?: Record<string, any>` field. Documentation clarified: `envelopes` are touched envelopes; `mergedPayload` is the complete post-write meta-envelope state.
Neo4j ID Indexes Migration `src/core/db/migrations/add-id-indexes.ts`	New migration module exports `createIdIndexes(driver)` to create range/point-lookup indexes on `Envelope.id` and `MetaEnvelope.id` with `IF NOT EXISTS` guards.
GraphQL Webhook & Authentication `src/core/protocol/graphql-server.ts`, `src/core/protocol/vault-access-guard.ts`	`deliverWebhooks` now logs single consolidated line per dispatch with stringified payload. `updateMetaEnvelope` and legacy `updateMetaEnvelopeById` webhook data now use `result.mergedPayload ?? input.payload` (full post-write state instead of input diff). `VaultAccessGuard.validateToken` caches JWKS per URL with TTL; `checkAccess` reuses cached `context.tokenPayload`. Both wrapped in `timed()` instrumentation.
Server Initialization & Rate Limiting `src/index.ts`	Added `createIdIndexes` call during eVault startup. Fastify global rate-limiter now `return reply` after 429 response to prevent downstream handler execution.
Tests & Documentation `src/e2e/evault-core.e2e.spec.ts`	Updated `updateMetaEnvelopeById` partial-update test to assert PATCH/merge semantics: fetched payload merges initial data with partial update rather than matching partial update alone.

Sequence Diagram

sequenceDiagram
participant Client
participant GraphQL
participant DBService
participant Neo4j
participant Webhook
Client->>GraphQL: updateMetaEnvelopeById(partialUpdate)
activate GraphQL
GraphQL->>DBService: updateMetaEnvelopeById(partialUpdate)
activate DBService
DBService->>Neo4j: session.executeWrite(tx => {...})
activate Neo4j
Neo4j->>Neo4j: Read existing envelopes
Neo4j->>Neo4j: Deduplicate by ontology
Neo4j->>Neo4j: Delete duplicate nodes (transaction)
Neo4j->>Neo4j: Update/Create envelopes via tx.run
Neo4j-->>DBService: Commit transaction
deactivate Neo4j
DBService->>DBService: Build mergedPayload (pre-existing + newly written)
DBService-->>GraphQL: Return {metaEnvelope, envelopes, mergedPayload}
deactivate DBService
GraphQL->>Webhook: deliverWebhooks(data: mergedPayload)
activate Webhook
Webhook->>Webhook: Log stringified payload with metadata
Webhook-->>GraphQL: Complete
deactivate Webhook
GraphQL-->>Client: Updated envelope with full post-write state
deactivate GraphQL

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

The refactoring involves dense transactional logic with careful state management (deduplication, PATCH semantics, merged payload construction), spans multiple interconnected files (db, types, graphql, auth), introduces new caching behavior, and requires verification that PATCH semantics and transactional integrity are correctly maintained across the read-modify-write cycle.

Possibly related PRs

feat: idiomatic graphql api #769: Modifies the same updateMetaEnvelopeById and StoreMetaEnvelopeResult surfaces with changes to envelope payload handling and merged state delivery.
Fix/emover graphql api #770: Adds storeMetaEnvelopeWithId alongside related changes to meta-envelope storage logic in db.service.ts.
feat: implement envelope operation logging with cursor pagination #764: Updates GraphQL webhook and post-write logging behavior in graphql-server.ts and related envelope state enrichment patterns.

Suggested labels

evault-refactor, database, transactional, performance-instrumentation, breaking-change

Suggested reviewers

sosweetham
xPathin

🐰 Transactional hops through the data warren,
PATCH semantics bloom where once was all-or-nothing,
Timers tick soft in the Neo4j burrow,
Full payloads emerge from the merged state—
A rabbit's reward for clean, careful writes.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description is incomplete. While it mentions JWKs caching (one optimization), it omits major changes: timing instrumentation, atomic transaction refactoring, database indexing, and webhook payload improvements. The 'How the change has been tested' section is blank.	Provide a comprehensive description covering all key changes: JWKs caching, timing instrumentation, atomic transaction refactoring, database indexing, and webhook improvements. Specify how testing was performed.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title focuses on optimizing CRUD performance, which aligns with the primary changes: adding timing instrumentation, JWKs caching, atomic transactions, and database indexing for performance improvements.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch feat/evault-core-perf-optimization

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

_{Review rate limit: 0/1 reviews remaining, refill in 60 minutes.}

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

coodos · 2026-04-14T08:32:21Z

Description of change

Added JWKs caching to reduce latency

Issue Number

Type of change

Update (a change which updates existing functionality)

How the change has been tested

Change checklist

I have ensured that the CI Checks pass locally
I have removed any unnecessary logic
My code is well documented
I have signed my commits
My code follows the pattern of the application
I have self reviewed my code

Summary by CodeRabbit

New Features
- Webhooks now deliver the complete post-write state of updated envelopes, preventing receivers from unintentionally overwriting fields with partial data.
Bug Fixes
- Fixed rate-limiting to properly prevent further request handling after rejection.
Performance Improvements
- Added database indexing on envelope identifiers for faster lookups.
- Implemented JWKS caching with configurable TTL for token validation.
- Added performance monitoring and instrumentation across critical operations.

coderabbitai · 2026-04-14T08:32:30Z

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR introduces performance timing instrumentation, refactors database meta-envelope operations to use transactional PATCH semantics with merged payloads, adds Neo4j id-field indexes, implements JWKS caching in authentication, updates GraphQL webhooks to deliver full post-write state, and fixes rate-limiting response handling.

Changes

Database Refactoring & Timing Infrastructure

Layer / File(s)	Summary
Timing Utility `src/core/utils/timing.ts`	New `timed()` async wrapper measures operation duration, logs slow calls (threshold `EVAULT_TIMING_SLOW_MS`), and exposes `newTraceId()` and `timingEnabled()` utilities. Disabled when `EVAULT_TIMING=0`.
Database Query Instrumentation `src/core/db/db.service.ts` (lines 45–53)	`runQueryInternal` wraps session lifecycle in `timed(...)` with Cypher label derived from the first line of the query.
Meta-Envelope Storage `src/core/db/db.service.ts` (lines 81–140)	`storeMetaEnvelope` now wrapped in `timed("db.storeMetaEnvelope", ...)`. ID generation timing and write operations are separately timed.
Meta-Envelope Update Transactional Refactor `src/core/db/db.service.ts` (lines 541–698)	`updateMetaEnvelopeById` refactored to execute full read-modify-write cycle inside a single `session.executeWrite` transaction using `tx.run`. Envelope deduplication now happens within the transaction. PATCH semantics enforced: stale envelopes no longer deleted; `mergedPayload` returned combining pre-existing and newly written envelopes.
Database Type Updates `src/core/db/types.ts`	`StoreMetaEnvelopeResult` gains optional `mergedPayload?: Record<string, any>` field. Documentation clarified: `envelopes` are touched envelopes; `mergedPayload` is the complete post-write meta-envelope state.
Neo4j ID Indexes Migration `src/core/db/migrations/add-id-indexes.ts`	New migration module exports `createIdIndexes(driver)` to create range/point-lookup indexes on `Envelope.id` and `MetaEnvelope.id` with `IF NOT EXISTS` guards.
GraphQL Webhook & Authentication `src/core/protocol/graphql-server.ts`, `src/core/protocol/vault-access-guard.ts`	`deliverWebhooks` now logs single consolidated line per dispatch with stringified payload. `updateMetaEnvelope` and legacy `updateMetaEnvelopeById` webhook data now use `result.mergedPayload ?? input.payload` (full post-write state instead of input diff). `VaultAccessGuard.validateToken` caches JWKS per URL with TTL; `checkAccess` reuses cached `context.tokenPayload`. Both wrapped in `timed()` instrumentation.
Server Initialization & Rate Limiting `src/index.ts`	Added `createIdIndexes` call during eVault startup. Fastify global rate-limiter now `return reply` after 429 response to prevent downstream handler execution.
Tests & Documentation `src/e2e/evault-core.e2e.spec.ts`	Updated `updateMetaEnvelopeById` partial-update test to assert PATCH/merge semantics: fetched payload merges initial data with partial update rather than matching partial update alone.

Sequence Diagram

sequenceDiagram
participant Client
participant GraphQL
participant DBService
participant Neo4j
participant Webhook
Client->>GraphQL: updateMetaEnvelopeById(partialUpdate)
activate GraphQL
GraphQL->>DBService: updateMetaEnvelopeById(partialUpdate)
activate DBService
DBService->>Neo4j: session.executeWrite(tx => {...})
activate Neo4j
Neo4j->>Neo4j: Read existing envelopes
Neo4j->>Neo4j: Deduplicate by ontology
Neo4j->>Neo4j: Delete duplicate nodes (transaction)
Neo4j->>Neo4j: Update/Create envelopes via tx.run
Neo4j-->>DBService: Commit transaction
deactivate Neo4j
DBService->>DBService: Build mergedPayload (pre-existing + newly written)
DBService-->>GraphQL: Return {metaEnvelope, envelopes, mergedPayload}
deactivate DBService
GraphQL->>Webhook: deliverWebhooks(data: mergedPayload)
activate Webhook
Webhook->>Webhook: Log stringified payload with metadata
Webhook-->>GraphQL: Complete
deactivate Webhook
GraphQL-->>Client: Updated envelope with full post-write state
deactivate GraphQL

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

The refactoring involves dense transactional logic with careful state management (deduplication, PATCH semantics, merged payload construction), spans multiple interconnected files (db, types, graphql, auth), introduces new caching behavior, and requires verification that PATCH semantics and transactional integrity are correctly maintained across the read-modify-write cycle.

Possibly related PRs

feat: idiomatic graphql api #769: Modifies the same updateMetaEnvelopeById and StoreMetaEnvelopeResult surfaces with changes to envelope payload handling and merged state delivery.
Fix/emover graphql api #770: Adds storeMetaEnvelopeWithId alongside related changes to meta-envelope storage logic in db.service.ts.
feat: implement envelope operation logging with cursor pagination #764: Updates GraphQL webhook and post-write logging behavior in graphql-server.ts and related envelope state enrichment patterns.

Suggested labels

evault-refactor, database, transactional, performance-instrumentation, breaking-change

Suggested reviewers

sosweetham
xPathin

🐰 Transactional hops through the data warren,
PATCH semantics bloom where once was all-or-nothing,
Timers tick soft in the Neo4j burrow,
Full payloads emerge from the merged state—
A rabbit's reward for clean, careful writes.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description is incomplete. While it mentions JWKs caching (one optimization), it omits major changes: timing instrumentation, atomic transaction refactoring, database indexing, and webhook payload improvements. The 'How the change has been tested' section is blank.	Provide a comprehensive description covering all key changes: JWKs caching, timing instrumentation, atomic transaction refactoring, database indexing, and webhook improvements. Specify how testing was performed.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title focuses on optimizing CRUD performance, which aligns with the primary changes: adding timing instrumentation, JWKs caching, atomic transactions, and database indexing for performance improvements.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch feat/evault-core-perf-optimization

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

_{Review rate limit: 0/1 reviews remaining, refill in 60 minutes.}

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

chore: JWKs caching
e1dce49

coodos added 9 commits April 14, 2026 14:14

chore: debug logs
07cd38e

chore: remove log noise
3980c33

fix: rate-limit failfast
33024a8

fix: indexing on mid
626c692

chore: atomic update
e654f0a

feat: atomic updates
3e22b87

fix: regression on registry participants array
97e6286

chore: debug logs
804d0cd

chore: fix e2e test
50a4eb9

coodos marked this pull request as ready for review May 2, 2026 14:54

coodos merged commit 2990789 into mainMay 2, 2026
5 of 6 checks passed

coodos deleted the feat/evault-core-perf-optimization branch May 2, 2026 14:56

coderabbitaiBot mentioned this pull request Aug 7, 2026
Fix awareness webhook delivery reliability #1105
Merged
6 tasks

chore: JWKs caching
e1dce49

coodos added 9 commits April 14, 2026 14:14

chore: debug logs
07cd38e

chore: remove log noise
3980c33

fix: rate-limit failfast
33024a8

fix: indexing on mid
626c692

chore: atomic update
e654f0a

feat: atomic updates
3e22b87

fix: regression on registry participants array
97e6286

chore: debug logs
804d0cd

chore: fix e2e test
50a4eb9

coodos marked this pull request as ready for review May 2, 2026 14:54

coodos merged commit 2990789 into mainMay 2, 2026
5 of 6 checks passed

coodos deleted the feat/evault-core-perf-optimization branch May 2, 2026 14:56

coderabbitaiBot mentioned this pull request Aug 7, 2026
Fix awareness webhook delivery reliability #1105
Merged
6 tasks

chore: JWKs caching
e1dce49

coodos added 9 commits April 14, 2026 14:14

chore: debug logs
07cd38e

chore: remove log noise
3980c33

fix: rate-limit failfast
33024a8

fix: indexing on mid
626c692

chore: atomic update
e654f0a

feat: atomic updates
3e22b87

fix: regression on registry participants array
97e6286

chore: debug logs
804d0cd

chore: fix e2e test
50a4eb9

coodos marked this pull request as ready for review May 2, 2026 14:54

coodos merged commit 2990789 into mainMay 2, 2026
5 of 6 checks passed

coodos deleted the feat/evault-core-perf-optimization branch May 2, 2026 14:56

coderabbitaiBot mentioned this pull request Aug 7, 2026
Fix awareness webhook delivery reliability #1105
Merged
6 tasks

chore: JWKs caching
e1dce49

coodos added 9 commits April 14, 2026 14:14

chore: debug logs
07cd38e

chore: remove log noise
3980c33

fix: rate-limit failfast
33024a8

fix: indexing on mid
626c692

chore: atomic update
e654f0a

feat: atomic updates
3e22b87

fix: regression on registry participants array
97e6286

chore: debug logs
804d0cd

chore: fix e2e test
50a4eb9

coodos marked this pull request as ready for review May 2, 2026 14:54

coodos merged commit 2990789 into mainMay 2, 2026
5 of 6 checks passed

coodos deleted the feat/evault-core-perf-optimization branch May 2, 2026 14:56

coderabbitaiBot mentioned this pull request Aug 7, 2026
Fix awareness webhook delivery reliability #1105
Merged
6 tasks

chore: JWKs caching
e1dce49

coodos added 9 commits April 14, 2026 14:14

chore: debug logs
07cd38e

chore: remove log noise
3980c33

fix: rate-limit failfast
33024a8

fix: indexing on mid
626c692

chore: atomic update
e654f0a

feat: atomic updates
3e22b87

fix: regression on registry participants array
97e6286

chore: debug logs
804d0cd

chore: fix e2e test
50a4eb9

coodos marked this pull request as ready for review May 2, 2026 14:54

coodos merged commit 2990789 into mainMay 2, 2026
5 of 6 checks passed

coodos deleted the feat/evault-core-perf-optimization branch May 2, 2026 14:56

coderabbitaiBot mentioned this pull request Aug 7, 2026
Fix awareness webhook delivery reliability #1105
Merged
6 tasks

chore: JWKs caching
e1dce49

coodos added 9 commits April 14, 2026 14:14

chore: debug logs
07cd38e

chore: remove log noise
3980c33

fix: rate-limit failfast
33024a8

fix: indexing on mid
626c692

chore: atomic update
e654f0a

feat: atomic updates
3e22b87

fix: regression on registry participants array
97e6286

chore: debug logs
804d0cd

chore: fix e2e test
50a4eb9

coodos marked this pull request as ready for review May 2, 2026 14:54

coodos merged commit 2990789 into mainMay 2, 2026
5 of 6 checks passed

coodos deleted the feat/evault-core-perf-optimization branch May 2, 2026 14:56

coderabbitaiBot mentioned this pull request Aug 7, 2026
Fix awareness webhook delivery reliability #1105
Merged
6 tasks

chore: JWKs caching
e1dce49

coodos added 9 commits April 14, 2026 14:14

chore: debug logs
07cd38e

chore: remove log noise
3980c33

fix: rate-limit failfast
33024a8

fix: indexing on mid
626c692

chore: atomic update
e654f0a

feat: atomic updates
3e22b87

fix: regression on registry participants array
97e6286

chore: debug logs
804d0cd

chore: fix e2e test
50a4eb9

coodos marked this pull request as ready for review May 2, 2026 14:54

coodos merged commit 2990789 into mainMay 2, 2026
5 of 6 checks passed

coodos deleted the feat/evault-core-perf-optimization branch May 2, 2026 14:56

coderabbitaiBot mentioned this pull request Aug 7, 2026
Fix awareness webhook delivery reliability #1105
Merged
6 tasks

chore: JWKs caching
e1dce49

coodos added 9 commits April 14, 2026 14:14

chore: debug logs
07cd38e

chore: remove log noise
3980c33

fix: rate-limit failfast
33024a8

fix: indexing on mid
626c692

chore: atomic update
e654f0a

feat: atomic updates
3e22b87

fix: regression on registry participants array
97e6286

chore: debug logs
804d0cd

chore: fix e2e test
50a4eb9

coodos marked this pull request as ready for review May 2, 2026 14:54

coodos merged commit 2990789 into mainMay 2, 2026
5 of 6 checks passed

coodos deleted the feat/evault-core-perf-optimization branch May 2, 2026 14:56

coderabbitaiBot mentioned this pull request Aug 7, 2026
Fix awareness webhook delivery reliability #1105
Merged
6 tasks

Uh oh!

Conversation

coodos commented Apr 14, 2026• edited by coderabbitai BotLoading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description of change

Issue Number

Type of change

How the change has been tested

Change checklist

Summary by CodeRabbit

Uh oh!

coderabbitaiBot commented Apr 14, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review failed

Walkthrough

Changes

Sequence Diagram

Estimated code review effort

Possibly related PRs

Suggested labels

Suggested reviewers

❌ Failed checks (2 warnings)

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

coodos commented Apr 14, 2026• edited by coderabbitai BotLoading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description of change

Issue Number

Type of change

How the change has been tested

Change checklist

Summary by CodeRabbit

Uh oh!

coderabbitaiBot commented Apr 14, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review failed

Walkthrough

Changes

Sequence Diagram

Estimated code review effort

Possibly related PRs

Suggested labels

Suggested reviewers

❌ Failed checks (2 warnings)

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

coodos commented Apr 14, 2026• edited by coderabbitai BotLoading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description of change

Issue Number

Type of change

How the change has been tested

Change checklist

Summary by CodeRabbit

Uh oh!

coderabbitaiBot commented Apr 14, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review failed

Walkthrough

Changes

coodos commented Apr 14, 2026•
edited by coderabbitai Bot
Loading

coderabbitaiBot commented Apr 14, 2026•
edited
Loading

coodos commented Apr 14, 2026•
edited by coderabbitai Bot
Loading

coderabbitaiBot commented Apr 14, 2026•
edited
Loading

coodos commented Apr 14, 2026•
edited by coderabbitai Bot
Loading

coderabbitaiBot commented Apr 14, 2026•
edited
Loading

coodos commented Apr 14, 2026•
edited by coderabbitai Bot
Loading

coderabbitaiBot commented Apr 14, 2026•
edited
Loading