[Schema Consistency] Schema Consistency Check 2026-06-13 — engine.extensions parsed but missing from schema (blocks Pi engine feature)

[github-actions[bot]]

Summary

• Inconsistencies Found: 2 (1 high-severity new, 1 low-priority re-confirmed)
• Categories Analyzed: Schema ↔ Parser, Schema ↔ Docs, Schema ↔ Workflows
• Strategy Used: strategy-25 Engine sub-object key coverage (newly generalized from strategy-24)
• New Strategy: YES (day-of-year mod 10 = 4 → proven-strategy mode; generalized an existing high-signal proven strategy to a nested config object)

This run drilled into nested config objects rather than top-level fields. The pre-computed field_gaps are dominated by top-level keys that are accessed via map[string]any (no yaml tags) and are well-covered, so the high-signal work is in sub-objects guarded by additionalProperties: false. Diffing the keys the parser actually reads from the engine: object against the schema's engine_config branches surfaced a real, working feature that schema validation rejects.

Critical Issues

🔴 engine.extensions is parsed and used by the Pi engine but absent from the schema

The compiler fully supports an extensions array under engine: (used by the Pi engine to install extensions), but the JSON schema does not declare it in any engine_config branch — and every branch sets additionalProperties: false. Because frontmatter is validated against the schema at compile time, any real workflow using this feature fails validation and shows editor squiggles, even though the compiler would handle it correctly.

Evidence:

• Parser reads it: pkg/workflow/engine.go:468-490
  • // Extract optional 'extensions' field (array of strings; used by the Pi engine)
  • if extVal, hasExt := engineObj["extensions"]; hasExt { ... config.Extensions = ... }
• Stored on the config struct: pkg/workflow/engine.go:74 → Extensions []string
• Consumed by the Pi engine: pkg/workflow/pi_engine.go:204-218 generates an install step per extension (example values ["@pi/web-search", "@pi/file-browser"], see pkg/workflow/cache_memory_prompt_test.go:154)
• Schema gap: pkg/parser/schemas/main_workflow_schema.json → $defs.engine_config has no extensions property in any of its 6 oneOf branches, all additionalProperties: false
• Validation is enforced: parser.ValidateMainWorkflowFrontmatterWithSchemaAndLocation(...) at pkg/workflow/compiler_orchestrator_frontmatter.go:140 (uses santhosh-tekuri/jsonschema/v6)
• Not documented in docs/src/content/docs/reference/engines.md

Confirmation it is the only such gap: diffing every engineObj["key"] the parser reads against the union of all engine_config branch properties yields exactly one parser-read key missing from the schema: extensions. (Schema-only keys description, display-name, models, options, runtime-id belong to the AWF custom-provider branch and are handled in awf_config.go — not a gap.)

Impact: A working compiler feature is effectively unusable through the normal validated path. engine: { id: pi, extensions: ["@pi/web-search"] } errors with additionalProperties 'extensions' not allowed.

Suggested fix

Add extensions to the Pi-capable engine_config branch(es) in main_workflow_schema.json:

"extensions": {
  "type": "array",
  "items": { "type": "string" },
  "description": "Engine extensions to install (used by the 'pi' engine), e.g. \"`@pi/web-search`\"."
}

Then document it under docs/src/content/docs/reference/engines.md. Alternatively, if engine.extensions is considered dead/experimental, remove the parser path so the two sources agree.

Schema Improvements Needed

🟡 Low priority — re-confirmed: dispatch-repository dash alias not in schema

The parser accepts both dispatch_repository (underscore, preferred) and dispatch-repository (dash) as a safe-output key (pkg/workflow/dispatch_repository.go:38-39), but the schema only defines dispatch_repository (main_workflow_schema.json:9095) while safe-outputs has additionalProperties: false. The dash spelling is therefore rejected by schema validation despite parser/test/doc support. Fix: either add a dispatch-repository alias property to the schema, or drop the dash alias from the parser and docs. (Tracked since 2026-06-12; still open.)

Parser Updates Required

None — the parser is correct in both findings; the schema is the lagging source of truth.

Workflow Violations

No .github/workflows/*.md file currently uses engine.extensions or the dispatch-repository dash spelling, so no existing workflow is broken. The risk is for authors who try to use these documented/working features.

Recommendations

1. (High) Add extensions (array of strings) to the Pi-capable engine_config branch in main_workflow_schema.json and document it in engines.md.
2. (Low) Resolve the dispatch-repository alias gap by adding the dash alias to the schema or removing it from parser/docs.
3. (Process) Add a regression guard: a unit test that diffs engineObj["..."] reads in engine.go against the union of engine_config branch properties, failing when a parser-read key is absent from the schema. This same additionalProperties:false sub-object diff generalizes to safe-outputs.* and tools.*.

Strategy Performance

• Strategy Used: strategy-25 — Engine sub-object key coverage (generalized from the high-signal strategy-24)
• Findings: 1 high-severity new + 1 low re-confirmed
• Effectiveness: HIGH
• Should Reuse: YES — extend the same additionalProperties:false parser-vs-schema diff to other nested objects (safe-outputs entries, tools sub-objects) on the next run

Next Steps

• Add engine.extensions to the schema
• Document engine.extensions in engines.md
• Add regression test diffing parser-read engine keys vs schema branches
• Resolve dispatch-repository dash alias (schema add or parser/doc removal)

References: §27459320087

Generated by ✅ Schema Consistency Checker · 117.8 AIC · ⌖ 32.1 AIC · ⊞ 9.5K · ◷

• expires on Jun 13, 2026, 10:46 PM UTC-08:00