[compliance] Specification Gap: payload_size_threshold field not in spec v1.8.0

[github-actions]

Summary

Commit db3ff1f (#790) added a new gateway configuration field payload_size_threshold that is NOT defined in the MCP Gateway Specification v1.8.0.

This creates a specification-implementation mismatch that violates the specification's forward compatibility requirements.

Specification Violation

Section 4.3.1 - Unknown Features

The gateway MUST reject configurations containing unrecognized fields at the top level with an error message indicating:

• The unrecognized field name
• The location in the configuration
• A suggestion to check the specification version

Deep Link: https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/mcp-gateway.md#431-unknown-features

Compliance Test: T-CFG-006 - Unknown field rejection

Gateway Configuration Fields (Spec v1.8.0)

Per Section 4.1.3, the specification defines:

Field	Type	Required	Spec Status
port	integer	Yes	✅ Defined
domain	string	Yes	✅ Defined
apiKey	string	Yes	✅ Defined
startupTimeout	integer	No	✅ Defined
toolTimeout	integer	No	✅ Defined
payloadDir	string	No	✅ Defined
payloadSizeThreshold	integer	No	❌ NOT DEFINED

Current Implementation State

Files Modified in db3ff1f:

• internal/config/config_core.go - Added PayloadSizeThreshold field
• internal/config/config_payload.go - Added DefaultPayloadSizeThreshold = 1024
• internal/cmd/flags_logging.go - Added --payload-size-threshold CLI flag
• internal/middleware/jqschema.go - Implemented size-based routing logic
• config.example-payload-threshold.toml - Example configuration

Configuration Methods:

# TOML config
[gateway]
payload_size_threshold = 1024

{
  "gateway": {
    "payloadSizeThreshold": 1024
  }
}

# CLI flag
awmg --config config.toml --payload-size-threshold 2048

# Environment variable
MCP_GATEWAY_PAYLOAD_SIZE_THRESHOLD=2048 awmg --config config.toml

Gap Analysis

1. Forward Compatibility Violation

The specification explicitly requires rejecting unknown fields (Section 4.3.1), but the implementation accepts payload_size_threshold despite it not being in the spec.

2. Documentation Inconsistency

The field is documented in implementation files but absent from the formal specification, creating confusion about what is "officially supported."

3. Compliance Test Impact

Compliance test T-CFG-006 (Unknown field rejection) would fail when testing gateway configuration fields, as the implementation accepts an unspecified field.

Recommended Resolution

Add payload_size_threshold to the specification (v1.9.0 or later).

Rationale

1. ✅ Addresses real performance issue (avoids unnecessary file I/O for small payloads)
2. ✅ Implementation is complete, tested, and working
3. ✅ Follows existing patterns (similar to optional payloadDir field)
4. ✅ Default value (1024 bytes) is reasonable
5. ✅ Configuration flexibility matches other gateway fields

Specification Update Needed

Section 4.1.3 - Gateway Configuration Fields

Add new row to the table:

Field	Type	Required	Description
payloadSizeThreshold	integer	No	Size threshold in bytes for inline vs disk payload storage. Payloads ≤ threshold are returned inline (no file storage). Payloads > threshold are stored to disk with metadata response. Default: 1024 (1KB). Must be a positive integer.

Section 4.1.3.2 - Payload Size Threshold Behavior (new subsection)

When `payloadSizeThreshold` is configured:

1. The gateway MUST compare the marshaled JSON response size against the threshold
2. If size ≤ threshold: return original response inline (no transformation)
3. If size > threshold: store to `{payloadDir}/{sessionID}/{queryID}/payload.json` and return metadata response
4. The threshold MUST be a positive integer (bytes)
5. Invalid values (negative, zero, non-numeric) MUST be rejected during configuration validation
6. Default: 1024 bytes (1KB)

Section 10.1.1 - Add Compliance Test T-CFG-020

- **T-CFG-020**: Payload size threshold configuration
  - Valid positive integer threshold accepted
  - Invalid values (negative, zero, non-numeric) rejected
  - Default value (1024) applied when not specified
  - Size-based routing works correctly (inline vs disk)

Change Log - Version 1.9.0

- **Added**: `payloadSizeThreshold` field to gateway configuration (Section 4.1.3)
  - Optional size threshold (bytes) for inline vs disk payload storage
  - Default: 1024 bytes (1KB)
  - Enables performance optimization by avoiding file I/O for small responses
  - Must be positive integer, validated during configuration parsing

Alternative Options

Option 2: Remove from Implementation

Revert commit db3ff1f to achieve immediate compliance.

Pros: Instant specification alignment
Cons: Loses performance optimization, wastes development effort

Option 3: Implementation-Defined Extension

Document as an implementation-specific extension outside the spec.

Pros: Keeps feature without spec change
Cons: Violates spec Section 4.3.1, confusing for users

Action Items

If proceeding with Option 1 (recommended):

1. Specification Update (github/gh-aw repository)

   • Update Section 4.1.3 table with payloadSizeThreshold field
   • Add Section 4.1.3.2 describing behavior
   • Add compliance test T-CFG-020
   • Update JSON schema (mcp-gateway-config.schema.json)
   • Update change log to v1.9.0

2. Implementation Validation

   • Verify current implementation matches proposed spec
   • Add validation for positive integer requirement
   • Add tests for T-CFG-020 compliance

3. Documentation

   • Update README.md if needed
   • Update AGENTS.md with new field

References

• MCP Gateway Specification v1.8.0: https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/mcp-gateway.md
• Section 4.1.3 - Gateway Configuration: https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/mcp-gateway.md#413-gateway-configuration-fields
• Section 4.3.1 - Unknown Features: https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/mcp-gateway.md#431-unknown-features
• Implementing Commit: db3ff1f
• Pull Request: Add configurable payload size threshold for inline vs disk storage #790

Review Context

• Last Compliance Review: 2026-02-06 (commit 06ff18a)
• Current Review: 2026-02-07 (commit db3ff1f)
• Files Reviewed: 160+ files in PR Add configurable payload size threshold for inline vs disk storage #790
• Specification Version: 1.8.0

AI generated by Daily Compliance Checker

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

AI generated by Issue Monster

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

AI generated by Issue Monster