Declared vs. Proven

Proving parallel execution from timestamps

The Gap

A recipe can say `parallel: 3`—but that's intent, not proof

A config flag declares what should run concurrently. It never shows what actually ran. This deck closes that gap: from the declaration, to the engine, to the telemetry that proves it.

Start with the declaration itself—and prove it's real.

Proof — The Declaration Is Real

A real recipe declares `parallel: 3` on a foreach step

document-generation.yaml v8.1.0 runs a foreach step, run-content-checks, over 3 content checks—accuracy, completeness, instructions—with parallel: 3 and agent foundation:zen-architect.

So the intent is on the record. But intent is all it is.

# document-generation.yaml (v8.1.0)
# step id: run-content-checks
foreach: "{{content_check_definitions}}"
as: "check"
parallel: 3
agent: "foundation:zen-architect"
mode: "REVIEW"
# 3 checks: accuracy, completeness, instructions

Tension

A YAML flag is a promise, not a proof

Nothing in the config rules out the executor silently serializing the checks. A flag could be mis-wired, ignored, or queued one-behind-the-next—and the YAML would look identical either way.

To trust it, stop reading the config and start measuring the execution.

Mechanism

`asyncio.gather` + `Semaphore(N)` turns the flag into concurrency

The executor's _execute_loop_parallel runs iterations through asyncio.gather, bounded by asyncio.Semaphore(N): parallel: true is unbounded, parallel: N caps at N concurrent.

The bound is real—so how do we watch it happen from outside?

# executor.py — _execute_loop_parallel
semaphore = asyncio.Semaphore(max_concurrent) if max_concurrent else None

async with semaphore:
    # run one iteration
    ...

raw_results = await asyncio.gather(*tasks, return_exceptions=True)

Setup — The Telemetry

Every spawn emits a `session:fork` event you can read

Each iteration's spawn records a session:fork event carrying an ISO-8601 millisecond ts and a parallel_group_id the executor stamps across the whole batch.

One shared group id, many timestamps—now you can correlate them.

// events.jsonl — a real fork event
{
  "ts": "2026-07-15T05:03:01.563464584+00:00",
  "event": "session:fork",
  "data": { "metadata": {
    "agent_name": "foundation:explorer",
    "parallel_group_id": "6d9f79f6-…-a187ed36b0a7"
  }}
}

The Turn — The Method

Correlate fork timestamps by `parallel_group_id`

Group forks by their shared id and read the timestamps: launched together means concurrent; one-behind-the-next means queued. The bound shows itself as waves.

5 quality checks at parallel: 3 run as 2 waves—3, then 2.

Wave 1 (3 concurrent)

depth

coherence

crossrefs

Wave 2 (2 concurrent)

consistency

tone

5 quality checks · parallel: 3 · Semaphore(3) → 2 waves (3 + 2)

Payoff

Verify, don't trust: config declares, timestamps prove

The declaration is git-verifiable. The proof of concurrency lives only in runtime fork timestamps—which is exactly the honest catch.

Because timestamps aren't git-verifiable, the reproducible method is the deliverable.

The load-bearing caveat. Timestamps are runtime artifacts, not stored in the repo. Any exact values vary between executions—the method is what reproduces, not the numbers.

Takeaway

Don't read the flag—find the telemetry that proves it

For any declared behavior, a declaration is a claim. Execution must be measured. Find the events the runtime already emits, correlate them, and let the data render the verdict.

Declaration is intent. Correlated telemetry is proof.

Sources

Research Methodology

Feature status: SHIPPED / REAL for the mechanism and the recipe declaration.

Verification commands run:

sed -n '1736,1742p' recipes/document-generation.yaml — confirms run-content-checks: parallel: 3, agent foundation:zen-architect.
grep -n '"type": "accuracy|completeness|instructions"' + sed -n '1690,1725p' … — 3 content checks launch in one wave.
grep -n 'depth|coherence|crossrefs|consistency|tone'; sed -n '2142,2145p' … — 5 quality checks at parallel: 3 → 2 waves.
grep -n 'Semaphore|asyncio.gather' + sed -n '2320,2440p' executor.py — _execute_loop_parallel uses asyncio.gather + asyncio.Semaphore(N).
python3 parse of ~/.amplifier/projects/**/events.jsonl — real session:fork events carry ms-precision ts + shared parallel_group_id.
grep -rn 'parallel: 3' amplifier-bundle-recipes/examples/; git show -s dfe6875 — example recipes + the cap of unbounded parallel: true to parallel: 3.
git show -s 0cf1d50 375aaed (microsoft/amplifier, author Mollie Munoz) — v8.0.0 parallel-validation merge and v8.1.0 follow-up.

Primary contributors: Mollie Munoz (document-generation v8.0.0 parallel-validation merge + v8.1.0); Amplifier bot (capped unbounded parallel: true → parallel: 3, microsoft/amplifier-bundle-recipes).

Gaps / honest limits: Specific measured timestamps, start spreads, and speedup percentages are runtime artifacts and are not git-verifiable; exact values vary between executions. The executor source lives in the installed Amplifier bundle cache, not a checked-out git tree; the primary recipe copy inspected is under an Inactive/ path.

Declared vs. Proven

A recipe can say parallel: 3—but that's intent, not proof

A real recipe declares parallel: 3 on a foreach step