Sharpen the find-or-version-vs-constraint rationale

The prior wording leaned on "can't verify existing data" as if this were a
one-time backfill problem. It isn't: createArtifact is a public,
unconditional insert used directly by the import route, uploads, and
artifact_link_file, none of which dedupe by title. Two independent creates
sharing a title is normal on every one of those paths, so a hard
UNIQUE(tenant_id, title, kind) constraint would reject ordinary inserts, not
just gate a legacy cleanup. Uniqueness on that triple is a property of the
find-or-version pattern, not an invariant of the table.

CL-5013

Author: TheGreatAxios

ARCHITECTURE.md

@@ -170,24 +170,39 @@ absent, add a version if present" is not naturally atomic: a plain
 read-then-write of that pattern races, and two concurrent callers can both
 observe NOT FOUND and both create, leaving two artifacts with the same
 title. A uniqueness constraint on `(tenant_id, title, kind)` was considered
-and rejected for now — this package has no way to confirm that no tenant
-already holds duplicate `(title, kind)` rows created before this primitive
-existed, and a migration that fails partway through a production deploy over
-real duplicate data is a worse outage than the race it closes. Instead,
-`findOrVersionArtifact(db, args)` (in `artifacts.ts`) closes the race with a
-transaction-scoped advisory lock keyed by `hashtext(tenantId, kind, title)`,
-in its own lock-space namespace (the two-`int4`-argument form of
-`pg_advisory_xact_lock`, disjoint from the single-`bigint` form
-`runArtifactMigrations` uses). Collision semantics: whichever concurrent
-caller acquires the lock first creates the artifact; every other caller for
-the identical `(tenantId, kind, title)` blocks, then finds the row the
-winner just committed and revises it. Two overlapping callers always
-converge on ONE artifact with two versions, never two rows — callers for a
-different tenant, kind, or title never contend with each other. If the
-`(tenant_id, title, kind)` triple is later confirmed duplicate-free in
-production, a follow-up migration can still add the hard constraint; the
-helper's serialization would make that migration a no-op for any writer that
-already goes through it.
+and rejected — not just for now, but structurally: `createArtifact` is a
+public, unconditional insert with no title lookup of its own, called
+directly by the import route, the upload path, and `artifact_link_file`.
+Two independent creates sharing a title is normal, intended behavior on
+every one of those paths — a coworker uploading `report.pdf` twice, or two
+agents each linking a file named `notes.md`, are not bugs. A hard
+`UNIQUE(tenant_id, title, kind)` constraint would reject those ordinary
+inserts outright, not just gate on a one-time backfill of legacy duplicates.
+Uniqueness on that triple is a property of the *find-or-version pattern
+specifically*, not an invariant of the table, so it does not belong in the
+schema — it belongs exactly where it now lives, inside the one code path
+that promises it. (Separately, this package also has no way to confirm
+existing tenants are already free of duplicate `(title, kind)` rows, which
+would make even a scoped constraint risky to backfill — but that is not the
+main reason, and is not by itself decisive: see `0003_schema_invariants` for
+this repo's own pattern for guarding a migration against exactly that kind
+of bad existing data.)
+Instead, `findOrVersionArtifact(db, args)` (in `artifacts.ts`) closes the
+race with a transaction-scoped advisory lock keyed by
+`hashtext(tenantId, kind, title)`, in its own lock-space namespace (the
+two-`int4`-argument form of `pg_advisory_xact_lock`, disjoint from the
+single-`bigint` form `runArtifactMigrations` uses). Collision semantics:
+whichever concurrent caller acquires the lock first creates the artifact;
+every other caller for the identical `(tenantId, kind, title)` blocks, then
+finds the row the winner just committed and revises it. Two overlapping
+callers always converge on ONE artifact with two versions, never two rows —
+callers for a different tenant, kind, or title never contend with each
+other. This guarantee holds only for callers that go through
+`findOrVersionArtifact`; a caller that instead calls `createArtifact`
+directly is unconstrained by design, as above, and a caller that hand-rolls
+its own find-then-create against a *different* lock is not serialized
+against this one — the primitive closes the race for its own call path, not
+for every possible way to write an artifact.
 
 **`upload` is never a standalone resource.** There is no `POST /uploads`; every
 upload eagerly mints its artifact, and the row is reachable only through

CHANGELOG.md

@@ -20,10 +20,11 @@ always called out under their own heading.
   concurrent callers for the same triple always converge on one artifact —
   the first to acquire the lock creates it, every other caller revises the
   row the first one just committed. A uniqueness constraint on
-  `(tenant_id, title, kind)` was considered instead but rejected for now: this
-  package cannot verify that no existing tenant already has duplicate
-  `(title, kind)` rows, and a migration that fails on real data is worse than
-  the race it would close. See the "Find-or-version" section of
+  `(tenant_id, title, kind)` was considered instead but rejected:
+  `createArtifact` is a public, unconditional insert used directly by the
+  import route, uploads, and `artifact_link_file`, and a shared title across
+  independent creates on those paths is normal, not a bug a schema
+  constraint should forbid. See the "Find-or-version" section of
   ARCHITECTURE.md.
 
 ### Changed