docs: complete Session package docs for v3.0

v3.0/packages/session/adapters.md

@@ -25,16 +25,17 @@ The native adapter:
 
 - starts a PHP session if one is not already active
 - keeps an internal `LAST_ACTIVITY` timestamp in the session
-- destroys the session when the idle time exceeds `timeout`
+- refreshes the session when the idle time is within `timeout`
+- resets the active session when the idle time exceeds `timeout`
 - updates `LAST_ACTIVITY` on every initialization
 
 Practical effect: the timeout is checked when the adapter is initialized, not by a background cleanup process.
 
 ### Caveats
 
-- `all()` includes the adapter's internal `LAST_ACTIVITY` key because it reads the full session storage
-- if `session_start()` fails, resolution throws a session exception
-- if the adapter tries to destroy an expired session and `session_destroy()` fails, resolution throws a session exception
+- `all()` includes the adapter's internal `LAST_ACTIVITY` key because it reads the full session storage.
+- Session values are stored as encrypted payloads, so direct inspection of the backing storage is best treated as transport data rather than app-level values.
+- When PHP session startup or teardown raises an error, Session surfaces it as a session exception.
 
 ## Database adapter
 
@@ -84,15 +85,17 @@ The database adapter:
 
 - creates a dynamic model for the configured table through the Model package
 - registers a custom PHP session save handler before starting the session
-- stores the raw PHP session payload in `data`
+- stores the PHP session payload in `data`
 - updates `ttl` to the current Unix timestamp on every write
 - deletes expired rows during garbage collection when `ttl < time() - max_lifetime`
 
+Because Session encrypts and serializes values before they reach `$_SESSION`, the `data` column contains PHP's session payload format around encrypted value strings.
+
 ### Caveats
 
-- this adapter depends on the Database and Model packages being configured correctly
-- expiry cleanup depends on PHP session garbage collection calling the handler's `gc()` method
-- the package does not create the session table for you
+- This adapter depends on the Database and Model packages being ready before the first `session('database')` call.
+- Expiry cleanup runs when PHP session garbage collection calls the handler's `gc()` method.
+- Create the session table as part of your database setup before you switch the default adapter.
 
 ## Choosing an adapter
 

v3.0/packages/session/contracts.md

@@ -6,6 +6,8 @@ This page defines behavior you can rely on when integrating with Session.
 
 `session()` returns `Quantum\Session\Session`, which forwards supported calls to the active adapter.
 
+The factory keeps one shared wrapper per adapter name for the current process, so repeated `session()` or `session('native')` calls reuse the same wrapper.
+
 Unsupported method calls throw a session exception.
 
 ## Read/write contract
@@ -15,6 +17,8 @@ Unsupported method calls throw a session exception.
 - `delete(string $key): void`
 - `all(): array`
 
+Session serializes and encrypts values on write, then decrypts and unserializes them on read. Scalars and arrays round-trip through the API, while backend storage keeps the encoded payload.
+
 Use Session APIs as the source of truth for values.
 
 ## Presence contract
@@ -44,7 +48,7 @@ Because `get()` depends on `has()`, these values read back as `null`.
 
 - `flush(): void` clears storage and destroys session state
 - `getId(): ?string` returns current session ID when available
-- `regenerateId(): bool` regenerates ID only when a session is active
+- `regenerateId(): bool` regenerates the ID for the active session, reopens the adapter, and keeps the same adapter config
 
 Use `regenerateId()` after authentication or privilege changes.
 
@@ -55,6 +59,6 @@ Supported adapter names:
 - `native`
 - `database`
 
-Unknown adapter names fail during resolution.
+Unknown adapter names raise a session exception during resolution.
 
 When no adapter is passed, resolution uses `session.default` config.

v3.0/packages/session/helpers.md

@@ -24,5 +24,6 @@ session('database')->set('cart_id', 'abc123');
 - no adapter passed → uses `session.default`
 - adapter passed → resolves that backend (`native` or `database`)
 - returns a Session wrapper, not a raw adapter
+- reuses the same wrapper for repeated calls to the same adapter in the current process
 
-Prefer backend setup through configuration, not direct adapter construction.
+Prefer backend setup through configuration, then call `session()` from application code.

v3.0/packages/session/overview.md

@@ -2,7 +2,7 @@
 
 Session provides a consistent API for request-scoped state, flash messages, and session ID management.
 
-Use it when you need to persist small values between requests without coupling your code to raw `$_SESSION` access.
+Use it when you need to persist small values between requests without coupling your code to raw `$_SESSION` access. Stored values are serialized and encrypted through the Encryption package, so session data round-trips as PHP values while backend storage stays opaque.
 
 ## What it provides
 
@@ -33,9 +33,10 @@ When no adapter is passed, Session uses `session.default` from `config/session.p
 
 ## Operational constraints
 
+- `session()` reuses one `Session` wrapper per adapter inside the current process.
 - `has()` treats empty-like values as missing (`null`, `false`, `0`, `'0'`, `''`).
 - `get()` depends on `has()`, so those values resolve as `null`.
-- Use Session APIs for reads/writes instead of relying on backend storage format.
+- Use Session APIs for reads and writes instead of relying on backend storage format.
 - Regenerate session IDs after authentication or privilege changes.
 
 ## Read next

v3.0/packages/session/usage.md

@@ -52,4 +52,5 @@ Most apps should set `session.default` and call `session()` without args.
 
 - `has()` returns `false` for empty-like values (`0`, `false`, `''`, `null`).
 - Native adapter includes framework keys like `LAST_ACTIVITY` in `all()` output.
-- Database adapter requires working DB/model setup before use.
+- Session values are encrypted in storage, so inspect them through `session()->get()` or `session()->all()` when you need app-level values.
+- Database adapter works best after the database connection, model layer, and session table are ready.