@jskit-ai/users-core 0.1.197 → 0.1.199

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/users-core",
-  "version": "0.1.197",
+  "version": "0.1.199",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -13,12 +13,12 @@
     "./shared/resources/userSettingsResource": "./src/shared/resources/userSettingsResource.js"
   },
   "dependencies": {
-    "@jskit-ai/database-runtime": "0.1.184",
-    "@jskit-ai/json-rest-api-core": "0.1.128",
-    "@jskit-ai/resource-core": "0.1.126",
-    "@jskit-ai/resource-crud-core": "0.1.126",
-    "@jskit-ai/storage-runtime": "0.1.181",
-    "@jskit-ai/uploads-runtime": "0.1.159",
+    "@jskit-ai/database-runtime": "0.1.186",
+    "@jskit-ai/json-rest-api-core": "0.1.130",
+    "@jskit-ai/resource-core": "0.1.128",
+    "@jskit-ai/resource-crud-core": "0.1.128",
+    "@jskit-ai/storage-runtime": "0.1.183",
+    "@jskit-ai/uploads-runtime": "0.1.161",
     "json-rest-schema": "^1.0.17"
   },
   "description": "Users/account runtime plus HTTP routes for account features.",
@@ -166,8 +166,8 @@
     }
   },
   "peerDependencies": {
-    "@jskit-ai/auth-core": "0.1.182",
-    "@jskit-ai/http-runtime": "0.1.182",
-    "@jskit-ai/kernel": "0.1.184"
+    "@jskit-ai/auth-core": "0.1.184",
+    "@jskit-ai/http-runtime": "0.1.184",
+    "@jskit-ai/kernel": "0.1.186"
   }
 }

package/patterns/user-administration-server/example/packages/users/package.json

@@ -9,8 +9,8 @@
     "./shared": "./src/shared/index.js"
   },
   "dependencies": {
-    "@jskit-ai/crud-core": "0.1.195",
-    "@jskit-ai/resource-crud-core": "0.1.126"
+    "@jskit-ai/crud-core": "0.1.197",
+    "@jskit-ai/resource-crud-core": "0.1.128"
   },
   "jskit": {
     "kind": "runtime",

package/patterns/user-administration-server/example/packages/users-workspace/package.json

@@ -9,9 +9,9 @@
     "./shared": "./src/shared/index.js"
   },
   "dependencies": {
-    "@jskit-ai/crud-core": "0.1.195",
-    "@jskit-ai/resource-crud-core": "0.1.126",
-    "@jskit-ai/workspaces-core": "0.1.162"
+    "@jskit-ai/crud-core": "0.1.197",
+    "@jskit-ai/resource-crud-core": "0.1.128",
+    "@jskit-ai/workspaces-core": "0.1.164"
   },
   "jskit": {
     "kind": "runtime",

package/src/server/UsersIdentityProvider.js

@@ -14,14 +14,13 @@ const UsersIdentityProvider = defineProvider({
   id: "users.identity",
   requires: {
     authExtensions: "auth.extensions",
-    database: "runtime.database",
     extensions: "users.extensions",
     jsonRestApi: "runtime.json-rest-api"
   },
   provides: {
     identity: "users.identity"
   },
-  async setup({ authExtensions, database, extensions, jsonRestApi }) {
+  async setup({ authExtensions, extensions, jsonRestApi }) {
     const scopeOptions = {
       writeSerializers: { "datetime-utc": toDatabaseDateTimeUtc }
     };
@@ -36,8 +35,8 @@ const UsersIdentityProvider = defineProvider({
       createJsonRestResourceScopeOptions(userSettingsResource, scopeOptions)
     );
     const repositories = Object.freeze({
-      userProfiles: createUserProfilesRepository({ api: jsonRestApi, knex: database.knex }),
-      userSettings: createUserSettingsRepository({ api: jsonRestApi, knex: database.knex })
+      userProfiles: createUserProfilesRepository({ api: jsonRestApi }),
+      userSettings: createUserSettingsRepository({ api: jsonRestApi })
     });
     const profileProjector = createAuthProfileSyncService({
       userProfilesRepository: repositories.userProfiles,

package/src/server/accountNotifications/accountNotificationsActions.js

@@ -17,6 +17,13 @@ const accountNotificationsActionSpecifications = Object.freeze([
     },
     input: userSettingsResource.operations.notificationsUpdate.body,
     output: null,
+    extensions: {
+      assistant: {
+        description: "Update the signed-in user’s notification preferences.",
+        output: userSettingsResource.operations.notificationsUpdate.output,
+        transformResult: (result) => result.value
+      }
+    },
     idempotency: "optional",
     audit: {
       actionName: "settings.notifications.update"

package/src/server/accountPreferences/accountPreferencesActions.js

@@ -17,6 +17,13 @@ const accountPreferencesActionSpecifications = Object.freeze([
     },
     input: userSettingsResource.operations.preferencesUpdate.body,
     output: null,
+    extensions: {
+      assistant: {
+        description: "Update the signed-in user’s display and regional preferences.",
+        output: userSettingsResource.operations.preferencesUpdate.output,
+        transformResult: (result) => result.value
+      }
+    },
     idempotency: "optional",
     audit: {
       actionName: "settings.preferences.update"

package/src/server/accountProfile/accountProfileActions.js

@@ -1,3 +1,4 @@
+import { userSettingsResource } from "../../shared/resources/userSettingsResource.js";
 import {
   emptyInputValidator,
   resolveRequest
@@ -24,6 +25,13 @@ const accountProfileActionSpecifications = deepFreeze([
     },
     input: emptyInputValidator,
     output: null,
+    extensions: {
+      assistant: {
+        description: "Read the signed-in user’s profile, preferences, notifications and security status.",
+        output: userSettingsResource.operations.view.output,
+        transformResult: (result) => result.value
+      }
+    },
     idempotency: "none",
     audit: {
       actionName: "settings.read"
@@ -46,6 +54,13 @@ const accountProfileActionSpecifications = deepFreeze([
     },
     input: settingsProfileUpdateInputValidator,
     output: null,
+    extensions: {
+      assistant: {
+        description: "Update the signed-in user’s display name.",
+        output: userSettingsResource.operations.view.output,
+        transformResult: (result) => result.response.value
+      }
+    },
     idempotency: "optional",
     audit: {
       actionName: "settings.profile.update"
@@ -74,6 +89,11 @@ const accountProfileActionSpecifications = deepFreeze([
     },
     input: userProfileResource.operations.avatarUpload.body,
     output: null,
+    extensions: {
+      assistant: {
+        exclude: "Use the authenticated account profile file picker; upload streams must not enter assistant arguments."
+      }
+    },
     idempotency: "none",
     audit: {
       actionName: "settings.profile.avatar.upload"
@@ -109,6 +129,13 @@ const accountProfileActionSpecifications = deepFreeze([
     },
     input: userProfileResource.operations.avatarDelete.body,
     output: null,
+    extensions: {
+      assistant: {
+        description: "Remove the signed-in user’s uploaded avatar.",
+        output: userSettingsResource.operations.view.output,
+        transformResult: (result) => result.value
+      }
+    },
     idempotency: "none",
     audit: {
       actionName: "settings.profile.avatar.delete"

package/src/server/accountSecurity/accountSecurityActions.js

@@ -25,6 +25,11 @@ const accountSecurityActionSpecifications = Object.freeze([
     },
     input: userSettingsResource.operations.passwordChange.body,
     output: null,
+    extensions: {
+      assistant: {
+        exclude: "Use the authenticated account security form; passwords must not enter assistant arguments."
+      }
+    },
     idempotency: "none",
     audit: {
       actionName: "settings.security.password.change"
@@ -52,6 +57,13 @@ const accountSecurityActionSpecifications = Object.freeze([
     },
     input: userSettingsResource.operations.passwordMethodToggle.body,
     output: null,
+    extensions: {
+      assistant: {
+        description: "Enable or disable password sign-in for the signed-in user, subject to the account authentication policy.",
+        output: userSettingsResource.operations.passwordMethodToggle.output,
+        transformResult: (result) => ({ securityStatus: result.value.securityStatus, settings: result.value.settings })
+      }
+    },
     idempotency: "none",
     audit: {
       actionName: "settings.security.password_method.toggle"
@@ -79,6 +91,11 @@ const accountSecurityActionSpecifications = Object.freeze([
     },
     input: oauthLinkStartInputValidator,
     output: null,
+    extensions: {
+      assistant: {
+        exclude: "Use the authenticated account security screen; OAuth authorization URLs contain transient credentials."
+      }
+    },
     idempotency: "none",
     audit: {
       actionName: "settings.security.oauth.link.start"
@@ -106,6 +123,13 @@ const accountSecurityActionSpecifications = Object.freeze([
     },
     input: userSettingsResource.operations.oauthUnlink.params,
     output: null,
+    extensions: {
+      assistant: {
+        description: "Unlink an OAuth sign-in method from the signed-in account, subject to the account authentication policy.",
+        output: userSettingsResource.operations.oauthUnlink.output,
+        transformResult: (result) => ({ securityStatus: result.value.securityStatus })
+      }
+    },
     idempotency: "none",
     audit: {
       actionName: "settings.security.oauth.unlink"
@@ -133,6 +157,13 @@ const accountSecurityActionSpecifications = Object.freeze([
     },
     input: userSettingsResource.operations.logoutOtherSessions.body,
     output: null,
+    extensions: {
+      assistant: {
+        description: "Sign the current user out of other devices.",
+        output: userSettingsResource.operations.logoutOtherSessions.output,
+        transformResult: () => ({ ok: true })
+      }
+    },
     idempotency: "none",
     audit: {
       actionName: "settings.security.sessions.logout_others"

package/src/server/common/repositories/repositoryUtils.js

@@ -1,9 +1,8 @@
 import {
   normalizeDbRecordId,
-  toIsoString,
-  createWithTransaction
+  toIsoString
 } from "@jskit-ai/database-runtime/shared";
-import { isDuplicateEntryError } from "@jskit-ai/database-runtime/shared/duplicateEntry";
+import { findDuplicateEntryError, isDuplicateEntryError } from "@jskit-ai/database-runtime/shared/duplicateEntry";
 import { normalizeLowerText, normalizeRecordId, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 
 function uniqueSorted(values) {
@@ -32,12 +31,12 @@ function toDbJson(value, fallback = {}) {
 export {
   toIsoString,
   isDuplicateEntryError,
+  findDuplicateEntryError,
   normalizeText,
   normalizeLowerText,
   normalizeRecordId,
   normalizeDbRecordId,
   uniqueSorted,
   parseJson,
-  toDbJson,
-  createWithTransaction
+  toDbJson
 };

package/src/server/common/repositories/userProfilesRepository.js

@@ -1,5 +1,5 @@
 import {
-  createWithTransaction,
+  findDuplicateEntryError,
   isDuplicateEntryError,
   normalizeDbRecordId,
   normalizeLowerText,
@@ -8,13 +8,11 @@ import {
   toIsoString
 } from "./repositoryUtils.js";
 import {
-  createJsonApiInputRecord,
   createJsonRestContext,
   extractJsonRestCollectionRows
 } from "@jskit-ai/json-rest-api-core/server/jsonRestApiHost";
 import { normalizeIdentity } from "../support/identity.js";
 
-const RESOURCE_TYPE = "userProfiles";
 const USERNAME_MAX_LENGTH = 120;
 
 function normalizeUsername(value) {
@@ -114,25 +112,28 @@ function buildUsernameCandidate(baseUsername, suffix) {
 }
 
 function duplicateTargetsEmail(error) {
-  if (!isDuplicateEntryError(error)) {
+  const duplicate = findDuplicateEntryError(error);
+  if (!duplicate) {
     return false;
   }
 
-  const message = normalizeLowerText(error?.sqlMessage || error?.message);
+  const message = normalizeLowerText(duplicate.sqlMessage || duplicate.message);
   return message.includes("email");
 }
 
 function duplicateTargetsUsername(error) {
-  if (!isDuplicateEntryError(error)) {
+  const duplicate = findDuplicateEntryError(error);
+  if (!duplicate) {
     return false;
   }
 
-  const message = normalizeLowerText(error?.sqlMessage || error?.message);
+  const message = normalizeLowerText(duplicate.sqlMessage || duplicate.message);
   return message.includes("username");
 }
 
-function createDuplicateEmailConflictError() {
-  const error = new Error("Email is already linked to a different profile.");
+function createDuplicateEmailConflictError(cause) {
+  const error = new Error("Email is already linked to a different profile.", { cause });
+  error.transactionOutcome = cause.transactionOutcome;
   error.code = "USER_PROFILE_EMAIL_CONFLICT";
   return error;
 }
@@ -150,7 +151,7 @@ async function resolveUniqueUsername(api, baseUsername, { excludeUserId = null,
           }
         },
         transaction,
-        simplified: true
+        format: "plain"
       })
     );
     const existing = existingRows[0] || null;
@@ -163,15 +164,12 @@ async function resolveUniqueUsername(api, baseUsername, { excludeUserId = null,
   throw new Error("Unable to generate unique username.");
 }
 
-function createRepository({ api, knex } = {}) {
+function createRepository({ api } = {}) {
   if (!api?.resources?.userProfiles) {
     throw new TypeError("internal.repository.user-profiles requires json-rest-api userProfiles resource.");
   }
-  if (typeof knex !== "function") {
-    throw new TypeError("internal.repository.user-profiles requires knex.");
-  }
 
-  const withTransaction = createWithTransaction(knex);
+  const withTransaction = (work) => api.transaction(work);
 
   async function queryFirst(filters = {}, options = {}) {
     const rows = extractJsonRestCollectionRows(
@@ -181,7 +179,7 @@ function createRepository({ api, knex } = {}) {
             filters
           },
           transaction: options?.trx || null,
-          simplified: true
+          format: "plain"
         },
         createJsonRestContext(options?.context || null)
       )
@@ -233,16 +231,13 @@ function createRepository({ api, knex } = {}) {
 
     const updated = await api.resources.userProfiles.patch(
       {
-        inputRecord: createJsonApiInputRecord(
-          RESOURCE_TYPE,
-          {
-            displayName,
-            updatedAt: new Date().toISOString()
-          },
-          {
-            id: normalizedUserId
-          }
-        ),
+        id: normalizedUserId,
+        data: {
+          displayName,
+          updatedAt: new Date().toISOString()
+        },
+        format: "plain",
+        returning: "full",
         transaction: options?.trx || null
       },
       createJsonRestContext(options?.context || null)
@@ -259,18 +254,15 @@ function createRepository({ api, knex } = {}) {
 
     const updated = await api.resources.userProfiles.patch(
       {
-        inputRecord: createJsonApiInputRecord(
-          RESOURCE_TYPE,
-          {
-            avatarStorageKey: avatar.avatarStorageKey ?? null,
-            avatarVersion: avatar.avatarVersion ?? null,
-            avatarUpdatedAt: toIsoString(avatar.avatarUpdatedAt ?? new Date()),
-            updatedAt: new Date().toISOString()
-          },
-          {
-            id: normalizedUserId
-          }
-        ),
+        id: normalizedUserId,
+        data: {
+          avatarStorageKey: avatar.avatarStorageKey ?? null,
+          avatarVersion: avatar.avatarVersion ?? null,
+          avatarUpdatedAt: toIsoString(avatar.avatarUpdatedAt ?? new Date()),
+          updatedAt: new Date().toISOString()
+        },
+        format: "plain",
+        returning: "full",
         transaction: options?.trx || null
       },
       createJsonRestContext(options?.context || null)
@@ -287,18 +279,15 @@ function createRepository({ api, knex } = {}) {
 
     const updated = await api.resources.userProfiles.patch(
       {
-        inputRecord: createJsonApiInputRecord(
-          RESOURCE_TYPE,
-          {
-            avatarStorageKey: null,
-            avatarVersion: null,
-            avatarUpdatedAt: null,
-            updatedAt: new Date().toISOString()
-          },
-          {
-            id: normalizedUserId
-          }
-        ),
+        id: normalizedUserId,
+        data: {
+          avatarStorageKey: null,
+          avatarVersion: null,
+          avatarUpdatedAt: null,
+          updatedAt: new Date().toISOString()
+        },
+        format: "plain",
+        returning: "full",
         transaction: options?.trx || null
       },
       createJsonRestContext(options?.context || null)
@@ -330,84 +319,80 @@ function createRepository({ api, knex } = {}) {
         context: options?.context || null
       });
 
-      try {
-        if (existing) {
-          const existingUsername = normalizeUsername(existing.username);
-          const username = existingUsername || (
-            await resolveUniqueUsername(
-              api,
-              requestedUsername || usernameBaseFromEmail(email),
-              { excludeUserId: existing.id, transaction: trx }
-            )
-          );
-
-          const updated = await api.resources.userProfiles.patch(
-            {
-              inputRecord: createJsonApiInputRecord(
-                RESOURCE_TYPE,
-                {
-                  email,
-                  displayName,
-                  username,
-                  updatedAt: new Date().toISOString()
-                },
-                {
-                  id: normalizeDbRecordId(existing.id, { fallback: null })
-                }
-              ),
-              transaction: trx
-            },
-            createJsonRestContext(options?.context || null)
-          );
-
-          return normalizeProfileRecord(updated);
-        }
-
-        const username = await resolveUniqueUsername(
-          api,
-          requestedUsername || usernameBaseFromEmail(email),
-          { transaction: trx }
+      if (existing) {
+        const existingUsername = normalizeUsername(existing.username);
+        const username = existingUsername || (
+          await resolveUniqueUsername(
+            api,
+            requestedUsername || usernameBaseFromEmail(email),
+            { excludeUserId: existing.id, transaction: trx }
+          )
         );
 
-        const created = await api.resources.userProfiles.post(
+        const updated = await api.resources.userProfiles.patch(
           {
-            inputRecord: createJsonApiInputRecord(RESOURCE_TYPE, {
-              authProvider: identity.provider,
-              authProviderUserSid: identity.providerUserId,
+            id: normalizeDbRecordId(existing.id, { fallback: null }),
+            data: {
               email,
               displayName,
               username,
-              createdAt: new Date().toISOString()
-            }),
+              updatedAt: new Date().toISOString()
+            },
+            format: "plain",
+            returning: "full",
             transaction: trx
           },
           createJsonRestContext(options?.context || null)
         );
 
-        return normalizeProfileRecord(created);
-      } catch (error) {
-        if (duplicateTargetsEmail(error)) {
-          throw createDuplicateEmailConflictError();
-        }
-        if (duplicateTargetsUsername(error)) {
-          throw error;
-        }
-        if (!isDuplicateEntryError(error)) {
-          throw error;
-        }
+        return normalizeProfileRecord(updated);
       }
 
-      return findByIdentity(identity, {
-        trx,
-        context: options?.context || null
-      });
+      const username = await resolveUniqueUsername(
+        api,
+        requestedUsername || usernameBaseFromEmail(email),
+        { transaction: trx }
+      );
+
+      const created = await api.resources.userProfiles.post(
+        {
+          data: {
+            authProvider: identity.provider,
+            authProviderUserSid: identity.providerUserId,
+            email,
+            displayName,
+            username,
+            createdAt: new Date().toISOString()
+          },
+          format: "plain",
+          returning: "full",
+          transaction: trx
+        },
+        createJsonRestContext(options?.context || null)
+      );
+
+      return normalizeProfileRecord(created);
     };
 
-    if (options?.trx) {
-      return executeUpsert(options.trx);
+    try {
+      return await (options?.trx ? executeUpsert(options.trx) : withTransaction(executeUpsert));
+    } catch (error) {
+      if (["pending", "rolledBack"].includes(error?.transactionOutcome) && duplicateTargetsEmail(error)) {
+        throw createDuplicateEmailConflictError(error);
+      }
+      // A failed participant cannot recover inside the caller's transaction.
+      if (options?.trx || error?.transactionOutcome !== "rolledBack" || !isDuplicateEntryError(error)) {
+        throw error;
+      }
+      if (duplicateTargetsUsername(error)) {
+        throw error;
+      }
+      const existing = await findByIdentity(identity, { context: options?.context || null });
+      if (existing) {
+        return existing;
+      }
+      throw error;
     }
-
-    return withTransaction(executeUpsert);
   }
 
   return Object.freeze({

package/src/server/common/repositories/userSettingsRepository.js

@@ -1,16 +1,13 @@
 import {
   normalizeRecordId,
-  isDuplicateEntryError,
-  createWithTransaction
+  isDuplicateEntryError
 } from "./repositoryUtils.js";
 import {
-  createJsonApiInputRecord,
   createJsonRestContext,
   extractJsonRestCollectionRows
 } from "@jskit-ai/json-rest-api-core/server/jsonRestApiHost";
 import { DEFAULT_USER_SETTINGS } from "../../../shared/settings.js";
 
-const RESOURCE_TYPE = "userSettings";
 const USER_SETTINGS_PATCH_FIELDS = Object.freeze([
   "theme",
   "locale",
@@ -56,14 +53,11 @@ function createDefaultUserSettingsCreatePayload(userId) {
   };
 }
 
-function createRepository({ api, knex } = {}) {
+function createRepository({ api } = {}) {
   if (!api?.resources?.userSettings) {
     throw new TypeError("userSettingsRepository requires json-rest-api userSettings resource.");
   }
-  if (typeof knex !== "function") {
-    throw new TypeError("userSettingsRepository requires knex.");
-  }
-  const withTransaction = createWithTransaction(knex);
+  const withTransaction = (work) => api.transaction(work);
 
   async function queryFirst(filters = {}, options = {}) {
     const rows = extractJsonRestCollectionRows(
@@ -73,7 +67,7 @@ function createRepository({ api, knex } = {}) {
             filters
           },
           transaction: options?.trx || null,
-          simplified: true
+          format: "plain"
         },
         createJsonRestContext(options?.context || null)
       )
@@ -105,19 +99,15 @@ function createRepository({ api, knex } = {}) {
     try {
       await api.resources.userSettings.post(
         {
-          inputRecord: createJsonApiInputRecord(
-            RESOURCE_TYPE,
-            createDefaultUserSettingsCreatePayload(normalizedUserId),
-            {
-              id: normalizedUserId
-            }
-          ),
+          data: createDefaultUserSettingsCreatePayload(normalizedUserId),
+          format: "plain",
+          returning: "full",
           transaction: options?.trx || null
         },
         createJsonRestContext(options?.context || null)
       );
     } catch (error) {
-      if (!isDuplicateEntryError(error)) {
+      if (options?.trx || error?.transactionOutcome !== "rolledBack" || !isDuplicateEntryError(error)) {
         throw error;
       }
     }
@@ -141,16 +131,13 @@ function createRepository({ api, knex } = {}) {
 
     await api.resources.userSettings.patch(
       {
-        inputRecord: createJsonApiInputRecord(
-          RESOURCE_TYPE,
-          {
-            ...updatePayload,
-            updatedAt: new Date().toISOString()
-          },
-          {
-            id: normalizedUserId
-          }
-        ),
+        id: normalizedUserId,
+        data: {
+          ...updatePayload,
+          updatedAt: new Date().toISOString()
+        },
+        format: "plain",
+        returning: "full",
         transaction: options?.trx || null
       },
       createJsonRestContext(options?.context || null)

package/test/authProfileSyncService.test.js

@@ -147,3 +147,31 @@ test("authProfileSyncService.findByIdentity normalizes provider identity input",
     providerUserId: "user-1"
   });
 });
+
+test("auth profile sync joins the supplied managed transaction and propagates contributor failure", async () => {
+  const trx = { trxId: "managed-profile-sync" };
+  const failure = new Error("Lifecycle participant failed");
+  const calls = [];
+  const profile = {
+    id: "7", authProvider: "local", authProviderUserSid: "local-7",
+    email: "ada@example.com", displayName: "Ada"
+  };
+  const service = createService({
+    userProfilesRepository: {
+      async findByIdentity(_identity, options) { calls.push(options.trx); return null; },
+      async upsert(_data, options) { calls.push(options.trx); return profile; },
+      async withTransaction() { throw new Error("Must join the caller's owner"); }
+    },
+    userSettingsRepository: {
+      async ensureForUserId(_id, options) { calls.push(options.trx); }
+    },
+    resolveLifecycleContributors: () => [{
+      async afterIdentityProfileSynced({ options }) {
+        calls.push(options.trx);
+        throw failure;
+      }
+    }]
+  });
+  await assert.rejects(service.syncIdentityProfile(profile, { trx }), error => error === failure);
+  assert.deepEqual(calls, [trx, trx, trx, trx]);
+});

package/test/featureRuntime.test.js

@@ -46,7 +46,6 @@ test("UsersFeature assembles account behavior through explicit capabilities", as
       "auth.extensions": authExtensions,
       "auth.service": {},
       "runtime.bootstrap": bootstrap,
-      "runtime.database": { knex() {} },
       "runtime.http": {
         router: {
           register(method, path) {

package/test/repositoryContracts.test.js

@@ -5,27 +5,17 @@ import { userProfileResource } from "../src/shared/resources/userProfileResource
 import { createRepository as createUserProfilesRepository } from "../src/server/common/repositories/userProfilesRepository.js";
 import { createRepository as createUserSettingsRepository } from "../src/server/common/repositories/userSettingsRepository.js";
 
-function createKnexStub() {
-  const knex = Object.assign(() => {
-    throw new Error("query execution not expected");
-  }, {
-    async transaction(work) {
-      return work({ trxId: "trx-1" });
-    }
-  });
-
-  return knex;
-}
-
 function asCollectionDocument(rows = []) {
   return {
     data: Array.isArray(rows) ? rows : []
   };
 }
 
-test("users-core repositories expose withTransaction", async () => {
-  const knex = createKnexStub();
+test("users-core repositories delegate transaction ownership and failures to the API", async () => {
   const api = {
+    async transaction(work) {
+      return work({ trxId: "managed-1" });
+    },
     resources: {
       userProfiles: {
         async query() {
@@ -40,14 +30,16 @@ test("users-core repositories expose withTransaction", async () => {
     }
   };
   const repositories = [
-    createUserProfilesRepository({ api, knex }),
-    createUserSettingsRepository({ api, knex })
+    createUserProfilesRepository({ api }),
+    createUserSettingsRepository({ api })
   ];
 
   for (const repository of repositories) {
     assert.equal(typeof repository.withTransaction, "function");
     const result = await repository.withTransaction(async (trx) => ({ id: trx.trxId }));
-    assert.deepEqual(result, { id: "trx-1" });
+    assert.deepEqual(result, { id: "managed-1" });
+    const failure = new Error("Participant failed");
+    await assert.rejects(repository.withTransaction(async () => { throw failure; }), error => error === failure);
   }
 });
 
@@ -59,7 +51,8 @@ function createUserProfilesApiStub(expectedRecord) {
     api: {
       resources: {
         userProfiles: {
-          async query({ queryParams }) {
+          async query({ queryParams, format }) {
+            assert.equal(format, "plain");
             calls.push(queryParams?.filters || {});
             return asCollectionDocument(
               expectedRecord ? [{
@@ -74,12 +67,11 @@ function createUserProfilesApiStub(expectedRecord) {
   };
 }
 
-test("userSettingsRepository.ensureForUserId sends transaction outside simplified attributes", async () => {
+test("userSettingsRepository.ensureForUserId sends transaction outside plain data", async () => {
   const trx = { trxId: "trx-1" };
   let queryCount = 0;
   let postParams = null;
   const repository = createUserSettingsRepository({
-    knex: createKnexStub(),
     api: {
       resources: {
         userSettings: {
@@ -108,28 +100,25 @@ test("userSettingsRepository.ensureForUserId sends transaction outside simplifie
 
   const record = await repository.ensureForUserId("7", { trx });
 
-  assert.equal(postParams?.simplified, undefined);
+  assert.equal(postParams?.format, "plain");
+  assert.equal(postParams?.returning, "full");
   assert.equal(postParams?.transaction, trx);
-  assert.deepEqual(postParams?.inputRecord?.data, {
-    type: "userSettings",
+  assert.deepEqual(postParams?.data, {
     id: "7",
-    attributes: {
-      id: "7",
-      ...DEFAULT_USER_SETTINGS
-    }
+    ...DEFAULT_USER_SETTINGS
   });
   assert.equal(record?.id, "7");
 });
 
-test("userProfilesRepository.upsert sends native JSON:API write documents with transaction outside the record body", async () => {
+test("userProfilesRepository.upsert sends plain data with transaction outside the record body", async () => {
   const trx = { trxId: "trx-1" };
   let postParams = null;
   const repository = createUserProfilesRepository({
-    knex: createKnexStub(),
     api: {
       resources: {
         userProfiles: {
-          async query({ queryParams }) {
+          async query({ queryParams, format }) {
+            assert.equal(format, "plain");
             const filters = queryParams?.filters || {};
             if (Object.hasOwn(filters, "authProvider") || Object.hasOwn(filters, "authProviderUserSid")) {
               return asCollectionDocument([]);
@@ -141,7 +130,7 @@ test("userProfilesRepository.upsert sends native JSON:API write documents with t
           },
           async post(params) {
             postParams = params;
-            const attributes = params.inputRecord?.data?.attributes || {};
+            const attributes = params.data || {};
             return {
               id: "11",
               authProvider: attributes.authProvider,
@@ -167,11 +156,13 @@ test("userProfilesRepository.upsert sends native JSON:API write documents with t
     displayName: "Ada Example"
   }, { trx });
 
-  assert.equal(postParams?.simplified, undefined);
+  assert.equal(postParams?.format, "plain");
+  assert.equal(postParams?.returning, "full");
   assert.equal(postParams?.transaction, trx);
-  assert.equal(postParams?.inputRecord?.transaction, undefined);
-  assert.equal(postParams?.inputRecord?.data?.type, "userProfiles");
-  assert.equal(postParams?.inputRecord?.data?.attributes?.authProvider, "supabase");
+  assert.equal(postParams?.data?.transaction, undefined);
+  assert.equal(postParams?.document, undefined);
+  assert.equal(postParams?.inputRecord, undefined);
+  assert.equal(postParams?.data?.authProvider, "supabase");
   assert.equal(record?.id, "11");
 });
 
@@ -192,11 +183,11 @@ test("userProfilesRepository.upsert patches existing profiles with resource-back
   };
   let patchParams = null;
   const repository = createUserProfilesRepository({
-    knex: createKnexStub(),
     api: {
       resources: {
         userProfiles: {
-          async query({ queryParams }) {
+          async query({ queryParams, format }) {
+            assert.equal(format, "plain");
             const filters = queryParams?.filters || {};
             if (Object.hasOwn(filters, "authProvider") || Object.hasOwn(filters, "authProviderUserSid")) {
               return asCollectionDocument([existingRecord]);
@@ -208,7 +199,7 @@ test("userProfilesRepository.upsert patches existing profiles with resource-back
           },
           async patch(params) {
             patchParams = params;
-            const attributes = params.inputRecord?.data?.attributes || {};
+            const attributes = params.data || {};
             return {
               ...existingRecord,
               ...attributes
@@ -226,7 +217,7 @@ test("userProfilesRepository.upsert patches existing profiles with resource-back
     displayName: "Ada Renamed"
   }, { trx });
 
-  const attributes = patchParams?.inputRecord?.data?.attributes || {};
+  const attributes = patchParams?.data || {};
   assert.equal(userProfileResource.schema.updatedAt?.type, "dateTime");
   assert.equal(userProfileResource.schema.updatedAt?.storage?.column, "updated_at");
   assert.equal(userProfileResource.schema.updatedAt?.storage?.writeSerializer, "datetime-utc");
@@ -244,7 +235,6 @@ test("userProfilesRepository profile patch helpers stamp updatedAt through the r
   const trx = { trxId: "trx-1" };
   const calls = [];
   const repository = createUserProfilesRepository({
-    knex: createKnexStub(),
     api: {
       resources: {
         userProfiles: {
@@ -253,9 +243,9 @@ test("userProfilesRepository profile patch helpers stamp updatedAt through the r
           },
           async patch(params) {
             calls.push(params);
-            const attributes = params.inputRecord?.data?.attributes || {};
+            const attributes = params.data || {};
             return {
-              id: params.inputRecord?.data?.id || "7",
+              id: params.id || "7",
               authProvider: "local",
               authProviderUserSid: "local-user-7",
               email: "ada@example.com",
@@ -285,21 +275,26 @@ test("userProfilesRepository profile patch helpers stamp updatedAt through the r
   assert.equal(calls.length, 3);
   for (const call of calls) {
     assert.equal(call.transaction, trx);
-    assert.equal(typeof call.inputRecord?.data?.attributes?.updatedAt, "string");
+    assert.equal(call.id, "7");
+    assert.equal(call.format, "plain");
+    assert.equal(call.returning, "full");
+    assert.equal(call.document, undefined);
+    assert.equal(call.inputRecord, undefined);
+    assert.equal(typeof call.data?.updatedAt, "string");
   }
-  assert.deepEqual(Object.keys(calls[0].inputRecord.data.attributes).sort(), ["displayName", "updatedAt"]);
-  assert.deepEqual(Object.keys(calls[1].inputRecord.data.attributes).sort(), [
+  assert.deepEqual(Object.keys(calls[0].data).sort(), ["displayName", "updatedAt"]);
+  assert.deepEqual(Object.keys(calls[1].data).sort(), [
     "avatarStorageKey",
     "avatarUpdatedAt",
     "avatarVersion",
     "updatedAt"
   ]);
-  assert.equal(calls[1].inputRecord.data.attributes.avatarStorageKey, "avatars/7.png");
-  assert.equal(calls[1].inputRecord.data.attributes.avatarVersion, "v1");
-  assert.equal(calls[1].inputRecord.data.attributes.avatarUpdatedAt, avatarUpdatedAt.toISOString());
-  assert.deepEqual(calls[2].inputRecord.data.attributes.avatarStorageKey, null);
-  assert.deepEqual(calls[2].inputRecord.data.attributes.avatarVersion, null);
-  assert.deepEqual(calls[2].inputRecord.data.attributes.avatarUpdatedAt, null);
+  assert.equal(calls[1].data.avatarStorageKey, "avatars/7.png");
+  assert.equal(calls[1].data.avatarVersion, "v1");
+  assert.equal(calls[1].data.avatarUpdatedAt, avatarUpdatedAt.toISOString());
+  assert.deepEqual(calls[2].data.avatarStorageKey, null);
+  assert.deepEqual(calls[2].data.avatarVersion, null);
+  assert.deepEqual(calls[2].data.avatarUpdatedAt, null);
 });
 
 test("userProfilesRepository.findByEmail normalizes email lookup", async () => {
@@ -316,8 +311,7 @@ test("userProfilesRepository.findByEmail normalizes email lookup", async () => {
     createdAt: "2026-04-20T00:00:00.000Z"
   });
   const repository = createUserProfilesRepository({
-    api,
-    knex: createKnexStub()
+    api
   });
 
   const profile = await repository.findByEmail(" ADA@EXAMPLE.COM ");
@@ -342,8 +336,7 @@ test("userProfilesRepository.findByIdentity reads existing profiles from collect
     createdAt: "2026-04-20T00:00:00.000Z"
   });
   const repository = createUserProfilesRepository({
-    api,
-    knex: createKnexStub()
+    api
   });
 
   const profile = await repository.findByIdentity({
@@ -362,11 +355,158 @@ test("userProfilesRepository.findByIdentity reads existing profiles from collect
 test("userProfilesRepository.findByEmail returns null when the row is missing", async () => {
   const { api } = createUserProfilesApiStub(undefined);
   const repository = createUserProfilesRepository({
-    api,
-    knex: createKnexStub()
+    api
   });
 
   const profile = await repository.findByEmail("missing@example.com");
 
   assert.equal(profile, null);
 });
+
+for (const outcome of ["pending", "committed", "unknown"]) {
+  test(`user settings preserves a ${outcome} write failure instead of recovering as a duplicate`, async () => {
+    let reads = 0;
+    const failure = Object.assign(new Error("Write failed"), {
+      transactionOutcome: outcome,
+      cause: { code: "23505" }
+    });
+    const api = {
+      resources: {
+        userSettings: {
+          async query() { reads += 1; return asCollectionDocument([]); },
+          async post() { throw failure; }
+        }
+      }
+    };
+    const repository = createUserSettingsRepository({ api });
+    await assert.rejects(repository.ensureForUserId("7"), error => error === failure);
+    assert.equal(reads, 1);
+  });
+}
+
+test("user settings recovers a duplicate only after its standalone write rolled back", async () => {
+  let reads = 0;
+  const existing = { id: "7", ...DEFAULT_USER_SETTINGS };
+  const api = {
+    resources: {
+      userSettings: {
+        async query() { reads += 1; return asCollectionDocument(reads === 1 ? [] : [existing]); },
+        async post() {
+          throw Object.assign(new Error("Write failed"), {
+            transactionOutcome: "rolledBack", cause: { code: "23505" }
+          });
+        }
+      }
+    }
+  };
+  const repository = createUserSettingsRepository({ api });
+  assert.deepEqual(await repository.ensureForUserId("7"), existing);
+  assert.equal(reads, 2);
+});
+
+test("profile upsert performs duplicate recovery after its API transaction has finished", async () => {
+  const trx = { trxId: "managed-upsert" };
+  const profile = {
+    id: "7", authProvider: "local", authProviderUserSid: "local-7",
+    email: "ada@example.com", username: "ada", displayName: "Ada"
+  };
+  let active = false;
+  let rolledBack = false;
+  const api = {
+    async transaction(work) {
+      active = true;
+      try {
+        return await work(trx);
+      } catch (cause) {
+        active = false;
+        rolledBack = true;
+        throw Object.assign(new Error("Transaction failed", { cause }), { transactionOutcome: "rolledBack" });
+      }
+    },
+    resources: {
+      userProfiles: {
+        async query({ transaction, queryParams, format }) {
+          assert.equal(format, "plain");
+          if (active) {
+            assert.equal(transaction, trx);
+            return asCollectionDocument([]);
+          }
+          assert.equal(rolledBack, true);
+          assert.equal(transaction, null);
+          assert.equal(queryParams.filters.authProviderUserSid, "local-7");
+          return asCollectionDocument([profile]);
+        },
+        async post({ transaction }) {
+          assert.equal(transaction, trx);
+          throw Object.assign(new Error("Duplicate identity"), {
+            transactionOutcome: "pending", cause: { code: "23505", message: "unique provider identity" }
+          });
+        }
+      }
+    }
+  };
+  const repository = createUserProfilesRepository({ api });
+  assert.equal((await repository.upsert(profile)).id, "7");
+  assert.equal(active, false);
+});
+
+test("profile upsert never recovers inside a caller-owned failed transaction", async () => {
+  const trx = { trxId: "caller-managed" };
+  let reads = 0;
+  const failure = Object.assign(new Error("Duplicate identity"), {
+    transactionOutcome: "pending", cause: { code: "23505" }
+  });
+  const api = {
+    async transaction() { throw new Error("Must join the caller's owner"); },
+    resources: {
+      userProfiles: {
+        async query({ transaction }) {
+          assert.equal(transaction, trx);
+          reads += 1;
+          return asCollectionDocument([]);
+        },
+        async post() { throw failure; }
+      }
+    }
+  };
+  const repository = createUserProfilesRepository({ api });
+  await assert.rejects(repository.upsert({
+    authProvider: "local", authProviderUserSid: "local-7",
+    email: "ada@example.com", displayName: "Ada"
+  }, { trx }), error => error === failure);
+  assert.equal(reads, 2);
+});
+
+for (const outcome of ["pending", "committed", "unknown"]) {
+  test(`profile email conflict preserves the ${outcome} outcome from a caller-owned write`, async () => {
+    const trx = { trxId: "caller-managed" };
+    let reads = 0;
+    const failure = Object.assign(new Error("Resource write failed"), {
+      transactionOutcome: outcome,
+      cause: { code: "23505", message: "duplicate key in users_email_unique" }
+    });
+    const api = {
+      resources: {
+        userProfiles: {
+          async query() { reads += 1; return asCollectionDocument([]); },
+          async post() { throw failure; }
+        }
+      }
+    };
+    const repository = createUserProfilesRepository({ api });
+    await assert.rejects(repository.upsert({
+      authProvider: "local", authProviderUserSid: "local-7",
+      email: "ada@example.com", displayName: "Ada"
+    }, { trx }), error => {
+      if (outcome === "pending") {
+        assert.equal(error.code, "USER_PROFILE_EMAIL_CONFLICT");
+        assert.equal(error.cause, failure);
+      } else {
+        assert.equal(error, failure);
+      }
+      assert.equal(error.transactionOutcome, outcome);
+      return true;
+    });
+    assert.equal(reads, 2);
+  });
+}