Stabilize the SQL enqueue contract as a public producer API

[hardbyte]

Problem

Awa's positioning is "Postgres job queue for Rust and Python", but a very common fleet shape is a third language on the producer side only — a Node/Go/JVM service enqueueing work for Rust/Python workers. Awa is closer to supporting this than the docs admit:

• awa.insert_job_compat(...) is a complete SQL enqueue entry point (kind, queue, args, priority, run_at, metadata, tags, unique_key, unique_states).
• docs+test: SQL-only install/upgrade path for external migration tooling #314 documented and tested the SQL-only install/upgrade path for external migration tooling, so non-Rust deployments already have a schema story.

What's missing is the decision and contract, not the mechanism: today insert_job_compat is an internal detail that any migration may change without notice.

Proposal

Decide whether the SQL enqueue surface is a stable public API. If yes:

1. Document the contract: function signature, parameter semantics, returned row shape, error codes (e.g. unique-conflict), and the NOTIFY wakeup behaviour producers get for free.
2. Version it: tie the contract to the migration version table; document that breaking changes get a new function name or an explicit major-version note.
3. Cross-language uniqueness: unique_key is a BLAKE3 hash computed client-side (ADR-002). A non-Rust producer needs the exact derivation (input canonicalization, what by_args/by_queue fold in) documented, or uniqueness silently diverges between languages.
4. Ordering keys: same for ordering_key → shard derivation (ADR-025) if external producers should compose with sharded FIFO queues.
5. Contract tests: a SQL-level test (psql fixture or pgTAP) that pins the public surface so a migration that breaks it fails CI, plus a docs example in one non-supported language (plain node-postgres or pgx snippet) to prove the path.

Explicitly out of scope: official client libraries for other languages. The contract makes external producers possible and safe; maintaining idiomatic clients stays out of the core scope.

Refs: ADR-002, ADR-016, ADR-025, #314, docs/positioning.md.