[Schema Consistency] Constraint Coverage Audit - Critical Port Validation Gap (Run #3)

[github-actions[bot]]

Summary

Analysis Date: 2026-01-22
Strategy: #28 - Constraint Coverage & Enforcement Gap Analysis
Run: 3 of 3 total runs
Status: 🔴 CRITICAL - Persistent unvalidated field + new findings

Key Metrics:

• Critical Issues: 1 persistent (15 days unfixed)
• Moderate Issues: 3 new discoveries
• Resolved: 1 issue fixed since last run
• Positive: 4 fields with excellent validation

Critical Issue (PERSISTENT)

1. ❌ sandbox.mcp.port - No Runtime Validation

Severity: CRITICAL
First Identified: 2026-01-07 (15 days ago)
Status: Still not fixed as of 2026-01-22

Schema Definition:

{
  "port": {
    "type": "integer",
    "minimum": 1,
    "maximum": 65535,
    "description": "Port for the gateway HTTP server"
  }
}

Current Behavior:

• Schema declares minimum: 1, maximum: 65535
• validateIntRange helper exists in pkg/workflow/validation_helpers.go
• Port is extracted in pkg/workflow/frontmatter_extraction_security.go:extractMCPGatewayConfig()
• NO validation called - invalid ports (0, -1, 99999) would pass through

Impact:

• Invalid port numbers could cause runtime failures
• MCP gateway container startup failures
• Difficult-to-debug networking issues
• Security risk if port 0 allows OS-assigned random ports

Location:

• Schema: pkg/parser/schemas/main_workflow_schema.json (properties.sandbox.oneOf[2].properties.mcp.properties.port)
• Extraction: pkg/workflow/frontmatter_extraction_security.go:extractMCPGatewayConfig()
• Missing validation site: After line where mcpConfig.Port = int(v) is set

Recommended Fix:

// In extractMCPGatewayConfig after port extraction:
if mcpConfig.Port != 0 {
    if err := validateIntRange(mcpConfig.Port, 1, 65535, "sandbox.mcp.port"); err != nil {
        // return error
    }
}

Moderate Issues (NEW)

View 3 New Unvalidated Constraint Findings

2. ⚠️ tools.timeout - No Minimum Validation

Schema: minimum: 1
Reality: No runtime check for positive integer
Files:

• Schema: properties.tools.properties.timeout
• Processing: pkg/workflow/tools*.go

Risk: Timeout of 0 or negative values could cause unexpected behavior

---

3. ⚠️ tools.startup-timeout - No Minimum Validation

Schema: minimum: 1
Reality: No runtime check for positive integer
Files:

• Schema: properties.tools.properties.startup-timeout
• Processing: pkg/workflow/tools*.go

Risk: Startup timeout of 0 could cause immediate MCP server failures

---

4. ⚠️ tracker-id - No String Constraint Validation

Schema:

• minLength: 8
• pattern: ^[a-zA-Z0-9_-]+$

Reality: No runtime validation of length or character set
Files:

• Schema: properties.tracker-id
• Processing: Various workflow files

Risk: Short or invalid tracker IDs could cause downstream issues

Architectural Gaps (PERSISTENT)

These structural schema gaps have been present since the beginning:

Constraint Type	Count	Note
minItems	18	✓ Well used
maxItems	0	❌ No upper bounds on arrays
minLength	17	✓ Decent coverage
maxLength	3	❌ Most strings unbounded
format	0	❌ No URI/email/regex validation
pattern	25	✓ Good coverage

Impact:

• Arrays could grow unbounded (memory issues)
• Strings have no max length (DoS via huge values)
• No format validation for URLs, emails, versions

Positive Findings ✅

View 4 Examples of Excellent Constraint Enforcement

1. ✅ cache-memory.retention-days (RESOLVED)

Status: Fixed since 2026-01-13
Schema: minimum: 1, maximum: 90
Runtime: validateIntRange(*entry.RetentionDays, 1, 90, "retention-days")
Location: pkg/workflow/cache.go (2 validation calls)

This issue was reported in run #1 (2026-01-07) and fixed by run #2 (2026-01-13). Excellent response time!

---

2. ✅ repo-memory.max-file-size

Schema: minimum: 1, maximum: 104857600
Runtime: validateIntRange(entry.MaxFileSize, 1, 104857600, "max-file-size")
Location: pkg/workflow/repo_memory.go

Perfect enforcement of both bounds.

---

3. ✅ repo-memory.max-file-count

Schema: minimum: 1, maximum: 1000
Runtime: validateIntRange(entry.MaxFileCount, 1, 1000, "max-file-count")
Location: pkg/workflow/repo_memory.go

Perfect enforcement of both bounds.

---

4. ✅ repo-memory.branch-prefix (GOLD STANDARD)

Schema:

• minLength: 1
• maxLength: 32
• pattern: ^[^/]+$ (and other patterns)

Runtime: validateBranchPrefix() - comprehensive validation
Location: pkg/workflow/repo_memory.go (4 validation calls)

This is the gold standard for constraint enforcement - all three constraint types validated!

Methodology

This analysis used Strategy 028: Constraint Coverage & Enforcement Gap Analysis:

1. Extract all constraints from main_workflow_schema.json using Python JSON parser

   • Found: 17 minLength, 3 maxLength, 52 minimum, 30 maximum, 18 minItems, 0 maxItems, 25 pattern, 0 format

2. Trace each constraint to runtime validation code

   • Search for validateIntRange, ValidateMinLength, ValidateMaxLength, ValidatePattern calls
   • Cross-reference schema field paths with Go struct tags and validation functions

3. Identify gaps where schema declares constraints but runtime doesn't enforce

   • 4 total gaps found (1 critical persistent, 3 new moderate)

4. Verify positive examples to understand best practices

   • branch-prefix is the gold standard for multi-constraint validation

Run History & Trends

Run #	Date	Critical	Moderate	Resolved	Status
1	2026-01-07	2	3	0	New strategy launch
2	2026-01-13	1	0	1	retention-days fixed ✅
3	2026-01-22	1	3	0	Port still unfixed ❌

Trend Analysis:

• ✅ Positive: 1 critical issue fixed (retention-days) - good responsiveness
• ❌ Concern: sandbox.mcp.port remains unfixed for 15 days
• 🔍 Discovery: 3 new moderate issues found (timeout fields, tracker-id)

Recommendations

Immediate Actions (High Priority)

1. Fix sandbox.mcp.port validation (URGENT - 15 days old)

   • Add validateIntRange(mcpConfig.Port, 1, 65535, "sandbox.mcp.port") call
   • Location: pkg/workflow/frontmatter_extraction_security.go after port extraction
   • Estimated effort: 5 minutes

2. Add timeout field validations

   • tools.timeout: Add minimum validation (minimum: 1)
   • tools.startup-timeout: Add minimum validation (minimum: 1)
   • Location: Where these fields are processed in pkg/workflow/tools*.go
   • Estimated effort: 15 minutes

3. Add tracker-id validation

   • Validate minLength: 8 and pattern: ^[a-zA-Z0-9_-]+$
   • Create validateTrackerId() function following branch-prefix pattern
   • Estimated effort: 20 minutes

Long-term Actions (Medium Priority)

4. Add maxItems constraints to schema

   • Review all array fields and add reasonable upper bounds
   • Prevents DoS via unbounded array growth

5. Add maxLength constraints to strings

   • Currently only 3 fields have maxLength
   • Add reasonable bounds to prevent huge string values

6. Add format constraints

   • Use format: uri for URL fields
   • Use format: email for email fields
   • Enables better validation and documentation

7. Create systematic constraint enforcement tests

   • Add tests that verify all schema constraints have runtime validation
   • Prevent regressions

Strategy Performance

Strategy 028 continues to be highly effective:

• Success Count: 3 runs
• Effectiveness: Very High
• Unique Value: Only strategy focused on constraint infrastructure
• Recommendation: Continue using every 4-5 analyses

Key Strength: Finds bugs where schema documents constraints but runtime doesn't enforce them - these are actual bugs that can cause production issues.

References

• Workflow Run: §21269056069
• Previous Run: 2026-01-13 (9 days ago)
• Strategy Cache: /tmp/gh-aw/cache-memory/strategies.json

AI generated by Schema Consistency Checker

• expires on Jan 29, 2026, 11:53 PM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-01-29T23:53:23.620Z.