fix(storyboard): refs_resolve follow-ups (#710, #711, #712, #714)

[bokelley]

Summary

Bundle of four refs_resolve validator fixes surfaced by security/protocol review on adcontextprotocol/adcp#2601. Each fix closes a dedicated issue and ships with its own changeset.

• refs_resolve $agent_url should canonicalize transport path before scope compare #710 — Canonicalize \$agent_url by stripping transport suffixes (/mcp, /a2a, /sse, /.well-known/agent[-card].json) while preserving subpath. Mirrors SingleAgentClient.computeBaseUrl. Previously, the scope compare degraded to a silent no-op on every MCP/A2A agent because the runner's target URL never equalled the bare agent URL on refs. Path-preserving matters: AdCP agent_url can legitimately live under a subpath (https://publisher.com/.well-known/adcp/sales) — origin-only would false-positive sibling agents on shared hosts.

• refs_resolve: warn when scope filter excludes 100% of source refs #711 — Emit scope_excluded_all_refs meta-observation when a scope filter partitions 100% of source refs out. Catches the silent-no-op smell even when the underlying comparison is broken. Suppressed under on_out_of_scope: 'ignore' (which explicitly opts out of scope warnings).

• refs_resolve: pagination of list_creative_formats target #712 — Detect paginated current-step targets (pagination.has_more: true) and demote unresolved refs to unresolved_with_pagination observations instead of failing the check. Stops false positives against conformant paginating sellers. target_paginated meta-observation surfaces the partition decision. The spec-level fix (compliance mode requires seller returns all product-referenced formats in a single response) should follow in the AdCP repo.

• refs_resolve: observations payload hygiene (userinfo strip, size caps, escaping) #714 — Harden grader-visible payloads: strip userinfo via WHATWG URL parsing plus a regex fallback for credential-shaped substrings in non-URL fields; replace non-http(s) schemes (blocks javascript: / data: / file: stored-XSS vectors) with a placeholder; code-point-safe truncate at 512 chars; cap observations at 50 with observations_truncated marker; use hasOwnProperty throughout to prevent storyboard authors from drawing match keys from Object.prototype.

Expert review notes

Routed through code-reviewer, security-reviewer, and ad-tech-protocol-expert before pushing. Key incorporated feedback:

• Protocol — flagged that origin-only canonicalization (my first draft) contradicts the AdCP schema's own agent_url examples (core/format-id.json shows https://publisher.com/.well-known/adcp/sales). Rewrote to path-preserving + transport-suffix-stripping.
• Protocol — flagged that #712 needs to demote failure → observation, not just annotate. Implemented.
• Security — non-URL userinfo substrings, javascript: scheme survival, key in ref prototype access, pre-truncate ordering. All addressed with dedicated tests.
• Code review — surrogate-pair-safe truncation; positional assertion on meta-observation ordering; stale comment in types.ts. All addressed.

Observation vocabulary

This PR adds three observation kinds the runner emits on refs_resolve results: scope_excluded_all_refs, target_paginated, unresolved_with_pagination, plus observations_truncated marker. The runner-output-contract at compliance/cache/latest/universal/runner-output-contract.yaml is synced from upstream and doesn't yet enumerate an observation taxonomy — documenting these kinds in the source contract belongs in a follow-up PR against adcontextprotocol/adcp.

Test plan

• node --test test/lib/storyboard-validations-refs-resolve.test.js — 39 tests, all pass (18 pre-existing + 21 new covering canonicalization, scope warnings, pagination demotion, and each hardening case)
• npm test — full suite 4965 pass / 0 fail / 6 skipped
• npm run build clean

Changesets

Four patch-level changesets, one per closed issue — lets each fix land with its own CHANGELOG entry in the next release PR.

Closes #710, closes #711, closes #712, closes #714.

🤖 Generated with Claude Code

[bokelley]

Downstream review came back as ship it with three follow-ups. Filed:

• refs_resolve: grader-level flag when target_paginated co-occurs with unresolved_with_pagination (pagination-bypass) #718 — pagination-bypass attack: a malicious seller claiming `pagination.has_more: true` indefinitely gets every unresolved ref demoted to an observation, so a grader scoring on `refs_resolve.passed` alone sees green. Same shape as refs_resolve: warn when scope filter excludes 100% of source refs #711's silent-no-op smell, different trigger. Substantive — needs a separate scoring signal at the grader level.
• Factor out shared transport-suffix registry between SingleAgentClient.computeBaseUrl and storyboard validations canonicalizer #719 — factor out the transport-suffix list (currently duplicated between `SingleAgentClient.computeBaseUrl` and `canonicalizeAgentUrlForScope`). Cleanup; low priority.

Two non-PR items the reviewer is taking themselves:

• Documenting the new observation kinds in upstream `runner-output-contract.yaml` against adcontextprotocol/adcp once fix(storyboard): refs_resolve follow-ups (#710, #711, #712, #714) #717 ships.
• Updating their note in adcp#2601 to reflect landed canonicalization behavior.

Plus one nit deemed not worth fixing here: `CREDENTIAL_SHAPE_RE` doesn't catch `scheme://@host` (bare `@` with empty user). Edge case; mentioned for completeness.