docs: document intentional PUBLIC_WORKSPACE_OWNER_ID upload quarantine

[BigSimmo]

What

Comments-only change (16 insertions, 1 deletion) documenting an intentional design so it isn't mistaken for a bug later:

• src/lib/public-api-access.ts — expand the withOwnerReadScope doc comment: anonymous callers see only the public corpus (owner_id IS NULL); the PUBLIC_WORKSPACE_OWNER_ID upload pool is deliberately excluded (moderation quarantine).
• src/app/api/upload/route.ts — comment explaining anonymous "public" uploads pool under a non-null PUBLIC_WORKSPACE_OWNER_ID and stay out of anonymous viewing and RAG retrieval until an operator promotes them via scripts/promote-public-documents.ts.

Why

While verifying that all Database/RAG document images are viewable without a login, the PUBLIC_WORKSPACE_OWNER_ID pool looked like a visibility gap. On investigation it is the documented public-workspace model (TEN-N3 in docs/tenancy-defense-in-depth-review.md): unreviewed anonymous uploads are quarantined until promoted. These comments prevent a future "fix" that would expose unvetted anonymous uploads to logged-out visitors or the clinical answer corpus.

Verification context (no change in this PR)

Live check confirmed 12,202 / 12,202 document/RAG images are already anonymous-visible (parent owner_id IS NULL, committed generation), and anonymous production fetches return the images end-to-end. Owned/private docs still 404 for anon. This PR changes no behavior.

Clinical governance preflight

N/A — comments only, no behavioral change to ingestion, answer generation, search/ranking, source rendering, document access, privacy, or production config. prettier --check and eslint pass on both files.

🤖 Generated with Claude Code

[supabase]

This pull request has been ignored for the connected project sjrfecxgysukkwxsowpy because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[coderabbitai]

📝 Walkthrough

Walkthrough

Documentation-only changes clarify that pooled anonymous uploads are quarantined for moderation, excluded from anonymous viewing and RAG retrieval, and must be explicitly promoted before inclusion.

Changes

Public upload quarantine

Layer / File(s)	Summary
Quarantine and public read scope documentation src/app/api/upload/route.ts, src/lib/public-api-access.ts	Comments document pooled uploads under PUBLIC_WORKSPACE_OWNER_ID, anonymous owner_id IS NULL reads, and exclusion of quarantined documents from public viewing and gated RAG retrieval.

Estimated code review effort: 1 (Trivial) | ~2 minutes

---

Caution

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

• Ignore

❌ Failed checks (1 error, 1 warning)

Check name	Status	Explanation	Resolution
Verification Claims	❌ Error	PR text claims verification succeeded (“Live check confirmed…”, “prettier --check and eslint pass”) without the required explicit run/result wording.	Rewrite verification notes to name the exact command/check and outcome, e.g. “Ran prettier --check: passed” or “Not run: reason.”
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 70.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (9 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly describes the docs-only quarantine clarification for PUBLIC_WORKSPACE_OWNER_ID and matches the main change.
Description check	✅ Passed	The description covers the summary, motivation, verification, and governance context, even though it doesn't use the template headings verbatim.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Generated And Sensitive Files	✅ Passed	PASS: HEAD only touches two TypeScript comment blocks; no added paths match secret/generated patterns, and content scans found no credentials.
Risky Git Or Deployment Actions	✅ Passed	Touched files only add comments about public-upload quarantine and operator promotion; no force-push, destructive git, or unsafe deploy guidance appears.
Supabase Project And Schema Safety	✅ Passed	PASS: PR is comments-only; no Supabase project refs, schema, RLS, or migration logic changed, and the cited public-workspace docs/scripts already exist.
Runtime And Package Manager Integrity	✅ Passed	Diff is comment-only in two TS files; no lockfile, packageManager, engines, or engine-strict changes were made.
Api Route Failure Handling	✅ Passed	Comments-only PR; no runtime route/RAG/provider logic changed, and the upload POST already has explicit 400/503/401/jsonError paths plus cleanup on exceptions.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/database-rag-image-visibility-d6b809

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch claude/database-rag-image-visibility-d6b809

---

_{Comment @coderabbitai help to get the list of available commands.}