Skip to content

docs: unique constraints are an existence oracle on access-scoped lists - #1774

Merged
borisno2 merged 3 commits into
mainfrom
claude/wonderful-feynman-62qdq3
Oct 7, 2026
Merged

borisno2 merged 3 commits into
mainfrom
claude/wonderful-feynman-62qdq3

Conversation

@borisno2

@borisno2 borisno2 commented Oct 7, 2026

Copy link
Copy Markdown
Member

Summary

  • CLAUDE.md "Costs taken knowingly" and architecture-spec §14: new bullet for the unique/restrictive-FK existence channel
  • ADR-0042: amendment explaining why field-mapped messages stay (no wording closes the channel)
  • access-control concepts doc: "Uniqueness and existence" section with a db.indexes tenant-scoped snippet, rate-limit and onDelete guidance

No source or behaviour change, so no changeset.

Test plan

  • prettier passes on changed files
  • snippets use the existing db.indexes / isIndexed: 'unique' API

Closes #1654

🤖 Generated with Claude Code

https://claude.ai/code/session_01NVTKtZrZbRq9APE49o2y46


Generated by Claude Code

@vercel

vercel Bot commented Oct 7, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
stack-docs Ready Ready Preview Oct 7, 2026 11:29am UTC

@changeset-bot

changeset-bot Bot commented Oct 7, 2026 •

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: 50b7e06

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 7, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-07T11:27:36.285525Z f5cb99c PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

borisno2 commented Oct 7, 2026

Copy link
Copy Markdown
Member Author

Review of PR #1774 (docs-only, unique-constraint existence oracle, issue #1654)

The review found 3 documentation issues, none blocking. The review did not report separate findings for the cross-doc consistency, snippet validity or link checks, so I am not claiming a full manual pass on those.

1. Tenant-scoped unique index example does not pin the tenant

docs/content/concepts/access-control.md (~line 420)

The Member example with unique(tenant, email) reads as a complete mitigation, but it is not one on its own. Suppose the create or update rule is not scoped to the caller's tenant. The caller can connect a tenant they can reach, or leave the tenant to a hook, and probe (otherTenant, email) pairs. The UniqueConstraintViolation still confirms which emails exist, so the oracle remains.

Suggested fix: say that the tenant must be pinned by the access filter or a resolveInput hook, and that the per-field rule must stop the caller choosing it.

2. onDelete: 'restrict' advice does not say where the option lives

docs/content/concepts/access-control.md (~line 416)

onDelete is configured on the relationship field as db: { onDelete } (packages/core/src/config/types.ts:1347). The doc does not say this, and it gives no replacement for restrict. A reader looking for a list-level option will not find one.

Suggested fix: name the field option and show the replacement, for example db: { onDelete: 'setNull' }.

3. fieldErrors is described as always present

docs/content/concepts/access-control.md (~line 413), plus the ADR amendment

The text implies fieldErrors always accompanies a unique violation. The UniqueConstraintViolation docblock in packages/core/src/lib/database-errors.ts says a hand-managed constraint is absent from the constraint map. For those constraints the error has the generic message and empty fieldErrors. The oracle exists either way.

Suggested fix: say the fields detail is best-effort.


Generated by Claude Code

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NVTKtZrZbRq9APE49o2y46

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f5cb99c19b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/content/concepts/access-control.md Outdated

A session that updates its own `email` to another user's address receives the violation, confirming that address is taken even though it cannot read that user. The same applies to `create` for any caller with create access. A restrictive foreign key (`onDelete: 'restrict'`) likewise reveals, by blocking a delete, that rows the session cannot read still reference the target.

No runtime check can close this: the database alone knows about the colliding row, and any outcome other than success differs from success. The stack keeps the field-mapped message on purpose (see ADR-0042). Mitigate in the schema and at the edge:

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Document indistinguishable success responses as a mitigation

The claim that no runtime behavior can close this channel is too absolute. For flows where the caller does not need the created row—such as registration, invitations, or password-recovery requests—the endpoint can catch a uniqueness violation and return exactly the same status and payload as a successful write, preventing the caller from distinguishing an existing address from a new one. This is especially important when uniqueness must remain global and cannot be scoped to a tenant; qualify the claim for writes whose success is independently observable and document uniform success responses as an additional edge mitigation.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed. The claim is now qualified to writes whose success the caller observes, and uniform success responses are documented as a mitigation.


Generated by Claude Code

@github-actions

github-actions Bot commented Oct 7, 2026

Copy link
Copy Markdown
Contributor

Coverage Report for Core Package Coverage (./packages/core)

Status Category Percentage Covered / Total
🟢 Lines 94.54% (🎯 81%) 3814 / 4034
🟢 Statements 92.84% (🎯 76%) 4337 / 4671
🟢 Functions 96.09% (🎯 78%) 861 / 896
🟢 Branches 88.42% (🎯 71%) 2948 / 3334
File CoverageNo changed files found.
Generated in workflow #2985 for commit 50b7e06 by the Vitest Coverage Report Action

@github-actions

github-actions Bot commented Oct 7, 2026

Copy link
Copy Markdown
Contributor

Coverage Report for UI Package Coverage (./packages/ui)

Status Category Percentage Covered / Total
🔵 Lines 78.7% 244 / 310
🔵 Statements 78.43% 251 / 320
🔵 Functions 69.81% 74 / 106
🔵 Branches 67.51% 160 / 237
File CoverageNo changed files found.
Generated in workflow #2985 for commit 50b7e06 by the Vitest Coverage Report Action

@github-actions

github-actions Bot commented Oct 7, 2026

Copy link
Copy Markdown
Contributor

Coverage Report for CLI Package Coverage (./packages/cli)

Status Category Percentage Covered / Total
🔵 Lines 82.18% 2044 / 2487
🔵 Statements 81.94% 2196 / 2680
🔵 Functions 87.28% 350 / 401
🔵 Branches 75.44% 1100 / 1458
File CoverageNo changed files found.
Generated in workflow #2985 for commit 50b7e06 by the Vitest Coverage Report Action

@github-actions

github-actions Bot commented Oct 7, 2026

Copy link
Copy Markdown
Contributor

Coverage Report for Auth Package Coverage (./packages/auth)

Status Category Percentage Covered / Total
🔵 Lines 83.33% 405 / 486
🔵 Statements 82.19% 457 / 556
🔵 Functions 86.2% 100 / 116
🔵 Branches 78.28% 375 / 479
File CoverageNo changed files found.
Generated in workflow #2985 for commit 50b7e06 by the Vitest Coverage Report Action

@github-actions

github-actions Bot commented Oct 7, 2026

Copy link
Copy Markdown
Contributor

Coverage Report for Storage Package Coverage (./packages/storage)

Status Category Percentage Covered / Total
🔵 Lines 96.97% 417 / 430
🔵 Statements 96.02% 459 / 478
🔵 Functions 98.36% 120 / 122
🔵 Branches 93.43% 427 / 457
File CoverageNo changed files found.
Generated in workflow #2985 for commit 50b7e06 by the Vitest Coverage Report Action

@github-actions

github-actions Bot commented Oct 7, 2026

Copy link
Copy Markdown
Contributor

Coverage Report for RAG Package Coverage (./packages/rag)

Status Category Percentage Covered / Total
🔵 Lines 88.79% 634 / 714
🔵 Statements 88.19% 695 / 788
🔵 Functions 95.48% 127 / 133
🔵 Branches 85.03% 449 / 528
File CoverageNo changed files found.
Generated in workflow #2985 for commit 50b7e06 by the Vitest Coverage Report Action

@github-actions

github-actions Bot commented Oct 7, 2026

Copy link
Copy Markdown
Contributor

Coverage Report for Storage S3 Package Coverage (./packages/storage-s3)

Status Category Percentage Covered / Total
🔵 Lines 100% 47 / 47
🔵 Statements 100% 48 / 48
🔵 Functions 100% 10 / 10
🔵 Branches 96.87% 31 / 32
File CoverageNo changed files found.
Generated in workflow #2985 for commit 50b7e06 by the Vitest Coverage Report Action

@github-actions

github-actions Bot commented Oct 7, 2026

Copy link
Copy Markdown
Contributor

Coverage Report for Storage Vercel Package Coverage (./packages/storage-vercel)

Status Category Percentage Covered / Total
🔵 Lines 100% 74 / 74
🔵 Statements 100% 78 / 78
🔵 Functions 100% 16 / 16
🔵 Branches 96.55% 56 / 58
File CoverageNo changed files found.
Generated in workflow #2985 for commit 50b7e06 by the Vitest Coverage Report Action

@borisno2
borisno2 merged commit 899bfdf into main Oct 7, 2026
9 checks passed
@borisno2
borisno2 deleted the claude/wonderful-feynman-62qdq3 branch October 7, 2026 19:58

This branch was successfully deployed

1 active deployment
Preview — 50b7e069 Deployed Oct 7, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Unique-constraint violations reveal that a row the session cannot read has a given value

2 participants