feat(db): add freeform client_key for idempotent upload registration

Persist owner-scoped client_key on freeform_documents so upload create
can retry safely without inventing local doc-upload orphans.

Co-authored-by: Cursor <cursoragent@cursor.com>

deploy/postgres/goose/00029_2026-09-13-freeform-client-key.sql

@@ -0,0 +1,18 @@
+-- +goose Up
+-- 2026-09-13 freeform upload registration: formal client_key for idempotent server fact-source create
+-- Schema 28 → 29
+
+ALTER TABLE freeform_documents
+    ADD COLUMN IF NOT EXISTS client_key VARCHAR(128) NULL;
+
+COMMENT ON COLUMN freeform_documents.client_key IS
+    'Client-supplied idempotency key for direct create (e.g. upload batch id); NULL for message-derived docs';
+
+-- Same owner cannot register the same client_key twice while the doc is alive.
+CREATE UNIQUE INDEX IF NOT EXISTS uq_freeform_owner_client_key
+    ON freeform_documents (owner_user_id, client_key)
+    WHERE is_deleted = FALSE AND client_key IS NOT NULL AND length(trim(client_key)) > 0;
+
+-- +goose Down
+DROP INDEX IF EXISTS uq_freeform_owner_client_key;
+ALTER TABLE freeform_documents DROP COLUMN IF EXISTS client_key;