Summary
docs/building/by-layer/L1/request-signing.mdx § ### Conformance vectors refers to the vector set at compliance/cache/3.0.0/test-vectors/request-signing/ twice — once in prose, once as a copy-pasteable command argument:
adcp signing verify-vector \
--vector compliance/cache/3.0.0/test-vectors/request-signing/positive/001-basic-post.json
Two things are wrong here, and the second is why I did not just fix the first.
1. 3.0.0 is a moving path frozen as a literal
Per scripts/overlay-compliance-cache.sh, compliance/cache/<version>/ is the SDK's bundled compliance cache under node_modules/@adcp/sdk/compliance/cache/<version>/, where <version> is read from node_modules/@adcp/sdk/ADCP_VERSION — the SDK's pinned AdCP version:
CACHE_ROOT="node_modules/@adcp/sdk/compliance/cache"
ADCP_VERSION_FILE="node_modules/@adcp/sdk/ADCP_VERSION"
...
DST="$CACHE_ROOT/$PINNED_VERSION"
The script comments call this out explicitly — "SDK 5.13 moved the cache dir from latest to the AdCP version string", and it resolves the value at runtime precisely "so the overlay doesn't have to bump with every SDK release." The docs then hardcode one snapshot of that value.
Two failure modes:
- Loud — the path does not exist on a current SDK, and the command fails.
- Quiet, and worse — an older SDK makes
3.0.0 exist, so the user grades the 3.0.0 vector set: 39 vectors rather than 40, missing 028-unsigned-protocol-method-required, and reports a clean pass against a stale contract.
Elsewhere in the repo the same path is written with a placeholder — server/src/services/storyboards.ts: "Storyboard YAML definitions live under compliance/cache/{version}/" — and the runner header uses /compliance/{version}/test-vectors/request-signing/. The docs page is the outlier.
These two lines are the only hardcoded-version occurrences of compliance/cache/ in the repo outside dist/:
docs/building/by-layer/L1/request-signing.mdx:711
docs/building/by-layer/L1/request-signing.mdx:719
2. The --vector flag may not exist
This is the part I could not settle from this repo, and it blocks a confident fix.
docs/building/verification/grading.mdx — the CLI reference page — documents the same subcommand differently:
npx @adcp/sdk@latest signing verify-vector
Reads a vector from stdin (JSON matching the test-vector schema at /compliance/latest/test-vectors/request-signing/) …
So the reference page says stdin, no --vector flag, and refers to the vector set by its published URL with the latest alias — not a node_modules cache path at all. The implementation guide says --vector <path> into the SDK's internal cache. Both cannot be right.
The CLI lives in @adcp/sdk, not in this repo, so I cannot verify which form is correct from here.
Why I left it rather than guess
Correcting only 3.0.0 → a placeholder would leave a command whose flag may not exist and whose path form may be wrong in kind, not just in version — a cosmetic fix that makes a broken snippet look maintained. Whoever fixes this should settle the CLI surface first.
Suggested fix, once the CLI form is confirmed
- If
verify-vector reads stdin: rewrite the snippet to match grading.mdx and refer to vectors by the published /compliance/latest/… URL, dropping the node_modules path entirely.
- If
--vector <path> is real: use a version placeholder and say how to resolve it (cat node_modules/@adcp/sdk/ADCP_VERSION), rather than a literal.
- Either way, reconcile the two pages so one CLI has one documented invocation.
Scope note
Line 711 is edited by #6074 (approved, green), so a fix here should land after it to stay conflict-free.
Related
Summary
docs/building/by-layer/L1/request-signing.mdx§### Conformance vectorsrefers to the vector set atcompliance/cache/3.0.0/test-vectors/request-signing/twice — once in prose, once as a copy-pasteable command argument:Two things are wrong here, and the second is why I did not just fix the first.
1.
3.0.0is a moving path frozen as a literalPer
scripts/overlay-compliance-cache.sh,compliance/cache/<version>/is the SDK's bundled compliance cache undernode_modules/@adcp/sdk/compliance/cache/<version>/, where<version>is read fromnode_modules/@adcp/sdk/ADCP_VERSION— the SDK's pinned AdCP version:The script comments call this out explicitly — "SDK 5.13 moved the cache dir from
latestto the AdCP version string", and it resolves the value at runtime precisely "so the overlay doesn't have to bump with every SDK release." The docs then hardcode one snapshot of that value.Two failure modes:
3.0.0exist, so the user grades the 3.0.0 vector set: 39 vectors rather than 40, missing028-unsigned-protocol-method-required, and reports a clean pass against a stale contract.Elsewhere in the repo the same path is written with a placeholder —
server/src/services/storyboards.ts: "Storyboard YAML definitions live undercompliance/cache/{version}/" — and the runner header uses/compliance/{version}/test-vectors/request-signing/. The docs page is the outlier.These two lines are the only hardcoded-version occurrences of
compliance/cache/in the repo outsidedist/:2. The
--vectorflag may not existThis is the part I could not settle from this repo, and it blocks a confident fix.
docs/building/verification/grading.mdx— the CLI reference page — documents the same subcommand differently:So the reference page says stdin, no
--vectorflag, and refers to the vector set by its published URL with thelatestalias — not anode_modulescache path at all. The implementation guide says--vector <path>into the SDK's internal cache. Both cannot be right.The CLI lives in
@adcp/sdk, not in this repo, so I cannot verify which form is correct from here.Why I left it rather than guess
Correcting only
3.0.0→ a placeholder would leave a command whose flag may not exist and whose path form may be wrong in kind, not just in version — a cosmetic fix that makes a broken snippet look maintained. Whoever fixes this should settle the CLI surface first.Suggested fix, once the CLI form is confirmed
verify-vectorreads stdin: rewrite the snippet to matchgrading.mdxand refer to vectors by the published/compliance/latest/…URL, dropping thenode_modulespath entirely.--vector <path>is real: use a version placeholder and say how to resolve it (cat node_modules/@adcp/sdk/ADCP_VERSION), rather than a literal.Scope note
Line 711 is edited by #6074 (approved, green), so a fix here should land after it to stay conflict-free.
Related
3.0.0was the right cache directory when written" instance