feat(server): classify guarded projection outcomes

[Pouyanpi]

Description

Phase A establishes the private provider-neutral foundations for transparent provider proxying. This PR completes the provider-neutral projection boundary before provider integration is added.

It adds:

• an explicit unsupported-payload exception for generated or handwritten projections;
• an input projection-failure outcome that stops before dispatch;
• an output projection-failure outcome that hides an incompatible provider response;
• an output-not-applicable marker for provider responses with no guarded assistant content;
• transparent preservation of non-content responses without an output checker call;
• HTTP rendering of projection failures through the injected outcome renderer.

This layer does not decide which status codes or payloads contain content to inspect. Each provider binding owns that declaration.

Together with the checker and HTTP outcomes from the preceding PRs, these values form a provider-neutral failure model. A provider integration must use one provider-owned mapping for native runtime envelopes, stable error codes, and OpenAPI documentation so those representations cannot drift.

Stable and temporary parts

The semantic projection outcomes and their fail-closed ordering are intended to remain provider-neutral. They are not temporary HTTP error models.

The injected renderer is the narrow part: provider integration later maps the same outcomes to native status codes and response envelopes and uses the same mapping for OpenAPI documentation. Each provider binding also decides which responses contain content to inspect. ContentInspectionNotApplicable is not a general bypass for successful output.

Review focus

• Does unsupported input fail before dispatch?
• Can an unsupported output expose any provider body or headers?
• Is output-not-applicable narrow enough to preserve provider errors without silently bypassing guarded successful output?
• Does this layer remain provider-neutral by delegating status and payload selection to provider bindings?
• Are programmer errors distinct from supported projection failures?
• Is it clear that provider mapping extends the semantic outcomes rather than replacing them?

Non-goals

• provider payload parsing or validation;
• provider status-code selection;
• provider-shaped error responses;
• OpenAI routing or integration;
• streaming;
• 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 projection 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.

[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: e349e667-52fd-44c4-9962-1344efc2020a

📥 Commits

Reviewing files that changed from the base of the PR and between 7a731d7 and 48d2e0f.

📒 Files selected for processing (5)

• nemoguardrails/server/experimental/_buffered_kernel.py
• nemoguardrails/server/experimental/_guarded_operation.py
• nemoguardrails/server/experimental/_http_kernel.py
• tests/server/experimental/test_buffered_kernel.py
• tests/server/experimental/test_http_kernel.py

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

---

📝 Walkthrough

Walkthrough

Guarded message projections can now indicate that inspection does not apply or raise an unsupported-payload failure. Buffered operations report projection failures by stage, and the HTTP renderer accepts those failures.

Changes

Projection outcome handling

Layer / File(s)	Summary
Guarded projection contract and buffered operation handling nemoguardrails/server/experimental/_guarded_operation.py, nemoguardrails/server/experimental/_buffered_kernel.py, tests/server/experimental/test_buffered_kernel.py	Projections can return ContentInspectionNotApplicable or raise UnsupportedGuardedPayload. Buffered operations return OperationProjectionFailed with the input or output stage for unsupported payloads. Inapplicable input inspection raises TypeError; inapplicable output inspection completes with the original response without running the output check. Tests cover these outcomes.
HTTP failure rendering and response behavior nemoguardrails/server/experimental/_http_kernel.py, tests/server/experimental/test_http_kernel.py	The renderer accepts OperationProjectionFailed. Tests cover an input projection failure response and preservation of a provider error response and headers when output inspection is inapplicable.

Priority: ➖ Normal

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

Change: Feature

Merge Risk: ⚪ Minimal · up to 48d2e

No actionable issue is established for this PR; it is mergeable after normal checks.

🚥 Pre-merge checks | ✅ 5 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 28 functions across 5 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 makes major server behavior changes and adds 248 lines across implementation and tests. The description documents verification results, including 71 passing experimental tests, 368 passing serv…
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: classifying guarded projection outcomes across the server execution and HTTP handling paths.

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• 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.}

[greptile-apps]

Confidence Score: 5/5

[Medium risk] Adds new outcome types for guarded operation failures.

The PR appears safe to merge; no outstanding findings remain.

Summary

This PR adds provider-neutral outcomes for unsupported input and output projections. Input failure stops before dispatch; output failure withholds the provider response; an output marked inapplicable preserves the response without an output check. The HTTP kernel passes projection failures to the injected renderer.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Project input] -->|Unsupported| B[Input projection failure]
  A -->|Supported| C[Optional input check]
  C --> D[Dispatch]
  D --> E{Project output if inspection enabled}
  E -->|Unsupported| F[Output projection failure]
  E -->|Not applicable| G[Return provider response]
  E -->|Guarded message| H[Output check]
  H -->|Allowed| G
  B --> I[Injected HTTP renderer]
  F --> I

Loading

_{Reviews (7) · Last reviewed commit: "docs(server): describe projection outcom..." · Reviewed by Greptile}

[tgasser-nv]

Looks good, just one nit

[tgasser-nv]

Looks good, approving