Spec gap: multiple-file loading order relative to Phase A template rendering is undefined #11

New issue

Open

opened 2026-05-27 05:25:31 +00:00 by hurui200320 · 0 comments

hurui200320 commented

2026-05-27 05:25:31 +00:00

Member

Problem

§3.1 specifies that a compliant implementation MUST support merging multiple Actor configuration files:

For each key encountered in a subsequent file: if absent, add it; if both mappings, deeply merge; if both sequences, append; otherwise replace.

§8.2 specifies the Phase A document-level template rendering lifecycle, where the raw YAML text is rendered as a Jinja2 template before YAML parsing.

These two features interact in an underspecified way. Consider two files where both contain agents: sections and the first uses Phase A {% for %} loops:

Option A: Each file is independently Phase-A-rendered, then the resulting YAML documents are deep-merged. This allows each file to have its own isolated template context.
Option B: All files are text-concatenated first, then rendered as a single Phase A template. This allows templates in one file to reference variables defined in another.
Option C: Files are YAML-parsed first (without Phase A rendering), then merged, and the merged document is Phase-A-rendered as a single pass. This breaks any file that uses Phase A loops to generate YAML keys.

Each option produces different results and has different failure modes. The spec gives no guidance.

Impact on Library Implementation

The file loading pipeline must be designed around one of these models. Choosing the wrong one means that multi-file configurations authored for a different model will silently produce wrong or broken results.

Decision Needed

Define the multi-file loading order relative to Phase A rendering:

When does Phase A rendering happen — per-file or on the merged document?
Is the Phase A rendering context shared across files?
Are template expressions in one file visible to another file's template context?

References

§3.1 — File Format (multi-file merge semantics)
§8.2 — Document-Level Rendering Lifecycle
§8.4 — Deferred Rendering and Field Protection

## Problem §3.1 specifies that a compliant implementation MUST support merging multiple Actor configuration files: > For each key encountered in a subsequent file: if absent, add it; if both mappings, deeply merge; if both sequences, append; otherwise replace. §8.2 specifies the Phase A document-level template rendering lifecycle, where the raw YAML text is rendered as a Jinja2 template **before** YAML parsing. These two features interact in an underspecified way. Consider two files where both contain `agents:` sections and the first uses Phase A `{% for %}` loops: - **Option A**: Each file is independently Phase-A-rendered, then the resulting YAML documents are deep-merged. This allows each file to have its own isolated template context. - **Option B**: All files are text-concatenated first, then rendered as a single Phase A template. This allows templates in one file to reference variables defined in another. - **Option C**: Files are YAML-parsed first (without Phase A rendering), then merged, and the merged document is Phase-A-rendered as a single pass. This breaks any file that uses Phase A loops to generate YAML keys. Each option produces different results and has different failure modes. The spec gives no guidance. ## Impact on Library Implementation The file loading pipeline must be designed around one of these models. Choosing the wrong one means that multi-file configurations authored for a different model will silently produce wrong or broken results. ## Decision Needed Define the multi-file loading order relative to Phase A rendering: 1. When does Phase A rendering happen — per-file or on the merged document? 2. Is the Phase A rendering context shared across files? 3. Are template expressions in one file visible to another file's template context? ## References - §3.1 — File Format (multi-file merge semantics) - §8.2 — Document-Level Rendering Lifecycle - §8.4 — Deferred Rendering and Field Protection

Rows
Columns