docs(errors): follow-up to #2595 — transport-errors cross-ref, alias template, narrative drift#2596
Conversation
…template, narrative drift Addresses protocol-review feedback on the merged error-model PR #2595: 1. transport-errors.mdx — add "Envelope vs. payload errors" section cross-linking to the normative two-layer model. Previously the normative text only lived in error-handling.mdx; readers who landed on transport-errors had no pointer. 2. transport-errors.mdx — add "Storyboard check: error_code contract" section. Promotes the shape-agnostic extraction contract from a storyboard-schema.yaml comment to spec-grade text so @adcp/client implementers can find it without grepping compliance source. 3. transport-errors.mdx — new client-detection step 6 for payload.errors[0] as a fallback path, making the two-layer detection explicit in code. 4. state-machine.yaml — replace INVALID_STATE_TRANSITION → INVALID_STATE in narrative/expected prose (validator assertions were already INVALID_STATE; the prose was drifting). 5. comply-test-controller.mdx — add a Note clarifying the controller response enum (INVALID_TRANSITION/INVALID_STATE/NOT_FOUND/etc. per comply-test-controller-response.json) is controller-specific and distinct from the canonical seller error-code.json. The transition- vs-state distinction is meaningful at the state-machine primitive layer; storyboard assertions on controller responses use path: "error", not check: error_code. 6. static/schemas/source/enums/error-code-aliases.json — new template file with an empty aliases map and a self-describing JSON Schema. Documents the alias shape so future renames have a home without ad- hoc invention. tests/schema-validation.test.cjs updated to skip files whose $id ends in -aliases.json from the enum-values check. All tests clean: schemas, examples, error-codes lint, unit, typecheck.
Schema Link Check ResultsCommit:
|
|
Reviewed as the follow-up to merged #2595 closing issue #2588 (error-code taxonomy + lint). One real question and one cross-cutting concern with the sister PR #2593. Question — is
|
… data Reviewer concern on PR #2596: error-code-aliases.json was a hybrid schema+instance file (JSON Schema declaring its own shape AND an instance of itself, permitted by additionalProperties: true). Unusual, and likely to confuse tooling that expects /schemas/ paths to be pure schemas. Fix: move to scripts/error-code-aliases.json — pure data, sits next to the lint script that reads it. No JSON Schema wrapper; just {"aliases": {}} with a $_comment$ documenting the shape. Touches: - scripts/error-code-aliases.json (new, pure data) - scripts/lint-error-codes.cjs (ALIAS_PATH points at new location) - static/schemas/source/enums/error-code-aliases.json (removed) - tests/schema-validation.test.cjs (revert the `-aliases.json` skip — the file no longer sits under /schemas/, so the enum-values test doesn't need to exclude it) - docs/contributing/storyboard-authoring.md (reference path updated)
|
On the "is
Interpretation (b) from the review (" Structural — hybrid schema/instance file: fair critique. Addressed in 611adc3 — moved the alias registry from |
|
Correction — retracting my earlier question about the empty
This PR is fixing the drift, not cataloguing a rename. Empty Apologies for the noise — structural nit about the hybrid schema+instance file still stands (worth a separate cleanup), but the core finding was wrong. Reading #2596 as ship-ready. Side note — our training-agent PR emitted |
1 participant
Summary
Follow-up to the merged #2595 (error model) addressing protocol-review feedback that landed after merge.
What changed
transport-errors.mdx— new "Envelope vs. payload errors" section with a table + cross-link to the normative two-layer model inerror-handling.mdx. Previously the normative text only lived inerror-handling.mdx; readers who landed ontransport-errorshad no pointer to the payload layer.transport-errors.mdx— new "Storyboard `check: error_code` contract" section. Promotes the shape-agnostic extraction rule from a YAML comment instoryboard-schema.yamlto spec-grade text so@adcp/clientimplementers can find it without grepping compliance source.transport-errors.mdx— adds a sixth client-detection step forpayload.errors[0]as a payload-layer fallback, making the two-layer detection order explicit in prose.state-machine.yaml— prose drift fix. ReplacesINVALID_STATE_TRANSITION→INVALID_STATEin narrative/expected strings (validator assertions were alreadyINVALID_STATE; the prose was out of sync).comply-test-controller.mdx— controller-enum clarification note. The controller'serrorfield uses a controller-specific vocabulary defined incomply-test-controller-response.json(INVALID_TRANSITION,INVALID_STATE,NOT_FOUND,UNKNOWN_SCENARIO,INVALID_PARAMS,FORBIDDEN,INTERNAL_ERROR). This is distinct from the canonical sellererror-code.jsonenum — the transition-vs-state distinction is meaningful at the state-machine primitive layer. Storyboard assertions on controller responses use `path: "error"`, not `check: error_code`.New
static/schemas/source/enums/error-code-aliases.jsontemplate. Self-describing JSON Schema with an emptyaliasesmap. Documents the alias shape so future renames have a home without ad-hoc invention. Lint continues to warn-only on aliased codes.tests/schema-validation.test.cjsupdated to skip files whose$idends in-aliases.jsonfrom the enum-values check.storyboard-authoring.md— updated alias-file docs with the actual JSON shape so authors don't have to grep for it.Why this is a follow-up, not an amend
PR #2595 was merged before expert review completed. Rather than revert or amend, this PR lands the review feedback on top of main. Nothing in this PR is load-bearing — it's clarifying the normative rules that already exist, fixing drift between narrative prose and validator assertions, and putting the alias-file convention on disk so the next rename has a clear home.
Test plan
npm run test:schemas— all 7 tests pass (the enum-values test now skips*-aliases.jsonfiles)npm run test:examples— 31 validations passnpm run test:error-codes— clean (0 errors, 1 pre-existing YAML warning)npm run test:unit— 627 passnpm run typecheckcleannpm run build:compliancecleanExpert reviews that drove this:
ad-tech-protocol-expert+code-reviewerpost-hoc review of #2595.🤖 Generated with Claude Code