Add findOrVersionArtifact to close the tenant+title+kind race

The schema's only uniqueness is (artifactId, version); nothing constrains
(tenantId, title, kind), so "find by title, create if absent, add a version
if present" raced between the read and the write whenever a consumer
hand-rolled it. findOrVersionArtifact closes that race inside the package
with a transaction-scoped advisory lock keyed on (tenantId, kind, title),
in its own lock-space namespace so it never collides with the migration
runner's lock.

Collision semantics: the caller that acquires the lock first creates the
artifact; every other concurrent caller for the same triple blocks, then
finds and revises the row the first caller just committed. Concurrent
callers always converge on one artifact, never two.

A uniqueness constraint on (tenant_id, title, kind) was considered and
rejected for now: there is no way to confirm existing tenants are free of
duplicate (title, kind) rows, and a migration that fails on real data is
worse than the race it would close. Documented in ARCHITECTURE.md.

CL-5013

Author: TheGreatAxios

ARCHITECTURE.md

@@ -108,7 +108,7 @@ which store is installed.
 | File | Role |
 | --- | --- |
 | `mount.ts` | HTTP surface: parsing, validation, status codes. |
-| `artifacts.ts` | The core domain — create, revise, list, get, archive, serialize. |
+| `artifacts.ts` | The core domain — create, revise, find-or-version, list, get, archive, serialize. |
 | `uploads.ts` | `createFileArtifact`, the MIME policies, and the size caps. |
 | `download.ts` | One download path over the three storage conventions. |
 | `content-store.ts` | The two shipped `ContentStore` implementations. |
@@ -163,6 +163,32 @@ version fail loudly rather than corrupt history.
 **Archival is a soft hide.** `archived_at` null means visible; a timestamp means
 hidden from discovery. Deep links to archived artifacts still load.
 
+**Find-or-version is a package primitive, not a constraint.** The only
+uniqueness the schema enforces is `(artifact_id, version)` — there is no
+constraint on `(tenant_id, title, kind)`, so "find by title, create if
+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.
+
 **`upload` is never a standalone resource.** There is no `POST /uploads`; every
 upload eagerly mints its artifact, and the row is reachable only through
 `source.upload.id`. `mail_attachment_ref` carries no bytes at all — the file

CHANGELOG.md

@@ -9,6 +9,23 @@ always called out under their own heading.
 
 ## [Unreleased]
 
+### Added
+
+- `findOrVersionArtifact(db, args)` — the atomic primitive behind "find an
+  artifact by title, create it if absent, add a version if present." The
+  schema's only uniqueness is `(artifactId, version)`; nothing constrains
+  `(tenantId, title, kind)`, so that common pattern raced between the read
+  and the write when hand-rolled outside the package. This closes the race
+  with a transaction-scoped advisory lock keyed on `(tenantId, kind, title)`:
+  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
+  ARCHITECTURE.md.
+
 ### Changed
 
 - The repository root **is** the `@corbits/artifacts` package. The previous

README.md

@@ -249,6 +249,15 @@ legacy zoneless columns with `USING col AT TIME ZONE 'UTC'` (existing walls were
 always documented as UTC). Do not edit shipped migrations to roll back — ship a
 new reverse cast if you must.
 
+`(tenant_id, title, kind)` is **not** a uniqueness constraint — only
+`(artifact_id, version)` is. Use `findOrVersionArtifact(db, args)` for "find
+by title, create if absent, add a version if present": it takes a
+transaction-scoped advisory lock so concurrent callers for the same
+`(tenantId, kind, title)` converge on one artifact instead of racing into
+two. See ARCHITECTURE.md's "Find-or-version" note for the collision
+semantics and why this is a package primitive rather than a schema
+constraint.
+
 ## Working on it
 
 ```sh

src/artifacts.test.ts

@@ -5,6 +5,7 @@ import {
   ArtifactSizeError,
   createArtifact,
   findArtifactByTitle,
+  findOrVersionArtifact,
   getArtifactVersion,
   listArtifactVersions,
   MAX_ARTIFACT_CONTENT_BYTES,
@@ -324,6 +325,121 @@ describe("find by title", () => {
   });
 });
 
+describe("find-or-version", () => {
+  test("creates when no match exists", async () => {
+    const db = await testDb();
+    const result = await findOrVersionArtifact(db, {
+      scope: SCOPE,
+      ownerPrincipalId: SCOPE.principalId,
+      kind: "document",
+      title: "Report",
+      content: "v1",
+      source: { origin: "agent" },
+    });
+
+    expect(result.outcome).toBe("created");
+    expect(result.artifact.version).toBe(1);
+    expect(result.artifact.content).toBe("v1");
+  });
+
+  test("revises the existing match instead of creating a second artifact", async () => {
+    const db = await testDb();
+    const seeded = await seedArtifact(db, { title: "Report", content: "v1" });
+
+    const result = await findOrVersionArtifact(db, {
+      scope: SCOPE,
+      ownerPrincipalId: SCOPE.principalId,
+      kind: "document",
+      title: "Report",
+      content: "v2",
+      source: { origin: "agent" },
+    });
+
+    expect(result.outcome).toBe("revised");
+    expect(result.artifact.id).toBe(seeded.id);
+    expect(result.artifact.version).toBe(2);
+    expect(result.artifact.content).toBe("v2");
+
+    const rows = await db.select().from(artifact).where(eq(artifact.tenantId, "acme"));
+    expect(rows.length).toBe(1);
+  });
+
+  test("a different kind with the same title creates a separate artifact", async () => {
+    const db = await testDb();
+    await seedArtifact(db, { title: "Report", kind: "document" });
+
+    const result = await findOrVersionArtifact(db, {
+      scope: SCOPE,
+      ownerPrincipalId: SCOPE.principalId,
+      kind: "csv-export",
+      title: "Report",
+      content: "csv body",
+      source: { origin: "agent" },
+    });
+
+    expect(result.outcome).toBe("created");
+    const rows = await db.select().from(artifact).where(eq(artifact.title, "Report"));
+    expect(rows.length).toBe(2);
+  });
+
+  test("an archived match does not get silently revived — a fresh artifact is created", async () => {
+    const db = await testDb();
+    const archived = await seedArtifact(db, { title: "Report" });
+    await setArtifactArchived(db, archived, true);
+
+    const result = await findOrVersionArtifact(db, {
+      scope: SCOPE,
+      ownerPrincipalId: SCOPE.principalId,
+      kind: "document",
+      title: "Report",
+      content: "fresh",
+      source: { origin: "agent" },
+    });
+
+    expect(result.outcome).toBe("created");
+    expect(result.artifact.id).not.toBe(archived.id);
+  });
+
+  // The race the ticket describes: two callers both see "no match" under a
+  // plain read-then-write, and both create. The advisory lock this helper
+  // takes must serialize them instead, so the second caller's lookup runs
+  // AFTER the first caller's write is committed and finds it.
+  test("concurrent calls for the same (tenant, kind, title) converge on one artifact", async () => {
+    const db = await testDb();
+
+    const [first, second] = await Promise.all([
+      findOrVersionArtifact(db, {
+        scope: SCOPE,
+        ownerPrincipalId: SCOPE.principalId,
+        kind: "document",
+        title: "Report",
+        content: "from first",
+        source: { origin: "agent" },
+      }),
+      findOrVersionArtifact(db, {
+        scope: SCOPE,
+        ownerPrincipalId: SCOPE.principalId,
+        kind: "document",
+        title: "Report",
+        content: "from second",
+        source: { origin: "agent" },
+      }),
+    ]);
+
+    expect(first.artifact.id).toBe(second.artifact.id);
+    expect([first.outcome, second.outcome].sort()).toEqual(["created", "revised"]);
+    expect([first.artifact.version, second.artifact.version].sort()).toEqual([1, 2]);
+
+    const rows = await db.select().from(artifact).where(eq(artifact.tenantId, "acme"));
+    expect(rows.length).toBe(1);
+    const versions = await db
+      .select()
+      .from(artifactVersion)
+      .where(eq(artifactVersion.artifactId, first.artifact.id));
+    expect(versions.length).toBe(2);
+  });
+});
+
 describe("serialization", () => {
   test("a null source reads as an unknown origin", () => {
     expect(normalizeSource(null)).toEqual({ origin: "unknown" });