@jskit-ai/workspaces-core 0.1.197 → 0.1.198

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/workspaces-core",
-  "version": "0.1.197",
+  "version": "0.1.198",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -18,11 +18,11 @@
     "./shared/resources/workspaceSettingsResource": "./src/shared/resources/workspaceSettingsResource.js"
   },
   "dependencies": {
-    "@jskit-ai/database-runtime": "0.1.219",
-    "@jskit-ai/json-rest-api-core": "0.1.163",
-    "@jskit-ai/resource-core": "0.1.161",
-    "@jskit-ai/resource-crud-core": "0.1.161",
-    "@jskit-ai/users-core": "0.1.232",
+    "@jskit-ai/database-runtime": "0.1.220",
+    "@jskit-ai/json-rest-api-core": "0.1.164",
+    "@jskit-ai/resource-core": "0.1.162",
+    "@jskit-ai/resource-crud-core": "0.1.162",
+    "@jskit-ai/users-core": "0.1.233",
     "json-rest-schema": "^1.0.17"
   },
   "description": "Workspace tenancy runtime plus HTTP routes, role catalog, and workspace config scaffolding.",
@@ -169,8 +169,8 @@
     }
   },
   "peerDependencies": {
-    "@jskit-ai/auth-core": "0.1.217",
-    "@jskit-ai/http-runtime": "0.1.217",
-    "@jskit-ai/kernel": "0.1.219"
+    "@jskit-ai/auth-core": "0.1.218",
+    "@jskit-ai/http-runtime": "0.1.218",
+    "@jskit-ai/kernel": "0.1.220"
   }
 }

package/patterns/workspace-server/PATTERN.md

@@ -28,6 +28,55 @@ member permissions, personal-workspace behavior, and surface access rules.
 Use workspace routes, resources, scope helpers, tenancy profiles, and settings
 contracts exported by `@jskit-ai/workspaces-core`.
 
+## Transactional invitation participation
+
+Use the existing `workspaces.core` capability. During application feature setup,
+register one callback with
+`workspaces.services.pendingInvitations.registerAcceptanceParticipant(fn)`.
+The built-in `workspace.invite.redeem` action invokes
+`fn({ invite, user }, { trx, context })` after recipient/state/expiry validation
+and membership activation inside the same uncommitted managed transaction.
+Forward `trx` to every application owner; throw on invalid reviewed associations
+or failed writes. The framework marks accepted and commits only after success.
+Do not perform external effects or complete the transaction in the participant.
+Non-functions, duplicate registrations and registrations after acceptance/refusal
+begins reject. Ordinary invitations can pass through without an association;
+expected-but-missing, stale, revoked or conflicting associations must fail closed.
+
+For deliberate invitation creation, use `members.prepareInvite(workspace, actor,
+payload, { trx, context })` in `repositories.workspaceInvites.withTransaction`
+or the same JSON REST API's managed `transaction`. It returns
+`{ createdInviteId, inviteTokenPreview }` without delivery. Lock the workspace
+with `repositories.workspaceInvites.lockWorkspaceForInvitations(workspace.id,
+{ trx })` before application draft/receipt rows, and save the exact invitation
+association and retry receipt before commit. Failed association restores any
+prior pending invitation. A draft of intended access should not call preparation.
+
+After confirmed commit, call `members.sendInvite(workspace, actor, prepared,
+{ context })`. A later attempt can pass only `{ createdInviteId }`. Delivery
+reloads the committed pending invitation and uses stored recipient/role/expiry;
+it does not replace the invitation. Its `inviteDelivery` is separate from
+persistence: `mailer_unconfigured` when no mailer is supplied, `failed` on a
+renderer/mailer exception, or the normalized controlled/provider result.
+Interruption or failure may still mean a provider accepted the message. Receipt
+idempotency and delivery retries are application-owned; email is not exactly once.
+Do not log the returned token/URL. No SMTP setup is required for testing.
+
+`createInvite`, acceptance and refusal now own managed transactions and reject
+borrowed `options.trx`. Move transactional creation to preparation/post-commit
+sending and acceptance-related writes into the participant. Revocation may join
+a managed transaction. Raw Knex/savepoint transactions cannot own resource
+writes. Invitation mutations lock workspace then invitation rows, revalidate
+current state and reject attempts to overwrite terminal state. Matching-recipient
+expiry rejection commits revocation before returning 409. Preserve transaction
+outcomes and causes; a completion-hook error after commit cannot undo writes.
+
+See the human guide's **Workspace tenancy → Transactional invitation
+participation** for the full consumer example, errors, controlled mailer,
+compatibility notes and native verification commands. Application services still
+own authorization, identity/training linking, reviewed scope eligibility and
+required audit. This seam adds no application domain tables or policy.
+
 ## Invariants
 
 - Workspace membership and role are checked before scoped application actions.

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

@@ -1,3 +1,4 @@
+import { AppError } from "@jskit-ai/kernel/server/runtime/errors";
 import {
   normalizeLowerText,
   normalizeRecordId,
@@ -83,6 +84,30 @@ function createRepository({ api } = {}) {
   const withTransaction = (work) => api.transaction(work);
 
   async function queryInvites(filters = {}, options = {}, { includeWorkspace = false } = {}) {
+    if (options.lock === true) {
+      if (typeof options.trx !== "function" || includeWorkspace) {
+        throw new TypeError("Locking invites requires a transaction and no relationship includes.");
+      }
+      // Read current rows under lock rather than authorising a state transition
+      // from the ordinary resource query's earlier snapshot.
+      const fields = { id: "id", workspace: "workspace_id", email: "email", status: "status", tokenHash: "token_hash" };
+      const where = Object.fromEntries(Object.entries(filters).map(([key, value]) => {
+        if (!fields[key]) throw new TypeError("Unsupported locking invitation filter.");
+        return [fields[key], value];
+      }));
+      // PostgreSQL's driver interprets timestamp-without-time-zone as local
+      // time. These owner columns store UTC; preserve their database text just
+      // as the resource read path does before toIsoString normalizes it.
+      const dateColumn = (name) => options.trx.client?.config?.client === "pg"
+        ? options.trx.raw("CAST(?? AS TEXT)", [name])
+        : name;
+      return options.trx("workspace_invites").where(where).select({
+        id: "id", workspaceId: "workspace_id", email: "email", roleSid: "role_sid",
+        status: "status", tokenHash: "token_hash", invitedByUserId: "invited_by_user_id",
+        expiresAt: dateColumn("expires_at"), acceptedAt: dateColumn("accepted_at"), revokedAt: dateColumn("revoked_at"),
+        createdAt: dateColumn("created_at"), updatedAt: dateColumn("updated_at")
+      }).forUpdate();
+    }
     return extractJsonRestCollectionRows(
       await api.resources.workspaceInvites.query(
         {
@@ -98,16 +123,34 @@ function createRepository({ api } = {}) {
     );
   }
 
-  async function findPendingByTokenHash(tokenHash, options = {}) {
-    const rows = await queryInvites(
-      {
-        tokenHash: normalizeText(tokenHash),
-        status: "pending"
-      },
-      options
-    );
+  async function lockWorkspaceForInvitations(workspaceId, options = {}) {
+    if (typeof options.trx !== "function" || options.trx.isCompleted?.()) {
+      throw new TypeError("Invitation locking requires an active transaction.");
+    }
+    const id = normalizeRecordId(workspaceId, { fallback: null });
+    if (!id) throw new TypeError("Invitation locking requires workspaceId.");
+    const row = await options.trx("workspaces").where({ id }).forUpdate().first("id");
+    if (!row) throw new AppError(404, "Invitation workspace no longer exists.");
+  }
 
-    return normalizeInviteRecord(rows[0] || null);
+  async function findPendingByTokenHash(tokenHash, options = {}) {
+    if (options.lock === true) {
+      // The service locates the workspace before opening its transaction, then
+      // revalidates this token against current state under workspace/invite locks.
+      await lockWorkspaceForInvitations(options.workspaceId, options);
+    }
+    const filters = options.lock === true
+      ? {
+          id: normalizeRecordId(options.inviteId, { fallback: null }),
+          workspace: normalizeRecordId(options.workspaceId, { fallback: null }),
+          status: "pending"
+        }
+      : { tokenHash: normalizeText(tokenHash), status: "pending" };
+    // The current locking query uses only IDs, keeping bearer-equivalent token
+    // hashes out of native lock-error SQL. Still recheck token correspondence.
+    const rows = await queryInvites(filters, options);
+    const invite = normalizeInviteRecord(rows[0] || null);
+    return invite?.tokenHash === normalizeText(tokenHash) ? invite : null;
   }
 
   async function findByTokenHashWithWorkspace(tokenHash, options = {}) {
@@ -235,6 +278,10 @@ function createRepository({ api } = {}) {
       return;
     }
 
+    if (!options.trx) {
+      return withTransaction((trx) => expirePendingByWorkspaceIdAndEmail(workspaceId, email, { ...options, trx }));
+    }
+    await lockWorkspaceForInvitations(normalizedWorkspaceId, options);
     const patch = normalizeInvitePatchPayload({ status: "expired" });
     const rows = await queryInvites(
       {
@@ -242,7 +289,7 @@ function createRepository({ api } = {}) {
         email: normalizeLowerText(email),
         status: "pending"
       },
-      options
+      { ...options, lock: true }
     );
 
     for (const row of rows) {
@@ -265,50 +312,43 @@ function createRepository({ api } = {}) {
     }
   }
 
-  async function markAcceptedById(inviteId, options = {}) {
-    const normalizedInviteId = normalizeRecordId(inviteId, { fallback: null });
-    if (!normalizedInviteId) {
-      return;
+  async function transitionPendingById(inviteId, status, options = {}) {
+    const id = normalizeRecordId(inviteId, { fallback: null });
+    if (!id) throw new TypeError("Invitation transition requires inviteId.");
+    let workspaceId = options.workspaceId;
+    if (!workspaceId) {
+      const candidate = await queryInvites({ id }, { ...options, lock: false });
+      if (!candidate[0]) throw new AppError(404, "Invitation not found or already handled.");
+      workspaceId = normalizeInviteRecord(candidate[0]).workspaceId;
     }
-
-    const acceptedAt = new Date().toISOString();
+    if (!options.trx) {
+      return withTransaction((trx) => transitionPendingById(id, status, { ...options, trx, workspaceId }));
+    }
+    const invite = await findPendingByIdForWorkspace(id, workspaceId, { ...options, lock: true });
+    if (!invite) throw new AppError(404, "Invitation not found or already handled.");
+    const updatedAt = new Date().toISOString();
     await api.resources.workspaceInvites.patch(
       {
-        id: normalizedInviteId,
+        id,
         data: {
-          status: "accepted",
-          acceptedAt,
-          updatedAt: acceptedAt
+          status,
+          [status === "accepted" ? "acceptedAt" : "revokedAt"]: updatedAt,
+          updatedAt
         },
         format: "plain",
         returning: "full",
-        transaction: options?.trx || null
+        transaction: options.trx
       },
-      createJsonRestContext(options?.context || null)
+      createJsonRestContext(options.context || null)
     );
   }
 
-  async function revokeById(inviteId, options = {}) {
-    const normalizedInviteId = normalizeRecordId(inviteId, { fallback: null });
-    if (!normalizedInviteId) {
-      return;
-    }
+  async function markAcceptedById(inviteId, options = {}) {
+    return transitionPendingById(inviteId, "accepted", options);
+  }
 
-    const revokedAt = new Date().toISOString();
-    await api.resources.workspaceInvites.patch(
-      {
-        id: normalizedInviteId,
-        data: {
-          status: "revoked",
-          revokedAt,
-          updatedAt: revokedAt
-        },
-        format: "plain",
-        returning: "full",
-        transaction: options?.trx || null
-      },
-      createJsonRestContext(options?.context || null)
-    );
+  async function revokeById(inviteId, options = {}) {
+    return transitionPendingById(inviteId, "revoked", options);
   }
 
   async function findPendingByIdForWorkspace(inviteId, workspaceId, options = {}) {
@@ -318,20 +358,25 @@ function createRepository({ api } = {}) {
       return null;
     }
 
+    if (options.lock === true) await lockWorkspaceForInvitations(normalizedWorkspaceId, options);
     const rows = await queryInvites(
       {
         id: normalizedInviteId,
         workspace: normalizedWorkspaceId,
         status: "pending"
       },
-      options
+      options,
+      { includeWorkspace: options.includeWorkspace === true }
     );
 
-    return normalizeInviteRecord(rows[0] || null);
+    return options.includeWorkspace === true
+      ? (rows[0] ? normalizeInviteWithWorkspace(rows[0]) : null)
+      : normalizeInviteRecord(rows[0] || null);
   }
 
   return Object.freeze({
     withTransaction,
+    lockWorkspaceForInvitations,
     findPendingByTokenHash,
     findByTokenHashWithWorkspace,
     listPendingByEmail,

package/src/server/workspaceMembers/workspaceMembersService.js

@@ -1,6 +1,7 @@
 import { normalizeRecordId } from "@jskit-ai/kernel/shared/support/normalize";
 import { normalizeLowerText, normalizeText } from "@jskit-ai/kernel/shared/actions/textNormalization";
-import { buildInviteToken, hashInviteToken } from "@jskit-ai/auth-core/server/inviteTokens";
+import { encodeInviteTokenHash } from "@jskit-ai/auth-core/shared/inviteTokens";
+import { resolveInviteTokenHash, buildInviteToken, hashInviteToken } from "@jskit-ai/auth-core/server/inviteTokens";
 import { AppError } from "@jskit-ai/kernel/server/runtime/errors";
 import { OWNER_ROLE_ID, createWorkspaceRoleCatalog, cloneWorkspaceRoleCatalog } from "../../shared/roles.js";
 import { renderDefaultWorkspaceInviteEmail } from "./defaultWorkspaceInviteEmail.js";
@@ -127,10 +128,11 @@ function createService({
         message
       }, options);
       return normalizeInviteDeliveryResult(result || { status: "sent" });
-    } catch (error) {
+    } catch {
       return {
         status: "failed",
-        message: normalizeText(error?.message || "Unable to send workspace invite email."),
+        // Provider errors can contain the secret invitation URL.
+        message: "Unable to send workspace invite email.",
         providerMessageId: ""
       };
     }
@@ -234,8 +236,11 @@ function createService({
     return listInvitesPayload(workspace, options);
   }
 
-  async function createInvite(workspace, user, payload = {}, options = {}) {
+  // Trusted server composition: authorisation, association and retry receipts
+  // belong to the application. JSON REST writes enforce managed ownership.
+  async function prepareInvite(workspace, user, payload = {}, options = {}) {
     ensureWorkspaceInvitationsEnabled();
+    if (!options.trx) throw new TypeError("prepareInvite requires a managed transaction.");
     const email = normalizeLowerText(payload.email);
     const roleSid = normalizeLowerText(payload.roleSid || "member") || "member";
     if (!assignableRoleIds.includes(roleSid)) {
@@ -251,6 +256,7 @@ function createService({
     const token = buildInviteToken();
     const tokenHash = hashInviteToken(token);
     const expiresAt = new Date(Date.now() + resolvedInviteExpiresInMs).toISOString();
+    await workspaceInvitesRepository.lockWorkspaceForInvitations(workspace.id, options);
     await workspaceInvitesRepository.expirePendingByWorkspaceIdAndEmail(workspace.id, email, options);
     const createdInvite = await workspaceInvitesRepository.insert(
       {
@@ -266,35 +272,56 @@ function createService({
     );
     const createdInviteId = normalizeRecordId(createdInvite?.id, { fallback: null });
     if (!createdInviteId) {
-      throw new Error("workspaceMembersService.createInvite expected repository to return created invite id.");
+      throw new Error("workspaceMembersService.prepareInvite expected repository to return created invite id.");
     }
 
-    const response = await listInvitesPayload(workspace, options);
-    const inviteUrl = resolvedInviteUrlBuilder({
-      token,
-      invite: createdInvite,
-      workspace
-    });
-    const inviteDelivery = await deliverInviteEmail({
-      workspace,
-      user,
-      invite: {
-        ...createdInvite,
-        email,
-        roleSid,
-        expiresAt: createdInvite?.expiresAt || expiresAt
-      },
-      inviteUrl
-    }, options);
+    return { createdInviteId, inviteTokenPreview: token };
+  }
+
+  async function sendInvite(workspace, user, prepared = {}, options = {}) {
+    ensureWorkspaceInvitationsEnabled();
+    if (options.trx) throw new TypeError("sendInvite must run after the invitation transaction commits.");
+    const invite = await workspaceInvitesRepository.findPendingByIdForWorkspace(
+      prepared.createdInviteId, workspace.id, { ...options, includeWorkspace: true, lock: false }
+    );
+    if (!invite) throw new AppError(404, "Invite not found or already handled.");
+    if (invite.expiresAt && new Date(invite.expiresAt).getTime() < Date.now()) {
+      throw new AppError(409, "Invitation has expired.");
+    }
+    const token = Object.hasOwn(prepared, "inviteTokenPreview")
+      ? normalizeText(prepared.inviteTokenPreview)
+      : encodeInviteTokenHash(invite.tokenHash);
+    if (!token || resolveInviteTokenHash(token) !== invite.tokenHash) {
+      throw new AppError(400, "Invitation token does not match the saved invitation.");
+    }
+    const savedWorkspace = {
+      ...workspace,
+      id: invite.workspaceId,
+      slug: invite.workspaceSlug,
+      name: invite.workspaceName,
+      avatarUrl: invite.workspaceAvatarUrl
+    };
+    const inviteUrl = resolvedInviteUrlBuilder({ token, invite, workspace: savedWorkspace });
+    const response = await listInvitesPayload(savedWorkspace, options);
+    const inviteDelivery = await deliverInviteEmail({ workspace: savedWorkspace, user, invite, inviteUrl }, options);
     return {
       ...response,
-      inviteTokenPreview: token,
-      inviteUrl,
-      inviteDelivery,
-      createdInviteId
+      inviteTokenPreview: token, inviteUrl, inviteDelivery,
+      createdInviteId: normalizeRecordId(invite.id, { fallback: null })
     };
   }
 
+  async function createInvite(workspace, user, payload = {}, options = {}) {
+    ensureWorkspaceInvitationsEnabled();
+    if (options.trx) {
+      throw new TypeError("Use prepareInvite inside a transaction, then sendInvite after commit.");
+    }
+    const prepared = await workspaceInvitesRepository.withTransaction((trx) =>
+      prepareInvite(workspace, user, payload, { ...options, trx })
+    );
+    return sendInvite(workspace, user, prepared, options);
+  }
+
   async function revokeInvite(workspace, inviteId, options = {}) {
     ensureWorkspaceInvitationsEnabled();
     const normalizedInviteId = normalizeRecordId(inviteId, { fallback: null });
@@ -302,20 +329,18 @@ function createService({
       throw new AppError(400, "Validation failed.");
     }
 
-    const invite = await workspaceInvitesRepository.findPendingByIdForWorkspace(
-      normalizedInviteId,
-      workspace.id,
-      options
-    );
-    if (!invite) {
-      throw new AppError(404, "Invite not found.");
-    }
-
-    await workspaceInvitesRepository.revokeById(normalizedInviteId, options);
-    const revokedInviteId = normalizeRecordId(invite?.id, { fallback: null });
-    if (!revokedInviteId) {
-      throw new Error("workspaceMembersService.revokeInvite expected repository to return pending invite id.");
-    }
+    const revoke = async (trx) => {
+      const transactionOptions = { ...options, trx, lock: true, workspaceId: workspace.id };
+      const invite = await workspaceInvitesRepository.findPendingByIdForWorkspace(
+        normalizedInviteId, workspace.id, transactionOptions
+      );
+      if (!invite) throw new AppError(404, "Invite not found.");
+      await workspaceInvitesRepository.revokeById(normalizedInviteId, transactionOptions);
+      return normalizeRecordId(invite.id, { fallback: null });
+    };
+    const revokedInviteId = options.trx
+      ? await revoke(options.trx)
+      : await workspaceInvitesRepository.withTransaction(revoke);
 
     const response = await listInvitesPayload(workspace, options);
     return {
@@ -331,6 +356,8 @@ function createService({
     removeMember,
     listInvites,
     createInvite,
+    prepareInvite,
+    sendInvite,
     revokeInvite
   });
 }

package/src/server/workspacePendingInvitations/workspacePendingInvitationsActions.js

@@ -100,7 +100,7 @@ const workspacePendingInvitationsActionSpecifications = Object.freeze([
     events: WORKSPACE_INVITE_DECISION_EVENTS,
     async run(workspacePendingInvitationsService, input, context) {
       const payload = input || {};
-      const user = resolveActionUser(context, input);
+      const user = resolveActionUser(context);
 
       if (payload.decision === "accept") {
         return returnJsonApiData(await workspacePendingInvitationsService.acceptInviteByToken({

package/src/server/workspacePendingInvitations/workspacePendingInvitationsService.js

@@ -12,6 +12,36 @@ function createService({
     throw new Error("workspacePendingInvitationsService requires invite and membership repositories.");
   }
 
+  let acceptanceParticipant = null;
+  let registrationClosed = false;
+
+  function registerAcceptanceParticipant(participant) {
+    if (typeof participant !== "function") throw new TypeError("Acceptance participant must be a function.");
+    if (acceptanceParticipant) throw new Error("An invitation acceptance participant is already registered.");
+    if (registrationClosed) throw new Error("Invitation acceptance participant registration is closed.");
+    acceptanceParticipant = participant;
+  }
+
+  async function inTransaction(user, token, options, work) {
+    if (options.trx) {
+      throw new TypeError("Invitation acceptance/refusal owns its transaction; use the acceptance participant for related writes.");
+    }
+    registrationClosed = true;
+    // Locate the workspace before opening the unit, avoiding a stale MySQL
+    // repeatable-read snapshot while waiting for its lock. Validate again under
+    // that lock; this preliminary read never authorises a write.
+    const initial = await requirePendingInviteForUserByToken(user, token, options);
+    const result = await workspaceInvitesRepository.withTransaction((trx) => work({
+      ...options, trx, lock: true, workspaceId: initial.invite.workspaceId, inviteId: initial.invite.id
+    }));
+    // Expiry revocation intentionally commits before reporting rejection, as it
+    // did before acceptance became atomic. Failed commit keeps its real outcome.
+    if (result.expired) {
+      throw Object.assign(new AppError(409, "Invitation has expired."), { transactionOutcome: "committed" });
+    }
+    return result;
+  }
+
   function requireAuthenticatedInviteUser(user) {
     if (!normalizeRecordId(user?.id, { fallback: null })) {
       throw new AppError(401, "Authentication required.");
@@ -136,13 +166,6 @@ function createService({
     };
   }
 
-  async function revokeExpiredInviteAndThrow(invite, options = {}) {
-    if (invite.expiresAt && new Date(invite.expiresAt).getTime() < Date.now()) {
-      await workspaceInvitesRepository.revokeById(invite.id, options);
-      throw new AppError(409, "Invitation has expired.");
-    }
-  }
-
   async function listPendingInvitesForUser(user, options = {}) {
     const actor = requireAuthenticatedInviteUser(user);
     const actorEmail = normalizeLowerText(actor?.email);
@@ -193,7 +216,10 @@ function createService({
 
   async function resolveInviteActionInput(user, token, options = {}, methodName = "workspacePendingInvitationsService") {
     const resolvedInvite = await requirePendingInviteForUserByToken(user, token, options);
-    await revokeExpiredInviteAndThrow(resolvedInvite.invite, options);
+    if (resolvedInvite.invite.expiresAt && new Date(resolvedInvite.invite.expiresAt).getTime() < Date.now()) {
+      await workspaceInvitesRepository.revokeById(resolvedInvite.invite.id, options);
+      return { expired: true };
+    }
 
     return {
       resolvedInvite,
@@ -202,46 +228,44 @@ function createService({
   }
 
   async function acceptInviteByToken({ user, token } = {}, options = {}) {
-    const { resolvedInvite, workspaceId } = await resolveInviteActionInput(
-      user,
-      token,
-      options,
-      "workspacePendingInvitationsService.acceptInviteByToken"
-    );
-
-    await workspaceMembershipsRepository.upsertMembership(
-      workspaceId,
-      resolvedInvite.user.id,
-      {
-        roleSid: resolvedInvite.invite.roleSid,
-        status: "active"
-      },
-      options
-    );
-    await workspaceInvitesRepository.markAcceptedById(resolvedInvite.invite.id, options);
-
-    return {
-      decision: "accepted",
-      workspaceId
-    };
+    return inTransaction(user, token, options, async (transactionOptions) => {
+      const resolved = await resolveInviteActionInput(
+        user, token, transactionOptions, "workspacePendingInvitationsService.acceptInviteByToken"
+      );
+      if (resolved.expired) return resolved;
+      const { resolvedInvite, workspaceId } = resolved;
+      await workspaceMembershipsRepository.upsertMembership(
+        workspaceId, resolvedInvite.user.id,
+        { roleSid: resolvedInvite.invite.roleSid, status: "active" },
+        transactionOptions
+      );
+      if (acceptanceParticipant) {
+        // Do not expose the repository's lock flag as a general application
+        // option. Freeze the envelope so participants cannot replace trx.
+        await acceptanceParticipant({
+          invite: Object.freeze({ ...resolvedInvite.invite }),
+          user: Object.freeze({ ...resolvedInvite.user })
+        }, Object.freeze({ ...options, trx: transactionOptions.trx }));
+      }
+      await workspaceInvitesRepository.markAcceptedById(resolvedInvite.invite.id, transactionOptions);
+      return { decision: "accepted", workspaceId };
+    });
   }
 
   async function refuseInviteByToken({ user, token } = {}, options = {}) {
-    const { resolvedInvite, workspaceId } = await resolveInviteActionInput(
-      user,
-      token,
-      options,
-      "workspacePendingInvitationsService.refuseInviteByToken"
-    );
-    await workspaceInvitesRepository.revokeById(resolvedInvite.invite.id, options);
-
-    return {
-      decision: "refused",
-      workspaceId
-    };
+    return inTransaction(user, token, options, async (transactionOptions) => {
+      const resolved = await resolveInviteActionInput(
+        user, token, transactionOptions, "workspacePendingInvitationsService.refuseInviteByToken"
+      );
+      if (resolved.expired) return resolved;
+      const { resolvedInvite, workspaceId } = resolved;
+      await workspaceInvitesRepository.revokeById(resolvedInvite.invite.id, transactionOptions);
+      return { decision: "refused", workspaceId };
+    });
   }
 
   return Object.freeze({
+    registerAcceptanceParticipant,
     resolveInviteByToken,
     resolveInviteContextForAuth,
     listPendingInvitesForUser,

package/test/featureRuntime.test.js

@@ -65,6 +65,7 @@ test("WorkspacesFeature assembles workspace behavior and explicit integrations",
     setup({ actions, workspaceCapability }) {
       actionCatalogue = actions;
       workspaces = workspaceCapability;
+      workspaceCapability.services.pendingInvitations.registerAcceptanceParticipant(async () => {});
       return {};
     }
   });
@@ -104,6 +105,10 @@ test("WorkspacesFeature assembles workspace behavior and explicit integrations",
     "workspaces"
   ]);
   assert.equal(typeof workspaces.services.directory.resolveWorkspaceContextForUserBySlug, "function");
+  assert.equal(typeof workspaces.services.members.prepareInvite, "function");
+  assert.equal(typeof workspaces.services.members.sendInvite, "function");
+  assert.throws(() => workspaces.services.pendingInvitations.registerAcceptanceParticipant(null), /must be a function/);
+  assert.throws(() => workspaces.services.pendingInvitations.registerAcceptanceParticipant(async () => {}), /already registered/);
   assert.equal(routes.includes("POST /api/workspaces"), true);
   assert.equal(routes.includes("GET /api/workspace/invitations/resolve"), true);
   assert.equal(actionCatalogue.listDefinitions().length, 16);