fix(creative): clarify preflight dry-run validation

[bokelley]

Clarifies the boundary between validate_input manifest preflight and sync_creatives dry-run trafficking rehearsal across schemas, docs, and training-agent tool descriptions.

Updates sync_creatives dry-run behavior to validate assignment references without mutating package assignments, matching the new operation-level rehearsal language.

Adds a regression test for invalid dry-run assignments and a patch changeset for the protocol-facing clarification.

Validated with schema/type checks, targeted docs JSON checks, changeset checks, the new Vitest regression, and the pre-push storyboard/docs gates.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
adcp	🟢 Ready	View Preview	Jul 1, 2026, 10:20 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[aao-release-bot]

Clean clarification: separates validate_input (manifest-structure preflight) from sync_creatives dry_run: true (operation-level trafficking rehearsal), and makes the training-agent reference implementation match. The boundary is drawn on the right axis — preflight validates shape, dry-run rehearses the seller's account/library/policy path.

Things I checked

• Schema changes are description-only. All four files under static/schemas/source/creative/ touch only description / examples[].description strings. No field renames, type changes, enum changes, required↔optional flips, or oneOf discriminator moves. dry_run stays boolean/default: false; validate-input-result keeps required: ["target","result_kind"] and its three result_kind values intact. Wire-compatible → patch changeset is the correct semver call. (ad-tech-protocol-expert: sound.)
• Schema-vs-docs coherence. The two-primitive narrative matches across sync-creatives-request.json, the three validate-input-*.json files, canonical-formats.mdx, canonical-formats-migration.mdx, and task-reference/sync_creatives.mdx. No drift. The renamed section validate_input vs sync_creatives dry run and its comparison table mirror the schema descriptions.
• The one behavior change is correct. task-handlers.ts:5439-5466 — dry-run now enters the assignment block (was gated out by !isDryRun), validates references against availableCreativeIds (session creatives + non-failed results), returns status: 'error' for bad refs, and gates only the real mutation (pkg.creativeAssignments.push) behind !isDryRun at :5461. Non-dry-run path is unchanged: session.creatives already holds every just-created creative before the loop, so availableCreativeIds is a superset of the old session.creatives.has() check — identical behavior on the happy path.
• No library mutation on dry-run. Creatives stay gated by the existing if (!isDryRun) persist block; the new test asserts list_creatives returns [] after a dry-run sync, and that assertion is genuinely load-bearing (the creative_ids filter runs before the compliance fallback). (code-reviewer: clean, no blockers.)
• Changeset present and typed correctly. .changeset/clarify-creative-preflight.md — patch, wire-touching PR covered.

Minor nits (non-blocking)

1. New test covers the error path only. server/tests/unit/training-agent.test.ts asserts the dry-run missing-package case (status: 'error') but not the more load-bearing invariant: a valid ref on dry_run: true returns status: 'assigned' while pkg.creativeAssignments stays empty. That's the !isDryRun guard at task-handlers.ts:5461 — worth an explicit assertion. Not blocking; the mutation guard is a one-liner and the non-dry-run push is already covered at training-agent.test.ts:4294.

LGTM. Follow-up noted.

[aao-release-bot]

Schema/tool/prose reframing is sound and the dry-run server change is clean — but the new dry-run snippet in sync_creatives.mdx checks assignment errors on a field the published response schema doesn't have, so it fails open on the exact path this PR exists to teach.

The reframing itself is the right shape: validate_input = manifest-structure preflight (no trafficking gates), sync_creatives dry_run:true = non-mutating rehearsal of the actual seller operation. That boundary is now stated coherently across the four schema descriptions, both tool strings, and the three docs. ad-tech-protocol-expert: sound — the four schema touches are description-only, no wire-shape change, patch changeset is correct.

Things I checked

• Schema touches are description-only. Every changed line in the four static/schemas/source/creative/*.json files is a -/+ pair on a description string. dry_run stays {type: boolean, default: false} (sync-creatives-request.json:88); result_kind enum and the oneOf const discriminators on validate-input-result.json are untouched. Not a breaking change. patch is right.
• Dry-run server change leaks no state. handleSyncCreatives now seeds availableCreativeIds from session.creatives.keys() plus non-failed results, validates assignment references, and gates the only mutation — pkg.creativeAssignments.push — behind !isDryRun (task-handlers.ts:204). Creative persistence at :5411 was already !isDryRun. Non-dry-run is equivalent to the prior session.creatives.has() check. code-reviewer: ready to push.
• Regression test covers the new path. training-agent.test.ts:4335 asserts dry-run returns assignments[0].status === 'error' ("Package not found") and list_creatives returns []. On base the block was skipped in dry-run, so this genuinely exercises new behavior.
• The response schema has no top-level assignments[]. grep confirms it exists only in the request. The success shape carries assignment outcomes per-creative via assigned_to[] and assignment_errors{} (sync-creatives-response.json:83-100).

The question that flips this to approve

sync_creatives.mdx:113-116 (JS) and :124-127 (Python) detect assignment failures via validated.assignments?.some(a => a.status === "error") / getattr(result, 'assignments', []). That top-level assignments[] does not exist on SyncCreativesResponseSchema — a spec-conformant seller returns assignment failures in the per-creative assignment_errors map. So the branch never fires against the wire contract: creative uploads clean, package assignment fails, and the snippet prints "Validation passed! Ready to sync." The creative.action === "failed" sibling branch is correct (sync-creatives-response.json:40, creative-action.json) — only the assignment branch is wrong. Rewrite both to read assignment_errors per creative and I'll approve.

The shape the snippet checks is the one the training-agent runtime emits (task-handlers.ts:5471), not the one the published schema documents — an easy shape to reach for when the reference server is what you're testing against.

Follow-ups (non-blocking — file as issues)

• The training-agent runtime returns a top-level assignments[] with status, which sync-creatives-response.json doesn't model. Pre-existing divergence the snippet leaned on; worth reconciling the reference server to the published response shape (per-creative assignment_errors).
• training-agent.test.ts:4335 only covers the package-not-found branch. Add a dry-run happy-path case (valid media buy + package + creative) asserting pkg.creativeAssignments stays unmutated — the !isDryRun push guard itself is currently untested.

Minor nits (non-blocking)

1. "Dry run" doc section doesn't show where assignment errors live. sync_creatives.mdx:816-819 now promises dry-run returns "assignment errors" but never points at assignment_errors. One accurate example closes the loop the snippet above opens.

LGTM after the two snippets read assignment_errors. Everything else is clean.