feat(server): execute buffered guarded operations

[Pouyanpi]

Description

Phase A establishes the private provider-neutral foundations for transparent provider proxying. This PR adds the buffered execution ordering on top of the contracts introduced by PR 1.

The executor:

• runs request projection, input checking, dispatch, response projection, and output checking in a fixed order;
• always projects and validates guarded input, even when both checker calls are disabled;
• uses the same validated checker and captured inspection settings for the complete operation;
• prevents dispatch when input is blocked or checking fails;
• prevents a provider response from escaping when output is blocked or checking fails;
• preserves the original request and response object identities when checks allow them;
• still projects input context for output-only checking;
• converts raised checker exceptions and unknown decisions into stage-specific failure outcomes;
• converts requested content modification into an explicit unsupported outcome.

The implementation remains independent of FastAPI, HTTPX, provider payloads, configuration resolution, and streaming.

Stable and temporary parts

The fail-closed execution order and semantic outcomes are intended to remain as the shared buffered execution primitive.

This executor is deliberately narrower than a complete provider pipeline:

• its generic request and response values do not yet carry parsed provider payloads or exact guarded-target state;
• provider media-type, content-encoding, success-status, and payload validation remain provider-owned;
• native provider error rendering and OpenAPI error documentation remain outside this layer;
• response-mode selection and streaming remain outside this buffered executor;
• content replacement remains unsupported until exact-target mutation and HTTP rewrite integrity are available.

Provider integration composes these responsibilities around the executor rather than replacing or duplicating its ordering.

Review focus

• Is the execution order explicit and fail-closed at every step?
• Can an input rejection ever dispatch upstream?
• Can an output rejection ever expose the provider response?
• Does one checker binding and one captured policy govern the complete operation?
• Does the executor remain independent of HTTP and provider-specific behavior?
• Is the boundary between stable execution ordering and deferred provider composition clear?

Non-goals

• HTTP routing or forwarding;
• provider payload models or contracts;
• streaming;
• Rails configuration resolution;
• safe replacement;
• a public provider-extension API.

Phase A stack

Review every PR against its parent branch rather than against develop, except for PR 1.

Order	PR	Branch	Base
1	#2404	pouyanpi/transparent-proxy-kernel-1	develop
2	#2405	pouyanpi/transparent-proxy-buffered-kernel-2	pouyanpi/transparent-proxy-kernel-1
3	#2406	pouyanpi/transparent-proxy-http-kernel-3	pouyanpi/transparent-proxy-buffered-kernel-2
4	#2407	pouyanpi/transparent-proxy-projection-outcomes-4	pouyanpi/transparent-proxy-http-kernel-3

AI Assistance

• No AI tools were used.
• AI tools were used; a human reviewed and can explain every change.

Checklist

• I've read the CONTRIBUTING guidelines.
• This is maintainer-led work tracked internally.
• The PR title follows the project commit convention.
• Public documentation is not applicable to this private executor-only change.
• Tests cover the introduced behavior.
• Verification and checks not run are documented.
• Generated changelog files were not edited manually.
• All automated and human review comments are addressed or answered.
• The responsible reviewer or team is mentioned.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[greptile-apps]

Confidence Score: 5/5

[Medium risk] Adds buffered operation execution with content checking.

This PR appears safe to merge; no outstanding findings remain in its changed files.

Summary

This PR adds a private buffered executor that projects guarded input, runs enabled checks around provider dispatch, and returns stage-specific stop outcomes while preserving allowed response identity.

• Adds tests for execution order, blocked decisions, checker errors, invalid projections, and import boundaries.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Validate checker and capture policy] --> B[Project input]
  B --> C{Input check enabled?}
  C -- Yes --> D[Check input]
  C -- No --> E[Dispatch]
  D -- Allow --> E
  D -- Stop --> S[Return input-stage outcome]
  E --> F{Output check enabled?}
  F -- Yes --> G[Project and check output]
  F -- No --> H[Return original response]
  G -- Allow --> H
  G -- Stop --> T[Return output-stage outcome]

Loading

_{Reviews (4) · Last reviewed commit: "test(server): cover invalid output proje..."}

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: NVIDIA-NeMo/Guardrails/.coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 8c0b2d67-71c2-4d48-a029-c466be91c717

📥 Commits

Reviewing files that changed from the base of the PR and between a46e449 and f4902d0.

📒 Files selected for processing (3)

• nemoguardrails/server/experimental/_buffered_kernel.py
• tests/server/experimental/test_buffered_kernel.py
• tests/server/experimental/test_import_boundaries.py

Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 10 remain after this review.

---

📝 Walkthrough

Walkthrough

The change adds buffered guarded-operation execution. It checks projected request and response messages when inspection is enabled, and returns stage-specific outcomes for blocking decisions, checker failures, and unsupported modifications.

Changes

Buffered guarded execution

Layer / File(s)	Summary
Inspection outcomes and checker decisions nemoguardrails/server/experimental/_buffered_kernel.py	Adds input and output inspection stages, result types, projection validation, and conversion of checker decisions or exceptions into outcomes.
Buffered execution and validation nemoguardrails/server/experimental/_buffered_kernel.py, tests/server/experimental/test_buffered_kernel.py, tests/server/experimental/test_import_boundaries.py	Adds execution that checks enabled input and output stages around dispatch. Tests cover dispatch behavior, stage-specific outcomes, projection errors, checker calls, and importability.

Priority: ⬇️ Low

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

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant execute_buffered_operation
  participant ContentChecker
  participant dispatch
  Caller->>execute_buffered_operation: operation, checker, request, dispatch
  execute_buffered_operation->>ContentChecker: check projected user message when input inspection is enabled
  ContentChecker-->>execute_buffered_operation: input decision
  execute_buffered_operation->>dispatch: request when input check allows or input inspection is disabled
  dispatch-->>execute_buffered_operation: response
  execute_buffered_operation->>ContentChecker: check projected assistant message when output inspection is enabled
  ContentChecker-->>execute_buffered_operation: output decision
  execute_buffered_operation-->>Caller: completion or stage-specific outcome

Loading

Merge Risk: ⚪ Minimal · up to f4902

No actionable merge-blocking risk remains for the buffered executor after normal checks.

🚥 Pre-merge checks | ✅ 5 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 46.67% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 30 functions across 3 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (5 passed)

Check name	Status	Explanation
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.
Test Results For Major Changes	✅ Passed	The PR introduces a major feature, and its description documents testing information: 40 experimental server tests passed via make test WORKERS=1 TEST='tests/server/experimental' ARGS='-q', and pre-…
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding execution support for buffered guarded operations.

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 2

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🛠️ Fix failing CI checks 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

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

[tgasser-nv]

Looks good! Just a couple of naming nits