@marianmeres/ownsuite 1.0.3 → 2.1.0

package/API.md

@@ -63,6 +63,10 @@ Orchestrator that coordinates owner-scoped domain managers and provides a shared
 
 **Parameters:** same as `createOwnsuite`.
 
+#### `suite.session`, `suite.auth`, `suite.profile`
+
+Readonly properties pointing at the account-lifecycle managers. Populated only when `config.adapters.auth` was supplied — `null` otherwise. Full surface documented under [Account lifecycle (optional)](#account-lifecycle-optional).
+
 #### `suite.registerDomain(name, cfg)`
 
 Register a new domain after construction. Throws if `name` is already registered.
@@ -98,17 +102,44 @@ Initialize all registered domains (or a subset). Runs in parallel. Individual do
 
 **Returns:** `Promise<void>`
 
-#### `suite.setContext(ctx)`
+#### `suite.setContext(ctx, options?)`
 
-Merge `ctx` into the shared context and propagate to every registered domain manager.
+Update the shared context and propagate to every registered domain manager.
 
 **Parameters:**
 - `ctx` (`OwnsuiteContext`)
+- `options` (`SetContextOptions`, optional)
+  - `options.replace` (`boolean`, default `false`) — replace the context wholesale instead of merging. Use this when the subject changes and previous per-subject keys must not leak into adapter calls.
+  - `options.refresh` (`boolean`, default `false`) — fire-and-forget `refresh()` on every domain after the context change. Recommended when `subjectId` changes so stale per-subject caches are cleared.
+
+**Example:**
+```typescript
+// Subject change: drop old context + re-fetch every domain
+suite.setContext({ subjectId: newId }, { replace: true, refresh: true });
+```
 
 #### `suite.getContext(): OwnsuiteContext`
 
 Snapshot of current shared context.
 
+#### `suite.errors(): Record<string, DomainError>`
+
+Map of currently-errored domains to their `DomainError`. Empty if none are in error state. Use after `initialize()` to detect silent boot failures.
+
+#### `suite.hasErrors(): boolean`
+
+True if any domain is currently in `error` state.
+
+#### `suite.destroy()`
+
+Dispose of the suite: destroys every registered domain (which aborts in-flight adapter requests), clears the domain map, and unsubscribes every listener attached to the internal pubsub. Safe to call multiple times.
+
+Subsequent method calls are best-effort no-ops (e.g., `initialize()` returns immediately, `setContext()` ignores the call). `registerDomain()` throws after destroy.
+
+#### `suite.isDestroyed: boolean`
+
+True after `destroy()` has been called.
+
 #### `suite.on(type, subscriber)`
 
 Subscribe to a specific event type.
@@ -177,7 +208,9 @@ Re-fetch the list. Same as `initialize` but re-entrant; accepts an adapter-speci
 
 #### `manager.getOne(id): Promise<TRow | null>`
 
-Fetch a single row by id. Does **not** mutate the list. Returns `null` on error and transitions the manager to `error` state.
+Fetch a single row by id. Does **not** mutate the list and does **not** transition the domain to `error` on failure — a 404 for an un-owned row or a network blip on a read shouldn't invalidate a healthy list view. Returns `null` on any failure (including missing adapter). Emits `own:row:fetched` on success.
+
+Callers that need error detail should wrap this method and inspect the adapter error themselves.
 
 #### `manager.create(data): Promise<TRow | null>`
 
@@ -190,15 +223,19 @@ Create a new row. On success, prepends the server-returned row to the list. On f
 
 #### `manager.update(id, data): Promise<TRow | null>`
 
-Update a row. Optimistically merges `data` into the existing row; on server failure the list is rolled back to its pre-call state. On success, the server-returned row replaces the optimistic one.
+Update a row. Optimistically merges `data` into the existing row; on server failure the single row reverts to its pre-call value (other rows are untouched — including any added by an interleaved `refresh()`). On success, the server-returned row replaces the optimistic one.
+
+If `id` is **not** in the current cached list (filtered out by an active query, or not loaded), the optimistic step is a no-op AND the successful server response is **not** inserted — call `refresh()` if you want the row to appear. The `own:row:updated` event is emitted regardless.
 
 **Parameters:**
 - `id` (`string`)
 - `data` (`TUpdate`)
 
+Mutations serialize per-manager — a `create/update/delete` that starts while another is in-flight queues behind it.
+
 #### `manager.delete(id): Promise<boolean>`
 
-Delete a row. Optimistically removes it from the list; on server failure the list is rolled back.
+Delete a row. Optimistically removes it from the list; on server failure the single row is re-inserted at its original position (unless another op has since re-added it).
 
 **Returns:** `true` on success, `false` on failure.
 
@@ -214,13 +251,21 @@ Find a row by id in the current list without hitting the server.
 
 Swap or inspect the adapter at runtime.
 
-#### `manager.setContext(ctx)` / `manager.getContext()`
+#### `manager.setContext(ctx)` / `manager.replaceContext(ctx)` / `manager.getContext()`
 
-Per-manager context. `Ownsuite.setContext()` propagates to every manager.
+Per-manager context. `setContext` merges into the existing context; `replaceContext` replaces it wholesale. `Ownsuite.setContext()` propagates to every manager (with the same `{ replace }` option).
 
 #### `manager.reset()`
 
-Reset to `initializing` state.
+Reset to `initializing` state. Aborts any in-flight reads or mutations (their completions become no-ops) and emits `domain:state:changed`.
+
+#### `manager.destroy()`
+
+Abort in-flight operations, drop the adapter reference, and mark the manager as destroyed. Subsequent method calls are best-effort no-ops. Usually invoked via `Ownsuite.destroy()`, but safe to call directly.
+
+#### `manager.isDestroyed: boolean`
+
+True after `destroy()` has been called.
 
 ---
 
@@ -239,12 +284,23 @@ interface OwnsuiteConfig {
 	context?: OwnsuiteContext;
 	domains?: Record<string, OwnsuiteDomainConfig>;
 	autoInitialize?: boolean;
+	adapters?: {
+		auth?: AuthAdapter;
+		profile?: ProfileAdapter;
+	};
+	session?: {
+		storage?: SessionStorageType;   // "local" | "session" | "memory" | SessionStorage
+		storageKey?: string;            // default: "ownsuite:session"
+	};
 }
 ```
 
 - `context` — initial context passed to every adapter call.
 - `domains` — domain registry at construction time. Keys are arbitrary labels.
 - `autoInitialize` — fire-and-forget `initialize()` in the constructor. Default: `false`.
+- `adapters.auth` — when provided, the suite builds `SessionManager` / `AuthManager` / `ProfileManager` and exposes them as `suite.session` / `suite.auth` / `suite.profile`. Without it, those properties are `null`.
+- `adapters.profile` — optional but recommended companion. Without it, login still succeeds but the subject is not hydrated from `/me`.
+- `session.storage` / `session.storageKey` — persistence config for the session. Ignored when no `adapters.auth` is provided.
 
 ### `OwnsuiteDomainConfig<TRow, TCreate, TUpdate>`
 
@@ -255,16 +311,26 @@ interface OwnsuiteDomainConfig<TRow, TCreate, TUpdate> {
 }
 ```
 
+### `SetContextOptions`
+
+```typescript
+interface SetContextOptions {
+	replace?: boolean;   // default: false — merge into existing context
+	refresh?: boolean;   // default: false — fire refresh() on every domain
+}
+```
+
 ### `OwnsuiteContext`
 
 ```typescript
 interface OwnsuiteContext {
 	subjectId?: string;
+	signal?: AbortSignal;  // manager-injected, per-call
 	[key: string]: unknown;
 }
 ```
 
-Context passed to adapters. **`subjectId` is a hint only** — the server authoritatively resolves the owner from the authenticated JWT. The context object is the extension point for passing host-app data (correlation ids, feature flags, tenants) through adapter calls.
+Context passed to adapters. **`subjectId` is a hint only** — the server authoritatively resolves the owner from the authenticated JWT. **`signal` is injected by the manager** on every call; adapters should forward it to `fetch()` for cancellation on `reset()`/`destroy()`/read-supersede. The context object is also the extension point for passing host-app data (correlation ids, feature flags, tenants) through adapter calls.
 
 ### `OwnedCollectionAdapter<TRow, TCreate, TUpdate>`
 
@@ -353,7 +419,16 @@ type OwnsuiteEventType =
 	| "own:row:fetched"
 	| "own:row:created"
 	| "own:row:updated"
-	| "own:row:deleted";
+	| "own:row:deleted"
+	// Account lifecycle — only emitted when adapters.auth is wired
+	| "auth:register"
+	| "auth:login"
+	| "auth:logout"
+	| "auth:session:changed"
+	| "auth:verification:required"
+	| "profile:updated"
+	| "oauth:linked"
+	| "oauth:unlinked";
 ```
 
 ### `OwnsuiteEvent`
@@ -383,9 +458,13 @@ interface MockAdapterOptions<TRow> {
 	failOn?: { list?: boolean; getOne?: boolean; create?: boolean; update?: boolean; delete?: boolean };
 	getRowId?: (row: TRow) => string;
 	newId?: () => string;
+	/** Reject create payloads containing `model_id` (default: true). */
+	rejectClientId?: boolean;
 }
 ```
 
+The mock adapter forwards `ctx.signal` — `delayMs` waits can be aborted mid-sleep so tests that assert on abort-supersede semantics run deterministically.
+
 ---
 
 ## Implementing a real adapter
@@ -393,27 +472,33 @@ interface MockAdapterOptions<TRow> {
 Point the adapter at your server's owner-scoped mount (typically `/api/<stack>/me/col/<entity>/...`). The server is responsible for `owner_id` enforcement — the client only talks to `/me/*`.
 
 ```typescript
-import type { OwnedCollectionAdapter } from "@marianmeres/ownsuite";
+import type { OwnedCollectionAdapter, OwnsuiteContext } from "@marianmeres/ownsuite";
 import { HTTP_ERROR } from "@marianmeres/http-utils";
 
 export function createRestAdapter(stack: string, entity: string): OwnedCollectionAdapter {
 	const base = `/api/${stack}/me/col/${entity}`;
-	const json = async <T>(method: string, url: string, body?: unknown): Promise<T> => {
+	const json = async <T>(
+		method: string,
+		url: string,
+		ctx: OwnsuiteContext,
+		body?: unknown,
+	): Promise<T> => {
 		const res = await fetch(url, {
 			method,
 			headers: { "content-type": "application/json" },
 			body: body === undefined ? undefined : JSON.stringify(body),
+			signal: ctx.signal, // forward manager-injected abort signal
 		});
 		if (!res.ok) throw new HTTP_ERROR.BadRequest(await res.text());
 		return await res.json();
 	};
 	return {
-		list: (_ctx) => json("GET", `${base}/mod`),
-		getOne: (id, _ctx) => json("GET", `${base}/mod/${id}`),
-		create: (data, _ctx) => json("POST", `${base}/mod`, data),
-		update: (id, data, _ctx) => json("PUT", `${base}/mod/${id}`, data),
-		delete: async (id, _ctx) => {
-			await json("DELETE", `${base}/mod/${id}`);
+		list: (ctx) => json("GET", `${base}/mod`, ctx),
+		getOne: (id, ctx) => json("GET", `${base}/mod/${id}`, ctx),
+		create: (data, ctx) => json("POST", `${base}/mod`, ctx, data),
+		update: (id, data, ctx) => json("PUT", `${base}/mod/${id}`, ctx, data),
+		delete: async (id, ctx) => {
+			await json("DELETE", `${base}/mod/${id}`, ctx);
 			return true;
 		},
 	};
@@ -421,3 +506,310 @@ export function createRestAdapter(stack: string, entity: string): OwnedCollectio
 ```
 
 The `@marianmeres/joy` admin SPA ships a reusable factory — `createOwnedCollectionAdapter()` in `src/routes/me/owned-collection-adapter.ts` — that implements exactly this shape.
+
+---
+
+## Account lifecycle (optional)
+
+Attached automatically when `adapters.auth` is passed to `createOwnsuite`. See also the example at the top of [README.md](README.md).
+
+### `createStackAccountAuthAdapter(options?)`
+
+Default `AuthAdapter` pointing at the `@marianmeres/stack-account` REST surface.
+
+**Parameters:**
+- `options` (`StackAccountAdapterOptions`, optional)
+  - `options.baseUrl` (`string`, optional) — mount path. Default: `"/api/account"`.
+  - `options.fetch` (`typeof fetch`, optional) — custom fetch (tests / SSR).
+
+**Returns:** `AuthAdapter`
+
+Endpoints targeted:
+
+```
+POST   {baseUrl}/register
+POST   {baseUrl}/login
+POST   {baseUrl}/logout
+POST   {baseUrl}/verify/resend
+POST   {baseUrl}/password/reset
+POST   {baseUrl}/password/change
+DELETE {baseUrl}/me
+GET    {baseUrl}/oauth/{provider}/init
+```
+
+### `createStackAccountProfileAdapter(options?)`
+
+Default `ProfileAdapter`.
+
+**Parameters:** same `StackAccountAdapterOptions` as above.
+
+**Returns:** `ProfileAdapter`
+
+Endpoints targeted: `GET/PUT {baseUrl}/me`, `GET {baseUrl}/me/oauth`, `DELETE {baseUrl}/me/oauth/{provider}`.
+
+### `createMockAuthStore(init?)` / `createMockAuthAdapter(store)` / `createMockProfileAdapter(store)` / `verifyMockAccount(store, email)`
+
+In-memory mock for tests and demos. `createMockAuthStore` builds a shared state object; the adapter factories close over it.
+
+**`createMockAuthStore(init?)`** returns `MockAuthStore`. `init.requireVerifiedEmail` (default `false`) toggles the email-verification gate; `init.seed` can pre-populate accounts.
+
+**`verifyMockAccount(store, email)`** marks an account as verified — stands in for the user clicking the link in a real verification email.
+
+**Example:**
+```typescript
+const store = createMockAuthStore({ requireVerifiedEmail: true });
+const suite = createOwnsuite({
+    adapters: {
+        auth: createMockAuthAdapter(store),
+        profile: createMockProfileAdapter(store),
+    },
+});
+await suite.auth!.register({
+    email: "alice@example.com",
+    password: "mysecretpassword",
+    password_confirm: "mysecretpassword",
+});
+// suite.session!.get().status === "unverified"
+verifyMockAccount(store, "alice@example.com");
+await suite.auth!.login({ email: "alice@example.com", password: "mysecretpassword" });
+// suite.session!.get().status === "authenticated"
+```
+
+---
+
+### `SessionManager`
+
+Reactive session state + persistence. No HTTP. Attached as `suite.session`.
+
+#### `session.subscribe(listener)` / `session.get()`
+
+Svelte-compatible store over [`SessionState`](#sessionstate).
+
+#### `session.getJwt(): string | null`
+
+Current JWT, or `null` when anonymous.
+
+#### `session.isAuthenticated` / `session.isUnverified` / `session.isAnonymous` (boolean getters)
+
+Shorthand reads.
+
+#### `session.setAuthenticated({ jwt, subject, expiresAt? })`
+
+Enter the `authenticated` state. Normally called by `AuthManager`, not consumers.
+
+#### `session.setUnverified(email)` / `session.clear()` / `session.patchSubject(patch)`
+
+Mutation helpers — typically driven by `AuthManager` / `ProfileManager`.
+
+#### `session.destroy()`
+
+Clear storage and in-memory state. Called by `suite.destroy()`.
+
+---
+
+### `AuthManager`
+
+Verbs only. Attached as `suite.auth`. No state of its own — results flow into `SessionManager`.
+
+| Method | Purpose |
+|---|---|
+| `register({ email, password, password_confirm, roles?, extras? })` | Create account. Returns an `AuthTokenResult`. When the server's verification gate is on, the result carries `requiresVerification: true` and the session flips to `"unverified"` — no JWT yet. |
+| `login({ email, password })` | Exchange credentials for a JWT. Session flips to `"authenticated"` on success, `"unverified"` if the server reports the gate. |
+| `logout()` | Best-effort server revoke + local clear. Idempotent. |
+| `resendVerification({ email, lang? })` | Trigger a fresh verification email. Anti-enumeration: always resolves. |
+| `requestPasswordReset({ email, lang? })` | Trigger a password-reset email. Anti-enumeration. |
+| `changePassword({ current_password?, new_password, confirm_password, token? })` | Authenticated self-change (with `current_password`) or token-based reset. |
+| `deleteAccount({ password?, confirm? })` | Irreversible server delete + local session clear + identity-changed hook. |
+| `initiateOAuth(provider, opts)` | Start an OAuth flow. `mode: "popup"` (default) resolves with the auth result from the popup's `postMessage`; `mode: "redirect"` navigates the top window. |
+| `handleOAuthCallback()` | For `mode: "redirect"` apps, call from your callback route to extract the result from the URL (delegated to `adapter.handleOAuthCallback`). |
+
+Successful identity changes (register-with-autologin, login, OAuth login, logout, deleteAccount) fire the orchestrator's `onIdentityChanged` hook, which resets every owner-scoped domain and re-initializes them with the new context.
+
+---
+
+### `ProfileManager`
+
+Singleton `/me` manager. Attached as `suite.profile`.
+
+| Method | Purpose |
+|---|---|
+| `fetch()` | GET `/me`. Aborts any in-flight fetch (supersede). Patches the session subject in place on success. |
+| `update({ email?, current_password? })` | PUT `/me`. Updates the session subject in place; emits `profile:updated`. |
+| `listOAuth()` | List the account's linked OAuth providers. |
+| `unlinkOAuth(provider)` | DELETE a provider connection; emits `oauth:unlinked`; re-fetches the profile. |
+| `get()` / `subscribe(fn)` | Read / subscribe to `ProfileState` (`{ profile, loading, error }`). |
+| `reset()` / `destroy()` | Abort in-flight fetch; drop state. |
+
+---
+
+### `openOAuthPopup(url, options?)`
+
+Open an OAuth popup and await the server's `postMessage`.
+
+**Parameters:**
+- `url` (`string`) — server OAuth init URL.
+- `options` (`OpenOAuthPopupOptions`, optional)
+  - `options.host` (`PopupWindowHost`, optional) — shim for tests. Default: `globalThis`.
+  - `options.closedPollMs` (`number`, optional) — detect popup-closed-without-message. Default: `500`.
+  - `options.timeoutMs` (`number`, optional) — hard timeout. Default: `0` (disabled).
+  - `options.expectedOrigin` (`string`, optional) — restrict accepted message origins.
+  - `options.features` (`string`, optional) — popup window features string.
+
+**Returns:** `Promise<OAuthPopupMessage>` — resolves with `{ type: "oauth_login_success", jwt, email, roles?, ... }` or `{ type: "oauth_link_success", provider }`. Rejects with `OAUTH_POPUP_BLOCKED` / `OAUTH_POPUP_CLOSED` / `OAUTH_POPUP_TIMEOUT` or the server-supplied error message.
+
+---
+
+## Account-lifecycle types
+
+### `SessionState`
+
+```typescript
+interface SessionState {
+    status: "anonymous" | "authenticated" | "unverified";
+    subject: SessionSubject | null;
+    jwt: string | null;
+    expiresAt: number | null;  // unix seconds
+}
+```
+
+### `SessionSubject`
+
+```typescript
+interface SessionSubject {
+    id: string;
+    email: string;
+    roles: string[];
+    isVerified: boolean;
+    hasPassword: boolean;   // OAuth-only accounts: false
+}
+```
+
+### `SessionStatus` / `SessionStorage` / `SessionStorageType`
+
+```typescript
+type SessionStatus = "anonymous" | "authenticated" | "unverified";
+
+interface SessionStorage {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    del(key: string): void;
+}
+
+type SessionStorageType = "local" | "session" | "memory" | SessionStorage;
+```
+
+### `AuthTokenResult`
+
+```typescript
+interface AuthTokenResult {
+    jwt?: string;                    // absent when requiresVerification is true
+    email: string;
+    roles: string[];
+    isVerified?: boolean;
+    validFrom?: number;
+    validUntil?: number;
+    requiresVerification?: boolean;  // server declined auto-login pending verify
+}
+```
+
+### `ProfileResult`
+
+```typescript
+interface ProfileResult {
+    email: string;
+    roles: string[];
+    isVerified: boolean;
+    hasPassword: boolean;
+    oauthConnections: OAuthConnection[];
+}
+```
+
+### `OAuthProvider` / `OAuthAction` / `OAuthInitOptions` / `OAuthConnection`
+
+```typescript
+type OAuthProvider = "google" | "facebook" | "apple" | "twitter";
+type OAuthAction = "login" | "link";
+
+interface OAuthInitOptions {
+    action: OAuthAction;
+    redirect?: string;
+    lang?: string;
+    mode?: "popup" | "redirect";  // default "popup"
+}
+
+interface OAuthConnection {
+    provider: OAuthProvider;
+    display_name?: string;
+    avatar_url?: string;
+    email?: string;
+}
+```
+
+### `AuthAdapter`
+
+```typescript
+interface AuthAdapter {
+    register(input, ctx): Promise<AuthTokenResult>;
+    login(input, ctx): Promise<AuthTokenResult>;
+    logout(ctx): Promise<void>;
+    oauthInitUrl(provider, opts, ctx): string;
+    handleOAuthCallback?(ctx): Promise<AuthTokenResult>;
+    resendVerification(input, ctx): Promise<void>;
+    requestPasswordReset(input, ctx): Promise<void>;
+    changePassword(input, ctx): Promise<void>;
+    deleteAccount(input, ctx): Promise<{ deleted: true }>;
+}
+```
+
+Parameter shapes match [`src/types/auth.ts`](src/types/auth.ts). Implementations forward `ctx.jwt` as `Authorization: Bearer <jwt>` and `ctx.signal` to `fetch()`.
+
+### `ProfileAdapter`
+
+```typescript
+interface ProfileAdapter {
+    get(ctx): Promise<ProfileResult>;
+    update(input: { email?, current_password? }, ctx): Promise<ProfileResult>;
+    listOAuth(ctx): Promise<OAuthConnection[]>;
+    unlinkOAuth(provider, ctx): Promise<void>;
+}
+```
+
+### `StackAccountAdapterOptions`
+
+```typescript
+interface StackAccountAdapterOptions {
+    baseUrl?: string;    // default "/api/account"
+    fetch?: typeof fetch;
+}
+```
+
+### `OpenOAuthPopupOptions` / `PopupWindowHost` / `OAuthPopupMessage`
+
+See [src/oauth/popup.ts](src/oauth/popup.ts) for full definitions. `OAuthPopupMessage` is a union of `OAuthPopupLoginMessage` (`{ type: "oauth_login_success", jwt, email, roles?, ... }`) and `OAuthPopupLinkMessage` (`{ type: "oauth_link_success", provider }`). Errors posted by the server (`{ type: "oauth_error", error }`) cause the promise to reject.
+
+### `MockAuthStore`
+
+```typescript
+interface MockAuthStore {
+    accounts: Map<string, MockAccount>;
+    requireVerifiedEmail: boolean;
+    jwtsByEmail: Map<string, string>;
+}
+```
+
+---
+
+## Account-lifecycle events
+
+Emitted on the shared pubsub. Each payload has a `timestamp` (ms).
+
+| Event | Payload |
+|---|---|
+| `auth:register` | `{ email, requiresVerification }` |
+| `auth:login` | `{ email }` |
+| `auth:logout` | `{ subjectId? }` |
+| `auth:session:changed` | `{ session: SessionState }` |
+| `auth:verification:required` | `{ email }` (fired when status flips to `"unverified"`) |
+| `profile:updated` | `{ email }` |
+| `oauth:linked` | `{ connection: OAuthConnection }` |
+| `oauth:unlinked` | `{ provider: OAuthProvider }` |

package/README.md

@@ -16,11 +16,79 @@ Ownsuite gives front-end applications a uniform way to read, create, update and
 ## Features
 
 - **Generic domain managers** — register any owner-scoped collection by name; no hard-coded domain list
-- **Optimistic updates** — UI mutates immediately; the manager rolls back on server failure
+- **Optimistic updates** with per-row rollback — UI mutates immediately; failed ops revert just the affected row
+- **Race-safe concurrency** — mutations serialize; reads abort-supersede (a newer `refresh()` aborts an older one)
+- **AbortSignal plumbing** — every adapter call receives a per-operation signal, wired to `destroy()` and route-change cancellation
 - **Svelte-compatible stores** — every domain exposes a `subscribe()` method
 - **Adapter pattern** — plug in any HTTP/WebSocket/mock transport
 - **Event system** — subscribe to list fetches, row CRUD, and lifecycle transitions
-- **Mock adapter** — in-memory fixture for tests, with configurable failure injection
+- **Mock adapter** — in-memory fixture for tests, with configurable failure injection and latency
+- **Explicit lifecycle** — `suite.destroy()` aborts in-flight work and releases listeners cleanly
+- **Account lifecycle (opt-in)** — `suite.auth` / `suite.session` / `suite.profile` for register / login / OAuth / verify / logout / profile edit / delete account, wired to pair with `@marianmeres/stack-account` via the bundled default adapters
+
+## Authentication (optional)
+
+Pass an `AuthAdapter` to `createOwnsuite` to attach the account-lifecycle managers. The default adapters target the `@marianmeres/stack-account` REST surface; apps with custom routes can write their own against the `AuthAdapter` / `ProfileAdapter` interfaces exported from this package.
+
+```typescript
+import {
+  createOwnsuite,
+  createStackAccountAuthAdapter,
+  createStackAccountProfileAdapter,
+} from "@marianmeres/ownsuite";
+
+const suite = createOwnsuite({
+  adapters: {
+    auth: createStackAccountAuthAdapter({ baseUrl: "/api/account" }),
+    profile: createStackAccountProfileAdapter({ baseUrl: "/api/account" }),
+  },
+  session: { storage: "local", storageKey: "myapp:session" },
+  // Existing owner-scoped domains continue to work — their ctx.jwt is
+  // populated automatically from the session and they re-initialize on
+  // every login / logout.
+  domains: {
+    orders: { adapter: ordersAdapter },
+  },
+});
+
+// Observable session — UI subscribes to this for logged-in state.
+suite.session!.subscribe(({ status, subject }) => {
+  if (status === "authenticated") console.log("hi", subject!.email);
+  if (status === "unverified")   console.log("check your inbox");
+  if (status === "anonymous")    console.log("signed out");
+});
+
+// Register → server requires email verification (default gate in stack-account)
+await suite.auth!.register({
+  email: "alice@example.com",
+  password: "mysecretpassword",
+  password_confirm: "mysecretpassword",
+});
+// suite.session!.get().status === "unverified"
+
+// After the user clicks the email link and the server flips isVerified:
+await suite.auth!.login({ email: "alice@example.com", password: "mysecretpassword" });
+// suite.session!.get().status === "authenticated"
+// Every registered owner-scoped domain is re-initialized with the new JWT.
+
+// OAuth popup flow — resolves when the callback page postMessages back
+await suite.auth!.initiateOAuth("google", { action: "login" });
+
+// Profile edit — changing email resets isVerified server-side and dispatches
+// a new verification email. Session subject is patched in place.
+await suite.profile!.update({
+  email: "renamed@example.com",
+  current_password: "mysecretpassword",
+});
+
+// Logout — revokes JWT server-side (via stack-account's jti deletion) and
+// clears local session storage. Owner-scoped domains reset to initializing.
+await suite.auth!.logout();
+```
+
+Session state is persisted through a pluggable `SessionStorage` backend (`"local"` / `"session"` / `"memory"` / custom object with `get`/`set`/`del`). Expired stored sessions are discarded on construction so a reload after the JWT lapses starts anonymous.
+
+Tests can use the in-memory mock adapters (`createMockAuthAdapter`, `createMockProfileAdapter`, `createMockAuthStore`, `verifyMockAccount`) and the injectable popup host for deterministic OAuth dances.
 
 ## Installation
 
@@ -65,6 +133,12 @@ suite.domain("orders").subscribe((s) => {
 await suite.domain("orders").create({ data: { total: 99 } });
 await suite.domain("orders").update(id, { data: { total: 120 } });
 await suite.domain("orders").delete(id);
+
+// 6. Detect silent boot failures
+if (suite.hasErrors()) console.warn("boot errors:", suite.errors());
+
+// 7. Clean up on teardown (SPA unmount, tenant switch, test harness)
+suite.destroy();
 ```
 
 ## Architecture at a glance
@@ -103,6 +177,16 @@ await suite.domain("notes").update("1", { data: { label: "new" } });
 
 See [API.md](API.md) for complete API documentation.
 
+## Breaking changes in 2.0.0
+
+- `getOne()` no longer transitions the domain to `error` on failure — it returns `null` quietly.
+- `update(id, ...)` for an id absent from the cached list no longer prepends a phantom row — the server update is still applied server-side (event emitted), but the list stays unchanged. Call `refresh()` to surface it.
+- `createMockOwnedCollectionAdapter` rejects `create` payloads containing a client-supplied `model_id` by default (opt out with `rejectClientId: false`).
+- Rollback on failed `update`/`delete` is now per-row, not whole-list. Interleaved refresh results are preserved.
+- `reset()` now emits `domain:state:changed`.
+
+See [AGENTS.md](AGENTS.md) "Breaking changes in 2.0.0" for the full list and migration notes.
+
 ## License
 
 [MIT](LICENSE)