toiljs 0.0.106 → 0.0.108

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "toiljs",
     "type": "module",
-    "version": "0.0.106",
+    "version": "0.0.108",
     "author": "Dacely",
     "description": "The modern React framework: a file-based React frontend and a ToilScript-compiled WebAssembly backend.",
     "repository": {
@@ -136,7 +136,7 @@
         "nodemailer": "^9.0.3",
         "picocolors": "^1.1.1",
         "sharp": "^0.35.3",
-        "toilscript": "^0.1.54",
+        "toilscript": "^0.1.56",
         "typescript-eslint": "^8.62.1",
         "vite": "^8.1.3",
         "vite-imagetools": "^10.0.1",
@@ -147,7 +147,7 @@
         "prettier": ">=3.0.0",
         "react": ">=18.0.0",
         "react-dom": ">=18.0.0",
-        "toilscript": ">=0.1.54",
+        "toilscript": ">=0.1.56",
         "typescript": ">=6.0.0"
     },
     "overrides": {

package/server/auth/AuthController.ts

@@ -488,6 +488,9 @@ class AuthAccount {
     // TWOFA_NONE (2FA off), the safe default, so existing accounts stay logged in
     // by password alone until they opt in via /auth/2fa/setup.
     twoFactorMethod: u8 = 0;
+    // Append-only: the STABLE ToilUserId, derived once at registration. Reset rotates
+    // publicKey but leaves this, so the id is stable across a reset.
+    toilUserId: Uint8Array = new Uint8Array(0);
 }
 
 @data
@@ -609,16 +612,6 @@ class Auth {
         // on domain A is a DIFFERENT account + index entry from the same on domain B.
         const h = realm(ctx);
 
-        // Distinguishable statuses (not the generic 401) so the UI can say
-        // "username taken" / "email in use". Signup intentionally leaks existence
-        // (a product choice, now gated behind the PoP above); reset never does.
-        if (AuthDb.accounts.exists(new Username(h, username))) {
-            return Response.bytes(new DataWriter().writeU8(ST_TAKEN).toBytes());
-        }
-        if (AuthDb.emails.exists(new EmailKey(h, email))) {
-            return Response.bytes(new DataWriter().writeU8(ST_EMAIL_TAKEN).toBytes());
-        }
-
         // Send the confirm email + store unconfirmed when EITHER flag is on
         // (AUTH_EMAIL_CONFIRMATION or the stricter AUTH_REQUIRE_EMAIL_CONFIRMATION).
         // Whether login is then BLOCKED is a separate check (requireConfirmation,
@@ -633,14 +626,20 @@ class Auth {
         a.memKiB = MEM_KIB;
         a.iterations = ITERS;
         a.parallelism = PAR;
-        // create-if-absent: a racing duplicate registration loses here, not above.
+        // Derive + persist the stable id once. Tenant-scoped, and unique WITHOUT a
+        // separate index: the framed derive maps distinct (username, domain) to
+        // distinct ids, and username is unique per realm (accounts.create below), so
+        // two accounts can never share an id.
+        a.toilUserId = ToilUserId.derive(pk, username, authDomain(ctx)).toBytes();
+        // create-if-absent IS the authoritative, race-safe uniqueness guard
+        // (serialized at the key's home): a duplicate username loses here and gets the
+        // distinguishable ST_TAKEN. No pre-`exists` read needed -- the create result
+        // is the answer.
         if (!AuthDb.accounts.create(new Username(h, username), a)) {
             return Response.bytes(new DataWriter().writeU8(ST_TAKEN).toBytes());
         }
-        // Reserve the email -> username index (uniqueness for reset-by-email, scoped
-        // per host). A racing duplicate email loses here: roll back the account we
-        // just created so a lost email race can't orphan a username whose email index
-        // points at someone else (which would also break reset-by-email for it).
+        // Reserve the email -> username index (email uniqueness + reset-by-email). A
+        // duplicate email loses here; roll back the account so nothing is orphaned.
         if (!AuthDb.emails.create(new EmailKey(h, email), new EmailOwner(username))) {
             AuthDb.accounts.delete(new Username(h, username));
             return Response.bytes(new DataWriter().writeU8(ST_EMAIL_TAKEN).toBytes());
@@ -841,8 +840,7 @@ class Auth {
         //    extended one). `__toilEncodeAuthUser` is injected by `--authUser`: it constructs the `@user`
         //    (app fields at their defaults), sets the reserved identity, and encodes it. The stable
         //    ToilUserId is derived from the login public key + username + tenant domain.
-        const domain = authDomain(ctx);
-        const toilUserId = ToilUserId.derive(acct.publicKey, ch.username, domain).toBytes();
+        const toilUserId = this.stableUserId(ctx, h, ch.username, acct);
         const userData = __toilEncodeAuthUser(toilUserId, ch.username);
         const w = new DataWriter();
         w.writeU8(ST_OK);
@@ -958,6 +956,16 @@ class Auth {
         return Response.bytes(new DataWriter().writeU8(ST_OK).toBytes());
     }
 
+    /** The account's STABLE ToilUserId, persisted at registration (so reset never
+     *  changes it). An empty stored id is derived once, persisted, and indexed. */
+    private stableUserId(ctx: RouteContext, h: string, username: string, acct: AuthAccount): Uint8Array {
+        if (acct.toilUserId.length > 0) return acct.toilUserId;
+        const uid = ToilUserId.derive(acct.publicKey, username, authDomain(ctx)).toBytes();
+        acct.toilUserId = uid;
+        AuthDb.accounts.patch(new Username(h, username), acct);
+        return uid;
+    }
+
     /** GET /auth/me  (@auth: 401 without a valid session) -> the typed user
      *  (bytes(toilUserId) str(username)). `AuthService.getUser()` is auto-typed
      *  to the built-in `@user` with no type argument. */
@@ -1037,8 +1045,7 @@ class Auth {
         AuthDb.twoFaLogins.getDelete(key);
         const acct = AuthDb.accounts.get(new Username(h, ch.username));
         if (acct == null) return fail();
-        const domain = authDomain(ctx);
-        const toilUserId = ToilUserId.derive(acct.publicKey, ch.username, domain).toBytes();
+        const toilUserId = this.stableUserId(ctx, h, ch.username, acct);
         const userData = __toilEncodeAuthUser(toilUserId, ch.username);
         const w = new DataWriter();
         w.writeU8(ST_OK);

package/server/globals/auth.ts

@@ -228,8 +228,16 @@ function __labelled(label: string, transcriptHash: Uint8Array): Uint8Array {
 function __reqIsSecure(): bool {
     const req = Server.currentRequest;
     if (req == null) return false;
+    // Proxied deployments: trust the terminating proxy's scheme header.
     const proto = req.header('x-forwarded-proto');
-    return proto != null && proto == 'https';
+    if (proto != null) return proto == 'https';
+    // Direct-origin deployments: the edge terminates TLS itself and sends no
+    // x-forwarded-proto, so fall back to the configured public origin. An https
+    // PUBLIC_BASE_URL means the site is served over TLS, so the auth cookies must
+    // be Secure + __Host-/__Secure- prefixed. Without this a direct-origin HTTPS
+    // edge sets bare cookies and the client's getUser() misses the __Secure- name.
+    const base = Environment.get('PUBLIC_BASE_URL');
+    return base != null && base.startsWith('https://');
 }
 
 export namespace AuthService {
@@ -402,7 +410,10 @@ export namespace AuthService {
         let cookie = Cookie.create(USER_BASE, base64UrlEncode(userData))
             .sameSite(SameSite.Lax)
             .maxAge(<i64>ttlSecs);
-        cookie = secure ? cookie.asSecurePrefixed() : cookie.path('/');
+        // Path=/ in BOTH branches: asSecurePrefixed() sets no path, so without this
+        // the cookie is scoped to the /auth request path and getUser() can't read it
+        // on /login or /dashboard.
+        cookie = secure ? cookie.asSecurePrefixed().path('/') : cookie.path('/');
         return cookie;
     }
 
@@ -412,7 +423,10 @@ export namespace AuthService {
         let cookie = Cookie.create(USER_BASE, '')
             .sameSite(SameSite.Lax)
             .maxAge(0);
-        cookie = secure ? cookie.asSecurePrefixed() : cookie.path('/');
+        // Path=/ in BOTH branches: asSecurePrefixed() sets no path, so without this
+        // the cookie is scoped to the /auth request path and getUser() can't read it
+        // on /login or /dashboard.
+        cookie = secure ? cookie.asSecurePrefixed().path('/') : cookie.path('/');
         return cookie;
     }
 

package/server/globals/userid.ts

@@ -30,12 +30,18 @@ export class ToilUserId {
      * unambiguous, and `domain` is the trusted tail supplied by the host, not the user.
      */
     static derive(mldsaPublicKey: Uint8Array, identifier: string, domain: string): ToilUserId {
+        // Length-framed, domain-separated preimage: a u32 length prefix on every
+        // field keeps ids collision-free across tenants; the context tag separates
+        // this hash from other sha256 uses.
+        const ctx = Uint8Array.wrap(String.UTF8.encode(USERID_CONTEXT));
         const id = Uint8Array.wrap(String.UTF8.encode(identifier));
         const dom = Uint8Array.wrap(String.UTF8.encode(domain));
-        const buf = new Uint8Array(mldsaPublicKey.length + id.length + dom.length);
-        buf.set(mldsaPublicKey, 0);
-        buf.set(id, mldsaPublicKey.length);
-        buf.set(dom, mldsaPublicKey.length + id.length);
+        const buf = new Uint8Array(16 + ctx.length + mldsaPublicKey.length + id.length + dom.length);
+        let off = 0;
+        off = putField(buf, off, ctx);
+        off = putField(buf, off, mldsaPublicKey);
+        off = putField(buf, off, id);
+        off = putField(buf, off, dom);
         return ToilUserId.fromBytes(crypto.sha256(buf));
     }
 
@@ -105,3 +111,18 @@ export class ToilUserId {
         return !this.equals(other);
     }
 }
+
+/** Domain-separation tag for {@link ToilUserId.derive}; versioned. */
+const USERID_CONTEXT: string = 'toil.userid.v1';
+
+/** Append a u32-LE length prefix + `src` to `buf` at `off`; return the new offset. */
+function putField(buf: Uint8Array, off: i32, src: Uint8Array): i32 {
+    const n = src.length;
+    buf[off] = <u8>(n & 0xff);
+    buf[off + 1] = <u8>((n >> 8) & 0xff);
+    buf[off + 2] = <u8>((n >> 16) & 0xff);
+    buf[off + 3] = <u8>((n >> 24) & 0xff);
+    off += 4;
+    buf.set(src, off);
+    return off + n;
+}

package/src/compiler/auth-emails.ts

@@ -23,7 +23,6 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 
 import pc from 'picocolors';
 import { createServer } from 'vite';
@@ -33,20 +32,19 @@ import { RESERVED_AUTH_EMAIL_NAMES, renderEmailFile, toPascal, type RenderedEmai
 import { createViteConfig } from './vite.js';
 
 /**
- * The toiljs package's `server/globals` LIB directory: the ambient, no-import
- * surface (`EmailService`, `AuthService`, …) the toilconfig `lib` array points
- * at. The auth-email module is generated HERE, not in the app's `server/` dir,
- * because that is what makes `AuthEmail` resolvable from the node_modules-compiled
- * `AuthController` with NO import (an exported namespace in a plain app entry is
- * module-scoped, not global). Prefers the app's install so a symlinked/linked
- * toiljs is followed; falls back to the running package (hoisted install).
+ * The APP-LOCAL library directory the auth-email module is generated into,
+ * relative to the project root (posix, for the toilscript `--lib` CLI arg). It is
+ * passed to the compiler via `--lib` (see runToilscriptPass), which "uses exports
+ * of all top-level files at this path as globals". That is what makes the
+ * generated `AuthEmail` namespace resolvable from the node_modules-compiled
+ * `AuthController` with NO import, the same way `EmailService`/`AuthService` are
+ * ambient. Generating HERE (the app's own gitignored `.toil/`) rather than into
+ * `node_modules/toiljs/server/globals` keeps it PER-APP: a pnpm/workspace/linked
+ * install physically shares that package dir, so writing there would let one app
+ * clobber another's templates (or delete the file another app is compiling), and
+ * a read-only store would fail the build. `.toil` is always app-writable.
  */
-function globalsDir(root: string): string {
-    const inApp = path.join(root, 'node_modules', 'toiljs', 'server', 'globals');
-    if (fs.existsSync(inApp)) return inApp;
-    const pkgDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
-    return path.join(pkgDir, 'server', 'globals');
-}
+export const AUTH_EMAILS_LIB_SUBDIR = '.toil/authlib';
 
 /** The reserved override names (PascalCase), one per built-in auth email. */
 type AuthName = 'AuthConfirm' | 'AuthReset' | 'Auth2fa';
@@ -204,17 +202,36 @@ function moduleSource(parts: Parts): string {
 }
 
 /**
- * (Re)write `_auth_emails.ts` in the toiljs lib globals dir so the built-in auth
- * controller has its email senders, baking any reserved `emails/*.tsx` override
- * over the default. Runs BEFORE the toilscript server build (like
- * {@link renderEmails}) so the module is compiled in. A no-op that removes a stale
- * module when `authOn` is false. Only spins up Vite when an override actually
- * exists.
+ * Best-effort removal of a stale copy from the pre-0.0.107 location
+ * (`node_modules/toiljs/server/globals/_auth_emails.ts`). Leaving it there would
+ * define a SECOND `AuthEmail` namespace alongside the new app-local one and break
+ * the compile with a duplicate symbol, so a project upgraded in place (without a
+ * fresh `npm i`) is cleaned up here. Never throws (a read-only store just skips).
+ */
+function removeLegacyModule(root: string): void {
+    try {
+        const legacy = path.join(root, 'node_modules', 'toiljs', 'server', 'globals', GENERATED_BASENAME);
+        if (fs.existsSync(legacy)) fs.rmSync(legacy);
+    } catch {
+        // read-only / missing: nothing to clean, not fatal
+    }
+}
+
+/**
+ * (Re)write `_auth_emails.ts` into the app-local `.toil/authlib` LIB dir so the
+ * built-in auth controller has its email senders, baking any reserved
+ * `emails/*.tsx` override over the default. Runs BEFORE the toilscript server
+ * build (like {@link renderEmails}) so the module is compiled in via `--lib`. A
+ * no-op that removes a stale module when auth is off or there is no server. Only
+ * spins up Vite when an override actually exists.
  */
 export async function renderAuthEmails(cfg: ResolvedToilConfig, authOn: boolean): Promise<void> {
-    const generatedPath = path.join(globalsDir(cfg.root), GENERATED_BASENAME);
+    const generatedPath = path.join(cfg.root, AUTH_EMAILS_LIB_SUBDIR, GENERATED_BASENAME);
+    removeLegacyModule(cfg.root);
 
-    if (!authOn) {
+    // No server to compile into, or auth off: ensure no stale module lingers.
+    const hasServer = fs.existsSync(path.join(cfg.root, 'toilconfig.json'));
+    if (!authOn || !hasServer) {
         if (fs.existsSync(generatedPath)) fs.rmSync(generatedPath);
         return;
     }

package/src/compiler/emails.ts

@@ -325,7 +325,7 @@ function warn(msg: string): void {
  * there is no `emails/` directory. Removes a stale generated module when the
  * directory becomes empty.
  */
-export async function renderEmails(cfg: ResolvedToilConfig): Promise<void> {
+export async function renderEmails(cfg: ResolvedToilConfig, authOn = false): Promise<void> {
     const emailsDir = path.join(cfg.root, 'emails');
     const generatedPath = path.join(serverDir(cfg.root), GENERATED_BASENAME);
 
@@ -355,7 +355,12 @@ export async function renderEmails(cfg: ResolvedToilConfig): Promise<void> {
         for (const file of files) {
             // Reserved auth-override templates (emails/auth-confirm.tsx, …) are
             // consumed by the auth pipeline, not surfaced as generic `Emails.*`.
-            if (RESERVED_AUTH_EMAIL_NAMES.has(toPascal(path.basename(file).replace(/\.(tsx|jsx)$/, ''))))
+            // Only reserved WHEN AUTH IS ON: a non-auth project keeping an email
+            // by that name still gets its normal `Emails.<Name>.send(...)`.
+            if (
+                authOn &&
+                RESERVED_AUTH_EMAIL_NAMES.has(toPascal(path.basename(file).replace(/\.(tsx|jsx)$/, '')))
+            )
                 continue;
             try {
                 const r = await renderEmailFile(

package/src/compiler/index.ts

@@ -14,7 +14,11 @@ import type { RunningBackend } from 'toiljs/backend';
 
 import { loadConfig, type ResolvedToilConfig } from './config.js';
 import { renderEmails } from './emails.js';
-import { AUTH_EMAILS_GENERATED_BASENAME, renderAuthEmails } from './auth-emails.js';
+import {
+    AUTH_EMAILS_GENERATED_BASENAME,
+    AUTH_EMAILS_LIB_SUBDIR,
+    renderAuthEmails,
+} from './auth-emails.js';
 import { generate, TOIL_SERVER_ENV_DTS } from './generate.js';
 import { prerenderStaticParams } from './ssg.js';
 import {
@@ -546,6 +550,11 @@ function runToilscriptPass(
     if (opts.rpcSurfaceFiles)
         for (const surfaceFile of opts.rpcSurfaceFiles) args.push('--rpcSurfaceFiles', surfaceFile);
     if (opts.authUser) args.push('--authUser');
+    // Built-in auth: add the app-local `.toil/authlib` as a library path so the
+    // generated `AuthEmail` (see renderAuthEmails) is an ambient global the
+    // node_modules-compiled AuthController resolves with no import. `--lib` merges
+    // with the toilconfig `lib` (it does not replace it). Written before this pass.
+    if (opts.authUser) args.push('--lib', AUTH_EMAILS_LIB_SUBDIR);
     // Each pass is handed its OWN entry subset (the per-tier `files`); suppress the toilconfig
     // `entries` so toilscript does not ALSO append every project entry to every pass (which would
     // pull, e.g., a `@stream` class into the cold daemon pass). serverEntryFiles already folds
@@ -595,8 +604,9 @@ function watchServer(cfg: ResolvedToilConfig, watcher: ViteDevServer['watcher'])
         process.stdout.write(pc.dim('  server changed, rebuilding…') + '\n');
         // Recompile emails/*.tsx -> the generated module before the server build,
         // so editing an email template hot-reloads like any other server change.
-        renderEmails(cfg)
-            .then(() => renderAuthEmails(cfg, serverAuthEnabled(root, cfg.auth)))
+        const authOn = serverAuthEnabled(root, cfg.auth);
+        renderEmails(cfg, authOn)
+            .then(() => renderAuthEmails(cfg, authOn))
             .then(() => buildServer(root, cfg.auth))
             .then(() => process.stdout.write(pc.green('  ✓ ') + pc.dim('server rebuilt') + '\n'))
             .catch((e: unknown) =>
@@ -879,10 +889,11 @@ export async function dev(opts: ToilCommandOptions = {}): Promise<ViteDevServer>
     const hasServer = fs.existsSync(path.join(cfg.root, 'toilconfig.json'));
     if (hasServer) process.stdout.write(pc.dim('  building the server (toilscript)…') + '\n');
     // Compile emails/*.tsx -> generated server module BEFORE toilscript builds it in.
-    await renderEmails(cfg);
-    // Built-in auth: (re)generate `<server>/_auth_emails.ts` (defaults + any emails/auth-*.tsx
-    // overrides) so the injected AuthController's `AuthEmail.*` senders compile in.
-    await renderAuthEmails(cfg, serverAuthEnabled(cfg.root, cfg.auth));
+    const authOnDev = serverAuthEnabled(cfg.root, cfg.auth);
+    await renderEmails(cfg, authOnDev);
+    // Built-in auth: (re)generate `.toil/authlib/_auth_emails.ts` (defaults + any emails/auth-*.tsx
+    // overrides) so the injected AuthController's `AuthEmail.*` senders compile in via --lib.
+    await renderAuthEmails(cfg, authOnDev);
     // Generate the client codegen first so the SSR slots pre-pass can load the route graph, then
     // emit the server-importable `<server>/_ssr/<name>.slots.ts` BEFORE the server build so its
     // `render` can import them. Dev reuses the prior build's shell (or the template) for the HASH;
@@ -1007,10 +1018,11 @@ export async function build(opts: ToilCommandOptions = {}): Promise<void> {
     if (hasServer && !opts.serverOnly)
         process.stdout.write(pc.dim('  building the server (toilscript)…') + '\n');
     // Compile emails/*.tsx -> generated server module BEFORE toilscript builds it in.
-    await renderEmails(cfg);
-    // Built-in auth: (re)generate `<server>/_auth_emails.ts` (defaults + any emails/auth-*.tsx
-    // overrides) so the injected AuthController's `AuthEmail.*` senders compile in.
-    await renderAuthEmails(cfg, serverAuthEnabled(cfg.root, cfg.auth));
+    const authOnBuild = serverAuthEnabled(cfg.root, cfg.auth);
+    await renderEmails(cfg, authOnBuild);
+    // Built-in auth: (re)generate `.toil/authlib/_auth_emails.ts` (defaults + any emails/auth-*.tsx
+    // overrides) so the injected AuthController's `AuthEmail.*` senders compile in via --lib.
+    await renderAuthEmails(cfg, authOnBuild);
     // Generate the client codegen (`.toil/globals.ts`, `.toil/index.html`, …) NOW — before the
     // server build — so the SSR slots pre-pass below can load the route/layout module graph and
     // render the opted-in routes.

package/src/devserver/db/catalog.ts

@@ -21,6 +21,7 @@ import {
     type DbCatalogState,
     DEFAULT_FILL_WAIT_MS,
     type DevCollectionHandle,
+    type DevField,
     isCollectionFamily,
     MAX_FILL_WAIT_MS,
 } from './types.js';
@@ -72,10 +73,13 @@ export function parseCatalog(wasm: Buffer): DbCatalogState {
                 return { kind: 'malformed' };
             const fillAllowStale = fillAllowStaleByte === 1;
             const nFields = r.readU16();
+            const fields: DevField[] = [];
             for (let f = 0; f < nFields; f++) {
-                r.readString(); // field name
-                r.readString(); // field type
-                r.readU8(); // isArray
+                const fName = r.readString();
+                const fType = r.readString();
+                const isArray = r.readU8() !== 0;
+                const unique = r.readU8() !== 0;
+                fields.push({ name: fName, typeName: fType, isArray, unique });
             }
             const nMig = r.readU16();
             for (let m = 0; m < nMig; m++) r.readU32(); // migratableFrom versions
@@ -96,6 +100,7 @@ export function parseCatalog(wasm: Buffer): DbCatalogState {
                     placement,
                     fillMaxWaitMs,
                     fillAllowStale,
+                    fields,
                 });
         }
     }

package/src/devserver/db/database.ts

@@ -685,6 +685,70 @@ export class DevDatabase {
         return this.store.has(storeKey(coll.name, readKey(ref, keyPtr, keyLen))) ? 1 : 0;
     }
 
+    /** Each `@unique` field's raw value in an encoded record, per the collection's
+     *  field layout. `[]` when there is no layout or no `@unique` field. The
+     *  compiler restricts `@unique` to top-level scalar/blob records, so the walker
+     *  only skips fixed scalars and length-prefixed blobs. */
+    private uniqueValuesOf(coll: DevCollectionHandle, value: Buffer): { index: number; val: Buffer }[] {
+        const fields = coll.fields;
+        if (!fields || !fields.some((f) => f.unique)) return [];
+        const r = new DataReader(value);
+        const out: { index: number; val: Buffer }[] = [];
+        for (let i = 0; i < fields.length; i++) {
+            const f = fields[i];
+            if (f.isArray) break;
+            if (f.typeName === 'string') {
+                const s = r.readString();
+                if (f.unique) out.push({ index: i, val: Buffer.from(s, 'utf8') });
+            } else if (f.typeName === 'Uint8Array') {
+                const b = r.readBytes();
+                if (f.unique) out.push({ index: i, val: Buffer.from(b) });
+            } else {
+                switch (f.typeName) {
+                    case 'bool':
+                    case 'u8':
+                    case 'i8':
+                        r.readU8();
+                        break;
+                    case 'u16':
+                    case 'i16':
+                        r.readU16();
+                        break;
+                    case 'u32':
+                    case 'i32':
+                    case 'f32':
+                        r.readU32();
+                        break;
+                    case 'u64':
+                    case 'i64':
+                    case 'f64':
+                        r.readU64();
+                        break;
+                    default:
+                        return out; // nested @data — compiler forbids @unique on/after it
+                }
+            }
+        }
+        return out;
+    }
+
+    /** True when another record in `coll` already holds one of `value`'s `@unique`
+     *  field values (per-tenant uniqueness). `selfSk` is the writing record's store
+     *  key so it never conflicts with itself; empty values are unique-if-present. */
+    private uniqueConflict(coll: DevCollectionHandle, value: Buffer, selfSk: string): boolean {
+        const uvals = this.uniqueValuesOf(coll, value).filter((u) => u.val.length > 0);
+        if (uvals.length === 0) return false;
+        const prefix = coll.name + '\0';
+        for (const [otherSk, otherVal] of this.store) {
+            if (otherSk === selfSk || !otherSk.startsWith(prefix)) continue;
+            const otherUvals = this.uniqueValuesOf(coll, otherVal);
+            for (const u of uvals) {
+                if (otherUvals.some((o) => o.index === u.index && o.val.equals(u.val))) return true;
+            }
+        }
+        return false;
+    }
+
     create(
         ref: MemoryRef,
         db: DbDevState,
@@ -706,9 +770,12 @@ export class DevDatabase {
         if (!start.fresh)
             return start.outcome ? this.replayRecordOutcome(db, start.outcome) : start.status;
         const sk = storeKey(coll.name, key);
-        const outcome: RecordOutcome = this.store.has(sk)
-            ? { kind: 'already_exists' }
-            : { kind: 'unit' };
+        // @unique: a value already held by another record blocks the create, exactly
+        // like the edge's op_create claim (surfaced as AlreadyExists -> create false).
+        const outcome: RecordOutcome =
+            this.store.has(sk) || this.uniqueConflict(coll, value, sk)
+                ? { kind: 'already_exists' }
+                : { kind: 'unit' };
         if (outcome.kind === 'unit') {
             this.store.set(sk, value);
             this.stampVersion(coll, sk); // stamp the value type's current schema version
@@ -740,7 +807,9 @@ export class DevDatabase {
             return start.outcome ? this.replayRecordOutcome(db, start.outcome) : start.status;
         const sk = storeKey(coll.name, key);
         const outcome: RecordOutcome = this.store.has(sk)
-            ? { kind: 'value', value: v, schemaVersion: this.currentSchemaVersion(coll) }
+            ? this.uniqueConflict(coll, v, sk)
+                ? { kind: 'already_exists' } // patch would collide a @unique field
+                : { kind: 'value', value: v, schemaVersion: this.currentSchemaVersion(coll) }
             : { kind: 'not_found' };
         if (outcome.kind === 'value') {
             this.store.set(sk, v);

package/src/devserver/db/types.ts

@@ -28,6 +28,13 @@ export function isCollectionFamily(value: number): value is CollectionFamily {
     return value >= CollectionFamily.Record && value <= CollectionFamily.Capacity;
 }
 
+export interface DevField {
+    name: string;
+    typeName: string;
+    isArray: boolean;
+    unique: boolean;
+}
+
 export interface DevCollectionHandle {
     name: string;
     family: CollectionFamily;
@@ -36,6 +43,9 @@ export interface DevCollectionHandle {
     placement: number;
     fillMaxWaitMs: number;
     fillAllowStale: boolean;
+    /** The value type's field layout (declaration order); present when the catalog
+     *  carried one. Drives @unique enforcement. */
+    fields?: DevField[];
 }
 
 export type DbCatalogState =