Function canonicalDeclarationFromBareId

Resolve a bare v1 format-id string to its full v2 ProductFormatDeclaration, or null when the id has no canonical mapping.

Adopters migrating off legacy format storage routinely hold a bare id (display_300x250_image, video_standard_30s) persisted before the { agent_url, id } structured-ref convention. This lifts that bare id to a structured ref (via agentUrl, default the AAO host) and runs the exact resolution the v1 → v2 product projection uses — in the registry spec's v1-canonical-mapping.json resolution order:

• AAO catalog canonical: annotation — the authoritative seller-asserted mapping (registry resolution-order step 2).
• Registry format_id_glob literal match (registry resolution-order step 3) — future-proof; 3.1 ships zero literal globs, so this fires only when a future registry adds platform-specific literals.

Fails closed: returns null — never a guess — when neither path resolves the id. That covers an unknown id, an under-specified id (display_300x250, which the catalog only carries as _image / _html / _generative variants), and a catalog entry the AAO has not yet annotated with a canonical:. Structural matching never contributes a kind: a bare id absent from the catalog carries no asset shape to match on, and a catalog entry lacking a canonical: fails closed before the structural step is reached.

For an under-specified bare id, pass assetType (the asset type you already hold, such as an adopter's format_type) and the resolver retries the disambiguated catalog variant <id>_<suffix> — so the SDK owns the _image / _html suffix convention instead of every adopter re-deriving it. The hint is consulted only when the bare id doesn't resolve on its own, and still fails closed when the disambiguated id isn't a catalog entry.

The returned declaration carries v1_format_ref: [{ agent_url, id }] (the resolved id — the disambiguated <id>_<suffix> when a hint applied), so adopters lift a bare id to a structured ref in one step (the pre-projection step the migration docs encourage).

Like the rest of the projection layer, this requires the bundled AAO catalog + canonical-mapping registry; it throws (rather than returning null) only when those are missing from the install — a corrupted @adcp/sdk package, not a normal unresolved-id outcome.

For just the format_kind, use resolveCanonicalFormatKind. For the structured diagnostic explaining why an id did not resolve, run it through projectV1ProductToV2 inside a one-format product.