Improve slug reliability

[jmankoff]

We are moving toward a slug-first API model: clients should primarily use slugs for resource interaction, while UUID ids remain internal and used when needed for performance or internal joins.

Currently:

• Collection endpoints return both product_ids and product_slugs in read responses (see collections.py:366, collections.py:512).
• Existing tests include baseline product_slugs coverage (see test_collections.py:291).
• Documentation in API_REFERENCE.md does not yet fully specify slug-first collection response semantics and edge cases.

Todo:

• Expand collection response contract tests in test_collections.py and adjust router behavior only if needed in collections.py.
• Document collection response contract explicitly in API_REFERENCE.md, including slug-first guidance
• Encode slug-first API usage in tests and docs.
• Keep ids available for internal use/performance and backward compatibility where needed.

Tests

• verify product_slugs ordering matches product_ids ordering for collection detail responses.
• verify graceful behavior when a slug cannot be resolved for an item (expected null in aligned position, not dropped/reordered).
• verify slug-based add and fetch across mixed slug/id endpoint usage paths.
• verify duplicate-prevention behavior remains correct when mixed slug/id identifiers refer to the same product.

Announcement

Add note to API docs changelog/release notes stating:

• Deprecation notice (no removal in this ticket)
• product_ids are deprecated for external client usage (not removed yet).

Add a short “slug-first” note in collection endpoint docs/examples.

Open follow-up issue: “Deprecate/remove product_ids from collection responses.”

Out of scope / future work

• Removing ids from API responses.
• Schema redesign unrelated to collection response contract.
• Deprecate product_ids from collection API responses (slug-only external contract)