@jskit-ai/agent-docs 0.1.191 → 0.1.193

package/guide/agent/app-setup/existing-application-migration.md

@@ -222,6 +222,36 @@ not undo the write. Do not turn pending, committed, or unknown write failures
 into successful missing-record results, or automatically replay a committed
 or unresolved write.
 
+### Workspace invitation transaction compatibility (workspaces-core 0.1.198)
+
+Workspace invitation creation, acceptance and refusal now own managed
+transactions. Existing calls to `members.createInvite(..., { trx })` must become
+`members.prepareInvite(..., { trx })`, application association/receipt writes,
+confirmed commit, then `members.sendInvite(...)` without `trx`. Move writes that
+must accompany built-in acceptance into
+`pendingInvitations.registerAcceptanceParticipant(fn)` during feature setup.
+Acceptance/refusal reject borrowed transactions; revocation can still participate
+in a managed transaction. Ordinary invitation actions retain their IDs and
+response shapes. Terminal repository transitions now reject instead of
+rewriting already accepted/revoked invitations. Mailer exceptions return a fixed
+message to avoid leaking invitation tokens from provider diagnostics.
+
+Required participant writes roll back together. Preserve transaction outcomes:
+a failure after commit is not rollback, and an unresolved commit must not be
+blindly replayed. Matching-recipient expiry revocation deliberately commits
+before its 409 rejection. Review the
+[workspace invitation contract and example](./multi-homing.md#transactional-invitation-participation)
+when migrating. No schema migration is required for these framework APIs.
+
+The first coordinated release containing this contract includes
+`@jskit-ai/workspaces-core@0.1.198`, `@jskit-ai/jskit-catalog@0.1.245` and
+`@jskit-ai/agent-docs@0.1.192`. Once that release is published, use
+`npm run jskit:update` in the application to upgrade the coordinated graph,
+restart the backend, check the actual installed versions, and assert
+that `prepareInvite`, `sendInvite` and `registerAcceptanceParticipant` are present
+on the resolved capability. Application domain integration and real email
+activation remain separate work.
+
 ## 4. Adopt migrations without breaking either database history
 
 Every immutable migration belongs to the package that owns its tables. Declare

package/guide/agent/app-setup/multi-homing.md

@@ -39,6 +39,218 @@ before an operation discloses records or record existence.
 membership semantics exactly; do not synthesize memberships to compensate for
 a policy/runtime mismatch.
 
+## Transactional invitation participation
+
+Use the existing `workspaces.core` capability when accepting an invitation must
+also connect an application-owned identity, training history, access scopes or
+required audit records. JSKIT owns tokens, invitation state and membership; the
+application owns its reviewed association and domain policy. The built-in
+`workspace.invite.redeem` action runs the participant. No replacement route,
+client follow-up save or after-action event is needed.
+
+Saving intended access without sending remains an application draft. Do not call
+preparation until an administrator deliberately issues an invitation: preparation
+creates a real token and pending invitation, but does not activate membership.
+
+### Public server methods
+
+These methods are trusted server composition APIs, not new public actions. The
+caller must authorize creation, delivery and revocation in the requested workspace.
+The ordinary invitation routes retain their existing authorization and role
+validation. Do not forward arbitrary HTTP input as server composition options.
+
+| Capability method | Contract |
+| --- | --- |
+| `workspaces.repositories.workspaceInvites.withTransaction(work)` | Delegates to the same JSON REST API's managed `transaction(work)`; awaits commit and completion hooks before resolving. |
+| `workspaces.repositories.workspaceInvites.lockWorkspaceForInvitations(workspaceId, { trx })` | Locks the workspace before application receipt/draft rows when composing preparation. Requires an active transaction. |
+| `workspaces.services.members.prepareInvite(workspace, actor, payload, options)` | Requires a managed `options.trx`. Validates the invitation role, replaces pending invitations for that workspace/email, and returns `{ createdInviteId, inviteTokenPreview }`. Never sends. |
+| `workspaces.services.members.sendInvite(workspace, actor, prepared, options)` | Requires no `options.trx`. Reloads the committed pending invitation and workspace display data, validates expiry and token correspondence, and sends that invitation without replacement. |
+| `workspaces.services.members.createInvite(workspace, actor, payload, options)` | Owns preparation and commit, then calls `sendInvite`; retains the ordinary response shape. Rejects `options.trx`. |
+| `workspaces.services.pendingInvitations.registerAcceptanceParticipant(fn)` | Registers one application callback receiving `({ invite, user }, options)`. Invalid, duplicate and late registration reject. |
+
+`sendInvite` accepts `{ createdInviteId, inviteTokenPreview }` from preparation or
+only `{ createdInviteId }` for a later attempt. The latter uses JSKIT's existing
+opaque token-hash encoding without rotating the token. Supplying an empty or
+mismatched token rejects. Email, role, expiry and workspace display fields come
+from the stored invitation/workspace, not replacement input. Its response keeps
+`createdInviteId`, `inviteTokenPreview`, `inviteUrl` and `inviteDelivery` alongside
+the ordinary workspace/invitation-list payload. Treat tokens and URLs as secrets;
+do not log them or put them in diagnostic messages or administrative receipts.
+A receipt normally needs only the exact invitation ID.
+
+### Preparation, association, commit and controlled delivery
+
+Inside application feature setup, declare `workspaces: "workspaces.core"` in
+`requires`, then use that capability. The `reviewedPeople`, `people`, `scopes`
+and `audit` names below represent application-owned services, not JSKIT APIs.
+Their writes must forward the provided transaction to their repositories.
+
+```js
+// During application Feature.setup, before serving requests:
+const { members, pendingInvitations } = workspaces.services;
+const invites = workspaces.repositories.workspaceInvites;
+
+pendingInvitations.registerAcceptanceParticipant(async ({ invite, user }, options) => {
+  // Resolve from the exact validated invitation, never a client person ID.
+  const association = await reviewedPeople.resolveInvitation(invite.id, options);
+  if (association.kind === "ordinary") return;
+  await reviewedPeople.requireCurrentReview(association, {
+    workspaceId: invite.workspaceId,
+    user,
+    roleSid: invite.roleSid
+  }, options);
+  await people.linkAccountAndTraining(association.personId, user.id, options);
+  await scopes.applyReviewedAccess(association, user.id, options);
+  await audit.recordInvitationAcceptance(association, user.id, options);
+});
+
+// Inside an authorized application command:
+const prepared = await invites.withTransaction(async (trx) => {
+  const options = { trx, context };
+  // Match acceptance's order: workspace, then application draft/receipt rows.
+  await invites.lockWorkspaceForInvitations(workspace.id, options);
+  const reviewed = await reviewedPeople.lockAuthorizedDraft(draftId, workspace.id, actor, options);
+  const receipt = await reviewedPeople.findMatchingReceipt(reviewed, requestId, options);
+  if (receipt) return { createdInviteId: receipt.inviteId };
+  const created = await members.prepareInvite(workspace, actor, {
+    email: reviewed.email,
+    roleSid: reviewed.roleSid
+  }, options);
+  await reviewedPeople.associateInvitationAndSaveReceipt(reviewed, requestId, created.createdInviteId, options);
+  return { createdInviteId: created.createdInviteId };
+}); // Confirmed commit; a rejection here must not fall through to delivery.
+
+const result = await members.sendInvite(workspace, actor, prepared, { context });
+// Persist delivery feedback through the application owner. Avoid logging result:
+// it contains a secret token and URL as well as the nonsecret delivery outcome.
+await reviewedPeople.recordDeliveryOutcome(prepared.createdInviteId, result.inviteDelivery, { context });
+```
+
+The application must lock its reviewed draft/receipt, enforce request identity,
+and reject changed input on a reused request ID. A retry after losing the
+preparation response reads that receipt instead of preparing another invitation.
+Association failure rolls back the new invitation, replacement of an older
+invitation, receipt and application writes. This is not generic framework
+idempotency, and does not imply exactly-once email.
+
+Real SMTP is unnecessary for implementation and verification. With no
+`workspaceInviteMailer`, delivery returns `status: "mailer_unconfigured"`, an
+explanatory `message` and an empty `providerMessageId`; the invitation remains
+committed. A test application can configure a controlled mailer:
+
+```js
+workspaceInviteMailer: {
+  async sendWorkspaceInvite(message) {
+    capturedInvites.push(message); // Test-local memory; contains the secret link.
+    return { status: "sent", message: "Captured by test mailer.", providerMessageId: "fixture-1" };
+  }
+}
+```
+
+A thrown renderer/mailer error returns `inviteDelivery.status: "failed"` and a
+fixed message, avoiding accidental token leakage through provider exceptions.
+It does not delete the invitation/association or activate membership. Mailer
+results retain their normalized status, message and provider message ID; a
+successful default is `sent`. A provider exception or interrupted response may
+occur after a provider accepted the message: `failed` is not proof of nondelivery.
+There is no exactly-once delivery guarantee. Applications own durable delivery
+attempts and safe retry policy. Validation checks committed invitation state
+before sending; revocation after sending starts cannot recall the message.
+
+### Acceptance and failure semantics
+
+Register one callback during feature setup. It composes any application domain
+owners explicitly. Non-functions throw `TypeError`; a second registration
+throws, and registration closes when acceptance/refusal first begins. The
+callback's invite, user and options envelope are shallow frozen. It receives the
+same managed `trx` and request `context`; transaction ownership stays with JSKIT.
+
+Acceptance authenticates the user, checks email, pending state and expiry, then
+revalidates the invitation under workspace/invitation locks. Membership is
+available as active inside that transaction before the callback runs. Existing
+role-upsert semantics remain: the stored invitation role becomes the membership
+role, including for an existing membership. The callback cannot authorize role
+or scope overrides from client input. It must recheck the reviewed version,
+workspace, current inviter authority, person eligibility, existing account link,
+and scope eligibility using application-owned data.
+
+An ordinary invitation with no application association may pass through. A
+stale, revoked, conflicting or expected-but-missing association must fail closed.
+The application needs enough durable association/review state to distinguish
+these cases; absence alone cannot identify a deleted reviewed association.
+
+Await every owner write and forward the same transaction. Do not commit,
+roll back, use savepoints, start a new transaction, or perform external side
+effects in the callback. Do not swallow failures. Participant exceptions and
+later invitation-status failures roll back membership (including its prior role
+and status), person/training links, scopes, required audit and accepted status.
+The callback is not invoked for an invalid invitation or on refusal. Acceptance
+and refusal reject borrowed `options.trx`; revocation can join a managed
+transaction or own one when none is supplied.
+
+A missing/already-handled invitation rejects with 404; mismatched authenticated
+email with 403; unauthenticated access with 401. An expired invitation for its
+matching recipient is revoked in a committed transaction and then rejects with
+409 and `transactionOutcome: "committed"`. It never activates membership or
+runs the participant. A failure to commit that revocation preserves the managed
+transaction error instead. Delivery rejects missing/foreign/handled invitations
+with 404, expired invitations with 409, and mismatched tokens with 400.
+
+Keep `error.transactionOutcome` and `error.cause` when translating failures.
+`rolledBack` confirms rollback; `committed` can indicate a completion-hook error
+after successful persistence; `unknown` leaves the outcome unresolved. A thrown
+error alone does not prove rollback. After-commit failures and external effects
+cannot be included in the atomic guarantee. See
+[managed transaction guidance](./existing-application-migration.md#json-rest-v2-integration).
+
+Invitation mutations lock workspace before invitation rows, and use current
+locking reads before terminal transitions. Accepted/revoked state cannot be
+overwritten by a losing acceptance, refusal, revocation or replacement. A
+replacement after acceptance may create a new pending invitation while retaining
+the older accepted invitation. Keep callbacks short: invitation changes in the
+same workspace serialize. Database deadlocks/serialization failures remain
+transaction errors; callbacks are not automatically replayed.
+
+### Compatibility and verification
+
+This server-composition contract starts with `@jskit-ai/workspaces-core@0.1.198`.
+Transactional callers of
+`createInvite` must migrate to preparation plus post-commit delivery. Related
+acceptance writes must move into the participant. `markAcceptedById` and
+`revokeById` now reject terminal/missing invitations rather than overwriting their
+state. No route/action ID, package export, table or migration is added.
+
+Verify ordinary invitations, rollback after each domain write, late framework
+failure, existing membership restoration, recipient checks, stale associations,
+controlled delivery failures and lost-response receipts. Run the normal redeem
+action in tests. Use independent connections to race acceptance against acceptance,
+refusal, revocation and replacement in both winning orders. The package fixture
+runs these races on native MySQL/MariaDB and PostgreSQL; SQLite skips those races
+and is not evidence of native locking correctness.
+
+Use only a verified empty disposable database named
+`jskit_repository_test_*` for native tests. The runner verifies the actual target,
+reports its engine version, applies package migrations and drops fixture tables.
+
+```sh
+node --test packages/workspaces-core/test/*.test.js
+# Set JSKIT_REPOSITORY_TEST_DATABASE_URL to the verified empty disposable target.
+node --test packages/workspaces-core/test/repositories.integration.test.js
+npm run verify
+```
+
+A passing framework fixture does not complete the application's People, training,
+permissions, privacy or browser integration. Publication remains a separate
+maintainer operation. After a coordinated release is published, run the
+application's `npm run jskit:update`, restart its backend and verify that
+`members.prepareInvite`, `members.sendInvite` and
+`pendingInvitations.registerAcceptanceParticipant` are functions on the installed
+`workspaces.core` capability. Check the installed package/catalogue versions
+against that release. The first coordinated release containing this contract pairs
+`@jskit-ai/workspaces-core@0.1.198`, `@jskit-ai/jskit-catalog@0.1.245` and
+`@jskit-ai/agent-docs@0.1.192`. Upgrade the coordinated dependency graph rather
+than pinning only `workspaces-core`. Do not patch installed `node_modules`.
+
 ## Browser composition
 
 Use `workspaces/workspace-surfaces` for workspace selection, invitation landing,

package/guide/agent/framework/material-3.md

@@ -102,9 +102,18 @@ Run this behavior-preserving audit over every affected screen:
 3. Check hierarchy, token use, component purpose, responsive presentation,
    interaction states, keyboard/focus behavior, labels, targets, contrast, and
    reduced motion.
-4. Correct issues at the narrowest established owner. Consolidate only truly
+4. Audit Back on every affected page using [Back navigation](./ui-operations.md#back-navigation):
+   verify its presence or justified omission, actual previous-page destination,
+   safe direct-entry fallback, and retained origin context. Inspect handlers and
+   route bindings; a hardcoded parent/list link is an explicit exception, not
+   the default. Check label, accessible name, consistent leading placement,
+   keyboard order, responsive reachability, duplicates, and distinction from
+   Cancel, Close, or Previous step. Report misleading navigation as a finding;
+   fix behavior only within the requested scope, otherwise report it separately
+   from behavior-preserving cleanup.
+5. Correct issues at the narrowest established owner. Consolidate only truly
    repeated policy; avoid pass-through wrappers and speculative abstractions.
-5. Run focused tests and Playwright at compact, medium, and expanded widths.
+6. Run focused tests and Playwright at compact, medium, and expanded widths.
    Navigate away and back with warm query data when the screen persists state.
 
 Do not declare Material 3 compliance from visual resemblance alone. Report any

package/guide/agent/framework/ui-operations.md

@@ -23,6 +23,38 @@ only when defining or diagnosing topology. Resolve current dynamic parameters
 to an absolute URL or route object for sibling/child links—never bind a route
 template or relative string raw to Vue Router `to`.
 
+## Back navigation
+
+Check every page for a visible Back button that returns to the previous page.
+Omit it only when returning makes no product sense, such as the app's root
+landing page or a completed flow that must not reopen an expired step. State
+the reason in the implementation or review result; a drawer link is not Back.
+
+Plain **Back** normally follows the person's actual route history, retaining
+the originating page's query, filters, tab, and pagination. Reuse the existing
+JSKIT screen/navigation owner and its public seams. For history traversal use
+the app's Vue Router instance (`useRouter()` from `vue-router`, then
+[`router.back()`](https://router.vuejs.org/guide/essentials/navigation.html#traverse-history));
+`usePaths().page()` from `@jskit-ai/shell-web/client/navigation/usePaths`
+resolves a destination, not history. Do not invent a second navigation stack.
+
+For direct links, new tabs, or no usable in-app history, use a deliberate safe
+fallback resolved through the existing surface/workspace-aware path helpers.
+Do not infer a usable previous page from `window.history.length` alone or send
+people outside the app unexpectedly. Keep existing unsaved-change guards.
+
+A fixed parent/list destination is valid when the task calls for it; name it
+explicitly, for example **Back to appointments**. It must not silently replace
+ordinary Back. Shared CRUD `listLocation`/`listUrlTemplate` links are fixed
+destinations, not proof of previous-page behavior. Keep Back distinct from
+Cancel, Close, and a wizard's Previous step.
+
+Place Back consistently near the start of the page's existing action region,
+before forward/primary actions in reading and keyboard order. Reuse shell or
+shared-screen controls; avoid duplicates, drawer-only access, or adding a page
+heading just to house it. Keep its meaning and accessible name clear at every
+supported width.
+
 ## Application-owned files
 
 Pattern source is ordinary customizable application source. When replacing a
@@ -67,6 +99,9 @@ Exercise user-facing changes with Playwright at compact, medium, and expanded
 widths. Check overflow, clipped text, duplicate navigation, route placement,
 actions, skeleton replacement, error feedback, and target sizes. Use relative
 URLs. When `PLAYWRIGHT_BASE_URL` is provided, start no duplicate server.
+For Back, enter the same page from two different origins and verify each
+returns to its own origin with context intact. Also check direct entry, reload,
+browser back/forward, fixed-destination exceptions, and any unsaved-change guard.
 
 Vibe64 owns its managed browser and may provide
 `VIBE64_PLAYWRIGHT_STORAGE_STATE`; never print or commit that value, bypass it,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.191",
+  "version": "0.1.193",
   "description": "Distributed JSKIT agent references, prompts, guides, and generated reference maps.",
   "type": "module",
   "files": [

package/patterns/INDEX.md

@@ -30,7 +30,7 @@ How to use it:
   - `client-requests.md`
 - playwright, browser test, e2e, ui verification, baseline test, authenticated ui test, test auth, dev login as, dev auth bypass
   - `ui-testing.md`
-- UI contract, design contract, navigation roles, density, placeholder copy, card shells, shared CRUD screens, row actions, synthetic rows, detail slots
+- UI contract, design contract, navigation roles, Back button, previous page, history, hardcoded destination, Deslop, density, placeholder copy, card shells, shared CRUD screens, row actions, synthetic rows, detail slots
   - `ui-contract.md`
 - filter, filters, search facets, chips, date range, enum filter, lookup filter, `useCrudListFilters`, `createCrudListFilters`
   - `filters.md`

package/patterns/feature-package/example/booking-engine/package.json

@@ -5,7 +5,7 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@jskit-ai/kernel": "0.1.219",
+    "@jskit-ai/kernel": "0.1.221",
     "json-rest-schema": "^1.0.17"
   },
   "exports": {

package/patterns/minimal-foundation/example/package.json

@@ -34,7 +34,7 @@
   "dependencies": {
     "@local/main": "0.1.0",
     "@fastify/static": "^10.1.3",
-    "@jskit-ai/kernel": "0.1.219",
+    "@jskit-ai/kernel": "0.1.221",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.8.5",
     "json-rest-schema": "^1.0.17",
@@ -42,13 +42,13 @@
     "vue": "^3.5.43",
     "vue-router": "^5.3.1",
     "vuetify": "^4.1.2",
-    "@jskit-ai/http-runtime": "0.1.217",
+    "@jskit-ai/http-runtime": "0.1.219",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
-    "@jskit-ai/config-eslint": "0.1.216",
-    "@jskit-ai/jskit-catalog": "0.1.244",
+    "@jskit-ai/config-eslint": "0.1.218",
+    "@jskit-ai/jskit-catalog": "0.1.246",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

package/patterns/page-scaffolding.md

@@ -34,6 +34,8 @@ Rules:
 - If the screen is not implemented yet, use a product-shaped empty state with one clear next action or status, not developer instructions.
 - Primary navigation links belong in semantic placements such as `shell.primary-nav` or `page.section-nav`; do not place every route into one drawer by default.
 - Compact layouts must be checked first: no horizontal overflow, no unreachable primary action, and tap targets should be at least 48 px.
+- Check Back's presence, previous-page behavior, and position using the
+  [UI contract](./ui-contract.md); explain any omission or fixed destination.
 
 UI contract:
 

package/patterns/shell-foundation/example/package.json

@@ -34,7 +34,7 @@
   "dependencies": {
     "@local/main": "0.1.0",
     "@fastify/static": "^10.1.3",
-    "@jskit-ai/kernel": "0.1.219",
+    "@jskit-ai/kernel": "0.1.221",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.8.5",
     "json-rest-schema": "^1.0.17",
@@ -42,15 +42,15 @@
     "vue": "^3.5.43",
     "vue-router": "^5.3.1",
     "vuetify": "^4.1.2",
-    "@jskit-ai/http-runtime": "0.1.217",
+    "@jskit-ai/http-runtime": "0.1.219",
     "@mdi/js": "^7.4.47",
-    "@jskit-ai/shell-web": "0.1.223",
+    "@jskit-ai/shell-web": "0.1.225",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
-    "@jskit-ai/config-eslint": "0.1.216",
-    "@jskit-ai/jskit-catalog": "0.1.244",
+    "@jskit-ai/config-eslint": "0.1.218",
+    "@jskit-ai/jskit-catalog": "0.1.246",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

package/patterns/shell-foundation/example/packages/main/package.json

@@ -9,7 +9,7 @@
   },
   "description": "App-local runtime composition and lightweight glue.",
   "dependencies": {
-    "@jskit-ai/kernel": "0.1.219"
+    "@jskit-ai/kernel": "0.1.221"
   },
   "jskit": {
     "kind": "runtime",

package/patterns/ui-contract.md

@@ -11,6 +11,11 @@ and action UI.
   overflow.
 - Compact interactive targets are at least 48 CSS pixels.
 - Navigation uses semantic placements and explicit navigation roles.
+- Check every page for Back to the previous page unless returning makes no
+  product sense. Use the existing navigation owner; fixed destinations are
+  deliberate, explicitly labelled exceptions. Follow the
+  [Back navigation contract](../guide/agent/framework/ui-operations.md#back-navigation)
+  for history, direct-entry fallback, retained context, and consistent placement.
 - Pages do not stack decorative cards inside structural cards.
 - Pages do not include a header, title block, welcome heading, or standalone
   heading copy unless the user explicitly requests one.
@@ -50,6 +55,8 @@ it as a closed sheet and wider layouts as a closed side panel.
 
 - test skeleton, empty, loaded, local error, retry, and mutation feedback states
 - navigate away and back with warm query cache, including browser back/forward
+- during review or Deslop, audit Back's presence or justified omission, leading
+  position, label, and actual destination; verify two origins and direct entry
 - exercise compact, medium, and expanded viewports
 - verify accessible names, keyboard operation, target size, and no overflow
 - assert that no spinner or layout-shifting transient error banner appears